Skip to main content

API Overview

Everything you can do in the Docana UI sits on an HTTP API, and the parts you need for integrations are open to you: chat with your assistant, search your knowledge, manage conversation threads, and trigger routines.

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

Keys have scopes. Full access keys can call everything below. 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).

Create API key dialog showing the Name field, Scope options (Full access, Widget only, Routine only), Expiration, and the generated key with a copy button
Creating a scoped API key. Copy it when it's shown, you won't see it again.

The Endpoints You'll Actually Use​

MethodPathWhat it does
POST/api/channels/widget/{applicationId}/chatSend a message to your application and stream the answer
GET/api/channels/widget/{applicationId}/historyFetch a visitor's conversation history
POST/api/channels/widget/{applicationId}/archiveEnd and archive a widget conversation
POST/api/searchSearch your knowledge base
GET/api/threads/{threadId}/messagesRead the messages in a thread
POST/api/threads/{threadId}/archiveArchive a thread (triggers insights in archive mode)
GET/api/threads/{threadId}/latest-insightsGet the latest extracted insights for a thread
POST/api/agents/{agentId}/routines/{routineId}/runTrigger a routine
GET/api/healthHealth check, no auth required

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.

Example: Archive a Thread​

curl -X POST "https://platform.docana.com/api/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). 403 means the key's scope doesn't cover that endpoint. 404 usually means the ID belongs to a different application than your key.

A Full Reference Is Coming​

This page covers the endpoints integrations need most. A complete endpoint-by-endpoint reference is in the works. Until then, two good options:

  • The CLI wraps the API with commands for agents, documents, and conversations
  • The channel settings pages generate exact, working examples for your application

Next Steps​