API Reference

Agents

List agents

GET /api/agents

Scope required: read

Returns all agents belonging to your account.

Response

{
  "agents": [
    {
      "id": "oc-a1b2c3",
      "name": "oc-a1b2c3",
      "status": "ONLINE",
      "agentType": "openclaw",
      "region": "eu",
      "publicUrl": "https://oc-a1b2c3.eu2.agentstead.dev",
      "createdAt": "2026-03-01T12:00:00.000Z"
    }
  ]
}

Get agent

GET /api/agents/:id

Scope required: read

Returns a single agent by ID.

Deploy agent

POST /api/agents/deploy

Scope required: deploy

Request body

{
  "agentType": "openclaw",
  "region": "eu"
}

Response: 201 Created — the new agent object.

Start agent

POST /api/agents/:id/start

Scope required: deploy

Starts a stopped agent. No request body required.

Stop agent

POST /api/agents/:id/stop

Scope required: deploy

Stops a running agent. Workspace is preserved.

Restart agent

POST /api/agents/:id/restart

Scope required: deploy

Soft restart — same container, processes restarted.

Redeploy agent

POST /api/agents/:id/redeploy

Scope required: deploy

Pulls the latest image and recreates the container. Use after image updates or to recover from a broken state. Workspace is preserved.

Get agent logs

GET /api/agents/:id/logs

Scope required: read

Returns recent log output for the agent.

Get agent health

GET /api/agents/:id/health

Scope required: read

Returns health status and runtime diagnostics.

Get agent metrics

GET /api/agents/:id/metrics

Scope required: read

Returns resource usage metrics (CPU, memory).

Secrets

Secrets are injected into the agent environment on start. Keys are stored; values are encrypted at rest and never returned after saving.

List secret keys

GET /api/agents/:id/secrets

Scope required: full

Returns key names only — values are never exposed via the API.

Response

{
  "secrets": [
    { "key": "ANTHROPIC_API_KEY" },
    { "key": "OPENAI_API_KEY" }
  ]
}

Set secret

POST /api/agents/:id/secrets

Scope required: full

Creates or replaces a secret.

Request body

{
  "key": "ANTHROPIC_API_KEY",
  "value": "sk-ant-..."
}

Delete secret

DELETE /api/agents/:id/secrets/:key

Scope required: full

Permanently removes a secret. The agent must be restarted for the change to take effect.

Backups

List backups

GET /api/agents/:id/workspace/backups

Scope required: read

Returns all backups for the agent.

Response

{
  "backups": [
    {
      "id": "bkp_xyz",
      "size": 10485760,
      "pinned": false,
      "createdAt": "2026-03-10T08:00:00.000Z"
    }
  ]
}

Create backup

POST /api/agents/:id/workspace/backup

Scope required: deploy

Triggers an immediate full workspace backup. Returns when the backup is complete.

Download backup

GET /api/agents/:id/workspace/backups/:backupId/download

Scope required: full

Returns a signed download URL for the backup archive.

Pin backup

PATCH /api/agents/:id/workspace/backups/:backupId/pin

Scope required: deploy

Pins a backup to protect it from automatic cleanup.

Request body

{ "pinned": true }

Delete backup

DELETE /api/agents/:id/workspace/backups/:backupId

Scope required: deploy

Permanently deletes a backup and frees its quota.

Schedules

Schedules trigger automated actions (backups, restarts) on a cron schedule.

List schedules

GET /api/agents/:id/schedules

Scope required: read

Create schedule

POST /api/agents/:id/schedules

Scope required: deploy

Request body

{
  "name": "Daily backup",
  "cron": "0 2 * * *",
  "action": "backup",
  "enabled": true
}

Update schedule

PATCH /api/agents/:id/schedules/:scheduleId

Scope required: deploy

Partial update — send only the fields you want to change.

Delete schedule

DELETE /api/agents/:id/schedules/:scheduleId

Scope required: deploy

Personal Access Tokens

List tokens

GET /api/user/tokens

Scope required: any valid token (or session)

Returns metadata for all your PATs. Token values are never returned.

Response

{
  "tokens": [
    {
      "id": "tok_abc",
      "name": "deploy-ci",
      "prefix": "x3s_abc1",
      "scopes": ["read", "deploy"],
      "lastUsedAt": "2026-03-12T10:00:00.000Z",
      "expiresAt": null,
      "createdAt": "2026-03-01T09:00:00.000Z"
    }
  ]
}

Create token

POST /api/user/tokens

Scope required: session auth only (cannot create tokens with a token)

Request body

{
  "name": "deploy-ci",
  "scopes": ["read", "deploy"],
  "expiresAt": "2027-01-01T00:00:00.000Z"
}

expiresAt is optional — omit for a non-expiring token.

Response: 201 Created

{
  "id": "tok_abc",
  "token": "x3s_abc123defghijklmnopqrstuvwxyz"
}

Revoke token

DELETE /api/user/tokens/:id

Scope required: session auth only

Immediately invalidates the token.