Adligator API Документація

Початок роботи

Adligator API є RESTful HTTP API. Усі кінцеві точки обслуговуються через HTTPS від базового URL нижче та повертають JSON (за винятком кінцевої точки завантаження, яка відповідає перенаправленням).

https://api.adligator.com/api/v1

1. Для доступу до API потрібен активний План Team.
2. Створіть свій ключ API у Портал розробника. Ключ показується лише один раз — зберігайте його надійно.
3. Передайте ключ у заголовку X-API-Key з кожним запитом.

API зараз знаходиться в бета-версії та є безкоштовним. Обмеження та ціни можуть змінитися після закінчення бета-версії.

Хочете спробувати без плану Team? Використовуйте Ключ для пісочниці API нижче.

Ключ для пісочниці API

Використовуйте відкритий ключ пісочниці, щоб дослідити API без плану Team і власних облікових даних. Він шукає по реальній бібліотеці креативів, обмеженій ключовим словом "headway" та рекламою, вперше поміченою 1 січня 2026 року, — усі фільтри, ендпоінт деталей і завантаження медіа працюють так само, як у продакшені.

Ключ для пісочниці:

adl_sandbox000000000000000000000000000000001

Як поводиться

• План Team не потрібен.
• Єдине дозволене ключове слово — headway, що передається в параметрі body. Воно підставляється автоматично, якщо не вказане; будь-яке інше ключове слово повертає порожні результати.
• Результати обмежені рекламою, вперше поміченою між 2026-01-01 та 2026-01-02. Діапазони дат поза цим вікном повертають порожні результати.
• Усі інші фільтри, пагінація, сортування, деталі реклами та завантаження медіа працюють зі справжніми даними.
• Діють ті самі ліміти запитів, що й для продакшн-ключів.
• Ключ пісочниці працює лише з REST API; для MCP-сервера потрібен продакшн-ключ.
• Пошук сторінок Facebook (GET /fb-pages) для ключа пісочниці завжди повертає порожній список.

Приклад запиту

curl "https://api.adligator.com/api/v1/ads?body=headway&limit=5" \
  -H "X-API-Key: adl_sandbox000000000000000000000000000000001"

Щоб викликати кінцеву точку деталей або завантаження, замініть шлях на ідентифікатор реклами з відповіді пошуку.

Автентифікація

Автентифікуйте кожен запит за допомогою заголовка X-API-Key. Ключі виглядають як adl_, за якими слідують 40 символів.

curl "https://api.adligator.com/api/v1/ads?limit=5" \
  -H "X-API-Key: adl_your_api_key_here"

Запити без дійсного ключа відхиляються:

• 401 Unauthorized — відсутній заголовок або ключ невідомий.
• 403 Forbidden — ключ дезактивовано або ваш план не включає доступ до API.

Ліміти запитів

Обмеження застосовуються для кожного ключа API і кінцевої точки. Щоденні лічильники скидаються опівночі UTC.

Кожна відповідь містить заголовки обмеження швидкості:

X-RateLimit-Limit-Second: 2
X-RateLimit-Limit-Day: 1000
X-RateLimit-Remaining-Day: 987

Коли обмеження перевищено, API відповідає 429 Too Many Requests і заголовком Retry-After (через секунди). Відхилені запити не враховуються у вашій щоденній квоті.

GET Пошук реклами

GET /api/v1/ads

Виконує пошук у бібліотеці креативів. Повертає розбитий на сторінки список із мінімальною інформацією про рекламу; використовуйте кінцеву точку деталей для медіадескрипторів, а кінцеву точку завантаження — для оригінальних файлів. Усі параметри запиту необов’язкові. Параметри списку приймають значення, розділені комами.

Параметри запиту

Приклад запиту

curl "https://api.adligator.com/api/v1/ads?countries=US,DE&isActive=true&title=fitness&limit=2" \
  -H "X-API-Key: adl_your_api_key_here"

Приклад відповіді

