API Reference

Manage agents, send chat messages, stream logs, and install skills from any language. Authenticate with an X-Api-Key header.

Authentication

All API requests require an X-Api-Key header. Create API keys from the dashboard.

Example

curl https://api.agento.host/v1/agents \
  -H "X-Api-Key: ak_live_a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4"

Base URL

https://api.agento.host

Scopes

Each API key is created with one or more scopes that control which endpoints it can access.

Scope	Access
`agents:read`	List, get, and check status of agents
`agents:write`	Create, update, delete, start, stop, restart agents + manage secrets and personality
`chat`	Send messages, read history, manage sessions
`logs`	Read and stream agent logs
`skills`	Install, uninstall, and browse skills
`swarms:read`	List and view swarms
`swarms:write`	Create, update, and delete swarms

Rate Limits

120 requests per minute per API key (sliding window). Rate limit headers are included in every response:

Header	Description
`X-RateLimit-Limit`	Max requests per window (120)
`X-RateLimit-Remaining`	Requests remaining in current window
`X-RateLimit-Reset`	Unix timestamp when the window resets
`Retry-After`	Seconds to wait (only on 429 responses)

Error Format

All errors return a consistent JSON envelope:

Error response

{
  "error": {
    "code": "unauthorized",
    "message": "Invalid or missing API key"
  }
}

Agents

GET/v1/agents

Returns all agents in your account, ordered by creation date (newest first). Deleted agents are excluded.

Scope:agents:read

JSON

{
  "data": [
    {
      "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "name": "My Assistant",
      "status": "running",
      "region": "eu",
      "image": "openclaw/openclaw:latest",
      "swarm": null,
      "createdAt": "2026-01-15T10:30:00.000Z",
      "startedAt": "2026-01-15T10:31:00.000Z",
      "stoppedAt": null
    }
  ],
  "pagination": {
    "total": 1,
    "limit": 1,
    "offset": 0
  }
}

POST/v1/agents

Creates a new agent, provisions a container on an available server, and starts it. Requires at least one LLM API key in secrets.

Scope:agents:write

Body Parameters

Name	Type	Required	Description
`name`	string	required	Agent display name (1-100 characters).
`region`	string	optional	"us" or "eu". Defaults to "eu".
`secrets`	object	required	LLM credentials. At least one of anthropicApiKey, openaiApiKey, or googleApiKey is required.
`secrets.anthropicApiKey`	string	optional	Anthropic API key (starts with sk-ant-).
`secrets.openaiApiKey`	string	optional	OpenAI API key.
`secrets.googleApiKey`	string	optional	Google Gemini API key.
`secrets.telegramBotToken`	string	optional	Telegram BotFather token.
`secrets.slackBotToken`	string	optional	Slack bot token (xoxb-).
`secrets.slackAppToken`	string	optional	Slack app-level token (xapp-).
`config`	object	optional	Agent configuration (channels, personality style, etc.).
`soulMd`	string	optional	Initial SOUL.md content for agent personality.
`workflowMd`	string	optional	Initial WORKFLOW.md content defining the agent's role and procedures.
`swarmId`	string	optional	Swarm UUID to assign the agent to.

JSON

{
  "data": {
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "name": "My Assistant",
    "status": "running",
    "region": "eu",
    "createdAt": "2026-02-10T14:00:00.000Z",
    "startedAt": "2026-02-10T14:00:05.000Z"
  }
}

GET/v1/agents/:id

Returns full details for a single agent, including config, error state, and restart status.

Scope:agents:read

Path Parameters

Name	Type	Required	Description
`id`	string	required	Agent UUID.

JSON

{
  "data": {
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "name": "My Assistant",
    "status": "running",
    "region": "eu",
    "image": "openclaw/openclaw:latest",
    "avatarUrl": null,
    "config": {
      "llmProvider": "anthropic",
      "authType": "api_key"
    },
    "workflowMd": "# Workflow\n\n## Role\n\nDescribe your agent's role here.",
    "swarm": null,
    "createdAt": "2026-01-15T10:30:00.000Z",
    "startedAt": "2026-01-15T10:31:00.000Z",
    "stoppedAt": null,
    "lastError": null,
    "errorCategory": null,
    "needsRestart": false
  }
}

PATCH/v1/agents/:id

Updates agent name, avatar, or config. Changes that affect the running container set needsRestart to true.

Scope:agents:write

Path Parameters

Name	Type	Required	Description
`id`	string	required	Agent UUID.

Body Parameters

Name	Type	Required	Description
`name`	string	optional	New display name.
`avatarUrl`	string \| null	optional	Avatar image URL, or null to remove.
`config`	object	optional	Config fields to merge into existing config.
`swarmId`	string \| null	optional	Swarm UUID to assign to, or null to unassign.

JSON

{
  "data": {
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "name": "Updated Assistant",
    "status": "running",
    "needsRestart": true
  }
}

DELETE/v1/agents/:id

Stops the agent container, removes all data and secrets, and marks the agent as deleted. This action is irreversible.

Scope:agents:write

Path Parameters

Name	Type	Required	Description
`id`	string	required	Agent UUID.

JSON

{
  "data": {
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "deleted": true
  }
}

POST/v1/agents/:id/start

Starts a stopped agent. Creates or resumes the Docker container and updates status to "running".

Scope:agents:write

Path Parameters

Name	Type	Required	Description
`id`	string	required	Agent UUID.

JSON

{
  "data": {
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "status": "running",
    "startedAt": "2026-02-10T14:00:05.000Z"
  }
}

