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
`knowledge:read`	List knowledge base entries
`knowledge:write`	Ingest and delete knowledge base entries
`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 scoped to the peer (or API key if no peerId).
`peerId`	string	optional	Unique identifier for the end user (e.g. your customer account ID). Isolates sessions and memory per peer so conversations with different customers never leak data. Highly recommended when multiple customers share the same agent.
`context`	string \| object	optional	Customer or session metadata to pass to the agent. Accepts a plain string or a key-value object (e.g. {"name": "Alice", "plan": "Pro"}). The agent sees this as conversation context and can use it to personalize responses. Max 2000 characters after formatting. Useful for chat widgets, customer support bots, and embedded experiences.

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

Knowledge

POST/v1/knowledge/ingest

Embeds and stores text chunks in the knowledge base. Chunks are deduplicated by cosine similarity (threshold 0.95). If an agent belongs to a swarm, entries are stored at the swarm level automatically.

Scope:knowledge:write

Body Parameters

Name	Type	Required	Description
`swarmId`	string	optional	Target swarm UUID. Provide either swarmId or agentId.
`agentId`	string	optional	Target agent UUID. If the agent belongs to a swarm, entries are stored at the swarm level.
`chunks`	array	required	Array of text chunks to ingest (max 100).
`chunks[].text`	string	required	Chunk text content (max 4000 characters).
`chunks[].source`	string	required	Source identifier (e.g. filename).
`chunks[].metadata`	object	optional	Optional key-value metadata (e.g. { "type": "faq" }).

JSON

{
  "data": {
    "stored": 2,
    "skipped": 0,
    "total": 2
  }
}

GET/v1/knowledge

Returns knowledge base entries with pagination. Filter by source to see entries from a specific file.

Scope:knowledge:read

Query Parameters

Name	Type	Required	Description
`swarmId`	string	optional	Target swarm UUID. Provide either swarmId or agentId.
`agentId`	string	optional	Target agent UUID. If the agent belongs to a swarm, listing resolves to swarm-scoped KB entries.
`source`	string	optional	Filter by source identifier.
`limit`	number	optional	Max entries to return (default 50, max 100).
`offset`	string	optional	Pagination cursor from a previous response.

JSON

{
  "data": [
    {
      "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "text": "Agento is a managed hosting platform for AI agents.",
      "source": "docs/intro.md",
      "type": "article",
      "createdAt": "2026-03-04T12:00:00.000Z",
      "updatedAt": "2026-03-04T12:00:00.000Z"
    }
  ],
  "pagination": {
    "nextOffset": "a1b2c3d4-e5f6-7890-abcd-ef1234567891",
    "hasMore": true
  }
}

DELETE/v1/knowledge

Deletes knowledge base entries by source, individual ID, or all entries. Deleting all entries requires explicit confirmation.

Scope:knowledge:write

Query Parameters

Name	Type	Required	Description
`swarmId`	string	optional	Target swarm UUID. Provide either swarmId or agentId.
`agentId`	string	optional	Target agent UUID. If the agent belongs to a swarm, deletion resolves to swarm-scoped KB entries.
`source`	string	optional	Delete all entries from this source.
`id`	string	optional	Delete a single entry by UUID.
`all`	string	optional	Set to "true" to delete all entries (requires confirm=true).
`confirm`	string	optional	Set to "true" to confirm bulk deletion.

JSON

{
  "data": {
    "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
`knowledge:read`	List knowledge base entries
`knowledge:write`	Ingest and delete knowledge base entries
`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 scoped to the peer (or API key if no peerId).
`peerId`	string	optional	Unique identifier for the end user (e.g. your customer account ID). Isolates sessions and memory per peer so conversations with different customers never leak data. Highly recommended when multiple customers share the same agent.
`context`	string \| object	optional	Customer or session metadata to pass to the agent. Accepts a plain string or a key-value object (e.g. {"name": "Alice", "plan": "Pro"}). The agent sees this as conversation context and can use it to personalize responses. Max 2000 characters after formatting. Useful for chat widgets, customer support bots, and embedded experiences.

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

Knowledge

POST/v1/knowledge/ingest

Scope:knowledge:write

Body Parameters

Name	Type	Required	Description
`swarmId`	string	optional	Target swarm UUID. Provide either swarmId or agentId.
`agentId`	string	optional	Target agent UUID. If the agent belongs to a swarm, entries are stored at the swarm level.
`chunks`	array	required	Array of text chunks to ingest (max 100).
`chunks[].text`	string	required	Chunk text content (max 4000 characters).
`chunks[].source`	string	required	Source identifier (e.g. filename).
`chunks[].metadata`	object	optional	Optional key-value metadata (e.g. { "type": "faq" }).

JSON

{
  "data": {
    "stored": 2,
    "skipped": 0,
    "total": 2
  }
}

GET/v1/knowledge

Returns knowledge base entries with pagination. Filter by source to see entries from a specific file.

Scope:knowledge:read

Query Parameters

Name	Type	Required	Description
`swarmId`	string	optional	Target swarm UUID. Provide either swarmId or agentId.
`agentId`	string	optional	Target agent UUID. If the agent belongs to a swarm, listing resolves to swarm-scoped KB entries.
`source`	string	optional	Filter by source identifier.
`limit`	number	optional	Max entries to return (default 50, max 100).
`offset`	string	optional	Pagination cursor from a previous response.

JSON

{
  "data": [
    {
      "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "text": "Agento is a managed hosting platform for AI agents.",
      "source": "docs/intro.md",
      "type": "article",
      "createdAt": "2026-03-04T12:00:00.000Z",
      "updatedAt": "2026-03-04T12:00:00.000Z"
    }
  ],
  "pagination": {
    "nextOffset": "a1b2c3d4-e5f6-7890-abcd-ef1234567891",
    "hasMore": true
  }
}

DELETE/v1/knowledge

Deletes knowledge base entries by source, individual ID, or all entries. Deleting all entries requires explicit confirmation.

Scope:knowledge:write

Query Parameters

Name	Type	Required	Description
`swarmId`	string	optional	Target swarm UUID. Provide either swarmId or agentId.
`agentId`	string	optional	Target agent UUID. If the agent belongs to a swarm, deletion resolves to swarm-scoped KB entries.
`source`	string	optional	Delete all entries from this source.
`id`	string	optional	Delete a single entry by UUID.
`all`	string	optional	Set to "true" to delete all entries (requires confirm=true).
`confirm`	string	optional	Set to "true" to confirm bulk deletion.

JSON

{
  "data": {
    "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
  }
}