Base URL
Authentication
The SDK API uses the same authentication as the embedded widget. Requests are authorized by theX-User-Anon-Id header and validated against your allowed domains list, which you configure in Widget & SDK Configuration.
Include these headers in every request:
*When you send a JWT in the
Authorization header, X-User-Anon-Id can be omitted: the user identity is taken from the token’s sub claim.
Conversations
List Conversations
Example request:
Get Unread Count
Get Conversation
Example request:
tool_call_data array listing the tool calls the agent
made while producing that message, in the order they ran. The array is empty
when no tool was used. Each entry carries the tool’s status, tool_name, a
display name, and a type that tells your interface how to render it (for
example status_message, progress_indicator, confirmation_input, or
form). Calls to your own client-side functions also include an arguments
object with the values the function was called with, so you can show what ran.
This is the same shape used by the built-in chat interface, so you can replay a
past conversation — including its tool calls — in a custom UI.
Messages
Send Message
This endpoint returns a
text/event-stream response. You need an SSE-compatible client to consume the stream. If the stream disconnects, use the Get Message Status endpoint to poll for the final result.
Example request (JSON):
multipart/form-data with content, conversation_id, and agent_id as form fields and files for file attachments.
text/event-stream. Each event is a line of text prefixed with data: . Events that belong to a conversation carry it as thread.id; error events such as a rejected file upload carry type and error instead, and end the stream.
Forked conversations
A conversation belongs to the user who started it. If someone else sends a message to it — most often because a conversation link was shared with them — AGO does not add their message to the original. It creates a copy owned by the new sender, seeded with the conversation history, and continues there. The original owner never sees the new sender’s messages, and the new sender’s replies stay private to them. When this happens, the stream opens with aconversation_forked event before any content:
to conversation.
What your integration must do: store the returned ID and use it for subsequent requests. If you keep sending the original conversation_id, your messages are not lost — repeated sends from the same user resolve to the same copy — but GET /conversations/{original_id} keeps returning the original conversation, which never gains the new turns. Your interface would appear frozen while the agent answers into a conversation you never read.
The same conversation_forked object is returned by Get Message Status, so a client that polls after a dropped stream sees it too.
Forking does not apply when the sender is a staff member replying from the agent console, nor to conversations that arrive over Slack, WhatsApp, Messenger or HelpScout, which are shared by design.
What a copy contains: the message text and roles of the conversation so far, capped at the most recent 200 messages. Knowledge sources, file attachments, tool call details and follow-up suggestions are not copied, so messages in a copy are thinner than in the original.
A copy is seeded that way only when the sender could already read the original — with conversation link sharing on, that is anyone holding the link. If your workspace has link sharing turned off, the sender still keeps their message and still gets an answer, but the copy starts empty: no history and no title, since the title is written from the original’s content. They were never able to open that conversation, so nothing from it reaches them.
Carried-over messages are attributed to the new sender, not to whoever shared the conversation, and are returned exactly like any other message. From the moment the copy exists it is that sender’s own conversation, and nothing in a later GET /conversations/{id} marks it as a copy. If you want to show your users that a fork happened, do it once from the conversation_forked event on the stream — it is a notice about the moment, not a permanent property of the conversation.
Stop Message
CANCELED.
Closing the SSE connection on its own does not stop the agent — it keeps
generating and the full answer appears the next time you load the conversation.
Call this endpoint as well as closing the stream.
Path parameters:
Response:
status is stopping when the request was accepted, not_running when the turn
had already finished — stopping a completed turn is harmless, so you can call
this without checking first — or not_supported for a background agent run,
which cannot currently be stopped once started.
Example:
Continue Message
client_functions_mode: "pause".
The two modes differ in when the agent sees your function results:
placeholder(default): when the agent calls one of your client functions, the turn continues immediately without the result. The result you submit is only visible to the agent on the next message.pause: the turn stops when the agent calls your client function(s). The SSE stream ends with astatus: "WAITING_CLIENT"event that listswaiting_tool_call_ids. Execute each function, submit its result viaPOST /tool-calls/{id}/submit(body:{"formData": {...}}), then call this endpoint. The agent continues the same turn with the real results — useful when a function changes what the agent should do next (for example a page navigation followed by filling the destination page).
status: "WAITING_CLIENT" and tool calls in waiting_input status, then
submit and continue as usual.
Path parameters:
JSON request body:
Example flow:
resume.ready flag flips to
true on the last one. Sending a new message to the conversation abandons any
paused turn. The endpoint returns 409 if the message is not paused, if some
tool calls are still waiting, or if the conversation moved on.
Response: a text/event-stream, same format as Send Message.
Get Message Status
Example request:
status field is one of:
Submit Feedback
Request body:
rating on its own records the thumbs up or thumbs down. Sending reasons, a
comment, or both also files a feedback report, which appears in the Feedback
tab of the dashboard alongside reports submitted from the chat interface — see
Feedback Analytics.
A message holds one report. Submitting feedback again for the same message
replaces the previous reasons and comment rather than filing a second report.
A reason outside the four listed values is rejected with 422 and named in the
response, so a typo fails rather than being dropped silently.
Example request:
204 No Content
Tickets
Create Ticket
multipart/form-data to support file attachments.
Form fields:
Example request:
Configuration
Get Config
proactive block tells the SDK whether proactive mode is enabled for the workspace. When enabled is false, the SDK never shows a nudge and never calls the proactive endpoints.
Get Pre-Chat Form Status
Submit Pre-Chat Form
Example request:
Get Active Incident Banners
agent_ids is empty, the banner applies to all agents. When populated, it only appears for conversations with the listed agents.
Proactive Mode
Used by the SDK’s proactive mode. The evaluate endpoint requires proactive mode to be enabled for the workspace; the events endpoint accepts lifecycle reports regardless, so batches sent around a configuration change are not lost.Evaluate an Intervention
intervene: "agent". A fast model decides whether a nudge is worth showing right now and drafts its message.
Request body:
client_nudge_id is a UUID generated by the SDK for this nudge instance; lifecycle events sent later reference it. agent (optional) is the agent id or name. signals only carries counters and page paths — never form values.
Example response:
intervene is false, message and action are null and the SDK stays silent. action is only ever one of the client_functions declared in the request.
Returns 403 (proactive_mode_disabled) when the feature is off for the workspace or the agent, and 429 (rate_limited) when the per-user evaluation cap is reached — the SDK treats both as “do not intervene”.
Report Nudge Events
source is "static" or "agent". type is one of shown, dismissed, accepted, converted. Events are idempotent per nudge and type: the first reported timestamp wins.
Example response:
Error Format
All errors follow a consistent structure:Related
- Public API v1 — the admin-facing REST API for managing your workspace
- API Key Authentication — how to generate and manage API keys
- SDK Integration — guide to embedding AGO in your application