POST/v1/agents/:id/stop

Stops a running agent. The container is stopped and workspace files are synced back to storage.

Scope:agents:write

Path Parameters

Name	Type	Required	Description
`id`	string	required	Agent UUID.

JSON

{
  "data": {
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "status": "stopped",
    "stoppedAt": "2026-02-10T15:00:00.000Z"
  }
}

POST/v1/agents/:id/restart

Removes the existing container and creates a fresh one with the latest configuration, secrets, and skills.

Scope:agents:write

Path Parameters

Name	Type	Required	Description
`id`	string	required	Agent UUID.

JSON

{
  "data": {
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "status": "running",
    "startedAt": "2026-02-10T14:05:00.000Z"
  }
}

GET/v1/agents/:id/status

Returns real-time status from Redis (if fresh) or falls back to an SSH check. Includes container resource usage when available.

Scope:agents:read

Path Parameters

Name	Type	Required	Description
`id`	string	required	Agent UUID.

JSON

{
  "data": {
    "status": "running",
    "containerStatus": "running",
    "live": true,
    "resources": {
      "memoryUsage": "128MiB / 512MiB",
      "cpuPercent": "2.35%"
    },
    "source": "redis"
  }
}

Chat

POST/v1/agents/:id/chat/messagesSSE

Sends a message to the agent and returns the response as a Server-Sent Events (SSE) stream. The connection stays open until the agent finishes responding.

Scope:chat

Path Parameters

Name	Type	Required	Description
`id`	string	required	Agent UUID.

Body Parameters

Name	Type	Required	Description
`message`	string	required	The message to send to the agent.
`sessionId`	string	optional	Chat session ID. If omitted, uses a default session per API key.

text/event-stream

data: {"type":"text","content":"I can help you with"}
data: {"type":"text","content":" a wide range of tasks!"}
data: {"type":"done"}

GET/v1/agents/:id/chat/messages

Returns chat message history for the agent. Retrieves messages from the container session file.

Scope:chat

Path Parameters

Name	Type	Required	Description
`id`	string	required	Agent UUID.

Query Parameters

Name	Type	Required	Description
`sessionId`	string	optional	Filter by session ID.
`limit`	number	optional	Max messages to return (default 50, max 200).
`since`	string	optional	ISO 8601 timestamp. Only return messages after this time.

JSON

{
  "data": [
    {
      "role": "user",
      "content": "Hello!",
      "timestamp": "2026-02-10T14:00:00.000Z"
    },
    {
      "role": "assistant",
      "content": "Hi! How can I help you?",
      "timestamp": "2026-02-10T14:00:02.000Z"
    }
  ],
  "pagination": {
    "total": 2,
    "limit": 50,
    "offset": 0
  }
}

GET/v1/agents/:id/chat/sessions

Returns the most recent chat sessions for the agent (up to 100), ordered by start time.

Scope:chat

Path Parameters

Name	Type	Required	Description
`id`	string	required	Agent UUID.

JSON

{
  "data": [
    {
      "id": "sess_abc123",
      "name": null,
      "channel": "api",
      "startedAt": "2026-02-10T14:00:00.000Z"
    }
  ],
  "pagination": {
    "total": 1,
    "limit": 100,
    "offset": 0
  }
}

POST/v1/agents/:id/chat/sessions

Creates a new chat session, resetting the conversation context. Sends a /new command to the running agent.

Scope:chat

Path Parameters

Name	Type	Required	Description
`id`	string	required	Agent UUID.

JSON

{
  "data": {
    "id": "sess_def456",
    "startedAt": "2026-02-10T15:00:00.000Z"
  }
}

Logs

GET/v1/agents/:id/logs

Returns the most recent container logs for the agent. Useful for debugging startup issues or monitoring output.

Scope:logs

Path Parameters

Name	Type	Required	Description
`id`	string	required	Agent UUID.

Query Parameters

Name	Type	Required	Description
`tail`	number	optional	Number of lines to return (default 100).

JSON

{
  "data": {
    "logs": "2026-02-10T14:00:05Z [info] Agent started successfully\n2026-02-10T14:00:06Z [info] Connected to Anthropic API\n"
  }
}

GET/v1/agents/:id/logs/streamSSE

Streams container logs in real-time via Server-Sent Events. The connection stays open and new log lines are pushed as they appear.

Scope:logs

Path Parameters

Name	Type	Required	Description
`id`	string	required	Agent UUID.

Query Parameters

Name	Type	Required	Description
`tail`	string	optional	Number of historical lines to include (default 200).

text/event-stream

data: 2026-02-10T14:00:05Z [info] Agent started
data: 2026-02-10T14:00:06Z [info] Processing message...

Skills

GET/v1/agents/:id/skills

Returns all skills installed on the agent, including version and trust level.

Scope:skills

Path Parameters

Name	Type	Required	Description
`id`	string	required	Agent UUID.

JSON

{
  "data": [
    {
      "id": "as_abc123",
      "skillId": "web-search",
      "name": "Web Search",
      "installedVersion": "1.2.0",
      "trustLevel": "verified",
      "isEnabled": true,
      "installedAt": "2026-02-08T12:00:00.000Z"
    }
  ],
  "pagination": {
    "total": 1,
    "limit": 1,
    "offset": 0
  }
}

POST/v1/agents/:id/skills

Installs a skill on the agent. The agent may need a restart for the skill to take effect.

Scope:skills

Path Parameters

Name	Type	Required	Description
`id`	string	required	Agent UUID.

