Skip to content

Developer API ​

REST API Adexium для внешних интеграторов: кампании, креативы (assets), баланс, справочники таргетинга и аналитика кампаний.

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

Аутентификация ​

К каждому запросу добавляйте API-ключ:

http
Authorization: Bearer <api_key>

Ключ создаётся в кабинете: Аккаунт → API keys. Доступ к API включает ваш менеджер. Ключ показывается только один раз, и у каждого ключа есть скоупы — campaigns:read, campaigns:write, account:read; запрос вне них получит 403. Подробнее: API-ключи.

Интерактивная документация ​

Полное описание endpoints, схем запросов/ответов и «Try it out»:

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

OpenAPI JSON (для генераторов кода и MCP tools):

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

Типичный сценарий ​

  1. Загрузить креатив — POST /api/v1/assets/from-url или POST /api/v1/assets → в ответе path
  2. Создать кампанию — POST /api/v1/campaigns/{channel} с creatives[].creative = этот path
  3. Список и изменения — GET /api/v1/campaigns, GET/PATCH /api/v1/campaigns/{id}
  4. Статистика — GET /api/v1/campaigns/stats/{id}?startDate=...&endDate=...&splitBy=country

Каналы для create: tma, ime_messenger, web_pops, web_inpage, web_push, bot.

Эндпоинты ​

Метод и путьСкоупЧто делает
GET /api/v1/account/balanceaccount:readБаланс аккаунта
GET /api/v1/dictionaries/{type}campaigns:readЗначения для таргетинга; type — countries, languages или platforms
POST /api/v1/assets/from-urlcampaigns:writeЗагрузить изображение креатива по URL → path
POST /api/v1/assetscampaigns:writeЗагрузить файл изображения креатива (multipart) → path
GET /api/v1/campaignscampaigns:readСписок ваших кампаний
POST /api/v1/campaigns/{channel}campaigns:writeСоздать кампанию с 1–7 креативами
GET /api/v1/campaigns/{id}campaigns:readПолучить кампанию
PATCH /api/v1/campaigns/{id}campaigns:writeИзменить кампанию
POST /api/v1/campaigns/{id}/startcampaigns:writeЗапустить кампанию
POST /api/v1/campaigns/{id}/pausecampaigns:writeПоставить кампанию на паузу
DELETE /api/v1/campaigns/{id}/creatives/{creativeId}campaigns:writeУдалить креатив (последний удалить нельзя)
GET /api/v1/campaigns/{id}/sourcescampaigns:readБлок- / вайт-лист источников кампании
POST /api/v1/campaigns/{id}/sourcescampaigns:writeДобавить источники в список; switchMode: true переключает непустой список между блоком и вайт-листом
DELETE /api/v1/campaigns/{id}/sources/{sourceId}campaigns:writeУдалить одну строку списка; пустой список означает все источники
GET /api/v1/campaigns/stats/{id}campaigns:readАналитика кампании

Списки источников есть у всех каналов, кроме bot. Коды источников берите из статистики с splitBy=source.

Параметры статистики ​

ПараметрОбязателенЗначения
startDate, endDateдаYYYY-MM-DD
splitByдаcountry, region, language, premium, date, hour, source, placement, tonConnected, vpn, deviceType, ispNetwork, platform, browser, campaign, creative
campaignIds[]нетНесколько ваших кампаний в одном отчёте

Минимальные ставки ​

API принимает те же минимальные ставки по каналам, что и кабинет, — см. Форматы, цены и минимальные ставки. Меньшая price отклоняется с ошибкой валидации.

Ошибки ​

Ошибки валидации возвращают 400:

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

Нарушение бизнес-правила возвращает стабильный код ошибки и, где полезно, подробности:

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

Ошибки авторизации (401, 400 Unable to authorize, 403 при нехватке скоупа) описаны на странице API-ключи.

Интеграция через MCP ​

AI-агенты (Cursor, Claude Desktop и др.) можно подключить к Adexium через Model Context Protocol (MCP). MCP-сервер — тонкая обёртка над HTTP: агент вызывает tools, сервер ходит в https://api.adexium.io/api/v1/... с Authorization: Bearer <api_key>.

mermaid
flowchart LR
    Agent[AI Agent] --> MCP[MCP Server]
    MCP -->|Bearer api_key| API["api.adexium.io /api/v1"]

Рекомендуемые tools ​

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}

Схемы tools можно сгенерировать из OpenAPI spec или описать вручную.

Создание кампании с картинкой ​

  1. upload_asset_from_url или upload_asset_file → получить path
  2. create_campaign с creatives[].creative = path (не передавайте большой base64 через chat)
  3. list_campaigns / get_campaign — когда нужен id для PATCH или stats

Пример конфигурации Cursor ​

В MCP settings (mcp.json или 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"
      }
    }
  }
}

Укажите путь к вашему MCP-серверу (реализация не входит в этот репозиторий).

Безопасность и лимиты ​

  • API-ключ только в env / secrets MCP-сервера — не в промптах, git и клиентском коде.
  • /api/v1 ограничен ~2 запросами в секунду на IP. Обрабатывайте HTTP 429 (backoff/retry) в MCP-сервере.