Adligator API Documentation

Getting started

The Adligator API is a RESTful HTTP API. All endpoints are served over HTTPS from the base URL below and return JSON (except the download endpoint, which responds with a redirect).

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

1. API access requires an active Team plan.
2. Create your API key in the Developer Portal. The key is shown only once — store it securely.
3. Pass the key in the X-API-Key header with every request.

The API is currently in beta and free of charge. Limits and pricing may change once the beta ends.

Authentication

Authenticate every request with the X-API-Key header. Keys look like adl_ followed by 40 characters.

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

Requests without a valid key are rejected:

• 401 Unauthorized — the header is missing or the key is unknown.
• 403 Forbidden — the key is deactivated or your plan does not include API access.

Rate limits

Limits are applied per API key and per endpoint. Daily counters reset at midnight UTC.

Every response includes rate limit headers:

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

When a limit is exceeded, the API responds with 429 Too Many Requests and a Retry-After header (in seconds). Rejected requests do not count towards your daily quota.

GET Search ads

GET /api/v1/ads

Searches the ads library. Returns a paginated list with minimal ad information; use the details endpoint for media descriptors and the download endpoint for original files. All query parameters are optional. List parameters accept comma-separated values.

Query parameters

Example request

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"

Example response

{
  "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 Get ad details

GET /api/v1/ads/:id

Returns full information for a single ad, including media descriptors with preview URLs. Media objects expose a mediaId that you pass to the download endpoint to retrieve the highest-resolution file.

Path parameters

Example request

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

Example response

{
  "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": []
  }
}

Media URLs in this response are preview quality (resized images / SD video). Use the download endpoint to get the original file.

GET Download media

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

Resolves the highest-resolution file (original image or HD video) for a media item of an ad and responds with 302 Found and a Location header pointing at the file. Follow the redirect to download it.

Parameters

Example request

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"

Example response

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

Errors

Errors use conventional HTTP status codes and a consistent JSON body:

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