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
POST/api/v1/tables/Create a personal or application table
GET/api/v1/tables/{tableId}/rows/Read live table data as JSON, with server-side pagination, search, and sorting
POST/api/v1/tables/{tableId}/rows/Save a record with exact JSON values, source references, and a retry key
GET/api/v1/tables/{tableId}/columns/Read table column IDs, names, and extraction instructions
POST/api/v1/tables/{tableId}/watches/Connect a collection to process new or changed documents automatically
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.

For table request schemas and responses, see the API reference. Follow Automate tables to connect the operations into a workflow. The same table operations support document tables and conversation Insights. Add classifications to saved fields, then configure deliveries for email, CSV, PDF/chart reports, or webhooks.

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.

Outbound requests from a workflow​

For outbound HTTP requests inside an agent workflow, set the webhook node's config.proxy to "direct", "brazil", or "us". Omission means direct. This field belongs to the saved AgentSpec, not the request that starts an execution. Create and replace draft specs, import and export bundles, and schema validation all use the same field. The webhook node guide lists the endpoints and a JSON 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​