Body Parameters

Name	Type	Required	Description
`skillId`	string	required	Skill identifier (e.g. "web-search").
`trustLevel`	string	required	"verified" for curated skills, "clawhub" for community skills.

JSON

{
  "data": {
    "id": "as_abc123",
    "skillId": "web-search",
    "name": "Web Search",
    "installedVersion": "1.2.0",
    "trustLevel": "verified",
    "isEnabled": true,
    "needsRestart": true
  }
}

DELETE/v1/agents/:id/skills/:skillId

Removes a skill from the agent. The agent may need a restart for the change to take effect.

Scope:skills

Path Parameters

Name	Type	Required	Description
`id`	string	required	Agent UUID.
`skillId`	string	required	Skill identifier.

JSON

{
  "data": {
    "skillId": "web-search",
    "uninstalled": true,
    "needsRestart": true
  }
}

GET/v1/skills

Search and browse the verified skills marketplace. Supports text search, category filtering, and pagination.

Scope:skills

Query Parameters

Name	Type	Required	Description
`search`	string	optional	Search query (matches name and description).
`category`	string	optional	Filter by category.
`page`	number	optional	Page number (default 1).
`pageSize`	number	optional	Results per page (default 20, max 100).

JSON

{
  "data": [
    {
      "id": "web-search",
      "name": "Web Search",
      "description": "Search the web for real-time information.",
      "author": "agento",
      "category": "productivity",
      "installCount": 1250,
      "latestVersion": "1.2.0",
      "securityScore": 95
    }
  ],
  "pagination": {
    "total": 42,
    "limit": 20,
    "offset": 0
  }
}

GET/v1/skills/:id

Returns detailed information about a skill, including use cases, tool count, and security score.

Scope:skills

Path Parameters

Name	Type	Required	Description
`id`	string	required	Skill identifier.

JSON

{
  "data": {
    "id": "web-search",
    "name": "Web Search",
    "description": "Search the web for real-time information.",
    "enhancedDescription": "A powerful web search skill that allows your agent to find current information...",
    "author": "agento",
    "category": "productivity",
    "tags": [
      "search",
      "web",
      "research"
    ],
    "installCount": 1250,
    "latestVersion": "1.2.0",
    "securityScore": 95,
    "useCases": [
      "Research questions",
      "Fact-checking"
    ],
    "toolCount": 3
  }
}

Swarms

GET/v1/swarms

Returns all swarms in your account with agent and member counts.

Scope:swarms:read

JSON

{
  "data": [
    {
      "id": "s1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "name": "Growth",
      "slug": "growth",
      "description": "Agents focused on growth initiatives.",
      "icon": null,
      "agentCount": 3,
      "memberCount": 2,
      "createdAt": "2026-02-01T10:00:00.000Z",
      "updatedAt": "2026-02-15T12:00:00.000Z"
    }
  ]
}

POST/v1/swarms

Creates a new swarm. A unique slug is generated from the name. Requires the swarms feature on your plan.

Scope:swarms:write

Body Parameters

Name	Type	Required	Description
`name`	string	required	Swarm name (1-100 characters).
`description`	string	optional	Short description of the swarm.
`icon`	string	optional	Emoji or icon string.

JSON

{
  "data": {
    "id": "s1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "name": "Growth",
    "slug": "growth",
    "description": "Agents focused on growth initiatives.",
    "icon": null,
    "agentCount": 0,
    "memberCount": 0,
    "createdAt": "2026-02-19T10:00:00.000Z",
    "updatedAt": "2026-02-19T10:00:00.000Z"
  }
}

GET/v1/swarms/:id

Returns swarm details including the list of agents assigned to it.

Scope:swarms:read

Path Parameters

Name	Type	Required	Description
`id`	string	required	Swarm UUID.

JSON

{
  "data": {
    "id": "s1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "name": "Growth",
    "slug": "growth",
    "description": "Agents focused on growth initiatives.",
    "icon": null,
    "agentCount": 1,
    "memberCount": 2,
    "agents": [
      {
        "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
        "name": "My Assistant",
        "status": "running",
        "createdAt": "2026-01-15T10:30:00.000Z"
      }
    ],
    "createdAt": "2026-02-01T10:00:00.000Z",
    "updatedAt": "2026-02-15T12:00:00.000Z"
  }
}

PATCH/v1/swarms/:id

Updates swarm name, description, or icon.

Scope:swarms:write

Path Parameters

Name	Type	Required	Description
`id`	string	required	Swarm UUID.

Body Parameters

Name	Type	Required	Description
`name`	string	optional	New swarm name (1-100 characters).
`description`	string \| null	optional	New description, or null to clear.
`icon`	string \| null	optional	New icon, or null to clear.

JSON

{
  "data": {
    "id": "s1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "name": "Growth Team",
    "slug": "growth",
    "description": "All growth-related agents.",
    "icon": null,
    "agentCount": 3,
    "memberCount": 2,
    "createdAt": "2026-02-01T10:00:00.000Z",
    "updatedAt": "2026-02-19T14:00:00.000Z"
  }
}

DELETE/v1/swarms/:id

Deletes a swarm. Agents in the swarm are unassigned (not deleted). Provider credentials are removed from the vault.

Scope:swarms:write

Path Parameters

Name	Type	Required	Description
`id`	string	required	Swarm UUID.

JSON

{
  "data": {
    "id": "s1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "deleted": true
  }
}

Account

GET/v1/account

Returns your account details, plan information, and current usage. Any valid API key can access this endpoint.

