Adligator API Dokumentation

Erste Schritte

Der Adligator API ist ein RESTful HTTP API. Alle Endpunkte werden über HTTPS von der Basis URL unten bedient und geben JSON zurück (mit Ausnahme des Download-Endpunkts, der mit einer Umleitung antwortet).

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

1. Für den API-Zugriff ist ein aktiver Team-Plan erforderlich.
2. Erstellen Sie Ihren API-Schlüssel im Entwicklerportal. Der Schlüssel wird nur einmal angezeigt – bewahren Sie ihn sicher auf.
3. Übergeben Sie den Schlüssel bei jeder Anfrage im X-API-Key-Header.

Der API ist derzeit in der Beta-Phase und kostenlos. Limits und Preise können sich ändern, sobald die Beta endet.

Möchten Sie es ohne Team-Plan versuchen? Verwenden Sie unten den Sandbox API-Schlüssel.

Sandbox API-Schlüssel

Verwenden Sie den öffentlichen Sandbox-Schlüssel, um die API ohne Team-Plan oder eigene Anmeldedaten zu erkunden. Er durchsucht die echte Anzeigenbibliothek, beschränkt auf das Keyword "headway" und Anzeigen, die erstmals am 1. Januar 2026 gesehen wurden — alle Filter, der Detail-Endpunkt und Medien-Downloads verhalten sich genau wie in der Produktion.

Sandbox-Schlüssel:

adl_sandbox000000000000000000000000000000001

Wie es sich verhält

• Kein Team-Plan erforderlich.
• Das einzige erlaubte Keyword ist headway, übergeben im Parameter body. Es wird automatisch angewendet, wenn es fehlt; jedes andere Keyword liefert leere Ergebnisse.
• Die Ergebnisse sind auf Anzeigen beschränkt, die erstmals zwischen 2026-01-01 und 2026-01-02 gesehen wurden. Datumsbereiche außerhalb dieses Fensters liefern leere Ergebnisse.
• Alle anderen Filter, Paginierung, Sortierung, Anzeigendetails und Medien-Downloads arbeiten mit echten Daten.
• Es gelten dieselben Ratenlimits wie für Produktionsschlüssel.
• Der Sandbox-Schlüssel funktioniert nur mit der REST-API; der MCP-Server erfordert einen Produktionsschlüssel.
• Die Facebook-Seitensuche (GET /fb-pages) liefert für den Sandbox-Schlüssel immer eine leere Liste.

Beispielanfrage

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

Ersetzen Sie den Pfad durch eine Anzeigen-ID aus der Suchantwort, um Details anzurufen oder herunterzuladen.

Authentifizierung

Authentifizieren Sie jede Anfrage mit dem X-API-Key-Header. Die Tasten sehen aus wie adl_, gefolgt von 40 Zeichen.

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

Anfragen ohne gültigen Schlüssel werden abgelehnt:

• 401 Unauthorized – der Header fehlt oder der Schlüssel ist unbekannt.
• 403 Forbidden – der Schlüssel ist deaktiviert oder Ihr Plan beinhaltet keinen API-Zugriff.

Ratenbegrenzungen

Grenzwerte werden pro API-Schlüssel und pro Endpunkt angewendet. Tägliche Zähler werden um Mitternacht zurückgesetzt UTC.

Jede Antwort enthält Ratenlimit-Header:

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

Wenn ein Grenzwert überschritten wird, antwortet der API mit 429 Too Many Requests und einem Retry-After-Header (in Sekunden). Abgelehnte Anfragen werden nicht auf Ihr Tageskontingent angerechnet.

GET Suchanzeigen

GET /api/v1/ads

Durchsucht die Anzeigenbibliothek. Gibt eine paginierte Liste mit minimalen Anzeigeninformationen zurück; Verwenden Sie den Endpunkt „Details“ für Mediendeskriptoren und den Endpunkt „Download“ für Originaldateien. Alle Abfrageparameter sind optional. Listenparameter akzeptieren durch Kommas getrennte Werte.

Abfrageparameter

Beispielanfrage

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"

Beispielantwort

{
  "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-Seiten suchen

GET /api/v1/fb-pages

Sucht Facebook-Seiten (Werbetreibende) nach Namen. Nutzen Sie sie, um einen Marken-, App- oder Produktnamen in eine fbOriginalPageId umzuwandeln, bevor Sie Anzeigen nach diesem Werbetreibenden filtern. Gibt die besten Treffer mit Seitenname, Likes, Profil-Link und Bild zurück.

Abfrageparameter

Beispielanfrage

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

Beispielantwort

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

Übergeben Sie eine zurückgegebene fbOriginalPageId an GET /ads als fbOriginalPageId, um die Anzeigen dieses Werbetreibenden abzurufen.

GET Anzeigendetails abrufen

GET /api/v1/ads/:id

Gibt vollständige Informationen für eine einzelne Anzeige zurück, einschließlich Medienbeschreibungen mit Vorschau-URLs. Medienobjekte stellen einen mediaId bereit, den Sie an den Download-Endpunkt übergeben, um die Datei mit der höchsten Auflösung abzurufen.

Pfadparameter

Beispielanfrage

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

Beispielantwort

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

Die Medien URLs in dieser Antwort haben Vorschauqualität (verkleinerte Bilder / SD-Videos). Verwenden Sie den Download-Endpunkt, um die Originaldatei abzurufen.

GET Medien herunterladen

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

Löst die Datei mit der höchsten Auflösung (Originalbild oder HD-Video) für ein Medienelement einer Anzeige auf und antwortet mit 302 Found und einem Location-Header, der auf die Datei zeigt. Folgen Sie der Weiterleitung, um es herunterzuladen.

Parameter

Beispielanfrage

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"

Beispielantwort

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

Fehler

Fehler verwenden herkömmliche HTTP-Statuscodes und einen konsistenten JSON-Körper:

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