Epinium-API

Zugang: Einstellungen → API Keys

Epinium stellt deine Daten über eine REST-API bereit, damit du sie aus deinen eigenen Werkzeugen lesen kannst: einem eigenen Dashboard, einem Analyseskript oder einem KI-Assistenten. Es sind dieselben Informationen wie in der App, mit denselben Zahlen.

In der aktuellen Version ist die API nur lesend: Sie dient zum Abfragen, nicht zum Ändern von Kampagnen oder Produkten.

Willst du sie aus einem KI-Assistenten nutzen?

Du musst nichts programmieren. Der Epinium-MCP verbindet genau diese Daten mit Claude und anderen kompatiblen Assistenten.

Token erzeugen

1. Gehe zu Einstellungen → API Keys
2. Klicke auf API Key erstellen und gib ihm einen Namen, der an den Zweck erinnert
3. Wähle die benötigten Berechtigungen aus
4. Kopiere den Schlüssel und bewahre ihn sicher auf
5. Verwende ihn im Authorization-Header jeder Anfrage

Der Schlüssel wird nur einmal angezeigt

Der vollständige Wert erscheint bei der Erstellung genau einmal. Verlierst du ihn, ist er nicht wiederherstellbar: Du musst ihn widerrufen und einen neuen erstellen.

Berechtigungen

Jedes Token trägt die Berechtigungen, die du bei der Erstellung auswählst. Vergib nur die, die deine Integration braucht.

Berechtigung	Gibt Zugriff auf
catalog:read	Produkte, Marken, Länder und Cluster
campaigns:read	Kampagnen, Ad Groups, Targets, Product Ads und Suchbegriffe
workflows:read	Deine Workflows, ihre Konfiguration und welche Kampagnen sie erreichen
connections:read	Die Amazon-Verbindungen deines Kontos
tasks:read	Epinium-Aufgaben und ihre Items
skills:read	Der Katalog validierter Marketing-Playbooks von Epinium

Ein Token erreicht alle Verbindungen deines Kontos. Als Agentur erreicht es die Verbindungen, die jeder Kunde mit der Annahme deiner Einladung freigegeben hat.

Als Agentur: wähle das Konto bei jedem Aufruf

Ein Agentur-Token erreicht mehrere Konten, deshalb muss jede Anfrage sagen, auf welchem sie arbeitet. Über den Header Epinium-Account: <Konto-ID> oder über den Parameter account_id, wenn du über das MCP aufrufst.

/v1/me und /v1/accounts sind die Ausnahme: sie antworten ohne Kontoauswahl, und genau sie sagen dir, welche Konten du erreichst und wie sie heißen.

Ist das Konto gewählt, siehst du es vollständig: seine Produkte und Kampagnen sind auf die freigegebenen Verbindungen begrenzt, und seine Konto-Ressourcen — Workflows, Aufgaben und Cluster, die an keiner Verbindung hängen — sind auf das Konto begrenzt. Was außerhalb deiner Reichweite liegt, wird nicht still gefiltert: eine account_id, zu der du nicht eingeladen bist, gibt einen ausdrücklichen Fehler zurück, keine leere Liste.

Welche Endpoints sie abdeckt

Jede Ressource hat eine Liste, und die meisten erlauben zusätzlich das Abrufen eines Elements über seine id. Die Metrik-Ressourcen haben nur eine Liste: Eine über einen Zeitraum aggregierte Zeile hat keine eigene Kennung.

Katalog — catalog:read

Endpoint	Was er zurückgibt
/v1/products	Deine vereinheitlichten Produkte
/v1/amazon-seller-products	Die Seller-Central-Sicht jedes Produkts
/v1/amazon-vendor-products	Die Vendor-Central-Sicht
/v1/amazon-advertising-products	Die Advertising-Sicht
/v1/seller-product-metrics	Umsatz, Sessions, Buy Box und Rank pro Produkt
/v1/vendor-product-metrics	Vendor-Umsatz pro Produkt, mit Manufacturing und Sourcing
/v1/product-brands	Deine Marken
/v1/countries	Länder und Marketplaces
/v1/clusters	Deine Keyword-Segmentierungen

Advertising — campaigns:read

