API Reference

Integrate OpenClaw with your applications using our REST API.

Base URL

http://localhost:3000/api/v1

Authentication

All API requests require authentication using a Bearer token:

Authorization: Bearer your-api-token

Generate an API token in your configuration:

api:
  enabled: true
  tokens:
    - name: "my-app"
      token: "your-secure-token"
      permissions: ["chat", "sessions"]

Endpoints

POST /chat

Send a message and receive a response.

Request

POST /api/v1/chat
Content-Type: application/json

{
  "message": "What's the weather like today?",
  "sessionKey": "optional-session-id",
  "stream": false
}

Response

{
  "id": "msg_123456",
  "content": "I'd be happy to check the weather for you...",
  "sessionKey": "session_abc123",
  "model": "claude-sonnet-4-20250514",
  "usage": {
    "inputTokens": 15,
    "outputTokens": 142
  },
  "createdAt": "2026-02-08T10:30:00Z"
}

POST /chat/stream

Stream a response using Server-Sent Events.

POST /api/v1/chat/stream
Content-Type: application/json

{
  "message": "Write a short poem",
  "sessionKey": "session_abc123"
}

Response (SSE)

event: start
data: {"id": "msg_123"}

event: delta
data: {"content": "The "}

event: delta
data: {"content": "morning "}

event: delta
data: {"content": "sun..."}

event: done
data: {"usage": {"inputTokens": 10, "outputTokens": 45}}

GET /sessions

List all active sessions.

GET /api/v1/sessions

Response

{
  "sessions": [
    {
      "key": "session_abc123",
      "channel": "api",
      "createdAt": "2026-02-08T09:00:00Z",
      "lastActivity": "2026-02-08T10:30:00Z",
      "messageCount": 15
    }
  ]
}

GET /sessions/:key/history

Get message history for a session.

GET /api/v1/sessions/session_abc123/history?limit=50

Response

{
  "messages": [
    {
      "role": "user",
      "content": "Hello!",
      "timestamp": "2026-02-08T10:00:00Z"
    },
    {
      "role": "assistant",
      "content": "Hi there! How can I help?",
      "timestamp": "2026-02-08T10:00:01Z"
    }
  ]
}

DELETE /sessions/:key

Delete a session and its history.

DELETE /api/v1/sessions/session_abc123

GET /status

Get gateway status and health information.

GET /api/v1/status

Response

{
  "status": "healthy",
  "version": "2026.2.3",
  "uptime": 86400,
  "activeSessions": 5,
  "model": {
    "provider": "anthropic",
    "model": "claude-sonnet-4-20250514"
  }
}

Error Handling

All errors follow a consistent format:

{
  "error": {
    "code": "RATE_LIMITED",
    "message": "Too many requests. Please try again later.",
    "retryAfter": 60
  }
}

Error Codes

Code	HTTP Status	Description
UNAUTHORIZED	401	Invalid or missing API token
FORBIDDEN	403	Token lacks required permissions
NOT_FOUND	404	Resource not found
RATE_LIMITED	429	Too many requests
MODEL_ERROR	502	AI model returned an error

Rate Limits

Default rate limits per token:

• 100 requests per minute for /chat
• 1000 requests per minute for read endpoints

Rate limit headers are included in responses:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1707388800

SDKs

Official SDKs are available for popular languages:

# Node.js
npm install @openclaw/sdk

# Python
pip install openclaw

# Go
go get github.com/openclaw/openclaw-go

Node.js Example

import { OpenClaw } from '@openclaw/sdk';

const client = new OpenClaw({
  baseUrl: 'http://localhost:3000',
  apiKey: 'your-api-token'
});

const response = await client.chat({
  message: 'Hello, OpenClaw!'
});

console.log(response.content);