OpenClaw Starter / Docs / API Reference

API Reference

Complete REST & WebSocket API for OpenClaw Starter — agents, chat, sovereign memory, autonomous heartbeats, schedules, sub‑agents, channels, governance, vault, files, and verifiable proofs.

Base URL: https://starter.obligationsign.com
Authentication

Browser session — Dashboard and browser‑based access uses an authenticated session cookie. The verified email is propagated to all backend services.

API key — Programmatic access via Authorization: Bearer ocs_.... Keys are scoped to a single agent. Some collection‑level routes (e.g. GET /v1/agents) are blocked for API‑key callers and require a browser session.

WebSocket ticket — To open the chat WebSocket, first POST /v1/ws‑ticket to mint a single‑use ticket and connect with ?ticket=....

Webhooks — Inbound channel webhooks (/v1/webhooks/whatsapp, /v1/webhooks/email) are unauthenticated at the HTTP layer and instead verify provider signatures.

Conventions

All responses are JSON unless noted. Errors return { "error": string, "detail"?: string } with the appropriate HTTP status.

Agent IDs look like ocs_.... Leaf hashes look like sha256:.... Timestamps are ISO‑8601 UTC.

Endpoints under /v1/agents/:agentId/... are owner‑scoped — the caller must own the agent or hold a valid API key for it.

Feature‑gated endpoints return 403 feature_requires_upgrade with the required tier when the caller's tier does not allow it. Discover gating via GET /v1/capabilities.

Platform & Health

Public, unauthenticated metadata about the running platform — build version, capability catalog, supported channels, and pricing tiers. Useful for discovery, status pages, and dynamic UIs.

GET
/health
Liveness check. Returns service status, version, runtime, and dependency health.
GET
/v1/version
Build version and SDK versions in use.
GET
/v1/capabilities
Feature catalog with status (stable/beta/experimental), allowed tiers, and per‑tier limits. Drives upgrade prompts in the dashboard.
GET
/v1/architecture
High‑level capability map of the platform — surfaces and how they relate.
GET
/v1/services
Discovery map of named services exposed by the platform.
GET
/v1/tiers
Pricing tiers and per‑tier limits.
GET
/v1/cost-model
Risk‑tier pricing model used by the billing layer.
POST
/v1/cost-estimate
Estimate the cost of a proposed action before running it.
GET
/v1/channels
Supported input channels (chat, email, WhatsApp, REST).
GET
/v1/metrics
Worker‑level metrics in Prometheus format.
Example — GET /health 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", ... } }

Auth & Tickets

Identify the calling user and mint short‑lived tickets for connections that can't carry full credentials (browser WebSockets).

GET
/v1/auth/me
Returns the authenticated user's email, role, and tier.
POST
/v1/ws-ticket
Mint a single‑use WebSocket ticket. Pass via ?ticket=... when opening the chat WS.

Agents — Lifecycle

Create, list, inspect, and control agents. Agents must be started before chat connections; stop creates an automatic checkpoint. /mode toggles between Chat and Autonomous mode at runtime.

GET
/v1/agents
List all agents owned by the authenticated user. Browser sessions only.
POST
/v1/agents
Create a new agent. Body: { agent_name?, model?, model_provider?, governance_mode? }. Returns { agent, claw_passport_id, sandbox_session_id }.
GET
/v1/agents/:agentId
Agent details: state, model, governance mode, tier, mode (chat/autonomous).
PATCH
/v1/agents/:agentId
Update mutable agent fields (name, model, governance mode).
DEL
/v1/agents/:agentId
Permanently delete the agent (admin role).
GET
/v1/agents/:agentId/health
Per‑agent health, queue depth, last activity.
POST
/v1/agents/:agentId/start
Start a stopped agent. Required before opening the chat WebSocket.
POST
/v1/agents/:agentId/stop
Stop a running agent. Creates an automatic checkpoint.
POST
/v1/agents/:agentId/restore
Restore the agent from a named checkpoint.
GET
/v1/agents/:agentId/checkpoints
List checkpoints available for restore.
PATCH
/v1/agents/:agentId/mode
Toggle between chat and autonomous mode.
GET
/v1/agents/:agentId/version-health
Health of the active agent version (good/degraded/unsafe). Source for rollback decisions.
POST
/v1/agents/:agentId/rollback
Roll back the agent to a previous signed configuration version.
POST
/v1/agents/:agentId/summarize
Run an AI summary over a body of agent output (used by the dashboard).
POST
/v1/agents/:agentId/screenshot
Capture a browser screenshot via the agent's browser tool.

