# Answer API

> The retrieval behind the widget, over HTTP. Add a "draft answer from docs" button to your ticketing tool, a Slack slash command, or an agent, and get the sources with every answer.

## Authentication

- **botId**: your bot's UUID from the dashboard.
- **botKey**: the public bot key from Settings → API and MCP.
- **Origin**: browser requests must come from an allowed origin. Server to server calls without an `Origin` header are allowed when the bot has no allowed origins set.

## POST /chat

JSON request body:

```
{
  "botId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "botKey": "pk_…",
  "question": "How do I reset two-factor authentication?",
  "conversationId": "optional-existing-id",
  "visitor": "zendesk-ticket-4821",
  "pageUrl": "https://docs.example.com/security/2fa"
}
```

Response:

```
{
  "conversationId": "…",
  "answer": "…",
  "citations": [{ "url": "…", "title": "…" }],
  "confidence": 0.72,
  "escalate": false,
  "actions": []
}
```

- **citations**: the sources used. Show them to agents and customers.
- **confidence**: the retrieval score from 0 to 1. Low values usually mean the docs don't cover the question.
- **escalate**: true when the docs don't cover the question and the assistant declines to guess.

## POST /chat/stream

Same body as `/chat`. The response is Server-Sent Events: `start`, then `token` events, then `result` (or `error`).

## cURL example

```
curl -sS -X POST 'https://usedocs.app/chat' \
  -H 'content-type: application/json' \
  -d '{
    "botId": "YOUR_BOT_ID",
    "botKey": "YOUR_PUBLIC_BOT_KEY",
    "question": "How do I get started?",
    "visitor": "ticket-system"
  }'
```

## Human handoff

When the assistant hands off, your Slack, Discord, Teams, or webhook integrations notify the team. Read and assign the conversation in **Inbox → Conversations**. The question also shows up as a gap, with a drafted article for you to approve.

## Rate limits and usage

Each new chat counts toward your workspace's AI conversations (2,000 a month on Growth; follow-up questions are free) and toward the per-visitor rate limit of 30 requests per 60 seconds. Handle `429` and quota errors by falling back to a human, and honor `Retry-After`. More in the [developer portal](https://help.usedocs.app/rate-limits).