Agents API

Create, manage, and interact with agents.

List agents

GET /api/agents

Returns all agents owned by the authenticated user. When no session is present, returns an empty list instead of a 401 error.

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"
}

Create agent

The POST /api/agents endpoint is deprecated. Use POST /api/agents/provision to create agents.

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

Update agent

PUT /api/agents/:id is deprecated. Use PUT /api/agents/:id/config to update agent configuration.

Delete agent

DELETE /api/agents/:id is deprecated. Use the lifecycle endpoints to manage agent state (for example, POST /api/instance/:userId/stop).

Provision agent

POST /api/agents/provision

Provisions a new agent. Requires an active subscription unless the caller is an admin.

Provisioning requests may be processed asynchronously through the background task queue. The agent is created immediately with a provisioning status and transitions to running once the gateway confirms the deployment. If gateway provisioning fails, the status changes to error.

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 hint. Options: `starter`, `pro`, `enterprise`

The agent limit is determined by the subscription plan on the authenticated user’s account (starter: 1, pro: 3, enterprise: 100). It cannot be overridden in the request body.

Admin bypass

Admin users (configured via ADMIN_EMAILS) are exempt from the following restrictions:

Subscription requirement — admins can provision agents without an active subscription (the 402 error is not returned).
Agent limit — admins receive an elevated agent slot limit instead of the plan-based cap.

Response (201 Created)

{
  "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 plan. Response includes `current` (agent count) and `limit` fields. Limits: `starter` 1, `pro` 3, `enterprise` 100. Users without a recognized plan default to a limit of 1.
500	Failed to provision agent

List provisioned agents

GET /api/agents/provision

Requires session authentication.

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
}

Errors

Code	Description
401	Unauthorized
500	Failed to list agents

Get agent configuration

GET /api/agents/:id/config

Returns the configuration for an agent. Requires authentication and ownership.

Response

{
  "config": {
    "model": "claude-opus-4-6",
    "channels": ["telegram"],
    "skills": []
  },
  "status": "ok"
}

Errors

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

Update agent configuration

PUT /api/agents/:id/config

Updates the configuration for an agent. Requires authentication and ownership. The request body is forwarded to the backend configuration service.

Request body

Pass the configuration fields you want to update. The exact fields depend on the backend configuration schema.

Response

{
  "config": {
    "model": "claude-opus-4-6",
    "channels": ["telegram", "discord"],
    "skills": ["browser"]
  },
  "status": "updated"
}

Errors

Code	Description
404	Agent not found or not owned by user
500	Failed to update agent configuration

Get agent logs

GET /api/agents/:id/logs

Returns activity logs for an agent. Requires authentication and ownership.

Query parameters

Parameter	Type	Default	Description
`limit`	number	`50`	Maximum number of log entries to return (capped at 100)
`level`	string	—	Filter by log level. Options: `info`, `warning`, `error`, `debug`. Returns all levels when omitted.

Response

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

Errors

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

Get agent messages

GET /api/agents/:id/messages

Returns messages exchanged with an agent. Requires authentication and ownership.

Query parameters

Parameter	Type	Default	Description
`limit`	number	`50`	Maximum number of messages to return (capped at 100)
`offset`	number	`0`	Number of messages to skip for pagination

Response

{
  "messages": [
    {
      "id": "msg-0",
      "agentId": "agent_123",
      "sender": "user",
      "content": "User message 1",
      "timestamp": "2026-03-19T12:00:00Z",
      "platform": "telegram"
    },
    {
      "id": "msg-1",
      "agentId": "agent_123",
      "sender": "agent",
      "content": "Agent response to message 0",
      "timestamp": "2026-03-19T11:59:00Z",
      "platform": "discord"
    }
  ],
  "total": 50,
  "limit": 50,
  "offset": 0,
  "status": "ok"
}

Errors

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

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": "active"
}

The backend returns "active" as the status value. The Next.js proxy layer may normalize this to "running" in some deployments.

Stop agent

POST /api/instance/:userId/stop

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

Restart agent

POST /api/instance/:userId/restart

