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. Admin endpoints (indexing and operations) are documented for reference but aren’t callable from this console.
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. The proxy only forwards a safe set of query endpoints — the indexing and operations endpoints are documented for reference but aren’t reachable this way.
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 on the API itself, but the app proxy authenticates every request, so send your API token.
curl https://app.gg.env.docutrix.com/api/v1/document_proxy/health \
-H "Authorization: Bearer $API_TOKEN"Returns the running application version. Public on the API itself, but the app proxy authenticates every request, so send your API token.
curl https://app.gg.env.docutrix.com/api/v1/document_proxy/version \
-H "Authorization: Bearer $API_TOKEN"Run a retrieval-augmented question against one or more docsets and get an answer grounded in the retrieved passages, with citations.
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://app.gg.env.docutrix.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": [] }
}Evaluate which docsets a query would route to via keyword rules, without running a full RAG query.
curl https://app.gg.env.docutrix.com/api/v1/document_proxy/keyword-routing/evaluate?question=refund%20policy \
-H "Authorization: Bearer $API_TOKEN"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://app.gg.env.docutrix.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": "support@example.com"
}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://app.gg.env.docutrix.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":"customer@example.com"}'{
"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://app.gg.env.docutrix.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://app.gg.env.docutrix.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. limit is optional (1–100, default 20).
curl https://app.gg.env.docutrix.com/api/v1/document_proxy/documents/recent?limit=1 \
-H "Authorization: Bearer $API_TOKEN"List every docset with its source types and document counts.
curl https://app.gg.env.docutrix.com/api/v1/document_proxy/documents/docsets \
-H "Authorization: Bearer $API_TOKEN"Return aggregate metadata for a single docset.
curl https://app.gg.env.docutrix.com/api/v1/document_proxy/documents/metadata/company-policies \
-H "Authorization: Bearer $API_TOKEN"Summary of indexing status across docsets.
curl https://app.gg.env.docutrix.com/api/v1/document_proxy/documents/indexing-summary \
-H "Authorization: Bearer $API_TOKEN"Fetch a single document by id, or 404 if the id is unknown.
curl https://app.gg.env.docutrix.com/api/v1/document_proxy/documents/123 \
-H "Authorization: Bearer $API_TOKEN"Index a docset from a source — S3 (default), SharePoint, or Google Drive. Runs asynchronously by default and returns a job id.
docSetName string Required | The docset to index into. |
sourceType enum Optional | S3 (default), SHAREPOINT, or GOOGLEDRIVE. |
credentials object Optional | Source credentials; shape depends on sourceType. Omit for S3 when the API has bucket access. |
indexOptions object Optional | { targetIndexTypes?, forceReindex? }. |
async boolean Optional | Queue the job (true, default) or block until done (false). |
accountName string Optional | Optional account/tenant label. |
summaryModel string Optional | LLM used for document summarization. |
curl -X POST https://app.gg.env.docutrix.com/api/v1/document_proxy/index \
-H "Authorization: Bearer $API_TOKEN" \
-H "Content-Type: application/json" \
-d '{"docSetName":"company-policies","sourceType":"S3"}'{ "message": "Indexing queued", "docSetName": "company-policies", "jobId": "..." }Validate connectivity and report how many supported files a source has, without indexing anything.
curl -X POST https://app.gg.env.docutrix.com/api/v1/document_proxy/index/check-source \
-H "Authorization: Bearer $API_TOKEN" \
-H "Content-Type: application/json" \
-d '{"docSetName":"company-policies","sourceType":"S3"}'{ "sourceFileCount": 12, "existingDocumentCount": 0, "message": "Found 12 supported files." }Return document status counts and an isIndexing flag for a docset.
curl https://app.gg.env.docutrix.com/api/v1/document_proxy/index/progress/company-policies \
-H "Authorization: Bearer $API_TOKEN"{
"pendingCount": 3,
"indexingCount": 1,
"completedCount": 8,
"errorCount": 0,
"isIndexing": true
}Cancel an in-progress indexing run for a docset.
curl -X POST https://app.gg.env.docutrix.com/api/v1/document_proxy/index/cancel/company-policies \
-H "Authorization: Bearer $API_TOKEN"Retry indexing a single failed document.
curl -X POST https://app.gg.env.docutrix.com/api/v1/document_proxy/index/retry/DOCUMENT_ID \
-H "Authorization: Bearer $API_TOKEN"Trigger a reindex of every document. Long-running.
curl -X POST https://app.gg.env.docutrix.com/api/v1/document_proxy/index/reindex-all \
-H "Authorization: Bearer $API_TOKEN"Delete one or more docsets and their indexed documents.
curl -X DELETE https://app.gg.env.docutrix.com/api/v1/document_proxy/index/docsets \
-H "Authorization: Bearer $API_TOKEN" \
-H "Content-Type: application/json" \
-d '{"docSetNames":["company-policies"]}'Return the current queue consumer mode.
curl https://app.gg.env.docutrix.com/api/v1/document_proxy/index/consumer \
-H "Authorization: Bearer $API_TOKEN"Set the queue consumer mode (e.g. pause or resume consumption).
curl -X POST https://app.gg.env.docutrix.com/api/v1/document_proxy/index/consumer \
-H "Authorization: Bearer $API_TOKEN" \
-H "Content-Type: application/json" \
-d '{"mode":"paused"}'List active indexing sessions.
curl https://app.gg.env.docutrix.com/api/v1/document_proxy/index/sessions \
-H "Authorization: Bearer $API_TOKEN"Return the indexing session detail for a docset.
curl https://app.gg.env.docutrix.com/api/v1/document_proxy/index/sessions/company-policies \
-H "Authorization: Bearer $API_TOKEN"Return the indexing recovery log.
curl https://app.gg.env.docutrix.com/api/v1/document_proxy/index/recovery-log \
-H "Authorization: Bearer $API_TOKEN"Return the indexing abort log.
curl https://app.gg.env.docutrix.com/api/v1/document_proxy/index/abort-log \
-H "Authorization: Bearer $API_TOKEN"Return the indexing watchdog status.
curl https://app.gg.env.docutrix.com/api/v1/document_proxy/index/watchdog \
-H "Authorization: Bearer $API_TOKEN"Return queue status.
curl https://app.gg.env.docutrix.com/api/v1/document_proxy/index/queues \
-H "Authorization: Bearer $API_TOKEN"Return queue statistics.
curl https://app.gg.env.docutrix.com/api/v1/document_proxy/index/queue-stats \
-H "Authorization: Bearer $API_TOKEN"List documents that appear stuck mid-indexing.
curl https://app.gg.env.docutrix.com/api/v1/document_proxy/index/stuck-documents \
-H "Authorization: Bearer $API_TOKEN"List documents that errored during indexing.
curl https://app.gg.env.docutrix.com/api/v1/document_proxy/index/document-errors \
-H "Authorization: Bearer $API_TOKEN"Return the indexer’s runtime configuration.
curl https://app.gg.env.docutrix.com/api/v1/document_proxy/index/config \
-H "Authorization: Bearer $API_TOKEN"Return the indexing timeline for a single document.
curl https://app.gg.env.docutrix.com/api/v1/document_proxy/index/document-timeline/123 \
-H "Authorization: Bearer $API_TOKEN"