Skip to main content
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 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.

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.
  2. An endpoint key that lists it. See Endpoint keys.
  3. A paid plan. Calls from apps and AI assistants need one. You can set everything up before.
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 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, 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.

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

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

Send the key in either header:
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} 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.
Response 200, when the call finished within the wait:
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.
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 instead, and nothing runs.

Read a call later

GET /api/v1/endpoint-calls/{callId}
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

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. 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: 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: 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.

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.