Einführung in die Tentary API

Die API bietet dieselben Funktionen, die auch verbundene KI-Apps wie ChatGPT oder Claude über den MCP-Server von Tentary (https://mcp.tentary.com/mcp) nutzen. Wie du eine KI-App verbindest, erfährst du unter KI-Apps mit Tentary verbinden. Diese Referenz richtet sich an Entwickler:innen, die direkt mit der API arbeiten.

Basis-URL

Alle Anfragen gehen an:

https://api.tentary.com

Alle Pfade beginnen mit /v1.

API-Schlüssel

Die API nimmt nur API-Schlüssel an, keine Anmelde-Tokens von KI-Apps. Einen Schlüssel legst du in Tentary an:

1. Öffne in Tentary die Seite KI & API.
2. Klicke auf Neuer API-Schlüssel und gib dem Schlüssel einen Namen, zum Beispiel „Mein Export-Skript“.
3. Wähle unter Der Schlüssel darf: die Berechtigungen aus. Standardmäßig sind alle ausgewählt.
4. Klicke auf Schlüssel erstellen und kopiere den Schlüssel sofort. Tentary zeigt ihn nur dieses eine Mal.

Ein Schlüssel beginnt mit tnt_. Schick ihn bei jeder Anfrage im Header Authorization mit:

curl https://api.tentary.com/v1/account -H "Authorization: Bearer YOUR_API_KEY"

Die Beispiele in dieser Referenz lesen den Schlüssel aus der Umgebungsvariable TENTARY_API_KEY. So setzt du sie im Terminal:

export TENTARY_API_KEY="tnt_..."

Wichtig: Ein Schlüssel kann deine Daten lesen und ändern. Halte ihn geheim und schreib ihn nicht in Code, den andere sehen können.

Gut zu wissen:

• Nur die Kontoinhaberin oder der Kontoinhaber sieht die Seite KI & API und kann Schlüssel anlegen.
• Du kannst höchstens 10 aktive Schlüssel haben und höchstens 20 neue Schlüssel pro Tag anlegen.
• Tentary speichert nur einen Hash des Schlüssels. Hast du ihn verloren, lege einen neuen an.
• Für jeden neuen Schlüssel bekommst du die E-Mail „Neuer API-Schlüssel für dein Tentary-Konto“.
• Ein Schlüssel läuft nicht von selbst ab. Er gilt, bis du ihn auf der Seite KI & API mit Entziehen entziehst oder dein Passwort oder deine Login-E-Mail-Adresse änderst. Danach brauchst du einen neuen Schlüssel.

Berechtigungen

Jeder Schlüssel hat eine oder mehrere Berechtigungen. Fehlt eine, antwortet die API mit dem Fehler scope_missing und dem Status 403.

Berechtigung	In Tentary	Was sie erlaubt
read	Daten lesen	Alle lesenden Endpunkte und Feedback an Tentary
catalog:write	Katalog bearbeiten	Produkte, Dateien und Bilder, Kurse, Module, Lektionen, Rabattcodes, HTML-Landingpages und Rechtstexte ändern; diese archivieren oder löschen (mit Bestätigung)
customers:write	Kunden bearbeiten	Zugang geben und entziehen, Kund:innen reaktivieren, externe Kund:innen deaktivieren (mit Bestätigung)
email:write	E-Mails schreiben	Kampagnen-Entwürfe, Automationen und ihre E-Mails, Test-E-Mails; versenden, aktivieren, deaktivieren und löschen (mit Bestätigung)
orders:write	Bestellungen verwalten	Bestellungen erstatten, Abos und Ratenzahlungen beenden (beides mit Bestätigung)

Eine schreibende Berechtigung enthält kein Lesen. Ohne read kann ein Schlüssel Dinge ändern, aber nicht nachschauen.

Anfragen und Antworten

• GET liest Daten. POST und PATCH nehmen einen JSON-Body (Content-Type: application/json) und brauchen meist einen Schlüssel mit schreibender Berechtigung. POST /v1/feedback braucht nur die Berechtigung zum Lesen.
• PATCH ändert nur die Felder, die du mitschickst. Ein Feld, das du weglässt, bleibt, wie es ist. null entfernt einen Wert, wo der Endpunkt das erlaubt.
• Listen sind nach dem Neuesten sortiert und kommen seitenweise. Siehe Pagination.
• Beträge sind Dezimalzahlen als Text, zum Beispiel "19.90", immer zusammen mit einer currency wie EUR.
• Zeitpunkte sind in UTC, zum Beispiel 2026-01-31T14:05:00Z. Tage haben die Form 2026-01-31.
• Einige Aktionen wie Erstattungen, Versand und Löschen ändern nicht sofort etwas. Sie brauchen erst eine Bestätigung in Tentary. Siehe Bestätigungen.
• Fehler haben immer dasselbe Format. Siehe Fehler.

Beispieldaten

Die Beispiel-Anfragen und -Antworten stammen aus „Lena Berg Yoga“, dem Demo-Shop einer Yogalehrerin. Namen, E-Mail-Adressen und IDs sind erfunden.

Kontrolle und Protokoll

Jede Änderung über die API erscheint im Aktivitätsprotokoll als „API key: Name deines Schlüssels“. Tentary protokolliert jeden Aufruf 90 Tage lang, mit Zeit, Schlüssel oder App, Werkzeug und Ergebnis, aber ohne Inhalte.