Chat & Messages

Real‑time chat is delivered over WebSocket. Every user message is governance‑evaluated before the model runs. Message history is fetched via REST.

WS
/v1/agents/:agentId/chat?ticket=...&session=...
WebSocket. Connect with a ticket from /v1/ws-ticket. Streams governance verdicts and assistant tokens.
GET
/v1/agents/:agentId/messages
Message history. Query: limit, offset, session.
DEL
/v1/agents/:agentId/messages
Clear messages for the agent's current session.
Send (client → server)
{ "type": "message", "content": "Hello" }
Receive (server → client, 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": "..." }

Sovereign Memory

Governed agent memory: cross‑session recall, semantic search, active compaction, and TTL controls. Every memory write is anchored on the same transparency log as governance decisions; recall is newest‑first by construction. When the index is not yet consistent the API returns 503 indexing_in_progress rather than a partial result.

GET
/v1/agents/:agentId/memory
List/query memory entries. Newest‑first, supports limit, cursor, namespace.
PUT
/v1/agents/:agentId/memory
Write or upsert a memory entry. Becomes a signed leaf in the agent's transparency log.
DEL
/v1/agents/:agentId/memory
Delete one or more memory entries by key/namespace. Deletion is itself a logged event.
GET
/v1/agents/:agentId/memory/context
Build a recall context for the agent given a query, with provenance per snippet.
POST
/v1/agents/:agentId/memory/search
Semantic search across the agent's memory.
POST
/v1/agents/:agentId/memory/consolidate
Trigger active compaction — consolidates redundant entries and re‑anchors.
POST
/v1/agents/:agentId/memory/gc
Run garbage collection over expired entries.
GET
/v1/agents/:agentId/memory/ttl
Get the active TTL policy.
POST
/v1/agents/:agentId/memory/ttl
Update the TTL policy.

Profile & Onboarding

The agent profile is the signed rulebook — a versioned, cryptographically committed contract of preferences, policies, and approvals the agent is bound to. Elicitation is the guided onboarding flow that builds and amends the profile. Export the full profile as a sovereign bundle for portability between environments.

GET
/v1/agents/:agentId/profile
Current profile (signed rulebook).
PUT
/v1/agents/:agentId/profile
Amend the profile. Each amendment is a signed, versioned commit.
GET
/v1/agents/:agentId/profile/status
Profile completeness and verification status.
GET
/v1/agents/:agentId/profile/verify
Verify the profile signature chain end‑to‑end.
GET
/v1/agents/:agentId/profile-versions
List all profile versions with their commit hashes.
POST
/v1/agents/:agentId/elicitation/start
Start a guided elicitation session to populate or amend the profile.
GET
/v1/agents/:agentId/elicitation/status
Status of the active elicitation session.
GET
/v1/agents/:agentId/onboarding-status
Onboarding checklist status.
POST
/v1/agents/:agentId/onboarding-dismiss
Dismiss the onboarding panel.
GET
/v1/agents/:agentId/config-export
Export the agent's configuration manifest.
GET
/v1/agents/:agentId/config-export/bundle
Download the full sovereign bundle (profile + memory + history) for portability.
POST
/v1/agents/:agentId/import-profile
Hydrate an agent from a previously exported sovereign bundle.

Autonomous Mode — Heartbeats

When the agent is in Autonomous Mode, it executes a heartbeat: a profile‑matched playbook of recipes that runs on a schedule and on event triggers. Each recipe can be proposed, approved, rejected, disabled, or run now. Every autonomous tool call passes the same five governance gates as Chat Mode and produces the same signed proof. Persistence failures are surfaced explicitly — never silently dropped.

GET
/v1/agents/:agentId/heartbeat
Current heartbeat configuration: cadence, recipe list, approval state per item.
POST
/v1/agents/:agentId/heartbeat/propose
Propose a new recipe for the heartbeat.
POST
/v1/agents/:agentId/heartbeat/approve
Approve a proposed recipe; it becomes eligible to run.
POST
/v1/agents/:agentId/heartbeat/reject
Reject a proposed recipe.
POST
/v1/agents/:agentId/heartbeat/:itemId/disable
Temporarily disable a previously approved recipe.
DEL
/v1/agents/:agentId/heartbeat/:itemId
Permanently remove a recipe from the heartbeat.
POST
/v1/agents/:agentId/heartbeat/run
Trigger the heartbeat to run now (out of band from its cadence).
GET
/v1/agents/:agentId/heartbeat/executions
List heartbeat executions, newest first.
GET
/v1/agents/:agentId/heartbeat/timeline
Time‑indexed governance timeline of every heartbeat decision, with proof per row. Supports cursor‑based paging for high‑volume agents.
GET
/v1/agents/:agentId/heartbeat/playbook
Active playbook resolved against the agent profile.
PUT
/v1/agents/:agentId/heartbeat/playbook/config
Update the playbook configuration.
GET
/v1/agents/:agentId/heartbeat/tools
Tools available to the heartbeat playbook for this agent.
GET
/v1/agents/:agentId/heartbeat/digest
Get the latest heartbeat digest (summary email/notification payload).
POST
/v1/agents/:agentId/heartbeat/digest/config
Configure digest cadence and style.
POST
/v1/agents/:agentId/heartbeat/digest/deliver
Force‑deliver the current digest now.

Schedules

Recurring schedules trigger heartbeat runs and dream tasks. Soft‑deleted schedules are hidden by default; pass state=all or state=deleted to query them. Schedule creation is feature‑gated.

GET
/v1/agents/:agentId/schedules
List schedules. Query: state=active|paused|deleted|all (default excludes deleted).
POST
/v1/agents/:agentId/schedules
Create a recurring schedule. Body: cadence, target action, payload.
POST
/v1/agents/:agentId/schedules/dreamtasks
Create a recurring dream‑task schedule.
GET
/v1/agents/:agentId/schedules/:scheduleId
Schedule details and last/next run.
POST
/v1/agents/:agentId/schedules/:scheduleId/pause
Pause an active schedule.
POST
/v1/agents/:agentId/schedules/:scheduleId/resume
Resume a paused schedule.
DEL
/v1/agents/:agentId/schedules/:scheduleId
Soft‑delete the schedule.

Tasks — Dream Tasks

Long‑running, multi‑step tasks the agent advances over time. Each step is a governed decision with full proof. Dream tasks are feature‑gated.

GET
/v1/agents/:agentId/tasks
List tasks for the agent.
POST
/v1/agents/:agentId/tasks
Create a new dream task.
GET
/v1/agents/:agentId/tasks/:taskId
Task details and step history.
DEL
/v1/agents/:agentId/tasks/:taskId
Cancel and remove the task.
POST
/v1/agents/:agentId/tasks/:taskId/advance
Advance the task by one step.
POST
/v1/agents/:agentId/tasks/:taskId/pause
Pause the task.
POST
/v1/agents/:agentId/tasks/:taskId/resume
Resume the task.

Sub‑Agents

An agent can spawn scoped sub‑agents to delegate work in parallel. Every delegation is cryptographically linked to the parent's proof chain. Sub‑agent spawning is feature‑gated.

GET
/v1/agents/:agentId/sub-agents
List sub‑agents spawned by this agent.
POST
/v1/agents/:agentId/sub-agents
Spawn a sub‑agent. Body: scope, goal, budget.
GET
/v1/agents/:agentId/sub-agents/:subAgentId
Sub‑agent state and progress.
GET
/v1/agents/:agentId/sub-agents/:subAgentId/result
Final result of a completed sub‑agent run.
POST
/v1/agents/:agentId/sub-agents/:subAgentId/cancel
Cancel an in‑flight sub‑agent.
POST
/v1/agents/:agentId/sub-agents/:subAgentId/review
Submit a human review decision for a sub‑agent escalation.

Channels & Webhooks

Inbound messages can reach the agent over chat (WebSocket), REST, email, or WhatsApp. All channels feed the same governance pipeline. Email and WhatsApp channels are feature‑gated. Webhooks verify provider signatures rather than using session auth.

POST
/v1/agents/:agentId/channel/message
Send an inbound message into the agent over the REST channel.
GET
/v1/webhooks/whatsapp
WhatsApp webhook verification (provider handshake).
POST
/v1/webhooks/whatsapp
Inbound WhatsApp message webhook.
POST
/v1/webhooks/email
Inbound email webhook.

Tools & Skills

Discover the governed tools and skills an agent has access to, including the unified tool catalog routed through the MCP gateway.

GET
/v1/agents/:agentId/skills
Skills enabled for this agent.
GET
/v1/agents/:agentId/mcp-tools
Catalog of tools available to the agent through the unified gateway.
GET
/v1/agents/:agentId/mcp-capabilities
Per‑tool capabilities (required scopes, governance class).

Governance

Inspect the five‑gate governance pipeline, fetch decision history, search and audit decisions, manage human‑review escalations, and export full governance bundles.

GET
/v1/agents/:agentId/governance-config
Active governance configuration: gates, policies, thresholds.
GET
/v1/agents/:agentId/governance-decisions
Recent governance decisions, newest first.
GET
/v1/agents/:agentId/governance-search
Search decisions by verdict, gate, time range.
GET
/v1/agents/:agentId/governance-audits
List saved audit views.
POST
/v1/agents/:agentId/governance-audits
Save a named audit view.
POST
/v1/agents/:agentId/governance-trace
Build a full governance trace for a specific decision.
GET
/v1/agents/:agentId/governance-traces
List governance traces for the agent.
GET
/v1/agents/:agentId/governance-widget
Compact governance summary widget payload (for embeds).
GET
/v1/agents/:agentId/event-log
Raw event log for the agent.
GET
/v1/agents/:agentId/session-state
Current session state, including pending governance escalations.
GET
/v1/agents/:agentId/review-status
Status of pending human reviews for escalated decisions.
POST
/v1/agents/:agentId/review-decision
Submit an approve/reject decision for an escalated action.
POST
/v1/governance/export
Export a governance bundle across one or more agents.
GET
/v1/governance/viewport
Global governance viewport (cross‑agent live feed).
GET
/v1/governance/events
Stream of recent governance events.
GET
/v1/governance/summary
Aggregate governance summary across the user's agents.

Proofs

Retrieve a verifiable proof for any signed leaf hash — chat decision, tool call, memory write, profile amendment, or heartbeat run. Proofs are independently verifiable through the public verification portal.

GET
/v1/agents/:agentId/proofs/:leafHash
Fetch a proof. 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": "..." }

Vault — BYOK

Bring‑your‑own‑key storage for OpenAI / Anthropic / Google providers. Keys are encrypted at rest with AES‑GCM and never returned in full — only prefixes.

GET
/v1/agents/:agentId/vault
List stored BYOK keys (prefixes only).
PUT
/v1/agents/:agentId/vault
Store a BYOK key. Body: { provider, api_key }.
DEL
/v1/agents/:agentId/vault?provider=openai
Delete a stored BYOK key.

API Keys

Mint scoped API keys for programmatic access to a single agent.

GET
/v1/agents/:agentId/api-keys
List API keys for the agent (prefixes only, never raw keys).
POST
/v1/agents/:agentId/api-keys
Create a key. Body: { name? }. The full raw_key is shown once only.
DEL
/v1/agents/:agentId/api-keys/:keyId
Revoke a key. Cannot be used after revocation.

Files

Per‑agent encrypted object storage.

GET
/v1/agents/:agentId/files
List files in the agent's storage.
POST
/v1/agents/:agentId/files
Upload a file (multipart/form-data).

Billing & Quota

Per‑agent quota, tenant‑wide billing summary, and a hosted checkout flow for upgrades.

GET
/v1/agents/:agentId/quota
Quota usage and tier for the agent.
GET
/v1/agents/:agentId/billing
Billing snapshot for the agent (alias of quota).
GET
/v1/billing/tenant-summary
Roll‑up across all agents owned by the user.
POST
/v1/billing/checkout
Start a hosted checkout session for tier upgrade.
Example — GET /v1/agents/:agentId/quota Response 200
{ "agent_id": "...", "email": "...", "tier": "free", "allowed": true, "remaining": 499 }

Ready to build?

Launch Dashboard