Endpoint	Was er zurückgibt
/v1/campaigns	Deine Amazon-Advertising-Kampagnen
/v1/campaign-metrics	Ausgaben, Umsatz, ACOS und ROAS pro Kampagne
/v1/adgroups	Die Ad Groups jeder Kampagne
/v1/adgroup-metrics	Performance pro Ad Group
/v1/targets	Keywords und Produkt-Targets
/v1/target-metrics	Performance pro Target, mit Keyword und Match-Typ
/v1/product-ads	Die Verbindung zwischen Ad Group und beworbenem Produkt
/v1/product-ad-metrics	Performance pro beworbenem Produkt, mit seiner ASIN
/v1/search-terms	Die tatsächlichen Suchanfragen der Käufer
/v1/search-term-metrics	Performance pro Suchanfrage, mit Text und passendem Target
/v1/campaigns/{id}/optimization-history	Was die Automatisierung an einer Kampagne geändert hat, mit dem Nettoeffekt

Automatisierung — workflows:read

Endpoint	Was er zurückgibt
/v1/workflows	Deine Workflows, mit ihrem Zeitplan und ob sie aktiv sind
/v1/workflows/{id}	Die vollständige Konfiguration eines Workflows: sein Diagramm und jede Variable mit ihrem effektiven Wert
/v1/workflows/{id}/campaigns	Welche Kampagnen er wirklich erreicht, und warum jede dabei ist
/v1/workflows/{id}/performance	Die Performance dieser Kampagnen, mit ihrem Ziel daneben, um sie beurteilen zu können

Ein Workflow kann jede Nacht geplant sein und dennoch keine einzige Kampagne anfassen: /campaigns bringt genau das zum Vorschein, und wenn die Menge leer zurückkommt, nennt sie den Grund.

Verbindungen, Aufgaben und Skills

Endpoint	Berechtigung	Was er zurückgibt
/v1/connections	connections:read	Deine Amazon-Verbindungen
/v1/tasks	tasks:read	Epinium-Aufgaben
/v1/task-items	tasks:read	Die Items jeder Aufgabe
/v1/skills	skills:read	Der Katalog von Marketing-Playbooks von Epinium

Der Skills-Katalog ist von Epinium verfasster Inhalt, keine Daten deines Kontos: er ist für alle Kunden identisch. Welche Teile jedes Playbooks du erhältst, hängt von deinem Plan ab.

Zusätzlich gibt es /v1/me, das dir sagt, welche Berechtigungen und welche Konten dein Token erreicht. Das ist der erste sinnvolle Aufruf, um zu prüfen, ob der Schlüssel funktioniert.

Drei Regeln beim Lesen der Daten

Diese drei erklären fast alle Interpretationsfragen:

• Beträge sind Text, keine Zahlen. "cost": "8.22" kommt absichtlich als String, damit bei der Umwandlung in eine binäre Dezimalzahl keine Genauigkeit verloren geht.
• Verhältnisse kommen als Bruch, nicht als Prozent. Ein ACOS von 90,83 % kommt als 0.908287. Für die Anzeige mit 100 multiplizieren.
• null ist nicht 0. null heißt, dass Amazon den Wert nicht gemeldet hat; 0 heißt echte Null. Ein acos von null ist eine Kampagne, die ausgegeben und nichts verkauft hat, nicht kostenlose Werbung. Und new_to_brand_sales kommt bei Sponsored Products als null, weil Amazon es für dieses Format nicht misst.

Was die Automatisierung an einer Kampagne geändert hat

/v1/campaigns/{id}/optimization-history beantwortet, was der Workflow an einer Kampagne geändert hat, nicht was er entschieden hat. Der Unterschied zählt: in einem Entscheidungsprotokoll kann dasselbe Target in derselben Nacht mit einer Erhöhung und einer Senkung auftauchen, und dort sieht man nicht, dass sie sich aufheben.

Deshalb kommt jede Zeile aggregiert zum Nettoeffekt der Entität: das Gebot von vor der ersten Änderung des Zeitraums gegen das nach der letzten, plus wie oft es sich unterwegs bewegt hat. Ein Target, das von 0,18 € auf 0,45 € erhöht und in derselben Nacht auf 0,18 € zurückgeschnitten wurde, kommt mit einem Netto von null und zwei Bewegungen zurück — das ist die nützliche Lesart, und genau die, die eine flache Liste verbirgt.

Drei Dinge begrenzen, was zurückkommt:

• Nur echte Änderungen. Simulationen werden hier unter keinem Parameter ausgeliefert: es sind Gebote, die Amazon nie erreicht haben.
• Nur das Angewendete, nicht das Vorgeschlagene. Der Optimizer berechnet ein Gebot, das eine Obergrenze danach kappen kann; berichtet wird nur, was gesendet wurde.
• Höchstens ein Fenster von 90 Tagen. So lange werden diese Einträge aufbewahrt. Ohne Datumsangaben kommen die letzten 90 Tage zurück.

