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

Начиная

Adligator API — это REST, полный 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"
}