Skip to main content

API reference

Use the REST API to manage employees, applications, documents, agents, and conversations from your own systems. Each endpoint page lists its parameters, response schemas, and request samples. The reference is generated from the platform’s route definitions.

For a task-oriented walkthrough, start with API Overview. To work from a terminal or an AI client, see the CLI or Docana MCP.

For the employee lifecycle, open the Employee API overview. It connects creation, file and voice briefs, knowledge, tests, publication, and work history to the operations behind the product.

Base URL​

For the hosted platform, the versioned API base URL is:

https://platform.docana.com/api/v1

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 and inherit the permissions of their owner. Full access enables the general API surface, subject to those permissions. Widget only is restricted to widget endpoints, and Routine only to routine triggers. Keep full-access keys in your backend or secrets manager. Manage your keys under API Keys in the platform.

Send a User-Agent​

The hosted platform sits behind Cloudflare, which rejects requests without a User-Agent header with a 403 and error code 1010, before the request reaches Docana. Browsers and curl always send one. Some HTTP libraries do not (Python's urllib is the usual surprise), so set a descriptive one:

User-Agent: my-ingestion-script/1.0

Always use trailing slashes​

Use the trailing slash shown on each endpoint page to call the canonical URL directly. A request without it may receive a 308 Permanent Redirect. Unlike a 301 or 302, a 308 preserves the request method. Calling the canonical URL avoids the redirect and the need for your client to replay the request body. See HTTP redirect semantics.

curl "https://platform.docana.com/api/v1/agents/" \
  -H "Authorization: ApiKey ${DOCANA_API_KEY}"

Versioning​

/api/v1/ is the canonical, versioned surface and what you should call. Most versionless /api/ equivalents return 410 Gone. A limited set remains for existing integrations and channel or authentication infrastructure. Do not rely on those exceptions for new integrations.

Content type​

Use the content type documented by the endpoint. Most write operations accept JSON with Content-Type: application/json. Document uploads may use multipart form data, and some responses are streamed or binary. When using FormData, let your HTTP library set the multipart boundary.

Where parameters go​

The API follows three placement rules:

  • The path identifies the resource. Everything the URL needs to name one thing is a path segment: /agents/{agentId}/executions/{executionId}/.
  • The body carries the data of a write. POST, PUT, and PATCH requests put their payload in the JSON body, including scoping fields like applicationId when the operation needs one.
  • The query string filters and paginates reads. Query parameters on GET requests narrow a list or shape a response. Some endpoints require query parameters, including application scoping on analytics endpoints. Check the required fields on the endpoint page.

On many routes under /agents/{agentId}/, the platform derives application scope from the agent. This is not universal: use each endpoint’s parameter table to determine whether applicationId is required.

A few operations are marked deprecated in this reference. They keep working, and their pages name the replacement, which is the same operation with better parameter placement. Prefer the replacement in new code.

Your first request​

Set your key and the application ID, then list that application’s agents. You can find the application ID in its platform URL or with docana applications list.

export DOCANA_API_KEY=your_api_key_here
export APPLICATION_ID=42

curl "https://platform.docana.com/api/v1/agents/?applicationId=${APPLICATION_ID}" \
  -H "Authorization: ApiKey ${DOCANA_API_KEY}"

Without applicationId, this endpoint lists company-scoped agents only, so an empty list does not mean your application has no agents. The response is an array of agent objects. A shortened example:

[
  {
    "id": "cmc4v8xq10001l708h2vxk9d3",
    "name": "Support Assistant",
    "type": "CUSTOM",
    "applicationId": 42
  }
]

Every endpoint page in this reference shows the same three things: the parameters, a ready-to-copy request in your language, and the response schema with an example.

OpenAPI spec​

This whole reference is generated from the platform's OpenAPI 3.1 document, and you can use the same file with your own tools:

Import it into Postman or Insomnia to get a ready-made collection, feed it to a code generator for a typed client, or hand it to an AI agent so it can call the API for you.

Next steps​

  • Errors: What non-2xx responses look like, including plan limits and upload ceilings
  • Browse the endpoints by resource in the sidebar
  • CLI: The same API, wrapped in commands for your terminal
  • Docana MCP: The same platform, from Claude Code, Cursor, or any MCP client