What format does the OpenClaw API use for requests and responses?

All OpenClaw API requests and responses use JSON. Request bodies must include Content-Type: application/json. Responses always return JSON with a consistent envelope: a data field for successful responses and an error field with a machine-readable code for failures.

Can I test the OpenClaw API without deploying to a server?

Yes. Run OpenClaw locally and hit http://localhost:8080/api/v1/ with any HTTP client — curl, Postman, Insomnia, or HTTPie. The local gateway has full API functionality. Import the OpenAPI spec from /docs/api/openapi.yaml into Postman for a pre-built collection of all endpoints.

Does OpenClaw have an OpenAPI / Swagger spec?

Yes. OpenClaw ships an openapi.yaml file in the repository. Import it into Postman or any OpenAPI-compatible tool for auto-generated documentation, interactive testing, and client SDK generation in your language of choice.

What HTTP status codes does the OpenClaw API return?

The API follows standard HTTP conventions: 200 for success, 201 for resource creation, 400 for malformed requests, 401 for missing or invalid tokens, 404 for missing resources, 409 for conflicts (e.g. duplicate channel ID), 429 for rate limit exceeded, and 500 for server errors. Always handle non-200 codes with specific error logic — do not catch all errors generically.

OpenClaw API Documentation: Master It in 5 Minutes

Q: Where is the official OpenClaw API documentation?

OpenClaw's official API docs live on GitHub in the openclaw/openclaw repository under /docs/api/. They cover all REST endpoints, WebSocket events, and authentication patterns. Community-maintained guides on aiagentsguides.com provide annotated examples and integration walkthroughs beyond what the official docs cover.

Q: How do I get an API token for OpenClaw?

Your API token is the gateway secret you define in gateway.yaml. There is no separate token generation step — the same secret used to authenticate agent connections to the gateway is used to authenticate API calls. Rotate it by updating gateway.yaml and restarting the gateway.

Key Takeaways

The OpenClaw API docs live at /docs/api/ in the GitHub repository — start there for the authoritative reference
An openapi.yaml file ships with every OpenClaw release — import it into Postman for instant interactive testing
Authentication uses a single Bearer token (your gateway secret) — no OAuth flows, no separate API key management
Every response follows a consistent JSON envelope: data on success, error with a machine-readable code on failure
The /health endpoint requires no authentication — use it for uptime monitoring and load balancer health checks

Developers who skip the API docs and build directly against example code from forums hit the same three walls: wrong auth headers, missing Content-Type, and no idea what the error codes mean. Five minutes with the actual documentation avoids all of it. Here's the structure and the fastest paths to useful information.

How the OpenClaw API Documentation Is Organized

The official OpenClaw API documentation is maintained in the repository at openclaw/openclaw on GitHub under the /docs/api/ directory. It's organized into four sections that you'll return to repeatedly:

Authentication — covers token generation, header format, and token rotation
REST Endpoints — every endpoint with request/response schemas and example payloads
WebSocket Events — real-time event subscriptions for live agent monitoring
Error Reference — all error codes with causes and recommended fixes

The single most useful file in the docs is openapi.yaml. It's the machine-readable spec for every endpoint. Import it into any OpenAPI-compatible tool — Postman, Insomnia, Swagger UI — and you get interactive testing with auto-populated request formats immediately.

As of early 2025, the docs are actively maintained with each minor release. If you're pinning to a specific OpenClaw version, check the corresponding git tag for the docs that match — endpoint behavior can change between minor versions.

Authentication Reference

Every API request (except /health) requires an Authorization header with your gateway token as a Bearer token. There is no separate API key — the gateway token defined in your gateway.yaml is the single credential for both agent connections and API access.

# Correct auth header format
Authorization: Bearer your-gateway-token-here

# Full curl example
curl -H "Authorization: Bearer your-gateway-token" \
     -H "Content-Type: application/json" \
     https://your-domain.com/api/v1/channels

⚠️

One Token Rules Everything

The gateway token is a master key. It grants full access to all agents, all channels, all memory keys, and all webhooks in your deployment. Store it in a secret manager. Never log it. Never include it in client-side code or public repositories.

For multi-tenant deployments where different clients need different access levels, the recommended pattern is to run separate gateway instances — one per tenant — each with its own token. OpenClaw does not yet support scoped API tokens within a single gateway deployment as of early 2025.

Endpoint Index and Request Formats

The REST API has eleven core endpoints across four resource types. Here's the complete index with the request format for each.

Resource	Endpoints	Key Fields
Channels	GET /channels, GET /channels/{id}	id, status, last_seen, agent_name
Messages	POST /messages, GET /messages/{channel_id}	channel_id, message, metadata
Memory	GET /memory/{key}, POST /memory/{key}, DELETE /memory/{key}	key, value, ttl
Webhooks	POST /webhooks, GET /webhooks, DELETE /webhooks/{id}	url, events, channel_id, secret
Health	GET /health	status, version, uptime

