REST API

The REST API lets scripts and tools do what you can do in the web app, as you. The base URL is the address of your install plus /api/v1.

Before you start #

Create a personal token on the API and AI tools page of your profile. The token is shown once, so copy it when it appears. You can make a token read-only, and give it an expiry date. Revoke it on the same page when you no longer need it.

Everything a token does is recorded under your name, in issue history, notifications and the time report. It sees what you see and can change what you can change.

Authentication #

Send the token as a bearer token on every request. Browser cookies are never accepted.

curl -H "Authorization: Bearer <your token>" https://<your domain>/api/v1/me

A missing, invalid, expired or revoked token gets 401. A read-only token can call every GET endpoint, and any other request fails with 403.

Conventions #

• Request bodies are JSON. On PATCH, send only the fields you want to change.
• Responses are JSON with camelCase fields and ISO 8601 timestamps. Markdown stays Markdown.
• Creates return 201, deletes return 204, and everything else returns 200.
• Lists return { "items": [], "page": 1, "pageSize": 50, "total": 123 }. Pass page and pageSize (1 to 100) as query parameters.
• Issue keys look like ACME-12. A project is addressed by its slug, such as acme-web, and its short key works too.
• Durations are text such as 30m, 1h 30m or 1d 4h. A day is 8 hours.
• Dates are YYYY-MM-DD.

Errors #

Every error has the same shape:

{ "error": { "code": "forbidden", "message": "You do not have permission to do that." } }

Status	Code	Meaning
400	invalid_input	The request is malformed or a field is invalid. The message names the field.
401	unauthorized	No token, or the token is invalid, expired or revoked.
403	forbidden	You can see this, but may not do that. Also used for read-only tokens.
404	not_found	It does not exist, or you cannot see it.
409	conflict	A doc was saved by someone else since the version you read.
413	too_large	The body is over the limit.
422	rejected	The input is valid but a rule refuses it, for example moving an epic that has children.
429	rate_limited	Too many requests. Wait the number of seconds in Retry-After.
500	internal	Something went wrong on the server.

Users with the client role get 404 for anything Internal and for any project they are not in. See client access.

Not available through the API #

User administration, accepting invites, signing in, changing a password and managing API tokens. A token cannot create or revoke tokens.

AI tools can use the same access through MCP.