Skip to the content

DocumentationAPI

Connect your systems

API

The API, its description, sign-in, errors, retries and versions

Everything the web app does, it does through this API: the same routes are open to an organisation's own systems.

The description

The API describes itself in OpenAPI 3.1 at <API>/v1/openapi.json, generated from the code, so it is never behind the API it describes. Every route lists the permission it needs.

Signing in

  • People: a bearer token from the identity provider (Authorization: Bearer …): OpsCommand's own, an organisation's provider (enterprise sign-in, SIGN_IN.md), or in a private deployment the installation's provider. What a person may do comes only from their roles in the organisation, never from the token.
  • Services: an ingest key per service (oik_…) for errors, logs and deployments (OPENTELEMETRY.md).
  • Directories: a SCIM token per organisation (/scim/v2).
  • AI assistants: a scoped, short-lived grant (ASSISTANTS.md).

An organisation's routes are under /v1/organisations/{org}/…, by its short address or its id. An organisation you are not a member of answers not found: its existence is not revealed.

Answers and errors

  • JSON in and out; times in ISO 8601 with a time zone.
  • Errors are problem details (RFC 9457, application/problem+json): type, title, status, a detail a person can act on, the instance, the request id, and for an invalid request every field that is wrong. A missing permission names the permission.
  • Every answer carries X-Request-Id; give it when asking for support.
  • Lists that can grow are paginated with an opaque cursor.

Retries and limits

  • Creating something accepts an Idempotency-Key header (8–128 letters, digits or ._:-): a retry of the same request returns the first answer instead of creating twice; the same key with a different request is refused.
  • Rate limits answer 429, with Retry-After where the wait is known.

Versions

The API is versioned in its path (/v1). A route to be removed is announced first: it answers with Deprecation and Sunset (RFC 8594) headers until the date, and the change is in the release notes.

Webhooks

OpsCommand calls an organisation's own systems when things happen, signed so they can be verified (WEBHOOKS.md).