{"openapi":"3.1.0","info":{"title":"Agento API","version":"1.0.0","description":"Public REST API for managing AI agents on Agento. Authenticate with an API key in the `X-Api-Key` header. Generate keys at https://agento.host/app/api-keys."},"components":{"securitySchemes":{"apiKey":{"type":"apiKey","in":"header","name":"X-Api-Key"}},"schemas":{}},"paths":{"/v1/agents":{"get":{"summary":"List agents","tags":["Agents"],"description":"Returns all agents in your account, ordered by creation date (newest first). Deleted agents are excluded.","security":[{"apiKey":[]}],"x-required-scopes":["agents:read"],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"status":{"type":"string"},"region":{"type":"string","nullable":true},"image":{"type":"string","nullable":true},"swarm":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"slug":{"type":"string"},"icon":{"type":"string","nullable":true}},"required":["id","name","slug","icon"],"additionalProperties":false,"nullable":true},"createdAt":{"type":"string","format":"date-time"},"startedAt":{"type":"string","format":"date-time","nullable":true},"stoppedAt":{"type":"string","format":"date-time","nullable":true}},"required":["id","name","status","region","image","swarm","createdAt","startedAt","stoppedAt"],"additionalProperties":false}},"pagination":{"type":"object","properties":{"total":{"type":"integer"},"limit":{"type":"integer"},"offset":{"type":"integer"}},"required":["total","limit","offset"],"additionalProperties":false}},"required":["data","pagination"],"additionalProperties":false,"example":{"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}}}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false,"example":{"error":{"code":"unauthorized","message":"Invalid or missing API key"}}}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false,"example":{"error":{"code":"forbidden","message":"API key missing required scope"}}}}}},"429":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false,"example":{"error":{"code":"rate_limit_exceeded","message":"Too many requests"}}}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false,"example":{"error":{"code":"internal_error","message":"An internal error occurred"}}}}}}}},"post":{"summary":"Create agent","tags":["Agents"],"description":"Creates a new agent, provisions a container on an available server, and starts it. Requires at least one LLM API key in secrets.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":100},"region":{"type":"string","enum":["us","eu"]},"secrets":{"type":"object","properties":{"anthropicApiKey":{"type":"string"},"openaiApiKey":{"type":"string"},"googleApiKey":{"type":"string"},"minimaxApiKey":{"type":"string"},"telegramBotToken":{"type":"string"},"slackBotToken":{"type":"string"},"slackAppToken":{"type":"string"}},"additionalProperties":false},"config":{"type":"object","additionalProperties":{}},"soulMd":{"type":"string"},"workflowMd":{"type":"string"},"swarmId":{"type":"string","format":"uuid"}},"required":["name","secrets"],"additionalProperties":false,"example":{"name":"My Assistant","region":"eu","secrets":{"anthropicApiKey":"sk-ant-api03-..."},"soulMd":"# SOUL.md\n\nYou are a helpful assistant.","workflowMd":"# Workflow\n\n## Role\n\nDescribe your agent's role here."}}}}},"security":[{"apiKey":[]}],"x-required-scopes":["agents:write"],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"status":{"type":"string"},"region":{"type":"string"},"createdAt":{"type":"string","format":"date-time"},"startedAt":{"type":"string","format":"date-time","nullable":true}},"required":["id","name","status","region","createdAt","startedAt"],"additionalProperties":false}},"required":["data"],"additionalProperties":false,"example":{"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"}}}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false,"example":{"error":{"code":"unauthorized","message":"Invalid or missing API key"}}}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false,"example":{"error":{"code":"forbidden","message":"API key missing required scope"}}}}}},"429":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false,"example":{"error":{"code":"rate_limit_exceeded","message":"Too many requests"}}}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false,"example":{"error":{"code":"internal_error","message":"An internal error occurred"}}}}}}}}},"/v1/agents/{id}":{"get":{"summary":"Get agent","tags":["Agents"],"description":"Returns full details for a single agent, including config, error state, and restart status.","parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"security":[{"apiKey":[]}],"x-required-scopes":["agents:read"],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"status":{"type":"string"},"region":{"type":"string","nullable":true},"image":{"type":"string","nullable":true},"avatarUrl":{"type":"string","nullable":true},"config":{"type":"object","additionalProperties":{},"nullable":true},"workflowMd":{"type":"string","nullable":true},"swarm":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"slug":{"type":"string"},"icon":{"type":"string","nullable":true}},"required":["id","name","slug","icon"],"additionalProperties":false,"nullable":true},"createdAt":{"type":"string","format":"date-time"},"startedAt":{"type":"string","format":"date-time","nullable":true},"stoppedAt":{"type":"string","format":"date-time","nullable":true},"lastError":{"type":"string","nullable":true},"errorCategory":{"type":"string","nullable":true},"needsRestart":{"type":"boolean"}},"required":["id","name","status","region","image","avatarUrl","config","workflowMd","swarm","createdAt","startedAt","stoppedAt","lastError","errorCategory","needsRestart"],"additionalProperties":false}},"required":["data"],"additionalProperties":false}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false,"example":{"error":{"code":"unauthorized","message":"Invalid or missing API key"}}}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false,"example":{"error":{"code":"forbidden","message":"API key missing required scope"}}}}}},"429":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false,"example":{"error":{"code":"rate_limit_exceeded","message":"Too many requests"}}}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false,"example":{"error":{"code":"internal_error","message":"An internal error occurred"}}}}}}}},"patch":{"summary":"Update agent","tags":["Agents"],"description":"Update an agent. Returns the updated record. Setting `needsRestart` may be required for changes to take effect.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":100},"avatarUrl":{"type":"string","format":"uri","nullable":true},"config":{"type":"object","additionalProperties":{}},"swarmId":{"type":"string","format":"uuid","nullable":true}},"additionalProperties":false,"example":{"name":"Renamed Assistant","config":{"personalityStyle":"concise"}}}}}},"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"security":[{"apiKey":[]}],"x-required-scopes":["agents:write"],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"status":{"type":"string"},"config":{"type":"object","additionalProperties":{},"nullable":true},"needsRestart":{"type":"boolean"},"swarm":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"slug":{"type":"string"},"icon":{"type":"string","nullable":true}},"required":["id","name","slug","icon"],"additionalProperties":false,"nullable":true},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","name","status","config","needsRestart","swarm","updatedAt"],"additionalProperties":false}},"required":["data"],"additionalProperties":false}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false,"example":{"error":{"code":"unauthorized","message":"Invalid or missing API key"}}}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false,"example":{"error":{"code":"forbidden","message":"API key missing required scope"}}}}}},"429":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false,"example":{"error":{"code":"rate_limit_exceeded","message":"Too many requests"}}}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false,"example":{"error":{"code":"internal_error","message":"An internal error occurred"}}}}}}}},"delete":{"summary":"Delete agent","tags":["Agents"],"description":"Stops the agent container, removes its data, and marks the agent as deleted. Irreversible.","parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"security":[{"apiKey":[]}],"x-required-scopes":["agents:write"],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"deleted":{"type":"boolean","enum":[true]}},"required":["id","deleted"],"additionalProperties":false}},"required":["data"],"additionalProperties":false,"example":{"data":{"id":"a1b2c3d4-e5f6-7890-abcd-ef1234567890","deleted":true}}}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false,"example":{"error":{"code":"unauthorized","message":"Invalid or missing API key"}}}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false,"example":{"error":{"code":"forbidden","message":"API key missing required scope"}}}}}},"429":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false,"example":{"error":{"code":"rate_limit_exceeded","message":"Too many requests"}}}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false,"example":{"error":{"code":"internal_error","message":"An internal error occurred"}}}}}}}}},"/v1/agents/{id}/start":{"post":{"summary":"Start agent","tags":["Agents"],"description":"Starts a stopped agent container, or recreates it if necessary.","parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"security":[{"apiKey":[]}],"x-required-scopes":["agents:write"],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"status":{"type":"string"},"startedAt":{"type":"string","format":"date-time","nullable":true}},"required":["id","status","startedAt"],"additionalProperties":false}},"required":["data"],"additionalProperties":false}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false,"example":{"error":{"code":"unauthorized","message":"Invalid or missing API key"}}}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false,"example":{"error":{"code":"forbidden","message":"API key missing required scope"}}}}}},"429":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false,"example":{"error":{"code":"rate_limit_exceeded","message":"Too many requests"}}}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false,"example":{"error":{"code":"internal_error","message":"An internal error occurred"}}}}}}}}},"/v1/agents/{id}/stop":{"post":{"summary":"Stop agent","tags":["Agents"],"description":"Stops a running agent container. Workspace is synced to storage.","parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"security":[{"apiKey":[]}],"x-required-scopes":["agents:write"],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"status":{"type":"string"},"stoppedAt":{"type":"string","format":"date-time","nullable":true}},"required":["id","status","stoppedAt"],"additionalProperties":false}},"required":["data"],"additionalProperties":false}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false,"example":{"error":{"code":"unauthorized","message":"Invalid or missing API key"}}}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false,"example":{"error":{"code":"forbidden","message":"API key missing required scope"}}}}}},"429":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false,"example":{"error":{"code":"rate_limit_exceeded","message":"Too many requests"}}}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false,"example":{"error":{"code":"internal_error","message":"An internal error occurred"}}}}}}}}},"/v1/agents/{id}/restart":{"post":{"summary":"Restart agent","tags":["Agents"],"description":"Removes the running container and starts it again with current secrets and config.","parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"security":[{"apiKey":[]}],"x-required-scopes":["agents:write"],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"status":{"type":"string"},"startedAt":{"type":"string","format":"date-time","nullable":true}},"required":["id","status","startedAt"],"additionalProperties":false}},"required":["data"],"additionalProperties":false}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false,"example":{"error":{"code":"unauthorized","message":"Invalid or missing API key"}}}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false,"example":{"error":{"code":"forbidden","message":"API key missing required scope"}}}}}},"429":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false,"example":{"error":{"code":"rate_limit_exceeded","message":"Too many requests"}}}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false,"example":{"error":{"code":"internal_error","message":"An internal error occurred"}}}}}}}}},"/v1/agents/{id}/status":{"get":{"summary":"Get live agent status","tags":["Agents"],"description":"Returns the current container status, prefering a recent Redis heartbeat and falling back to SSH inspection.","parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"security":[{"apiKey":[]}],"x-required-scopes":["agents:read"],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"status":{"type":"string"},"containerStatus":{"type":"string"},"live":{"type":"boolean"},"resources":{"type":"object","properties":{"memoryUsage":{"type":"string"},"cpuPercent":{"type":"string"}},"required":["memoryUsage","cpuPercent"],"additionalProperties":false},"source":{"type":"string","enum":["redis","ssh"]}},"required":["status","live"],"additionalProperties":false}},"required":["data"],"additionalProperties":false,"example":{"data":{"status":"running","containerStatus":"running","live":true,"source":"redis"}}}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false,"example":{"error":{"code":"unauthorized","message":"Invalid or missing API key"}}}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false,"example":{"error":{"code":"forbidden","message":"API key missing required scope"}}}}}},"429":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false,"example":{"error":{"code":"rate_limit_exceeded","message":"Too many requests"}}}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false,"example":{"error":{"code":"internal_error","message":"An internal error occurred"}}}}}}}}},"/v1/agents/{id}/chat/messages":{"post":{"summary":"Send chat message (SSE)","tags":["Chat"],"description":"Sends a user message and streams the agent response as Server-Sent Events. Response is `text/event-stream`. Pass `peerId` to scope session memory per end-user when one API key fronts multiple customers.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","minLength":1},"sessionId":{"type":"string"},"context":{"anyOf":[{"type":"string"},{"type":"object","additionalProperties":{"type":"string"}}]},"peerId":{"type":"string"}},"required":["message"],"additionalProperties":false,"example":{"message":"What is our refund policy?","peerId":"customer-12345"}}}}},"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"security":[{"apiKey":[]}],"x-required-scopes":["chat"],"responses":{"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false,"example":{"error":{"code":"unauthorized","message":"Invalid or missing API key"}}}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false,"example":{"error":{"code":"forbidden","message":"API key missing required scope"}}}}}},"429":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false,"example":{"error":{"code":"rate_limit_exceeded","message":"Too many requests"}}}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false,"example":{"error":{"code":"internal_error","message":"An internal error occurred"}}}}}}}},"get":{"summary":"Get chat message history","tags":["Chat"],"description":"Reads the most recent assistant/user messages from the agent session transcript. Returns at most `limit` messages (default 50, max 200).","parameters":[{"schema":{"type":"string"},"in":"query","name":"sessionId","required":false},{"schema":{"type":"integer","minimum":1,"maximum":200},"in":"query","name":"limit","required":false},{"schema":{"type":"string","format":"date-time"},"in":"query","name":"since","required":false},{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"security":[{"apiKey":[]}],"x-required-scopes":["chat"],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"role":{"type":"string","enum":["user","assistant"]},"content":{"type":"string"},"timestamp":{"type":"string"}},"required":["role","content","timestamp"],"additionalProperties":false}},"pagination":{"type":"object","properties":{"total":{"type":"integer"},"limit":{"type":"integer"},"offset":{"type":"integer"}},"required":["total","limit","offset"],"additionalProperties":false}},"required":["data","pagination"],"additionalProperties":false,"example":{"data":[{"role":"user","content":"What is our refund policy?","timestamp":"2026-05-02T10:30:00.000Z"},{"role":"assistant","content":"Refunds are accepted within 30 days of purchase.","timestamp":"2026-05-02T10:30:01.500Z"}],"pagination":{"total":2,"limit":50,"offset":0}}}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false,"example":{"error":{"code":"unauthorized","message":"Invalid or missing API key"}}}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false,"example":{"error":{"code":"forbidden","message":"API key missing required scope"}}}}}},"429":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false,"example":{"error":{"code":"rate_limit_exceeded","message":"Too many requests"}}}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false,"example":{"error":{"code":"internal_error","message":"An internal error occurred"}}}}}}}}},"/v1/agents/{id}/chat/sessions":{"get":{"summary":"List chat sessions","tags":["Chat"],"description":"Returns the most recent 100 sessions for the agent (across all channels).","parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"security":[{"apiKey":[]}],"x-required-scopes":["chat"],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string","nullable":true},"channel":{"type":"string"},"startedAt":{"type":"string","format":"date-time"}},"required":["id","name","channel","startedAt"],"additionalProperties":false}},"pagination":{"type":"object","properties":{"total":{"type":"integer"},"limit":{"type":"integer"},"offset":{"type":"integer"}},"required":["total","limit","offset"],"additionalProperties":false}},"required":["data","pagination"],"additionalProperties":false}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false,"example":{"error":{"code":"unauthorized","message":"Invalid or missing API key"}}}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false,"example":{"error":{"code":"forbidden","message":"API key missing required scope"}}}}}},"429":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false,"example":{"error":{"code":"rate_limit_exceeded","message":"Too many requests"}}}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false,"example":{"error":{"code":"internal_error","message":"An internal error occurred"}}}}}}}},"post":{"summary":"Create chat session","tags":["Chat"],"description":"Resets the per-key default session for this agent and returns a new session id.","parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"security":[{"apiKey":[]}],"x-required-scopes":["chat"],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string"},"startedAt":{"type":"string","format":"date-time"}},"required":["id","startedAt"],"additionalProperties":false}},"required":["data"],"additionalProperties":false,"example":{"data":{"id":"sess_2026-05-02_8b1d4a1e","startedAt":"2026-05-02T10:31:00.000Z"}}}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false,"example":{"error":{"code":"unauthorized","message":"Invalid or missing API key"}}}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false,"example":{"error":{"code":"forbidden","message":"API key missing required scope"}}}}}},"429":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false,"example":{"error":{"code":"rate_limit_exceeded","message":"Too many requests"}}}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false,"example":{"error":{"code":"internal_error","message":"An internal error occurred"}}}}}}}}},"/v1/agents/{id}/logs":{"get":{"summary":"Get recent agent logs","tags":["Logs"],"description":"Returns the most recent log lines from the agent container, concatenated as a single string.","parameters":[{"schema":{"type":"integer","exclusiveMinimum":true,"minimum":0,"maximum":10000},"in":"query","name":"tail","required":false},{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"security":[{"apiKey":[]}],"x-required-scopes":["logs"],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"logs":{"type":"string"}},"required":["logs"],"additionalProperties":false}},"required":["data"],"additionalProperties":false,"example":{"data":{"logs":"2026-05-02T10:30:00.000Z [info] Agent started\n2026-05-02T10:30:01.500Z [info] Connected to Telegram\n"}}}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false,"example":{"error":{"code":"unauthorized","message":"Invalid or missing API key"}}}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false,"example":{"error":{"code":"forbidden","message":"API key missing required scope"}}}}}},"429":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false,"example":{"error":{"code":"rate_limit_exceeded","message":"Too many requests"}}}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false,"example":{"error":{"code":"internal_error","message":"An internal error occurred"}}}}}}}}},"/v1/agents/{id}/logs/stream":{"get":{"summary":"Stream live agent logs (SSE)","tags":["Logs"],"description":"Server-Sent Events stream of live log lines. Response is `text/event-stream`. Connect with an EventSource or a streaming HTTP client and consume `data:` frames until the client closes the connection.","parameters":[{"schema":{"type":"integer","exclusiveMinimum":true,"minimum":0,"maximum":10000},"in":"query","name":"tail","required":false},{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"security":[{"apiKey":[]}],"x-required-scopes":["logs"],"responses":{"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false,"example":{"error":{"code":"unauthorized","message":"Invalid or missing API key"}}}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false,"example":{"error":{"code":"forbidden","message":"API key missing required scope"}}}}}},"429":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false,"example":{"error":{"code":"rate_limit_exceeded","message":"Too many requests"}}}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false,"example":{"error":{"code":"internal_error","message":"An internal error occurred"}}}}}}}}},"/v1/agents/{id}/skills":{"get":{"summary":"List installed skills","tags":["Skills"],"description":"Returns the skills currently installed on the agent, ordered by install date (newest first).","parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"security":[{"apiKey":[]}],"x-required-scopes":["skills"],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"skillId":{"type":"string"},"name":{"type":"string"},"installedVersion":{"type":"string","nullable":true},"trustLevel":{"type":"string"},"isEnabled":{"type":"boolean"},"installedAt":{"type":"string","format":"date-time"}},"required":["id","skillId","name","installedVersion","trustLevel","isEnabled","installedAt"],"additionalProperties":false}},"pagination":{"type":"object","properties":{"total":{"type":"integer"},"limit":{"type":"integer"},"offset":{"type":"integer"}},"required":["total","limit","offset"],"additionalProperties":false}},"required":["data","pagination"],"additionalProperties":false}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false,"example":{"error":{"code":"unauthorized","message":"Invalid or missing API key"}}}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false,"example":{"error":{"code":"forbidden","message":"API key missing required scope"}}}}}},"429":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false,"example":{"error":{"code":"rate_limit_exceeded","message":"Too many requests"}}}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false,"example":{"error":{"code":"internal_error","message":"An internal error occurred"}}}}}}}},"post":{"summary":"Install a skill on an agent","tags":["Skills"],"description":"Adds a marketplace skill to the agent. The agent will need a restart for the skill to load.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"skillId":{"type":"string","minLength":1},"trustLevel":{"type":"string","enum":["verified","clawhub","custom","github"]},"githubUrl":{"type":"string","format":"uri"}},"required":["trustLevel"],"additionalProperties":false,"example":{"skillId":"web-search","trustLevel":"verified"}}}}},"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"security":[{"apiKey":[]}],"x-required-scopes":["skills"],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"skillId":{"type":"string"},"name":{"type":"string"},"installedVersion":{"type":"string","nullable":true},"trustLevel":{"type":"string"},"isEnabled":{"type":"boolean"},"needsRestart":{"type":"boolean"}},"required":["id","skillId","name","installedVersion","trustLevel","isEnabled","needsRestart"],"additionalProperties":false}},"required":["data"],"additionalProperties":false}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false,"example":{"error":{"code":"unauthorized","message":"Invalid or missing API key"}}}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false,"example":{"error":{"code":"forbidden","message":"API key missing required scope"}}}}}},"429":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false,"example":{"error":{"code":"rate_limit_exceeded","message":"Too many requests"}}}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false,"example":{"error":{"code":"internal_error","message":"An internal error occurred"}}}}}}}}},"/v1/agents/{id}/skills/{skillId}":{"delete":{"summary":"Uninstall a skill from an agent","tags":["Skills"],"description":"Removes the installed skill. The agent needs a restart to fully unload it.","parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true},{"schema":{"type":"string"},"in":"path","name":"skillId","required":true}],"security":[{"apiKey":[]}],"x-required-scopes":["skills"],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"skillId":{"type":"string"},"uninstalled":{"type":"boolean","enum":[true]},"needsRestart":{"type":"boolean"}},"required":["skillId","uninstalled","needsRestart"],"additionalProperties":false}},"required":["data"],"additionalProperties":false,"example":{"data":{"skillId":"web-search","uninstalled":true,"needsRestart":true}}}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false,"example":{"error":{"code":"unauthorized","message":"Invalid or missing API key"}}}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false,"example":{"error":{"code":"forbidden","message":"API key missing required scope"}}}}}},"429":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false,"example":{"error":{"code":"rate_limit_exceeded","message":"Too many requests"}}}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false,"example":{"error":{"code":"internal_error","message":"An internal error occurred"}}}}}}}}},"/v1/skills":{"get":{"summary":"Browse skill marketplace","tags":["Skills"],"description":"Search verified skills available in the marketplace. Use `category` and `search` to narrow.","parameters":[{"schema":{"type":"string"},"in":"query","name":"search","required":false},{"schema":{"type":"string"},"in":"query","name":"category","required":false},{"schema":{"type":"integer","minimum":1},"in":"query","name":"page","required":false},{"schema":{"type":"integer","minimum":1,"maximum":100},"in":"query","name":"pageSize","required":false}],"security":[{"apiKey":[]}],"x-required-scopes":["skills"],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"description":{"type":"string","nullable":true},"author":{"type":"string","nullable":true},"category":{"type":"string","nullable":true},"installCount":{"type":"integer","nullable":true},"latestVersion":{"type":"string","nullable":true},"securityScore":{"type":"number","nullable":true}},"required":["id","name","description","author","category","installCount","latestVersion","securityScore"],"additionalProperties":false}},"pagination":{"type":"object","properties":{"total":{"type":"integer"},"limit":{"type":"integer"},"offset":{"type":"integer"}},"required":["total","limit","offset"],"additionalProperties":false}},"required":["data","pagination"],"additionalProperties":false}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false,"example":{"error":{"code":"unauthorized","message":"Invalid or missing API key"}}}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false,"example":{"error":{"code":"forbidden","message":"API key missing required scope"}}}}}},"429":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false,"example":{"error":{"code":"rate_limit_exceeded","message":"Too many requests"}}}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false,"example":{"error":{"code":"internal_error","message":"An internal error occurred"}}}}}}}},"post":{"summary":"Create a custom skill","tags":["Skills"],"description":"Author a SKILL.md (and optional helper files) and store it as an account-private skill. Install it on any agent in the account via `POST /v1/agents/:id/skills` with `trustLevel: \"custom\"`.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":64,"pattern":"^[a-z][a-z0-9-]{0,63}$"},"description":{"type":"string","minLength":1,"maxLength":500},"version":{"type":"string","pattern":"^(0|[1-9]\\d*)\\.(0|[1-9]\\d*)\\.(0|[1-9]\\d*)(?:-[0-9A-Za-z-]+(?:\\.[0-9A-Za-z-]+)*)?(?:\\+[0-9A-Za-z-]+(?:\\.[0-9A-Za-z-]+)*)?$"},"kind":{"type":"string","enum":["openclaw","hermes"]},"files":{"type":"object","additionalProperties":{"type":"string"}}},"required":["name","description","version","files"],"additionalProperties":false,"example":{"name":"my-trello-helper","description":"Manage Trello boards, lists, and cards via the REST API.","version":"1.0.0","files":{"SKILL.md":"---\nname: my-trello-helper\ndescription: Manage Trello boards.\n---\n\n# Trello\n\nUse `$TRELLO_API_KEY` and `$TRELLO_TOKEN`.\n","scripts/list-cards.sh":"#!/bin/bash\ncurl -s \"https://api.trello.com/1/boards/$1/cards?key=$TRELLO_API_KEY&token=$TRELLO_TOKEN\"\n"}}}}}},"security":[{"apiKey":[]}],"x-required-scopes":["skills"],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"skillId":{"type":"string"},"name":{"type":"string"},"description":{"type":"string","nullable":true},"version":{"type":"string"},"kind":{"type":"string","enum":["openclaw","hermes"]},"fileCount":{"type":"integer"},"totalSizeBytes":{"type":"integer"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["skillId","name","description","version","kind","fileCount","totalSizeBytes","createdAt","updatedAt"],"additionalProperties":false}},"required":["data"],"additionalProperties":false}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false,"example":{"error":{"code":"unauthorized","message":"Invalid or missing API key"}}}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false,"example":{"error":{"code":"forbidden","message":"API key missing required scope"}}}}}},"429":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false,"example":{"error":{"code":"rate_limit_exceeded","message":"Too many requests"}}}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false,"example":{"error":{"code":"internal_error","message":"An internal error occurred"}}}}}}}}},"/v1/skills/{id}":{"get":{"summary":"Get skill details","tags":["Skills"],"description":"Returns the verified skill record with full description, tags, use cases, and security score.","parameters":[{"schema":{"type":"string"},"in":"path","name":"id","required":true}],"security":[{"apiKey":[]}],"x-required-scopes":["skills"],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"description":{"type":"string","nullable":true},"enhancedDescription":{"type":"string","nullable":true},"author":{"type":"string","nullable":true},"category":{"type":"string","nullable":true},"tags":{"type":"array","items":{"type":"string"},"nullable":true},"installCount":{"type":"integer","nullable":true},"latestVersion":{"type":"string","nullable":true},"securityScore":{"type":"number","nullable":true},"useCases":{"type":"array","items":{"type":"string"},"nullable":true},"toolCount":{"type":"integer","nullable":true}},"required":["id","name","description","enhancedDescription","author","category","tags","installCount","latestVersion","securityScore","useCases","toolCount"],"additionalProperties":false}},"required":["data"],"additionalProperties":false}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false,"example":{"error":{"code":"unauthorized","message":"Invalid or missing API key"}}}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false,"example":{"error":{"code":"forbidden","message":"API key missing required scope"}}}}}},"429":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false,"example":{"error":{"code":"rate_limit_exceeded","message":"Too many requests"}}}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false,"example":{"error":{"code":"internal_error","message":"An internal error occurred"}}}}}}}}},"/v1/skills/custom":{"get":{"summary":"List custom skills","tags":["Skills"],"description":"Returns custom skills authored by the authenticated account.","security":[{"apiKey":[]}],"x-required-scopes":["skills"],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"skillId":{"type":"string"},"name":{"type":"string"},"description":{"type":"string","nullable":true},"version":{"type":"string"},"kind":{"type":"string","enum":["openclaw","hermes"]},"fileCount":{"type":"integer"},"totalSizeBytes":{"type":"integer"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["skillId","name","description","version","kind","fileCount","totalSizeBytes","createdAt","updatedAt"],"additionalProperties":false}},"pagination":{"type":"object","properties":{"total":{"type":"integer"},"limit":{"type":"integer"},"offset":{"type":"integer"}},"required":["total","limit","offset"],"additionalProperties":false}},"required":["data","pagination"],"additionalProperties":false}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false,"example":{"error":{"code":"unauthorized","message":"Invalid or missing API key"}}}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false,"example":{"error":{"code":"forbidden","message":"API key missing required scope"}}}}}},"429":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false,"example":{"error":{"code":"rate_limit_exceeded","message":"Too many requests"}}}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false,"example":{"error":{"code":"internal_error","message":"An internal error occurred"}}}}}}}}},"/v1/skills/custom/{id}":{"get":{"summary":"Get a custom skill","tags":["Skills"],"description":"Returns the skill manifest plus its file list (paths and sizes, not content).","parameters":[{"schema":{"type":"string","minLength":1},"in":"path","name":"id","required":true}],"security":[{"apiKey":[]}],"x-required-scopes":["skills"],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"skillId":{"type":"string"},"name":{"type":"string"},"description":{"type":"string","nullable":true},"version":{"type":"string"},"kind":{"type":"string","enum":["openclaw","hermes"]},"fileCount":{"type":"integer"},"totalSizeBytes":{"type":"integer"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"files":{"type":"array","items":{"type":"object","properties":{"path":{"type":"string"},"sizeBytes":{"type":"integer"},"sha256":{"type":"string"}},"required":["path","sizeBytes","sha256"],"additionalProperties":false}},"installedOnAgentIds":{"type":"array","items":{"type":"string","format":"uuid"}}},"required":["skillId","name","description","version","kind","fileCount","totalSizeBytes","createdAt","updatedAt","files","installedOnAgentIds"],"additionalProperties":false}},"required":["data"],"additionalProperties":false}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false,"example":{"error":{"code":"unauthorized","message":"Invalid or missing API key"}}}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false,"example":{"error":{"code":"forbidden","message":"API key missing required scope"}}}}}},"429":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false,"example":{"error":{"code":"rate_limit_exceeded","message":"Too many requests"}}}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false,"example":{"error":{"code":"internal_error","message":"An internal error occurred"}}}}}}}},"patch":{"summary":"Update a custom skill","tags":["Skills"],"description":"Update the description, files, and/or version. If `version` is omitted but `files` change, the patch number is auto-bumped. Any agents currently running this skill must be restarted to pick up the new content.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"description":{"type":"string","minLength":1,"maxLength":500},"version":{"type":"string","pattern":"^(0|[1-9]\\d*)\\.(0|[1-9]\\d*)\\.(0|[1-9]\\d*)(?:-[0-9A-Za-z-]+(?:\\.[0-9A-Za-z-]+)*)?(?:\\+[0-9A-Za-z-]+(?:\\.[0-9A-Za-z-]+)*)?$"},"files":{"type":"object","additionalProperties":{"type":"string"}}},"additionalProperties":false}}}},"parameters":[{"schema":{"type":"string","minLength":1},"in":"path","name":"id","required":true}],"security":[{"apiKey":[]}],"x-required-scopes":["skills"],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"skillId":{"type":"string"},"name":{"type":"string"},"description":{"type":"string","nullable":true},"version":{"type":"string"},"kind":{"type":"string","enum":["openclaw","hermes"]},"fileCount":{"type":"integer"},"totalSizeBytes":{"type":"integer"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"needsRestart":{"type":"boolean"},"affectedAgentCount":{"type":"integer"}},"required":["skillId","name","description","version","kind","fileCount","totalSizeBytes","createdAt","updatedAt","needsRestart","affectedAgentCount"],"additionalProperties":false}},"required":["data"],"additionalProperties":false}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false,"example":{"error":{"code":"unauthorized","message":"Invalid or missing API key"}}}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false,"example":{"error":{"code":"forbidden","message":"API key missing required scope"}}}}}},"429":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false,"example":{"error":{"code":"rate_limit_exceeded","message":"Too many requests"}}}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false,"example":{"error":{"code":"internal_error","message":"An internal error occurred"}}}}}}}},"delete":{"summary":"Delete a custom skill","tags":["Skills"],"description":"Deletes the skill and its files. If the skill is installed on any agents, returns 409 unless `force=true`.","parameters":[{"schema":{"type":"boolean"},"in":"query","name":"force","required":false},{"schema":{"type":"string","minLength":1},"in":"path","name":"id","required":true}],"security":[{"apiKey":[]}],"x-required-scopes":["skills"],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"skillId":{"type":"string"},"deleted":{"type":"boolean","enum":[true]},"uninstalledFromAgentCount":{"type":"integer"}},"required":["skillId","deleted","uninstalledFromAgentCount"],"additionalProperties":false}},"required":["data"],"additionalProperties":false}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false,"example":{"error":{"code":"unauthorized","message":"Invalid or missing API key"}}}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false,"example":{"error":{"code":"forbidden","message":"API key missing required scope"}}}}}},"429":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false,"example":{"error":{"code":"rate_limit_exceeded","message":"Too many requests"}}}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false,"example":{"error":{"code":"internal_error","message":"An internal error occurred"}}}}}}}}},"/v1/skills/custom/{id}/files/{*}":{"get":{"summary":"Read a custom skill file","tags":["Skills"],"description":"Returns the raw content of a single file inside the skill, useful for round-tripping a skill back into Claude Code or another editor.","parameters":[{"schema":{"type":"string","minLength":1},"in":"path","name":"id","required":true},{"schema":{"type":"string","minLength":1},"in":"path","name":"path","required":true}],"security":[{"apiKey":[]}],"x-required-scopes":["skills"],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"path":{"type":"string"},"content":{"type":"string"},"sizeBytes":{"type":"integer"},"sha256":{"type":"string"}},"required":["path","content","sizeBytes","sha256"],"additionalProperties":false}},"required":["data"],"additionalProperties":false}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false,"example":{"error":{"code":"unauthorized","message":"Invalid or missing API key"}}}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false,"example":{"error":{"code":"forbidden","message":"API key missing required scope"}}}}}},"429":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false,"example":{"error":{"code":"rate_limit_exceeded","message":"Too many requests"}}}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false,"example":{"error":{"code":"internal_error","message":"An internal error occurred"}}}}}}}}},"/v1/account":{"get":{"summary":"Get account info","tags":["Account"],"description":"Returns the account record, current plan and entitlements, plus aggregate agent usage. No specific scope required.","security":[{"apiKey":[]}],"x-required-scopes":[],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string","nullable":true},"plan":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"status":{"type":"string"},"limits":{"type":"object","additionalProperties":{}},"features":{"type":"object","additionalProperties":{}}},"required":["id","name","status","limits","features"],"additionalProperties":false,"nullable":true},"usage":{"type":"object","properties":{"agents":{"type":"integer"},"runningAgents":{"type":"integer"}},"required":["agents","runningAgents"],"additionalProperties":false}},"required":["id","name","plan","usage"],"additionalProperties":false}},"required":["data"],"additionalProperties":false,"example":{"data":{"id":"8b1d4a1e-1c2f-4f51-b09b-9d1ad3a1c3bc","name":"Acme Inc.","plan":{"id":"pro","name":"Pro","status":"active","limits":{"maxAgents":10,"maxRunningAgents":5},"features":{"swarms":true,"api_access":true}},"usage":{"agents":3,"runningAgents":1}}}}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false,"example":{"error":{"code":"unauthorized","message":"Invalid or missing API key"}}}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false,"example":{"error":{"code":"forbidden","message":"API key missing required scope"}}}}}},"429":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false,"example":{"error":{"code":"rate_limit_exceeded","message":"Too many requests"}}}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false,"example":{"error":{"code":"internal_error","message":"An internal error occurred"}}}}}}}}},"/v1/agents/{id}/secrets":{"put":{"summary":"Update agent secrets","tags":["Account"],"description":"Set, update, or delete agent secrets (LLM API keys, channel tokens, etc.). Secrets are write-only and cannot be read back.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"secrets":{"type":"object","additionalProperties":{"type":"string"}},"deleteSecrets":{"type":"array","items":{"type":"string"}}},"additionalProperties":false,"example":{"secrets":{"anthropicApiKey":"sk-ant-api03-..."},"deleteSecrets":["openaiApiKey"]}}}}},"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"security":[{"apiKey":[]}],"x-required-scopes":["agents:write"],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"updated":{"type":"boolean","enum":[true]},"needsRestart":{"type":"boolean"}},"required":["updated","needsRestart"],"additionalProperties":false}},"required":["data"],"additionalProperties":false,"example":{"data":{"updated":true,"needsRestart":true}}}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false,"example":{"error":{"code":"unauthorized","message":"Invalid or missing API key"}}}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false,"example":{"error":{"code":"forbidden","message":"API key missing required scope"}}}}}},"429":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false,"example":{"error":{"code":"rate_limit_exceeded","message":"Too many requests"}}}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false,"example":{"error":{"code":"internal_error","message":"An internal error occurred"}}}}}}}}},"/v1/agents/{id}/personality":{"get":{"summary":"Get agent personality","tags":["Account"],"description":"Returns the agent's SOUL.md and IDENTITY.md content plus the SOUL.md hash for optimistic concurrency.","parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"security":[{"apiKey":[]}],"x-required-scopes":["agents:read"],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"soulMd":{"type":"string","nullable":true},"identityMd":{"type":"string","nullable":true},"soulMdHash":{"type":"string","nullable":true},"soulMdUpdatedAt":{"type":"string","format":"date-time","nullable":true}},"required":["soulMd","identityMd","soulMdHash","soulMdUpdatedAt"],"additionalProperties":false}},"required":["data"],"additionalProperties":false}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false,"example":{"error":{"code":"unauthorized","message":"Invalid or missing API key"}}}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false,"example":{"error":{"code":"forbidden","message":"API key missing required scope"}}}}}},"429":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false,"example":{"error":{"code":"rate_limit_exceeded","message":"Too many requests"}}}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false,"example":{"error":{"code":"internal_error","message":"An internal error occurred"}}}}}}}},"put":{"summary":"Update agent personality","tags":["Account"],"description":"Replaces SOUL.md with new content. Pass `expectedHash` to detect concurrent edits.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"soulMd":{"type":"string","minLength":1},"expectedHash":{"type":"string"}},"required":["soulMd"],"additionalProperties":false}}}},"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"security":[{"apiKey":[]}],"x-required-scopes":["agents:write"],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"soulMd":{"type":"string","nullable":true},"soulMdHash":{"type":"string","nullable":true},"soulMdUpdatedAt":{"type":"string","format":"date-time","nullable":true},"needsRestart":{"type":"boolean"}},"required":["soulMd","soulMdHash","soulMdUpdatedAt","needsRestart"],"additionalProperties":false}},"required":["data"],"additionalProperties":false}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false,"example":{"error":{"code":"unauthorized","message":"Invalid or missing API key"}}}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false,"example":{"error":{"code":"forbidden","message":"API key missing required scope"}}}}}},"429":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false,"example":{"error":{"code":"rate_limit_exceeded","message":"Too many requests"}}}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false,"example":{"error":{"code":"internal_error","message":"An internal error occurred"}}}}}}}}},"/v1/agents/{id}/workflow":{"get":{"summary":"Get agent workflow","tags":["Account"],"description":"Reads WORKFLOW.md from the agent workspace and lists rule files. Live data is only available while the agent is running.","parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"security":[{"apiKey":[]}],"x-required-scopes":["agents:read"],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"workflowMd":{"type":"string","nullable":true},"rules":{"type":"array","items":{"type":"string"}}},"required":["workflowMd","rules"],"additionalProperties":false}},"required":["data"],"additionalProperties":false,"example":{"data":{"workflowMd":"# Workflow\n\n## Role\n\nYou are a customer support agent...","rules":["greeting.md","escalation.md"]}}}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false,"example":{"error":{"code":"unauthorized","message":"Invalid or missing API key"}}}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false,"example":{"error":{"code":"forbidden","message":"API key missing required scope"}}}}}},"429":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false,"example":{"error":{"code":"rate_limit_exceeded","message":"Too many requests"}}}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false,"example":{"error":{"code":"internal_error","message":"An internal error occurred"}}}}}}}},"put":{"summary":"Update agent workflow","tags":["Account"],"description":"Writes WORKFLOW.md to the agent workspace. Agent restart is required for changes to take effect.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"workflowMd":{"type":"string","minLength":1}},"required":["workflowMd"],"additionalProperties":false,"example":{"workflowMd":"# Workflow\n\n## Role\n\nYou are a customer support agent."}}}}},"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"security":[{"apiKey":[]}],"x-required-scopes":["agents:write"],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"workflowMd":{"type":"string"},"needsRestart":{"type":"boolean"}},"required":["workflowMd","needsRestart"],"additionalProperties":false}},"required":["data"],"additionalProperties":false}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false,"example":{"error":{"code":"unauthorized","message":"Invalid or missing API key"}}}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false,"example":{"error":{"code":"forbidden","message":"API key missing required scope"}}}}}},"429":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false,"example":{"error":{"code":"rate_limit_exceeded","message":"Too many requests"}}}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false,"example":{"error":{"code":"internal_error","message":"An internal error occurred"}}}}}}}}},"/v1/agents/{id}/rules":{"get":{"summary":"List agent rules","tags":["Account"],"description":"Lists all .md files in the agent's workspace `rules/` directory with their byte sizes.","parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"security":[{"apiKey":[]}],"x-required-scopes":["agents:read"],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"rules":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"size":{"type":"integer"}},"required":["name","size"],"additionalProperties":false}}},"required":["rules"],"additionalProperties":false}},"required":["data"],"additionalProperties":false}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false,"example":{"error":{"code":"unauthorized","message":"Invalid or missing API key"}}}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false,"example":{"error":{"code":"forbidden","message":"API key missing required scope"}}}}}},"429":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false,"example":{"error":{"code":"rate_limit_exceeded","message":"Too many requests"}}}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false,"example":{"error":{"code":"internal_error","message":"An internal error occurred"}}}}}}}}},"/v1/agents/{id}/rules/{name}":{"get":{"summary":"Read agent rule","tags":["Account"],"description":"Returns the content of a single rule file by name.","parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true},{"schema":{"type":"string","pattern":"^[a-zA-Z0-9][a-zA-Z0-9_-]{0,98}$"},"in":"path","name":"name","required":true}],"security":[{"apiKey":[]}],"x-required-scopes":["agents:read"],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"name":{"type":"string"},"content":{"type":"string"}},"required":["name","content"],"additionalProperties":false}},"required":["data"],"additionalProperties":false}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false,"example":{"error":{"code":"unauthorized","message":"Invalid or missing API key"}}}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false,"example":{"error":{"code":"forbidden","message":"API key missing required scope"}}}}}},"429":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false,"example":{"error":{"code":"rate_limit_exceeded","message":"Too many requests"}}}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false,"example":{"error":{"code":"internal_error","message":"An internal error occurred"}}}}}}}},"put":{"summary":"Create or replace agent rule","tags":["Account"],"description":"Writes the rule file to the agent workspace under `rules/<name>.md`. Restart is required for runtime effect.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"content":{"type":"string","minLength":1}},"required":["content"],"additionalProperties":false}}}},"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true},{"schema":{"type":"string","pattern":"^[a-zA-Z0-9][a-zA-Z0-9_-]{0,98}$"},"in":"path","name":"name","required":true}],"security":[{"apiKey":[]}],"x-required-scopes":["agents:write"],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"name":{"type":"string"},"needsRestart":{"type":"boolean"}},"required":["name","needsRestart"],"additionalProperties":false}},"required":["data"],"additionalProperties":false}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false,"example":{"error":{"code":"unauthorized","message":"Invalid or missing API key"}}}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false,"example":{"error":{"code":"forbidden","message":"API key missing required scope"}}}}}},"429":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false,"example":{"error":{"code":"rate_limit_exceeded","message":"Too many requests"}}}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false,"example":{"error":{"code":"internal_error","message":"An internal error occurred"}}}}}}}},"delete":{"summary":"Delete agent rule","tags":["Account"],"description":"Removes the rule file from the agent workspace.","parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true},{"schema":{"type":"string","pattern":"^[a-zA-Z0-9][a-zA-Z0-9_-]{0,98}$"},"in":"path","name":"name","required":true}],"security":[{"apiKey":[]}],"x-required-scopes":["agents:write"],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"name":{"type":"string"},"deleted":{"type":"boolean","enum":[true]},"needsRestart":{"type":"boolean"}},"required":["name","deleted","needsRestart"],"additionalProperties":false}},"required":["data"],"additionalProperties":false}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false,"example":{"error":{"code":"unauthorized","message":"Invalid or missing API key"}}}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false,"example":{"error":{"code":"forbidden","message":"API key missing required scope"}}}}}},"429":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false,"example":{"error":{"code":"rate_limit_exceeded","message":"Too many requests"}}}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false,"example":{"error":{"code":"internal_error","message":"An internal error occurred"}}}}}}}}},"/v1/swarms":{"get":{"summary":"List swarms","tags":["Swarms"],"description":"Returns all swarms in your account. Requires the swarms feature on your plan.","security":[{"apiKey":[]}],"x-required-scopes":["swarms:read"],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"slug":{"type":"string"},"description":{"type":"string","nullable":true},"icon":{"type":"string","nullable":true},"agentCount":{"type":"integer"},"memberCount":{"type":"integer"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","name","slug","description","icon","agentCount","memberCount","createdAt","updatedAt"],"additionalProperties":false}}},"required":["data"],"additionalProperties":false,"example":{"data":[{"id":"8b1d4a1e-1c2f-4f51-b09b-9d1ad3a1c3bc","name":"Customer Support","slug":"customer-support","description":"Frontline support agents","icon":"headset","agentCount":3,"memberCount":2,"createdAt":"2026-04-01T10:00:00.000Z","updatedAt":"2026-04-15T14:30:00.000Z"}]}}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false,"example":{"error":{"code":"unauthorized","message":"Invalid or missing API key"}}}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false,"example":{"error":{"code":"forbidden","message":"API key missing required scope"}}}}}},"429":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false,"example":{"error":{"code":"rate_limit_exceeded","message":"Too many requests"}}}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false,"example":{"error":{"code":"internal_error","message":"An internal error occurred"}}}}}}}},"post":{"summary":"Create swarm","tags":["Swarms"],"description":"Creates a new swarm. The slug is generated from the name and de-duplicated within your account.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":100},"description":{"type":"string"},"icon":{"type":"string"}},"required":["name"],"additionalProperties":false,"example":{"name":"Customer Support","description":"Frontline support agents","icon":"headset"}}}}},"security":[{"apiKey":[]}],"x-required-scopes":["swarms:write"],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"slug":{"type":"string"},"description":{"type":"string","nullable":true},"icon":{"type":"string","nullable":true},"agentCount":{"type":"integer"},"memberCount":{"type":"integer"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","name","slug","description","icon","agentCount","memberCount","createdAt","updatedAt"],"additionalProperties":false}},"required":["data"],"additionalProperties":false}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false,"example":{"error":{"code":"unauthorized","message":"Invalid or missing API key"}}}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false,"example":{"error":{"code":"forbidden","message":"API key missing required scope"}}}}}},"429":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false,"example":{"error":{"code":"rate_limit_exceeded","message":"Too many requests"}}}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false,"example":{"error":{"code":"internal_error","message":"An internal error occurred"}}}}}}}}},"/v1/swarms/{id}":{"get":{"summary":"Get swarm details","tags":["Swarms"],"description":"Returns the swarm record plus its non-deleted agents.","parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"security":[{"apiKey":[]}],"x-required-scopes":["swarms:read"],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"slug":{"type":"string"},"description":{"type":"string","nullable":true},"icon":{"type":"string","nullable":true},"agentCount":{"type":"integer"},"memberCount":{"type":"integer"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"agents":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"status":{"type":"string"},"createdAt":{"type":"string","format":"date-time"}},"required":["id","name","status","createdAt"],"additionalProperties":false}}},"required":["id","name","slug","description","icon","agentCount","memberCount","createdAt","updatedAt","agents"],"additionalProperties":false}},"required":["data"],"additionalProperties":false}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false,"example":{"error":{"code":"unauthorized","message":"Invalid or missing API key"}}}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false,"example":{"error":{"code":"forbidden","message":"API key missing required scope"}}}}}},"429":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false,"example":{"error":{"code":"rate_limit_exceeded","message":"Too many requests"}}}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false,"example":{"error":{"code":"internal_error","message":"An internal error occurred"}}}}}}}},"patch":{"summary":"Update swarm","tags":["Swarms"],"description":"Updates name, description, or icon. Slug is not updatable.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":100},"description":{"type":"string","nullable":true},"icon":{"type":"string","nullable":true}},"additionalProperties":false}}}},"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"security":[{"apiKey":[]}],"x-required-scopes":["swarms:write"],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"slug":{"type":"string"},"description":{"type":"string","nullable":true},"icon":{"type":"string","nullable":true},"agentCount":{"type":"integer"},"memberCount":{"type":"integer"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","name","slug","description","icon","agentCount","memberCount","createdAt","updatedAt"],"additionalProperties":false}},"required":["data"],"additionalProperties":false}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false,"example":{"error":{"code":"unauthorized","message":"Invalid or missing API key"}}}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false,"example":{"error":{"code":"forbidden","message":"API key missing required scope"}}}}}},"429":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false,"example":{"error":{"code":"rate_limit_exceeded","message":"Too many requests"}}}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false,"example":{"error":{"code":"internal_error","message":"An internal error occurred"}}}}}}}},"delete":{"summary":"Delete swarm","tags":["Swarms"],"description":"Removes the swarm. Members and providers cascade; assigned agents are unlinked (SetNull).","parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"security":[{"apiKey":[]}],"x-required-scopes":["swarms:write"],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"deleted":{"type":"boolean","enum":[true]}},"required":["id","deleted"],"additionalProperties":false}},"required":["data"],"additionalProperties":false,"example":{"data":{"id":"8b1d4a1e-1c2f-4f51-b09b-9d1ad3a1c3bc","deleted":true}}}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false,"example":{"error":{"code":"unauthorized","message":"Invalid or missing API key"}}}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false,"example":{"error":{"code":"forbidden","message":"API key missing required scope"}}}}}},"429":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false,"example":{"error":{"code":"rate_limit_exceeded","message":"Too many requests"}}}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false,"example":{"error":{"code":"internal_error","message":"An internal error occurred"}}}}}}}}},"/v1/knowledge/ingest":{"post":{"summary":"Ingest knowledge chunks","tags":["Knowledge"],"description":"Embed and store up to 100 text chunks for the target swarm or agent. Duplicates (cosine similarity > 0.95) are skipped.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"swarmId":{"type":"string"},"agentId":{"type":"string"},"chunks":{"type":"array","items":{"type":"object","properties":{"text":{"type":"string","minLength":1,"maxLength":4000},"source":{"type":"string","minLength":1},"metadata":{"type":"object","additionalProperties":{"type":"string"}}},"required":["text","source"],"additionalProperties":false},"minItems":1,"maxItems":100}},"required":["chunks"],"additionalProperties":false,"example":{"agentId":"a1b2c3d4-e5f6-7890-abcd-ef1234567890","chunks":[{"text":"Our refund policy allows returns within 30 days of purchase.","source":"support/refund-policy.md"},{"text":"Shipping is free for orders over $50.","source":"support/shipping.md","metadata":{"type":"policy"}}]}}}}},"security":[{"apiKey":[]}],"x-required-scopes":["knowledge:write"],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"stored":{"type":"integer"},"skipped":{"type":"integer"},"total":{"type":"integer"}},"required":["stored","skipped","total"],"additionalProperties":false}},"required":["data"],"additionalProperties":false,"example":{"data":{"stored":2,"skipped":0,"total":2}}}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false,"example":{"error":{"code":"unauthorized","message":"Invalid or missing API key"}}}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false,"example":{"error":{"code":"forbidden","message":"API key missing required scope"}}}}}},"429":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false,"example":{"error":{"code":"rate_limit_exceeded","message":"Too many requests"}}}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false,"example":{"error":{"code":"internal_error","message":"An internal error occurred"}}}}}}}}},"/v1/knowledge":{"get":{"summary":"List knowledge entries","tags":["Knowledge"],"description":"Returns stored KB entries for a target. Use `nextOffset` to paginate.","parameters":[{"schema":{"type":"string"},"in":"query","name":"swarmId","required":false},{"schema":{"type":"string"},"in":"query","name":"agentId","required":false},{"schema":{"type":"string"},"in":"query","name":"source","required":false},{"schema":{"type":"integer","minimum":1,"maximum":100},"in":"query","name":"limit","required":false},{"schema":{"type":"string"},"in":"query","name":"offset","required":false}],"security":[{"apiKey":[]}],"x-required-scopes":["knowledge:read"],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"text":{"type":"string","nullable":true},"source":{"type":"string","nullable":true},"type":{"type":"string","nullable":true},"createdAt":{"type":"string","nullable":true},"updatedAt":{"type":"string","nullable":true}},"required":["id","text","source","type","createdAt","updatedAt"],"additionalProperties":false}},"pagination":{"type":"object","properties":{"nextOffset":{"type":"string","nullable":true},"hasMore":{"type":"boolean"}},"required":["nextOffset","hasMore"],"additionalProperties":false}},"required":["data","pagination"],"additionalProperties":false,"example":{"data":[{"id":"8b1d4a1e-1c2f-4f51-b09b-9d1ad3a1c3bc","text":"Our refund policy allows returns within 30 days of purchase.","source":"support/refund-policy.md","type":"text","createdAt":"2026-05-01T10:00:00.000Z","updatedAt":"2026-05-01T10:00:00.000Z"}],"pagination":{"nextOffset":null,"hasMore":false}}}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false,"example":{"error":{"code":"unauthorized","message":"Invalid or missing API key"}}}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false,"example":{"error":{"code":"forbidden","message":"API key missing required scope"}}}}}},"429":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false,"example":{"error":{"code":"rate_limit_exceeded","message":"Too many requests"}}}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false,"example":{"error":{"code":"internal_error","message":"An internal error occurred"}}}}}}}},"delete":{"summary":"Delete knowledge entries","tags":["Knowledge"],"description":"Delete by `id` (single entry), by `source` (all entries from that source), or `all=true&confirm=true` (entire target).","parameters":[{"schema":{"type":"string"},"in":"query","name":"swarmId","required":false},{"schema":{"type":"string"},"in":"query","name":"agentId","required":false},{"schema":{"type":"string"},"in":"query","name":"source","required":false},{"schema":{"type":"string"},"in":"query","name":"id","required":false},{"schema":{"type":"string","enum":["true","false"]},"in":"query","name":"all","required":false},{"schema":{"type":"string","enum":["true","false"]},"in":"query","name":"confirm","required":false}],"security":[{"apiKey":[]}],"x-required-scopes":["knowledge:write"],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"deleted":{"type":"boolean","enum":[true]}},"required":["deleted"],"additionalProperties":false}},"required":["data"],"additionalProperties":false,"example":{"data":{"deleted":true}}}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false,"example":{"error":{"code":"unauthorized","message":"Invalid or missing API key"}}}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false,"example":{"error":{"code":"forbidden","message":"API key missing required scope"}}}}}},"429":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false,"example":{"error":{"code":"rate_limit_exceeded","message":"Too many requests"}}}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false,"example":{"error":{"code":"internal_error","message":"An internal error occurred"}}}}}}}}}},"servers":[{"url":"https://api.agento.host"}],"tags":[{"name":"Agents","description":"Create, configure, and manage AI agents"},{"name":"Account","description":"Account info, agent secrets, personality, workflow, and rules"},{"name":"Chat","description":"Send messages and read chat history"},{"name":"Knowledge","description":"Ingest and query the agent or swarm knowledge base"},{"name":"Logs","description":"Inspect and stream agent container logs"},{"name":"Skills","description":"Browse the marketplace and install skills on agents"},{"name":"Swarms","description":"Manage swarms and their members"}]}