REST API
Everything in Ithura is reachable over HTTP with a personal API token: tasks, projects, sprints, modules, pages, chat, goals and agent runs. The token carries your own permissions, narrowed to the scopes you give it.
API tokens need the Starter plan or higher. Agent tokens are the exception: a token bound to an agent works on every plan, on the agent routes.
If a workspace drops to Free, its existing tokens keep READ access for fourteen days so you can get your data out. Writes stop at once.
Creating a token
Workspace settings, then API tokens, then Create token.
- Token label is required. Name it after the thing that will use it, because the label is how you will recognise it in six months.
- Scopes decide what the token may do. Start from a preset (read-only, issues-only, a CI bot, automation, or full access) and adjust, or tick Full access (*) if it genuinely needs everything.
- Allowed IPs is optional. Give it CIDR blocks, separated by commas or spaces, and the token only works from those addresses. Leave it empty and any address is allowed.
The token is shown once. Copy it when it is created; it is stored hashed and cannot be read back. If you lose it, delete it and make another.
Tokens do not expire by default.
Using it
Send the token in the X-Api-Key header:
curl -H "X-Api-Key: $ITHURA_TOKEN" \
https://api.ithura.com/v1/workspaces/acme/projects/<project-id>/issues/
Authorization: Bearer <token> also works. Prefer X-Api-Key: the rate limiter counts requests per token when it sees that header, and falls back to counting per IP address when it does not. With Bearer alone, several tokens behind one address share a budget.
Two sets of routes
/v1/workspaces/{workspace}/...is the token surface. It is the one to build against.- The routes the web app uses accept either a session or a token.
Some things are deliberately not on the token surface: direct messages, huddles, scheduled messages, reminders, and your saved items. Automation does not need to read someone's DMs.
Scopes
Scopes are resource:action, for example issues:read, issues:write, issues:delete, issues:comment, projects:write, pages:read, chat:write, goals:write, boards:read, wiki:read, members:read. A wildcard works per resource, so issues:* covers all of them, and * is everything.
A call that needs a scope the token lacks is refused and names the scope it wanted, so you can fix it without guessing.
A token can also be pinned to one workspace, in which case calls to any other workspace are refused.
Rate limit
The token surface allows 60 requests a minute by default, as a sliding window. Every response carries X-RateLimit-Remaining and X-RateLimit-Reset, so a well-behaved client never has to guess. Over the limit you get 429.
On a self-hosted instance the number can differ, since whoever runs the instance sets it.
The reference
The OpenAPI spec is served at /openapi.yaml, with a browsable version at /api-docs.
One caveat worth knowing before you go looking: the published spec documents the connector routes, not yet the full /v1/workspaces/... surface described above. Until it does, the routes here and the ones your browser's network tab shows are the better guide.
Troubleshooting
| What you see | What it means |
|---|---|
| "API tokens need the Starter plan or higher. Agent tokens still work on every plan." | Creating or using a general API token needs Starter. A token bound to an agent is unaffected. |
| A token that worked yesterday now fails on a write but still reads | The workspace dropped to Free. Reads last fourteen days from that point; writes stopped immediately. |
| "Authentication required. Provide an API token via the X-Api-Key header" | No token on the request, or the header name is wrong. |
| "Invalid API token" | The token is wrong, or it was deleted. |
| "API token expired" | It had an expiry and has passed it. Create a new one. |
| "API token cannot be used from this IP" | The token is locked to CIDR blocks that do not include where you are calling from. |
| "token missing required scope" | The reply names the scope. Create a token with it; scopes cannot be added to an existing token. |
| "token is pinned to a different workspace" | The token is bound to one workspace. Use that one, or a token that is not pinned. |
| "Rate limit exceeded" | Over 60 requests in the sliding minute. Back off until X-RateLimit-Reset. |
| "INVALID_IP_CIDR" | An allowed-IP entry is not a valid CIDR block. 10.0.0.0/8 is, 10.0.0.* is not. |
| "TOKEN_SCOPES_REQUIRED" | No scopes were given. Pick scopes, or choose full access deliberately. |
Related
- Managing your agents: an agent acts with a token, and the token is its whole access.
- Webhooks: to be told when something happens, instead of polling for it.
- Zapier and Make: automation without writing a client.