Documentação Adligator API

Começando

O Adligator API é um RESTful HTTP API. Todos os endpoints são atendidos por HTTPS a partir do URL base abaixo e retornam JSON (exceto o endpoint de download, que responde com um redirecionamento).

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

1. O acesso API requer um Plano Team ativo.
2. Crie sua chave API no Portal do desenvolvedor. A chave é mostrada apenas uma vez – guarde-a com segurança.
3. Passe a chave no cabeçalho X-API-Key com cada solicitação.

O API está atualmente em beta e gratuito. Os limites e preços podem mudar quando o beta terminar.

Quer experimentar sem um plano Team? Use o Chave da caixa de areia API abaixo.

Chave da caixa de areia API

Use a chave pública de sandbox para explorar a API sem um plano Team ou as suas próprias credenciais. Ela pesquisa a biblioteca real de anúncios, restrita à palavra-chave "headway" e a anúncios vistos pela primeira vez em 1 de janeiro de 2026 — todos os filtros, o endpoint de detalhes e os downloads de mídia comportam-se exatamente como em produção.

Chave da caixa de areia:

adl_sandbox000000000000000000000000000000001

Como se comporta

• Nenhum plano Team é necessário.
• A única palavra-chave permitida é headway, passada no parâmetro body. Ela é aplicada automaticamente quando omitida; qualquer outra palavra-chave devolve resultados vazios.
• Os resultados limitam-se a anúncios vistos pela primeira vez entre 2026-01-01 e 2026-01-02. Intervalos de datas fora desta janela devolvem resultados vazios.
• Todos os outros filtros, paginação, ordenação, detalhes de anúncios e downloads de mídia funcionam com dados reais.
• Aplicam-se os mesmos limites de pedidos que às chaves de produção.
• A chave de sandbox funciona apenas com a API REST; o servidor MCP requer uma chave de produção.
• A pesquisa de páginas do Facebook (GET /fb-pages) sempre retorna uma lista vazia com a chave de sandbox.

Solicitação de exemplo

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

Substitua o caminho por um ID de anúncio da resposta da pesquisa para detalhes da chamada ou download.

Autenticação

Autentique cada solicitação com o cabeçalho X-API-Key. As chaves se parecem com adl_ seguidas de 40 caracteres.

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

Solicitações sem uma chave válida são rejeitadas:

• 401 Unauthorized — o cabeçalho está faltando ou a chave é desconhecida.
• 403 Forbidden — a chave está desativada ou seu plano não inclui acesso API.

Limites de pedidos

Os limites são aplicados por chave API e por endpoint. Os contadores diários são redefinidos à meia-noite UTC.

Cada resposta inclui cabeçalhos de limite de taxa:

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

Quando um limite é excedido, o API responde com 429 Too Many Requests e um cabeçalho Retry-After (em segundos). As solicitações rejeitadas não contam para sua cota diária.

GET Anúncios de pesquisa

GET /api/v1/ads

Pesquisa a biblioteca de anúncios. Retorna uma lista paginada com informações mínimas do anúncio; use o endpoint de detalhes para descritores de mídia e o endpoint de download para arquivos originais. Todos os parâmetros de consulta são opcionais. Os parâmetros de lista aceitam valores separados por vírgula.

Parâmetros de consulta

Solicitação de exemplo

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"

Exemplo de resposta

{
  "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 Pesquisar páginas do Facebook

GET /api/v1/fb-pages

Procura páginas do Facebook (anunciantes) pelo nome. Use para resolver o nome de uma marca, aplicativo ou produto para um fbOriginalPageId antes de filtrar anúncios por esse anunciante. Retorna os melhores candidatos com nome da página, curtidas, link do perfil e imagem.

Parâmetros de consulta

Solicitação de exemplo

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

Resposta de exemplo

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

Passe um fbOriginalPageId retornado para GET /ads como fbOriginalPageId para obter os anúncios desse anunciante.

GET Obtenha detalhes do anúncio

GET /api/v1/ads/:id

Retorna informações completas para um único anúncio, incluindo descritores de mídia com visualização URLs. Os objetos de mídia expõem um mediaId que você passa para o endpoint de download para recuperar o arquivo de resolução mais alta.

Parâmetros de caminho

Solicitação de exemplo

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

Exemplo de resposta

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

A mídia URL nesta resposta tem qualidade de visualização (imagens redimensionadas/vídeo SD). Use o endpoint de download para obter o arquivo original.

GET Baixar mídia

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

Resolve o arquivo de resolução mais alta (imagem original ou vídeo HD) para um item de mídia de um anúncio e responde com 302 Found e um cabeçalho Location apontando para o arquivo. Siga o redirecionamento para baixá-lo.

Parâmetros

Solicitação de exemplo

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"

Exemplo de resposta

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

Erros

Os erros usam códigos de status HTTP convencionais e um corpo JSON consistente:

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