API reference
Everything you do in the UI, with ir or through the MCP server goes through one REST API. You can call it too: from CI, from a script, or from an agent of your own. It answers with the same roles you have in the UI.
The API is served at https://<host>/api, and every path starts with /v1.
curl -H "Authorization: Bearer $INFRARED_TOKEN" https://<host>/api/v1/orgs
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 |
Inside the cluster, after kubectl port-forward -n infrared svc/infrared-api 8080, the same API answers at http://localhost:8080, with no /api prefix.
Sign in
| How | For |
|---|---|
Authorization: Bearer <token> | ir, CI and MCP clients. Mint a token on the You page. It acts with the roles of the person who minted it. 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. A session lasts 12 hours |
| The setup token | Only the setup wizard's calls, until the root user exists: the X-Infrared-Setup-Token header, with the token from the Secret infrared-setup |
A few changes take a browser session and refuse a token, such as installing a license or minting a token. ir handles this for you where it needs to (ir license install --email).
Who may call what
Each org has three roles. A viewer reads. A member also starts and acts on Changes and deployments: starting runs, approving, promoting, Go now, opening issues and incidents. An org-admin also changes how the org works: its Products and repos, AgentRoles and AgentWorkflows, access groups, scheduling and model provider, and cuts releases.
Platform admins hold every role in every org. Only they change what spans the install, such as clusters, backups, sign-in and install features. 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. When you replace a resource, send back the resourceVersion you read, or a Product's generation. If someone changed the resource in the meantime, the API answers 409 instead of overwriting their change.
Errors are RFC 9457 problem documents. detail says what failed, on which resource, and how to fix it, and errors lists each field that was wrong.
| Status | Means |
|---|---|
| 401 | You aren't signed in, or the token is unknown or revoked |
| 403 | You are 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 deployment of the Product already in progress, a zone with no hold for Go now to end, or a restore in progress |
| 422 | The request is well formed but can't be done as asked; the reason is given per field |
Lists
Lists return every item in one response. The list behind Changes is the exception, because it can be long: GET /v1/orgs/{org}/changelog takes a window (since, until), filters (product, kinds, waiting), a limit (500 by default, at most 2000) and a before cursor. Pass the next value of one page as before to get the page after it.
Where each area is explained
| Area | Paths | Explained in |
|---|---|---|
| Setup | /v1/setup/… | Setup wizard |
| Sign-in and tokens | /v1/auth/… | Access groups and access |
| You | /v1/me/links/…, /v1/orgs/{org}/me/human | Your linked accounts and your own profile in the org. See Linked accounts |
| Access (platform admins) | /v1/access/… | People, git connectors and break glass. See Access groups and access |
| Orgs | /v1/orgs, /v1/orgs/{org} | Organizations |
| Access groups | /v1/orgs/{org}/access-groups, /v1/orgs/{org}/access-groups/status | Access groups |
| Workforce | /v1/orgs/{org}/teams/…, /v1/orgs/{org}/humans/… | Teams and people. See Workforce |
| Clusters | /v1/clusters/…, /v1/orgs/{org}/clusters/…, /v1/orgs/{org}/cluster-allowlist | Workload clusters |
| Cloud accounts and registries | /v1/cloud-identity, /v1/orgs/{org}/cloud-accounts/…, /v1/orgs/{org}/registries/…, /v1/orgs/{org}/build-registry | Cloud accounts and registries |
| Products, zones and addresses | /v1/orgs/{org}/products/…, /v1/orgs/{org}/repos/…, /v1/orgs/{org}/domains/…, /v1/orgs/{org}/addresses/… | Products, Environments and instances, Domains and addresses |
| Issues and the backlog | /v1/orgs/{org}/products/{name}/issues/… | Plan work in the backlog |
| Changes | /v1/orgs/{org}/agentworkflowruns/…, /v1/orgs/{org}/changelog | Run a Change, Follow a change |
| AgentRoles and AgentWorkflows | /v1/orgs/{org}/agentroles/…, /v1/orgs/{org}/agentworkflows/…, /v1/orgs/{org}/scheduling | AgentRoles, AgentWorkflows and AgentWorkflowRuns, Triggers and scheduling |
| Models and costs | /v1/orgs/{org}/model-provider, /v1/orgs/{org}/models, /v1/orgs/{org}/agent-costs | Models and costs |
| Deployments (the API's Releases) | /v1/orgs/{org}/releases/…, /v1/orgs/{org}/products/{name}/versions | Deployments, Deliver a single app |
| Releases (the API's ReleaseCuts) | /v1/orgs/{org}/releasecuts/…, /v1/orgs/{org}/products/{product}/releasecut-draft, /v1/orgs/{org}/products/{product}/release-tracks | Cut a release |
| SLOs, incidents and DORA | /v1/orgs/{org}/incidents/…, /v1/orgs/{org}/products/{name}/slos, …/dora, …/zones/{zone}/metrics, …/zones/{zone}/logs, /v1/status/{org}/{product} | SLOs, incidents and DORA |
| Summary videos | /v1/orgs/{org}/summary-videos, /v1/orgs/{org}/agentworkflowruns/{name}/summary-video/…, /v1/orgs/{org}/week-in-review/…, /v1/features/… | Summary videos |
| Slack | /v1/slack/…, /v1/orgs/{org}/slack/… | Slack |
| Code index | /v1/orgs/{org}/code/… | Code index |
| Usage and limits | /v1/orgs/{org}/usage, /v1/usage, /v1/ai-limits | Usage and limits |
| Backups | /v1/backup/… | Back up and restore |
| License | /v1/license | Licensing |
| Status | /v1/status | The Installation, the management cluster, the gitops repo's sync waves and resource counts in one call, as ir status shows them |
Deprecated operations
An operation marked deprecated in the OpenAPI document still answers, and is removed in a later release. The reference at /api/docs marks each one and names what to use instead.