Agents API

Create, manage, and interact with agents.

List agents

GET /api/agents

Returns all agents owned by the authenticated user.

Response

{
  "agents": [
    {
      "id": "agent_123",
      "name": "My Agent",
      "model": "claude-opus-4-6",
      "status": "running",
      "websocketUrl": "ws://openclaw-gateway:10000/agent/user_123",
      "createdAt": "2026-03-01T00:00:00Z",
      "updatedAt": "2026-03-18T00:00:00Z"
    }
  ],
  "count": 1,
  "status": "ok"
}

Get agent

GET /api/agents/:id

Requires authentication and ownership of the agent.

Response

{
  "agent": {
    "id": "agent_123",
    "status": "active",
    "startedAt": "2026-03-01T00:00:00Z",
    "plan": "starter",
    "subdomain": "agent_123.agents.localhost",
    "url": "https://agent_123.agents.localhost",
    "openclawVersion": "2026.3.13",
    "verified": false,
    "verificationType": null,
    "attestationUid": null,
    "verifiedAt": null
  },
  "status": "ok"
}

Errors

Code	Description
401	Unauthorized
404	Agent not found or not owned by user
500	Failed to fetch agent

Provision agent

POST /api/agents/provision

Provisions a new agent. Requires an active subscription.

Request body

Field	Type	Required	Description
`name`	string	Yes	Agent name
`model`	string	No	AI model (default: `claude-opus-4-6`). Options: `claude-opus-4-6`, `gpt-4`, `custom`
`config`	object	No	Agent configuration
`tier`	string	No	Subscription tier: `starter`, `pro`, `enterprise`

Response

{
  "success": true,
  "agent": {
    "id": "agent_789",
    "name": "My Agent",
    "status": "running",
    "websocketUrl": "ws://openclaw-gateway:10000/agent/user_123",
    "model": "claude-opus-4-6",
    "createdAt": "2026-03-19T00:00:00Z"
  }
}

Errors

Code	Description
400	Agent name is required
401	Unauthorized
402	Active subscription required to provision agents
429	Agent limit reached for your tier (`starter`: 1, `pro`: 3, `enterprise`: 100)
500	Failed to provision agent

List provisioned agents

GET /api/agents/provision

Response

{
  "success": true,
  "agents": [
    {
      "id": "agent_789",
      "name": "My Agent",
      "model": "claude-opus-4-6",
      "status": "running",
      "websocketUrl": "ws://openclaw-gateway:10000/agent/user_123",
      "createdAt": "2026-03-19T00:00:00Z",
      "updatedAt": "2026-03-19T00:00:00Z"
    }
  ],
  "count": 1
}

Get agent configuration

GET /api/agents/:id/config

Requires authentication and ownership.

Response

{
  "config": {},
  "status": "ok"
}

Update agent configuration

PUT /api/agents/:id/config

Request body

Arbitrary JSON configuration to apply.

Response

{
  "config": {},
  "status": "updated"
}

Get agent logs

This endpoint is not yet available. It is planned for a future release.

GET /api/agents/:id/logs

Query parameters

Parameter	Type	Default	Description
`limit`	integer	50	Max entries to return (max 100)
`level`	string	—	Filter by level: `info`, `warning`, `error`, `debug`

Response

{
  "logs": [
    {
      "id": "log-0",
      "timestamp": "2026-03-19T00:00:00Z",
      "level": "info",
      "message": "Agent activity log entry",
      "source": "agent",
      "agentId": "agent_123"
    }
  ],
  "total": 50,
  "limit": 50,
  "status": "ok"
}

Get agent messages

GET /api/agents/:id/messages

Query parameters

Parameter	Type	Default	Description
`limit`	integer	50	Max messages to return (max 100)
`offset`	integer	0	Offset for pagination

Response

{
  "messages": [
    {
      "id": "msg-0",
      "agentId": "agent_123",
      "sender": "user",
      "content": "Hello!",
      "timestamp": "2026-03-19T00:00:00Z",
      "platform": "telegram"
    }
  ],
  "total": 50,
  "limit": 50,
  "offset": 0,
  "status": "ok"
}

The sender field is either user or agent. The platform field indicates the messaging channel: telegram, discord, or whatsapp.

Get agent stats

GET /api/agents/:id/stats

Returns live container metrics when available, with a mock fallback.

Response (live)

