{"openapi":"3.1.0","info":{"title":"AgentForge API","version":"1.0.0","description":"Programmatically create and configure AI agents. Every endpoint returns next_steps to guide you through the setup flow."},"servers":[{"url":"/api"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"API key from AgentForge dashboard (format: af_xxx)"}},"schemas":{},"parameters":{}},"paths":{"/v1/agents":{"get":{"tags":["Agents"],"summary":"List all agents in your workspace","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"List of agents","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"tenantId":{"type":"string","format":"uuid"},"name":{"type":"string"},"model":{"type":"string"},"systemPrompt":{"type":"string"},"toolConfig":{"nullable":true},"memoryConfig":{"nullable":true},"channelConfig":{"nullable":true},"guardrailConfig":{"nullable":true},"promptConfig":{"nullable":true},"escalationConfig":{"nullable":true},"status":{"type":"string","enum":["draft","active","paused","disabled"]},"createdAt":{"type":"string"},"updatedAt":{"type":"string"}},"required":["id","tenantId","name","model","systemPrompt","status","createdAt","updatedAt"]}}},"required":["data"]}}}}}},"post":{"tags":["Agents"],"summary":"Create a new agent","description":"Creates a new agent in draft status. Follow the next_steps to configure it.","security":[{"bearerAuth":[]}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"example":"Customer Support Bot"},"model":{"type":"string","example":"openai/gpt-4o"},"systemPrompt":{"type":"string","example":"You are a helpful customer support agent."}},"required":["name","model"]}}}},"responses":{"201":{"description":"Agent created","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"tenantId":{"type":"string","format":"uuid"},"name":{"type":"string"},"model":{"type":"string"},"systemPrompt":{"type":"string"},"toolConfig":{"nullable":true},"memoryConfig":{"nullable":true},"channelConfig":{"nullable":true},"guardrailConfig":{"nullable":true},"promptConfig":{"nullable":true},"escalationConfig":{"nullable":true},"status":{"type":"string","enum":["draft","active","paused","disabled"]},"createdAt":{"type":"string"},"updatedAt":{"type":"string"}},"required":["id","tenantId","name","model","systemPrompt","status","createdAt","updatedAt"]},"next_steps":{"type":"array","items":{"type":"object","properties":{"description":{"type":"string"},"method":{"type":"string"},"path":{"type":"string"}},"required":["description","method","path"]}}},"required":["data","next_steps"]}}}}}}},"/v1/agents/{id}":{"get":{"tags":["Agents"],"summary":"Get an agent with its full configuration","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"Agent details","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"tenantId":{"type":"string","format":"uuid"},"name":{"type":"string"},"model":{"type":"string"},"systemPrompt":{"type":"string"},"toolConfig":{"nullable":true},"memoryConfig":{"nullable":true},"channelConfig":{"nullable":true},"guardrailConfig":{"nullable":true},"promptConfig":{"nullable":true},"escalationConfig":{"nullable":true},"status":{"type":"string","enum":["draft","active","paused","disabled"]},"createdAt":{"type":"string"},"updatedAt":{"type":"string"}},"required":["id","tenantId","name","model","systemPrompt","status","createdAt","updatedAt"]}},"required":["data"]}}}},"404":{"description":"Agent not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"fix":{"type":"string"},"request_id":{"type":"string"}},"required":["code","message","fix","request_id"]}},"required":["error"]}}}}}},"patch":{"tags":["Agents"],"summary":"Update an agent","description":"Update agent name, status, or other top-level fields. Use dedicated sub-resource endpoints for prompt, tools, etc.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"id","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1},"status":{"type":"string","enum":["draft","active","paused","disabled"]}}}}}},"responses":{"200":{"description":"Agent updated","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"tenantId":{"type":"string","format":"uuid"},"name":{"type":"string"},"model":{"type":"string"},"systemPrompt":{"type":"string"},"toolConfig":{"nullable":true},"memoryConfig":{"nullable":true},"channelConfig":{"nullable":true},"guardrailConfig":{"nullable":true},"promptConfig":{"nullable":true},"escalationConfig":{"nullable":true},"status":{"type":"string","enum":["draft","active","paused","disabled"]},"createdAt":{"type":"string"},"updatedAt":{"type":"string"}},"required":["id","tenantId","name","model","systemPrompt","status","createdAt","updatedAt"]},"next_steps":{"type":"array","items":{"type":"object","properties":{"description":{"type":"string"},"method":{"type":"string"},"path":{"type":"string"}},"required":["description","method","path"]}}},"required":["data","next_steps"]}}}},"404":{"description":"Agent not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"fix":{"type":"string"},"request_id":{"type":"string"}},"required":["code","message","fix","request_id"]}},"required":["error"]}}}}}},"delete":{"tags":["Agents"],"summary":"Delete an agent","description":"Permanently deletes an agent and all its associated data (knowledge bases, logs, conversations).","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"Agent deleted","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"404":{"description":"Agent not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"fix":{"type":"string"},"request_id":{"type":"string"}},"required":["code","message","fix","request_id"]}},"required":["error"]}}}}}}},"/v1/agents/{id}/clone":{"post":{"tags":["Agents"],"summary":"Clone an agent","description":"Creates a copy of the agent with all its configuration. The clone starts in draft status.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"id","in":"path"}],"responses":{"201":{"description":"Agent cloned","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"tenantId":{"type":"string","format":"uuid"},"name":{"type":"string"},"model":{"type":"string"},"systemPrompt":{"type":"string"},"toolConfig":{"nullable":true},"memoryConfig":{"nullable":true},"channelConfig":{"nullable":true},"guardrailConfig":{"nullable":true},"promptConfig":{"nullable":true},"escalationConfig":{"nullable":true},"status":{"type":"string","enum":["draft","active","paused","disabled"]},"createdAt":{"type":"string"},"updatedAt":{"type":"string"}},"required":["id","tenantId","name","model","systemPrompt","status","createdAt","updatedAt"]},"next_steps":{"type":"array","items":{"type":"object","properties":{"description":{"type":"string"},"method":{"type":"string"},"path":{"type":"string"}},"required":["description","method","path"]}}},"required":["data","next_steps"]}}}},"404":{"description":"Agent not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"fix":{"type":"string"},"request_id":{"type":"string"}},"required":["code","message","fix","request_id"]}},"required":["error"]}}}}}}},"/v1/agents/{id}/prompt":{"get":{"tags":["Agent Configuration"],"summary":"Get agent prompt config","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"Prompt config","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"promptConfig":{"type":"object","nullable":true,"properties":{"role":{"type":"string"},"authority":{"type":"string"},"constraints":{"type":"array","items":{"type":"string"}},"reasoning":{"type":"string"},"responseStyle":{"type":"string"},"examples":{"type":"array","items":{"type":"object","properties":{"user":{"type":"string"},"assistant":{"type":"string"}},"required":["user","assistant"]}},"contextInjection":{"type":"array","items":{"type":"string"}},"escalationRules":{"type":"string"}},"required":["role","authority","constraints","reasoning","responseStyle","examples","contextInjection","escalationRules"]},"systemPrompt":{"type":"string","nullable":true}},"required":["promptConfig","systemPrompt"]}},"required":["data"]}}}},"404":{"description":"Agent not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"fix":{"type":"string"},"request_id":{"type":"string"}},"required":["code","message","fix","request_id"]}},"required":["error"]}}}}}},"put":{"tags":["Agent Configuration"],"summary":"Update agent prompt config","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"id","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"promptConfig":{"type":"object","properties":{"role":{"type":"string"},"authority":{"type":"string"},"constraints":{"type":"array","items":{"type":"string"}},"reasoning":{"type":"string"},"responseStyle":{"type":"string"},"examples":{"type":"array","items":{"type":"object","properties":{"user":{"type":"string"},"assistant":{"type":"string"}},"required":["user","assistant"]}},"contextInjection":{"type":"array","items":{"type":"string"}},"escalationRules":{"type":"string"}},"required":["role","authority","constraints","reasoning","responseStyle","examples","contextInjection","escalationRules"]},"systemPrompt":{"type":"string"}}}}}},"responses":{"200":{"description":"Prompt updated","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"promptConfig":{"type":"object","nullable":true,"properties":{"role":{"type":"string"},"authority":{"type":"string"},"constraints":{"type":"array","items":{"type":"string"}},"reasoning":{"type":"string"},"responseStyle":{"type":"string"},"examples":{"type":"array","items":{"type":"object","properties":{"user":{"type":"string"},"assistant":{"type":"string"}},"required":["user","assistant"]}},"contextInjection":{"type":"array","items":{"type":"string"}},"escalationRules":{"type":"string"}},"required":["role","authority","constraints","reasoning","responseStyle","examples","contextInjection","escalationRules"]},"systemPrompt":{"type":"string","nullable":true}},"required":["promptConfig","systemPrompt"]},"next_steps":{"type":"array","items":{"type":"object","properties":{"description":{"type":"string"},"method":{"type":"string"},"path":{"type":"string"}},"required":["description","method","path"]}}},"required":["data","next_steps"]}}}},"404":{"description":"Agent not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"fix":{"type":"string"},"request_id":{"type":"string"}},"required":["code","message","fix","request_id"]}},"required":["error"]}}}}}}},"/v1/agents/{id}/model":{"get":{"tags":["Agent Configuration"],"summary":"Get agent model config","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"Model config","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"model":{"type":"string"}},"required":["model"]}},"required":["data"]}}}},"404":{"description":"Agent not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"fix":{"type":"string"},"request_id":{"type":"string"}},"required":["code","message","fix","request_id"]}},"required":["error"]}}}}}},"put":{"tags":["Agent Configuration"],"summary":"Update agent model config","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"id","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"model":{"type":"string"}},"required":["model"]}}}},"responses":{"200":{"description":"Model updated","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"model":{"type":"string"}},"required":["model"]},"next_steps":{"type":"array","items":{"type":"object","properties":{"description":{"type":"string"},"method":{"type":"string"},"path":{"type":"string"}},"required":["description","method","path"]}}},"required":["data","next_steps"]}}}},"404":{"description":"Agent not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"fix":{"type":"string"},"request_id":{"type":"string"}},"required":["code","message","fix","request_id"]}},"required":["error"]}}}}}}},"/v1/agents/{id}/tools":{"get":{"tags":["Agent Configuration"],"summary":"Get agent tools config","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"Tools config","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string","enum":["api_call","web_scraper","knowledge_card","calculator","code_executor"]},"name":{"type":"string"},"description":{"type":"string"},"config":{"type":"object","properties":{"url":{"type":"string"},"method":{"type":"string","enum":["GET","POST","PUT","DELETE"]},"headers":{"type":"object","additionalProperties":{"type":"string"}},"authType":{"type":"string","enum":["none","bearer","api_key","basic"]},"authValue":{"type":"string"},"bodyTemplate":{"type":"string"},"responseMapping":{"type":"string"},"timeoutMs":{"type":"number"},"defaultUrl":{"type":"string"},"cssSelector":{"type":"string"},"instructions":{"type":"string"},"language":{"type":"string","enum":["javascript","python"]}}},"inputSchema":{"type":"object","additionalProperties":{"type":"object","properties":{"type":{"type":"string"},"description":{"type":"string"},"required":{"type":"boolean"}},"required":["type","description"]}}},"required":["type","name","description","config"]}}},"required":["data"]}}}},"404":{"description":"Agent not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"fix":{"type":"string"},"request_id":{"type":"string"}},"required":["code","message","fix","request_id"]}},"required":["error"]}}}}}},"put":{"tags":["Agent Configuration"],"summary":"Update agent tools config","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"id","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string","enum":["api_call","web_scraper","knowledge_card","calculator","code_executor"]},"name":{"type":"string"},"description":{"type":"string"},"config":{"type":"object","properties":{"url":{"type":"string"},"method":{"type":"string","enum":["GET","POST","PUT","DELETE"]},"headers":{"type":"object","additionalProperties":{"type":"string"}},"authType":{"type":"string","enum":["none","bearer","api_key","basic"]},"authValue":{"type":"string"},"bodyTemplate":{"type":"string"},"responseMapping":{"type":"string"},"timeoutMs":{"type":"number"},"defaultUrl":{"type":"string"},"cssSelector":{"type":"string"},"instructions":{"type":"string"},"language":{"type":"string","enum":["javascript","python"]}}},"inputSchema":{"type":"object","additionalProperties":{"type":"object","properties":{"type":{"type":"string"},"description":{"type":"string"},"required":{"type":"boolean"}},"required":["type","description"]}}},"required":["type","name","description","config"]}}}}},"responses":{"200":{"description":"Tools updated","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string","enum":["api_call","web_scraper","knowledge_card","calculator","code_executor"]},"name":{"type":"string"},"description":{"type":"string"},"config":{"type":"object","properties":{"url":{"type":"string"},"method":{"type":"string","enum":["GET","POST","PUT","DELETE"]},"headers":{"type":"object","additionalProperties":{"type":"string"}},"authType":{"type":"string","enum":["none","bearer","api_key","basic"]},"authValue":{"type":"string"},"bodyTemplate":{"type":"string"},"responseMapping":{"type":"string"},"timeoutMs":{"type":"number"},"defaultUrl":{"type":"string"},"cssSelector":{"type":"string"},"instructions":{"type":"string"},"language":{"type":"string","enum":["javascript","python"]}}},"inputSchema":{"type":"object","additionalProperties":{"type":"object","properties":{"type":{"type":"string"},"description":{"type":"string"},"required":{"type":"boolean"}},"required":["type","description"]}}},"required":["type","name","description","config"]}},"next_steps":{"type":"array","items":{"type":"object","properties":{"description":{"type":"string"},"method":{"type":"string"},"path":{"type":"string"}},"required":["description","method","path"]}}},"required":["data","next_steps"]}}}},"404":{"description":"Agent not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"fix":{"type":"string"},"request_id":{"type":"string"}},"required":["code","message","fix","request_id"]}},"required":["error"]}}}}}}},"/v1/agents/{id}/knowledge-bases":{"get":{"tags":["Knowledge Bases"],"summary":"List knowledge bases for an agent","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"Knowledge bases","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"agentId":{"type":"string","format":"uuid"},"tenantId":{"type":"string","format":"uuid"},"name":{"type":"string"},"description":{"type":"string","nullable":true},"createdAt":{"type":"string"}},"required":["id","agentId","tenantId","name","description","createdAt"]}}},"required":["data"]}}}},"404":{"description":"Agent not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"fix":{"type":"string"},"request_id":{"type":"string"}},"required":["code","message","fix","request_id"]}},"required":["error"]}}}}}},"post":{"tags":["Knowledge Bases"],"summary":"Create a knowledge base","description":"Creates a knowledge base for RAG. After creating, upload documents to it.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"id","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"example":"Product Documentation"},"description":{"type":"string","example":"All product docs and FAQs"}},"required":["name"]}}}},"responses":{"201":{"description":"Knowledge base created","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"agentId":{"type":"string","format":"uuid"},"tenantId":{"type":"string","format":"uuid"},"name":{"type":"string"},"description":{"type":"string","nullable":true},"createdAt":{"type":"string"}},"required":["id","agentId","tenantId","name","description","createdAt"]},"next_steps":{"type":"array","items":{"type":"object","properties":{"description":{"type":"string"},"method":{"type":"string"},"path":{"type":"string"}},"required":["description","method","path"]}}},"required":["data","next_steps"]}}}},"404":{"description":"Agent not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"fix":{"type":"string"},"request_id":{"type":"string"}},"required":["code","message","fix","request_id"]}},"required":["error"]}}}}}}},"/v1/agents/{id}/knowledge-bases/{kbId}/documents":{"get":{"tags":["Knowledge Bases"],"summary":"List documents in a knowledge base","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"id","in":"path"},{"schema":{"type":"string","format":"uuid"},"required":true,"name":"kbId","in":"path"}],"responses":{"200":{"description":"Documents","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"kbId":{"type":"string","format":"uuid"},"filename":{"type":"string"},"s3Url":{"type":"string"},"status":{"type":"string","enum":["processing","ready","error"]},"chunkCount":{"type":"number","nullable":true},"createdAt":{"type":"string"}},"required":["id","kbId","filename","s3Url","status","chunkCount","createdAt"]}}},"required":["data"]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"fix":{"type":"string"},"request_id":{"type":"string"}},"required":["code","message","fix","request_id"]}},"required":["error"]}}}}}},"post":{"tags":["Knowledge Bases"],"summary":"Upload a document","description":"Upload a document as plain text or base64-encoded file. Supported formats: PDF, DOCX, CSV, TXT, Markdown. The document will be chunked and embedded automatically.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"id","in":"path"},{"schema":{"type":"string","format":"uuid"},"required":true,"name":"kbId","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"filename":{"type":"string","example":"product-guide.md"},"content":{"type":"string","description":"Plain text content"},"base64":{"type":"string","description":"Base64-encoded file (for PDF, DOCX, etc.)"}},"required":["filename"]}}}},"responses":{"201":{"description":"Document uploaded","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"kbId":{"type":"string","format":"uuid"},"filename":{"type":"string"},"s3Url":{"type":"string"},"status":{"type":"string","enum":["processing","ready","error"]},"chunkCount":{"type":"number","nullable":true},"createdAt":{"type":"string"}},"required":["id","kbId","filename","s3Url","status","chunkCount","createdAt"]},"next_steps":{"type":"array","items":{"type":"object","properties":{"description":{"type":"string"},"method":{"type":"string"},"path":{"type":"string"}},"required":["description","method","path"]}}},"required":["data","next_steps"]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"fix":{"type":"string"},"request_id":{"type":"string"}},"required":["code","message","fix","request_id"]}},"required":["error"]}}}}}}},"/v1/agents/{id}/channels":{"get":{"tags":["Agent Configuration"],"summary":"Get agent channels config","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"Channels config","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"discord":{"type":"object","properties":{"botToken":{"type":"string"},"applicationId":{"type":"string"},"publicKey":{"type":"string"},"guildId":{"type":"string"},"channelId":{"type":"string"},"enabled":{"type":"boolean"}},"required":["botToken","applicationId","publicKey","guildId","channelId","enabled"]},"telegram":{"type":"object","properties":{"botToken":{"type":"string"},"enabled":{"type":"boolean"}},"required":["botToken","enabled"]},"whatsapp":{"type":"object","properties":{"accessToken":{"type":"string"},"appSecret":{"type":"string"},"phoneNumberId":{"type":"string"},"enabled":{"type":"boolean"}},"required":["accessToken","appSecret","phoneNumberId","enabled"]},"slack":{"type":"object","properties":{"botToken":{"type":"string"},"signingSecret":{"type":"string"},"enabled":{"type":"boolean"}},"required":["botToken","signingSecret","enabled"]}}}},"required":["data"]}}}},"404":{"description":"Agent not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"fix":{"type":"string"},"request_id":{"type":"string"}},"required":["code","message","fix","request_id"]}},"required":["error"]}}}}}},"put":{"tags":["Agent Configuration"],"summary":"Update agent channels config","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"id","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"discord":{"type":"object","properties":{"botToken":{"type":"string"},"applicationId":{"type":"string"},"publicKey":{"type":"string"},"guildId":{"type":"string"},"channelId":{"type":"string"},"enabled":{"type":"boolean"}},"required":["botToken","applicationId","publicKey","guildId","channelId","enabled"]},"telegram":{"type":"object","properties":{"botToken":{"type":"string"},"enabled":{"type":"boolean"}},"required":["botToken","enabled"]},"whatsapp":{"type":"object","properties":{"accessToken":{"type":"string"},"appSecret":{"type":"string"},"phoneNumberId":{"type":"string"},"enabled":{"type":"boolean"}},"required":["accessToken","appSecret","phoneNumberId","enabled"]},"slack":{"type":"object","properties":{"botToken":{"type":"string"},"signingSecret":{"type":"string"},"enabled":{"type":"boolean"}},"required":["botToken","signingSecret","enabled"]}}}}}},"responses":{"200":{"description":"Channels updated","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"discord":{"type":"object","properties":{"botToken":{"type":"string"},"applicationId":{"type":"string"},"publicKey":{"type":"string"},"guildId":{"type":"string"},"channelId":{"type":"string"},"enabled":{"type":"boolean"}},"required":["botToken","applicationId","publicKey","guildId","channelId","enabled"]},"telegram":{"type":"object","properties":{"botToken":{"type":"string"},"enabled":{"type":"boolean"}},"required":["botToken","enabled"]},"whatsapp":{"type":"object","properties":{"accessToken":{"type":"string"},"appSecret":{"type":"string"},"phoneNumberId":{"type":"string"},"enabled":{"type":"boolean"}},"required":["accessToken","appSecret","phoneNumberId","enabled"]},"slack":{"type":"object","properties":{"botToken":{"type":"string"},"signingSecret":{"type":"string"},"enabled":{"type":"boolean"}},"required":["botToken","signingSecret","enabled"]}}},"next_steps":{"type":"array","items":{"type":"object","properties":{"description":{"type":"string"},"method":{"type":"string"},"path":{"type":"string"}},"required":["description","method","path"]}}},"required":["data","next_steps"]}}}},"404":{"description":"Agent not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"fix":{"type":"string"},"request_id":{"type":"string"}},"required":["code","message","fix","request_id"]}},"required":["error"]}}}}}}},"/v1/agents/{id}/guardrails":{"get":{"tags":["Agent Configuration"],"summary":"Get agent guardrails config","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"Guardrails config","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"blockedTopics":{"type":"array","items":{"type":"string"}},"piiDetection":{"type":"boolean"},"maxInputLength":{"type":"number"},"maxOutputLength":{"type":"number"}},"required":["blockedTopics","piiDetection","maxInputLength","maxOutputLength"]}},"required":["data"]}}}},"404":{"description":"Agent not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"fix":{"type":"string"},"request_id":{"type":"string"}},"required":["code","message","fix","request_id"]}},"required":["error"]}}}}}},"put":{"tags":["Agent Configuration"],"summary":"Update agent guardrails config","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"id","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"blockedTopics":{"type":"array","items":{"type":"string"}},"piiDetection":{"type":"boolean"},"maxInputLength":{"type":"number"},"maxOutputLength":{"type":"number"}},"required":["blockedTopics","piiDetection","maxInputLength","maxOutputLength"]}}}},"responses":{"200":{"description":"Guardrails updated","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"blockedTopics":{"type":"array","items":{"type":"string"}},"piiDetection":{"type":"boolean"},"maxInputLength":{"type":"number"},"maxOutputLength":{"type":"number"}},"required":["blockedTopics","piiDetection","maxInputLength","maxOutputLength"]},"next_steps":{"type":"array","items":{"type":"object","properties":{"description":{"type":"string"},"method":{"type":"string"},"path":{"type":"string"}},"required":["description","method","path"]}}},"required":["data","next_steps"]}}}},"404":{"description":"Agent not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"fix":{"type":"string"},"request_id":{"type":"string"}},"required":["code","message","fix","request_id"]}},"required":["error"]}}}}}}},"/v1/agents/{id}/memory":{"get":{"tags":["Agent Configuration"],"summary":"Get agent memory config","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"Memory config","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"strategy":{"type":"string","enum":["sliding_window","summary"]},"windowSize":{"type":"number"}},"required":["strategy","windowSize"]}},"required":["data"]}}}},"404":{"description":"Agent not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"fix":{"type":"string"},"request_id":{"type":"string"}},"required":["code","message","fix","request_id"]}},"required":["error"]}}}}}},"put":{"tags":["Agent Configuration"],"summary":"Update agent memory config","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"id","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"strategy":{"type":"string","enum":["sliding_window","summary"]},"windowSize":{"type":"number"}},"required":["strategy","windowSize"]}}}},"responses":{"200":{"description":"Memory updated","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"strategy":{"type":"string","enum":["sliding_window","summary"]},"windowSize":{"type":"number"}},"required":["strategy","windowSize"]},"next_steps":{"type":"array","items":{"type":"object","properties":{"description":{"type":"string"},"method":{"type":"string"},"path":{"type":"string"}},"required":["description","method","path"]}}},"required":["data","next_steps"]}}}},"404":{"description":"Agent not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"fix":{"type":"string"},"request_id":{"type":"string"}},"required":["code","message","fix","request_id"]}},"required":["error"]}}}}}}},"/v1/agents/{id}/escalation":{"get":{"tags":["Agent Configuration"],"summary":"Get agent escalation config","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"Escalation config","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"webhookUrl":{"type":"string"},"autoEscalateKeywords":{"type":"array","items":{"type":"string"}},"assignedTo":{"type":"array","items":{"type":"string"}},"enabled":{"type":"boolean"}},"required":["webhookUrl","autoEscalateKeywords","assignedTo","enabled"]}},"required":["data"]}}}},"404":{"description":"Agent not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"fix":{"type":"string"},"request_id":{"type":"string"}},"required":["code","message","fix","request_id"]}},"required":["error"]}}}}}},"put":{"tags":["Agent Configuration"],"summary":"Update agent escalation config","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"id","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"webhookUrl":{"type":"string"},"autoEscalateKeywords":{"type":"array","items":{"type":"string"}},"assignedTo":{"type":"array","items":{"type":"string"}},"enabled":{"type":"boolean"}},"required":["webhookUrl","autoEscalateKeywords","assignedTo","enabled"]}}}},"responses":{"200":{"description":"Escalation updated","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"webhookUrl":{"type":"string"},"autoEscalateKeywords":{"type":"array","items":{"type":"string"}},"assignedTo":{"type":"array","items":{"type":"string"}},"enabled":{"type":"boolean"}},"required":["webhookUrl","autoEscalateKeywords","assignedTo","enabled"]},"next_steps":{"type":"array","items":{"type":"object","properties":{"description":{"type":"string"},"method":{"type":"string"},"path":{"type":"string"}},"required":["description","method","path"]}}},"required":["data","next_steps"]}}}},"404":{"description":"Agent not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"fix":{"type":"string"},"request_id":{"type":"string"}},"required":["code","message","fix","request_id"]}},"required":["error"]}}}}}}},"/v1/agents/{id}/evals":{"get":{"tags":["Evals"],"summary":"List eval suites for an agent","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"Eval suites","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"agentId":{"type":"string","format":"uuid"},"name":{"type":"string"},"testCases":{"type":"array","nullable":true,"items":{"type":"object","properties":{"input":{"type":"string"},"expectedOutput":{"type":"string","nullable":true},"criteria":{"type":"string"},"scorer":{"type":"string","enum":["llm-judge","exact-match","contains"]}},"required":["input","expectedOutput","criteria","scorer"]}},"lastRunAt":{"type":"string","nullable":true},"lastResult":{"type":"array","nullable":true,"items":{"type":"object","properties":{"testCaseIndex":{"type":"number"},"passed":{"type":"boolean"},"score":{"type":"number"},"response":{"type":"string"},"reasoning":{"type":"string","nullable":true}},"required":["testCaseIndex","passed","score","response","reasoning"]}},"createdAt":{"type":"string"}},"required":["id","agentId","name","testCases","lastRunAt","lastResult","createdAt"]}}},"required":["data"]}}}},"404":{"description":"Agent not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"fix":{"type":"string"},"request_id":{"type":"string"}},"required":["code","message","fix","request_id"]}},"required":["error"]}}}}}},"post":{"tags":["Evals"],"summary":"Create an eval suite","description":"Creates an eval suite with test cases. After creating, run it to evaluate the agent.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"id","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"example":"Core Q&A Tests"},"testCases":{"type":"array","items":{"type":"object","properties":{"input":{"type":"string"},"expectedOutput":{"type":"string","nullable":true},"criteria":{"type":"string"},"scorer":{"type":"string","enum":["llm-judge","exact-match","contains"]}},"required":["input","expectedOutput","criteria","scorer"]},"minItems":1,"example":[{"input":"What is your return policy?","expectedOutput":null,"criteria":"Mentions 30-day return window","scorer":"llm-judge"}]}},"required":["name","testCases"]}}}},"responses":{"201":{"description":"Eval suite created","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"agentId":{"type":"string","format":"uuid"},"name":{"type":"string"},"testCases":{"type":"array","nullable":true,"items":{"type":"object","properties":{"input":{"type":"string"},"expectedOutput":{"type":"string","nullable":true},"criteria":{"type":"string"},"scorer":{"type":"string","enum":["llm-judge","exact-match","contains"]}},"required":["input","expectedOutput","criteria","scorer"]}},"lastRunAt":{"type":"string","nullable":true},"lastResult":{"type":"array","nullable":true,"items":{"type":"object","properties":{"testCaseIndex":{"type":"number"},"passed":{"type":"boolean"},"score":{"type":"number"},"response":{"type":"string"},"reasoning":{"type":"string","nullable":true}},"required":["testCaseIndex","passed","score","response","reasoning"]}},"createdAt":{"type":"string"}},"required":["id","agentId","name","testCases","lastRunAt","lastResult","createdAt"]},"next_steps":{"type":"array","items":{"type":"object","properties":{"description":{"type":"string"},"method":{"type":"string"},"path":{"type":"string"}},"required":["description","method","path"]}}},"required":["data","next_steps"]}}}},"404":{"description":"Agent not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"fix":{"type":"string"},"request_id":{"type":"string"}},"required":["code","message","fix","request_id"]}},"required":["error"]}}}}}}},"/v1/agents/{id}/evals/{suiteId}/run":{"post":{"tags":["Evals"],"summary":"Run an eval suite","description":"Executes all test cases in the eval suite against the agent and returns scored results.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"id","in":"path"},{"schema":{"type":"string","format":"uuid"},"required":true,"name":"suiteId","in":"path"}],"responses":{"200":{"description":"Eval results","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"testCaseIndex":{"type":"number"},"passed":{"type":"boolean"},"score":{"type":"number"},"response":{"type":"string"},"reasoning":{"type":"string","nullable":true}},"required":["testCaseIndex","passed","score","response","reasoning"]}}},"required":["data"]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"fix":{"type":"string"},"request_id":{"type":"string"}},"required":["code","message","fix","request_id"]}},"required":["error"]}}}}}}},"/v1/agents/{id}/logs":{"get":{"tags":["Logs & Stats"],"summary":"List request logs for an agent","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"id","in":"path"},{"schema":{"type":"number","minimum":1,"maximum":100,"default":50},"required":false,"name":"limit","in":"query"},{"schema":{"type":"number","nullable":true,"minimum":0,"default":0},"required":false,"name":"offset","in":"query"}],"responses":{"200":{"description":"Request logs","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"agentId":{"type":"string","format":"uuid"},"tenantId":{"type":"string","format":"uuid"},"model":{"type":"string"},"tokensIn":{"type":"number"},"tokensOut":{"type":"number"},"cost":{"type":"string"},"latencyMs":{"type":"number","nullable":true},"status":{"type":"string"},"error":{"type":"string","nullable":true},"createdAt":{"type":"string"}},"required":["id","agentId","tenantId","model","tokensIn","tokensOut","cost","latencyMs","status","error","createdAt"]}}},"required":["data"]}}}},"404":{"description":"Agent not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"fix":{"type":"string"},"request_id":{"type":"string"}},"required":["code","message","fix","request_id"]}},"required":["error"]}}}}}}},"/v1/agents/{id}/stats":{"get":{"tags":["Logs & Stats"],"summary":"Get aggregated stats for an agent","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"id","in":"path"},{"schema":{"type":"string","description":"ISO date (default: 30 days ago)","example":"2026-02-20T00:00:00Z"},"required":false,"description":"ISO date (default: 30 days ago)","name":"from","in":"query"},{"schema":{"type":"string","description":"ISO date (default: now)","example":"2026-03-22T00:00:00Z"},"required":false,"description":"ISO date (default: now)","name":"to","in":"query"}],"responses":{"200":{"description":"Agent stats","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"totalCost":{"type":"number"},"totalTokensIn":{"type":"number"},"totalTokensOut":{"type":"number"},"totalRequests":{"type":"number"},"errorCount":{"type":"number"},"avgLatencyMs":{"type":"number"},"p95LatencyMs":{"type":"number"}},"required":["totalCost","totalTokensIn","totalTokensOut","totalRequests","errorCount","avgLatencyMs","p95LatencyMs"]}},"required":["data"]}}}},"404":{"description":"Agent not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"fix":{"type":"string"},"request_id":{"type":"string"}},"required":["code","message","fix","request_id"]}},"required":["error"]}}}}}}},"/v1/agents/{id}/conversations/{conversationId}":{"delete":{"tags":["Conversations"],"summary":"Delete a single conversation","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"id","in":"path"},{"schema":{"type":"string","format":"uuid"},"required":true,"name":"conversationId","in":"path"}],"responses":{"200":{"description":"Conversation deleted","content":{"application/json":{"schema":{"type":"object","properties":{"deleted":{"type":"boolean"}},"required":["deleted"]}}}},"404":{"description":"Agent or conversation not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"fix":{"type":"string"},"request_id":{"type":"string"}},"required":["code","message","fix","request_id"]}},"required":["error"]}}}}}}},"/v1/agents/{id}/conversations":{"delete":{"tags":["Conversations"],"summary":"Delete all conversations for an agent","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"Conversations deleted","content":{"application/json":{"schema":{"type":"object","properties":{"deletedCount":{"type":"number"}},"required":["deletedCount"]}}}},"404":{"description":"Agent not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"fix":{"type":"string"},"request_id":{"type":"string"}},"required":["code","message","fix","request_id"]}},"required":["error"]}}}}}}},"/v1/chat":{"post":{"tags":["Chat"],"summary":"Send a message to an agent","description":"Send a message and receive a complete response. Use /chat-stream for streaming.","security":[{"bearerAuth":[]}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"agent_id":{"type":"string","format":"uuid","example":"550e8400-e29b-41d4-a716-446655440000"},"message":{"type":"string","minLength":1,"example":"Hello, how can you help me?"},"conversation_id":{"type":"string","format":"uuid","description":"Continue an existing conversation"}},"required":["agent_id","message"]}}}},"responses":{"200":{"description":"Chat response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"conversation_id":{"type":"string","format":"uuid"},"text":{"type":"string"},"usage":{"type":"object","properties":{"promptTokens":{"type":"number"},"completionTokens":{"type":"number"}},"required":["promptTokens","completionTokens"]}},"required":["conversation_id","text","usage"]}},"required":["data"]}}}},"400":{"description":"Missing fields","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"fix":{"type":"string"},"request_id":{"type":"string"}},"required":["code","message","fix","request_id"]}},"required":["error"]}}}},"404":{"description":"Agent not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"fix":{"type":"string"},"request_id":{"type":"string"}},"required":["code","message","fix","request_id"]}},"required":["error"]}}}}}}},"/v1/chat-stream":{"post":{"tags":["Chat"],"summary":"Send a message to an agent (streaming)","description":"Send a message and receive a streaming SSE response.","security":[{"bearerAuth":[]}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"agent_id":{"type":"string","format":"uuid","example":"550e8400-e29b-41d4-a716-446655440000"},"message":{"type":"string","minLength":1,"example":"Hello, how can you help me?"},"conversation_id":{"type":"string","format":"uuid","description":"Continue an existing conversation"}},"required":["agent_id","message"]}}}},"responses":{"200":{"description":"SSE stream","content":{"text/event-stream":{"schema":{"nullable":true}}}},"400":{"description":"Missing fields","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"fix":{"type":"string"},"request_id":{"type":"string"}},"required":["code","message","fix","request_id"]}},"required":["error"]}}}},"404":{"description":"Agent not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"fix":{"type":"string"},"request_id":{"type":"string"}},"required":["code","message","fix","request_id"]}},"required":["error"]}}}}}}}}}