Atrium platform docs

Control-plane API

The platform endpoints used by atrium-cli for manifests, status, env, logs, deployments, renames, and workspaces.

Updated 2026-08-30

Base URLs

Production:

https://api.atrium.st/v0
https://api.atrium.st/v0/platform

Sandbox:

https://api.peter.sandbox.atrium.st/v0
https://api.peter.sandbox.atrium.st/v0/platform

Both /v0/... and /v0/platform/... are mounted for route compatibility. Use Authorization: Bearer <access_token> with a CLI token.

Workspace endpoints

Method	Path	Notes
`GET`	`/platform/me`	Current CLI user and workspace context.
`GET`	`/platform/workspaces`	Workspaces available to the user.
`POST`	`/platform/workspaces/{workspace_id}/select`	Switch workspace and return a fresh access token.

Manifest endpoints

Method	Path	Notes
`GET`	`/platform/manifest/schema`	Platform schema metadata.
`GET`	`/platform/agents/slug/{slug}/availability`	Used by `atrium init`.
`POST`	`/platform/agents/register`	Create an agent row and persist manifest state. Does not deploy.
`PUT`	`/platform/agents/{agent_id}/manifest`	Update manifest desired state.
`GET`	`/platform/agents/{agent_id}/sync`	Return desired YAML for `atrium sync`.

Manifest writes accept either the manifest directly or this envelope:

{
  "manifest": {
    "apiVersion": "atrium.dev/v1",
    "kind": "Agent"
  },
  "git": {
    "remote": "git@github.com:org/agent.git",
    "branch": "main",
    "commitSha": "abc123"
  }
}

Runtime endpoints

Method	Path	Notes
`GET`	`/platform/agents/{agent_id}/status`	Read resolved status.
`GET`	`/platform/agents/{agent_id}/env/{service_name}`	Read resolved env for one service.
`GET`	`/platform/agents/{agent_id}/logs/{service_name}`	Recent Cloud Logging reads.

Logs support lines and follow query parameters. follow=true currently returns 501 from the backend, so the CLI polls until streaming is implemented.

Deploy and rename endpoints

Method	Path	Notes
`POST`	`/platform/agents/{agent_id}/deploy`	Create a deployment request. Supports dry-run preview from the CLI.
`POST`	`/platform/agents/{agent_id}/rename`	Rename an agent slug with explicit confirmation.

Rename payload:

{
  "new_slug": "new-name",
  "confirm": "new-name"
}

Server-side validation

Server validation mirrors the CLI validator:

apiVersion must be atrium.dev/v1.
kind must be Agent.
metadata.name must be a lowercase slug.
metadata.displayName must be non-empty.
Service type must be nextjs, python-fastapi, or hasura.
Service path must be non-empty.
Platform-owned root fields, Cloud Run fields, and env keys are rejected.