{
  "stats": {
    "agentId": "agent_123",
    "cpu": "0.15%",
    "memory": "128MiB / 2GiB",
    "memoryPercent": "6.25%",
    "network": "1.2kB / 3.4kB",
    "uptime": 86400000,
    "uptimeFormatted": "1d 0h",
    "status": "running",
    "pids": "12",
    "messagesProcessed": "N/A",
    "messagesPerHour": "N/A",
    "averageResponseTime": "N/A",
    "successRate": "N/A",
    "errorRate": "N/A"
  },
  "status": "ok"
}

Response (mock fallback)

When the backend is unavailable, mock data is returned with "status": "mock":

{
  "stats": {
    "agentId": "agent_123",
    "messagesProcessed": 1234,
    "messagesPerHour": 456,
    "averageResponseTime": 789,
    "uptime": 12345,
    "successRate": "95.42",
    "errorRate": "4.58",
    "timestamp": "2026-03-19T00:00:00Z"
  },
  "status": "mock"
}

Agent lifecycle

Lifecycle operations use the /api/instance/:userId endpoint pattern. These endpoints require session authentication and proxy to the backend agent management service.

Start agent

POST /api/instance/:userId/start

{
  "success": true,
  "status": "running"
}

Stop agent

POST /api/instance/:userId/stop

{
  "success": true,
  "status": "stopped"
}

Restart agent

POST /api/instance/:userId/restart

{
  "success": true,
  "status": "running"
}

Update agent image

POST /api/instance/:userId/update

Triggers an image update on the backend.

{
  "success": true,
  "status": "running"
}

Repair agent

POST /api/instance/:userId/repair

Returns the backend response directly.

{
  "success": true,
  "message": "Agent repaired successfully"
}

Reset agent memory

POST /api/instance/:userId/reset-memory

Returns the backend response directly.

{
  "success": true,
  "message": "Memory reset successfully"
}

Lifecycle error responses

All lifecycle endpoints return the following shape on failure:

{
  "success": false,
  "status": "error"
}

Code	Description
502	Backend service unavailable
500	Internal server error

Get instance details

GET /api/instance/:userId

Returns the current status and metadata for an agent instance.

Response

{
  "userId": "user_123",
  "status": "running",
  "startedAt": "2026-03-01T00:00:00Z",
  "subdomain": "user_123.agents.localhost",
  "url": "https://user_123.agents.localhost",
  "plan": "free",
  "openclawVersion": "2026.2.17"
}

Get instance stats

GET /api/instance/:userId/stats

Returns resource usage statistics for an agent instance.

Response

{
  "userId": "user_123",
  "cpu": "0.15%",
  "memory": "128MiB",
  "status": "running",
  "plan": "starter",
  "openclawVersion": "2026.3.13"
}

Get agent gateway token

GET /api/instance/:userId/token

Returns an auto-generated gateway token for the agent. A new token is created if none exists.

{
  "token": "abc123def456"
}

Errors

Code	Description
502	Backend service unavailable
500	Failed to get token

Agent verification

Agents can be verified using multiple verification types: eas (Ethereum Attestation Service), coinbase, ens, or webauthn.

Get verification status

GET /api/agents/:id/verify

{
  "verified": false,
  "verificationType": null,
  "attestationUid": null,
  "verifierAddress": null,
  "verifiedAt": null,
  "metadata": null
}

Verify agent

POST /api/agents/:id/verify

Request body

Field	Type	Required	Description
`verificationType`	string	Yes	One of: `eas`, `coinbase`, `ens`, `webauthn`
`attestationUid`	string	For `eas`	Attestation UID from EAS
`signature`	string	For `coinbase`, `ens`, `webauthn`	Verification signature
`walletAddress`	string	For `ens`	Wallet address for ENS verification

Response

{
  "success": true,
  "verified": true,
  "verificationType": "eas",
  "attestationUid": "0x123...",
  "verifiedAt": "2026-03-19T00:00:00Z"
}

Errors

Code	Description
400	Invalid verification type or missing required fields
401	Unauthorized

Remove verification

DELETE /api/agents/:id/verify

{
  "success": true
}

Provision with channel tokens

POST /api/provision

Provisions a new agent with messaging channel tokens. Requires authentication. Rate-limited per IP. At least one channel token is required. A dedicated Mux live stream is automatically created for the agent.

Request body

