REST-API und API-Tokens

Mit einem API-Token arbeiten Ihre eigenen Systeme, etwa ein MAM, ein CMS oder Ihre Skripte, über die REST-API mit einem Arbeitsbereich. Die REST-API gehört zu den Tarifen Enterprise und OnPremise. Die API-Dokumentation beschreibt jede Route.

Tarife
Enterprise und OnPremise
Wer Tokens erstellt
Jedes Mitglied für sich selbst; Admins sehen und widerrufen alle Tokens des Arbeitsbereichs
Was ein Token darf
Was seine Berechtigungen erlauben, nie mehr als die Rolle seiner Person, in einem Arbeitsbereich

Was die API kann

Über die API lesen Ihre Systeme Folgen, Transkripte und Clips, laden Folgen in Teilen hoch oder importieren sie aus verbundenen Ablagen, bearbeiten Clips, senden sie zur Freigabe, geben sie frei oder schicken sie zurück, planen und posten freigegebene Clips und starten KI-Aufgaben. Außerdem verwalten sie Brand Kits, das Team, die redaktionellen Vorgaben und Webhooks, lesen Audit-Log und Verbrauch, holen freigegebene Clips mit ihren Dateien für ein CMS und liefern Clips in Ihr MAM oder DAM.

Die API folgt denselben Regeln wie die App: Rollen, Freigabe, Embargo und Kontingent. KI-Aufgaben und Uploads zählen gegen das Kontingent Ihrer Organisation.

API-Token erstellen

Jedes Mitglied des Arbeitsbereichs kann Tokens für sich selbst erstellen.

  1. Öffnen Sie Einstellungen → API.
  2. Klicken Sie auf Token erstellen.
  3. Geben Sie unter Name an, wofür das Token ist, zum Beispiel das System, das es nutzt.
  4. Wählen Sie unter Gültig für 30, 90, 180 oder 365 Tage.
  5. Entfernen Sie unter Berechtigungen die Haken bei allem, was das System nicht braucht. Anfangs sind alle Berechtigungen angehakt.
  6. Klicken Sie auf Erstellen.
  7. Klicken Sie auf Kopieren und bewahren Sie das Token dort auf, wo Ihr System seine Geheimnisse hält. ShowBits zeigt es nur dieses eine Mal und speichert nur einen Fingerabdruck davon.
  8. Klicken Sie auf Fertig.

Das Token handelt als Sie, mit Ihrer Rolle, und nur in diesem Arbeitsbereich; es kann nie mehr als Ihre Rolle. Je Arbeitsbereich können Sie bis zu 20 gültige Tokens haben.

Screenshot aus ShowBits: API-Token erstellen

Tokens sehen und widerrufen

Die Liste unter API-Tokens zeigt jedes Token mit seinem Namen, dem Ende seines Werts, dem Status (Aktiv, Abgelaufen oder Widerrufen), wer es erstellt hat, wann es erstellt wurde, bis wann es gilt und wann es zuletzt benutzt wurde. Sie sehen Ihre eigenen Tokens; Admins sehen alle Tokens des Arbeitsbereichs und können sie widerrufen.

  1. Öffnen Sie Einstellungen → API.
  2. Klicken Sie beim Token auf Widerrufen.
  3. Bestätigen Sie mit Widerrufen. Systeme, die das Token benutzen, verlieren sofort den Zugriff. Das lässt sich nicht rückgängig machen.

Ein Token endet auch, wenn es abläuft und wenn seine Person den Arbeitsbereich verlässt, und es funktioniert nur, solange der Tarif Ihrer Organisation die API enthält. Erstellen Sie rechtzeitig vor dem Ablauf ein neues Token.

Screenshot aus ShowBits: Tokens sehen und widerrufen

Die erste Anfrage

Die Basisadresse und die OpenAPI-Beschreibung stehen auf derselben Seite wie Ihre Tokens. Die OpenAPI-Beschreibung nennt jede Route maschinenlesbar; die API-Dokumentation zeigt jede Route mit der Berechtigung, die sie braucht.

  1. Öffnen Sie Einstellungen → API und kopieren Sie die Adresse nach Basisadresse. In der ShowBits Cloud ist das https://app.showbits.ai/api/v1.
  2. Schicken Sie das Token mit jeder Anfrage in der Kopfzeile Authorization: Bearer sbk_….
  3. Probieren Sie es aus: curl -H 'Authorization: Bearer sbk_…' https://app.showbits.ai/api/v1/me antwortet mit Ihrem Namen, dem Arbeitsbereich des Tokens mit seinem slug, den Berechtigungen des Tokens und seinem Ablaufdatum.
  4. Verwenden Sie den Slug in den Pfaden des Arbeitsbereichs. So listet curl -H 'Authorization: Bearer sbk_…' 'https://app.showbits.ai/api/v1/workspaces/talk-am-abend/clips?status=review' die Clips, die im Arbeitsbereich talk-am-abend auf Freigabe warten; dafür braucht das Token die Berechtigung Clips, Texte, Videos und Untertitel lesen.

