Docs

ChadaQ docs

How to set up your assistant, adjust it and keep it running well.

DocsDevelopers

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.

Shell
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.

Each question counts toward your monthly messages, the same as the widget. A key can send 60 requests a minute.

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:

FieldTypeNotes
messagestringRequired. 1–2,000 characters.
conversation_idstring (UUID)Optional. Continues a conversation this workspace started through the API.
streambooleanOptional, default false. true sends server-sent events.
timezonestringOptional. An IANA time zone, such as Europe/London.
userobjectOptional. { 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.

JSON
{
  "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:

EventDataNotes
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": "…" }.

StatusCodeWhen
401invalid_api_keyThe key is missing, malformed, unknown or revoked.
402api_plan_requiredThe workspace’s plan doesn’t include the API.
402message_limit_reachedThe workspace has used its messages for the month.
402quota_exceededThe workspace has used its AI tokens for the month.
403workspace_suspendedThe workspace is suspended for billing.
403workspace_suspended_by_staffChadaQ has suspended the workspace.
404conversation_not_foundconversation_id isn’t an API conversation of this workspace.
422validation_errorAn unknown field, an empty message, a message over 8,000 characters or a value of the wrong type.
422message_too_longmessage is longer than 2,000 characters.
429rate_limit_exceededToo many requests. Retry after the Retry-After header’s 60 seconds.
502provider_errorThe assistant couldn’t answer right now. Try again.
503retrieval_unavailableThe 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.

Still stuck? Contact support