JSON

{
  "data": {
    "id": "acct_abc123",
    "name": "My Company",
    "plan": {
      "id": "plan_pro",
      "name": "Pro",
      "status": "active",
      "limits": {
        "maxAgents": 10,
        "maxSkillsPerAgent": 20
      },
      "features": {
        "api_access": true
      }
    },
    "usage": {
      "agents": 3,
      "runningAgents": 2
    }
  }
}

PUT/v1/agents/:id/secrets

Sets or deletes agent secrets (API keys, tokens). This is a write-only operation. Secrets are stored encrypted in Supabase Vault.

Scope:agents:write

Path Parameters

Name	Type	Required	Description
`id`	string	required	Agent UUID.

Body Parameters

Name	Type	Required	Description
`secrets`	object	optional	Key-value pairs to set (e.g. { "anthropic_api_key": "sk-ant-..." }).
`deleteSecrets`	string[]	optional	List of secret keys to remove.

JSON

{
  "data": {
    "updated": true,
    "needsRestart": true
  }
}

GET/v1/agents/:id/personality

Returns the agent's SOUL.md and IDENTITY.md content, along with a hash for optimistic concurrency control.

Scope:agents:read

Path Parameters

Name	Type	Required	Description
`id`	string	required	Agent UUID.

JSON

{
  "data": {
    "soulMd": "# SOUL.md\n\nYou are a helpful assistant.",
    "identityMd": "# IDENTITY.md\n\n- **Name:** My Assistant",
    "soulMdHash": "a1b2c3d4e5f6...",
    "soulMdUpdatedAt": "2026-02-10T14:00:00.000Z"
  }
}

PUT/v1/agents/:id/personality

Updates the agent's SOUL.md content. Supports optimistic concurrency via expectedHash. Previous versions are automatically snapshotted.

Scope:agents:write

Path Parameters

Name	Type	Required	Description
`id`	string	required	Agent UUID.

Body Parameters

Name	Type	Required	Description
`soulMd`	string	required	New SOUL.md content.
`expectedHash`	string	optional	SHA-256 hash of the current content. If provided and mismatched, returns 409.

JSON

{
  "data": {
    "soulMd": "# SOUL.md\n\nYou are a professional customer support agent.",
    "soulMdHash": "f6e5d4c3b2a1...",
    "soulMdUpdatedAt": "2026-02-10T15:30:00.000Z",
    "needsRestart": true
  }
}

GET/v1/agents/:id/workflow

Returns the agent's WORKFLOW.md content and a list of rule files in the rules/ directory. Only available for running agents with a server assigned.

Scope:agents:read

Path Parameters

Name	Type	Required	Description
`id`	string	required	Agent UUID.

JSON

{
  "data": {
    "workflowMd": "# Workflow\n\n## Role\n\nCustomer support agent.",
    "rules": [
      "example-new-request.md"
    ]
  }
}

PUT/v1/agents/:id/workflow

Updates the agent's WORKFLOW.md content on disk. The agent needs a restart for changes to take effect in its context.

Scope:agents:write

Path Parameters

Name	Type	Required	Description
`id`	string	required	Agent UUID.

Body Parameters

Name	Type	Required	Description
`workflowMd`	string	required	New WORKFLOW.md content.

JSON

{
  "data": {
    "workflowMd": "# Workflow\n\n## Role\n\nCustomer support agent.\n\n## Daily Priorities\n\n1. Respond to tickets\n2. Follow up on open issues",
    "needsRestart": true
  }
}

GET/v1/agents/:id/rules

Returns all rule files in the agent's rules/ directory with their names and sizes in bytes. Rules are detailed procedures the agent reads on demand, referenced from WORKFLOW.md.

Scope:agents:read

Path Parameters

Name	Type	Required	Description
`id`	string	required	Agent UUID.

JSON

{
  "data": {
    "rules": [
      {
        "name": "example-new-request",
        "size": 512
      },
      {
        "name": "daily-review",
        "size": 1024
      }
    ]
  }
}

GET/v1/agents/:id/rules/:name

Returns the content of a single rule file. The :name parameter is the rule name without the .md extension.

Scope:agents:read

Path Parameters

Name	Type	Required	Description
`id`	string	required	Agent UUID.
`name`	string	required	Rule name without .md extension (e.g. "new-request").

JSON

{
  "data": {
    "name": "example-new-request",
    "content": "# Handle New Requests\n\nWhen a user sends a new request:\n\n1. Acknowledge receipt\n2. Categorize the request\n3. Draft a response"
  }
}

PUT/v1/agents/:id/rules/:name

Creates a new rule or replaces an existing one. The :name parameter becomes the filename (with .md appended). Running agents are flagged for restart.

Scope:agents:write

Path Parameters

Name	Type	Required	Description
`id`	string	required	Agent UUID.
`name`	string	required	Rule name without .md extension. Alphanumeric, hyphens, and underscores only.

Body Parameters

Name	Type	Required	Description
`content`	string	required	Markdown content for the rule file.

JSON

{
  "data": {
    "name": "new-request",
    "needsRestart": true
  }
}

DELETE/v1/agents/:id/rules/:name

Deletes a rule file from the agent's rules/ directory. Running agents are flagged for restart.

Scope:agents:write

Path Parameters

Name	Type	Required	Description
`id`	string	required	Agent UUID.
`name`	string	required	Rule name without .md extension.

JSON

{
  "data": {
    "name": "old-rule",
    "deleted": true,
    "needsRestart": true
  }
}

