Публічне 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
• Конструктор звітів — ті ж метрики та групування в інтерфейсі кабінету