Authenticate users, manage accounts, and power an embeddable chatbot over your indexed documents — all from your application backend.
The Account API is organized around REST. It has predictable, resource-oriented URLs, accepts JSON request bodies, returns JSON-encoded responses, and uses standard HTTP status codes and verbs.
http://localhost:3000/api/v1Every request is made over HTTPS — calls over plain HTTP fail. The API is versioned in the path; the current version is v1.
Skip straight to Ask a question — one POST returns the answer text and the citations that back it.
Most endpoints use a personal API token; the chatbot endpoints use an account-scoped chatbot key. Both are bearer tokens.
Provide the token in the Authorization header of every request. Requests without a valid token return 401 Unauthorized.
Obtain a token by logging in or registering a user. The same token is returned on each login, so you can store and reuse it.
The chatbot and support-email endpoints authenticate with an account-scoped key that starts with cb_, generated from your account’s chatbot settings. It is safe to embed in a public website widget.
A personal API token carries full access to your account. Don’t embed it in client-side code, mobile apps, or public repositories. Only the cb_ chatbot key is safe to expose in a browser widget.
curl http://localhost:3000/api/v1/me \
-H "Authorization: Bearer $DOCUTRIX_API_TOKEN"{
"id": 42,
"name": "Ada Lovelace",
"avatar_url": "http://localhost:3000/rails/active_storage/...",
"sgid": "BAh7CEki...",
"content": "<div class=\"flex items-center\">...</div>"
}The API uses conventional HTTP status codes to signal the success or failure of a request.
Codes in the 2xx range indicate success. Codes in the 4xx range indicate an error caused by the request (a missing parameter, an invalid token, insufficient plan). Codes in the 5xx range indicate an error on the server.
| Code | Meaning |
|---|---|
200 | OK — the request succeeded. |
400 | Bad Request — a required parameter is missing or invalid. |
401 | Unauthorized — no valid token was provided. |
403 | Forbidden — plan does not allow access, or origin not allowed. |
422 | Unprocessable Entity — validation failed. |
429 | Too Many Requests — you hit a rate limit. |
503 | Service Unavailable — a dependency is not configured. |
Most errors return a JSON body with a human-readable error message. Validation failures additionally include a field-keyed errors object.
# Example error response (401)
{
"error": "Invalid Email or password."
}The chatbot endpoint is rate limited per chatbot key, by plan.
The chatbot endpoint allows 50 requests/hour on the Pro plan and 100 requests/hour on Business, metered separately because each call runs inference.
When you exceed the limit you receive 429 Too Many Requests with the plan limit and the time the window resets. Back off and retry after reset_at.
# 429 Too Many Requests
{
"error": "Rate limit exceeded. Please try again later.",
"limit": 50,
"reset_at": "2026-06-10T15:00:00.000Z"
}Create a user account and receive a ready-to-use API token in the response.
user.email string Required | The new user’s email address. |
user.password string Required | The account password. |
user.password_confirmation string Required | Must match password. |
user.name string Optional | Display name. |
user.terms_of_service boolean Optional | Whether the user accepted the terms. Required when the app enforces it. |
curl -X POST http://localhost:3000/api/v1/users \
-H "Content-Type: application/json" \
-d '{"user":{"name":"Ada Lovelace","email":"ada@example.com","password":"a-strong-password","password_confirmation":"a-strong-password","terms_of_service":true}}'{
"user": {
"id": 42,
"email": "ada@example.com",
"name": "Ada Lovelace",
"api_tokens": [
{ "id": 7, "name": "Default", "token": "kP3xQ9wA7sD2fG8hJ1kL4mN6" }
]
}
}Exchange an email and password for a reusable API token. The same token is returned on every login.
email string Required | The user’s email address. |
password string Required | The user’s password. |
otp_attempt string Optional | One-time password. Required only if two-factor authentication is enabled; otherwise the request fails with 422 and error: "otp_attempt_required". |
curl -X POST http://localhost:3000/api/v1/auth \
-H "Content-Type: application/json" \
-d '{"email":"ada@example.com","password":"a-strong-password"}'{
"token": "kP3xQ9wA7sD2fG8hJ1kL4mN6"
}Return the profile of the user the API token belongs to.
curl http://localhost:3000/api/v1/me \
-H "Authorization: Bearer $DOCUTRIX_API_TOKEN"{
"id": 42,
"name": "Ada Lovelace",
"avatar_url": "http://localhost:3000/rails/active_storage/...",
"sgid": "BAh7CEki...",
"content": "<div class=\"flex items-center\">...</div>"
}Update the authenticated user’s password. The current password is required to authorize the change.
user.current_password string Required | The user’s existing password. |
user.password string Required | The new password. |
user.password_confirmation string Required | Must match the new password. |
curl -X PATCH http://localhost:3000/api/v1/password \
-H "Authorization: Bearer $DOCUTRIX_API_TOKEN" \
-H "Content-Type: application/json" \
-d '{"user":{"current_password":"old-password","password":"new-password","password_confirmation":"new-password"}}'{
"success": true
}Return every account the authenticated user belongs to. Each account isolates its own set of documents.
curl http://localhost:3000/api/v1/accounts \
-H "Authorization: Bearer $DOCUTRIX_API_TOKEN"[
{
"id": 1,
"name": "Ada Lovelace",
"personal": true,
"owner_id": 42,
"created_at": "2026-01-15T09:30:00.000Z",
"updated_at": "2026-01-15T09:30:00.000Z",
"account_users": [
{ "id": 1, "user_id": 42 }
]
}
]Permanently delete the authenticated user’s account. This cannot be undone.
Deleting a user removes their data immediately. There is no recovery — confirm intent before calling this endpoint.
curl -X DELETE http://localhost:3000/api/v1/me \
-H "Authorization: Bearer $DOCUTRIX_API_TOKEN"{}Run a retrieval-augmented question against your account’s indexed documents and get back an answer with citations.
Authenticate with the cb_ key (not an API token). Requires a Pro or Business plan, and the request Origin/Referer must match the key’s allowed origin when one is set.
Pass prior turns in past_messages (the most recent 10 are used) to keep context. Set stream to true to receive a text/event-stream of Server-Sent Events instead of a single JSON body.
question string Required | The user’s question. |
past_messages array 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 http://localhost:3000/api/v1/chatbot/ask_question \
-H "Authorization: Bearer $DOCUTRIX_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.
message string Required | The support message (maximum 2000 characters). |
sender_email string Optional | Optional reply-to address for the requester. |
curl -X POST http://localhost:3000/api/v1/support_emails \
-H "Authorization: Bearer $DOCUTRIX_CHATBOT_KEY" \
-H "Content-Type: application/json" \
-d '{"message":"I can\u2019t 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!"
}