API Reference

Manage agents, send chat messages, stream logs, and install skills from any language. Authenticate with an X-Api-Key header.

Authentication

All API requests require an X-Api-Key header. Create API keys from the dashboard.

Example

curl https://api.agento.host/v1/agents \
  -H "X-Api-Key: ak_live_a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4"

Base URL

https://api.agento.host

Scopes

Each API key is created with one or more scopes that control which endpoints it can access.

Scope	Access
`agents:read`	List, get, and check status of agents
`agents:write`	Create, update, delete, start, stop, restart agents + manage secrets and personality
`chat`	Send messages, read history, manage sessions
`logs`	Read and stream agent logs
`skills`	Install, uninstall, and browse skills
`swarms:read`	List and view swarms
`swarms:write`	Create, update, and delete swarms

Rate Limits

120 requests per minute per API key (sliding window). Rate limit headers are included in every response:

Header	Description
`X-RateLimit-Limit`	Max requests per window (120)
`X-RateLimit-Remaining`	Requests remaining in current window
`X-RateLimit-Reset`	Unix timestamp when the window resets
`Retry-After`	Seconds to wait (only on 429 responses)

Error Format

All errors return a consistent JSON envelope:

Error response

{
  "error": {
    "code": "unauthorized",
    "message": "Invalid or missing API key"
  }
}

Agents

GET/v1/agents

Returns all agents in your account, ordered by creation date (newest first). Deleted agents are excluded.

Scope:agents:read

JSON

{
  "data": [
    {
      "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "name": "My Assistant",
      "status": "running",
      "region": "eu",
      "image": "openclaw/openclaw:latest",
      "swarm": null,
      "createdAt": "2026-01-15T10:30:00.000Z",
      "startedAt": "2026-01-15T10:31:00.000Z",
      "stoppedAt": null
    }
  ],
  "pagination": {
    "total": 1,
    "limit": 1,
    "offset": 0
  }
}

POST/v1/agents

Creates a new agent, provisions a container on an available server, and starts it. Requires at least one LLM API key in secrets.

Scope:agents:write

Body Parameters

Name	Type	Required	Description
`name`	string	required	Agent display name (1-100 characters).
`region`	string	optional	"us" or "eu". Defaults to "eu".
`secrets`	object	required	LLM credentials. At least one of anthropicApiKey, openaiApiKey, or googleApiKey is required.
`secrets.anthropicApiKey`	string	optional	Anthropic API key (starts with sk-ant-).
`secrets.openaiApiKey`	string	optional	OpenAI API key.
`secrets.googleApiKey`	string	optional	Google Gemini API key.
`secrets.telegramBotToken`	string	optional	Telegram BotFather token.
`secrets.slackBotToken`	string	optional	Slack bot token (xoxb-).
`secrets.slackAppToken`	string	optional	Slack app-level token (xapp-).
`config`	object	optional	Agent configuration (channels, personality style, etc.).
`soulMd`	string	optional	Initial SOUL.md content for agent personality.
`workflowMd`	string	optional	Initial WORKFLOW.md content defining the agent's role and procedures.
`swarmId`	string	optional	Swarm UUID to assign the agent to.

JSON

{
  "data": {
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "name": "My Assistant",
    "status": "running",
    "region": "eu",
    "createdAt": "2026-02-10T14:00:00.000Z",
    "startedAt": "2026-02-10T14:00:05.000Z"
  }
}

GET/v1/agents/:id

Returns full details for a single agent, including config, error state, and restart status.

Scope:agents:read

Path Parameters

Name	Type	Required	Description
`id`	string	required	Agent UUID.

JSON

{
  "data": {
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "name": "My Assistant",
    "status": "running",
    "region": "eu",
    "image": "openclaw/openclaw:latest",
    "avatarUrl": null,
    "config": {
      "llmProvider": "anthropic",
      "authType": "api_key"
    },
    "workflowMd": "# Workflow\n\n## Role\n\nDescribe your agent's role here.",
    "swarm": null,
    "createdAt": "2026-01-15T10:30:00.000Z",
    "startedAt": "2026-01-15T10:31:00.000Z",
    "stoppedAt": null,
    "lastError": null,
    "errorCategory": null,
    "needsRestart": false
  }
}

PATCH/v1/agents/:id

Updates agent name, avatar, or config. Changes that affect the running container set needsRestart to true.

Scope:agents:write

Path Parameters

Name	Type	Required	Description
`id`	string	required	Agent UUID.

Body Parameters

Name	Type	Required	Description
`name`	string	optional	New display name.
`avatarUrl`	string \| null	optional	Avatar image URL, or null to remove.
`config`	object	optional	Config fields to merge into existing config.
`swarmId`	string \| null	optional	Swarm UUID to assign to, or null to unassign.

JSON

{
  "data": {
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "name": "Updated Assistant",
    "status": "running",
    "needsRestart": true
  }
}

DELETE/v1/agents/:id

Stops the agent container, removes all data and secrets, and marks the agent as deleted. This action is irreversible.

Scope:agents:write

Path Parameters

Name	Type	Required	Description
`id`	string	required	Agent UUID.

JSON

{
  "data": {
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "deleted": true
  }
}

POST/v1/agents/:id/start

Starts a stopped agent. Creates or resumes the Docker container and updates status to "running".

Scope:agents:write

Path Parameters

Name	Type	Required	Description
`id`	string	required	Agent UUID.

JSON

{
  "data": {
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "status": "running",
    "startedAt": "2026-02-10T14:00:05.000Z"
  }
}

