Developers

API access (keys & the chat API)

Search all guides

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.

Creating a key

  1. Go to Settings > API keys.
  2. Click Create key and give it a name you will recognise later, like "Zapier production". The name is only for you, so you know what to turn off if something changes.
  3. Click Create key.
  4. Copy the key immediately. It is shown once and cannot be recovered. If you lose it, revoke it and make another.

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 acts as you

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.

Using the API

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.

Long jobs answer straight away, then you check back

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.

Watching the answer as it is written

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.

Getting the content the agent writes

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.

When the agent asks a question

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:

For a save offer, these three replies are always understood:

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

Finding the question after a 202

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"

Limits

Turning a key off

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.

Full reference

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.

Ready to publish on autopilot?

Start a 14-day free trial, or book a walkthrough.