{ "openapi": "3.0.0", "info": { "title": "Adexium Developer API", "description": "REST API for external integrators. Authenticate with `Authorization: Bearer `.\n\n**Channels** for `POST /api/v1/campaigns/{channel}`: `tma`, `ime_messenger`, `web_pops`, `web_inpage`, `web_push`, `bot`.\n\n**Creative assets:** upload via `POST /api/v1/assets/from-url` or `POST /api/v1/assets`, then pass returned `path` in `creatives[].creative` (or `icon`) when creating or updating a campaign.\n", "version": "1.0.0" }, "paths": { "/api/v1/campaigns/stats/{id}": { "get": { "tags": [ "Stats" ], "summary": "Get campaign analytics stats", "description": "Returns analytics rows for a campaign in the given date range, grouped by splitBy dimension.", "operationId": "get_developer_api_campaign_stats", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer", "minimum": 1, "pattern": "\\d+" } }, { "name": "startDate", "in": "query", "required": true, "schema": { "type": "string", "format": "date", "example": "2025-03-01" } }, { "name": "endDate", "in": "query", "required": true, "schema": { "type": "string", "format": "date", "example": "2025-03-31" } }, { "name": "splitBy", "in": "query", "required": true, "schema": { "type": "string", "enum": [ "country", "language", "premium", "date", "hour", "source", "tonConnected", "vpn", "deviceType", "ispNetwork", "platform", "browser", "campaign", "creative" ], "example": "country" } }, { "name": "campaignIds", "in": "query", "description": "Optional multi-campaign filter (must belong to the user).", "required": false, "style": "form", "explode": true, "schema": { "type": "array", "items": { "type": "integer" } } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/DeveloperApiCampaignStatsItem" } } } } }, "403": { "description": "Forbidden" }, "404": { "description": "Not found" } }, "security": [ { "ApiKeyBearer": [] } ] } }, "/api/v1/account/balance": { "get": { "tags": [ "Account" ], "summary": "Get account balance", "operationId": "get_developer_api_account_balance", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeveloperApiAccountBalance" } } } } }, "security": [ { "ApiKeyBearer": [] } ] } }, "/api/v1/assets/from-url": { "post": { "tags": [ "Assets" ], "summary": "Upload asset from URL", "description": "Downloads an HTTPS asset, stores it on CDN, and returns a path for use in campaign creatives.", "operationId": "post_developer_api_asset_from_url", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeveloperApiAssetFromUrlRequest" } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeveloperApiAssetResponse" } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeveloperApiValidationError" } } } }, "403": { "description": "Forbidden" } }, "security": [ { "ApiKeyBearer": [] } ] } }, "/api/v1/assets": { "post": { "tags": [ "Assets" ], "summary": "Upload asset file", "description": "Uploads a creative or icon file to CDN and returns a path for use in campaign creatives.", "operationId": "post_developer_api_asset_upload", "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "required": [ "file" ], "properties": { "file": { "type": "string", "format": "binary" }, "purpose": { "type": "string", "default": "creative", "enum": [ "creative", "icon" ] } }, "type": "object" } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeveloperApiAssetResponse" } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeveloperApiValidationError" } } } }, "403": { "description": "Forbidden" } }, "security": [ { "ApiKeyBearer": [] } ] } }, "/api/v1/campaigns": { "get": { "tags": [ "Campaigns" ], "summary": "List campaigns", "description": "Returns paginated campaigns owned by the authenticated user. Only Developer API channels are included.", "operationId": "get_developer_api_campaign_list", "parameters": [ { "name": "page", "in": "query", "schema": { "type": "integer", "default": 1, "minimum": 1 } }, { "name": "perPage", "in": "query", "schema": { "type": "integer", "default": 20, "maximum": 100, "minimum": 1 } }, { "name": "name", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "channel", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "tma", "ime_messenger", "web_pops", "web_inpage", "web_push", "bot" ] } }, { "name": "status", "in": "query", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeveloperApiCampaignListResponse" } } } }, "403": { "description": "Forbidden" } }, "security": [ { "ApiKeyBearer": [] } ] } }, "/api/v1/campaigns/{channel}": { "post": { "tags": [ "Campaigns" ], "summary": "Create campaign", "description": "Creates a campaign for the given channel. Request body shape is shared; channel-specific fields apply per channel type.", "operationId": "post_developer_api_campaign_create", "parameters": [ { "name": "channel", "in": "path", "description": "Campaign channel slug", "required": true, "schema": { "type": "string", "pattern": "tma|ime_messenger|web_pops|web_inpage|web_push|bot", "enum": [ "tma", "ime_messenger", "web_pops", "web_inpage", "web_push", "bot" ] } } ], "requestBody": { "description": "Campaign payload with creatives array (1\u20137 items). Use examples dropdown for TMA vs Bot.", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeveloperApiCampaignCreateRequest" }, "examples": { "tma": { "summary": "TMA", "value": { "name": "My TMA campaign", "clickUrl": "https://t.me/my_bot/app", "price": 1.5, "budgetLimit": 50, "limitImpressions": 10000, "limitImpressionsPeriodInDays": 1, "limitClicks": 500, "limitClicksPeriodInDays": 7, "endDate": "2026-12-31T23:59:59.000000Z", "isPremium": false, "countries": [ "US", "RU" ], "languages": [ "en", "ru" ], "platforms": [ "android", "ios" ], "creatives": [ { "title": "Summer promo", "description": "Short description shown in the ad", "buttonText": "Open", "creative": "creatives/images/abc123.webp", "isVideo": false, "weight": 1, "isActive": true } ] } }, "bot": { "summary": "Bot", "value": { "name": "Bot channel campaign", "clickUrl": "https://t.me/my_channel", "price": 2, "budgetLimit": 30, "limitClicksPerUser": 1, "languages": [ "en" ], "creatives": [ { "title": "Summer promo", "description": "Short description shown in the ad", "buttonText": "Open", "creative": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mP8z8BQDwAEhQGAhKmMIQAAAABJRU5ErkJggg==", "isVideo": false, "weight": 1, "isActive": true } ] } } } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeveloperApiCampaignResponse" } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeveloperApiValidationError" } } } }, "403": { "description": "Forbidden" } }, "security": [ { "ApiKeyBearer": [] } ] } }, "/api/v1/campaigns/{id}": { "get": { "tags": [ "Campaigns" ], "summary": "Get campaign by ID", "operationId": "get_developer_api_campaign_get", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer", "minimum": 1, "pattern": "\\d+" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeveloperApiCampaignResponse" } } } }, "403": { "description": "Forbidden" }, "404": { "description": "Not found" } }, "security": [ { "ApiKeyBearer": [] } ] }, "patch": { "tags": [ "Campaigns" ], "summary": "Update campaign (partial)", "operationId": "patch_developer_api_campaign_update", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer", "minimum": 1, "pattern": "\\d+" } } ], "requestBody": { "description": "Fields to update; omitted fields stay unchanged", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeveloperApiCampaignPatchRequest" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeveloperApiCampaignResponse" } } } } }, "security": [ { "ApiKeyBearer": [] } ] } }, "/api/v1/campaigns/{id}/creatives/{creativeId}": { "delete": { "tags": [ "Campaigns" ], "summary": "Remove creative from campaign", "operationId": "delete_developer_api_campaign_delete_creative", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer", "minimum": 1, "pattern": "\\d+" } }, { "name": "creativeId", "in": "path", "required": true, "schema": { "type": "integer", "minimum": 1, "pattern": "\\d+" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeveloperApiCampaignResponse" } } } }, "409": { "description": "Last creative", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeveloperApiValidationError" } } } } }, "security": [ { "ApiKeyBearer": [] } ] } }, "/api/v1/dictionaries/{type}": { "get": { "tags": [ "Dictionaries" ], "summary": "List dictionary entries", "operationId": "get_developer_api_dictionary", "parameters": [ { "name": "type", "in": "path", "required": true, "schema": { "type": "string", "pattern": "countries|languages|platforms", "enum": [ "countries", "languages", "platforms" ] } } ], "responses": { "200": { "description": "List of code/name objects", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeveloperApiDictionaryList" } } } } }, "security": [ { "ApiKeyBearer": [] } ] } } }, "components": { "schemas": { "DeveloperApiCampaignStatsItem": { "properties": { "id": { "type": "string", "example": "US" }, "value": { "type": "string", "example": "US" }, "clicks": { "type": "integer", "example": 1200 }, "spend": { "type": "number", "format": "float", "example": 45.5 }, "impressions": { "type": "integer", "example": 50000 }, "conversionLevel1": { "type": "integer", "example": 10 }, "conversionLevel2": { "type": "integer", "example": 5 }, "conversionLevel3": { "type": "integer", "example": 2 }, "cvr": { "type": "number", "format": "float", "example": 0.02 }, "ctr": { "type": "number", "format": "float", "example": 0.024 }, "cpc": { "type": "number", "format": "float", "example": 0.038 }, "cpm": { "type": "number", "format": "float", "example": 0.91 }, "cpa": { "type": "number", "format": "float", "example": 4.55 }, "campaignId": { "type": "integer", "nullable": true }, "campaignName": { "type": "string", "nullable": true } }, "type": "object", "example": { "id": "US", "value": "US", "clicks": 1200, "spend": 45.5, "impressions": 50000, "conversionLevel1": 10, "conversionLevel2": 5, "conversionLevel3": 2, "cvr": 0.02, "ctr": 0.024, "cpc": 0.038, "cpm": 0.91, "cpa": 4.55 } }, "DeveloperApiCampaignResponse": { "properties": { "id": { "type": "integer", "example": 12345 }, "channel": { "type": "string", "example": "tma" }, "name": { "type": "string" }, "clickUrl": { "type": "string" }, "price": { "type": "number", "format": "float" }, "budgetLimit": { "type": "number", "format": "float" }, "limitImpressions": { "type": "integer" }, "limitImpressionsPeriodInDays": { "type": "integer" }, "limitClicks": { "type": "integer" }, "limitClicksPeriodInDays": { "type": "integer" }, "endDate": { "description": "Unix timestamp in milliseconds", "type": "integer", "nullable": true }, "isPremium": { "type": "boolean", "nullable": true }, "mainstreamOnly": { "type": "integer", "nullable": true }, "limitClicksPerUser": { "type": "integer", "nullable": true }, "countries": { "type": "array", "items": { "type": "string" }, "nullable": true }, "languages": { "type": "array", "items": { "type": "string" }, "nullable": true }, "platforms": { "type": "array", "items": { "type": "string" }, "nullable": true }, "creatives": { "type": "array", "items": { "properties": { "id": { "type": "integer" }, "title": { "type": "string" }, "description": { "type": "string" }, "buttonText": { "type": "string" }, "creativeUrl": { "type": "string", "nullable": true }, "iconUrl": { "type": "string", "nullable": true }, "isVideo": { "type": "boolean" }, "weight": { "type": "integer" }, "isActive": { "type": "boolean" } } } } }, "type": "object", "example": { "id": 12345, "channel": "tma", "name": "My TMA campaign", "clickUrl": "https://t.me/my_bot/app", "price": 1.5, "budgetLimit": 50, "limitImpressions": 10000, "limitImpressionsPeriodInDays": 1, "limitClicks": 500, "limitClicksPeriodInDays": 7, "endDate": 1767225599000, "isPremium": false, "countries": [ "RU", "US" ], "languages": [ "en", "ru" ], "platforms": [ "android", "ios" ], "creatives": [ { "id": 9001, "title": "Summer promo", "description": "Short description shown in the ad", "buttonText": "Open", "creativeUrl": "https://cdn.example.com/creatives/9001.webp", "iconUrl": null, "isVideo": false, "weight": 1, "isActive": true } ] } }, "DeveloperApiCampaignPatchRequest": { "properties": { "name": { "type": "string", "nullable": true }, "clickUrl": { "type": "string", "format": "uri", "nullable": true }, "price": { "type": "number", "format": "float", "nullable": true }, "budgetLimit": { "type": "number", "format": "float", "nullable": true }, "creatives": { "type": "array", "items": { "$ref": "#/components/schemas/DeveloperApiCreativeItem" }, "nullable": true } }, "type": "object", "example": { "name": "My TMA campaign (renamed)", "price": 1.8, "budgetLimit": 75 } }, "DeveloperApiCampaignCreateRequest": { "required": [ "name", "clickUrl", "price", "creatives" ], "properties": { "name": { "type": "string", "example": "My TMA campaign" }, "clickUrl": { "type": "string", "format": "uri", "example": "https://t.me/my_bot/app" }, "price": { "type": "number", "format": "float", "example": 1.5 }, "budgetLimit": { "type": "number", "format": "float", "nullable": true }, "limitImpressions": { "type": "integer", "nullable": true }, "limitImpressionsPeriodInDays": { "type": "integer", "nullable": true }, "limitClicks": { "type": "integer", "nullable": true }, "limitClicksPeriodInDays": { "type": "integer", "nullable": true }, "limitClicksPerUser": { "description": "Bot channel", "type": "integer", "nullable": true }, "endDate": { "type": "string", "format": "date-time", "nullable": true }, "isPremium": { "description": "TMA / IME", "type": "boolean" }, "mainstreamOnly": { "description": "Pop / Inpage / Web push: -1, 0, or 1", "type": "integer" }, "countries": { "type": "array", "items": { "type": "string" }, "example": [ "US", "RU" ] }, "languages": { "type": "array", "items": { "type": "string" }, "example": [ "en", "ru" ] }, "platforms": { "type": "array", "items": { "type": "string" }, "example": [ "android", "ios" ] }, "creatives": { "type": "array", "items": { "$ref": "#/components/schemas/DeveloperApiCreativeItem" } } }, "type": "object", "example": { "name": "My TMA campaign", "clickUrl": "https://t.me/my_bot/app", "price": 1.5, "budgetLimit": 50, "limitImpressions": 10000, "limitImpressionsPeriodInDays": 1, "limitClicks": 500, "limitClicksPeriodInDays": 7, "endDate": "2026-12-31T23:59:59.000000Z", "isPremium": false, "countries": [ "US", "RU" ], "languages": [ "en", "ru" ], "platforms": [ "android", "ios" ], "creatives": [ { "title": "Summer promo", "description": "Short description shown in the ad", "buttonText": "Open", "creative": "creatives/images/abc123.webp", "isVideo": false, "weight": 1, "isActive": true } ] } }, "DeveloperApiValidationError": { "properties": { "code": { "type": "integer", "example": 400 }, "message": { "type": "string" }, "errors": { "type": "array", "items": { "properties": { "field": { "type": "string" }, "message": { "type": "string" } } } } }, "type": "object", "example": { "code": 400, "message": "Validation failed", "errors": [ { "field": "creatives", "message": "This collection should contain 1 element or more." } ] } }, "DeveloperApiDictionaryList": { "type": "array", "items": { "properties": { "code": { "type": "string", "example": "US" }, "name": { "type": "string", "example": "United States" } }, "type": "object" }, "example": [ { "code": "RU", "name": "Russia" }, { "code": "US", "name": "United States" } ] }, "DeveloperApiAccountBalance": { "properties": { "balance": { "type": "number", "format": "float", "example": 1250.75 }, "currency": { "type": "string", "example": "USD" } }, "type": "object", "example": { "balance": 1250.75, "currency": "USD" } }, "DeveloperApiCreativeItem": { "required": [ "title", "description", "buttonText", "creative" ], "properties": { "id": { "type": "integer", "nullable": true }, "title": { "type": "string" }, "description": { "type": "string" }, "buttonText": { "type": "string" }, "creative": { "description": "Base64 data URI, or CDN path/URL returned by POST /api/v1/assets", "type": "string" }, "icon": { "description": "Base64 data URI, or CDN path/URL returned by POST /api/v1/assets (purpose=icon)", "type": "string", "nullable": true }, "isVideo": { "type": "boolean" }, "weight": { "type": "integer" }, "isActive": { "type": "boolean" } }, "type": "object", "example": { "title": "Summer promo", "description": "Short description shown in the ad", "buttonText": "Open", "creative": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mP8z8BQDwAEhQGAhKmMIQAAAABJRU5ErkJggg==", "isVideo": false, "weight": 1, "isActive": true } }, "DeveloperApiCampaignListResponse": { "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/DeveloperApiCampaignListItem" } }, "page": { "type": "integer", "minimum": 1 }, "perPage": { "type": "integer", "maximum": 100, "minimum": 1 }, "total": { "type": "integer", "minimum": 0 } }, "type": "object" }, "DeveloperApiCampaignListItem": { "properties": { "id": { "type": "integer", "minimum": 1 }, "channel": { "type": "string", "enum": [ "tma", "ime_messenger", "web_pops", "web_inpage", "web_push", "bot" ] }, "name": { "type": "string" }, "status": { "type": "string" }, "paymentModel": { "type": "string", "enum": [ "CPM", "CPC" ] }, "price": { "type": "number", "format": "float" }, "clickUrl": { "type": "string" }, "createdAt": { "description": "Unix timestamp in milliseconds", "type": "integer" } }, "type": "object" }, "DeveloperApiAssetResponse": { "properties": { "path": { "type": "string", "example": "creatives/images/abc123.webp" }, "url": { "type": "string", "example": "https://images.adexium.online/creatives/images/abc123.webp" } }, "type": "object" }, "DeveloperApiAssetFromUrlRequest": { "required": [ "url" ], "properties": { "url": { "type": "string", "format": "uri", "example": "https://example.com/banner.png" }, "purpose": { "type": "string", "default": "creative", "enum": [ "creative", "icon" ] } }, "type": "object" }, "CampaignPrivateAPIStatsRequest": { "properties": { "startDate": { "type": "string", "format": "date-time" }, "endDate": { "type": "string", "format": "date-time" }, "splitBy": { "type": "string" } }, "type": "object" } }, "securitySchemes": { "ApiKeyBearer": { "type": "http", "description": "User API key (Authorization Bearer)", "scheme": "bearer" } } }, "tags": [ { "name": "Account", "description": "Account balance" }, { "name": "Assets", "description": "Upload creative/icon files to CDN before attaching them to campaigns" }, { "name": "Dictionaries", "description": "Reference data for campaign targeting (country, language, platform codes)" }, { "name": "Campaigns", "description": "Create, read, update campaigns and manage creatives" }, { "name": "Stats", "description": "Campaign analytics by dimension (country, source, date, etc.)" } ] }