API-Dokumentation

Autorisierung

Senden Sie den Token im Header Authorization: Bearer sk_live_…. Nicht in die URL schreiben — er landet sonst in Serverlogs und im Browserverlauf.

Tokens werden im Arbeitsbereich nach Bestätigung der E-Mail erstellt, maximal 5 aktive pro Konto. Der vollständige Wert wird einmal angezeigt — bewahren Sie ihn nur auf dem Server auf und widerrufen Sie ihn bei einem Leck. Derselbe Token wie im Arbeitsbereich deckt die Scopes unten ab: metadata:read, analyze:write, library:write, ai:write, keywords:write. Senden Sie den Token nur im Header Authorization. Eine Auswertung bucht Kommentare vom Guthaben ab (sonst 402 quota_exceeded). CORS: Bearer funktioniert von jedem Origin ohne Cookies; eine Cookie-Sitzung gilt nur für unsere Domains und braucht CSRF.

Sandbox — ohne Token

POST /api/v1/sandbox/metadata und POST /api/v1/sandbox/analyze liefern Fixtures in derselben Form wie die produktiven Endpunkte: ohne TikTok, ohne Kontingent, ohne Token. IP-Limit: 5 Anfragen pro Minute und 30 pro Stunde.

# Metadaten-Fixture (ohne Token)
curl -X POST https://api.example.com/api/v1/sandbox/metadata \
  -H "Content-Type: application/json" \
  -d '{"url": "https://www.tiktok.com/@user/video/7300000000000000000"}'

# Fixture der vollständigen Auswertung (sofort status: complete)
curl -X POST https://api.example.com/api/v1/sandbox/analyze \
  -H "Content-Type: application/json" \
  -d '{"url": "https://www.tiktok.com/@user/video/7300000000000000000"}'

POST /api/v1/metadata — kostenlos

Synchrone Antwort: Autor, Kennzahlen, Hashtags, Sound, Cover und Schlüsselwörter der Beschreibung. Kommentare sind hier nicht enthalten. Mit Token oder Sitzung: 10 Anfragen pro 2 Stunden und Konto. Von der Website ohne Login: 10 Anfragen pro Tag (nur Browser). Ein fehlgeschlagener Abruf verbraucht das Limit nicht. Antworten werden 5 Minuten pro URL zwischengespeichert, ein Cache-Treffer ("cached": true) verbraucht das Limit nicht. Curl und eigene Clients brauchen Bearer.

curl -X POST https://api.example.com/api/v1/metadata \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{"url": "https://www.tiktok.com/@user/video/7300000000000000000"}'

POST /api/v1/analyze — vom Kommentarguthaben

Asynchron: liefert eine job_id mit Status queued; das Ergebnis holen Sie über GET /api/v1/analyze/{job_id}. Fragen Sie alle 1–2 Sekunden ab; Status sind queued, in_progress, complete und failed. Ein fremder Job liefert 404. In comments stecken Antworten bereits als replies im übergeordneten Kommentar. Eine gespeicherte Auswertung und Kommentar-Mediendateien gelten 14 Tage ab der letzten vollständigen Kommentarerfassung; das Öffnen eines Lesezeichens verlängert das nicht.

# Job anlegen
curl -X POST https://api.example.com/api/v1/analyze \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{"url": "https://www.tiktok.com/@user/video/7300000000000000000"}'

# Antwort: {"job_id": "b1e2...", "status": "queued"}

# Ergebnis abholen
curl https://api.example.com/api/v1/analyze/b1e2... \
  -H "Authorization: Bearer sk_live_..."

Dieselbe URL erneut

Dieselbe URL wird nie zweimal geparst. Läuft der Job noch, erhalten Sie dessen job_id zurück ("deduplicated": "in_flight"). Liegt das Ergebnis weniger als 5 Minuten zurück, kommt der fertige Job ("deduplicated": "recent_result"). In beiden Fällen wird kein Kontingent verbraucht.

Idempotency-Key

Optional. Senden Sie den Header Idempotency-Key mit einem eindeutigen Wert, liefert eine Wiederholung mit demselben Schlüssel innerhalb von 24 Stunden dieselbe job_id statt eines neuen Jobs. Für normale Anfragen ist der Header nicht nötig.

Bibliothek und Beobachtung

POST /api/v1/analyses/{ref}/save speichert einen Beitrag. Liste mit GET /api/v1/analyses/saved, laden mit GET /api/v1/analyses/{ref}, entfernen mit DELETE /api/v1/analyses/{ref}. Auto-Aktualisierung mit PUT /api/v1/analyses/{ref}/watch, vollständige Erfassung mit POST /api/v1/analyses/{ref}/refresh. Die letzte Browsersitzung ist GET /api/v1/analyses/session.

Eine Token-Auswertung speichert automatisch mit bookmark_if_absent: der Beitrag ist bei complete schon in der Bibliothek. Das Abfragen von GET /api/v1/analyze/{job_id} verlängert die 14-Tage-TTL nicht.

Von der Auswertung zur Bibliothek

Mit Token ist der fertige Job bereits gespeichert. Danach können Sie beobachten oder die KI starten — dieselbe analysis_id ist die ref.

# Job anlegen
curl -X POST https://api.example.com/api/v1/analyze \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{"url": "https://www.tiktok.com/@user/video/7300000000000000000"}'

# Ergebnis abholen
curl https://api.example.com/api/v1/analyze/b1e2... \
  -H "Authorization: Bearer sk_live_..."
# fertiger Job — analysis_id ist bereits in der Bibliothek: {"status":"complete","result":{"analysis_id":"tiktok:7300..."}}

# optional: Auto-Aktualisierung
curl -X PUT https://api.example.com/api/v1/analyses/tiktok:7300.../watch \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{"enabled": true, "interval_min": 60}'

# optional: KI-Angebot (dann POST /ai/run)
curl -X POST https://api.example.com/api/v1/ai/quote \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{"ref": "tiktok:7300..."}'

KI

POST /api/v1/ai/quote liefert die Abbuchung, POST /api/v1/ai/run startet einen Job, Abfrage über GET /api/v1/ai/jobs/{id}. Beobachtungsphrasen mit PUT /api/v1/ai/{ref}/queries (bis zu drei). Ein Aufruf mit Token gilt als Einwilligung, Kommentartexte an das Modell zu senden.

Keywords und Hinweise

GET und PUT /api/v1/keywords verwalten die Wortliste des Kontos. Telegram und HTTPS-Callbacks mit GET / PUT /api/v1/notification-channels. Treffer abfragen mit GET /api/v1/keyword-alerts.

Job-Webhook

Ist job_events am Webhook-Kanal an (standardmäßig aus), senden wir POST, wenn ein Job endet: type ist job.complete oder job.failed, kind ist analyze oder ai, plus job_id, ref, url und error. Signatur des Körpers per HMAC in X-Signature wie bei Keyword-Hinweisen.

Endpunkte

Limits und Kontingente

Antworten enthalten X-RateLimit-Limit, X-RateLimit-Remaining, X-Quota-Limit und X-Quota-Remaining, bei 429 zusätzlich Retry-After in Sekunden. Den aktuellen Stand liefert auch GET /api/v1/usage.

Ist das Kommentarguthaben aufgebraucht, antwortet die Auswertung mit 402 quota_exceeded: Kaufen Sie ein Paket auf der Kommentarseite, es wird dem laufenden Monat gutgeschrieben. Das kostenlose Kommentarlimit nach der Registrierung gilt nur im Arbeitsbereich: Mit einem Token läuft die Auswertung immer über ein Paket.

Fehler

Fehlerkörper: {"detail": "...", "code": "machine_code"}