POST/v1/agents/:id/stop

Stops a running agent. The container is stopped and workspace files are synced back to storage.

Scope:agents:write

Path Parameters

Name	Type	Required	Description
`id`	string	required	Agent UUID.

JSON

{
  "data": {
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "status": "stopped",
    "stoppedAt": "2026-02-10T15:00:00.000Z"
  }
}

POST/v1/agents/:id/restart

Removes the existing container and creates a fresh one with the latest configuration, secrets, and skills.

Scope:agents:write

Path Parameters

Name	Type	Required	Description
`id`	string	required	Agent UUID.

JSON

{
  "data": {
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "status": "running",
    "startedAt": "2026-02-10T14:05:00.000Z"
  }
}

GET/v1/agents/:id/status

Returns real-time status from Redis (if fresh) or falls back to an SSH check. Includes container resource usage when available.

Scope:agents:read

Path Parameters

Name	Type	Required	Description
`id`	string	required	Agent UUID.

JSON

{
  "data": {
    "status": "running",
    "containerStatus": "running",
    "live": true,
    "resources": {
      "memoryUsage": "128MiB / 512MiB",
      "cpuPercent": "2.35%"
    },
    "source": "redis"
  }
}

Chat

POST/v1/agents/:id/chat/messagesSSE

Sends a message to the agent and returns the response as a Server-Sent Events (SSE) stream. The connection stays open until the agent finishes responding.

Scope:chat

Path Parameters

Name	Type	Required	Description
`id`	string	required	Agent UUID.

Body Parameters

Name	Type	Required	Description
`message`	string	required	The message to send to the agent.
`sessionId`	string	optional	Chat session ID. If omitted, uses a default session per API key.

text/event-stream

data: {"type":"text","content":"I can help you with"}
data: {"type":"text","content":" a wide range of tasks!"}
data: {"type":"done"}

GET/v1/agents/:id/chat/messages

Returns chat message history for the agent. Retrieves messages from the container session file.

Scope:chat

Path Parameters

Name	Type	Required	Description
`id`	string	required	Agent UUID.

Query Parameters

Name	Type	Required	Description
`sessionId`	string	optional	Filter by session ID.
`limit`	number	optional	Max messages to return (default 50, max 200).
`since`	string	optional	ISO 8601 timestamp. Only return messages after this time.

JSON

{
  "data": [
    {
      "role": "user",
      "content": "Hello!",
      "timestamp": "2026-02-10T14:00:00.000Z"
    },
    {
      "role": "assistant",
      "content": "Hi! How can I help you?",
      "timestamp": "2026-02-10T14:00:02.000Z"
    }
  ],
  "pagination": {
    "total": 2,
    "limit": 50,
    "offset": 0
  }
}

GET/v1/agents/:id/chat/sessions

Returns the most recent chat sessions for the agent (up to 100), ordered by start time.

Scope:chat

Path Parameters

Name	Type	Required	Description
`id`	string	required	Agent UUID.

JSON

{
  "data": [
    {
      "id": "sess_abc123",
      "name": null,
      "channel": "api",
      "startedAt": "2026-02-10T14:00:00.000Z"
    }
  ],
  "pagination": {
    "total": 1,
    "limit": 100,
    "offset": 0
  }
}

POST/v1/agents/:id/chat/sessions

Creates a new chat session, resetting the conversation context. Sends a /new command to the running agent.

Scope:chat

Path Parameters

Name	Type	Required	Description
`id`	string	required	Agent UUID.

JSON

{
  "data": {
    "id": "sess_def456",
    "startedAt": "2026-02-10T15:00:00.000Z"
  }
}

Logs

GET/v1/agents/:id/logs

Returns the most recent container logs for the agent. Useful for debugging startup issues or monitoring output.

Scope:logs

Path Parameters

Name	Type	Required	Description
`id`	string	required	Agent UUID.

Query Parameters

Name	Type	Required	Description
`tail`	number	optional	Number of lines to return (default 100).

JSON

{
  "data": {
    "logs": "2026-02-10T14:00:05Z [info] Agent started successfully\n2026-02-10T14:00:06Z [info] Connected to Anthropic API\n"
  }
}

GET/v1/agents/:id/logs/streamSSE

Streams container logs in real-time via Server-Sent Events. The connection stays open and new log lines are pushed as they appear.

Scope:logs

Path Parameters

Name	Type	Required	Description
`id`	string	required	Agent UUID.

Query Parameters

Name	Type	Required	Description
`tail`	string	optional	Number of historical lines to include (default 200).

text/event-stream

data: 2026-02-10T14:00:05Z [info] Agent started
data: 2026-02-10T14:00:06Z [info] Processing message...

Skills

GET/v1/agents/:id/skills

Returns all skills installed on the agent, including version and trust level.

Scope:skills

Path Parameters

Name	Type	Required	Description
`id`	string	required	Agent UUID.

JSON

{
  "data": [
    {
      "id": "as_abc123",
      "skillId": "web-search",
      "name": "Web Search",
      "installedVersion": "1.2.0",
      "trustLevel": "verified",
      "isEnabled": true,
      "installedAt": "2026-02-08T12:00:00.000Z"
    }
  ],
  "pagination": {
    "total": 1,
    "limit": 1,
    "offset": 0
  }
}

POST/v1/agents/:id/skills

Installs a skill on the agent. The agent may need a restart for the skill to take effect.

Scope:skills

Path Parameters

Name	Type	Required	Description
`id`	string	required	Agent UUID.

