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.