Auf dieser Seite
Anmelden mit dem API-Schlüssel
- 1Eine Person mit Organisationsverwaltung legt in der Organisation einen API-Zugang an. Bricksta zeigt den Schlüssel dabei einmal an; kopiere ihn gleich an die Stelle, wo das andere System ihn braucht.
- 2Das andere System schickt den Schlüssel bei jedem Aufruf im Kopf mit:
Authorization: Bearer <Schlüssel>. - 3Schicke den Schlüssel nie in der Adresse (Query-String). Dort landet er in Protokollen.
- 4Ist ein Schlüssel verloren oder nicht mehr nötig, wird der API-Zugang widerrufen. Der Schlüssel gilt dann sofort nicht mehr.
Jeder Aufruf steht im Lauf-Protokoll des API-Zugangs: Zeit, Pfad, Status und Dauer. Feldinhalte stehen nie darin.
Was die API kann
Ein externes System liest mit seinem API-Schlüssel die Vorgänge, die Aufgaben samt allen Feldern (mit Feld-IDs und Options-IDs) und die Vorlagen eurer Firma. Der Schlüssel handelt als eigenes API-Konto, ein Systemkonto. Er sieht genau das, was dieses Konto sehen darf: seine Rollen, private Vorlagen und die Sichtbarkeit einzelner Felder gelten auch hier.
Ein API-Konto mit Verwaltungsrechten (Organisation, Mitglieder oder Vorlagen verwalten) weist Bricksta ab. Gib dem API-Konto nur die Rechte, die das lesende System braucht.
API, Auslöser oder KI-Assistent?
| Weg | Wofür | Wer handelt |
|---|---|---|
| Auslöser | Ein anderes System stößt Bricksta von außen an, zum Beispiel um einen Vorgang zu starten. | Der Auslöser, ohne Person |
| KI-Assistent (MCP) | Claude oder ChatGPT arbeiten im Chat mit Bricksta. Mehr dazu unter Bricksta in Claude und ChatGPT nutzen. | Eine Person, mit ihren Rechten |
| API | Ein System liest Daten aus Bricksta, Maschine zu Maschine. | Das API-Konto, mit Schlüssel |
Soll Bricksta von sich aus melden, wenn etwas passiert, nutzt du den Rückkanal: ausgehende Webhooks.
Die Abrufe in Version 1
| Aufruf | Liefert |
|---|---|
GET /api/v1/cases | Eine Seite Vorgänge. Filter: updated_since, template, status, field mit value, limit (1 bis 100) und cursor. |
GET /api/v1/cases/{id} | Ein Vorgang mit allen seinen Aufgaben. |
GET /api/v1/tasks/{id} | Eine Aufgabe mit allen Feldern, auch den leeren, jeweils mit ihren IDs. |
GET /api/v1/templates | Die Vorlagen eurer Firma, die das API-Konto sehen darf. |
GET /api/v1/openapi.json | Die Beschreibung der API als OpenAPI 3.1. Dafür braucht es keine Anmeldung. |
Blättern und abgleichen
Bei GET /api/v1/cases gibst du den next_cursor der Antwort beim nächsten Aufruf als cursor mit. Ist next_cursor leer (null), bist du am Ende. Ein Vorgang kann beim Blättern mindestens einmal geliefert werden, also auch zweimal. Gleiche deshalb über die id ab.
Änderungen aus den letzten 30 Sekunden erscheinen erst beim nächsten Abruf. Für einen laufenden Abgleich merkst du dir das größte updated_at deiner letzten Antwort und fragst damit als updated_since nur nach Neuem. Nimm dafür nicht die Uhrzeit deines Abrufs: Was in den 30 Sekunden davor geändert wurde, fehlte in der Antwort und fiele sonst durch. updated_at ändert sich auch, wenn eine Aufgabe oder ein Feldwert des Vorgangs geändert wird.
Grenzen
| Grenze | Wert |
|---|---|
| Lesende Aufrufe | 120 je Minute und Schlüssel |
| Schreibende Aufrufe | 30 je Minute und Schlüssel (für spätere Versionen) |
| Gleichzeitige Aufrufe | höchstens 4 je Schlüssel, 8 je Firma |
Bei Überschreitung antwortet Bricksta mit 429 und dem Kopf Retry-After: so viele Sekunden wartest du, dann geht es weiter. Eine Firma, deren Vertrag beendet ist, kann weiter lesen.
Fehlermeldungen
Bei einem Fehler antwortet Bricksta mit application/problem+json (RFC 9457) und einem code. Nach dem code richtest du die Behandlung im anderen System aus. Die Codes stehen unten nach Status geordnet.
Anfrage fehlerhaft (400)
| Code | Bedeutung |
|---|---|
invalid_parameter | Ein Parameter hat einen ungültigen Wert. |
unknown_parameter | Die Anfrage enthält einen Parameter, den es nicht gibt. |
invalid_limit | limit liegt nicht zwischen 1 und 100. |
invalid_cursor | Der cursor ist ungültig oder abgelaufen. Beginne die Liste von vorn. |
idempotency_key_required | Ein schreibender Befehl braucht einen Idempotenz-Schlüssel. Betrifft spätere Versionen. |
unknown_command | Diesen Befehl gibt es nicht. |
Anmeldung und Rechte (401, 403, 404)
| Code | Status | Bedeutung |
|---|---|---|
invalid_api_key | 401 | Der Schlüssel fehlt, ist unbekannt oder widerrufen. Bricksta antwortet in allen drei Fällen gleich. |
account_has_admin_rights | 403 | Das API-Konto hat Verwaltungsrechte und wird abgewiesen. |
forbidden | 403 | Das API-Konto darf das nicht sehen oder tun. |
not_found | 404 | Das Objekt gibt es nicht. Das gilt auch für Objekte einer anderen Firma. |
Schreibende Befehle (409 bis 423)
Diese vier Codes treten erst bei schreibenden Befehlen späterer Versionen auf. Version 1 liest nur.
| Code | Status | Bedeutung |
|---|---|---|
conflict | 409 | Der Stand hat sich inzwischen geändert. |
payload_too_large | 413 | Die gesendeten Daten sind zu groß. |
unprocessable | 422 | Die Daten sind lesbar, passen aber nicht zu den Regeln der Vorlage. |
read_only | 423 | Die Firma ist gerade schreibgeschützt. |
Zu viele Aufrufe (429)
| Code | Bedeutung |
|---|---|
rate_limited | Das Limit je Minute ist erreicht. Warte die Zeit aus Retry-After ab. |
too_many_concurrent_requests | Zu viele Aufrufe laufen gleichzeitig. Warte kurz und versuche es erneut. |
Serverseitige Fehler (500 bis 503)
| Code | Status | Bedeutung |
|---|---|---|
internal_error | 500 | Bei Bricksta ist etwas schiefgegangen. Versuche es später erneut. |
timeout | 503 | Die Antwort hat zu lange gedauert. Mit Retry-After. |
temporarily_unavailable | 503 | Bricksta ist kurz nicht erreichbar. Mit Retry-After. |
not_written | 503 | Ein schreibender Befehl wurde nicht ausgeführt. Mit Retry-After. |
outcome_unknown | 503 | Ob ein schreibender Befehl ausgeführt wurde, ist offen. Ohne Retry-After: erst nachsehen, dann entscheiden. |