Skip to content

Developer API ​

The Adexium Developer API is a REST API for external integrators: campaigns, creative assets, account balance, targeting dictionaries, and campaign analytics.

Base URL: https://api.adexium.io

Authentication ​

Every request must include your API key:

http
Authorization: Bearer <api_key>

Create the key in your cabinet: Account → API keys. API access is turned on by your account manager. The key is shown only once, and each key carries scopes — campaigns:read, campaigns:write, account:read; a call outside them answers 403. Details: API keys.

Interactive documentation ​

Full endpoint reference, request/response schemas, and “Try it out”:

https://api.adexium.io/developer/api/doc

OpenAPI JSON (for code generators and MCP tools):

https://api.adexium.io/api/doc.json

Typical workflow ​

  1. Upload a creative — POST /api/v1/assets/from-url or POST /api/v1/assets → receive path
  2. Create a campaign — POST /api/v1/campaigns/{channel} with creatives[].creative set to that path
  3. List or update — GET /api/v1/campaigns, GET/PATCH /api/v1/campaigns/{id}
  4. Stats — GET /api/v1/campaigns/stats/{id}?startDate=...&endDate=...&splitBy=country

Channels for create: tma, ime_messenger, web_pops, web_inpage, web_push, bot.

Endpoints ​

Method and pathScopeWhat it does
GET /api/v1/account/balanceaccount:readAccount balance
GET /api/v1/dictionaries/{type}campaigns:readTargeting values; type is countries, languages or platforms
POST /api/v1/assets/from-urlcampaigns:writeUpload a creative image from a URL → path
POST /api/v1/assetscampaigns:writeUpload a creative image file (multipart) → path
GET /api/v1/campaignscampaigns:readList your campaigns
POST /api/v1/campaigns/{channel}campaigns:writeCreate a campaign with 1–7 creatives
GET /api/v1/campaigns/{id}campaigns:readRead one campaign
PATCH /api/v1/campaigns/{id}campaigns:writeUpdate a campaign
POST /api/v1/campaigns/{id}/startcampaigns:writeStart the campaign
POST /api/v1/campaigns/{id}/pausecampaigns:writePause the campaign
DELETE /api/v1/campaigns/{id}/creatives/{creativeId}campaigns:writeRemove a creative (the last one cannot be removed)
GET /api/v1/campaigns/{id}/sourcescampaigns:readThe campaign's source block/allow list
POST /api/v1/campaigns/{id}/sourcescampaigns:writeAdd sources to the list; send switchMode: true to switch a non-empty list between block and allow
DELETE /api/v1/campaigns/{id}/sources/{sourceId}campaigns:writeRemove one row from the list; an empty list means all sources
GET /api/v1/campaigns/stats/{id}campaigns:readCampaign analytics

Source lists exist on every channel except bot. Take source codes from the stats endpoint with splitBy=source.

Stats parameters ​

ParameterRequiredValues
startDate, endDateyesYYYY-MM-DD
splitByyescountry, region, language, premium, date, hour, source, placement, tonConnected, vpn, deviceType, ispNetwork, platform, browser, campaign, creative
campaignIds[]noSeveral of your campaigns in one report

Minimum bids ​

The API accepts the same minimum bid per channel as the dashboard — see Formats, pricing and minimum bids. A lower price is rejected with a validation error.

Errors ​

Validation errors answer 400:

json
{
  "code": 400,
  "message": "Validation failed",
  "errors": [
    { "field": "creatives", "message": "This collection should contain 1 element or more." }
  ]
}

A broken business rule answers with a stable error code and, where useful, details:

json
{
  "error": "exception.campaign.source_unknown",
  "message": "exception.campaign.source_unknown",
  "context": { "sources": ["ZZZZZZ"] }
}

Authorization errors (401, 400 Unable to authorize, 403 for a missing scope) are described on the API keys page.

MCP integration ​

You can connect AI agents (Cursor, Claude Desktop, etc.) to Adexium via Model Context Protocol (MCP). An MCP server is a thin HTTP wrapper: the agent calls tools, your server calls https://api.adexium.io/api/v1/... with Authorization: Bearer <api_key>.

mermaid
flowchart LR
    Agent[AI Agent] --> MCP[MCP Server]
    MCP -->|Bearer api_key| API["api.adexium.io /api/v1"]
ToolHTTP
get_balanceGET /api/v1/account/balance
list_campaignsGET /api/v1/campaigns
get_campaign / update_campaignGET / PATCH /api/v1/campaigns/{id}
create_campaignPOST /api/v1/campaigns/{channel}
upload_asset_from_urlPOST /api/v1/assets/from-url
upload_asset_filePOST /api/v1/assets (multipart)
get_campaign_statsGET /api/v1/campaigns/stats/{id}
list_dictionaryGET /api/v1/dictionaries/{type}

Use the OpenAPI spec to generate tool schemas or implement tools manually.

Creating a campaign with an image ​

  1. Call upload_asset_from_url or upload_asset_file → get path from the response
  2. Call create_campaign with creatives[].creative = path (do not pass large base64 through the chat context)
  3. Use list_campaigns or get_campaign when you need campaign id for updates or stats

Cursor configuration example ​

Add to MCP settings (mcp.json or Cursor Settings → MCP):

json
{
  "mcpServers": {
    "adexium": {
      "command": "node",
      "args": ["/path/to/your-adexium-mcp/dist/index.js"],
      "env": {
        "ADEXIUM_API_BASE": "https://api.adexium.io",
        "ADEXIUM_API_KEY": "your-api-key"
      }
    }
  }
}

Replace /path/to/your-adexium-mcp/... with your own MCP server implementation.

Security and limits ​

  • Store the API key only in MCP server env or secrets — never in prompts, git, or client-side code.
  • /api/v1 is rate-limited (~2 requests per second per IP). Implement backoff/retry on HTTP 429 in your MCP server.