Leitfaden
REST-API: Boards, Karten und Sprints per HTTP
Die offene Referenz zur Zuuna REST-API: zk_live_-Tokens, elf Scopes, 3.000 Anfragen pro Minute, Endpunkte und Idempotenz — ohne Account lesbar.
Die REST-API von Zuuna liest und schreibt genau das, was auch im Board steht: Boards und Spalten, Karten, Sprints, Releases, gebuchte Zeit und Git-Aktivität. Sie ist der Weg, Zuuna in eine Pipeline zu hängen, die es sonst nicht kennt.
Diese Seite beschreibt den stabilen Teil — Authentifizierung, Scopes, Limits, Fehler. Die vollständige Endpunkt-Referenz mit allen Feldern liegt in der App unter Entwickler, weil sie sich mit jedem Release ändert.
Authentifizierung
Jede Anfrage trägt ein Bearer-Token im Authorization-Header. Tokens beginnen mit zk_live_ und werden in der App unter Entwickler → API-Tokens ausgestellt. Der Klartext wird einmal angezeigt; gespeichert wird nur ein SHA-256-Hash.
curl -sS https://app.zuuna.de/api/v1/cards/ZNA-42 \
-H "Authorization: Bearer $ZUUNA_TOKEN"Ein Token ist die Delegation eines Zugriffs, keine Organisations-Zugangsdaten: Es handelt im Namen der Person, die es ausgestellt hat, und es hört auf zu funktionieren, wenn diese Person deaktiviert oder entfernt wird. Das ist Absicht — ein Token, das ein ausgeschiedenes Teammitglied überlebt, ist genau das Loch, das niemand bemerkt.
Scopes
Ein Token bekommt nur die Rechte, die du ihm gibst. Elf Scopes stehen zur Wahl:
| Scope | Erlaubt |
|---|---|
boards:read | Boards und Spalten lesen |
cards:read | Karten lesen |
cards:write | Karten anlegen und ändern |
comments:read | Kommentare lesen |
comments:write | Kommentare schreiben |
time:read | Erfasste Zeiten lesen |
time:write | Zeit auf Karten buchen |
git:write | Commits, Branches und PRs verknüpfen |
releases:write | Releases anlegen und veröffentlichen |
deployments:write | Deployments melden (building, live, failed) |
webhooks:manage | Webhooks verwalten und Zustellprotokoll lesen |
Limits
Der API-Zugriff gehört zum Developer-Tarif; Enterprise-Verträge können abweichen. Das Limit beträgt dort 3.000 Anfragen pro Minute.
Gezählt wird pro Workspace, nicht pro Token — sonst könnte man das Limit vervielfachen, indem man einfach mehr Tokens ausstellt. Jede Antwort trägt X-RateLimit-Limit, X-RateLimit-Remaining und X-RateLimit-Reset; bei Überschreitung kommt 429 zurück.
Die Endpunkte im Überblick
Alles liegt unter /api/v1. Karten sprichst du dabei mit ihrem Anzeige-Key an — /api/v1/cards/ZNA-42 funktioniert genauso wie die interne ID, weil der Key das ist, was auf der Karte, im Commit und in der CLI steht.
/boards,/boards/{id}/cards,/boards/{id}/columns— Struktur lesen/cards/{key}und darunter/comments,/checklist,/time,/relations,/attachments,/archive/sprints,/sprints/{id}/cards— Sprint-Inhalt lesen und ändern/releases,/deployments— Versionen und Deployment-Status/time/entries— Zeiterfassung/git/events,/git/branches,/git/checks,/git/merges— das, was die CLI benutzt/webhooksund darunter/deliveries,/test/groups,/me
Fehler und Idempotenz
Fehler kommen als JSON mit error und message. 401 heißt: Token fehlt, ist widerrufen oder seine Besitzerin ist nicht mehr im Workspace. 403 heißt: Token gültig, Scope fehlt. 404 bekommst du auch dann, wenn eine Karte existiert, dein Token sie aber nicht sehen darf — die Antwort verrät nicht, welcher der beiden Fälle vorliegt.
Beim Anlegen von Karten kannst du einen idempotencyKey mitschicken. Ein Retry nach einem Timeout legt dann keine zweite Karte an — der Fall, der sonst zuverlässig Doubletten produziert.
Weiter
Webhooks sind die Gegenrichtung: Zuuna ruft dich an, statt dass du fragst. Die CLI ist die fertig verpackte Variante für den häufigsten Fall — Commits mit Karten verknüpfen, ohne selbst HTTP zu schreiben. Praktisch anfangen kannst du mit dem Tutorial API-Token erstellen und erste Abfrage.
Häufige Fragen
Welchen Tarif brauche ich für den API-Zugriff?
Den Developer-Tarif. Dort lassen sich Tokens ausstellen und /api/v1 nutzen, mit 3.000 Anfragen pro Minute je Workspace. Enterprise-Verträge können davon abweichen.
Wie erstelle ich ein API-Token?
In der App unter Entwickler → API-Tokens. Du wählst die Scopes, und der Klartext wird genau einmal angezeigt — danach liegt nur noch ein SHA-256-Hash in der Datenbank. Verloren heißt neu ausstellen.
Wie hoch sind die Limits?
3.000 Anfragen pro Minute, gezählt pro Workspace und nicht pro Token. Jede Antwort trägt X-RateLimit-Limit, -Remaining und -Reset; darüber gibt es 429.
Kann ich Karten per API zwischen Sprints verschieben?
Ja, über /api/v1/sprints/{id}/cards. Die Karte lässt sich mit ihrem Anzeige-Key ansprechen, also etwa ZNA-42 statt der internen ID.
Gibt es die API-Dokumentation auch ohne Account?
Diese Seite ist offen und beschreibt den stabilen Teil. Die vollständige Endpunkt-Referenz steht in der App unter Entwickler, weil sie sich mit jedem Release ändert und eine zweite Kopie sonst irgendwann falsch wäre.