API-Dokumentation

Verbinde Reports, Automationen und eigene Werkzeuge mit ADMONGER. Die API liefert deine Projektinformationen bis zu einzelnen Logbuch-Einträgen, Creative-Dateien, täglichen Anzeigenmetriken, Kommentaren, Website-Conversions, Reports, Skripten und Angeboten.

Schnellstart

Unter API-Zugang einen persönlichen Token erstellen und sicher speichern.
Die feste Basisadresse https://www.admonger.de/api/v1 verwenden.
Projekte abrufen und die zurückgegebene Projekt-ID für weitere Anfragen verwenden.

# Gemeinsame Plattform für alle Nutzer
export ADMONGER_URL="https://www.admonger.de"
# ADMONGER_TOKEN über deine Secret-Verwaltung setzen.

curl "$ADMONGER_URL/api/v1/projects" \
  -H "Authorization: Bearer $ADMONGER_TOKEN"

curl "$ADMONGER_URL/api/v1/projects/PROJEKT_ID/log-entries?limit=100" \
  -H "Authorization: Bearer $ADMONGER_TOKEN"

Authentifizierung

Authorization: Bearer adm_DEIN_TOKEN

Alle Nutzer verwenden dieselbe API-Adresse. Jede Datenanfrage benötigt einen Bearer-Token. Der Server ordnet den Token automatisch seinem Nutzerkonto und dessen Projekt-Scope zu. Du sendest keine zusätzliche User-ID und brauchst keine eigene Instanz. Eine Browser-Anmeldung ersetzt diesen Header nicht. Tokens in URLs werden nicht akzeptiert. Bewahre den Token in der Secret-Verwaltung deiner Integration auf.

Tokens gehören einem aktiven Nutzer. Beim Erstellen legst du den Projekt-Scope fest: „Alle Projekte“ schließt auch später angelegte Projekte ein; „Ausgewählte Projekte“ erlaubt nur die ausdrücklich ausgewählten Projekte. Den Scope kannst du jederzeit in der Token-Verwaltung ändern. Bestehende Tokens behalten zunächst ihren bisherigen Scope „Alle Projekte“. Eine Admin-Nutzeransicht verändert diese Identität nicht. Andere Nutzer und deren Projekte sind ausgeschlossen. Projektlisten, Projektdetails, Unterressourcen und Downloads beachten den Scope; Projektgruppen werden bei eingeschränktem Scope nur ausgegeben, wenn sie mindestens ein freigegebenes Projekt enthalten. /me liefert weiterhin das Profil des Token-Eigentümers. Nicht freigegebene Projekte antworten mit 404. Tokens gelten 30, 90 oder 365 Tage; bis zu 20 aktive Tokens sind möglich.

Der Token wird nur beim Erstellen angezeigt und lässt sich jederzeit widerrufen. Schreibzugriffe unterstützt die API nicht. OAuth-Zugangsdaten, Plattformschlüssel, Einreichungs-Passwörter und Report-Freigabelinks werden nicht ausgegeben.

Endpunkte

Alle Pfade beziehen sich auf /api/v1. Anfragen verwenden GET; HEAD und OPTIONS werden ebenfalls unterstützt.

GET /me                      → eigenes Profil
GET /project-groups          → eigene Projektgruppen
GET /projects                → eigene Projekte
GET /projects/{projectId}    → Projektdetails und Kontext

GET /                        → Version und Ressourcenkatalog (ohne Token)

Der Katalog unter /api/v1 ist maschinenlesbar: Er nennt jede Ressource mit Bereich, Einzelabruf, Download sowie Datums- und Kanalfilter. Integrationen können ihn nutzen, statt die Tabelle unten nachzubauen. Jede Antwort trägt zusätzlich den Header X-Admonger-Api-Version (aktuell 1.1).

Die folgenden Ressourcen liegen unter /projects/{projectId}/. Jede liefert eine paginierte Liste. Wo angegeben, liefert ein angehängtes /{id} einen einzelnen Datensatz anhand seiner UUID.

