Skip to main content

API overview

Use the API to connect Docana to your own systems: search knowledge, run an agent, manage conversations, and trigger routines. This page helps you choose a starting endpoint. The API reference covers the complete request and response contracts.

Authentication​

Create an API key first (see Generating API Keys). Send it in the Authorization header using the ApiKey scheme, not as a Bearer token:

Authorization: ApiKey your_api_key_here

Keys have scopes. Full access keys can call the general API surface within their owner’s permissions. Widget only and Routine only keys are locked to their endpoints, which is what you want for anything that ships to a browser or a third-party system.

The base URL is https://platform.docana.com (or your own deployment's host).

Give the key a name, choose its scope, and set an expiration. This example uses Widget only access.
Give the key a name, choose its scope, and set an expiration. This example uses Widget only access.

Choose an endpoint​

MethodPathWhat it does
POST/api/v1/search/Search your knowledge base
GET/api/v1/threads/{threadId}/messages/Read the messages in a thread
POST/api/v1/threads/{threadId}/archive/Archive a thread (triggers insights in archive mode)
GET/api/v1/threads/{threadId}/latest-insights/Get the latest extracted insights for a thread
GET/api/v1/documents/{id}/content/Read a document's extracted text or transcription
GET/api/v1/usage/This month's budget, usage and what remains, as JSON
POST/api/v1/agents/{agentId}/routines/{routineId}/run/Trigger a routine
POST/api/channels/widget/{applicationId}/chat/Send a message to your application and stream the answer
GET/api/channels/widget/{applicationId}/history/Fetch a visitor's conversation history
POST/api/channels/widget/{applicationId}/archive/End and archive a widget conversation
GET/api/health/Health check, no auth required

Two path shapes show up there. /api/v1/ is the versioned API surface, and it is what your own code should call. The widget and health paths sit outside it because they are channel plumbing rather than API operations, not because they are older.

Versionless /api/ twins of the /api/v1/ rows are retired. Most now answer 410 Gone, and the few that still resolve are frozen aliases kept alive for integrations written before v1. Write new code against /api/v1/.

Keep the trailing slash

Use the trailing slash shown in each example. A request without it may receive a 308 redirect, which preserves the method but requires the client to follow the redirect and replay the request body. Calling the canonical URL directly avoids that extra step. See API conventions.

The channel settings pages in the platform generate ready-to-run request examples for your specific application, with the right IDs filled in. That's the fastest way to get a working call: open your application's Channels settings, pick the channel, and copy the example.

Example: Chat with your application​

curl -X POST "https://platform.docana.com/api/channels/widget/${APPLICATION_ID}/chat/" \
  -H "Authorization: ApiKey ${DOCANA_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [
      { "id": "msg-1", "role": "user", "content": "What is our refund policy?" }
    ],
    "visitor": { "id": "user-123", "email": "[email protected]" }
  }'

The response streams back the assistant's answer as it's generated. Pass a conversationId to keep follow-up messages in the same thread, and rehydrate a client with the history endpoint. Both are listed in the table above.

Example: Archive a thread​

curl -X POST "https://platform.docana.com/api/v1/threads/${THREAD_ID}/archive/" \
  -H "Authorization: ApiKey ${DOCANA_API_KEY}"

Archiving matters more than it sounds: if your agent generates insights in archive mode, this call is what triggers the extraction.

Errors​

The API uses standard HTTP status codes. 401 means your key is missing, expired, or malformed (check the ApiKey scheme). 402 means your plan is out of budget or over a quota, and retrying will not help. 403 means the key's scope doesn't cover that endpoint. 404 usually means the ID belongs to a different application than your key. The Errors page has the full list, with the machine-readable code values.

The full reference​

This page covers the endpoints integrations need most. The API Reference documents every endpoint, with parameters, response schemas, and copy-paste requests in curl, JavaScript, Python, Go, and PHP.

Next steps​