Before you start
- 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.
- An endpoint key that lists it. See Endpoint keys.
- A paid plan. Calls from apps and AI assistants need one. You can set everything up before.
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 withcek_ 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.
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-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.
200, when the call finished within the wait:
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
runningwith202: it starts a session, which runs as the person the endpoint runs as. Read the call later. Itsresultis{ "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
completedonce the conversation has started, with itsconversationId, or a website chatlink.
Read a call later
GET /api/v1/endpoint-calls/{callId}
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 anIdempotency-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-Keywith another endpoint or other inputs gets422 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.
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
runningwith acallId. check_endpoint_callreads 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.
manage_agent_endpoint, but it never makes or shows a key.
