API Design Principles
The octoja API provides HTTP endpoints for working with platform data and operations programmatically.
Written By Erdinc Akay
Last updated 26 days ago
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 session — a user session, a customer-account session, or an agent-scoped credential. A few endpoints are anonymous, such as GET /api/about. 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
Authenticated API requests use a bearer token in the Authorization header. 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 follow RFC 7807 Problem Details for HTTP APIs, with the standard type, title, status, and detail fields.
Rate limiting
Design clients to be resilient: implement retries with exponential backoff, and honor any Retry-After header returned on throttling or transient failures.
Pagination
Most list endpoints accept page (1-based) and pageSize query parameters, applying a default and a maximum page size, and respond with the envelope { Items, Total }, where Items is the current page and Total is the overall record count for the query. There are exceptions: the delivery list endpoints (webhook deliveries, Microsoft Teams deliveries, Woasi deliveries) instead take skip and limit parameters and return a plain list without the envelope. The exact default and maximum page size differ per endpoint — see each endpoint's reference article 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.