{"openapi":"3.1.0","info":{"title":"OrbContext REST API","version":"1.0.0","description":"Server-to-server access using scoped API keys created by a workspace owner/admin. API keys do not grant access to dashboard-only routes. Uploads, chat and search requests are not idempotent and may consume credits; do not automatically retry them."},"servers":[{"url":"/"}],"paths":{"/v1/bots":{"get":{"summary":"List permitted bots","description":"Requires the bots:read scope and access to the requested bot.","x-required-scope":"bots:read","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Only bots permitted by this key.","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/Bot"}}}}},"400":{"description":"Request failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Request failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Request failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Request failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Request failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Request failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"415":{"description":"Request failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate, concurrency or monthly quota limit; respect Retry-After.","headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds to wait."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Request failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Request failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/bots/{botId}":{"parameters":[{"name":"botId","in":"path","required":true,"schema":{"type":"string","example":"b_your_bot_id"}}],"get":{"summary":"Get a bot","description":"Requires the bots:read scope and access to the requested bot.","x-required-scope":"bots:read","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Bot settings.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Bot"}}}},"400":{"description":"Request failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Request failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Request failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Request failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Request failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Request failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"415":{"description":"Request failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate, concurrency or monthly quota limit; respect Retry-After.","headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds to wait."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Request failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Request failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/bots/{botId}/documents":{"parameters":[{"name":"botId","in":"path","required":true,"schema":{"type":"string","example":"b_your_bot_id"}}],"get":{"summary":"List documents and ingestion status","description":"Requires the documents:read scope and access to the requested bot.","x-required-scope":"documents:read","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Cursor-paginated documents.","content":{"application/json":{"schema":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/Document"}},"nextCursor":{"type":["string","null"]}},"required":["items","nextCursor"]}}}},"400":{"description":"Request failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Request failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Request failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Request failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Request failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Request failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"415":{"description":"Request failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate, concurrency or monthly quota limit; respect Retry-After.","headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds to wait."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Request failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Request failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":50}},{"name":"cursor","in":"query","schema":{"type":"string","format":"date-time"}}]},"post":{"summary":"Upload one knowledge document","description":"Requires the documents:write scope and access to the requested bot.","x-required-scope":"documents:write","security":[{"bearerAuth":[]}],"responses":{"202":{"description":"Queued; poll the document until ready or failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Document"}}}},"400":{"description":"Request failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Request failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Request failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Request failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Request failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Request failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"415":{"description":"Request failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate, concurrency or monthly quota limit; respect Retry-After.","headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds to wait."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Request failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Request failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"type":"object","required":["file"],"properties":{"file":{"type":"string","format":"binary","description":"PDF, DOCX, TXT, Markdown or CSV. Size and document count are limited by the workspace plan."}}}}}}}},"/v1/documents/{documentId}":{"parameters":[{"name":"documentId","in":"path","required":true,"schema":{"type":"string","example":"d_your_document_id"}}],"get":{"summary":"Get ingestion status","description":"Requires the documents:read scope and access to the requested bot.","x-required-scope":"documents:read","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Document metadata, no source content.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Document"}}}},"400":{"description":"Request failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Request failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Request failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Request failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Request failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Request failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"415":{"description":"Request failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate, concurrency or monthly quota limit; respect Retry-After.","headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds to wait."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Request failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Request failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"summary":"Remove a document","description":"Requires the documents:write scope and access to the requested bot.","x-required-scope":"documents:write","security":[{"bearerAuth":[]}],"responses":{"202":{"description":"Deletion queued.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Document"}}}},"400":{"description":"Request failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Request failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Request failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Request failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Request failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Request failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"415":{"description":"Request failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate, concurrency or monthly quota limit; respect Retry-After.","headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds to wait."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Request failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Request failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/documents/{documentId}/refresh":{"parameters":[{"name":"documentId","in":"path","required":true,"schema":{"type":"string","example":"d_your_document_id"}}],"post":{"summary":"Refresh a website document","description":"Requires the documents:write scope and access to the requested bot.","x-required-scope":"documents:write","security":[{"bearerAuth":[]}],"responses":{"202":{"description":"Re-crawl queued. The current version keeps answering (`refreshing: true`) until the new one is ready; a failed refresh leaves it in place. Website documents only, at most once an hour.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Document"}}}},"400":{"description":"Request failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Request failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Request failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Request failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Request failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Request failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"415":{"description":"Request failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate, concurrency or monthly quota limit; respect Retry-After.","headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds to wait."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Request failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Request failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/bots/{botId}/knowledge/search":{"parameters":[{"name":"botId","in":"path","required":true,"schema":{"type":"string","example":"b_your_bot_id"}}],"post":{"summary":"Search knowledge passages","description":"Requires the knowledge:read scope and access to the requested bot. `audience` must be allowed for the key; omitted means public knowledge only. `location` narrows results and never grants access.","x-required-scope":"knowledge:read","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Authorized passages from ready, current documents, best first. An empty `hits` array is a successful no-match. No answer is generated and no conversation is created. Each successful call consumes credits; a failed call is refunded. Not retried automatically by the SDK.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/KnowledgeSearchResponse"}}}},"400":{"description":"Request failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Request failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Request failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Request failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Request failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Request failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"415":{"description":"Request failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate, concurrency or monthly quota limit; respect Retry-After.","headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds to wait."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Request failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Request failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/KnowledgeSearchRequest"}}}}}},"/v1/bots/{botId}/suggestions":{"parameters":[{"name":"botId","in":"path","required":true,"schema":{"type":"string","example":"b_your_bot_id"}}],"get":{"summary":"Get suggested questions","description":"Requires the chat:write scope and access to the requested bot.","x-required-scope":"chat:write","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Starter questions.","content":{"application/json":{"schema":{"type":"object","properties":{"questions":{"type":"array","items":{"type":"string"}}},"required":["questions"]}}}},"400":{"description":"Request failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Request failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Request failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Request failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Request failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Request failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"415":{"description":"Request failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate, concurrency or monthly quota limit; respect Retry-After.","headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds to wait."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Request failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Request failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/chat":{"post":{"summary":"Stream a grounded chat answer","description":"Requires the chat:write scope and access to the requested bot.","x-required-scope":"chat:write","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"SSE frames: started, token, done, error. Parse complete frames across transport chunks. Sources and diagnostics are never included. HTTP errors occur before streaming begins; an error frame after streaming begins terminates the answer. Continuations must use the same key and bot. Streams time out after 120 seconds.","content":{"text/event-stream":{"schema":{"type":"string"},"x-event-schemas":{"started":{"$ref":"#/components/schemas/ChatStarted"},"token":{"$ref":"#/components/schemas/ChatToken"},"done":{"$ref":"#/components/schemas/ChatDone"},"error":{"$ref":"#/components/schemas/ChatError"}},"example":"event: started\ndata: {\"type\":\"started\",\"conversationId\":\"c_example\",\"messageId\":\"m_answer\",\"userMessageId\":\"m_question\"}\n\nevent: token\ndata: {\"type\":\"token\",\"value\":\"Hello!\"}\n\nevent: done\ndata: {\"type\":\"done\",\"conversationId\":\"c_example\",\"messageId\":\"m_answer\",\"tokensIn\":120,\"tokensOut\":18,\"latencyMs\":350}\n\n"}}},"400":{"description":"Request failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Request failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Request failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Request failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Request failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Request failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"415":{"description":"Request failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate, concurrency or monthly quota limit; respect Retry-After.","headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds to wait."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Request failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Request failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ChatRequest"}}}}}}},"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"OrbContext secret API key","description":"Server-side secret. Available scopes: bots:read, documents:read, documents:write, chat:write, knowledge:read."}},"schemas":{"Document":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"id":{"type":"string"},"botId":{"type":"string"},"name":{"type":"string"},"type":{"type":"string","enum":["pdf","docx","txt","csv","url","qa","api","sheet"]},"status":{"type":"string","enum":["ocr","queued","parsing","embedding","ready","failed","deleting"]},"chunkCount":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"tokenCount":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"sizeBytes":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"error":{"type":["string","null"]},"sourceUrl":{"type":["string","null"]},"crawledPages":{"type":"array","items":{"type":"string"}},"refreshing":{"type":"boolean"},"effectiveFrom":{"type":["string","null"]},"effectiveUntil":{"type":["string","null"]},"replacesDocumentId":{"type":["string","null"]},"location":{"type":"string"},"audience":{"type":"string"},"sheet":{"anyOf":[{"type":"object","properties":{"lastChangedAt":{"type":["string","null"]},"lastError":{"type":["string","null"]},"manifest":{"anyOf":[{"type":"object","properties":{"tabs":{"type":"array","items":{"type":"object","properties":{"gid":{"type":"string"},"title":{"type":"string"},"range":{"type":["string","null"]},"rows":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"columnsTruncated":{"type":"boolean"}},"required":["gid","title","range","rows","columnsTruncated"],"additionalProperties":false}},"skipped":{"type":"array","items":{"type":"object","properties":{"gid":{"type":"string"},"title":{"type":"string"},"reason":{"type":"string","enum":["hidden","not_linked","tab_limit"]}},"required":["gid","title","reason"],"additionalProperties":false}},"truncated":{"type":"boolean"},"sourceHash":{"type":"string"},"billedPages":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["tabs","skipped","truncated","sourceHash","billedPages"],"additionalProperties":false},{"type":"null"}]}},"required":["lastChangedAt","lastError","manifest"],"additionalProperties":false},{"type":"null"}]},"resync":{"type":"string","enum":["off","hourly","daily","weekly"]},"lastSyncedAt":{"type":["string","null"]},"nextSyncAt":{"type":["string","null"]},"createdAt":{"type":"string"},"ocr":{"anyOf":[{"type":"object","properties":{"totalPages":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"completed":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"langs":{"type":"string"}},"required":["totalPages","completed","langs"],"additionalProperties":false},{"type":"null"}]}},"required":["id","botId","name","type","status","chunkCount","tokenCount","sizeBytes","error","sourceUrl","crawledPages","refreshing","effectiveFrom","effectiveUntil","replacesDocumentId","location","audience","sheet","resync","lastSyncedAt","nextSyncAt","createdAt","ocr"],"additionalProperties":false,"example":{"id":"d_your_document_id","botId":"b_your_bot_id","name":"knowledge.txt","type":"txt","status":"ready","chunkCount":8,"tokenCount":1500,"sizeBytes":4200,"error":null,"sourceUrl":null,"crawledPages":[],"refreshing":false,"effectiveFrom":null,"effectiveUntil":null,"replacesDocumentId":null,"location":"","audience":"","sheet":null,"resync":"weekly","lastSyncedAt":null,"nextSyncAt":null,"createdAt":"2026-10-21T10:00:00.000Z","ocr":null}},"Bot":{"example":{"id":"b_your_bot_id","name":"Support assistant","persona":"Be helpful and concise.","model":"default","temperature":0.2,"fallbackMessage":"I could not find that in the available knowledge.","suggestedQuestions":["How can you help?"],"useCase":"support","websiteUrl":null,"hasLogo":false,"createdAt":"2026-10-21T10:00:00.000Z"},"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"persona":{"type":"string"},"model":{"type":"string"},"temperature":{"type":"number"},"fallbackMessage":{"type":"string"},"suggestedQuestions":{"type":"array","items":{"type":"string"}},"useCase":{"type":["string","null"]},"websiteUrl":{"type":["string","null"]},"hasLogo":{"type":"boolean"},"createdAt":{"type":"string","format":"date-time"}},"required":["id","name","persona","model","temperature","fallbackMessage","suggestedQuestions","useCase","websiteUrl","hasLogo","createdAt"]},"ChatRequest":{"type":"object","required":["botId","message"],"properties":{"botId":{"type":"string","minLength":1,"description":"A bot permitted by this API key.","example":"b_your_bot_id"},"message":{"type":"string","minLength":1,"maxLength":4000,"description":"Your question. Leading and trailing whitespace is trimmed.","example":"How can you help?"},"conversationId":{"type":"string","minLength":1,"description":"Optional. Continue a conversation created by this key and bot."},"location":{"type":"string","maxLength":80,"description":"Optional. Narrows retrieval to unscoped knowledge plus this location."},"audience":{"type":"string","maxLength":80,"description":"Optional. Must be allowed for this key; omitted means public knowledge only."}}},"KnowledgeSearchRequest":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"query":{"type":"string","minLength":1,"maxLength":4000},"limit":{"default":5,"type":"integer","minimum":1,"maximum":20},"location":{"type":"string","minLength":1,"maxLength":80},"audience":{"type":"string","minLength":1,"maxLength":80}},"required":["query"],"additionalProperties":false},"KnowledgeSearchResponse":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"hits":{"maxItems":20,"type":"array","items":{"type":"object","properties":{"chunkId":{"type":"string","minLength":1},"documentId":{"type":"string","minLength":1},"text":{"type":"string","maxLength":4000},"headingPath":{"anyOf":[{"type":"string","maxLength":512},{"type":"null"}]},"page":{"anyOf":[{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991},{"type":"null"}]}},"required":["chunkId","documentId","text","headingPath","page"],"additionalProperties":false}},"requestId":{"type":"string","minLength":1}},"required":["hits","requestId"],"additionalProperties":false,"example":{"hits":[{"chunkId":"k_example","documentId":"d_your_document_id","text":"Employees receive 12 days of paid sick leave each year.","headingPath":"Leave > Sick leave","page":null}],"requestId":"req_example"}},"ChatStarted":{"type":"object","required":["type","conversationId","messageId","userMessageId"],"properties":{"type":{"const":"started","type":"string"},"conversationId":{"type":"string","example":"c_example"},"messageId":{"type":"string","example":"m_answer"},"userMessageId":{"type":"string","example":"m_question"}}},"ChatToken":{"type":"object","required":["type","value"],"properties":{"type":{"const":"token","type":"string"},"value":{"type":"string","description":"Append this answer fragment.","example":"Hello! How can I help?"}}},"ChatDone":{"type":"object","required":["type","conversationId","messageId","tokensIn","tokensOut","latencyMs","refused"],"properties":{"type":{"const":"done","type":"string"},"conversationId":{"type":"string","example":"c_example"},"messageId":{"type":"string","example":"m_answer"},"tokensIn":{"type":"integer","example":120},"tokensOut":{"type":"integer","example":18},"latencyMs":{"type":"integer","example":350},"refused":{"type":"boolean","description":"True when the answer could not be grounded in the knowledge base."}}},"ChatError":{"type":"object","required":["type","code","message"],"properties":{"type":{"const":"error","type":"string"},"code":{"type":"string","example":"generation_failed"},"message":{"type":"string","example":"The answer failed. Please try again."}}},"Error":{"example":{"code":"forbidden","message":"API key does not have access to this operation","requestId":"req_example"},"type":"object","required":["code","message","requestId"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"requestId":{"type":"string"},"retryAfter":{"type":"integer"},"issues":{"type":"array","items":{"type":"object","properties":{"path":{"type":"string"},"message":{"type":"string"}}}}}}}}}