What this is: A way to use the platform from your own software instead of the dashboard. You create an API key in settings, then send requests to the API with that key. Today the API covers chat: you can start conversations, send messages to the agent, and read anything it writes.
Prerequisite: Someone on your team needs to be comfortable making HTTP requests. If you just want to talk to the agent, use Chat in the app instead.
After that, the list shows only a short fingerprint of the key (afk_abc123...wx9z), when it was created, and when it was last used. That is enough to tell two keys apart without exposing the key itself.
A key inherits the permissions of whoever created it and works only inside that workspace. Conversations started through the API appear in your chat list in the app, so you can open any of them, read what happened, and carry on in the dashboard. Nothing the API does is hidden from you.
Gotcha: Treat a key like a password. Put it in your server's environment variables, never in a browser, a mobile app, or anything a customer could view the source of. Keys are blocked from browser requests on purpose.
Your base URL is shown in Settings > API reference, along with the full endpoint list. Copy it from there, since it differs between environments. The examples below assume you have it in a shell variable:
export BASE=... # copied from Settings > API reference
export KEY=afk_your_key_here
Send the key on every request:
Authorization: Bearer afk_your_key_here
Start a conversation:
curl -X POST $BASE/api/v2/chat/conversations \
-H "Authorization: Bearer $KEY" \
-H "Content-Type: application/json" \
-d '{"title": "Weekly briefs"}'
Send a message and wait for the answer:
curl -X POST $BASE/api/v2/chat/conversations/CONVERSATION_ID/messages \
-H "Authorization: Bearer $KEY" \
-H "Content-Type: application/json" \
-d '{"message": "What is our brand voice?"}'
A quick question comes back in seconds, and the response holds the finished reply.
Asking for a full article takes several minutes, because the agent does the same research it does in the app. Rather than leave your request hanging (which some networks cut off), the API answers after four minutes with 202 and tells you the work is still going:
{
"success": true,
"data": {
"conversation_id": "...",
"status": "running",
"poll": {
"messages": "/api/v2/chat/conversations/.../messages",
"after_message_id": "8f1c..."
}
}
}
The agent has not stopped. Read the conversation's messages every 30 seconds or so, and when a reply newer than after_message_id shows up, the turn is done:
curl $BASE/api/v2/chat/conversations/CONVERSATION_ID/messages \
-H "Authorization: Bearer $KEY"
Two things to know while a turn is still running: sending another message to the same conversation is refused until it finishes, and a request that has run for ten minutes reports a failure even though the agent usually finishes shortly after. Check the messages before deciding anything went wrong.
For longer work you can stream the reply instead of waiting for the whole thing. Add Accept: text/event-stream and you will receive the answer as it is produced, along with notes about what the agent is doing:
curl -N -X POST $BASE/api/v2/chat/conversations/CONVERSATION_ID/messages \
-H "Authorization: Bearer $KEY" \
-H "Accept: text/event-stream" \
-H "Content-Type: application/json" \
-d '{"message": "Draft an article about zero trust security."}'
Gotcha: If the connection drops, the agent keeps working. Nothing is lost. Read the conversation's messages afterwards and the reply will be there.
When you ask for an article, a brief or an outline, the agent does not paste the draft into its reply. It writes it into the conversation's workspace, exactly as it does in the app. So after a writing request, fetch the workspace to get the actual content:
# What did this conversation produce?
curl $BASE/api/v2/chat/conversations/CONVERSATION_ID/artifacts \
-H "Authorization: Bearer $KEY"
# Read one of them in full
curl $BASE/api/v2/chat/conversations/CONVERSATION_ID/artifacts/SLOT \
-H "Authorization: Bearer $KEY"
If you only read the chat reply, you will see the agent describing the article rather than the article itself. This is the most common surprise when people start with the API.
Sometimes the agent needs a decision from you before it can continue, the same way it shows a card in the app. The response comes back with a status of needs_input and a needs_input block describing what it is waiting for. Reply by sending another message to the same conversation, and it picks up where it left off.
{
"needs_input": {
"prompt": "Save this draft to the library?",
"options": ["Save", "Keep iterating", "Discard"],
"kind": "proposal",
"intent": "save_offer",
"artifact_kind": "written_draft",
"artifact_slot": "written:zero-trust-security",
"summary": "Drafted the article, 8 sections, 1800 words.",
"proposed_next_step": "Saving adds it to your content library as a draft."
}
}
Two kinds of pause, told apart by intent:
direction_check, the agent is confirming direction, or kind is question and it simply needs information. Answer in your own words.save_offer, the agent has finished something and is asking whether to put it in your content library. artifact_slot tells you exactly which draft, so you can fetch it from the artifacts endpoint and check it before you answer.For a save offer, these three replies are always understood:
| Reply | What happens |
|---|---|
Yes, save this to the library. | The draft becomes a content library item. |
Let's keep iterating on this, don't save yet. | Nothing is saved; describe what to change. |
Discard this draft, I want to start over. | Nothing is saved and the agent starts fresh. |
A long turn answers 202 before it finishes, so the question arrives later. It travels with the message: when you poll the conversation's messages, the assistant message that is waiting on you carries the same needs_input block. It disappears once you have replied, so a message with needs_input is always something still outstanding.
curl $BASE/api/v2/chat/conversations/CONVERSATION_ID/messages -H "Authorization: Bearer $KEY"
Retry-After header telling you how many seconds to wait.In Settings > API keys, click Revoke next to the key. It stops working immediately and cannot be switched back on. The entry stays in the list so you keep a record of what existed and when it was last used.
Revoke a key whenever someone who had access leaves, whenever you suspect it has been shared, or whenever whatever it was built for is switched off.
Settings > API reference lists every endpoint with its request and response shapes, and your base URL. It is generated from the API itself, so it never drifts from what the API actually does.
You can also send real requests from that page: click Authorize, paste a key, then Try it out on any endpoint. That is usually the quickest way to see what a response looks like before you write any code.
Start a 14-day free trial, or book a walkthrough.