> ## Documentation Index
> Fetch the complete documentation index at: https://docs.arcdemo.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Demo agent API

> Run ArcDemo demo agents from your own backend: start conversations, send messages, stream replies, and read transcripts and analysis. Connect helpdesks and bots with a signed webhook.

Talk to a published demo agent from your own backend, or connect a helpdesk, chat tool or bot through a signed webhook. Conversations run through the same pipeline as the website widget: the published version, lead form, consent and terms, guardrails, knowledge, tools, workflow, branches, limits and usage. They appear in Conversations with their summary and analysis. Text only.

## Authentication

* Create a workspace API key in *Settings → API keys* with the **Talk to demo agents** scope (`agents:converse`). API keys are a Team plan feature.
* Send it as `Authorization: Bearer ak_…`. A key without the scope gets `403 insufficient_scope`.
* Keys are server secrets. Never put them in a browser or mobile app.
* Each key may make 120 requests a minute. The widget's per-conversation limits apply on top.
* Owners and admins can see each request's route, status and latency for 30 days under *Settings → Request log*. The request log does not store request or response bodies.

## Endpoints

Base URL `https://api.arcdemo.io/api/v1`. The agent ID is on the agent's *Channels → API* page.

```text theme={null}
POST /agents/{agentId}/conversations                          start
POST /agents/{agentId}/conversations/{conversationId}/messages  send a message
POST /agents/{agentId}/conversations/{conversationId}/end       end
GET  /agents/{agentId}/conversations/{conversationId}           transcript + analysis
```

### Start a conversation

For a first server-side request, set `ARCD_AGENT_ID` and `ARCD_API_KEY` in your environment, then send JSON:

```bash theme={null}
curl --request POST "https://api.arcdemo.io/api/v1/agents/${ARCD_AGENT_ID}/conversations" \
  --header "Authorization: Bearer ${ARCD_API_KEY}" \
  --header "Content-Type: application/json" \
  --data '{}'
```

The empty body works only when the agent's published configuration does not require additional lead, consent, or terms fields. Keep the key on your server; do not expose it in browser code. A successful response has status `201` and a `conversationId` to use for the next request.

The request below is illustrative. Replace the agent ID and example values. Supply consent and terms fields only when they reflect the visitor’s actual choices, and provide any fields required by the agent’s published configuration.

```http theme={null}
POST /agents/{agentId}/conversations
{
  "visitor": { "id": "crm-12345", "name": "Ada Lovelace", "email": "ada@acme.com",
               "company": "Acme", "role": "VP Sales", "ip": "198.51.100.4" },
  "dynamicVariables": { "plan": "Enterprise" },
  "language": "Spanish",
  "consentAccepted": true,
  "termsAccepted": true,
  "idempotencyKey": "7b0c2c1e-0f6a-4d2c-9a53-2f1f4f6f0b1a"
}

201 { "conversationId": "…", "agentId": "…", "greeting": "…", "starterChips": ["…"] }
```

* Send the lead fields, consent and terms your widget asks for. Missing ones fail with the widget's message (for example `Email is required.`).
* `visitor.id` keeps a visitor on one branch of a traffic split. `visitor.ip` is the visitor's address; the per-IP limit of 10 new conversations an hour applies to it (otherwise to your server's IP).
* `dynamicVariables` fill the agent's `{{variables}}`, with the same limits as the widget.
* `language` picks the reply language. It must be one of the agent's languages (its default plus its *Additional languages* on the Agent page); anything else fails with `400`. Leave it out to use the agent's default.
* `overrides` change one conversation, and only the fields the agent allows under *Settings → Security → Overrides*: `firstMessage` (one line, up to 500 characters, shown as written), `language` (one of the agent's languages), `voiceId` (the agent's voice or one listed there) and `workflowStartNodeId` (a Subagent or Say step of the published workflow). The system prompt and other instructions can never be overridden. A field that isn't allowed, isn't valid, or isn't overridable fails the start with `400` and names it, for example `overrides refused: systemPrompt:not_overridable`. Applied overrides are stored on the conversation.
* Use a new `idempotencyKey` for each new conversation and keep it stable across retries. Retrying with the same key returns the same conversation.

The widget takes the same overrides as URL parameters on the agent page or iframe: `override_first_message`, `override_language`, `override_voice` and `override_start_node`. They apply only when the agent has an embed allowlist, so no other site can restyle your agent; fields that aren't allowed are dropped. The floating launcher (`arcdemo.js`) forwards the same parameters from `data-arcdemo-override-language` (and `-first-message`, `-voice`, `-start-node`) on its script tag, or from `arcdemo.agent.init({ agent, overrides: { language, firstMessage } })`.

