Developer API
REST API Adexium для внешних интеграторов: кампании, креативы (assets), баланс, справочники таргетинга и аналитика кампаний.
Base URL: https://api.adexium.io
Аутентификация
К каждому запросу добавляйте API-ключ:
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
Типичный сценарий
- Загрузить креатив —
POST /api/v1/assets/from-urlилиPOST /api/v1/assets→ в ответеpath - Создать кампанию —
POST /api/v1/campaigns/{channel}сcreatives[].creative= этотpath - Список и изменения —
GET /api/v1/campaigns,GET/PATCH /api/v1/campaigns/{id} - Статистика —
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/balance | account:read | Баланс аккаунта |
GET /api/v1/dictionaries/{type} | campaigns:read | Значения для таргетинга; type — countries, languages или platforms |
POST /api/v1/assets/from-url | campaigns:write | Загрузить изображение креатива по URL → path |
POST /api/v1/assets | campaigns:write | Загрузить файл изображения креатива (multipart) → path |
GET /api/v1/campaigns | campaigns: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}/start | campaigns:write | Запустить кампанию |
POST /api/v1/campaigns/{id}/pause | campaigns:write | Поставить кампанию на паузу |
DELETE /api/v1/campaigns/{id}/creatives/{creativeId} | campaigns:write | Удалить креатив (последний удалить нельзя) |
GET /api/v1/campaigns/{id}/sources | campaigns:read | Блок- / вайт-лист источников кампании |
POST /api/v1/campaigns/{id}/sources | campaigns: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:
{
"code": 400,
"message": "Validation failed",
"errors": [
{ "field": "creatives", "message": "This collection should contain 1 element or more." }
]
}Нарушение бизнес-правила возвращает стабильный код ошибки и, где полезно, подробности:
{
"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>.
flowchart LR
Agent[AI Agent] --> MCP[MCP Server]
MCP -->|Bearer api_key| API["api.adexium.io /api/v1"]Рекомендуемые tools
| Tool | HTTP |
|---|---|
get_balance | GET /api/v1/account/balance |
list_campaigns | GET /api/v1/campaigns |
get_campaign / update_campaign | GET / PATCH /api/v1/campaigns/{id} |
create_campaign | POST /api/v1/campaigns/{channel} |
upload_asset_from_url | POST /api/v1/assets/from-url |
upload_asset_file | POST /api/v1/assets (multipart) |
get_campaign_stats | GET /api/v1/campaigns/stats/{id} |
list_dictionary | GET /api/v1/dictionaries/{type} |
Схемы tools можно сгенерировать из OpenAPI spec или описать вручную.
Создание кампании с картинкой
upload_asset_from_urlилиupload_asset_file→ получитьpathcreate_campaignсcreatives[].creative=path(не передавайте большой base64 через chat)list_campaigns/get_campaign— когда нуженidдля PATCH или stats
Пример конфигурации Cursor
В MCP settings (mcp.json или Cursor Settings → MCP):
{
"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-сервере.