Публичное HTTP API

Публичное HTTP API Adset.pro — программный доступ к данным и сущностям кабинета для внешних систем: BI и дашбордов, ETL-скриптов, автоматизации заведения кампаний, партнёрских сетей, офферов и потоков.

Базовый URL: https://adset.pro. Swagger UI: https://adset.pro/api/docs (OpenAPI 3.0; JSON-спецификация — https://adset.pro/api/docs/swagger.json).

Публичный API — это те же эндпойнты, которые использует веб-кабинет: отдельного слоя /api/public/* нет. Поля запросов и ответов совпадают с тем, что видит интерфейс, а видимость данных такая же, как в кабинете. В статьях раздела перечислены обязательные и ключевые поля; полные схемы — в Swagger.

Статьи раздела

Быстрый старт

1. В кабинете откройте Настройки пользователя → вкладка «Ключи MCP» (https://adset.pro/user-settings), нажмите «Создать API-ключ» и выберите тип Personal Access Token. Скопируйте токен сразу — он показывается только один раз.
2. Передавайте токен в каждом запросе заголовком Authorization: Bearer pat_….
3. Проверьте доступ справочным запросом:

curl 'https://adset.pro/api/stats/meta/metrics' \
  -H 'Authorization: Bearer pat_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX'

4. Списки сущностей пагинируются на сервере: GET /api/campaigns?page=1&pageSize=100.
5. Для создания и правки добавьте ключу write-скоупы — по умолчанию у нового PAT только чтение.

Получение токена

Personal Access Token (PAT)

Основной способ для скриптов и серверных интеграций. Префикс токена — pat_, длина около 64 символов.

Ключ создаётся в UI (см. «Быстрый старт») или запросом из кабинета — для него нужен JWT браузерной сессии, а не другой PAT:

POST /api/mcp/keys
Authorization: Bearer <JWT сессии кабинета>
Content-Type: application/json

{
  "type": "pat",
  "name": "BI ETL job",
  "scopes": ["api:stats", "api:stats:meta", "api:campaigns"],
  "expiresInDays": 365
}

В ответе один раз вернётся поле token — сохраните его.

Управление ключами (из кабинета; пользователь видит только свои ключи):

Все эти действия доступны и в UI на вкладке «Ключи MCP».

pat_ принимается только на путях /api/*. На /mcp он отклоняется — там нужен ключ типа MCP (mcp_) или OAuth-токен, см. MCP-сервис Adset.

OAuth 2.0 (для приложений)

OAuth-токены (oat_…, Authorization Code + PKCE) также принимаются на /api/* с теми же скоупами. Этот сценарий нужен в первую очередь для подключения MCP-клиентов (ChatGPT, Claude и совместимых) и описан в статье MCP-сервис Adset. Discovery-документ: GET /.well-known/oauth-authorization-server. Для скриптов и серверных интеграций используйте PAT.

Скоупы

Скоуп — разрешение самого токена вызывать группу эндпойнтов. Эффективный доступ = скоупы токена ∩ права роли владельца токена.

• Новый PAT без явного списка scopes получает все read-скоупы. Write-скоупы включаются при создании ключа или позже — через UI либо PATCH /api/mcp/keys/{keyId}/scopes.
• Ранее выданные ключи не получают новые скоупы автоматически: добавьте их тем же способом.
• Ни один скоуп не даёт права на удаление — удалять сущности через API нельзя.

Права роли владельца

Токен действует от имени пользователя, который его создал, и наследует его роль и видимость данных:

У всех ролей есть права на чтение и создание/правку кампаний, офферов и потоков, на создание CPA-сетей и на чтение доменов, CPA-шаблонов и статистики. Исключение одно: BUYER не может править CPA-сети — PATCH /api/cpa/{id} вернёт 403. Чужая сущность для токена не существует: ответ 404, а не 403.

Общие соглашения

Формат запросов и ответов

• JSON, UTF-8, Content-Type: application/json. Даты — ISO 8601 в UTC. Идентификаторы {id} — 24-символьный hex ObjectId.
• Одиночный объект: { "data": { … }, "traceId": "…" }.
• Список: { "data": [ … ], "meta": { "page", "pageSize", "total", "sort", "filters" }, "links": { "self", "next"?, "prev"? }, "traceId": "…" }.
• Создание — 201 Created с заголовком Location: /<ресурс>/{id}; правка — 200 OK с полным объектом.
• Каждый ответ содержит traceId и заголовок X-Trace-Id — указывайте его при обращении в поддержку.

Параметры списков (GET …)

Единый контракт для всех списков сущностей. Допустимые поля фильтров и сортировки у каждой сущности свои — они перечислены в статье группы.

curl -G 'https://adset.pro/api/offers' \
  -H 'Authorization: Bearer pat_…' \
  --data-urlencode 'page=1' \
  --data-urlencode 'pageSize=100' \
  --data-urlencode 'sort=updated:desc' \
  --data-urlencode 'filter[isActive]=true' \
  --data-urlencode 'filter[country][in]=DE,AT'

meta.total — общее число записей; на последней странице в links нет next. Если нужен полный справочник, запрашивайте его страницами или передавайте pageSize до 1000.

Ошибки

Тело ошибки единое: { "error": { "code": "…", "message": "…", "details": [ … ] }, "traceId": "…" } (details — список нарушений по полям, присутствует не всегда).

На /mcp ошибки авторизации отдаются в формате OAuth ({ "error": "invalid_token", … }); на /api/* формат всегда такой, как в таблице.

Лимиты и ограничения

Рекомендации: кэшируйте справочники (/api/stats/meta/*, CPA-шаблоны), запрашивайте только нужные поля (select), при 429 повторяйте запрос с экспоненциальной задержкой.

Что не входит в публичный API

Удаление сущностей, копирование (/copy, /clone), массовые операции (/reassign-owner, /replace-domain), серверные таблицы (/table), /free-list, список доменов кампании, мастер регистрации и покупка доменов, операции с Cloudflare, создание и правка CPA-шаблонов и доменов. У этих эндпойнтов нет скоупа, они не публикуются в /api/docs, их контракт не гарантируется и может измениться без предупреждения. Не используйте их из интеграций — доступ к ним по PAT/OAuth будет закрыт.

Полезные ссылки

• Swagger UI: https://adset.pro/api/docs
• MCP-сервис Adset — доступ LLM-клиентов к данным по Model Context Protocol и OAuth 2.0
• Конструктор отчётов — те же метрики и группировки в интерфейсе кабинета