API reference
Everything the UI, ir and the MCP server do goes through one REST API, served by the install at https://<host>/api. Its paths start with /v1.
The full reference
Each install serves its own description of the API, so it always matches the version you run:
| Address | What it is |
|---|---|
https://<host>/api/docs | The interactive reference: every operation, its parameters, request and response bodies, and who may call it |
https://<host>/api/openapi.yaml, https://<host>/api/openapi.json | The OpenAPI document, for generating a client |
Authenticate
| How | For |
|---|---|
Authorization: Bearer <token> | ir, CI and MCP clients. Mint a token in Settings → API tokens; it acts with its owner's roles. See API tokens |
| A browser session | The UI, after Sign in with Google, Sign in with GitHub, or the root user's email and password |
| The setup token | Only the setup wizard's calls, until the root user exists: the X-Infrared-Setup-Token header, from the Secret infrared-setup |
curl -H "Authorization: Bearer $INFRARED_TOKEN" https://<host>/api/v1/orgs
Who may call what
Per org, viewer reads, member also starts and acts on Changes and Releases, and org-admin also changes how the org works: its Products and repos, AgentRoles and AgentWorkflows, access groups, scheduling, model provider and announcement settings. Platform admins have every role in every org, and alone change what spans the install, such as backups, install features and sign-in. Some changes need a platform admin's browser session rather than a token. See Roles.
Responses and errors
Every response is a view of an Infrared custom resource: its name, its org, its spec and status, and a resourceVersion. Send the resourceVersion (or a Product's generation) back when you replace a resource, so a change made meanwhile isn't overwritten: a stale one answers 409.
Errors are RFC 9457 problem documents. detail says what failed, on which resource, and how to fix it; errors lists each field that was wrong. Common statuses:
| Status | Means |
|---|---|
| 401 | Not signed in, or the token is unknown or revoked |
| 403 | Signed in, but your roles don't allow it |
| 404 | No such resource in that org |
| 409 | It conflicts with the current state: a stale resourceVersion, a Release already in progress, or a restore in progress |
| 422 | The request is well formed but can't be done as asked, with the reason per field |
Where each area is explained
| Area | Paths | Explained in |
|---|---|---|
| Setup | /v1/setup/… | Setup wizard |
| Sign-in, tokens and access | /v1/auth/…, /v1/access/…, /v1/me/… | Access groups and access |
| Orgs | /v1/orgs, /v1/orgs/{org} | Organizations |
| Access groups | /v1/orgs/{org}/access-groups, /v1/orgs/{org}/access-groups/status, /v1/access/access-groups | Access groups |
| Clusters | /v1/clusters/… | Workload clusters |
| Products, zones and addresses | /v1/orgs/{org}/products/…, /v1/orgs/{org}/domains/… | Products, Environments and instances, Domains |
| Issues and the backlog | /v1/orgs/{org}/products/{name}/issues/… | Plan work in the backlog |
| Changes | /v1/orgs/{org}/agentworkflowruns/…, /v1/orgs/{org}/activity | Run a Change, Follow a change |
| AgentRoles and AgentWorkflows | /v1/orgs/{org}/agentroles/…, /v1/orgs/{org}/agentworkflows/… | AgentRoles, AgentWorkflows and AgentWorkflowRuns |
| Models and costs | /v1/orgs/{org}/model-provider, /v1/orgs/{org}/models, /v1/orgs/{org}/agent-costs | Models and costs |
| Releases and versions | /v1/orgs/{org}/releases/…, /v1/orgs/{org}/products/{name}/versions | Deliver a single app, A Product's Releases |
| Observability | /v1/orgs/{org}/incidents/…, SLOs, DORA, zone metrics and logs | Observability |
| Summary videos and announcements | /v1/orgs/{org}/summary-videos/…, /v1/features/… | Summary videos, Announce what's Done |
| Slack | /v1/orgs/{org}/slack/… | Slack |
| Cloud accounts and registries | /v1/cloud-identity, /v1/orgs/{org}/cloud-accounts/…, /v1/orgs/{org}/registries/… | Cloud accounts and registries |
| Backups | /v1/backup/… | Back up and restore |
| License and usage | /v1/license, /v1/usage | Licensing, Usage and limits |
| Status | /v1/status | One call for the Installation, the management cluster, the gitops repo's sync waves and resource counts, as ir status shows |
Deprecated operations
An operation marked deprecated in the OpenAPI document still answers, with a Deprecation header, and is removed one release later:
| Deprecated | Use instead |
|---|---|
GET /v1/orgs/{org}/teams, PUT /v1/orgs/{org}/teams (body {teams: [...]}) | GET /v1/orgs/{org}/access-groups, PUT /v1/orgs/{org}/access-groups (body {accessGroups: [...]}) |
GET /v1/orgs/{org}/teams/status | GET /v1/orgs/{org}/access-groups/status |
GET /v1/access/teams | GET /v1/access/access-groups, whose entries name the group in accessGroup |