Body Parameters

Name	Type	Required	Description
`skillId`	string	required	Skill identifier (e.g. "web-search").
`trustLevel`	string	required	"verified" for curated skills, "clawhub" for community skills.

JSON

{
  "data": {
    "id": "as_abc123",
    "skillId": "web-search",
    "name": "Web Search",
    "installedVersion": "1.2.0",
    "trustLevel": "verified",
    "isEnabled": true,
    "needsRestart": true
  }
}

DELETE/v1/agents/:id/skills/:skillId

Removes a skill from the agent. The agent may need a restart for the change to take effect.

Scope:skills

Path Parameters

Name	Type	Required	Description
`id`	string	required	Agent UUID.
`skillId`	string	required	Skill identifier.

JSON

{
  "data": {
    "skillId": "web-search",
    "uninstalled": true,
    "needsRestart": true
  }
}

GET/v1/skills

Search and browse the verified skills marketplace. Supports text search, category filtering, and pagination.

Scope:skills

Query Parameters

Name	Type	Required	Description
`search`	string	optional	Search query (matches name and description).
`category`	string	optional	Filter by category.
`page`	number	optional	Page number (default 1).
`pageSize`	number	optional	Results per page (default 20, max 100).

JSON

{
  "data": [
    {
      "id": "web-search",
      "name": "Web Search",
      "description": "Search the web for real-time information.",
      "author": "agento",
      "category": "productivity",
      "installCount": 1250,
      "latestVersion": "1.2.0",
      "securityScore": 95
    }
  ],
  "pagination": {
    "total": 42,
    "limit": 20,
    "offset": 0
  }
}

GET/v1/skills/:id

Returns detailed information about a skill, including use cases, tool count, and security score.

Scope:skills

Path Parameters

Name	Type	Required	Description
`id`	string	required	Skill identifier.

JSON

{
  "data": {
    "id": "web-search",
    "name": "Web Search",
    "description": "Search the web for real-time information.",
    "enhancedDescription": "A powerful web search skill that allows your agent to find current information...",
    "author": "agento",
    "category": "productivity",
    "tags": [
      "search",
      "web",
      "research"
    ],
    "installCount": 1250,
    "latestVersion": "1.2.0",
    "securityScore": 95,
    "useCases": [
      "Research questions",
      "Fact-checking"
    ],
    "toolCount": 3
  }
}

Swarms

GET/v1/swarms

Returns all swarms in your account with agent and member counts.

Scope:swarms:read

JSON

{
  "data": [
    {
      "id": "s1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "name": "Growth",
      "slug": "growth",
      "description": "Agents focused on growth initiatives.",
      "icon": null,
      "agentCount": 3,
      "memberCount": 2,
      "createdAt": "2026-02-01T10:00:00.000Z",
      "updatedAt": "2026-02-15T12:00:00.000Z"
    }
  ]
}

POST/v1/swarms

Creates a new swarm. A unique slug is generated from the name. Requires the swarms feature on your plan.

Scope:swarms:write

Body Parameters

Name	Type	Required	Description
`name`	string	required	Swarm name (1-100 characters).
`description`	string	optional	Short description of the swarm.
`icon`	string	optional	Emoji or icon string.

JSON

{
  "data": {
    "id": "s1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "name": "Growth",
    "slug": "growth",
    "description": "Agents focused on growth initiatives.",
    "icon": null,
    "agentCount": 0,
    "memberCount": 0,
    "createdAt": "2026-02-19T10:00:00.000Z",
    "updatedAt": "2026-02-19T10:00:00.000Z"
  }
}

GET/v1/swarms/:id

Returns swarm details including the list of agents assigned to it.

Scope:swarms:read

Path Parameters

Name	Type	Required	Description
`id`	string	required	Swarm UUID.

JSON

{
  "data": {
    "id": "s1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "name": "Growth",
    "slug": "growth",
    "description": "Agents focused on growth initiatives.",
    "icon": null,
    "agentCount": 1,
    "memberCount": 2,
    "agents": [
      {
        "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
        "name": "My Assistant",
        "status": "running",
        "createdAt": "2026-01-15T10:30:00.000Z"
      }
    ],
    "createdAt": "2026-02-01T10:00:00.000Z",
    "updatedAt": "2026-02-15T12:00:00.000Z"
  }
}

PATCH/v1/swarms/:id

Updates swarm name, description, or icon.

Scope:swarms:write

Path Parameters

Name	Type	Required	Description
`id`	string	required	Swarm UUID.

Body Parameters

Name	Type	Required	Description
`name`	string	optional	New swarm name (1-100 characters).
`description`	string \| null	optional	New description, or null to clear.
`icon`	string \| null	optional	New icon, or null to clear.

JSON

{
  "data": {
    "id": "s1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "name": "Growth Team",
    "slug": "growth",
    "description": "All growth-related agents.",
    "icon": null,
    "agentCount": 3,
    "memberCount": 2,
    "createdAt": "2026-02-01T10:00:00.000Z",
    "updatedAt": "2026-02-19T14:00:00.000Z"
  }
}

DELETE/v1/swarms/:id

Deletes a swarm. Agents in the swarm are unassigned (not deleted). Provider credentials are removed from the vault.

Scope:swarms:write

Path Parameters

Name	Type	Required	Description
`id`	string	required	Swarm UUID.

JSON

{
  "data": {
    "id": "s1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "deleted": true
  }
}

Account

GET/v1/account

Returns your account details, plan information, and current usage. Any valid API key can access this endpoint.

