API

Chat9 exposes its HTTP API at https://api.getchat9.live. There are two surfaces:

• Public widget endpoints (/widget/*, /embed.js, /widget/config) — unauthenticated, identified by your bot's public_id. This is what the embedded chat widget on your site calls. Documented in detail below.

• Authenticated dashboard / management endpoints — JWT-bearer authenticated. Sign-up, tenant settings, bot CRUD, document upload, chat logs, gap analyzer, escalations, FAQ workflow, etc. Catalogued below with one-line summaries; for request/response shapes use the canonical live spec:

  • Interactive: api.getchat9.live/docs
  • OpenAPI JSON: api.getchat9.live/openapi.json

When this page and the live spec ever disagree, the live spec wins.

Public widget endpoints

The widget on your site talks to Chat9 over a small set of public HTTP endpoints. You don't normally call them yourself — embed.js handles everything — but they're documented here for custom integrations, debugging, or signing identified-session tokens from your own backend.

All public widget endpoints are unauthenticated in the HTTP-headers sense: a request is identified by the bot's public_id (starts with ch_, same value as your widget data-bot-id). Each endpoint has its own per-IP rate limit listed below. Paths are appended to https://api.getchat9.live.

POST /widget/session/init

Start a new widget chat session for a visitor. Returns a session_id you'll use in subsequent calls.

Request body (JSON):

Response (JSON):

{
  "session_id": "5f4a3b1c-...-uuid",
  "mode": "anonymous"
}

mode is identified when a valid identity_token was provided, anonymous otherwise.

Errors: 404 (bot not found), 403 (tenant inactive), 400 (OpenAI API key missing for the bot).

Rate limit: 10 requests per minute per visitor IP.

POST /widget/chat

Send a user message and receive the bot's answer as a Server-Sent Events stream.

Query parameters:

Request body (JSON):

{ "message": "What is Chat9?" }

The message field is capped at 1000 characters — longer messages are rejected before reaching the bot.

Response: the response uses Content-Type: text/event-stream. The server emits two kinds of events while it works:

• data: {"type":"chunk","text":"..."} — partial reply text, emitted as the model streams. Concatenate text from successive chunks to display the answer as it arrives.
• data: {"type":"done","text":"<full reply>","session_id":"...","chat_ended":false} — emitted exactly once at the end with the complete reply, the session_id (so you can store it), and a chat_ended flag that's true when the bot decided to close the chat (e.g. after a manual escalation). The final payload can also include ticket_number when the turn opened a support ticket and sources when the answer cited URL-backed documents.

If something goes wrong server-side you may instead get one {"type":"error","code":...,"message":"..."} event before the stream closes.

Errors before the stream starts: 404 (bot not found), 422 (invalid session_id or empty message).

Rate limit: 30 requests per minute per visitor IP.

GET /widget/history

Reload the messages from an existing session — useful when the user refreshes the page and you want to rehydrate the conversation.

Query parameters: bot_id, session_id (both required).

Response: JSON object containing the session_id, ordered messages (role + content), chat_ended, and optional ticket_number.

Rate limit: 30 requests per minute per IP.

POST /widget/escalate

Open a support ticket from the widget, e.g. when the user clicks "Talk to a human". Returns the ticket number (ESC-42 style) which you can show as confirmation.

Query parameters: bot_id, session_id (both required).

Request body:

{
  "user_note": "Optional free-form text from the user",
  "trigger": "user_request"
}

Rate limit: 20 requests per minute per IP.

GET /embed.js

The widget loader script. Embed it on your site with:

<script
  src="https://api.getchat9.live/embed.js"
  data-bot-id="ch_...">
</script>

You don't normally fetch this directly — the script tag does it.

GET /widget/config

Returns widget configuration the loader uses (link-safety labels, allowed embed domains, etc.). Takes bot_id as a query parameter. You don't usually call it from your code.

Authenticated dashboard API

The endpoints below are everything the dashboard at getchat9.live talks to. They're the same surface you'd hit from a custom integration that runs server-side.

Authenticate once, then use the bearer token:

1. POST /auth/login with { "email": "...", "password": "..." } returns { "access_token": "..." }.
2. Send subsequent requests with header Authorization: Bearer <access_token>.

The bot's widget ck_... API key (issued in Settings → API keys) is a separate credential used for direct programmatic widget access; it does not authenticate dashboard routes.

For request/response shapes, payload validation, and example curl commands, jump into the live spec — api.getchat9.live/docs groups the endpoints below by tag.

Auth

Tenants

Bots

Documents and knowledge sources

Chat

Escalations

Gap analyzer

Knowledge profile and FAQ

Privacy and audit

Health

A note on chat answer models

The /widget/chat endpoint generates answers with gpt-5-mini and runs lightweight guard / validation checks with gpt-4o-mini by default. See Pricing and limits for cost guidance.

Need help?

Email support@getchat9.live if you hit something this page doesn't cover.