Änderungen, die keine Gebote sind — geerntete Keywords, Negatives, Platzierungsanpassungen, Targets in Quarantäne oder blockiert — werden separat in other_changes gezählt, denn sie haben kein vorheriges Gebot zum Vergleich.

Grenzen

• Metriken brauchen einen Zeitraum. start_date und end_date sind bei allen Metrik-Ressourcen Pflicht.
• Der Zeitraum hat ein Maximum, und es hängt von der Granularität ab. Mit granularity=total sind es 366 Tage, mit granularity=daily 93. Bei Targets und Suchbegriffen, den schwersten Ressourcen, sinkt das auf 93 und 31. Wer mehr anfragt, erhält einen Fehler mit dem exakten Limit. Beide Daten liegen im Zeitraum.
• Listen paginieren auf zwei Arten. Katalog- und Strukturressourcen nutzen einen Cursor (starting_after); Metrik-Ressourcen nutzen limit und offset. In beiden Fällen sagt has_more, ob eine weitere Seite folgt.
• Es gibt ein Anfragelimit pro Token. Bei Überschreitung kommt ein 429, und es genügt, langsamer erneut zu versuchen.
• Es gibt außerdem ein Limit für gleichzeitige Anfragen. Ein 429 kann „zu viele gleichzeitig“ bedeuten, nicht nur „zu viele pro Minute“; ein 503 bedeutet, dass der Server momentan ausgelastet ist. Beide bringen Retry-After mit und beide sind vorübergehend: erneut versuchen, mit weniger parallelen Anfragen.
• Eine Antwort kann nicht mehr als 5.000 Objekte expandieren. expand über Listen — die Produkte eines Clusters, die Länder einer Verbindung — multipliziert sich auf jeder Ebene. Darüber kommt ein 400, der nennt, wie viele Objekte zurückgekommen wären: limit senken, ein expand weglassen, oder diese Daten beim eigenen Endpoint anfragen.

Credits

Aufrufe dieser API verbrauchen Credits deines Kontos. Was jede Ressource kostet, siehst du in der Anwendung unter Einstellungen → Guthaben.

Jede Antwort sagt dir, was du verbraucht hast:

Header	Was es ist
X-Epinium-Credits-Cost	Was dieser Aufruf gekostet hat
X-Epinium-Credits-Remaining	Was dir bleibt. Der Wert ist ungefähr: wenn gleichzeitig anderes verbraucht, kann er abweichen
X-Epinium-Credits-Breakdown	Die Aufschlüsselung, pro Ressource und Einzelpreis: product=100x1,country=100x0
X-Epinium-Credits-Max	Das Maximum, das der Aufruf kosten konnte, vor der Ausführung berechnet

Zwei Dinge, die man wissen sollte:

• Berechnet wird nur, was geliefert wird. Ein fehlgeschlagener Aufruf kostet nichts, und ein expand, das keine Daten liefert — weil dein Token diesen Scope nicht hat oder der Datensatz zu einem anderen Konto gehört — ebenfalls nicht.
• Bei Metriken kostet der Zeitraum, nicht die Zeilenzahl. Ein Jahr mit limit=1 anzufragen ist nicht günstig: die Kosten laufen pro Tag des Zeitraums, denn genau das muss gelesen werden, um zu antworten, mit mindestens 3 Tagen pro Aufruf. Wer weniger ausgeben will, verkürzt den Zeitraum.

Reichen die Credits nicht, kommt ein 402 — vor der Ausführung: du bleibst nie mit einer halben Antwort zurück. Und er sagt nicht nur nein, sondern was zu ändern ist und auf welchen Wert:

{
  "error": {
    "type": "invalid_request_error",
    "code": "insufficient_credits",
    "message": "insufficient credits: needs up to 366 (campaignMetrics=1x1,campaignMetrics:window=365x1), 120 available. Shorten the date range to 119 days or less.",
    "param": "end_date"
  }
}

param ist dieselbe Abhilfe maschinenlesbar: limit, end_date oder include_total. Fehlt das Feld, bringt keine einzelne Parameteränderung den Aufruf durch und es muss aufgeladen werden.

Parameter und Antworten jedes Endpoints

Die Tabelle oben sagt, welche Ressourcen es gibt. Um die Eingabeparameter und die genaue Form jeder Antwort zu sehen, gibt es zwei Wege:

• Durchsuchbare Referenz — jeder Endpoint mit seinen Parametern, deren Typen und einer Beispielantwort. Wird aus der API selbst generiert und kann daher nicht veralten. Auf Englisch.
• OpenAPI-Schema — das rohe OpenAPI-3.0-Dokument, zum Import in Postman, Insomnia oder einen Client-Generator. Kein Token nötig.