Projektressourcen mit Einzelabruf und Filtern
Ressource	Inhalt	Abruf	Filter
Logbuch
`log-entries`	Logbuch-Einträge inklusive Reporting-Auswahl · Datum: starts_on/ends_on (überlappend)	/{id}	from/to
`categories`	Logbuch-Kategorien	/{id}	–
`log-attachments`	Logbuch-Anhänge	/{id} · /download	–
`log-mentions`	Erwähnungen	Liste	–
`suggestions`	Logbuch-Vorschläge	Liste	–
`dismissed-suggestions`	Verworfene Vorschläge	Liste	–
Creatives
`creatives`	Creatives	/{id}	–
`assets`	Creative-Dateien	/{id} · /download	–
`creative-tags`	Creative-Tags	/{id}	–
`creative-tag-assignments`	Tag-Zuordnungen	Liste	–
Learnings
`learnings`	Learnings	/{id}	–
`learning-sources`	Learning-Quellen	Liste	–
`learning-categories`	Learning-Kategorien	Liste	–
Aufgaben
`todos`	Aufgaben · Datum: due_on	/{id}	from/to
`todo-columns`	Aufgabenspalten	/{id}	–
`todo-verdicts`	Aufgabenbewertungen	Liste	–
Media Buying
`ads-daily`	Tägliche Rohdaten je Konto, Kampagne, Anzeigengruppe und Anzeige · Datum: date	Liste	from/to · channel
`ads-objects`	Kampagnen, Anzeigengruppen und Anzeigen	Liste	channel
`ad-activities`	Änderungsprotokoll der Werbekonten · Datum: event_date	Liste	from/to
`ad-jobs`	Upload-Läufe mit Konfiguration und Ergebnissen	/{id}	–
`created-ads`	Erstellte Anzeigen	Liste	–
`accounts`	Werbekonten, Media-Buying- und Kommentar-Einstellungen	Liste	channel
`ad-sync-status`	Stand des Plattform-Abgleichs je Konto	Liste	channel
Kommentare
`comments`	Kommentare mit Kategorie, Intent und Erledigt-Status · Datum: zeit	Liste	from/to
`comment-posts`	Beiträge und Anzeigen, unter denen kommentiert wurde · Datum: zeit	Liste	from/to
`comment-log`	Protokoll gesendeter Antworten, Nachrichten und Moderation · Datum: zeit	/{id}	from/to
Website-Tracking
`tracking-sites`	Websites mit Tracking	/{id}	–
`tracking-signals`	Signale (Conversion-Typen)	/{id}	–
`tracking-placements`	Platzierungen der Signale auf Seiten	/{id}	–
`tracking-campaign-signals`	Signal-Zuordnung je Kampagne	Liste	channel
`tracking-events`	Touches und Conversions mit aufgelöster Attribution · Datum: received_at	/{id}	from/to
`tracking-daily`	Tagesaggregat: Ereignisse und Personen je Signal und zugeordneter Kampagne/Anzeige · Datum: day (Projektzeitzone)	Liste	from/to
`tracking-settings`	Lead-Matching und Attributionsfenster	Liste	–
Reporting
`reports`	Reports mit Inhalt, veröffentlichter Fassung und Live-Link-Status · Datum: since/until (überlappend)	/{id}	from/to
`report-templates`	Report-Vorlagen	/{id}	–
`report-views`	Tägliche Aufrufe der Live-Reports · Datum: day	Liste	from/to
Creative Studio
`brand-profile`	Markenprofil des Creative Studios	Liste	–
`brand-assets`	Marken-Assets (Logos, Referenzen)	/{id} · /download	–
`studio-generations`	Generierte Studio-Bilder mit Eingaben und Kosten · Datum: created_at	/{id} · /download	from/to
`studio-edits`	Magic-Edits mit Ebenen	/{id}	–
Skripte & Angebote
`scripts`	Videoskripte mit Einstellungen, Reviews und Verlauf	/{id}	–
`script-folders`	Skript-Ordner	/{id}	–
`offers`	Angebote (Offer-Profile)	/{id}	–
Dateien & Chats
`project-files`	Projektdateien	/{id} · /download	–
`chats`	KI-Chats	/{id}	–
`chat-messages`	Chat-Nachrichten inklusive Inhalten	/{id}	–

Antworten enthalten die freigegebenen gespeicherten Detailfelder. Verknüpfungen bleiben als IDs erhalten: zum Beispiel entry_id bei Anhängen, learning_id bei Learning-Quellen und creative_id bei Assets. Löse diese über die zugehörigen Ressourcen auf.

Archivierte Projekte und soft-gelöschte Datensätze sind enthalten. Für aktive Inhalte filtere auf archived_at = null bzw. deleted_at = null, sofern das Feld existiert. Physisch entfernte Daten sind nicht verfügbar.

Antworten & Pagination

Einzelabrufe liefern { "data": { … } }. Listen haben dieses Format (Beispieldaten):

{
  "data": [
    {
      "id": "11111111-1111-4111-8111-111111111111",
      "name": "Beispielprojekt",
      "description": "Projektkontext",
      "archived_at": null
    }
  ],
  "pagination": {
    "limit": 1,
    "offset": 0,
    "has_more": true,
    "next_offset": 1
  }
}

limit bestimmt die Seitengröße: standardmäßig 100, maximal 500. Übernimm next_offset in die nächste Anfrage als ?offset=…. Sobald has_more false ist, sind alle Seiten gelesen. Behalte dabei dieselben Filter bei.

Sortiert wird nach dem vollständigen Primärschlüssel. Die Pagination ist kein transaktionaler Snapshot: Änderungen während des Abrufs können Datensätze zwischen Seiten verschieben. Unbekannte, doppelte und für den Endpunkt ungeeignete Parameter werden mit 400 abgewiesen.

Filter

GET /projects/{projectId}/comments?from=2026-09-01&to=2026-09-07
GET /projects/{projectId}/ads-daily?from=2026-09-01&to=2026-09-07&channel=meta