### Send a message

Set `ARCD_CONVERSATION_ID` to the returned ID and set `ARCD_MESSAGE_ID` to a newly generated UUID for this message. Persist and reuse that UUID if you retry the same message; generate a different one for the next message.

```bash theme={null}
curl --request POST "https://api.arcdemo.io/api/v1/agents/${ARCD_AGENT_ID}/conversations/${ARCD_CONVERSATION_ID}/messages" \
  --header "Authorization: Bearer ${ARCD_API_KEY}" \
  --header "Content-Type: application/json" \
  --data "{\"text\":\"What will I see in the product tour?\",\"messageId\":\"${ARCD_MESSAGE_ID}\"}"
```

The following response is schematic; the alternatives and ellipses describe possible values rather than literal JSON.

```http theme={null}
POST /agents/{agentId}/conversations/{conversationId}/messages
{ "text": "What will I see in the product tour?", "messageId": "916ac804-1646-4de1-864a-1fb396e7c20b" }

200 {
  "conversationId": "…",
  "messageId": "…",
  "reply": {
    "status": "completed" | "escalated" | "error",
    "text": "…",
    "error": null,
    "escalation": null | { "reason": "…", "bookMeetingUrl": "…" },
    "sources": [{ "sourceId": "…", "title": "…", "sourceType": "demo" }],
    "content": [ … surfaced demos and documents … ],
    "suggestedActions": ["…"],
    "events": ["text_delta", "…", "message_done"]
  }
}
```

* Reusing a `messageId` returns the stored reply without asking the agent again.
* For a live stream send `Accept: text/event-stream` or `"stream": true` in the request body. If `stream` is supplied, it takes precedence over the `Accept` header. You get the widget's Server-Sent Events: `event: event` frames whose `data` is JSON with a `type` such as `text_delta`, `sources`, `content_surfaced`, `suggested_actions`, `escalation`, `error` and `message_done`. Lines starting with `:` are keep-alives. Ignore types you don't use: new ones can be added. With the widget's Action indicator on, you also get `tool_status` frames (`id`, `status` running or done, and a short `label` such as "Checking availability…") that never contain tool names or data, and never change the reply text.
* One message per conversation at a time; up to 4,000 characters.
* Only conversations started through the API or a Custom Channel accept messages.

### End, read

`POST …/end` closes the conversation and runs the summary, analysis and triggers (as when a visitor closes the widget). `GET …/{conversationId}` returns the status, lead, transcript, summary, engagement score and the analysis (criteria results, data points, sentiment, topics) once it has run. It works for any conversation of the agent.

### Errors

The following is a schematic response, not a literal JSON example.

```text theme={null}
{ "error": { "code": "unauthorized" | "insufficient_scope" | "agent_not_found" |
                     "agent_unavailable" | "conversation_not_found" | "invalid_request" |
                     "rate_limited" | "unavailable" | "server_error",
             "message": "…" } }
```

## Custom Channel

On the agent's *Channels → Custom Channel* page, create the channel to get a webhook URL and a signing secret (shown once). Your system POSTs each user message; ArcDemo answers inline or, when a callback URL is set, answers `202` and POSTs the reply there.

```http theme={null}
POST /channels/{channelId}/messages
X-ArcDemo-Timestamp: 1767225600
X-ArcDemo-Signature: sha256=<hex HMAC-SHA256(secret, timestamp + "." + raw body)>

{ "conversationId": "ticket-123", "messageId": "msg-1", "text": "Do you support SSO?",
  "visitor": { "name": "Ada Lovelace", "email": "ada@acme.com" } }

200 { "type": "message.reply", "channelId": "…", "conversationId": "ticket-123",
      "messageId": "msg-1", "arcdemoConversationId": "…", "reply": { …as above… } }
```

* The timestamp is Unix time in seconds. Requests more than 5 minutes off the current time are rejected; generate a fresh timestamp and signature for each request.
* `conversationId` is your own thread id. Messages with the same id continue one ArcDemo conversation; after it ends (or after 24 hours) the next message starts a new one. `visitor` and the other start fields are read on the first message.
* `messageId` makes retries safe: the same id returns the same reply. If a callback was lost, send the message again with the same id.
* Callbacks carry the same envelope, signed the same way with the channel secret, plus `X-ArcDemo-Event: message.reply`. Callback URLs must be public https.
* A callback that fails (network error or a non-2xx answer) is retried with backoff, so treat `messageId` as your dedupe key. If every attempt fails, the Custom Channel page shows why.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.