Which plan do I need for API access?

The Developer plan. It is where tokens can be minted and /api/v1 becomes available, at 3,000 requests per minute per workspace. Enterprise contracts may differ.

How do I create an API token?

In the app under Developers → API tokens. You pick the scopes, and the plaintext is shown exactly once — after that only a SHA-256 hash remains in the database. Losing it means minting a new one.

What are the rate limits?

3,000 requests per minute, counted per workspace rather than per token. Every response carries X-RateLimit-Limit, -Remaining and -Reset; past the limit you get 429.

Can I move cards between sprints over the API?

Yes, via /api/v1/sprints/{id}/cards. The card can be addressed by its display key, so ZNA-42 rather than the internal id.

Are the API docs available without an account?

This page is open and covers the stable part. The complete endpoint reference lives in the app under Developers, because it changes with every release and a second copy would eventually be wrong.

Zuuna REST API — build on your board

The Zuuna REST API reads and writes exactly what the board holds: boards and columns, cards, sprints, releases, logged time and git activity. It is how you put Zuuna into a pipeline it knows nothing about.

This page covers the stable part — authentication, scopes, limits, errors. The full endpoint reference, with every field, lives in the app under Developers, because it changes with every release.

Authentication

Every request carries a bearer token in the Authorization header. Tokens start with zk_live_ and are minted in the app under Developers → API tokens. The plaintext is shown once; only a SHA-256 hash is stored.

curl -sS https://app.zuuna.de/api/v1/cards/ZNA-42 \
  -H "Authorization: Bearer $ZUUNA_TOKEN"

A token is a delegation of one person's access, not an org-owned credential: it acts as whoever minted it, and it stops working when that person is deactivated or removed. That is deliberate — a token outliving the teammate who left is exactly the hole nobody notices.

Scopes

A token only gets the rights you give it. Eleven scopes are available:

Scope	Grants
`boards:read`	Read boards and columns
`cards:read`	Read cards
`cards:write`	Create and update cards
`comments:read`	Read comments on cards
`comments:write`	Post comments on cards
`time:read`	Read logged time
`time:write`	Log time on cards
`git:write`	Link commits, branches and PRs
`releases:write`	Create and publish releases
`deployments:write`	Report deployments (building, live, failed)
`webhooks:manage`	Manage webhooks and read the delivery log

Limits

API access is part of the Developer plan; enterprise contracts may differ. The limit there is 3,000 requests per minute.

The bucket is the workspace, never the token — otherwise the limit could be multiplied by minting more tokens. Every response carries X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset; exceeding it returns 429.

The endpoints

Everything sits under /api/v1. Cards are addressed by their display key — /api/v1/cards/ZNA-42 works just as well as the internal id, because the key is what appears on the card, in the commit and in the CLI.

/boards, /boards/{id}/cards, /boards/{id}/columns — read the structure
/cards/{key} and below it /comments, /checklist, /time, /relations, /attachments, /archive
/sprints, /sprints/{id}/cards — read and change sprint contents
/releases, /deployments — versions and deployment status
/time/entries — time tracking
/git/events, /git/branches, /git/checks, /git/merges — what the CLI uses
/webhooks and below it /deliveries, /test
/groups, /me

Errors and idempotency

Errors come back as JSON with error and message. 401 means the token is missing, revoked, or its owner is no longer in the workspace. 403 means the token is valid but the scope is not there. You also get 404 when a card exists but your token may not see it — the response does not tell you which of the two it was.

When creating cards you can send an idempotencyKey. A retry after a timeout then does not create a second card — the case that otherwise produces duplicates reliably.

Webhooks are the other direction: Zuuna calls you instead of you asking. The CLI is the packaged version of the most common case — linking commits to cards without writing HTTP yourself. To start hands-on, follow Create an API token and make your first call.