Chat API
Ask your assistant questions from your own server. Available on Growth and Scale.
Create a secret key in Settings & billing → API keys. Keep it on your server: anyone with the key can read your content.
curl https://api.chadacreatives.com/api/v1/chat \
-H "Authorization: Bearer $CHADAQ_API_KEY" \
-H "Content-Type: application/json" \
-d '{"message": "Do you offer group rates?"}'Send "stream": true for server-sent events. Pass the conversation_id you get back to keep a conversation going.
Keys
A key is cq_sk_ followed by 43 characters. It’s shown once, when you create it; after that the dashboard shows only its first eight and last four characters. A workspace can have up to 10 active keys; revoke one to make room for another. Keys stop working while the workspace is on Starter and work again when you upgrade.
Call the API from your server only. It sends no CORS headers, so a browser can’t call it from another site.
Request
POST /api/v1/chat with a JSON body:
| Field | Type | Notes |
|---|---|---|
| message | string | Required. 1–2,000 characters. |
| conversation_id | string (UUID) | Optional. Continues a conversation this workspace started through the API. |
| stream | boolean | Optional, default false. true sends server-sent events. |
| timezone | string | Optional. An IANA time zone, such as Europe/London. |
| user | object | Optional. { name, email } labels the conversation in your dashboard. |
Any other field gets 422 validation_error.
Response
Without "stream", the whole answer comes back as one JSON body. is_fallback is true when your sources didn’t cover the question and the assistant sent your fallback message.
{
"conversation_id": "0199…",
"message_id": "0199…",
"answer": "Yes, for groups of eight or more.",
"is_fallback": false,
"citations": [
{ "source_id": "0199…", "label": "Group bookings", "page": null, "source_type": "url" }
],
"model": "…",
"latency_ms": 1840
}Streaming
With "stream": true the response is text/event-stream, with these events in order:
| Event | Data | Notes |
|---|---|---|
| meta | { conversation_id, message_id } | First. |
| token | { t } | The next piece of the answer. Repeats. |
| citations | { citations } | The same citations as the JSON body. |
| done | { is_fallback, needs_follow_up, latency_ms, sources, model } | Last. |
| error | { code, message } | Ends the stream when the assistant can’t answer. |
A ": ping" comment arrives after every 15 seconds without an event, to keep the connection open.
Over the API the assistant only answers questions: it never hands a visitor to your team or offers a booking.
Errors
An error comes back as JSON: { "code": "…", "message": "…" }.
| Status | Code | When |
|---|---|---|
| 401 | invalid_api_key | The key is missing, malformed, unknown or revoked. |
| 402 | api_plan_required | The workspace’s plan doesn’t include the API. |
| 402 | message_limit_reached | The workspace has used its messages for the month. |
| 402 | quota_exceeded | The workspace has used its AI tokens for the month. |
| 403 | workspace_suspended | The workspace is suspended for billing. |
| 403 | workspace_suspended_by_staff | ChadaQ has suspended the workspace. |
| 404 | conversation_not_found | conversation_id isn’t an API conversation of this workspace. |
| 422 | validation_error | An unknown field, an empty message, a message over 8,000 characters or a value of the wrong type. |
| 422 | message_too_long | message is longer than 2,000 characters. |
| 429 | rate_limit_exceeded | Too many requests. Retry after the Retry-After header’s 60 seconds. |
| 502 | provider_error | The assistant couldn’t answer right now. Try again. |
| 503 | retrieval_unavailable | The question couldn’t be searched right now. Try again. |
Limits
Each key can send 60 requests a minute, and a workspace 120 a minute across all its keys. An address that sends 30 invalid keys in a minute is refused for the rest of that minute, even with a valid key. Every refusal is a 429 with Retry-After: 60.