Developer API reference

Requests and identifiers

Use https://api.atrium.st/v0 as the API base and Authorization: Bearer <access-token> for authenticated requests. Send JSON bodies with Content-Type: application/json, except source uploads. See Authentication for obtaining and refreshing a token.

Platform app routes accept an app identifier or slug in {agent}; use the identifier returned by registration when storing references. Service names are keys from the manifest, such as frontend. Developer operations require access to the app's owning workspace.

The billing APIs use an app SID or UUID in the request's agent field, not its slug. Do not assume identifier rules are interchangeable across API groups.

Workspace context

Paths below are relative to /v0/platform.

Method	Path	Result
GET	/me	Current user and workspace.
GET	/workspaces	Available workspaces.
POST	/workspaces/{workspace}/select	Select workspace; CLI auth receives a fresh access token.

Use the returned token after selection. See Team access.

Scaffolding and manifests

Method	Path under /v0/platform	Purpose
GET	/manifest/schema	Supported types, fields, reserved values, and starter metadata.
GET	/init/profiles	Available starter profiles.
POST	/init/plan	Preview a scaffold without registering or deploying it.
GET	/agents/slug/{slug}/availability	Check a proposed app slug.
POST	/agents/register	Register an app and its manifest.
PUT	/agents/{agent}/manifest	Replace desired manifest state.
GET	/agents/{agent}/sync	Read the persisted desired manifest.
POST	/agents/{agent}/bootstrap/services	Validate or register declared service configuration.
GET	/agents/{agent}/status	Read resolved services and deployment state.
GET	/agents/{agent}/env/{service}	Read resolved service environment; may contain secrets.

Example scaffold preview:

POST /v0/platform/init/plan
Authorization: Bearer <access-token>
Content-Type: application/json

{
  "profile": "nextjs-fastapi",
  "name": "My Agent",
  "slug": "my-agent",
  "description": "A sample agent"
}

The plan contains the manifest and scaffold information. It does not reserve the slug or provision services. Resolve a slug conflict before registration.

Manifest writes accept the complete manifest directly or an envelope with manifest and optional git source metadata. Use the manifest example as the complete payload. A bootstrap request can supply manifest, serviceName, validateOnly, and idempotencyKey. Bootstrap does not provision a missing database, credentials, or custom-domain DNS/TLS.

Development sessions

Use these paths under /v0/platform/agents/{agent}:

Method	Path	Purpose
POST	/dev-sessions	Create or reuse a session.
GET	/dev-sessions/{session}	Read session state and expiry.
PATCH	/dev-sessions/{session}	Refresh environment and expiry.
DELETE	/dev-sessions/{session}	Revoke the session.

Create and refresh accept:

{
  "services": ["frontend", "backend"],
  "ttlSeconds": 3600,
  "idempotencyKey": "my-agent-local-session"
}

Use your actual service keys. The TTL range is 300 through 86,400 seconds; the default is 28,800. Session responses include a session object. A create request can return reused: true for a live session with the same idempotency key. Retain the returned session ID for reads, refresh, and revoke.

A session refresh does not update the environment inside an already-running local process. See Local development for restart behavior and isolated-database prerequisites.

Deployments

Paths below are relative to /v0/platform.

Method	Path	Purpose
POST	/agents/{agent}/deploy/source	Upload raw gzip source bytes; returns a source reference.
POST	/agents/{agent}/deploy/preflight	Check configuration without starting a build.
POST	/agents/{agent}/deploy	Submit deployment with manifest and source information.
GET	/agents/{agent}/deployments	Paginated deployment history.
GET	/deployments/{deployment}	Deployment status and detail.
GET	/deployments/{deployment}/events	Events as JSON or a stream.

Prefer atrium deploy for source packaging and submission. Custom clients upload a non-empty raw application/gzip body, not multipart data, with a maximum size of 200 MiB. Echo the returned source object unchanged into the deploy request; do not construct a storage location yourself.

Preflight accepts manifest and optional source. A positive result does not prove the archive builds, migrations succeed, or services become healthy. The deployment guide covers ordering, terminal states, and failure diagnosis.

History uses limit (1-100, default 20) and before (an ISO timestamp). Pass the returned nextBefore as the next request's before.

Events use cursor (non-negative integer), limit (1-1,000, default 100), stream, and format=json|sse|ndjson. An Accept: text/event-stream header also selects SSE. Preserve the returned cursor when reconnecting rather than treating a disconnect as a deployment failure.

Logs

GET /v0/platform/agents/{agent}/logs/{service} supports:

Parameter	Meaning
limit	Result limit, 1-1,000; default 100. The API does not call this lines.
cursor	Resume after a deployment-event cursor.
deployment	Select a deployment ID instead of the latest.
follow=true	Stream that service's deployment events as SSE.

Recent reads return logs, events, and availability information in sources. They may include runtime logs when available. Follow mode streams deployment events, not a continuous runtime-log tail. Before the first deployment, the response can contain empty arrays even when follow was requested.

Rename, migrations, and billing

Rename through POST /v0/platform/agents/{agent}/rename:

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

Review URL and integration impact first; confirm must exactly match the new slug.

Databases and migrations documents POST /v0/platform/agents/{agent}/services/{service}/migration-sessions and DELETE /v0/platform/agents/{agent}/migration-sessions/{session}.

Billing and entitlements documents POST /v0/billing/require, /balance, /consume, and /checkout, including their request and response shapes.

Error handling

Inspect both the HTTP status and response body. Renew authentication for 401; check enrollment or quota for 402; check workspace and permission for 403. A 404 can indicate a missing app, service, or deployment in the selected workspace.

Correct validation errors before retrying. For temporary service failures, retry with bounded backoff and preserve the operation's idempotency key where supported. Do not invent an idempotency field for an endpoint that does not define one.

When requesting support, provide the app/service and deployment or session ID, timestamp, status code, and a redacted error. Exclude tokens, cookies, secret environment values, and customer records.