Build on top of your own document sets. Upload and index documents, then ask natural-language questions and get answers grounded in those documents — with citations back to the source files and pages.
This reference covers the Document API (bearer-token, JSON) and the embeddable chatbot (an account-scoped cb_ key), which lives on the web app host.
Content-Type: application/json), except the streaming chat response, which is Server-Sent Events.docSetName) is a named collection of indexed documents.Most endpoints have a Try it console. Open Authorize in the top bar to set your API token or chatbot cb_ key, then edit the body and send. Every request goes to the app host — Document API calls are forwarded through its proxy, which attaches the backend credential server-side, so there’s no CORS setup and the backend secret never reaches the browser.
There are two credential types. Most API endpoints use a bearer API token; the embeddable chatbot uses an account-scoped cb_ key.
Authorization: Bearer YOUR_API_TOKENDocument API requests are made against the app host and forwarded through its proxy (/api/v1/document_proxy/…), which authenticates your bearer token and attaches the backend credential server-side. Requests without a valid token are rejected with 401 Unauthorized (except /health and /version, which are public). The proxy forwards a safe set of read/query endpoints, each scoped so you only ever see docsets your account owns.
Authorization: Bearer cb_1234567890abcdef…The chatbot and support-email endpoints use an account-scoped key that starts with cb_, generated from the account’s chatbot settings. It is safe to embed in a public website widget: a key may be locked to an allowed Origin/Referer, the endpoints require a Pro or Business plan, and they are rate-limited (50/hour on Pro, 100/hour on Business).
Treat the API token like a password — keep it server-side, never in client code. Only the cb_ chatbot key is designed to be exposed in a browser widget.
Errors are returned as JSON with an HTTP status code that reflects the problem.
{
"message": "Add an authorization header to the request: \"bearer <token>\"",
"errorCode": "UNAUTHENTICATED"
}message is human-readable; errorCode is a stable, machine-readable code you can branch on. Some validation errors include additional context fields.
| Status | Meaning |
|---|---|
400 | Bad Request — the input was malformed. |
401 | Unauthorized — missing or invalid credentials. |
404 | Not Found — the requested resource does not exist. |
409 | Conflict — the request clashes with current state. |
422 | Unprocessable Entity — well-formed but could not be acted on. |
503 | Service Unavailable — a required capability is disabled. |
Liveness probe for the API service. Public — no credential required; you can send this straight from the console without authorizing.
curl https://docsai.torqn.com/api/v1/document_proxy/healthReturns the running application version. Public — no credential required; you can send this straight from the console without authorizing.
curl https://docsai.torqn.com/api/v1/document_proxy/versionRun a retrieval-augmented question against one or more docsets and get an answer grounded in the retrieved passages, with citations.
Every name in docSetNames must belong to your account, or the request is rejected with 403 FORBIDDEN (“You can only access docsets that belong to your account.”). The example name company-policies is just a placeholder — a fresh account owns no docsets until it indexes a document. Call List docsets first to see the names you can actually use; if it returns [], index a document (or enable a read-only collection) before querying.
Pass the conversation so far in pastMessages (oldest first) to keep context. The current question goes in question, not in pastMessages.
Set "stream": true (or send Accept: text/event-stream) to receive a Server-Sent Events stream of JSON chunks carrying incremental answer text, so a chat UI can render tokens as they arrive.
The answer contains inline markers like [1] that map to entries in citations by index. Each citation carries fileName, pageNumber, and source metadata.
question string Required | The user’s question. |
docSetNames string[] Required | Docsets to search. |
pastMessages Message[] Optional | Prior turns, oldest first. A Message is { "role": "user" | "assistant", "content": string }. |
config object Optional | Retrieval/generation tuning — e.g. retrievalLimit, minimumSimilarityScore, model. |
promptContext string Optional | Extra system context prepended to the prompt. |
stream boolean Optional | Stream the answer as Server-Sent Events. |
curl -X POST https://docsai.torqn.com/api/v1/document_proxy/ask \
-H "Authorization: Bearer $API_TOKEN" \
-H "Content-Type: application/json" \
-d '{"question":"What is our refund policy?","docSetNames":["company-policies"]}'{
"answer": "Refunds are available within 30 days of purchase [1].",
"citations": [
{
"index": 1,
"fileName": "refund-policy.pdf",
"pageNumber": "2",
"sourceType": "S3",
"sourceMetadata": { "sourceId": "policies/refund-policy.pdf" }
}
],
"usage": { "inputTokens": 1234, "outputTokens": 88, "calls": 2, "perModel": [] }
}Classify a query against the keyword-routing rules — reports whether it is short/keyword-style enough to skip the query rewriter, without running a full RAG query. Pass the query in q.
curl https://docsai.torqn.com/api/v1/document_proxy/keyword-routing/evaluate?q=refund%20policy \
-H "Authorization: Bearer $API_TOKEN"{
"query": "refund policy",
"skipsRewriter": true,
"maxWords": 5,
"rule": "Short (1-5 words), no punctuation, no conversation history, no promptContext — rewriter is skipped. Keyword vs question classification is handled by the LLM router."
}The embeddable chatbot endpoint on the web app. Runs a retrieval-augmented question against the account’s docset and returns an answer with citations — authenticated with the account-scoped cb_ key.
Authenticate with the cb_ key (not the API token). Requires a Pro or Business plan, and — when the key has an allowed origin set — the request Origin/Referer must match it. Rate limited to 50/hour (Pro) or 100/hour (Business).
Pass prior turns in past_messages (oldest first; only the last 10 are used). Set stream to true to receive a text/event-stream of Server-Sent Events instead of a single JSON body. The docset is resolved from the account the key belongs to.
question string Required | The user’s question. |
past_messages Message[] Optional | Prior turns as { role, content } objects (role is "user" or "assistant"). Only the last 10 are used. |
format string Optional | text (default) returns Markdown; html returns rendered HTML. |
stream boolean Optional | When true, responds with a Server-Sent Events stream. |
curl -X POST https://docsai.torqn.com/api/v1/chatbot/ask_question \
-H "Authorization: Bearer $CHATBOT_KEY" \
-H "Content-Type: application/json" \
-d '{"question":"What is the refund policy?","format":"text"}'{
"answer": "Refunds are available within 30 days of purchase [1].",
"citations": [
{
"index": 1,
"fileName": "refund-policy.pdf",
"pageNumber": "2",
"source": "https://files.example.com/refund-policy.pdf?signature=..."
}
],
"support_email": "[email protected]"
}Send a support message to the account’s configured support inbox — designed to back a “Contact support” action in a widget. Uses the cb_ chatbot key.
message string Required | The support message (maximum 2000 characters). |
sender_email string Optional | Optional reply-to address for the requester. |
curl -X POST https://docsai.torqn.com/api/v1/support_emails \
-H "Authorization: Bearer $CHATBOT_KEY" \
-H "Content-Type: application/json" \
-d '{"message":"I can’t find the onboarding guide.","sender_email":"[email protected]"}'{
"success": true,
"message": "Your support request has been sent successfully. We'll get back to you soon!"
}Generate a short, descriptive title for a conversation — useful for naming chat threads in a sidebar.
pastMessages Message[] Required | The conversation to title, oldest first. A Message is { "role": "user" | "assistant", "content": string }. |
curl -X POST https://docsai.torqn.com/api/v1/document_proxy/summary \
-H "Authorization: Bearer $API_TOKEN" \
-H "Content-Type: application/json" \
-d '{"pastMessages":[{"role":"user","content":"What is our refund policy?"},{"role":"assistant","content":"Refunds are available within 30 days."}]}'{ "title": "Refund policy window" }List the documents in a docset. Returns id, fileName, docSetName, source, indexingStatus, and timestamps.
curl https://docsai.torqn.com/api/v1/document_proxy/documents?docSetName=company-policies \
-H "Authorization: Bearer $API_TOKEN"[
{
"id": "doc_01HZX9...",
"fileName": "refund-policy.pdf",
"docSetName": "company-policies",
"source": "S3",
"indexingStatus": "COMPLETE",
"createdAt": "2026-01-12T09:24:01.000Z",
"updatedAt": "2026-01-12T09:24:18.000Z"
}
]List recently indexed documents across your docsets, most recent first. limit is optional (1–100, default 20).
The proxy filters the recent list down to docsets your account owns. Because the underlying ordering is by recency before that filter is applied, a busy environment can return fewer than limit rows — it is a preview of your latest indexing activity, not a guaranteed count.
curl https://docsai.torqn.com/api/v1/document_proxy/documents/recent?limit=1 \
-H "Authorization: Bearer $API_TOKEN"[
{
"id": "doc_01HZX9...",
"fileName": "refund-policy.pdf",
"docSetName": "company-policies",
"source": "S3",
"indexingStatus": "COMPLETE",
"createdAt": "2026-01-12T09:24:01.000Z",
"updatedAt": "2026-01-12T09:24:18.000Z"
}
]List every docset with its source types and document counts.
Docsets aren’t created up front — one appears here the moment its first document finishes indexing, and disappears when its last document is removed. A brand-new account with nothing indexed (and no read-only collections enabled) gets an empty [] back. This list is also scoped to your account, so you only ever see docsets you own. Upload and index a document first (or enable a read-only collection), then the docset will show up here and become queryable from /ask.
curl https://docsai.torqn.com/api/v1/document_proxy/documents/docsets \
-H "Authorization: Bearer $API_TOKEN"Return aggregate metadata for a single docset.
curl https://docsai.torqn.com/api/v1/document_proxy/documents/metadata/company-policies \
-H "Authorization: Bearer $API_TOKEN"Summary of indexing status across docsets.
curl https://docsai.torqn.com/api/v1/document_proxy/documents/indexing-summary \
-H "Authorization: Bearer $API_TOKEN"Fetch a single document by id. Returns 404 if the id is unknown or the document isn’t in one of your docsets.
curl https://docsai.torqn.com/api/v1/document_proxy/documents/doc_01HZX9... \
-H "Authorization: Bearer $API_TOKEN"Return document status counts and an isIndexing flag for a docset.
curl https://docsai.torqn.com/api/v1/document_proxy/index/progress/company-policies \
-H "Authorization: Bearer $API_TOKEN"{
"pendingCount": 3,
"indexingCount": 1,
"completedCount": 8,
"errorCount": 0,
"isIndexing": true
}