REST API Reference — OpenClaw Developer

Authentication

All API requests require an API key passed in the X-API-Key header. Generate API keys with the CLI:

openclaw api-key create --name "my-app" --expires 90d
# Output: oc_live_abc123xyz...

curl -X POST https://your-openclaw/v1/tasks   -H "X-API-Key: oc_live_abc123xyz"   -H "Content-Type: application/json"   -d '{"prompt": "Summarize the top 5 GitHub issues in openclaw-ai/openclaw"}'

Tasks API

POST /v1/tasks — Create Task

Creates and queues an agent task for execution. Returns a task ID for polling.

// Request body
{
  "prompt": "Research the top 5 cloud providers for AI workloads",
  "agent": "default",          // agent configuration to use (optional)
  "tools": ["web_search"],     // override enabled tools (optional)
  "model": "gpt-4o-mini",      // override LLM model (optional)
  "max_tokens": 2000,          // budget limit (optional)
  "output_format": "markdown"  // json | markdown | text (optional)
}

// Response 202 Accepted
{
  "task_id": "task_abc123",
  "status": "queued",
  "created_at": "2024-01-15T10:30:00Z",
  "estimated_duration_seconds": 45
}

GET /v1/tasks/{task_id} — Get Task Status

// Response when complete (status: "completed")
{
  "task_id": "task_abc123",
  "status": "completed",
  "created_at": "2024-01-15T10:30:00Z",
  "completed_at": "2024-01-15T10:30:52Z",
  "duration_seconds": 52,
  "output": "# Cloud Provider Comparison for AI Workloads

...",
  "tokens_used": 1847,
  "tool_calls": 6,
  "cost_usd": 0.0042
}

GET /v1/tasks — List Tasks

Lists recent tasks with optional filtering:

GET /v1/tasks?status=completed&limit=20&since=2024-01-01T00:00:00Z

Streaming API

For tasks that need real-time output streaming (long-running research, code generation), use the streaming endpoint which returns Server-Sent Events:

curl -N -H "X-API-Key: oc_live_..."   -H "Accept: text/event-stream"   https://your-openclaw/v1/tasks/stream   -d '{"prompt": "Write a detailed guide to Kubernetes networking"}'

event: progress
data: {"step": "web_search", "status": "running"}

event: progress
data: {"step": "web_search", "status": "complete", "results_found": 8}

event: output
data: {"token": "# Kubernetes"}

event: output
data: {"token": " Networking"}

event: complete
data: {"tokens_used": 3421, "duration_seconds": 67}

Error Codes

HTTP Status	Error code	Meaning
400	`INVALID_REQUEST`	Request body is malformed or missing required fields
401	`UNAUTHORIZED`	Missing or invalid API key
402	`BUDGET_EXCEEDED`	Task would exceed configured token or cost budget
422	`VALIDATION_ERROR`	Request body fails schema validation
429	`RATE_LIMITED`	Too many requests; respect Retry-After header
503	`LLM_UNAVAILABLE`	Configured LLM provider is unreachable

Pipeline API

POST /v1/pipelines — Run a Pipeline

Runs a multi-agent pipeline defined in a YAML document passed in the request body:

// Request body
{
  "pipeline_yaml": "pipeline:\n  - id: research\n    ...",
  "input": {"topic": "kubernetes networking"},
  "dry_run": false   // if true, validate pipeline only without running
}

// Response 202 — same format as Tasks API
{"task_id": "task_pipeline_abc123", "status": "queued"}

GET /v1/pipelines/{task_id}/stages — Stage Status

// Response
{
  "task_id": "task_pipeline_abc123",
  "stages": [
    {"id": "research", "status": "completed", "duration_seconds": 18, "output_length": 2341},
    {"id": "analyze",  "status": "running",   "duration_seconds": null},
    {"id": "write",    "status": "pending",   "duration_seconds": null}
  ]
}

Health and Metrics Endpoints

# Health check (returns 200 if healthy, 503 if degraded)
GET /health
# Response: {"status": "ok", "version": "0.9.2", "llm_provider": "openai", "llm_status": "ok"}

# Prometheus metrics
GET /metrics
# Returns: openclaw_tasks_total, openclaw_task_duration_seconds, openclaw_llm_requests_total, etc.

# OpenAPI spec (machine-readable)
GET /openapi.json

The /health endpoint is the recommended liveness and readiness probe target for Kubernetes deployments. It checks connectivity to the configured LLM provider and returns 503 if the provider is unreachable or if the API key is invalid — ensuring the pod is removed from load balancing when it can't actually serve requests.

Rate Limits and Best Practices

The default rate limit for the API is 100 requests per minute per API key. Tasks that are still running count against your concurrent task limit (default: 10 concurrent tasks per API key). If you exceed rate limits, the API returns HTTP 429 with a Retry-After header specifying how many seconds to wait.

For high-volume use cases, configure the queue-based submission pattern: submit tasks to the queue endpoint, store task IDs, and poll for completion rather than using synchronous blocking requests. This decouples submission rate from processing capacity and naturally handles backpressure from the task queue.

Python SDK Examples

The openclaw Python package provides a higher-level client that wraps the REST API:

from openclaw import Agent

# Single synchronous task
agent = Agent(api_key="sk-openclaw-...")
result = agent.run("Summarize the top 5 HN stories from today")
print(result.output)

# Async task with streaming
import asyncio
from openclaw import AsyncAgent

async def main():
    agent = AsyncAgent(api_key="sk-openclaw-...")
    async for chunk in agent.stream("Write a Python HTTP server"):
        print(chunk, end="", flush=True)

asyncio.run(main())

# Pipeline execution
from openclaw import Pipeline
pipeline = Pipeline.from_file("research_pipeline.yaml", api_key="sk-openclaw-...")
result = pipeline.run(topic="quantum error correction")
print(result.stages["write"]["output"])

The SDK handles authentication, retries (with exponential backoff), timeout management, and response deserialization. It is available on PyPI as pip install openclaw. The SDK version should match the server version for all features to work correctly — use openclaw.__version__ and /health's version field to verify compatibility.

Webhook Callbacks

Instead of polling for task completion, register a webhook URL that OpenClaw will call when a task finishes:

// Include in POST /v1/tasks request body
{
  "task": "Analyze this CSV and return summary statistics",
  "webhook_url": "https://your-service.example.com/openclaw-callback",
  "webhook_secret": "your-hmac-secret"
}

// Callback payload sent to your webhook URL
{
  "task_id": "task_abc123",
  "status": "completed",
  "output": "...",
  "completed_at": "2024-10-01T14:30:00Z"
}

The webhook request includes an X-OpenClaw-Signature header containing an HMAC-SHA256 signature of the request body using your webhook_secret. Always verify this signature before processing the callback to prevent spoofed callbacks from untrusted sources.

API Versioning

The REST API uses URL versioning (/v1/). When breaking changes are introduced, a new version prefix (/v2/) is published alongside the old one, with a minimum 6-month support window for the old version before it is retired. Non-breaking additions (new optional fields, new endpoints) are added to the current version without incrementing it. Monitor the changelog for deprecation notices affecting endpoints you depend on.