JSON

{
  "data": {
    "id": "acct_abc123",
    "name": "My Company",
    "plan": {
      "id": "plan_pro",
      "name": "Pro",
      "status": "active",
      "limits": {
        "maxAgents": 10,
        "maxSkillsPerAgent": 20
      },
      "features": {
        "api_access": true
      }
    },
    "usage": {
      "agents": 3,
      "runningAgents": 2
    }
  }
}

PUT/v1/agents/:id/secrets

Sets or deletes agent secrets (API keys, tokens). This is a write-only operation. Secrets are stored encrypted in Supabase Vault.

Scope:agents:write

Path Parameters

Name	Type	Required	Description
`id`	string	required	Agent UUID.

Body Parameters

Name	Type	Required	Description
`secrets`	object	optional	Key-value pairs to set (e.g. { "anthropic_api_key": "sk-ant-..." }).
`deleteSecrets`	string[]	optional	List of secret keys to remove.

JSON

{
  "data": {
    "updated": true,
    "needsRestart": true
  }
}

GET/v1/agents/:id/personality

Returns the agent's SOUL.md and IDENTITY.md content, along with a hash for optimistic concurrency control.

Scope:agents:read

Path Parameters

Name	Type	Required	Description
`id`	string	required	Agent UUID.

JSON

{
  "data": {
    "soulMd": "# SOUL.md\n\nYou are a helpful assistant.",
    "identityMd": "# IDENTITY.md\n\n- **Name:** My Assistant",
    "soulMdHash": "a1b2c3d4e5f6...",
    "soulMdUpdatedAt": "2026-02-10T14:00:00.000Z"
  }
}

PUT/v1/agents/:id/personality

Updates the agent's SOUL.md content. Supports optimistic concurrency via expectedHash. Previous versions are automatically snapshotted.

Scope:agents:write

Path Parameters

Name	Type	Required	Description
`id`	string	required	Agent UUID.

Body Parameters

Name	Type	Required	Description
`soulMd`	string	required	New SOUL.md content.
`expectedHash`	string	optional	SHA-256 hash of the current content. If provided and mismatched, returns 409.

JSON

{
  "data": {
    "soulMd": "# SOUL.md\n\nYou are a professional customer support agent.",
    "soulMdHash": "f6e5d4c3b2a1...",
    "soulMdUpdatedAt": "2026-02-10T15:30:00.000Z",
    "needsRestart": true
  }
}

GET/v1/agents/:id/workflow

Returns the agent's WORKFLOW.md content and a list of rule files in the rules/ directory. Only available for running agents with a server assigned.

Scope:agents:read

Path Parameters

Name	Type	Required	Description
`id`	string	required	Agent UUID.

JSON

{
  "data": {
    "workflowMd": "# Workflow\n\n## Role\n\nCustomer support agent.",
    "rules": [
      "example-new-request.md"
    ]
  }
}

PUT/v1/agents/:id/workflow

Updates the agent's WORKFLOW.md content on disk. The agent needs a restart for changes to take effect in its context.

Scope:agents:write

Path Parameters

Name	Type	Required	Description
`id`	string	required	Agent UUID.

Body Parameters

Name	Type	Required	Description
`workflowMd`	string	required	New WORKFLOW.md content.

JSON

{
  "data": {
    "workflowMd": "# Workflow\n\n## Role\n\nCustomer support agent.\n\n## Daily Priorities\n\n1. Respond to tickets\n2. Follow up on open issues",
    "needsRestart": true
  }
}

GET/v1/agents/:id/rules

Returns all rule files in the agent's rules/ directory with their names and sizes in bytes. Rules are detailed procedures the agent reads on demand, referenced from WORKFLOW.md.

Scope:agents:read

Path Parameters

Name	Type	Required	Description
`id`	string	required	Agent UUID.

JSON

{
  "data": {
    "rules": [
      {
        "name": "example-new-request",
        "size": 512
      },
      {
        "name": "daily-review",
        "size": 1024
      }
    ]
  }
}

GET/v1/agents/:id/rules/:name

Returns the content of a single rule file. The :name parameter is the rule name without the .md extension.

Scope:agents:read

Path Parameters

Name	Type	Required	Description
`id`	string	required	Agent UUID.
`name`	string	required	Rule name without .md extension (e.g. "new-request").

JSON

{
  "data": {
    "name": "example-new-request",
    "content": "# Handle New Requests\n\nWhen a user sends a new request:\n\n1. Acknowledge receipt\n2. Categorize the request\n3. Draft a response"
  }
}

PUT/v1/agents/:id/rules/:name

Creates a new rule or replaces an existing one. The :name parameter becomes the filename (with .md appended). Running agents are flagged for restart.

Scope:agents:write

Path Parameters

Name	Type	Required	Description
`id`	string	required	Agent UUID.
`name`	string	required	Rule name without .md extension. Alphanumeric, hyphens, and underscores only.

Body Parameters

Name	Type	Required	Description
`content`	string	required	Markdown content for the rule file.

JSON

{
  "data": {
    "name": "new-request",
    "needsRestart": true
  }
}

DELETE/v1/agents/:id/rules/:name

Deletes a rule file from the agent's rules/ directory. Running agents are flagged for restart.

Scope:agents:write

Path Parameters

Name	Type	Required	Description
`id`	string	required	Agent UUID.
`name`	string	required	Rule name without .md extension.

JSON

{
  "data": {
    "name": "old-rule",
    "deleted": true,
    "needsRestart": true
  }
}