API reference
This page is the lookup reference for the Orbit REST API. For an introduction, start with the API overview.
Base URL
Section titled “Base URL”https://<company>.orbit.inortix.com/api/v1For example https://acme.orbit.inortix.com/api/v1/projects. JSON property names are camelCase, IDs are strings and timestamps are ISO 8601. Paths on this page are relative to /api/v1 unless stated.
Authentication
Section titled “Authentication”| Credential | How to send it |
|---|---|
| Session cookie | orbit_session, HttpOnly, SameSite=Lax. Send credentials. Writes check the Origin. |
| Personal or service-account token | Authorization: Bearer opt_... |
Details, scopes and error codes are on API authentication.
Errors
Section titled “Errors”Every error is JSON:
{ "error": "Readable message", "code": "validation_error" }error is English text, and code is a stable name to translate or branch on. A code stays the same when the wording changes. Domain errors name their code where they are raised and may add fields. Other errors answer the code of their status, for example bad_request, authentication_required, forbidden, not_found, conflict, gone, too_large, unprocessable, rate_limited and unavailable.
| HTTP status | Meaning |
|---|---|
| 400 | Invalid JSON, field data, references, workflow transition, or JQL (invalid_jql adds position and end) |
| 401 | Missing, expired or revoked session or token |
| 403 | Insufficient membership or role, or a rejected browser origin |
| 404 | Resource or endpoint missing, or not visible to you |
| 409 | Duplicate key, stale update or preview, an explicit step is required, referenced resource, or a capacity quota (quota_exceeded, with quota, limit and used) |
| 422 | Required resolution missing, publication validation, or a report that is too large |
| 429 | Rate limit. Read Retry-After and X-RateLimit-*. |
| 503 | PostgreSQL or Redis unreachable (dependency_unavailable, with Retry-After: 5) |
When PostgreSQL or Redis cannot be reached, a request answers a retryable 503, never a 500 and never a 401 that would send people to sign in. Work committed earlier stays. A connection lost during the commit itself leaves the outcome unknown, which is why creating operations take an idempotency key.
Paging
Section titled “Paging”| API | Parameters | Response |
|---|---|---|
Generic resource lists such as /issues |
limit (1 to 500) and offset |
The page, with X-Total-Count and Link: <...>; rel="next" while more remain. Without limit the whole list is answered. Other values answer 400. |
/search |
startAt and maxResults |
{issues, total, startAt, maxResults, jql, freshness}. At most 200 per page; startAt is at most 100,000. |
Catalogs such as /project-templates |
startAt, maxResults |
{templates, total, startAt, maxResults, hasMore} |
Concurrency and idempotency
Section titled “Concurrency and idempotency”If-Unmodified-Since: <updatedAt>rejects a stale update with 409.- Operations that create something accept a
requestId. Repeating the same command with the same id returns the same result, and reusing an id for a different command answers 409. - Server-generated IDs, work item keys and creation timestamps cannot be replaced by
PATCH.
Rate limits
Section titled “Rate limits”Each API token has 600 requests a minute. Responses carry X-RateLimit-Limit and X-RateLimit-Remaining, and a request over the limit answers 429 rate_limited with Retry-After. Failed sign-ins are throttled separately: after ten for one address in 15 minutes the sign-in answers 429 too_many_failed_sign_ins.
Caching headers
Section titled “Caching headers”Bootstrap and search responses carry X-Cache: HIT, MISS or BYPASS. Search results are cached for 15 seconds per person. consistency=primary on /search reads straight from the database, and the response says which policy applied in X-Orbit-Search-Consistency.
OpenAPI and the route list
Section titled “OpenAPI and the route list”GET /openapi.json is public. It returns the OpenAPI 3.1 document of the registered /api/v1 routes, with the cookie and bearer security schemes, the Error schema on every 4XX and 5XX answer, and schemas for work items, projects, search and API tokens. It is the full list of routes. A committed list of routes is also compared with the server in tests on every release, together with the typed error body of every route.
Health checks
Section titled “Health checks”GET /health/live checks the process, and GET /health/ready (also /health) checks PostgreSQL, Redis and writer compatibility. Health routes are outside /api/v1.
Compatibility
Section titled “Compatibility”/api/v1 changes only by adding routes, optional request fields, response fields and error codes. This is Orbit’s own API and not Atlassian’s Jira REST API.
Product APIs
Section titled “Product APIs”| Product | Prefix |
|---|---|
| Pulse | /api/v1/pulse/*, /otlp/* |
| Forge | /api/v1/forge/* |
| Folio | /api/v1/folio/* |
| Lumen | /api/v1/lumen/* |