> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cogniagent.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Endpoint API

> Call your agents' endpoints from your own apps with an endpoint key, read calls that take longer, and connect AI assistants over MCP.

Use the Endpoint API when your own app or server should start work in one of your agents: run a workflow, give a coworker a task, or start a conversation. You call the agent's [endpoint](https://docs.cogniagent.ai/features/endpoints.md) at its address with an endpoint key, and get its result back, or a link to read it when it takes longer.

The same endpoints can be tools for AI assistants such as Claude, Cursor or Codex, over MCP. See [AI assistants over MCP](#ai-assistants-over-mcp).

## Before you start

1. **An endpoint open to apps.** In the agent's **Settings → External access**, click **Offer something**, or open an endpoint, and switch on **Apps (API)** under **Who may call it**. See [Make an endpoint](https://docs.cogniagent.ai/features/endpoints.md#make-an-endpoint).
2. **An endpoint key that lists it.** See [Endpoint keys](#endpoint-keys).
3. **A paid plan.** Calls from apps and AI assistants need one. You can set everything up before.

> [!WARNING]
>
> An endpoint key belongs on your server only. Never put it in a web page, a mobile app or a public repository. The API answers no browser calls.

## Endpoint keys

An endpoint key calls only the endpoints it lists, and only while each is open to apps or AI assistants. It can also read or change the [stores](https://docs.cogniagent.ai/api/stores.md) its agent has exposed, at the level each allows. It can't read or change anything else in your workspace. What a key starts runs as the endpoint runs, never as the person who made the key.

When the agent has more than one [environment](https://docs.cogniagent.ai/features/environments.md), a key reaches every environment's copy of an endpoint it lists. Putting an endpoint on a key, or taking it off, does so for all its copies, and the key's list names it once, such as "Book a visit (in Production, Demo)". See [Endpoints in each environment](https://docs.cogniagent.ai/features/endpoints.md#in-each-environment).

### Make a key

You can make a key in four places. Each asks for a **Key name** (name it after what uses it, such as the app or the server) and when it **Expires**: **In a year** (the default), **In 90 days**, **In 30 days** or **Never**.

* **The endpoint builder.** Under **Keys that may call it**, pick keys you already have, or tick **Create a key**.
* **The endpoint's drawer.** Under **Keys that may call it**, put the endpoint on one of your keys, or **Create a key**.
* **External access → Connect an AI assistant.** **Make a key for this address** makes a key that lists the endpoints at this agent's MCP address that you may put on a key.
* **Settings.** **MCP & API tokens** in the workspace menu, for everyone, and **Workspace settings → API access**, for Owners and Admins, have an **Endpoint keys** section. **Make an endpoint key** also asks for the **Endpoints it may call**.

### Shown once

A new key starts with `cek_` and is shown once: "This is the only time the whole key is shown. Keep it on your server, never in a browser." When it is made for an endpoint open to apps, its address and a ready `curl` call are shown with it. After that, lists show only the key's first 12 characters, such as `cek_3f9a1b2c…`.

Each key shows its name, the endpoints it calls, who created it, **Last used** and when it expires. A key keeps working when the person who made it leaves the workspace, and the list says so.

### Replace and revoke

* **Replace** makes a new key that calls what the old one calls, named "*name* (new)" and shown once. The old key keeps working until you revoke it, so you can switch your app over first.
* **Revoke** stops a key at once: its next call is refused with `invalid_key`. It can't be undone.
* **Remove from this key**, in an endpoint's drawer, stops that key calling that endpoint. The key keeps calling what else it lists.

Keys don't rotate on their own. Deleting an endpoint takes it off every key.

### Who may do what

| | Who |
| - | - |
| Make a key | Any member with a confirmed email |
| Put an endpoint on a key | People who may change the endpoint's agent, on a key they made. Owners and Admins, on any key |
| Take an endpoint off a key | People who may change its agent, the key's creator, Owners and Admins |
| Replace or revoke a key | Its creator, Owners and Admins |
| See a key | Owners and Admins see every key. Others see their own, and the keys that list an endpoint they may change |

A workspace has at most 50 active keys, and a key lists at most 100 endpoints. An endpoint's copies in other environments count once.

## Base URL and authentication

```text theme={null}
https://app.cogniagent.ai/api/v1
```

Send the key in either header:

```http theme={null}
Authorization: Bearer cek_…
x-api-key: cek_…
```

Only endpoint keys work here. Personal access tokens and widget keys are refused.

An endpoint's address ends in its slug, such as `send-quote`. It is shown in the endpoint's drawer, under **Its address**. The slug is unique in your workspace and stays the same when the endpoint moves to another agent. **Change address** sets a new one; callers using the old address stop working. An endpoint's copies in other environments share its slug, so a new address applies to all of them, and a call reaches the copy in the environment the agent runs in.

## Call an endpoint

`POST /api/v1/endpoints/{slug}`

| Field | Type | Required | What it is |
| - | - | - | - |
| `inputs` | object | | The endpoint's inputs, by name. Inputs fixed on the endpoint are filled in for you, whatever you send |
| `waitSeconds` | number | | How long to wait for the result, from 0 to 50. Default 50 |

The body is 256 KB at most. An empty body calls the endpoint with no inputs. Add an `Idempotency-Key` header to make sure a call runs at most once: see [Call at most once](#call-at-most-once).

```bash theme={null}
curl -X POST 'https://app.cogniagent.ai/api/v1/endpoints/send-quote' \
  -H "Authorization: Bearer $COGNIAGENT_ENDPOINT_KEY" \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: order-10482-quote' \
  -d '{ "inputs": { "customer_email": "buyer@example.com", "plan": "team" } }'
```

Response `200`, when the call finished within the wait:

```json theme={null}
{
  "callId": "cm9q2x0f80000ab12cd34ef56",
  "status": "completed",
  "result": {
    "send_quote_email": { "messageId": "msg_7c41", "sent": true }
  },
  "executionId": "cm9q2x1a20001ab12gh78ij90",
  "durationMs": 3412,
  "statusUrl": "https://app.cogniagent.ai/api/v1/endpoint-calls/cm9q2x0f80000ab12cd34ef56"
}
```

Response `202`, when it is still running after the wait. Read it later at `statusUrl`, which is also in the `Location` header. `Retry-After` says how many seconds to wait.

```json theme={null}
{
  "callId": "cm9q2x0f80000ab12cd34ef56",
  "status": "running",
  "executionId": "cm9q2x1a20001ab12gh78ij90",
  "durationMs": 50021,
  "statusUrl": "https://app.cogniagent.ai/api/v1/endpoint-calls/cm9q2x0f80000ab12cd34ef56"
}
```

| Field | What it is |
| - | - |
| `callId` | The call's id. It is in the endpoint's call log too |
| `status` | `completed`, `failed`, `running` or `timed_out` |
| `result` | What the call produced. See below |
| `truncated` | `true` when the result was over 64 KB and was cut. The run keeps all of it |
| `executionId` | The workflow's run |
| `conversationId` | The conversation a starting channel started |
| `link` | A website chat link, when the channel is a website chat |
| `error` | Why it failed, when `status` is `failed` |
| `durationMs` | How long it took, or has taken so far |
| `statusUrl` | Where to read the call again |

What each kind of endpoint answers:

* **A workflow** answers with the output of its last steps, keyed by step key: a step that ran and was not followed by another step that ran. A workflow that is still running when the wait ends goes on, and you read its result later. A run that fails answers `failed`.
* **A coworker** answers `running` with `202`: it starts a session, which runs as the person the endpoint runs as. Read the call later. Its `result` is `{ "text": "…", "files": ["…"] }`: the coworker's final answer and the names of any files it made. The files themselves are not sent.
* **A starting channel** answers `completed` once the conversation has started, with its `conversationId`, or a website chat `link`.

A call that refuses gets an [error](#errors) instead, and nothing runs.

## Read a call later

`GET /api/v1/endpoint-calls/{callId}`

```bash theme={null}
curl 'https://app.cogniagent.ai/api/v1/endpoint-calls/cm9q2x0f80000ab12cd34ef56?wait=20' \
  -H "Authorization: Bearer $COGNIAGENT_ENDPOINT_KEY"
```

The answer has the same fields as the call: `202` while it runs, `200` once it has finished. Add `wait` (0 to 25 seconds) to hold the request open until the call ends, so you need far fewer requests.

* Only the key that made the call can read it. Any other key gets `404 call_not_found`.
* A call can be read for 30 days.
* A workflow still running after 24 hours, or a coworker's session after 120 minutes, is `timed_out`. The work itself may go on; the call stops waiting for it.

## Call at most once

Send an `Idempotency-Key` header, 1 to 128 characters, such as your own order or job id.

* The same `Idempotency-Key`, sent with the same endpoint key to the same endpoint with the same inputs within 24 hours, gets the first call's answer. Nothing runs twice.
* While the first call is still being made, a repeat gets `409 call_in_progress`. Read it when it ends.
* The same `Idempotency-Key` with another endpoint or other inputs gets `422 idempotency_key_reused`.
* An endpoint's copies in other environments count as the same endpoint, so a retry after the agent switched environments gets the first call's answer.

If a call fails with `503 endpoints_unavailable`, or your connection drops, retry with the same `Idempotency-Key`.

## Limits

| Limit | Value | When reached |
| - | - | - |
| Calls per key | 120 a minute | `429 rate_limited` |
| Reads of calls per key | 600 a minute | `429 rate_limited` |
| The endpoint's own limit | 60 a minute unless its owner set another | `429 rate_limited` |
| Coworker sessions running from outside, per endpoint | 10 | `429 too_many_running` |
| Failed sign-ins from one address | 30 a minute | `429 rate_limited` |
| Request body | 256 KB | `413 body_too_large` |
| Inputs | 64 KB | `400 inputs_too_large` |
| Result | 64 KB | Cut, with `truncated: true` |

A `429` carries a `Retry-After` header. Credits work as they do for any run, session or conversation: a workspace out of credits gets `402 insufficient_credits` before anything starts.

## Errors

Errors look like `{ "error": { "code": "…", "message": "…", "details": [] } }`. For a refused input, `details` is `[{ "code", "name" }]`, never the value. A `401` carries `WWW-Authenticate: Bearer`.

| HTTP | `code` | When |
| - | - | - |
| 400 | `invalid_request` | The body isn't a JSON object of `inputs` and `waitSeconds`, or `waitSeconds`, `wait` or the `Idempotency-Key` is out of range |
| 400 | `unknown_input`, `input_missing`, `input_invalid`, `inputs_too_large` | An input it doesn't take, a required one missing, a wrong type, or over 64 KB |
| 400 | `recipient_invalid`, `start_value_missing` | A starting channel can't reach the recipient, or a value it needs is missing |
| 401 | `invalid_key` | The key is missing, malformed, unknown, revoked or expired |
| 402 | `paid_plan_required` | The workspace has no paid plan |
| 402 | `insufficient_credits` | The workspace is out of credits |
| 404 | `endpoint_not_found` | No endpoint with this address is open to this key |
| 404 | `call_not_found` | No call of this key has this id, or it is older than 30 days |
| 405 | `method_not_allowed` | A method other than `POST` on an endpoint, or other than `GET` on a call |
| 409 | `endpoint_off`, `agent_stopped` | The endpoint is switched off, or its agent is stopped: "This endpoint's agent is stopped." Older servers answer `agent_paused` for a stopped agent: treat both the same |
| 409 | `target_gone`, `entry_gone`, `coworker_inactive`, `target_moved` | What it runs is gone, switched off, or moved |
| 409 | `no_run_as`, `run_as_cannot_reach` | It runs as nobody, or that person can't use what it runs |
| 409 | `channel_off`, `row_answers_only`, `connection_expired`, `person_connection_owner_only`, `active_session_exists` | A starting channel can't start now |
| 409 | `endpoint_not_in_environment` | The endpoint has no copy in the environment its agent runs in: "Lead intake has no copy in Demo. Copy it to Demo on the Endpoints tab." See [Endpoints in each environment](https://docs.cogniagent.ai/features/endpoints.md#in-each-environment) |
| 409 | `channel_not_in_environment` | The starting channel has no copy in the environment its agent runs in. See [Channels in each environment](https://docs.cogniagent.ai/features/ways-in.md#in-each-environment) |
| 409 | `call_in_progress` | A call with this `Idempotency-Key` is still being made |
| 413 | `body_too_large` | The body is over 256 KB |
| 422 | `idempotency_key_reused` | This `Idempotency-Key` was used for another call |
| 429 | `rate_limited`, `too_many_running` | A [limit](#limits) was reached |
| 502 | `launch_failed` | It could not be started |
| 503 | `engine_not_ready`, `endpoints_unavailable` | Endpoints can't be reached right now. Retry with the same `Idempotency-Key` |

An endpoint that isn't on the key gets the same `404` as one that doesn't exist, so addresses can't be guessed.

## AI assistants over MCP

An endpoint open to **AI assistants (MCP)** is a tool in AI assistants connected to your workspace. There are two addresses:

| Address | Lists |
| - | - |
| `https://embed.cogniagent.ai/mcp` | The workspace's address: endpoints listed at **The workspace's address** or **Both** |
| `https://embed.cogniagent.ai/mcp/agents/<agent-id>` | One agent's address: that agent's endpoints listed at **This agent's address** or **Both** |

Each endpoint's drawer shows its addresses. The **Connect an AI assistant** card in the agent's **Settings → External access** shows the agent's address with setups for Claude, Cursor and Codex.

What an assistant sees depends on what it connects with:

| Credential | At the workspace's address | At an agent's address |
| - | - | - |
| **Endpoint key** (`cek_…`) | Only the endpoints the key lists | Only the endpoints the key lists, of that agent |
| **Personal access token** (`cpt_…`) | The tools that build and run your workspace (see [Connect MCP](https://docs.cogniagent.ai/mcp-server.md)), plus the endpoints in agents you can open, when the token names one workspace | That agent's endpoints, if you can open the agent |
| **Workspace API key** (`cwk_…`, being retired) | As a personal access token, for the person who made the key | As a personal access token |
| **Widget key** | Refused | Refused |

A personal access token names one workspace when it is made for **Only** that workspace, or when the client sends the `X-Workspace-Id` header.

```bash theme={null}
claude mcp add-json cogniagent '{"type":"http","url":"https://embed.cogniagent.ai/mcp/agents/<agent-id>","headers":{"Authorization":"Bearer YOUR_KEY"}}'
```

### Endpoint tools

* **Each endpoint is one tool**, named by its address (`send-quote`). Its description is the endpoint's **What it does**, plus where it runs and how long it answers in. Its inputs are what a caller gives.
* **Its copies in other environments are the same tool.** A call reaches the copy in the environment the agent runs in, and an agent's address lists the endpoints of that environment.
* **A call waits up to 50 seconds.** It answers the same fields as the API. Past the wait, it answers `running` with a `callId`.
* **`check_endpoint_call`** reads a call made with the same key or token: `{ "callId": "…", "waitSeconds": 20 }`, up to 25 seconds. It is listed whenever endpoint tools can be called at that address.
* **The same rules apply** as for the API: 120 calls a minute per key or token, the endpoint's own limit, a paid plan, and the endpoint's checks. A refusal comes back as a tool error with its code.

Endpoint keys are made in the app only. Over MCP, a personal access token can create and change the endpoints of agents you may change, with `manage_agent_endpoint`, but it never makes or shows a key.

## How a call shows up

Every call is in the endpoint's call log, in its drawer, like any other call. For people who may change the agent, it names the door and the credential, such as "App · key Order sync (cek\_3f9a…)" or "AI assistant · *name*'s personal token · Front desk's address". Others see "App" or "AI assistant".

A coworker's session started from outside says it came from an app or an AI assistant. Its approvals go to the person the endpoint runs as.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.