Field	Type	Required	Description
`telegramToken`	string	Conditional	Telegram bot token. At least one channel token is required.
`telegramUserId`	string	No	Telegram user ID for owner binding
`whatsappToken`	string	Conditional	WhatsApp API token. At least one channel token is required.
`whatsappPhoneNumberId`	string	No	WhatsApp phone number ID
`whatsappBusinessAccountId`	string	No	WhatsApp Business Account ID
`discordBotToken`	string	Conditional	Discord bot token. At least one channel token is required.
`discordGuildId`	string	No	Discord guild (server) ID
`discordChannelId`	string	No	Discord channel ID
`aiProvider`	string	No	AI provider (default: `openrouter`)
`apiKey`	string	No	API key for the AI provider
`plan`	string	No	Plan tier (default: `free`)

Response

{
  "success": true,
  "userId": "a1b2c3d4e5f6g7h8",
  "agentId": "agent_789",
  "id": "a1b2c3d4e5f6g7h8",
  "aiProvider": "openrouter",
  "aiProviderConfig": {
    "model": "anthropic/claude-sonnet-4-20250514",
    "baseUrl": "https://openrouter.ai/api/v1",
    "requiresKey": true
  },
  "plan": "free",
  "streamKey": "live_abc123",
  "liveStreamId": "stream_456",
  "rtmpServer": "rtmps://global-live.mux.com:443/app",
  "playbackUrl": "https://stream.mux.com/abc123.m3u8",
  "subdomain": "a1b2c3d4e5f6g7h8.agents.localhost",
  "url": "https://a1b2c3d4e5f6g7h8.agents.localhost",
  "hls": {
    "playlistUrl": "https://stream.mux.com/abc123.m3u8"
  },
  "rtmp": {
    "server": "rtmps://global-live.mux.com:443/app",
    "key": "live_abc123"
  },
  "status": "active",
  "createdAt": "2026-03-19T00:00:00Z",
  "metadata": {
    "channels": {
      "telegram": true,
      "discord": false,
      "whatsapp": false
    },
    "streaming": {
      "provider": "mux",
      "lowLatency": true,
      "resolution": "1080p",
      "bitrate": "5000kbps"
    }
  }
}

Errors

Code	Description
400	At least one channel token required, invalid AI provider, or invalid plan
401	Unauthorized
429	Too many requests
500	Internal server error
502	Provisioning service unavailable or returned an error

Agent interaction

GET /api/agent
POST /api/agent

Unified endpoint for interacting with agents. All requests require session authentication. The userId is always bound to the authenticated session and cannot be overridden by the client.

GET actions

Pass the action query parameter to select the operation.

List endpoints

GET /api/agent

Returns available endpoints and version information when no action is specified.

{
  "apiVersion": "1.0.0",
  "agentbotVersion": "2026.3.1",
  "endpoints": {
    "GET /api/agent": "List endpoints",
    "GET /api/agent?action=health": "Health status",
    "GET /api/agent?action=sessions": "List sessions",
    "GET /api/agent?action=session&sessionId=xxx": "Get session details",
    "GET /api/agent?action=memory": "Get agent memory",
    "GET /api/agent?action=skills": "List available skills",
    "GET /api/agent?action=credentials": "List configured credentials",
    "POST /api/agent": "Send message to agent",
    "POST /api/agent?action=create-session": "Create new session",
    "POST /api/agent?action=update-skill": "Enable/disable skill"
  }
}

Health

GET /api/agent?action=health

{
  "status": "running",
  "version": "2026.3.1",
  "apiVersion": "1.0.0",
  "uptime": 86400,
  "model": "claude-sonnet-4-20250514",
  "channels": ["telegram"],
  "skills": [],
  "lastSeen": 1710806400000
}

List sessions

GET /api/agent?action=sessions

{
  "sessions": [
    {
      "id": "sess_abc123",
      "status": "active",
      "messageCount": 5,
      "createdAt": 1710806400000,
      "lastActivity": 1710810000000
    }
  ]
}

Get session

GET /api/agent?action=session&sessionId=sess_abc123

Returns the full session including messages.

Memory

GET /api/agent?action=memory

Returns the last 10 messages from the active session (truncated to 100 characters each).

{
  "memory": [
    { "role": "user", "content": "Hello, can you help me with..." },
    { "role": "assistant", "content": "Of course! Let me..." }
  ]
}

Skills