Every request body must use Content-Type: application/json. Requests that include a body without this header return a 400 with the error code INVALID_CONTENT_TYPE. This is the most common mistake new API users make — include the header on every POST.

💡

Start With /health

Always hit /health first when debugging connectivity issues. It requires no auth and returns the gateway version, uptime, and status. If /health returns a 200, the problem is your auth token or request format — not the gateway itself.

Using the OpenAPI Spec

The openapi.yaml file in the repo is the fastest path to a working API client. Import it into Postman using File → Import → select the yaml file. Postman generates a full collection with every endpoint pre-configured — you only need to set your base URL and auth token as collection variables.

# Download the spec from the official repo
curl -o openapi.yaml \
  https://raw.githubusercontent.com/openclaw/openclaw/main/docs/api/openapi.yaml

# Or use Swagger UI locally
docker run -p 8081:8080 \
  -e SWAGGER_JSON=/spec/openapi.yaml \
  -v $(pwd):/spec \
  swaggerapi/swagger-ui

The OpenAPI spec also enables client SDK generation via OpenAPI Generator. If your backend is Python, TypeScript, Go, or Java, run openapi-generator-cli generate against the spec to get a typed client library that matches the exact API surface. This is faster and safer than hand-writing HTTP calls.

HTTP Status Codes Reference

The API follows standard HTTP semantics consistently. Here's what each status code means in the OpenClaw context:

200 OK — Request succeeded. Response body contains the data field.
201 Created — Resource created (webhook registered, memory key written). Includes the new resource in the response.
400 Bad Request — Malformed request body, missing required fields, or invalid field types. Check the error.details field for the specific violation.
401 Unauthorized — Missing or invalid Authorization header. The token is wrong or the header format is incorrect.
404 Not Found — The requested channel ID, memory key, or webhook ID does not exist.
409 Conflict — Duplicate resource — most commonly a channel ID that's already registered.
429 Too Many Requests — Rate limit exceeded. Check the Retry-After header for the reset window.
500 Internal Server Error — Gateway-side error. Check gateway logs for the root cause. Usually indicates a misconfiguration or a downstream LLM API failure.

Every error response includes an error object with a machine-readable code string and a human-readable message. Log the code — not just the HTTP status — so your error handling can distinguish between different 400 subtypes.

Common API Documentation Mistakes

Reading the docs for the wrong version — OpenClaw's API surface changes between minor versions. Always check the docs for the specific version you're running. The GitHub release page lists doc changes in every release changelog.
Ignoring the error.code field — A 400 status from /api/v1/messages could mean five different things. The error.code field tells you which one. Build error handling around specific codes, not HTTP status ranges.
Not setting Content-Type on POST requests — Every POST request needs Content-Type: application/json. Missing this header is the #1 cause of unexplained 400 errors for API newcomers.
Building against example code instead of the spec — Community examples go stale. The openapi.yaml is always authoritative. When examples conflict with the spec, trust the spec.
Not handling 429 responses — If you hit a rate limit and retry immediately, you compound the problem. Implement exponential backoff with jitter on 429 responses.

Frequently Asked Questions

Where is the official OpenClaw API documentation?

The official docs live in the openclaw/openclaw repository on GitHub under /docs/api/. They cover all REST endpoints, WebSocket events, and authentication patterns. Community guides like this one provide annotated examples and integration walkthroughs beyond the official reference.

What format does the OpenClaw API use?

All requests and responses use JSON. POST requests must include Content-Type: application/json. Responses always return a JSON envelope with a data field on success and an error field with a machine-readable code on failure.

How do I get an API token?

Your API token is the gateway secret defined in gateway.yaml — there's no separate token generation step. The same secret used to authenticate agent connections also authenticates API calls. Rotate it by updating gateway.yaml and restarting the gateway.

Can I test the API without a server?

Yes. Run OpenClaw locally and call http://localhost:8080/api/v1/ with any HTTP client. The local gateway has full API functionality. Import the openapi.yaml spec into Postman for a pre-built collection of all endpoints with auto-generated request formats.

Does OpenClaw have an OpenAPI spec?

Yes. OpenClaw ships an openapi.yaml in the repository. Import it into Postman, Insomnia, or Swagger UI for interactive testing and auto-generated documentation. Use openapi-generator-cli to generate typed client SDKs in your language of choice.

What HTTP status codes does the API return?

Standard HTTP codes: 200 for success, 201 for resource creation, 400 for bad requests, 401 for auth failures, 404 for missing resources, 409 for conflicts, 429 for rate limit exceeded, and 500 for server errors. Always check the error.code field for the machine-readable subtype.

J. Donovan

Technical Writer

J. Donovan specializes in API documentation and developer experience for AI tooling. Has reviewed and contributed to OpenClaw's official API docs, and has integrated OpenClaw with ten external platforms via the REST API including Zapier, n8n, and custom Python backends.