{
  "success": true,
  "status": "active",
  "healedLegacyModel": false,
  "healMessage": null,
  "openclawVersion": "2026.3.13"
}

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
403	Forbidden — authenticated user does not own this agent instance
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/verification

{
  "verified": false,
  "verificationType": null,
  "attestationUid": null,
  "verifierAddress": null,
  "verifiedAt": 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
`walletAddress`	string	Conditional	Wallet address of the verifier. Required for `ens` verification.
`signature`	string	Conditional	Cryptographic signature. Required for `coinbase`, `ens`, and `webauthn` 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. Each type has specific requirements: `eas` requires `attestationUid`; `coinbase` and `webauthn` require `signature`; `ens` requires both `signature` and `walletAddress`.
401	Unauthorized
500	Failed to process verification

Remove verification

DELETE /api/agents/:id/verify

{
  "success": true
}

Provision with channel tokens

POST /api/provision

Provisions a new agent with messaging channel tokens. No authentication is required. Rate-limited per IP. At least one channel token is required. The request is proxied to the backend provisioning service. A dedicated Mux live stream is automatically created for the agent. The backend may enqueue the provisioning job to the provision queue for asynchronous processing.

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.
`discordBotToken`	string	Conditional	Discord bot token. At least one channel token is required.
`aiProvider`	string	No	AI provider (default: `openrouter`). Options: `openrouter`, `gemini`, `groq`, `anthropic`, `openai`
`apiKey`	string	No	API key for the AI provider
`plan`	string	No	Plan tier (default: `free`). Options: `free`, `pro`, `enterprise`

The following request fields are deprecated and no longer accepted: whatsappPhoneNumberId, whatsappBusinessAccountId, discordGuildId, discordChannelId.

Response

The response includes the following fields. Additional fields may be present depending on the backend configuration.

{
  "success": true,
  "userId": "a1b2c3d4e5",
  "agentId": "agent_789",
  "subdomain": "dj-a1b2c3d4e5.agentbot.raveculture.xyz",
  "url": "https://dj-a1b2c3d4e5.agentbot.raveculture.xyz",
  "streamKey": "sk-ab12-cd34-ef56",
  "liveStreamId": "x7k9m2p4q1",
  "aiProvider": "openrouter",
  "plan": "free",
  "playbackUrl": "https://stream.mux.com/playback_id.m3u8",
  "status": "active",
  "createdAt": "2026-03-19T00:00:00Z"
}

The Next.js proxy at /api/provision filters the response to a subset of fields (success, userId, subdomain, url, streamKey, liveStreamId). The full response is available when calling the backend provisioning service directly.

Errors

Code	Description
400	At least one channel token required (Telegram, WhatsApp, or Discord)
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

{
  "message": "Hello!",
  "topic": "general"
}

Response

{
  "id": "msg_123",
  "message": "Hello!",
  "topic": "general",
  "status": "sent",
  "timestamp": "2026-03-19T00:00:00Z",
  "reply": "Hi! How can I help?"
}

Errors

Code	Description
400	Message required
401	Unauthorized
500	Failed to send message

List messages

GET /api/chat

Returns the message history. Requires session authentication.

Response

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

Errors

Code	Description
401	Unauthorized

Getting Started

Core Concepts

Integrations

Core Services

Payments

API Reference

MCP

Security

​Agents API

​List agents

​Response

​Create agent

​Get agent

​Response

​Errors

​Update agent

​Delete agent

​Provision agent

​Request body

​Admin bypass

​Response (201 Created)

​Errors

​List provisioned agents

​Response

​Errors

​Get agent configuration

​Response

​Errors

​Update agent configuration

​Request body

​Response

​Errors

​Get agent logs

​Query parameters

​Response

​Errors

​Get agent messages

​Query parameters

​Response

​Errors

​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

Agents API

List agents

Response

Create agent

Get agent

Response

Errors

Update agent

Delete agent

Provision agent

Request body

Admin bypass

Response (201 Created)

Errors

List provisioned agents

Response

Errors

Get agent configuration

Response

Errors

Update agent configuration

Request body

Response

Errors

Get agent logs

Query parameters

Response

Errors

Get agent messages

Query parameters

Response

Errors

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

Errors

List messages