GET /api/agent?action=skills

Returns skills available on the agent instance.

Credentials

GET /api/agent?action=credentials

Returns which credentials are configured for the agent.

{
  "credentials": {
    "anthropic": false,
    "openai": false,
    "openrouter": true,
    "google": false,
    "telegram": true,
    "discord": false,
    "whatsapp": false
  }
}

POST actions

Pass the action field in the request body.

Chat

POST /api/agent

Field	Type	Required	Description
`action`	string	No	Set to `chat` or omit (default action)
`message`	string	Yes	Message to send to the agent
`sessionId`	string	No	Session ID to continue. A new session is created if omitted and no active session exists.

{
  "sessionId": "sess_abc123",
  "reply": "Agent is processing your request...",
  "timestamp": 1710810000000
}

Create session

Field	Type	Required	Description
`action`	string	Yes	`create-session`

{
  "sessionId": "sess_abc123",
  "status": "active"
}

Update skill

Field	Type	Required	Description
`action`	string	Yes	`update-skill`
`skillId`	string	Yes	Skill ID to enable or disable
`enabled`	boolean	Yes	Whether to enable or disable the skill

{
  "success": true,
  "skillId": "browser",
  "enabled": true
}

Set credential

Field	Type	Required	Description
`action`	string	Yes	`set-credential`
`key`	string	Yes	Credential key (for example, `anthropic`, `telegram`)
`value`	string	Yes	Credential value

{
  "success": true,
  "key": "anthropic",
  "configured": true
}

Errors

Code	Description
400	Invalid action or missing required fields
401	Unauthorized
404	Session not found
500	Internal error

Send message

POST /api/chat

Requires session authentication.

Request body

Field	Type	Required	Description
`message`	string	Yes	Message to send
`topic`	string	No	Conversation topic

Response

{
  "id": "msg_abc123",
  "message": "Hello!",
  "topic": "general",
  "status": "sent",
  "timestamp": "2026-03-19T00:00:00Z",
  "reply": "Message received by agent"
}

Get chat history

GET /api/chat

Requires session authentication.

{
  "messages": [],
  "count": 0
}

Errors

Code	Description
400	Message required
401	Unauthorized
500	Failed to send message or failed to fetch messages

Getting Started

Core Concepts

Integrations

Core Services

Payments

API Reference

MCP

Security

​Agents API

​List agents

​Response

​Get agent

​Response

​Errors

​Provision agent

​Request body

​Response

​Errors

​List provisioned agents

​Response

​Get agent configuration

​Response

​Update agent configuration

​Request body

​Response

​Get agent logs

​Query parameters

​Response

​Get agent messages

​Query parameters

​Response

​Get agent stats

​Response (live)

​Response (mock fallback)

​Agent lifecycle

​Start agent

​Stop agent

​Restart agent

​Update agent image

​Repair agent

​Reset agent memory

​Lifecycle error responses

​Get instance details

​Response

​Get instance stats

​Response

​Get agent gateway token

​Errors

​Agent verification

​Get verification status

​Verify agent

​Request body

​Response

​Errors

​Remove verification

​Provision with channel tokens

​Request body

​Response

​Errors

​Agent interaction

​GET actions

​List endpoints

​Health

​List sessions

​Get session

​Memory

​Skills

​Credentials

​POST actions

​Chat

​Create session

​Update skill

​Set credential

​Errors

​Send message

​Request body

​Response

​Get chat history

​Errors

Agents API

List agents

Response

Get agent

Response

Errors

Provision agent

Request body

Response

Errors

List provisioned agents

Response

Get agent configuration

Response

Update agent configuration

Request body

Response

Get agent logs

Query parameters

Response

Get agent messages

Query parameters

Response

Get agent stats

Response (live)

Response (mock fallback)

Agent lifecycle

Start agent

Stop agent

Restart agent

Update agent image

Repair agent

Reset agent memory

Lifecycle error responses

Get instance details

Response

Get instance stats

Response

Get agent gateway token

Errors

Agent verification

Get verification status

Verify agent

Request body

Response

Errors

Remove verification

Provision with channel tokens

Request body

Response

Errors

Agent interaction

GET actions

List endpoints

Health

List sessions

Get session

Memory

Skills

Credentials

POST actions

Chat

Create session

Update skill

Set credential

Errors

Send message

Request body

Response

Get chat history

Errors