In ShowBits OnPremise ist die Basisadresse die Ihrer Installation. Antworten kommen als JSON in camelCase, Zeiten in UTC (ISO 8601) und IDs als UUID.

Freigeben über die API

Clips freigeben oder zurückschicken kann ein System nur mit einem Token, das die Berechtigung Clips freigeben und zurückschicken (clips:approve) hat. Ein solches Token gibt in Ihrem Namen frei. Geben Sie diese Berechtigung deshalb nur Tokens, die sie brauchen. Der Dialog weist daneben darauf hin: „Damit kann ein System Clips in Ihrem Namen freigeben.“

Jeder Aufruf ist ein Freigabeschritt, wie ein Klick in der App: Die Antwort lautet forwarded, wenn der Clip an die nächste Stufe geht, oder approved, wenn er freigegeben ist. Das System gibt mit einem POST auf die Route des Clips mit /approve am Ende frei und schickt mit /reject zurück, beide mit einem optionalen comment. Ein zurückgeschickter Clip muss erst wieder in die Freigabe; bis dahin antwortet die API mit 409.

Grenzen, Fehler und Seiten

Je Token und Minute nimmt ShowBits 600 lesende und 60 schreibende Anfragen an. Die Kopfzeilen RateLimit-Limit, RateLimit-Remaining und RateLimit-Reset zeigen den Stand; darüber kommt 429 mit Retry-After. Fehler kommen als application/problem+json (RFC 9457) mit reason, einem festen Wort, nach dem Ihr System unterscheiden kann: 401 kein gültiges Token, 403 fehlende Berechtigung oder Rolle, 404 unbekannt oder in einem anderen Arbeitsbereich, 409 im aktuellen Zustand nicht möglich (etwa notApproved oder embargo), 413 Datei zu groß, 422 ungültige Eingabe, 429 Grenze oder Kontingent.

Listen kommen in Seiten mit bis zu 200 Einträgen (Standard 50, einzustellen mit ?limit=). Für die nächste Seite übergeben Sie nextCursor aus der Antwort als ?cursor=.

API-Aktionen im Audit-Log

Jede Änderung über ein Token steht im Audit-Log als Aktion seiner Person, mit „über das API-Token“ und dem Namen des Tokens. Auch das Erstellen und Widerrufen von Tokens steht dort.

  1. Öffnen Sie Einstellungen → Sicherheit.
  2. Scrollen Sie zum Audit-Log.

Fragen

Gilt ein Token für mehrere Arbeitsbereiche?

Nein. Ein Token gehört einer Person und einem Arbeitsbereich. Für einen anderen Arbeitsbereich erstellen Sie dort ein eigenes Token.

Ich habe das Token nicht rechtzeitig kopiert. Kann ShowBits es erneut zeigen?

Nein. ShowBits speichert nur einen Fingerabdruck davon. Widerrufen Sie das Token und erstellen Sie ein neues.

Was passiert mit den Tokens einer Person, die den Arbeitsbereich verlässt?

Sie enden sofort. Systeme, die sie genutzt haben, brauchen ein neues Token, das eine andere Person erstellt.

Kann ein System über die API Ablagen, Kanäle oder KI-Keys verbinden?

Nein. Verbindungen, KI-Keys, die Zugangsdaten eines MAM, API-Tokens und die Abrechnung richtet eine Person in der App ein.

Kann ich eine Anfrage gefahrlos wiederholen?

Ja. Ein POST darf die Kopfzeile Idempotency-Key tragen: Je Token und Schlüssel läuft er 24 Stunden lang nur einmal, und dieselbe Anfrage bekommt wieder die gespeicherte Antwort. PUT, PATCH und DELETE lassen sich ohnehin wiederholen.

Ändert sich die API unter unserer Anbindung?

/v1 wächst nur: neue Felder, Routen und Ereignisse. Übergehen Sie unbekannte Felder in Antworten; unbekannte Felder in Anfragen lehnt die API ab.

Wir haben Creator oder Business. Können wir die API nutzen?

Die REST-API gehört zu Enterprise und OnPremise; in anderen Tarifen bietet Einstellungen → API den Link Schreiben Sie uns. In jedem Tarif binden Sie n8n, Zapier und Make ohne die API an: siehe n8n, Zapier und Make.