API v1

BotIQ API

Programmatic access to a workspace: ask the chatbot a question, add a URL to its knowledge base, or read back sources, conversations (metadata only), knowledge gaps and usage counts. Every request is authenticated with a workspace-scoped API key — the workspace is never a request parameter, it comes from the key. Each key carries the scopes it needs; create one from the workspace Settings page in the dashboard. It is shown once, at creation. Successful responses carry X-RateLimit-* and X-Quota-* headers.

Download openapi.json

Authentication

A workspace-scoped API key, sent as `Authorization: Bearer bq_...`. Each key carries one or more scopes (`chat:read`, `sources:write`, `sources:read`, `conversations:read`, `gaps:read`, `analytics:read`); a request needs the scope its endpoint requires. Rate-limited to 60 requests/minute per key.

post/api/v1/chatscope: chat:read

Ask the chatbot a question

Runs retrieval against the workspace's knowledge base and returns one JSON answer — not a stream. Counts against the same monthly plan limit as the embedded widget.

Example

curl https://your-app.example/api/v1/chat \
  -H "Authorization: Bearer bq_..." \
  -H "Content-Type: application/json" \
  -d '{
  "question": "What is your refund policy?"
}'

200 An answer, with its confidence and the source chunks it drew on.400 The request body failed validation.401 Missing, malformed, revoked or unknown API key.403 The key is valid but lacks the scope this endpoint requires.429 More than 60 requests in the last minute for this key.500 Something failed on our side. The response body never includes internals.

get/api/v1/sourcesscope: sources:read

List knowledge-base sources

Returns the workspace's sources as metadata only — id, name, type, status and counts. Never source content. Not metered against message quota.

200 The most recent 200 sources, newest first.401 Missing, malformed, revoked or unknown API key.403 The key is valid but lacks the scope this endpoint requires.429 More than 60 requests in the last minute for this key.500 Something failed on our side. The response body never includes internals.

post/api/v1/sourcesscope: sources:write

Add a URL to the knowledge base

Queues a URL or sitemap for ingestion; returns immediately with the created source in `pending` status. Ingestion happens asynchronously — poll the dashboard, or your own workspace webhooks, for completion.

Example

curl https://your-app.example/api/v1/sources \
  -H "Authorization: Bearer bq_..." \
  -H "Content-Type: application/json" \
  -d '{
  "url": "https://example.com/docs/faq",
  "type": "url"
}'

201 The source was created and queued for ingestion.400 The request body failed validation.401 Missing, malformed, revoked or unknown API key.403 The key is valid but lacks the scope this endpoint requires.429 More than 60 requests in the last minute for this key.500 Something failed on our side. The response body never includes internals.

get/api/v1/conversationsscope: conversations:read

List conversations (metadata only)

Conversation ids and metadata — session, channel, timing, resolution state. Message content is never exposed on the API.

200 One page of conversation metadata.400 The request body failed validation.401 Missing, malformed, revoked or unknown API key.403 The key is valid but lacks the scope this endpoint requires.429 More than 60 requests in the last minute for this key.500 Something failed on our side. The response body never includes internals.

get/api/v1/gapsscope: gaps:read

List knowledge gaps

Questions the chatbot could not answer from the knowledge base, with how often they were asked.

200 Up to 100 gaps, most recently asked first.400 The request body failed validation.401 Missing, malformed, revoked or unknown API key.403 The key is valid but lacks the scope this endpoint requires.429 More than 60 requests in the last minute for this key.500 Something failed on our side. The response body never includes internals.

get/api/v1/analyticsscope: analytics:read

Workspace usage counts

Counts only: conversations started in the last 30 days, messages exchanged, open gaps, and feedback tallies.

200 Aggregate counts for the key’s workspace.401 Missing, malformed, revoked or unknown API key.403 The key is valid but lacks the scope this endpoint requires.429 More than 60 requests in the last minute for this key.500 Something failed on our side. The response body never includes internals.