from und to sind ISO-Datumswerte, jeweils inklusive und einzeln optional. Sie gelten für jede Ressource, deren Tabelle oben eine Datumsspalte nennt. Reine Datumsspalten wie date bei ads-daily sind Kalendertage des Werbekontos, tracking-daily nutzt die Projektzeitzone. Zeitstempel wie zeit oder received_at werden als UTC-Kalendertage verglichen. Logbuch-Zeiträume und Reports zählen, sobald sie den Filter überlappen.

Der optionale Filter channel akzeptiert meta, google und chatgpt und gilt für Ressourcen mit Kanalspalte: ads-daily, ads-objects, accounts, ad-sync-status und tracking-campaign-signals. Ein Filter an einer Ressource ohne passende Spalte wird mit 400 abgewiesen, statt still ignoriert zu werden.

Media Buying

Tagesdaten enthalten unter anderem date, level, object_id, kanal, impressions, reach, clicks, spend, actions und interactions. Anzeigenobjekte ergänzen Namen, Hierarchie, Status, Budgets und gespeicherte details.

Die API liefert den gespeicherten Sync-Stand und startet keinen neuen Plattformabgleich; wann zuletzt abgeglichen wurde, zeigt ad-sync-status. Abgeleitete Kennzahlen berechnest du aus den Rohdaten. Summiere dabei nicht Konto-, Kampagnen- und Anzeigenebenen zusammen – sie können dieselben Auslieferungen abbilden.

Kommentare, Tracking, Reporting & Studio

Kommentare. comments enthält Facebook- und Instagram-Kommentare mit kategorie, intent, von_uns, verborgen und erledigt_am. Offene Kommentare sind solche ohne eigene Antwort-Markierung, nicht verborgen und ohne erledigt_am. comment-posts liefert Beitrag oder Anzeige zu beitrag_id, comment-log das Protokoll gesendeter Antworten und Nachrichten. Plattform-Nutzer-IDs werden nicht ausgegeben.

Website-Tracking. tracking-sites, tracking-signals und tracking-placements beschreiben die Einrichtung. tracking-events liefert einzelne Touches und Conversions mit der aufgelösten Attribution, wie sie die Oberfläche zeigt (attribution_basis: direkt, identifiziert oder modelliert). tracking-daily ist das Tagesaggregat je Signal und zugeordneter Kampagne/Anzeige ohne Testereignisse – für Auswertungen meist die bessere Wahl. people zählt Personen je Tag und ist über Tage nicht eindeutig. Besucher-, Sitzungs- und Kontaktschlüssel bleiben intern.

Reporting. reports enthält Entwurf (content) und veröffentlichte Fassung, dazu live_link_active und die Summe der Live-Aufrufe; tägliche Aufrufe stehen in report-views. Freigabe-Tokens und Passwörter werden nicht ausgegeben.

Creative Studio, Skripte und Angebote. brand-profile, brand-assets, studio-generations und studio-edits bilden das Creative Studio ab, scripts und script-folders die Skripte samt Einstellungen, Reviews und Assistentenverlauf, offers die Angebotsprofile.

Dateien herunterladen

GET /projects/{projectId}/assets/{id}/download
GET /projects/{projectId}/log-attachments/{id}/download
GET /projects/{projectId}/project-files/{id}/download
GET /projects/{projectId}/brand-assets/{id}/download
GET /projects/{projectId}/studio-generations/{id}/download

{
  "data": {
    "url": "https://…",
    "expires_in": 60
  }
}

Rufe die zurückgegebene URL innerhalb von 60 Sekunden auf. Sie benötigt keinen zusätzlichen Bearer-Header. Bereits ausgestellte Links bleiben nach einem Token-Widerruf bis zu ihrem Ablauf gültig. Für soft-gelöschte Dateien und Studio-Generierungen ohne fertiges Bild werden keine Download-Links erstellt.

JavaScript: alle Logbuch-Einträge laden

Serverseitiges Beispiel mit Umgebungsvariablen. Es liest alle Seiten eines Projekts und meldet API-Fehler.

const base = process.env.ADMONGER_URL.replace(/\/$/, '') + '/api/v1';
const token = process.env.ADMONGER_TOKEN;
const projectId = process.env.ADMONGER_PROJECT_ID;
const entries = [];
let offset = 0;

while (true) {
  const url = new URL(base + '/projects/' + projectId + '/log-entries');
  url.searchParams.set('limit', '100');
  url.searchParams.set('offset', String(offset));
  const response = await fetch(url, {
    headers: { Authorization: 'Bearer ' + token },
  });
  if (!response.ok) {
    throw new Error('API ' + response.status + ': ' + await response.text());
  }
  const { data, pagination } = await response.json();
  entries.push(...data);
  if (!pagination.has_more) break;
  offset = pagination.next_offset;
}
console.log(entries);

Fehler & Limits

{ "error": { "code": "invalid_token" } }

Pro Token sind 120 Anfragen pro Minute erlaubt. Zusätzlich gilt ein gemeinsames Limit von 120 Datenabfragen pro Nutzer und Minute für REST-API und MCP. API-Antworten tragen Cache-Control: private, no-store. CORS unterstützt Bearer-Anfragen ohne Cookies. Bei 429 den angegebenen Zeitraum abwarten und anschließend fortsetzen.