Die Workspace-API im Überblick

Die Workspace-API macht das, was in der Oberfläche am Ticket möglich ist, für eigene Werkzeuge und KI-Agenten erreichbar: Tickets abholen und filtern, anlegen und ändern, kommentieren, Teilaufgaben führen, Dateien anhängen. Angesprochen wird sie mit einem API-Token, der an eine Person gebunden ist.

Der Grundsatz

Ein Token kann nie mehr als der Mensch, an den er gebunden ist.

Das ist keine Formulierung, sondern die Bauweise: Bei jedem Aufruf lädt die API die hinterlegte Person, reichert sie mit ihrer Rolle an und reicht sie in dieselben Prüfungen, die auch die Oberfläche benutzt. Wird das Konto archiviert, die Mitgliedschaft entzogen oder der Projektzugriff geändert, wirkt das sofort auf alle Token dieser Person — ohne dass jemand am Token etwas ändern müsste.

Stufe (Lesen / Lesen + Schreiben) und Projektauswahl deckeln diese Rechte zusätzlich. Sie erweitern sie nie. Ein Kunden-Token mit Schreibrecht kann darum trotzdem keine interne Notiz anlegen, und ein Team-Token ohne Projektzugriff bleibt in diesem Projekt außen vor.

Voraussetzungen

Tarif Business oder Enterprise. Auf Free weist die API vorhandene Token mit 403 plan_required ab — gelöscht wird nichts, nach einem Wechsel zurück funktionieren sie unverändert weiter.

Ein Token, erzeugt im eigenen Konto unter Benutzerkonto → API-Zugriff. Wie das geht, steht unter Einen API-Token anlegen.

Team-Mitgliedschaft. Kundenkonten bekommen in dieser Fassung keine Token.

Adresse und Form

Die Basis ist der API-Host des eigenen Workspace, die Version steht im Pfad. Diesen Host muss man nicht raten: Etappe Flow zeigt ihn beim Anlegen eines Tokens im Einmal-Fenster als fertiges curl-Beispiel an, jede Antwort der API nennt ihn im Link-Kopf — und beide Token-Seiten zeigen die vollständige Adresse der OpenAPI-Beschreibung mit Kopierknopf.

Die Beispiele auf diesen Seiten benutzen dafür durchgehend zwei Variablen:

export ETAPPE_API="https://flow-api.braindata.de"   # der Host aus dem Token-Dialog
export ETAPPE_TOKEN="etf_…"                          # der Token, einmal sichtbar

Der Host hängt am Workspace, nicht am Produkt — ein anderer Mandant hat eine andere Adresse. Deshalb steht hier bewusst kein fester Wert zum Abschreiben.

JSON hinein, JSON heraus (application/json; charset=utf-8).

Zeitangaben immer doppelt: als ISO-8601-Zeichenkette und als _ms (Epoch-Millisekunden). Agenten kommen mit dem einen oder dem anderen besser zurecht.

IDs sind Zeichenketten. Tickets tragen zusätzlich ihre number — die Nummer, die auch in der Oberfläche steht — und sind darüber auch erreichbar: /v1/tickets/<projekt>%23<nummer> (Tickets lesen).

Die Antwortform gehört der API und ist versioniert. Sie bildet nicht die internen Abfragen der Oberfläche ab, damit eine Anzeigeänderung keinen Bruch bedeutet.

Protokolltexte sind englisch. Fehlermeldungen richten sich an Maschinen und Entwickler, nicht an Endanwender, und laufen deshalb bewusst nicht über die Übersetzung der Oberfläche.

Der erste Aufruf

GET /v1/me ist der Selbsttest. Er sagt, als wer der Token gilt, in welchem Workspace, mit welcher Stufe, wie lange noch — und wie viele Projekte er tatsächlich erreicht.

curl -s $ETAPPE_API/v1/me \
  -H "Authorization: Bearer $ETAPPE_TOKEN"

Die Projektzahl in der Antwort ist die Schnittmenge aus der Auswahl am Token und dem echten Zugriff der Person — nicht die gespeicherte Liste. Wer hier weniger Projekte sieht als erwartet, hat die Antwort schon gefunden, bevor der erste Ticket-Aufruf ins Leere läuft.

Weiter

Einen API-Token anlegen — Stufe, Projekte, Laufzeit

Tickets lesen und filtern — Listen, Filter, Blättern

Tickets suchen — „gibt es dazu schon ein Ticket?"

Tickets anlegen und ändern — der Schreibweg

Fehler, Grenzen und Kopfzeilen — Codes und Limits

Für KI-Agenten — was ein Agent zuerst wissen sollte

Was die API bewusst nicht kann

Verwaltung. Firmen, Benutzer, Projekte, Kategorien, Bereiche und Status lassen sich lesen, aber nicht anlegen oder ändern. Diese Griffe bleiben in der Oberfläche, wo sie nachvollziehbar in einer Sitzung passieren. Ebenfalls nicht in dieser Fassung: eine Rechte-Matrix je Endpunkt, Token für Kundenkonten, ausgehende Webhooks und OAuth.