{"openapi":"3.1.0","info":{"title":"AI Chatbot Engine API","version":"1.0.0","description":"Auth: `Authorization: Bearer sk_live_…` (an organization API key, created in\nSettings → API keys). A key reaches only its organization's data, through the same\ntenant repositories as the console, and only what its scopes allow:\nchat, knowledge:read, knowledge:write, conversations:read, leads:read.\n\nConventions:\n- Lists are newest first with cursor pagination: `?limit=` (1–100) and `?after=<last id>`;\n  responses have `data`, `has_more` and `next_cursor`.\n- POSTs accept an `Idempotency-Key` header: the first response is replayed for 24 hours\n  (not for streamed chat).\n- Errors: `{\"error\": {\"type\", \"code\", \"message\", \"request_id\"}}`.\n- Every response carries `X-RateLimit-Limit`, `-Remaining` and `-Reset` (60 requests a\n  minute per key).\n"},"servers":[{"url":"https://aichatbotengine.com"}],"paths":{"/v1/agents":{"get":{"tags":["developer-api"],"summary":"List assistants","operationId":"list_agents_v1_agents_get","parameters":[{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":100,"minimum":1,"default":25,"title":"Limit"}},{"name":"after","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"After"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/src__api__routes__developer__AgentList"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/agents/{agent_id}":{"get":{"tags":["developer-api"],"summary":"Get an assistant","operationId":"get_agent_v1_agents__agent_id__get","parameters":[{"name":"agent_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Agent Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Agent"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/agents/{agent_id}/chat":{"post":{"tags":["developer-api"],"summary":"Ask an assistant","description":"Answers from the **published** version. Counts as a visitor message against your plan.","operationId":"chat_v1_agents__agent_id__chat_post","parameters":[{"name":"agent_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Agent Id"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/src__api__routes__developer__ChatRequest"}}}},"responses":{"200":{"description":"JSON, or SSE with stream=true","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ChatResponse"}},"text/event-stream":{}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/agents/{agent_id}/sources":{"get":{"tags":["developer-api"],"summary":"List an assistant's sources","operationId":"list_sources_v1_agents__agent_id__sources_get","parameters":[{"name":"agent_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Agent Id"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":100,"minimum":1,"default":25,"title":"Limit"}},{"name":"after","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"After"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/src__api__routes__developer__SourceList"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}},"post":{"tags":["developer-api"],"summary":"Add a source","description":"A `website` source starts reading at once; `text` and `qa` sources are filled with POST /sources/{id}/documents.","operationId":"create_source_v1_agents__agent_id__sources_post","parameters":[{"name":"agent_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Agent Id"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/src__api__routes__developer__SourceCreate"}}}},"responses":{"201":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Source"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/sources/{source_id}/sync":{"post":{"tags":["developer-api"],"summary":"Re-read a source","operationId":"sync_source_v1_sources__source_id__sync_post","parameters":[{"name":"source_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Source Id"}}],"responses":{"202":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SyncStarted"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/sources/{source_id}/documents":{"post":{"tags":["developer-api"],"summary":"Add text, Markdown or a Q&A pair","description":"Send `{title, body}` to a text source, or `{question, answer, alternates}` to a Q&A source.\nIt is read within seconds.","operationId":"add_document_v1_sources__source_id__documents_post","parameters":[{"name":"source_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Source Id"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/QADocument"},{"$ref":"#/components/schemas/src__api__routes__developer__TextDocument"}],"title":"Body"}}}},"responses":{"201":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/src__api__routes__developer__DocumentCreated"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/agents/{agent_id}/conversations":{"get":{"tags":["developer-api"],"summary":"List conversations","operationId":"list_conversations_v1_agents__agent_id__conversations_get","parameters":[{"name":"agent_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Agent Id"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":100,"minimum":1,"default":25,"title":"Limit"}},{"name":"after","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"After"}},{"name":"channel","in":"query","required":false,"schema":{"anyOf":[{"enum":["web","api"],"type":"string"},{"type":"null"}],"title":"Channel"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/src__api__routes__developer__ConversationList"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/conversations/{conversation_id}/messages":{"get":{"tags":["developer-api"],"summary":"Read a conversation","description":"Oldest first; `after` is the last message id you have.","operationId":"list_messages_v1_conversations__conversation_id__messages_get","parameters":[{"name":"conversation_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Conversation Id"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":100,"minimum":1,"default":100,"title":"Limit"}},{"name":"after","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"After"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MessageList"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/conversations/{conversation_id}/actions/{action_id}/{decision}":{"post":{"tags":["developer-api"],"summary":"Confirm or cancel an action","description":"Your user's answer to an `action_confirmation`. On confirm the action runs and the reply\nsays how it went.","operationId":"resolve_action_v1_conversations__conversation_id__actions__action_id___decision__post","parameters":[{"name":"conversation_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Conversation Id"}},{"name":"action_id","in":"path","required":true,"schema":{"type":"string","title":"Action Id"}},{"name":"decision","in":"path","required":true,"schema":{"enum":["confirm","cancel"],"type":"string","title":"Decision"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ChatResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/conversations/{conversation_id}/messages/{message_id}/feedback":{"post":{"tags":["developer-api"],"summary":"Rate an answer","description":"Your user's thumbs up or down on an answer in an API conversation. Shows in the inbox and\nsends the `message.feedback` webhook.","operationId":"message_feedback_v1_conversations__conversation_id__messages__message_id__feedback_post","parameters":[{"name":"conversation_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Conversation Id"}},{"name":"message_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Message Id"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/FeedbackIn"}}}},"responses":{"204":{"description":"Successful Response"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/agents/{agent_id}/leads":{"get":{"tags":["developer-api"],"summary":"List leads","operationId":"list_leads_v1_agents__agent_id__leads_get","parameters":[{"name":"agent_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Agent Id"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":100,"minimum":1,"default":25,"title":"Limit"}},{"name":"after","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"After"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/src__api__routes__developer__LeadList"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}},"components":{"schemas":{"ActionConfirmation":{"properties":{"id":{"type":"string","title":"Id","description":"Pass to /conversations/{id}/actions/{action_id}/confirm or /cancel."},"action":{"type":"string","title":"Action"},"description":{"type":"string","title":"Description"},"arguments":{"additionalProperties":true,"type":"object","title":"Arguments"}},"type":"object","required":["id","action","description","arguments"],"title":"ActionConfirmation"},"Agent":{"properties":{"id":{"type":"string","format":"uuid","title":"Id"},"name":{"type":"string","title":"Name"},"published_version":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Published Version"},"has_unpublished_changes":{"type":"boolean","title":"Has Unpublished Changes"},"created_at":{"type":"string","format":"date-time","title":"Created At"}},"type":"object","required":["id","name","has_unpublished_changes","created_at"],"title":"Agent"},"ChatResponse":{"properties":{"conversation_id":{"type":"string","format":"uuid","title":"Conversation Id"},"message_id":{"type":"string","format":"uuid","title":"Message Id"},"answer":{"type":"string","title":"Answer"},"citations":{"items":{"$ref":"#/components/schemas/Citation"},"type":"array","title":"Citations"},"usage":{"$ref":"#/components/schemas/ChatUsage"},"latency_ms":{"type":"integer","title":"Latency Ms"},"action_confirmation":{"anyOf":[{"$ref":"#/components/schemas/ActionConfirmation"},{"type":"null"}],"description":"An action waiting for your user's OK (actions with requires_confirmation)."}},"type":"object","required":["conversation_id","message_id","answer","citations","usage","latency_ms"],"title":"ChatResponse"},"ChatUsage":{"properties":{"tokens_in":{"type":"integer","title":"Tokens In"},"tokens_out":{"type":"integer","title":"Tokens Out"}},"type":"object","required":["tokens_in","tokens_out"],"title":"ChatUsage"},"Citation":{"properties":{"n":{"type":"integer","title":"N"},"title":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Title"},"url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Url"},"heading_path":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Heading Path"},"page":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Page"},"document_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Document Id"},"snippet":{"type":"string","title":"Snippet"}},"type":"object","required":["n","snippet"],"title":"Citation"},"Conversation":{"properties":{"id":{"type":"string","format":"uuid","title":"Id"},"agent_id":{"type":"string","format":"uuid","title":"Agent Id"},"channel":{"type":"string","title":"Channel"},"status":{"type":"string","title":"Status"},"external_user_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"External User Id"},"visitor":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Visitor"},"lead_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Lead Id"},"message_count":{"type":"integer","title":"Message Count"},"started_at":{"type":"string","format":"date-time","title":"Started At"},"last_message_at":{"type":"string","format":"date-time","title":"Last Message At"}},"type":"object","required":["id","agent_id","channel","status","message_count","started_at","last_message_at"],"title":"Conversation"},"FeedbackIn":{"properties":{"rating":{"type":"integer","enum":[-1,1],"title":"Rating","description":"1 helpful, -1 not helpful"},"reason":{"anyOf":[{"type":"string","maxLength":500},{"type":"null"}],"title":"Reason","description":"What was wrong (with -1)"}},"type":"object","required":["rating"],"title":"FeedbackIn"},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"Lead":{"properties":{"id":{"type":"string","format":"uuid","title":"Id"},"agent_id":{"type":"string","format":"uuid","title":"Agent Id"},"conversation_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Conversation Id"},"fields":{"additionalProperties":true,"type":"object","title":"Fields"},"status":{"type":"string","title":"Status"},"consent_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Consent At"},"via":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Via"},"created_at":{"type":"string","format":"date-time","title":"Created At"}},"type":"object","required":["id","agent_id","fields","status","created_at"],"title":"Lead"},"Message":{"properties":{"id":{"type":"string","format":"uuid","title":"Id"},"role":{"type":"string","enum":["user","assistant"],"title":"Role"},"content":{"type":"string","title":"Content"},"citations":{"items":{},"type":"array","title":"Citations"},"created_at":{"type":"string","format":"date-time","title":"Created At"}},"type":"object","required":["id","role","content","citations","created_at"],"title":"Message"},"MessageList":{"properties":{"data":{"items":{"$ref":"#/components/schemas/Message"},"type":"array","title":"Data"},"has_more":{"type":"boolean","title":"Has More"},"next_cursor":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Next Cursor"}},"type":"object","required":["data","has_more"],"title":"MessageList"},"QADocument":{"properties":{"question":{"type":"string","maxLength":1000,"minLength":1,"title":"Question"},"answer":{"type":"string","maxLength":10000,"minLength":1,"title":"Answer"},"alternates":{"items":{"type":"string"},"type":"array","maxItems":20,"title":"Alternates"}},"type":"object","required":["question","answer"],"title":"QADocument","description":"For a `qa` source: a question and the exact answer to give."},"Source":{"properties":{"id":{"type":"string","format":"uuid","title":"Id"},"type":{"type":"string","title":"Type"},"name":{"type":"string","title":"Name"},"status":{"type":"string","title":"Status"},"enabled":{"type":"boolean","title":"Enabled"},"documents_total":{"type":"integer","title":"Documents Total"},"indexed":{"type":"integer","title":"Indexed"},"failed":{"type":"integer","title":"Failed"},"last_synced_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Last Synced At"},"created_at":{"type":"string","format":"date-time","title":"Created At"}},"type":"object","required":["id","type","name","status","enabled","documents_total","indexed","failed","created_at"],"title":"Source"},"SyncStarted":{"properties":{"sync_id":{"type":"string","format":"uuid","title":"Sync Id"}},"type":"object","required":["sync_id"],"title":"SyncStarted"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"},"WebsiteSourceConfig":{"properties":{"url":{"type":"string","maxLength":2083,"minLength":1,"format":"uri","title":"Url"},"max_pages":{"anyOf":[{"type":"integer","maximum":10000.0,"minimum":1.0},{"type":"null"}],"title":"Max Pages"}},"type":"object","required":["url"],"title":"WebsiteSourceConfig"},"src__api__routes__developer__AgentList":{"properties":{"data":{"items":{"$ref":"#/components/schemas/Agent"},"type":"array","title":"Data"},"has_more":{"type":"boolean","title":"Has More"},"next_cursor":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Next Cursor"}},"type":"object","required":["data","has_more"],"title":"AgentList"},"src__api__routes__developer__ChatRequest":{"properties":{"message":{"type":"string","maxLength":2000,"minLength":1,"title":"Message"},"conversation_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Conversation Id","description":"Continue a conversation started by the same user."},"external_user_id":{"anyOf":[{"type":"string","maxLength":200},{"type":"null"}],"title":"External User Id","description":"Your id for the person chatting; conversations are kept per user."},"stream":{"type":"boolean","title":"Stream","description":"Stream the answer as Server-Sent Events instead of one JSON response.","default":false}},"type":"object","required":["message"],"title":"ChatRequest"},"src__api__routes__developer__ConversationList":{"properties":{"data":{"items":{"$ref":"#/components/schemas/Conversation"},"type":"array","title":"Data"},"has_more":{"type":"boolean","title":"Has More"},"next_cursor":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Next Cursor"}},"type":"object","required":["data","has_more"],"title":"ConversationList"},"src__api__routes__developer__DocumentCreated":{"properties":{"id":{"type":"string","format":"uuid","title":"Id"},"status":{"type":"string","title":"Status","default":"pending"}},"type":"object","required":["id"],"title":"DocumentCreated"},"src__api__routes__developer__LeadList":{"properties":{"data":{"items":{"$ref":"#/components/schemas/Lead"},"type":"array","title":"Data"},"has_more":{"type":"boolean","title":"Has More"},"next_cursor":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Next Cursor"}},"type":"object","required":["data","has_more"],"title":"LeadList"},"src__api__routes__developer__SourceCreate":{"properties":{"type":{"type":"string","enum":["website","text","qa"],"title":"Type"},"name":{"type":"string","maxLength":200,"minLength":1,"title":"Name"},"website":{"anyOf":[{"$ref":"#/components/schemas/WebsiteSourceConfig"},{"type":"null"}]}},"type":"object","required":["type","name"],"title":"SourceCreate"},"src__api__routes__developer__SourceList":{"properties":{"data":{"items":{"$ref":"#/components/schemas/Source"},"type":"array","title":"Data"},"has_more":{"type":"boolean","title":"Has More"},"next_cursor":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Next Cursor"}},"type":"object","required":["data","has_more"],"title":"SourceList"},"src__api__routes__developer__TextDocument":{"properties":{"title":{"type":"string","maxLength":300,"minLength":1,"title":"Title"},"body":{"type":"string","maxLength":200000,"minLength":1,"title":"Body"}},"type":"object","required":["title","body"],"title":"TextDocument","description":"For a `text` source: plain text or Markdown."}},"securitySchemes":{"apiKey":{"type":"http","scheme":"bearer","description":"An organization API key: sk_live_…"}}},"security":[{"apiKey":[]}]}