Skip to main content

Introduction

Everything you can do in the Docana UI sits on a REST API. This reference documents every endpoint: agents, knowledge, threads, applications, skills, and more. Each endpoint page shows the parameters, the response schema, and a ready-to-copy request in curl, JavaScript, Python, Go, and PHP.

Working from an AI tool instead of your own code? The Docana MCP gives Claude, Claude Code, Cursor, and any MCP client the same platform without writing HTTP calls. In Claude, open Settings → Connectors, click Add custom connector, and paste:

https://mcp.docana.com/mcp

In Claude Code, run:

claude mcp add --transport http docana https://mcp.docana.com/mcp \
  --header "Authorization: ApiKey your_api_key_here"

The Docana MCP page covers Cursor and other clients.

Base URL​

All requests go to your deployment's host over HTTPS. For the hosted platform that 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. Full access keys can call every endpoint in this reference. 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. Manage your keys under API Keys in the platform.

Always use trailing slashes​

Every path ends with a slash. A request without one gets a 308 redirect, and most HTTP clients drop the request body when they follow it, so a POST silently loses its payload.

# Good
curl https://platform.docana.com/api/v1/agents/

# Bad: redirects with 308 and your POST body disappears
curl https://platform.docana.com/api/v1/agents

Versioning​

/api/v1/ is the canonical, versioned surface and what you should call. The same operations also answer on the versionless /api/ paths, which exist as permanent aliases for the platform's own UI.

Content type​

Send request bodies as JSON with a Content-Type: application/json header. Responses are JSON unless an endpoint says otherwise (for example, the usage report returns a PDF).

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. No operation requires a query parameter to work.

On routes under /agents/{agentId}/, the applicationId query parameter is optional: when you leave it out, the platform derives it from the resource in the path. Sending it still works and asserts the resource belongs to that application, so existing callers keep working unchanged.

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​

List your agents:

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

You get back a JSON array, one entry per agent:

[
  {
    "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
  • 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