OpenClaw Starter – API Reference

GET /health

Health check endpoint. Returns worker status.

Response 200

{ "status": "ok", "service": "openclaw-starter", "version": "1.0.0", "runtime": "edge", "openclaw": { "package": "openclaw", "version": "...", "mcp_sdk": "..." }, "bindings": { "ai": true, ... }, "upstream": { "mcp_worker": "healthy", ... } }

POST /v1/agents

Create a new AI agent.

Request Body

{
  "agent_name": "string (default: 'My Agent')",
  "model": "string (default: '@cf/meta/llama-3.1-8b-instruct')",
  "model_provider": "string (default: 'workers-ai')",
  "governance_mode": "transparent | enforcing (default: 'transparent')"
}

Response 201

{ "agent": { "agent_id": "ocs_...", "agent_name": "...", "tier": "free", "session_state": "active", ... }, "claw_passport_id": "...", "sandbox_session_id": "..." }

GET /v1/agents

List all agents for the authenticated user. Not available via API keys.

Response 200

{ "agents": [...], "count": 3 }

GET /v1/agents/:id

Get agent details including state, model, governance mode.

POST /v1/agents/:id/start

Start a stopped agent. Required before chat connections.

POST /v1/agents/:id/stop

Stop a running agent. Creates an automatic checkpoint.

WS /v1/agents/:id/chat

WebSocket endpoint for real-time chat. Supports streaming AI responses and governance results.

Query Parameters

session — session ID (default: "default")

Send

{ "type": "message", "content": "Hello" }

Receive (in order)

{ "type": "governance_result", "message_id": "...", "verdict": "ADMIT", "leaf_hash": "sha256:..." }
{ "type": "stream_start", "message_id": "...", "role": "assistant" }
{ "type": "stream_chunk", "message_id": "...", "content": "..." }
{ "type": "stream_end", "message_id": "..." }

GET /v1/agents/:id/messages

Retrieve chat message history.

Query Parameters

limit (default: 50) · offset (default: 0) · session (default: "default")

DELETE /v1/agents/:id/messages

Clear all chat messages for the agent's current session.

PUT /v1/agents/:id/vault

Store a BYOK API key (AES-GCM encrypted at rest).

Request Body

{ "provider": "openai | anthropic | google", "api_key": "sk-..." }

Response 200

{ "ok": true, "provider": "openai", "key_prefix": "sk-abc...", "stored_at": "..." }

GET /v1/agents/:id/vault

List stored BYOK keys (prefixes only, never full keys).

Response 200

{ "agent_id": "...", "vault_keys": [{ "provider": "openai", "key_prefix": "sk-abc...", "stored_at": "..." }], "count": 1 }

DELETE /v1/agents/:id/vault?provider=openai

Delete a stored BYOK key.

POST /v1/agents/:id/api-keys

Create a scoped API key for programmatic access to this agent.

Request Body

{ "name": "string (optional, default: 'Default Key')" }

Response 201

{ "key_id": "key_...", "name": "...", "prefix": "ocs_...", "raw_key": "ocs_...", "created_at": "..." }

The raw_key is shown only once. Store it securely.

GET /v1/agents/:id/api-keys

List API keys for the agent.

DELETE /v1/agents/:id/api-keys/:key_id

Revoke an API key. The key cannot be used after revocation.

POST /v1/agents/:id/files

Upload a file to the agent's R2 storage. Use multipart/form-data.

GET /v1/agents/:id/files

List files in the agent's storage.

GET /v1/agents/:id/proofs/:leaf_hash

Retrieve a governance proof by leaf hash. Returns 403 if the hash does not belong to this agent.

Response 200 (proof found)

{
  "agent_id": "ocs_...",
  "hash": "sha256:...",
  "proof": { ... },
  "proof_error": null,
  "verification_url": "/verify/proof/sha256:...",
  "verification_portal": "https://obligationsign.com/verify/"
}

Response 404 (proof not found)

{ "agent_id": "ocs_...", "hash": "sha256:...", "proof": null, "proof_error": "...", "verification_url": "...", "verification_portal": "..." }

GET /v1/agents/:id/quota

Get quota usage and tier for the agent.

Response 200

{ "agent_id": "...", "email": "...", "tier": "free", "allowed": true, "remaining": 499 }