API overview
Endpoints, authentication and conventions.
The CognaOne API is JSON over HTTPS at https://api.cognaone.com. An agent asks the gate before each consequential action. Facts reach governed state from connected sources, and an MCP server gives agent frameworks the same gate as tools.
| Endpoint | Purpose |
|---|---|
POST /api/actions/evaluate | Ask whether an action may run; returns allow, warn, defer or block, with reason codes and a receipt |
POST /api/intake/{connectorId} | Receive signed events from a connected source; the facts they carry become governed state |
POST /api/runtimes | Register the runtime an agent runs in; a heartbeat keeps it current |
/api/mcp | MCP server with OAuth: the same gate, reachable as tools (see MCP server for its address) |
Authentication#
Each agent has its own bearer token, issued when you register the agent in the console. The token identifies the agent and its tenant, so requests never carry a tenant ID.
Authorization: Bearer <agent token>Conventions#
| Convention | Detail |
|---|---|
| Threads | A threadId groups the governed state and decisions of one case, conversation or task |
| Idempotency | Send a clientRequestId and reuse it on retries; the gate returns the original decision instead of evaluating twice |
| Modes | observe records the decision without enforcing it; enforce is the default |
| Receipts | Every evaluation returns lineage.receiptId; keep it with the action |
| Errors | JSON bodies. The gate and runtimes return { error, message }; intake returns { error: { code, message } }. See Errors |
Last reviewed October 2026Suggest a change