API Design Principles

The octoja API provides HTTP endpoints for working with platform data and operations programmatically.

API Design Principles

The octoja API is the HTTP surface that the octoja web dashboard and the octoja agents use to talk to the octoja platform — and the same surface you can call directly to work with your data programmatically. It is not a separately versioned public API, so endpoints can change between releases; treat the live OpenAPI description as the source of truth rather than pinning to a fixed shape. Almost every endpoint requires an authenticated caller, and octoja recognises two kinds: a signed-in user and an enrolled agent. Each gets its own token type, and every endpoint accepts only the type it expects. A few endpoints answer without any authentication, such as GET /api/about and the branding endpoints the sign-in screen loads before anyone has signed in. This article describes the conventions that surface follows so you know what to expect when you read traces, logs, or related developer documentation.

REST and JSON

octoja uses HTTPS endpoints with JSON request and response bodies.

Authentication

API clients send a bearer token in the Authorization header. Browser sessions use the octo_session cookie instead, which octoja sets on every successful sign-in — including an API login. See the API Authentication article for the current login, refresh, and session details.

HTTP status codes

The API uses standard HTTP status codes to indicate success, validation problems, authorization failures, and missing resources.

Response format

Successful responses return the requested data. Error responses are sent as application/problem+json and follow RFC 7807 Problem Details for HTTP APIs, with the standard type, title, status, and detail fields. octoja adds a traceId to every error body — quote it when you report a problem, because it identifies the exact request in octoja's own logs.

Retries and throttling

A handful of actions that send something outward — resending a user invitation, sending a test email — enforce a short cooldown. Call one again too soon and it answers 429 Too Many Requests with a problem-details body asking you to wait, then works normally a moment later.

Retry read requests and operations verified to be idempotent with exponential backoff on 429 or transient 5xx failures. Honour a Retry-After header when the response carries one. Before repeating other writes, check whether the first call already succeeded — for example, look for the case or time entry it created. A missing success response does not mean nothing was saved; backoff does not prevent duplicates.

Pagination

octoja does not apply one pagination style across the whole API. Which shape a list endpoint uses depends on how large its collection can grow, so check the endpoint before you write a paging loop.

Shape	How you ask for a page	What comes back
Paged	`page` (1-based) and `pageSize` — as query parameters on list endpoints such as `GET /api/assets`, or as fields in the request body on the filter endpoints such as `POST /api/asset-logs/filter`	The envelope `{ "items": [ … ], "total": … }`, where `items` is the current page and `total` is the overall record count for the query
Offset	`skip` and `limit`	A plain JSON array — no envelope, no total. Used by the delivery-history endpoints: webhooks, Microsoft Teams channels, email recipients, mobile notification groups, and every PSA and ITSM integration
Offset with envelope	`skip` and `take` on `GET /api/time-entries`	The envelope `{ "items": [ … ], "total": …, "totalDurationSeconds": … }`. `items` holds the current page; `total` counts all matching entries. See Time Entries API for parameters and limits.
Complete	Nothing — the endpoint takes no paging parameters and ignores them if you send some	A plain JSON array holding the whole collection. This is the most common shape by far, and it covers the configuration-sized lists such as `GET /api/customers`, `GET /api/users` and `GET /api/groups`

Paged endpoints each apply their own default and maximum page size and clamp anything larger: GET /api/assets defaults to 25 and caps at 500, GET /api/tickets defaults to 25 and caps at 100. See each endpoint's reference article, or the interactive API reference, for its exact parameters and limits.

Interactive API reference

octoja ships a complete, interactive API reference generated directly from the platform's OpenAPI definition. Because it is built from the running code, it always matches the live endpoints — treat it as the source of truth for exact paths, query parameters, request bodies, and response fields. The articles in this section are here to orient you; the interactive reference carries the full per-endpoint detail.

To open it, add /openapi to your octoja web address — the same address where you sign in to the dashboard (for example https://your-octoja-address/openapi). It is always available. To try a call that needs authentication, use the Authorize button and paste a bearer token. The raw definition behind the page sits at /openapi/v1.json, which is what you point a client generator at.

Was this helpful?

Still need help? Ask the team