{
  "data": [
    {
      "id": "9a1f4c9e-2b7d-4f1a-8c3e-5d6b7a8c9d0e",
      "isActive": true,
      "displayFormat": 1,
      "publishedOnPlatforms": ["FB", "INST"],
      "countries": ["US", "DE"],
      "countriesAmount": 2,
      "textLanguages": ["en"],
      "startDate": "2026-05-14T00:00:00.000Z",
      "endDate": null,
      "lastSeenAt": "2026-07-03T09:12:44.000Z",
      "activeDaysCount": 50,
      "copiesCount": 12,
      "title": "Get fit in 30 days",
      "linkUrl": "https://example.com/offer",
      "buttonType": "LEARN_MORE",
      "isAAAEligible": true,
      "fbPage": {
        "fbOriginalPageId": "104201234567890",
        "pageName": "Fit Life",
        "pageLikesCount": 53210,
        "profileUri": "https://facebook.com/fitlife"
      }
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 2,
    "totalPages": 187
  }
}

GET Пошук сторінок Facebook

GET /api/v1/fb-pages

Шукає сторінки Facebook (рекламодавців) за назвою. Використовуйте, щоб перетворити назву бренду, застосунку чи продукту на fbOriginalPageId перед фільтрацією реклами за цим рекламодавцем. Повертає найкращі збіги з назвою сторінки, кількістю вподобань, посиланням на профіль і зображенням.

Параметри запиту

Приклад запиту

curl "https://api.adligator.com/api/v1/fb-pages?query=Duolingo&limit=5" \
  -H "X-API-Key: adl_your_api_key_here"

Приклад відповіді

{
  "data": [
    {
      "fbOriginalPageId": "104201234567890",
      "pageName": "Duolingo",
      "pageLikesCount": 12500000,
      "profileUri": "https://facebook.com/duolingo",
      "profilePictureUrl": "https://cdn2.adligator.com/pages/....jpg"
    }
  ],
  "totalCount": 12
}

Передайте отриманий fbOriginalPageId у GET /ads як fbOriginalPageId, щоб отримати рекламу цього рекламодавця.

GET Отримати деталі реклами

GET /api/v1/ads/:id

Повертає повну інформацію про одну рекламу, зокрема медіадескриптори з URL попереднього перегляду. Медіаоб’єкти містять mediaId, який потрібно передати кінцевій точці завантаження, щоб отримати файл із найвищою роздільною здатністю.

Параметри шляху

Приклад запиту

curl "https://api.adligator.com/api/v1/ads/9a1f4c9e-2b7d-4f1a-8c3e-5d6b7a8c9d0e" \
  -H "X-API-Key: adl_your_api_key_here"

Приклад відповіді

{
  "data": {
    "id": "9a1f4c9e-2b7d-4f1a-8c3e-5d6b7a8c9d0e",
    "isActive": true,
    "displayFormat": 1,
    "publishedOnPlatforms": ["FB", "INST"],
    "countries": ["US", "DE"],
    "title": "Get fit in 30 days",
    "linkUrl": "https://example.com/offer",
    "buttonType": "LEARN_MORE",
    "isAAAEligible": true,
    "adArchiveId": "1234567890123456",
    "categories": [0],
    "bodyHtml": "Join the challenge today...",
    "entityType": "REGULAR",
    "linkDescription": "30-day fitness challenge",
    "caption": "example.com",
    "images": [],
    "videos": [
      {
        "mediaId": "7c2e1f0a-9b8d-4e3c-a1b2-c3d4e5f60789",
        "videoUrl": "https://cdn2.adligator.com/videos/sd/....mp4",
        "previewImageUrl": "https://cdn2.adligator.com/previews/....jpg"
      }
    ],
    "cards": []
  }
}

Медіа-файли URL у цій відповіді мають якість попереднього перегляду (змінений розмір зображень / відео SD). Використовуйте кінцеву точку завантаження, щоб отримати вихідний файл.

GET Завантажити медіа

GET /api/v1/ads/:id/download?mediaId=:mediaId

Розпізнає файл із найвищою роздільною здатністю (оригінальне зображення чи відео HD) для медіа-елементу реклами та відповідає 302 Found і заголовком Location, що вказує на файл. Дотримуйтеся перенаправлення, щоб завантажити його.

Параметри

Приклад запиту

curl -L -o creative.mp4 \
  "https://api.adligator.com/api/v1/ads/9a1f4c9e-2b7d-4f1a-8c3e-5d6b7a8c9d0e/download?mediaId=7c2e1f0a-9b8d-4e3c-a1b2-c3d4e5f60789" \
  -H "X-API-Key: adl_your_api_key_here"

Приклад відповіді

HTTP/1.1 302 Found
Location: https://cdn2.adligator.com/videos/hd/....mp4

Помилки

Помилки використовують звичайні коди стану HTTP і узгоджений корпус JSON:

{
  "statusCode": 401,
  "message": "Invalid API key.",
  "error": "Unauthorized"
}