REST API

Orkestra exposes a complete REST API over HTTPS with bearer token authentication. This page covers the basics — auth, response format, rate limits and the most commonly used endpoints.

Base URL

All requests go to https://api.orkestra.team/v1/. Versions are supported for at least 12 months after a new version is announced, with a clear deprecation period.

Authentication

The API uses bearer tokens in the Authorization header. There are two ways to get tokens:

• User session — login with email/password or SSO returns a JWT. Expires in 7 days, renewable with refresh token.
• API key — for server-to-server integrations. Generated from Settings → API Keys (requires Pro or higher plan).

For local development, you can also use an MCP token — they have the same scope as the user who created them.

Response format

All responses are JSON. On success, the body is the requested object or an array. On error, the body includes an error object with code, message and optionally details:

• 400 — Bad Request (validation failed, incorrect body)
• 401 — Unauthorized (token missing or invalid)
• 403 — Forbidden (valid token but insufficient permissions)
• 404 — Not Found
• 409 — Conflict (constraint violation, like duplicate)
• 422 — Unprocessable Entity (business logic rejected the operation)
• 429 — Rate limit exceeded (check X-RateLimit-* headers)
• 5xx — Server error (retryable with backoff)

Rate limiting

Limits are applied per token and per endpoint:

• General reads: 1000 req/minute
• General writes: 500 req/minute
• Bulk operations: 100 req/minute
• Auth (login, password reset): 5 req/minute per IP
• Webhook management: 100 req/minute

Each response includes X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset headers. On 429, respect Retry-After.

Pagination

Listings use cursor-based pagination. Query parameters:

• limit — maximum number of items (default 20, max 100)
• cursor — opaque cursor returned by the previous request

The response includes nextCursor if there are more items. When it's null, you reached the end.

Main endpoints

The API's main resources:

• /v1/organizations — CRUD for organizations, members, areas
• /v1/projects — projects, workflows, custom fields
• /v1/tasks — tasks, states, assignments, comments
• /v1/wiki — pages, versions, comments, edit locks
• /v1/chat — messages, rooms, search
• /v1/analytics — metrics, dashboards, exports
• /v1/webhooks — outbound + inbound webhooks
• /v1/mcp/tokens — MCP token management

Webhooks instead of polling

If you need to be notified of changes in Orkestra, use outbound webhooks instead of polling. They're more efficient, faster and Orkestra guarantees delivery with automatic retries. See the webhooks guide.

Full documentation