Developer API

DocuChat Developer API

Talk to your DocuChat chatbots programmatically over a simple REST API. Authenticate with an API key, list your chatbots, and run metered queries that reuse the same retrieval and answer generation as the app.

v1 scope. This release covers reading your chatbots and running metered queries. Write management (creating and editing chatbots or documents) and streaming responses are planned follow-ups.

Base URL

All endpoints are served under the /v1 prefix, which is permanent for the life of v1. Requests and responses are JSON.

https://api.docuchat.in/v1

Authentication

Create an API key in the DocuChat app under Settings → API. The full key (dc_ak_<keyId>_<secret>) is shown once at creation — store it securely; you cannot see it again.

Send it on every request using either header:

Authorization: Bearer dc_ak_<keyId>_<secret>
# or
X-API-Key: dc_ak_<keyId>_<secret>

Keys are account-scoped: every request acts within the resources of the account that owns the key. Revoked keys stop working immediately.

Quickstart

1. Create a key

In the app, open Settings → API and create a named key. Copy it once.

2. List your chatbots

curl https://api.docuchat.in/v1/chatbots \
  -H "Authorization: Bearer $DOCUCHAT_API_KEY"

3. Ask a question

curl -X POST https://api.docuchat.in/v1/chatbots/<chatbotId>/query \
  -H "Authorization: Bearer $DOCUCHAT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"message": "What is the refund policy?"}'

Endpoints

GET/v1/chatbotsFree

Lists your chatbots, newest first, paginated (see Pagination).

{
  "data": [
    {
      "chatbotId": "cb_123",
      "name": "Support bot",
      "description": "Answers from our help center",
      "provisioningStatus": "active",
      "isActive": true,
      "llmModel": "gpt-4o-mini",
      "answerLength": "medium",
      "showCitations": true,
      "documentCount": 12,
      "webUrlCount": 3,
      "createdAt": 1737400000000,
      "updatedAt": 1737500000000
    }
  ],
  "nextCursor": null
}

GET/v1/chatbots/{id}Free

Returns a single chatbot you own. Responds 404 if the id is unknown or not owned by your account.

POST/v1/chatbots/{id}/queryMetered

Runs retrieval + answer generation for a chatbot you own and debits credits for the tokens used. Guardrails run in order: authenticate → rate limit → credit/plan gate → per-chatbot spend cap → generate → debit.

Request body

{
  "message": "What is the refund policy?",
  "sessionId": "optional-caller-supplied"
}

Response

{
  "answer": "Our refund policy is ...",
  "chatbotId": "cb_123",
  "sessionId": "api-<requestId>",
  "model": "gpt-4o-mini",
  "usage": { "inputTokens": 812, "outputTokens": 143, "creditsDebited": 0.42 },
  "sources": [
    { "title": "Refund policy", "source": "refunds.pdf", "page": 2, "score": 0.87 }
  ]
}

Streaming (stream: true) is not supported yet and returns 400. Omit it for buffered JSON.

Rate limits

Requests are rate limited per key (60 requests per minute by default). Every response includes the current window state:

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 59
X-RateLimit-Reset: 1737500060

When exceeded you receive 429 RATE_LIMITED with a Retry-After header (seconds). Rate limiting is separate from your credit balance and the per-chatbot spend cap.

Errors

Every non-2xx response uses a consistent JSON envelope:

{ "error": "UNAUTHORIZED", "message": "Invalid or revoked API key." }

Code	HTTP	Meaning
UNAUTHORIZED	401	Missing, malformed, unknown, or revoked API key.
ACCOUNT_READ_ONLY	403	The account is deactivated and cannot perform this action.
VALIDATION_ERROR	400	The request was invalid (e.g. empty message, or stream:true).
NOT_FOUND	404	The chatbot was not found or is not owned by the calling account.
USAGE_BLOCKED	402	Insufficient credits / account blocked (when enforcement is on).
RATE_LIMITED	429	Per-key rate limit exceeded. Honor the Retry-After header.
CHATBOT_RATE_LIMITED	429	The chatbot's spend cap tripped for the current window.
INTERNAL	500	An unexpected server error.

Pagination

List endpoints accept ?limit= (1–100, default 25) and an opaque ?cursor=. The response includes nextCursor; pass it back to fetch the next page. A null cursor means the last page.

curl "https://api.docuchat.in/v1/chatbots?limit=50&cursor=<nextCursor>" \
  -H "Authorization: Bearer $DOCUCHAT_API_KEY"

OpenAPI spec

The machine-readable OpenAPI 3.1 description is available for import into Postman, code generators, and other tooling.

Download openapi.yaml

Ready to build?

Create your first API key in the DocuChat app and start querying in minutes.

Get your API key