REST API (beta)

Orkestra's REST API is in beta: you can use it today with a personal token, but it may still change without warning. This page covers the basics — how to get in, what a token can do, the response format and the limits.

In beta

The API is the same one the web app uses. While it is in beta there is no stability promise: a route or a field may change or disappear between releases. If you build on it, test it after each Orkestra update.

Base path

Every route hangs from /api/v1, for example https://api.orkestra.team/api/v1/projects.

Personal tokens

For a program of yours to use the API, create a token under Your settings → AI connections in the app. When you create it you choose:

  • Where it gets in: the REST API, MCP (AI assistants) or both.
  • What it can do in each part: nothing, read or write in each of these domains — tasks and projects, documents and tables, conversations and notifications, time, money, stock, products and sales, reports, organization and people, and your profile. Search, help and the overview can always be read.
  • A single organization if you want to limit it, and an expiry (never, 30 days, 90 days or a date).

The key starts with ork_ and is shown only once. Send it on every request:

Authorization: Bearer ork_…

A token can never do more than you: what it does goes through your own permissions, and if you lose access to something, so does the token. Everything it does is signed in the history with your name and the token’s. You can change what it reaches, generate a new key or revoke it anytime.

Some things can only be done from your session in the app, never with a token: managing tokens, signing in and the second step, authorizing apps, your account’s privacy, phone notifications, the calendar, SSO and SCIM, exports and phone sync.

Response format

Every response is JSON. On success:

{ "status": "success", "data": { } }

On error, message explains what happened (in the request’s language) and code classifies it:

{ "status": "error", "message": "…", "code": "FORBIDDEN" }

When a token falls short

  • 401 UNAUTHORIZED — the token is invalid, expired or revoked.
  • 403 FORBIDDEN — the token is valid but does not reach: the domain is outside its cut (or it only reads and the request writes), the route is session-only, or what you ask for is outside the organization it is limited to. The message says which.
  • 429 RATE_LIMITED — the token went over its limit; wait a few minutes.

Per-token limit

Each token gets 1000 requests every 15 minutes, one budget shared by the REST API and MCP. Responses limited by IP address carry the standard RateLimit-* headers.

Lists

Paginated lists take page and limit and answer with pagination: { page, limit, total, pages }. Some lists return a single page without that block, capped at limit (50 by default): if a full page comes back, ask for the next one.

Main routes

  • /api/v1/organizations — organizations, members and areas
  • /api/v1/projects — projects, and their tasks at /api/v1/projects/:id/tasks
  • /api/v1/tasks — tasks, comments, dependencies and time
  • /api/v1/wiki — documents
  • /api/v1/tables — data tables
  • /api/v1/search — search, filtered by what the token can read

Notifications instead of asking

If you need to hear about changes, use outbound webhooks instead of asking every so often: Orkestra notifies your system and retries if it fails.