The **QualiBot API** is a product-owned layer over QualiBot's services. You build with clean QualiBot concepts — conversations, messages, contacts and AI — over a stable, versioned REST interface, without depending on any internal system. - **Base URL:** `https:///v1` (QualiBot is self-hosted) - **Auth:** `Authorization: Bearer qb_live_…` (or `qb_test_…`) - **Format:** JSON in, JSON out; every object carries an `object` type - **IDs:** opaque and typed, e.g. `qbcnv_…` (conversation), `qbcon_…` (contact) Jump to the [Quick Start](#1-quick-start) to make your first call. --- ## 1. Quick Start Get from zero to your first successful QualiBot API call in under five minutes. The `/v1` API is REST over HTTPS, uses JSON everywhere, and authenticates with a Bearer token. This guide walks you through creating a key, pointing at your instance, and summarizing a conversation with **Brain** — QualiBot's built-in AI. ### 1.1 Create an API key API keys are created in the QualiBot dashboard, not through the API. 1. Sign in to your QualiBot dashboard. 2. Go to **Settings → Developers → API Keys**. 3. Click **Create key** and choose: - **Mode** — a **live** key (prefix `qb_live_…`) acts on real data; a **test** key (prefix `qb_test_…`) runs against test mode so you can build safely without touching production conversations or accruing billable usage. - **Scopes** — the permissions this key grants. The summarize endpoint in this guide needs `conversations:read` and `ai:summarize`. Grant only the scopes a key actually needs. - **Rate-limit tier** — the throughput ceiling for the key. 4. Copy the key immediately. **It is shown only once** and cannot be retrieved later — store it in your secrets manager. If you lose it, revoke it and create a new one. Keys are tenant-scoped: every request is checked server-side against the account that owns the key, so a key can only ever see its own account's data. ### 1.2 Set the base URL QualiBot is self-hosted, so the host is your own domain. Every endpoint lives under the `/v1` path prefix: ``` https:///v1 ``` Throughout these docs, replace `` with your instance's hostname (for example `support.acme.com`). For convenience in the examples below, export your key and host as environment variables: ```bash export QUALIBOT_HOST="https://" export QUALIBOT_API_KEY="qb_live_your_key_here" ``` ### 1.3 Make your first request Summarize a conversation by its **id**. Conversation ids are opaque and typed — they look like `qbcnv_3s9Kd2…` (you never deal with raw internal ids). Swap in a real id from your account: ```bash curl -X POST "$QUALIBOT_HOST/v1/conversations/qbcnv_3s9Kd2XwQ7/summarize" \ -H "Authorization: Bearer $QUALIBOT_API_KEY" \ -H "Content-Type: application/json" ``` This endpoint requires the `conversations:read` and `ai:summarize` scopes. Usage is metered per call, so each successful summarize counts toward your billing. ### 1.4 Read the response A successful call returns `200 OK` with a `conversation.summary` object: ```json { "object": "conversation.summary", "conversation_id": "qbcnv_3s9Kd2XwQ7", "summary": "Customer reported a failed payment on their annual plan. Agent confirmed the card was declined by the issuer, shared retry instructions, and the customer completed payment successfully.", "created_at": "2026-07-24T14:03:11Z" } ``` Every response — success or error — also carries these headers: ``` QualiBot-Request-Id: req_8Fa2Kd91xZ QualiBot-Api-Version: v1 ``` ### 1.5 Read QualiBot-Request-Id for support `QualiBot-Request-Id` uniquely identifies a single API call. It matches the `request_id` echoed inside every error envelope. **Log it on every request.** When something goes wrong and you contact support, quoting this id lets us find the exact call in seconds — it's the fastest path to a resolution. To see the response headers with `curl`, add the `-i` flag: ```bash curl -i -X POST "$QUALIBOT_HOST/v1/conversations/qbcnv_3s9Kd2XwQ7/summarize" \ -H "Authorization: Bearer $QUALIBOT_API_KEY" ``` If the call fails, you'll get one consistent error envelope, with the same id available in the `request_id` field: ```json { "error": { "type": "qualibot/insufficient_scope", "code": "missing_scope", "message": "This key is missing the required scope: ai:summarize.", "request_id": "req_8Fa2Kd91xZ" } } ``` ### 1.6 The same call in Node and Python **Node.js** (18+, using the built-in `fetch`): ```javascript const host = process.env.QUALIBOT_HOST; const apiKey = process.env.QUALIBOT_API_KEY; const conversationId = "qbcnv_3s9Kd2XwQ7"; const res = await fetch( `${host}/v1/conversations/${conversationId}/summarize`, { method: "POST", headers: { Authorization: `Bearer ${apiKey}`, "Content-Type": "application/json", }, } ); // Always log the request id for support and debugging. const requestId = res.headers.get("QualiBot-Request-Id"); const body = await res.json(); if (!res.ok) { console.error(`Request ${requestId} failed:`, body.error); } else { console.log(`Request ${requestId} ->`, body.summary); } ``` **Python** (using `requests`): ```python import os import requests host = os.environ["QUALIBOT_HOST"] api_key = os.environ["QUALIBOT_API_KEY"] conversation_id = "qbcnv_3s9Kd2XwQ7" res = requests.post( f"{host}/v1/conversations/{conversation_id}/summarize", headers={ "Authorization": f"Bearer {api_key}", "Content-Type": "application/json", }, ) # Always log the request id for support and debugging. request_id = res.headers.get("QualiBot-Request-Id") body = res.json() if res.ok: print(f"Request {request_id} ->", body["summary"]) else: print(f"Request {request_id} failed:", body["error"]) ``` ### Next steps - **The Basics** — the request/response conventions that apply to every endpoint: typed ids, headers, error envelopes, pagination, idempotency, and versioning. - **Security** — key handling, live vs. test mode, scopes, and verifying signed webhooks with `QualiBot-Signature`. --- ## 2. The Basics This section is the mental model for the QualiBot API. Read it once and the rest of the reference will feel predictable: every endpoint shares the same base URL, authentication scheme, ID format, response envelope, error shape, headers, and rate-limiting behavior described here. ### 2.1 Base URL and versioning QualiBot is self-hosted, so the API lives on your own domain under the `/v1` prefix: ``` https:///v1 ``` Replace `` with the hostname of your installation. Every path in this reference is relative to that base. For example, the summarize endpoint is: ``` POST https:///v1/conversations/{id}/summarize ``` The major version is pinned in the path. `/v1` will not change in backward-incompatible ways: fields may be added, but existing fields and their meanings stay stable. Breaking changes ship under a future prefix (`/v2`) so your integration keeps working without surprise. Every response also echoes the version in a header (see [2.7](#27-standard-headers)) so you can assert it in tests. ### 2.2 Authentication All requests authenticate with a bearer token in the `Authorization` header: ``` Authorization: Bearer qb_live_9fJ2kD8sLmQ0xR4tVwYz1a ``` You create API keys in the QualiBot dashboard. A key's secret is **shown once, at creation time** — copy it then and store it in a secret manager. QualiBot never displays or transmits the secret again; if you lose it, rotate the key. #### Test mode vs live mode Every key is bound to a mode, encoded in its prefix: | Prefix | Mode | Behavior | | --- | --- | --- | | `qb_live_…` | Live | Operates on real data. Calls are metered and billable. | | `qb_test_…` | Test | Operates against your test surface. Use it in CI, local development, and examples. | The mode is a property of the key, not a header or query parameter — so you cannot accidentally point test code at live data by forgetting a flag. Use `qb_test_` keys everywhere except production. #### Scopes Each key carries a set of **scopes** that bound what it can do. Scopes are granular and additive; a request succeeds only if the key holds every scope the endpoint requires. For example, `POST /v1/conversations/{id}/summarize` requires both: - `conversations:read` — read the conversation being summarized - `ai:summarize` — invoke Brain to produce the summary A key missing any required scope is rejected with `403 qualibot/insufficient_scope` (see [2.6](#26-errors)). Grant each key the least set of scopes its job needs — a webhook-verification service that only reads conversations should not hold `ai:summarize`. #### Rotating and revoking keys - **Rotate**: create a new key, deploy it, then delete the old one. Because scopes and mode live on the key, a replacement can carry the exact same grants. There is no shared global secret to coordinate. - **Revoke**: delete a key in the dashboard. Revocation takes effect immediately; the next request presenting that key returns `401 qualibot/unauthorized`. Each key also has a **rate-limit tier** attached (see [2.9](#29-rate-limits)), so you can issue a lower-tier key to a noisy batch job and a higher-tier key to interactive traffic. ### 2.3 Opaque, typed resource IDs Every resource is addressed by an **opaque, typed ID**. A conversation ID looks like: ``` qbcnv_3s9Kd2Lp7Qh1Zx ``` The `qbcnv_` prefix tells you the resource type at a glance; the remainder is an opaque token. Two rules matter: 1. **Never parse or construct IDs.** Treat the whole string as opaque. Do not split on the underscore, decode it, assume a length, or infer ordering from it. The only guaranteed operations are equality comparison and storage. 2. **Raw internal IDs are never exposed.** QualiBot does not return sequential database keys. Opaque IDs mean nothing about your data (count, age, volume) leaks through the API, and the storage engine underneath can change without changing the ID you hold. An ID you stored last year keeps resolving even if the provider or backing store has been swapped out beneath it. IDs are **tenant-checked server-side**. A request may only reference IDs that belong to the account the key authenticates. Presenting an ID from another tenant returns `404 qualibot/not_found` — QualiBot returns not-found rather than forbidden so the existence of other tenants' resources is never confirmed. ### 2.4 Requests Send request bodies as JSON with `Content-Type: application/json`. Path parameters (like the conversation ID) go in the URL; there are no positional or form-encoded bodies. ```bash curl -X POST \ "https:///v1/conversations/qbcnv_3s9Kd2Lp7Qh1Zx/summarize" \ -H "Authorization: Bearer qb_test_9fJ2kD8sLmQ0xR4tVwYz1a" \ -H "Content-Type: application/json" \ -H "Idempotency-Key: 4d1c2e6a-5f9b-4a2e-8c31-0b7d9f1e2a34" \ -d '{}' ``` ### 2.5 Responses and the `object` field Successful responses return a single JSON object. Every resource carries an `object` field naming its type, so you can dispatch on the shape without inspecting the URL that produced it: ```json { "object": "conversation.summary", "conversation_id": "qbcnv_3s9Kd2Lp7Qh1Zx", "summary": "Customer reported a failed payment on checkout; Brain confirmed the card was declined by the issuer and suggested retrying with an alternate method. Customer acknowledged and the conversation was resolved.", "created_at": "2026-07-24T14:03:22Z" } ``` - `object` is a stable, dotted type name (`conversation.summary`). New fields may appear over time; treat the object as open and ignore fields you do not recognize. - Timestamps are UTC in ISO 8601 with a trailing `Z`. ### 2.6 Errors Every error — validation, auth, rate limiting, upstream provider failures — uses **one envelope**. You only need to handle this shape once: ```json { "error": { "type": "qualibot/insufficient_scope", "code": "missing_scope_ai_summarize", "message": "This key is not authorized to call Brain summarization. Add the 'ai:summarize' scope.", "request_id": "req_8Kd2Lp7Qh1Zx3s9" } } ``` - `type` — a stable, namespaced category you branch on programmatically. Always `qualibot/…`. - `code` — a finer-grained machine string for the specific failure within a type. - `message` — a human-readable explanation for logs and developers. Do not parse it; it may change. - `request_id` — echoes the `QualiBot-Request-Id` header (see [2.7](#27-standard-headers)); quote it in support requests. #### Error type reference | `type` | HTTP status | Meaning | Typical fix | | --- | --- | --- | --- | | `qualibot/invalid_request` | 400 | The request was malformed — bad JSON, a missing or invalid parameter. | Correct the request shape or parameters. | | `qualibot/unauthorized` | 401 | The key is missing, malformed, revoked, or expired. | Present a valid `Authorization: Bearer` key. | | `qualibot/insufficient_scope` | 403 | The key is valid but lacks a required scope. | Grant the missing scope, or use a key that has it. | | `qualibot/not_found` | 404 | The resource does not exist or is not visible to this tenant. | Check the ID; confirm the key belongs to the owning account. | | `qualibot/rate_limited` | 429 | You exceeded your rate-limit tier. | Back off and retry after `Retry-After` (see [2.9](#29-rate-limits)). | | `qualibot/provider_error` | 502 | An upstream dependency Brain relies on failed. | Transient; retry with backoff. | | `qualibot/internal` | 500 | An unexpected error inside QualiBot. | Transient; retry, and share `request_id` if it persists. | Branch on `type` and the HTTP status, not on `message`. `4xx` errors are your side (fix and retry deliberately); `429`, `502`, and `500` are safe to retry with exponential backoff. ### 2.7 Standard headers Every response includes: | Header | Example | Purpose | | --- | --- | --- | | `QualiBot-Request-Id` | `req_8Kd2Lp7Qh1Zx3s9` | Unique per request. Log it; it matches `error.request_id` and is the fastest way to trace a call in support. | | `QualiBot-Api-Version` | `v1` | The API version that served the request. Assert on it in tests. | QualiBot custom headers follow the `QualiBot-*` convention. There are **no** `X-`-prefixed headers anywhere in this API — for requests you send, responses you receive, or webhook deliveries. ### 2.8 Idempotency Write endpoints accept an optional `Idempotency-Key` header. Supply a unique value (a UUID is ideal) per logical operation: ``` Idempotency-Key: 4d1c2e6a-5f9b-4a2e-8c31-0b7d9f1e2a34 ``` If a request fails midway — a dropped connection, a timeout — you can safely retry it with the **same** key. QualiBot recognizes the key and returns the result of the original operation instead of performing it a second time, so a retry never produces a duplicate side effect (or a duplicate metered charge). Reuse a key only for a retry of the identical request; a genuinely new operation needs a new key. Idempotency applies to writes. Reads are naturally idempotent and ignore the header. ### 2.9 Rate limits Each API key has a **rate-limit tier**. When you exceed it, QualiBot responds with `429` and the standard error envelope: ```json { "error": { "type": "qualibot/rate_limited", "code": "tier_limit_exceeded", "message": "Rate limit exceeded for this key's tier. Retry after the interval in Retry-After.", "request_id": "req_1Zx3s9Kd2Lp7Qh8" } } ``` A `429` response includes a **`Retry-After`** header giving the number of seconds to wait before retrying. Honor it: back off for at least that interval, then resume. A well-behaved client retries only `429`/`5xx`, uses exponential backoff with jitter, and caps total attempts. If you consistently hit your limit, request a higher tier for the key rather than retrying harder. ### 2.10 Cursor pagination The API today ships a single non-list endpoint (summarize), but list endpoints are rolling out and will all page the same way — **cursor-based**, not offset-based: - **Request**: `?limit=&cursor=`. `limit` bounds the page size; `cursor` is the opaque token from the previous page (omit it for the first page). - **Response**: ```json { "data": [ /* … resource objects … */ ], "has_more": true, "next_cursor": "qbcur_7Qh1Zx3s9Kd2Lp" } ``` Loop until `has_more` is `false`, passing `next_cursor` as the next request's `cursor`. Like resource IDs, cursors are **opaque** — do not parse or synthesize them. Cursor pagination stays correct even as records are inserted or deleted between pages, which offset pagination cannot guarantee. ### 2.11 Usage metering Every API call is **metered**, per call, and metering is the basis for billing. Two practical consequences: - Use `qb_test_` keys for development and CI so you exercise the API without accruing billable live usage. - Use `Idempotency-Key` on writes so that a retried request is not counted — or charged — twice. The `QualiBot-Request-Id` on each response is the unit of record; keep it in your logs to reconcile against your usage in the dashboard. --- ## 3. Customize — Style the widget to match your brand The QualiBot live-chat **widget** is an embeddable script you drop onto any web page. Once it loads, you get a launcher bubble, a chat window, and a JavaScript SDK you can drive from your own app. This section covers how to install it, restyle it to match your brand, and use the SDK to pass identity and context into the conversation. > Availability: everything in this section ships today. ### 3.1 Install the embed snippet Each web inbox in the QualiBot dashboard generates its own embed snippet under **Inbox Settings → Configuration**. The snippet contains two values you care about: - a **website token** — a public identifier for the inbox, safe to ship in client-side code, and - a **base URL** — your self-hosted QualiBot host (`https://`). Copy the snippet from the dashboard and paste it just before the closing `` tag. It looks like this (values shown as placeholders — use the ones the dashboard gives you): ```html ``` The SDK attaches a single global object to `window` after it loads. The exact name is provided in your dashboard snippet — throughout this section we refer to it as **`window.qualibotSDK`** as a neutral placeholder. Substitute whatever global the snippet declares. > Tip: load the script with `defer`/`async` (as above) so it never blocks page render. The widget mounts itself in an isolated iframe, so its styles won't leak into your page and your page's CSS won't leak into it. ### 3.2 Set brand color, position, and theme Pass a `settings` object to `run()` to control appearance. These are read once when the widget boots. ```html ``` Key `settings` fields: | Field | Values | Purpose | | --- | --- | --- | | `color` | any hex color | Brand accent for launcher, header, and primary buttons | | `position` | `"left"` \| `"right"` | Which corner the launcher sits in | | `darkMode` | `"light"` \| `"dark"` \| `"auto"` | Force a scheme or follow the visitor's OS setting | | `type` | `"standard"` \| `"expanded_bubble"` | Compact bubble vs. bubble with a text label | | `launcherTitle` | string | Label text when `type` is `"expanded_bubble"` | | `locale` | locale code | Widget UI language | | `showPopoutButton` | boolean | Show a control that opens the chat in a separate pop-out window | > The brand color and light/dark defaults can also be set in the dashboard under **Inbox Settings → Widget Builder**, which gives you a live preview. Values passed to `run()` override the dashboard defaults, so you can vary them per page or per environment. ### 3.3 Position, launcher, and pop-out - **Launcher position** — set `settings.position` to `"left"` or `"right"`. This moves both the launcher and the chat window to that side. - **Launcher style** — `settings.type` of `"expanded_bubble"` renders a labeled pill (using `launcherTitle`); `"standard"` renders the compact circular bubble. - **Pop-out window** — set `settings.showPopoutButton: true` to let visitors detach the conversation into its own browser window, handy for long or multitasking sessions. You can also trigger it programmatically: ```js window.qualibotSDK.popoutChatWindow(); ``` ### 3.4 Locale Set the widget's interface language with `settings.locale` using a supported locale code (for example `"en"`, `"fr"`, `"de"`, `"es"`, `"pt_BR"`). If you localize your page at runtime, update the widget to match without reloading: ```js window.qualibotSDK.setLocale("fr"); ``` ### 3.5 Hide the launcher bubble Sometimes you want to open chat from your own button (for example a "Contact support" link in your nav) rather than showing the floating bubble. Hide the bubble at boot: ```js window.qualibotSDK.run({ websiteToken: "YOUR_WEBSITE_TOKEN", baseUrl: BASE_URL, settings: { hideMessageBubble: true, }, }); ``` Then open, close, or toggle the window from your own UI: ```js // Wire your own button to the widget document .querySelector("#support-button") .addEventListener("click", function () { window.qualibotSDK.toggle("open"); // "open" | "close" }); ``` You can also show or hide the launcher dynamically after boot: ```js window.qualibotSDK.toggleBubbleVisibility("hide"); // "show" | "hide" ``` ### 3.6 Identify the user Once you know who the visitor is (after they log in, say), attach their identity so conversations arrive with the right name, email, and avatar, and so returning visitors resume their history. Call `setUser` with a **stable, unique identifier** for the person, plus an attributes object: ```js window.qualibotSDK.setUser("user_10327", { name: "Ada Lovelace", email: "ada@example.com", avatar_url: "https://example.com/avatars/ada.png", phone_number: "+15551234567", // A cryptographic HMAC of the identifier for identity validation (see below) identifier_hash: "SERVER_GENERATED_HMAC", }); ``` Notes: - The first argument (the **identifier**) should be your own primary key for the user, and it must stay constant for that person across sessions and devices. - All attribute fields are optional except that you need at least enough to be useful (usually `name` and `email`). - **Identity validation**: to prevent visitors from impersonating one another, enable HMAC identity validation on the inbox and compute `identifier_hash` **on your server** as an HMAC-SHA256 of the identifier, keyed by the inbox's secret. Never ship that secret to the browser. ### 3.7 Attach custom context Custom attributes let you carry business context (plan tier, signup date, cart value, current route) into QualiBot so agents and **Brain** have what they need. **Contact-level attributes** — describe the person, persist across their conversations: ```js window.qualibotSDK.setCustomAttributes({ plan: "enterprise", signed_up_at: "2024-11-02", lifetime_value: 4820, }); ``` **Conversation-level attributes** — describe the current chat only: ```js window.qualibotSDK.setConversationCustomAttributes({ order_id: "ORD-88231", page: window.location.pathname, cart_value: 129.5, }); ``` Remove a conversation attribute when it's no longer relevant: ```js window.qualibotSDK.deleteConversationCustomAttribute("cart_value"); ``` > Define custom attributes in the dashboard first (**Settings → Custom Attributes**) so they render with friendly labels in the agent view and are available to automation and **Brain**. ### 3.8 Labels Tag the current conversation to drive routing, reporting, or automation: ```js window.qualibotSDK.setLabel("vip"); window.qualibotSDK.setLabel("billing"); // Remove one you added window.qualibotSDK.removeLabel("billing"); ``` ### 3.9 Reset on logout When a user signs out, clear their session so the next visitor on that browser starts fresh with no carried-over identity or history: ```js window.qualibotSDK.reset(); ``` Call `reset()` as part of your logout flow, then call `setUser()` again after the next login. ### 3.10 Lifecycle events The widget emits DOM events on `window` so you can react to its state — for example to fire analytics, reveal a proactive message, or lazy-load the SDK only after the visitor engages. ```js // The SDK has booted and is ready to accept API calls window.addEventListener("qualibot:ready", function () { window.qualibotSDK.setUser("user_10327", { name: "Ada Lovelace" }); }); // The chat window was opened / closed by the visitor window.addEventListener("qualibot:on-open", function () { analytics.track("chat_opened"); }); window.addEventListener("qualibot:on-close", function () { analytics.track("chat_closed"); }); // The unread-message count changed (e.g. show a badge in your own UI) window.addEventListener("qualibot:on-unread-count-changed", function (e) { updateSupportBadge(e.detail); // number of unread messages }); ``` Common lifecycle events: | Event | Fires when | | --- | --- | | `qualibot:ready` | The SDK has finished booting; safe to call `setUser`, `setCustomAttributes`, etc. | | `qualibot:on-open` | The visitor opens the chat window | | `qualibot:on-close` | The visitor closes the chat window | | `qualibot:on-unread-count-changed` | The number of unread messages changes; count is in `event.detail` | > Guarding SDK calls behind `qualibot:ready` avoids race conditions where your identity or context calls run before the widget has mounted. ### 3.11 SDK method reference | Method | Description | | --- | --- | | `run(options)` | Boot the widget with `websiteToken`, `baseUrl`, and optional `settings` | | `setUser(identifier, attributes)` | Identify the visitor and resume their history | | `setCustomAttributes(attrs)` | Attach contact-level business context | | `setConversationCustomAttributes(attrs)` | Attach context to the current conversation | | `deleteConversationCustomAttribute(key)` | Remove a conversation attribute | | `setLabel(label)` / `removeLabel(label)` | Add or remove a conversation label | | `setLocale(code)` | Change the widget UI language at runtime | | `toggle(state)` | Open or close the chat window (`"open"` \| `"close"`) | | `toggleBubbleVisibility(state)` | Show or hide the launcher (`"show"` \| `"hide"`) | | `popoutChatWindow()` | Detach the conversation into a pop-out window | | `reset()` | Clear the current session (call on logout) | With the widget branded and wired to your identity and context, agents and **Brain** see who they're talking to and why — which is exactly what powers richer follow-ups like the summarize endpoint in the REST API. --- ## 4. Integrations — Connect with third-party services QualiBot connects to the rest of your stack in three ways: **first-party connectors** you enable in the dashboard, **outbound webhooks** that push events to your systems, and programmable surfaces — the **API / custom channel** and **MCP connectors + custom tools** — that let you build your own integrations and give Brain the ability to call your services. This section covers what's available today. Everything here ships in the current QualiBot release; the REST `/v1` API footprint (see the API reference) is still growing, but the integration surfaces below are live. --- ### 4.1 First-party connectors First-party connectors are configured entirely in the QualiBot dashboard under **Settings → Integrations**. You authorize QualiBot to the third-party service (usually via OAuth), pick the inboxes or accounts to scope, and QualiBot handles the token lifecycle. No code required. | Connector | What it enables | | --- | --- | | **Slack** | Mirror conversations into a Slack channel, reply to customers directly from Slack threads, and get notified of new/assigned conversations. Agent replies typed in Slack are posted back to the customer. | | **Shopify** | Surface the contact's Shopify profile alongside the conversation — recent orders, fulfillment status, and customer lifetime value — so agents (and Brain) have order context without leaving the inbox. | | **Linear** | Create a Linear issue from a conversation, link existing issues, and keep status in sync so support and engineering share one thread of truth. | | **Notion** | Reference Notion pages and databases as knowledge while handling a conversation, keeping internal runbooks and docs one click away. | | **Dyte video** | Escalate a text conversation into a live audio/video call. QualiBot provisions the Dyte meeting and shares the join link inline with the customer. | Each connector is scoped per account and can be enabled or revoked at any time from the same settings page. Connectors are additive — enabling one never changes the behavior of your existing inboxes. --- ### 4.2 Outbound webhooks When you need QualiBot to notify **your own** services in real time — a data warehouse, an internal CRM, a custom automation — subscribe to outbound webhooks. QualiBot delivers a signed HTTP `POST` to your endpoint whenever a subscribed event occurs. #### Subscribing Add a webhook under **Settings → Integrations → Webhooks**: provide an HTTPS URL and select the events you care about (for example `conversation.created`, `conversation.status_changed`, `message.created`). QualiBot begins delivering matching events immediately. #### Delivery format Each delivery is a JSON body sent to your URL with these headers: | Header | Description | | --- | --- | | `QualiBot-Signature` | `sha256=` followed by the HMAC-SHA256 of the signed payload (see below). | | `QualiBot-Timestamp` | Unix timestamp (seconds) when the delivery was signed. | | `QualiBot-Delivery` | Unique delivery id, useful for logging and idempotent processing. | The signature is computed over the string `{timestamp}.{body}` — the `QualiBot-Timestamp` value, a literal `.`, then the raw request body — using your webhook's **signing secret** (shown once when you create the webhook) as the HMAC key. #### Verifying the signature Always verify before trusting a payload. Recompute the HMAC over `{timestamp}.{body}`, compare it against `QualiBot-Signature` with a constant-time comparison, and reject deliveries whose `QualiBot-Timestamp` is too old to blunt replay attacks. ```javascript const crypto = require('crypto'); // Express example: mount with express.raw({ type: 'application/json' }) // so `req.body` is the exact bytes QualiBot signed. function verifyQualiBotWebhook(req, signingSecret) { const timestamp = req.get('QualiBot-Timestamp'); const signature = req.get('QualiBot-Signature'); // e.g. "sha256=abc123..." // Reject anything older than 5 minutes to limit replay. const age = Math.abs(Date.now() / 1000 - Number(timestamp)); if (!timestamp || age > 300) return false; const signedPayload = `${timestamp}.${req.body}`; // req.body is the raw string/Buffer const expected = 'sha256=' + crypto.createHmac('sha256', signingSecret).update(signedPayload).digest('hex'); const a = Buffer.from(signature || ''); const b = Buffer.from(expected); return a.length === b.length && crypto.timingSafeEqual(a, b); } ``` ```python import hashlib import hmac import time def verify_qualibot_webhook(headers, raw_body: bytes, signing_secret: str) -> bool: timestamp = headers.get("QualiBot-Timestamp", "") signature = headers.get("QualiBot-Signature", "") # "sha256=..." # Reject stale deliveries to limit replay. if not timestamp or abs(time.time() - int(timestamp)) > 300: return False signed_payload = f"{timestamp}.".encode() + raw_body expected = "sha256=" + hmac.new( signing_secret.encode(), signed_payload, hashlib.sha256 ).hexdigest() return hmac.compare_digest(signature, expected) ``` Return a `2xx` promptly to acknowledge. Non-`2xx` responses (or timeouts) are retried with backoff, so make your handler idempotent by de-duplicating on `QualiBot-Delivery`. --- ### 4.3 API / custom channel The first-party connectors cover the common channels, but you can build your own. The **API channel** (also called a custom channel) lets you plug any messaging surface — a proprietary chat app, an IoT device, a niche social network — into QualiBot as a first-class inbox. The pattern is bidirectional: - **Inbound (your platform → QualiBot):** create an API inbox in the dashboard, then relay incoming customer messages to QualiBot. Each contact and conversation lives in QualiBot with the full agent inbox, routing, automation, and Brain features available — identical to a native channel. - **Outbound (QualiBot → your platform):** subscribe to `message.created` webhooks (see §4.2) filtered to your API inbox. When an agent or Brain replies, QualiBot fires the webhook to your endpoint, and you deliver the message onto your platform. Because an API inbox behaves like any other inbox, everything else — assignment rules, labels, custom attributes, reporting, and Brain summaries — works without special-casing. --- ### 4.4 MCP connectors + custom tools Connectors and webhooks move data between systems. **MCP connectors** go a step further: they let **Brain** take actions in your systems during a conversation. QualiBot speaks the Model Context Protocol (MCP), so any MCP-compatible tool server you register becomes a set of tools Brain can call — look up an order, check a shipment, open a ticket, grant a refund — grounded in live data from your side. #### Registering a tool server Add an MCP connector under **Settings → Integrations → MCP**: point QualiBot at your tool server's URL and provide its credentials. QualiBot discovers the tools your server exposes and makes them available to Brain, subject to the guardrails you configure. You choose which tools Brain may invoke and in which contexts. #### Context headers your tool server receives Every request QualiBot makes to your tool server carries `QualiBot-*` context headers so you can authorize the call and scope your response to the right tenant and conversation. Trust these only after validating the request against your connector's shared secret. | Header | Description | | --- | --- | | `QualiBot-Account` | Opaque, typed id of the QualiBot account (tenant) on whose behalf the call is made. | | `QualiBot-Conversation` | Typed conversation id (e.g. `qbcnv_…`) the tool call originates from, when applicable. | | `QualiBot-Request-Id` | Correlation id for this tool invocation — log it to trace a call end-to-end. | | `QualiBot-Api-Version` | The QualiBot API version driving the call (`v1`). | Use `QualiBot-Account` to scope every lookup to the calling tenant — never return data across accounts — and treat `QualiBot-Conversation` as the context the response will be grounded in. Return your result as the MCP tool response; Brain incorporates it into its reply or summary. #### Custom tools vs. connectors - Reach for an **MCP connector / custom tool** when you want Brain to *act* or *fetch live data* mid-conversation (dynamic, per-turn, tenant-scoped). - Reach for a **webhook** (§4.2) when you want to *react* to something that already happened in QualiBot (event-driven, fire-and-forget). - Reach for the **API channel** (§4.3) when you're bringing a whole *messaging surface* into QualiBot as an inbox. Together these cover the full range: pull your data in, push QualiBot's events out, and let Brain operate against your systems in real time. --- ## 5. CLI — Manage resources from your terminal > **Preview / roadmap — not yet available.** The QualiBot CLI is in active design. Nothing in this section ships today, and the commands, flags, and output shown here are illustrative and may change before release. If you need programmatic access right now, call the [`/v1` REST API](#) directly — the CLI is a thin, ergonomic wrapper over exactly those endpoints and will never do anything you can't already do over HTTP. Want early access? Watch the changelog or reach out to your account contact. The CLI brings the QualiBot `/v1` API to your terminal and scripts. It mirrors the REST surface one-to-one: every command maps to an endpoint, every resource is addressed by the same opaque, typed id (`qbcnv_…`), and every request carries the same scopes and rate-limit tier as your API key. Human-friendly tables by default; clean JSON when you need to pipe. ### 5.1 Install The CLI will ship as a single self-contained binary, distributed through npm and Homebrew. ```bash # npm (cross-platform) npm i -g @qualibot/cli # Homebrew (macOS / Linux) brew install qualibot/tap/qualibot ``` Verify the install and see which API version the binary targets: ```bash qualibot --version # qualibot/1.0.0 api=v1 ``` Because QualiBot is self-hosted, the CLI needs to know which instance to talk to. Point it at your domain once (persisted to `~/.config/qualibot/config.toml`) or per-command with `--host`: ```bash qualibot config set host https://your-qualibot-domain ``` ### 5.2 Authenticate The CLI uses the same `qb_live_…` / `qb_test_…` API keys you create in the QualiBot dashboard — created once, shown once, scoped, and rate-limited. There are two ways to provide one. **Interactive login** (recommended for workstations). Prompts for the key, verifies it against your host, and stores it in your OS keychain — never in plaintext: ```bash qualibot login # ? QualiBot host: https://your-qualibot-domain # ? API key: qb_live_•••••••••••••••••••••••• # ✓ Authenticated. Key scopes: conversations:read, ai:summarize # ✓ Rate-limit tier: standard ``` **Environment variable** (recommended for CI and scripts). The CLI reads `QUALIBOT_API_KEY`, and `QUALIBOT_HOST` if set. These take precedence over stored config, so the same script runs unchanged locally and in a pipeline: ```bash export QUALIBOT_HOST="https://your-qualibot-domain" export QUALIBOT_API_KEY="qb_live_…" qualibot whoami # host https://your-qualibot-domain # key qb_live_…f3a9 (last 4 shown) # scopes conversations:read, ai:summarize # tier standard ``` Pass a test-mode key (`qb_test_…`) — or add the `--test` flag to any command — to route the call through test mode. Test-mode calls are not metered for billing. See [§5.6](#56-test-mode). Sign out and remove the stored credential at any time: ```bash qualibot logout ``` ### 5.3 Summarize a conversation The first REST endpoint to ship, `POST /v1/conversations/{id}/summarize`, is exposed as `qualibot conversations summarize`. It uses QualiBot **Brain** to summarize the conversation and requires the `conversations:read` and `ai:summarize` scopes. ```bash qualibot conversations summarize qbcnv_3s9Kd2Xa7Qm ``` Default (human) output: ``` Summary · qbcnv_3s9Kd2Xa7Qm Created 2026-07-24T18:22:04Z · request req_7Yb2Qн (api v1) Customer reported a failed export on the Reports page. Agent confirmed a transient provider outage, shared a workaround, and opened a follow-up ticket. Customer acknowledged and the conversation was resolved. ``` Add `--json` for the raw response envelope — identical to what the REST endpoint returns, ready to pipe into `jq`: ```bash qualibot conversations summarize qbcnv_3s9Kd2Xa7Qm --json ``` ```json { "object": "conversation.summary", "conversation_id": "qbcnv_3s9Kd2Xa7Qm", "summary": "Customer reported a failed export on the Reports page…", "created_at": "2026-07-24T18:22:04Z" } ``` Because summarize is a write (metered) call, the CLI accepts an idempotency key so retries don't double-bill. Reuse the same key to make a retry a safe no-op: ```bash qualibot conversations summarize qbcnv_3s9Kd2Xa7Qm \ --idempotency-key "nightly-2026-07-24-qbcnv_3s9Kd2Xa7Qm" ``` ### 5.4 Manage API keys Manage the keys themselves without leaving the terminal. Newly created keys are **shown once** — capture the value immediately, exactly as in the dashboard. ```bash # List keys (secrets are never printed, only a masked suffix + metadata) qualibot keys list ``` ``` ID NAME SCOPES TIER CREATED qbkey_9f…c2 ci-summarizer conversations:read, ai:sum… standard 2026-06-01 qbkey_1a…7d dashboard-scripts conversations:read standard 2026-05-18 ``` ```bash # Create a key with an explicit scope set — the value is printed ONCE qualibot keys create \ --name "ci-summarizer" \ --scope conversations:read \ --scope ai:summarize ``` ``` ✓ Created key qbkey_9f3b…c2 (name: ci-summarizer) qb_live_S8dJ2… ← shown once, store it now Scopes: conversations:read, ai:summarize Tier: standard ``` ```bash # Revoke a key immediately (idempotent) qualibot keys revoke qbkey_9f3b…c2 # ✓ Revoked qbkey_9f3b…c2 — future requests with this key will 401. ``` A revoked key stops working at once: subsequent calls return `qualibot/unauthorized` (401), the same envelope you'd get from the REST API. ### 5.5 Inspect usage Since every non-test call is metered, `qualibot usage` reports your consumption — the same figures that back billing — so you can watch spend from the terminal or a scheduled job. ```bash qualibot usage --since 2026-07-01 --until 2026-07-24 ``` ``` Usage · 2026-07-01 → 2026-07-24 (tier: standard) ENDPOINT CALLS METERED conversations.summarize 1,284 1,284 ──────────────────────────────────────────────────── Total 1,284 1,284 ``` ```bash # Machine-readable, grouped by day, for dashboards or alerting qualibot usage --since 2026-07-01 --group-by day --json ``` ```json { "data": [ { "date": "2026-07-01", "endpoint": "conversations.summarize", "calls": 52, "metered": 52 }, { "date": "2026-07-02", "endpoint": "conversations.summarize", "calls": 61, "metered": 61 } ], "has_more": true, "next_cursor": "cur_8Kd2…" } ``` List-style commands are cursor-paginated, mirroring the REST convention (`--limit`, `--cursor` → `has_more` / `next_cursor`). Pass `--all` to have the CLI follow the cursor for you and stream every page. ### 5.6 Test mode Any command runs against test mode with a `qb_test_…` key or the `--test` flag. Test-mode calls exercise the full request path — auth, scopes, Brain — but are **not metered** and never affect billing, so they're ideal for CI and local experiments: ```bash qualibot conversations summarize qbcnv_3s9Kd2Xa7Qm --test --json ``` You can keep separate live and test keys side by side; `--test` selects test mode explicitly even when a live key is configured. ### 5.7 Output, scripting, and exit codes - `--json` — emit the raw `/v1` response (or error) envelope; everything else is suppressed so output is safe to pipe. - `--quiet` — print only ids / essential values, ideal for `$(…)` capture. - `--host`, `--test`, `--idempotency-key` — available on every relevant command, overriding config and environment. - **Errors** surface the exact REST envelope. In `--json` mode you get the object verbatim; otherwise the CLI prints a readable line and always includes the `request_id` for support: ```json { "error": { "type": "qualibot/insufficient_scope", "code": "missing_scope", "message": "This key is missing the required scope: ai:summarize.", "request_id": "req_7Yb2Qн" } } ``` - **Exit codes** map cleanly onto the error taxonomy, so scripts can branch without parsing text: | Exit | Meaning | Error type | |------|---------|------------| | `0` | Success | — | | `2` | Invalid usage / bad input | `qualibot/invalid_request` | | `3` | Not authenticated | `qualibot/unauthorized` | | `4` | Missing scope | `qualibot/insufficient_scope` | | `5` | Not found | `qualibot/not_found` | | `6` | Rate limited (honors `Retry-After`) | `qualibot/rate_limited` | | `7` | Upstream / Brain error | `qualibot/provider_error` | | `1` | Unexpected | `qualibot/internal` | A minimal CI example that summarizes a conversation in test mode and fails the job on any error: ```bash #!/usr/bin/env bash set -euo pipefail export QUALIBOT_HOST="https://your-qualibot-domain" export QUALIBOT_API_KEY="$QUALIBOT_TEST_KEY" # qb_test_… from CI secrets qualibot conversations summarize "$CONVERSATION_ID" --test --json \ | jq -r '.summary' ``` ### 5.8 What's coming As new `/v1` endpoints roll out, matching commands land alongside them — same nouns, same ids, same scopes — so anything you can do over REST you'll be able to do from the terminal. Track progress in the changelog. Until the CLI ships, the REST API is the supported path, and everything above is a preview of the experience we're building. --- ## 6. Security — How we secure your data QualiBot is a self-hosted, AI-native conversation platform, and the /v1 API is built so that the security guarantees hold inside *your* deployment. This section explains how API access is authenticated, how resources are isolated between tenants, and how QualiBot protects data in transit and at the edges (webhooks, tool/MCP fetches). Everything below reflects the actual behavior of the API described in the rest of these docs. ### 6.1 API keys API keys are created in the QualiBot dashboard. A few properties matter for security: - **Shown once, stored as a hash.** When you create a key, the raw secret (`qb_live_…` or `qb_test_…`) is displayed a single time. QualiBot never stores the raw value — only a **SHA-256 hash** is persisted. On each request, the presented key is hashed and compared. This means that even with full database access, an attacker cannot recover your keys. If you lose a key, you rotate it; you cannot retrieve it. - **Revocable.** Any key can be revoked in the dashboard. Revocation takes effect immediately — subsequent requests with that key return `401 qualibot/unauthorized`. - **Live vs. test separation.** `qb_live_…` keys operate on real data and metered usage; `qb_test_…` keys run in test mode. They are distinct credentials with distinct prefixes, so a test key can never act on live resources (and vice versa). Use the prefix to keep environments unambiguous in code and logs. Treat keys as passwords: keep them server-side, never embed them in browsers or mobile apps, and never commit them to source control. ```bash curl https:///v1/conversations/qbcnv_3s9Kd2/summarize \ -X POST \ -H "Authorization: Bearer qb_live_…" ``` ### 6.2 Scopes — least privilege Every key carries **scopes** and a rate-limit tier. Scopes are granular, action-level permissions — for example `conversations:read` and `ai:summarize`. An endpoint checks the exact scopes it needs before doing any work; the summarize endpoint, for instance, requires both `conversations:read` and `ai:summarize`. Grant each key only the scopes it actually needs. A key minted for a read-only reporting job should not carry write or AI scopes. If a key is missing a required scope, the request fails cleanly: ```json { "error": { "type": "qualibot/insufficient_scope", "code": "missing_scope", "message": "This key is missing the required scope: ai:summarize", "request_id": "req_…" } } ``` Least privilege limits blast radius: if a narrowly scoped key leaks, what it can do is bounded by its scopes. ### 6.3 Opaque IDs and tenant isolation Resource IDs are **opaque and typed** — a conversation looks like `qbcnv_3s9Kd2…`, not a sequential integer. Raw internal identifiers are never exposed, so IDs cannot be guessed or enumerated by counting up. More importantly, **every request is tenant-isolated**. The account that owns a key is resolved server-side, and each resource is checked against that account before anything is returned. A valid-looking ID that belongs to a *different* account is treated as if it does not exist — you get `404 qualibot/not_found`, never data from another tenant: ```json { "error": { "type": "qualibot/not_found", "code": "resource_not_found", "message": "No conversation was found with that id.", "request_id": "req_…" } } ``` Returning `404` (rather than `403`) for cross-tenant access is deliberate: it avoids confirming that an ID exists at all, so probing yields no information. ### 6.4 Encryption in transit All API traffic is served over **TLS (HTTPS)**. Credentials, request bodies, and responses are encrypted on the wire. Point your clients at the `https://` base URL for your deployment; plaintext HTTP is not a supported transport for the API. ### 6.5 Signed webhooks — verify authenticity Outbound webhooks are **HMAC-signed** so your receiver can prove a delivery genuinely came from QualiBot and was not tampered with. Each delivery includes: - `QualiBot-Signature` — `sha256=` followed by the HMAC-SHA256 of `{timestamp}.{body}`, keyed with your webhook signing secret. - `QualiBot-Timestamp` — the timestamp used in the signed payload. - `QualiBot-Delivery` — a unique delivery id (useful for idempotency and de-duplication). To verify, recompute the HMAC over `{timestamp}.{raw_body}` using your signing secret and compare it to `QualiBot-Signature` with a constant-time comparison. Reject anything that does not match, and reject stale timestamps to guard against replay. ```python import hashlib, hmac, time def verify_webhook(secret: str, headers: dict, raw_body: bytes) -> bool: timestamp = headers["QualiBot-Timestamp"] signature = headers["QualiBot-Signature"] # e.g. "sha256=abcd…" # Reject deliveries older than 5 minutes to prevent replay. if abs(time.time() - int(timestamp)) > 300: return False signed_payload = f"{timestamp}.".encode() + raw_body expected = "sha256=" + hmac.new( secret.encode(), signed_payload, hashlib.sha256 ).hexdigest() return hmac.compare_digest(expected, signature) ``` Always verify against the **raw** request body, before any JSON parsing or re-serialization, since re-encoding can change the bytes the signature was computed over. ### 6.6 SSRF-safe outbound fetches When Brain calls out to external tools or MCP endpoints on your behalf, those outbound fetches are hardened against server-side request forgery (SSRF): - **HTTPS only.** Non-HTTPS URLs are rejected. - **Private ranges blocked.** Requests that resolve to loopback, link-local, or private/internal address ranges are refused, so a crafted tool URL cannot be used to reach internal services or cloud metadata endpoints from inside your deployment. This keeps the "AI can fetch things" capability from becoming a pivot into your internal network. ### 6.7 Platform-level controls Beyond the API surface, the QualiBot platform provides account and workspace security controls that protect the humans and systems around your data: - **MFA / TOTP** for dashboard sign-in. - **SAML SSO** for centralized identity and provisioning. - **Audit logs** to review who did what, and when. - **Custom roles** for fine-grained, per-workspace access control that complements API scopes. Use these together with least-privilege API keys so both interactive and programmatic access follow the same principle. ### 6.8 Self-hosted and self-contained QualiBot runs inside **your** infrastructure. Your conversations, summaries, and metadata stay in your deployment — there is **no third-party telemetry** phoning data home. Because the platform is self-contained, the security boundary is one you own and can audit end to end: TLS certificates, key storage, network egress policy, and identity all live in your environment. Usage is metered per call for billing, but metering counts calls — it is not a data-exfiltration channel for conversation content. ### 6.9 Responsible disclosure If you believe you have found a security vulnerability in QualiBot or the /v1 API, please report it privately rather than filing a public issue. Contact your QualiBot deployment's security team (or the maintainers of your distribution) with details and reproduction steps, and give us a reasonable window to remediate before any public disclosure. We appreciate coordinated, responsible reports. --- ## 7. Common Issues — Troubleshoot common issues Almost every failure you'll hit against the QualiBot `/v1` API surfaces as a single, predictable error envelope. Learn to read it once and you can diagnose the rest. Every error looks like this: ```json { "error": { "type": "qualibot/insufficient_scope", "code": "missing_scope", "message": "This key is missing the required scope: ai:summarize.", "request_id": "req_8kQ2m1nZ7v" } } ``` - `type` — the stable, machine-readable class of error (branch on this). - `code` — a finer-grained reason within the type. - `message` — a human-readable explanation; may change over time, so don't parse it. - `request_id` — the identifier to quote when you contact support (also returned in the `QualiBot-Request-Id` response header). The HTTP status and the `type` always agree. The table below maps each pairing to a cause and a fix; the sections that follow go deeper. | Status | `error.type` | Usually means | | --- | --- | --- | | 400 | `qualibot/invalid_request` | Malformed request: bad JSON, missing/invalid field, wrong id shape | | 401 | `qualibot/unauthorized` | Missing, malformed, revoked, or wrong-mode API key | | 403 | `qualibot/insufficient_scope` | Key is valid but lacks a required scope | | 404 | `qualibot/not_found` | Id doesn't exist, or isn't visible to this key's account | | 429 | `qualibot/rate_limited` | You've exceeded your rate-limit tier | | 502 | `qualibot/provider_error` | Brain's upstream AI provider isn't configured or failed | | 500 | `qualibot/internal` | Something broke on our side | ### 401 — `qualibot/unauthorized` **Symptom.** Every request fails with `401` regardless of the endpoint. **Causes.** - No `Authorization` header at all. - Wrong scheme or format. It must be `Authorization: Bearer ` — a literal `Bearer`, one space, then the key. Common mistakes: sending the raw key with no `Bearer` prefix, using `Basic`, or wrapping the key in quotes. - The key was rotated, revoked, or deleted in the dashboard. Keys are shown **once** at creation; if you lost it, rotate and update your environment rather than trying to recover the old one. - Mode mismatch. A `qb_test_…` key only works in test mode and a `qb_live_…` key only in live mode — but both authenticate. A `401` here means the key string itself is wrong, not the mode. (A key used out of context still authenticates; watch for surprising empty results instead.) **Fix.** ```bash curl -sS https:///v1/conversations/qbcnv_3s9Kd2/summarize \ -X POST \ -H "Authorization: Bearer qb_live_your_key_here" \ -H "Content-Type: application/json" ``` Check, in order: 1. The header is present and spelled `Authorization`. 2. The value starts with `Bearer ` (with the trailing space). 3. The key has no stray whitespace or newline — a trailing `\n` from a copy-paste or a `.env` file is the single most common cause. 4. The key still exists and is enabled in **Dashboard → API keys**. If in doubt, rotate it and redeploy. If you're loading the key from an environment variable, print its length (not its value) to confirm it was loaded and isn't empty or truncated. ### 403 — `qualibot/insufficient_scope` **Symptom.** The key authenticates (no `401`) but a specific endpoint returns `403`. **Cause.** API keys carry explicit **scopes**. The summarize endpoint requires **both** `conversations:read` **and** `ai:summarize`. A key that has one but not the other is rejected. The `error.message` names the scope that's missing. **Fix.** Open the key in **Dashboard → API keys**, confirm both scopes are granted, and re-issue the key if you need to add a scope it wasn't created with. Then retry: ```bash curl -sS https:///v1/conversations/qbcnv_3s9Kd2/summarize \ -X POST \ -H "Authorization: Bearer qb_live_your_key_here" \ -H "Content-Type: application/json" -i ``` Scopes are granted at key creation and can't be silently widened at request time — this is by design, so a leaked read-only key can't invoke Brain. Grant the minimum a given integration needs and use separate keys for separate jobs. ### 404 — `qualibot/not_found` **Symptom.** A request to a specific resource returns `404`, even though you're sure the conversation exists. **Causes.** - The id is mistyped or truncated. Ids like `qbcnv_3s9Kd2…` are opaque and typed — a single wrong character makes them invalid. - The id is real but belongs to **another account**. Ids are tenant-checked server-side: a key can only see resources in its own account. To prevent enumeration, a resource that exists but isn't yours returns `404`, not `403`. - A forged or guessed id. Ids aren't sequential and can't be constructed by hand; only use ids QualiBot returned to you. - Wrong resource type prefix (e.g. passing a non-`qbcnv_` id where a conversation id is expected). **Fix.** 1. Re-copy the exact id from the response that created or listed it — don't hand-edit it. 2. Confirm the key and the resource belong to the same account. A `qb_test_…` key won't find live-mode resources, and vice versa. 3. Confirm the prefix matches the resource type the endpoint expects. If the id is correct and definitely in your account but you still get `404`, capture the `QualiBot-Request-Id` and contact support. ### 429 — `qualibot/rate_limited` **Symptom.** Requests start failing with `429` under load or in tight loops. **Cause.** You've exceeded the rate-limit tier attached to your API key. Each call is metered. **Fix.** Respect the `Retry-After` response header — it tells you how many seconds to wait before retrying — and back off rather than hammering the endpoint. ```bash # Retry once, honoring Retry-After resp=$(curl -sS -D /tmp/h -o /tmp/b -w '%{http_code}' \ -X POST https:///v1/conversations/qbcnv_3s9Kd2/summarize \ -H "Authorization: Bearer qb_live_your_key_here") if [ "$resp" = "429" ]; then wait=$(grep -i '^retry-after:' /tmp/h | awk '{print $2}' | tr -d '\r') sleep "${wait:-2}" # retry the request here fi ``` Recommended pattern: exponential backoff with jitter, capped at a sane maximum, and always prefer `Retry-After` when present. If you consistently hit the ceiling, batch your work, spread it over time, or request a higher tier for the key. Summarize is an AI call — treat it as expensive and cache results per conversation rather than re-summarizing on every page load. ### 502 — `qualibot/provider_error` **Symptom.** Auth and scopes are fine, the conversation id is valid, but `POST …/summarize` returns `502`. **Cause.** Summarize runs on **Brain**, which calls an upstream AI provider. A `502` means Brain couldn't get a usable response from that provider — most commonly because **the account's AI provider isn't configured**, or the provider itself returned an error or timed out. **Fix.** 1. Confirm the account has an AI provider set up (API key / model configured) in the QualiBot dashboard AI settings. Summarize cannot run without it — this is the top cause of `502` on a fresh account. 2. If the provider is configured, this is usually transient (upstream hiccup or timeout). Retry with backoff, ideally with an `Idempotency-Key` so a retry can't produce duplicate metered work. 3. If it persists, capture the `QualiBot-Request-Id` and contact support so we can inspect the provider exchange. ```bash curl -sS https:///v1/conversations/qbcnv_3s9Kd2/summarize \ -X POST \ -H "Authorization: Bearer qb_live_your_key_here" \ -H "Idempotency-Key: 5f0b0e6b-2a1e-4c1e-9c2a-6d0b0e6b2a1e" \ -H "Content-Type: application/json" ``` ### 400 — `qualibot/invalid_request` **Symptom.** `400` before any resource lookup happens. **Causes.** - Malformed JSON body (trailing comma, unquoted key, truncated payload). - Missing `Content-Type: application/json` on a request that carries a body. - A required field is absent, or a field has the wrong type or an out-of-range value. - A path parameter has the wrong shape — e.g. an id that isn't a valid typed id. **Fix.** Validate your JSON locally before sending, set the `Content-Type` header, and check the `error.message` — it names the offending field. Sending an empty body where none is required is fine; sending a body that isn't valid JSON is not. ```bash # Validate the body before you send it echo '{}' | jq . >/dev/null && echo "valid JSON" ``` ### 500 — `qualibot/internal` **Symptom.** `500` with `type: qualibot/internal`. **Cause.** An unexpected error on QualiBot's side — not something your request can fix. **Fix.** Retry with backoff (use an `Idempotency-Key` on write calls). If it persists, send us the `QualiBot-Request-Id`. ### Getting help: always include your request id Every response carries a `QualiBot-Request-Id` header, and every error also embeds it as `error.request_id`. When you open a support ticket, quote that value — it lets us pull the exact request from our logs without guesswork. ```bash # Capture the request id for a support ticket curl -sS -D - -o /dev/null \ -X POST https:///v1/conversations/qbcnv_3s9Kd2/summarize \ -H "Authorization: Bearer qb_live_your_key_here" \ | grep -i '^qualibot-request-id:' ``` Include, at minimum: the `QualiBot-Request-Id`, the endpoint and HTTP method, the `error.type` and `error.code`, the approximate timestamp (UTC), and whether the key was live or test mode. Never paste the API key itself into a ticket. ### FAQ **My key worked yesterday and now returns 401.** It was almost certainly rotated, revoked, or deleted — or your deployment is loading a stale copy. Rotate the key in the dashboard and update your environment. Remember keys are shown only once. **I get 404 for a conversation I can see in the dashboard.** The dashboard session and your API key may belong to different accounts or modes. Confirm the key's account owns the conversation, and that a `qb_test_…` key isn't looking for a live-mode resource (or vice versa). **Why is a missing resource a 404 and not a 403?** To avoid leaking whether an id exists in another account. Cross-account and nonexistent ids both return `not_found` by design. **How should I handle 429?** Read `Retry-After`, wait that long, then retry with exponential backoff and jitter. Cache summaries per conversation so you don't re-spend a metered AI call on repeat views. **Summarize returns 502 on a brand-new account.** The account's AI provider isn't configured yet. Set it up in the dashboard AI settings — Brain can't summarize without an upstream provider. **Do I need an Idempotency-Key?** It's optional but recommended on write calls (like summarize) so that a network retry can't trigger duplicate metered work. Reuse the same key for the same logical operation. **Which errors are safe to retry?** `429`, `502`, and `500` are retryable with backoff. `400`, `401`, `403`, and `404` are not — they indicate a problem in the request itself that a retry won't change. --- ## 8. Sync — Connect to a storage provider Sync is about getting your conversation data — exports, transcripts, and attachments — into object storage you control. This section covers what QualiBot does with files today, and the customer-facing Sync feature that lets you mirror data into your own bucket. > **Availability:** The deployment-level storage described in [8.1](#81-how-qualibot-stores-files-today-available) is **available today**. The customer-facing Sync feature in [8.2](#82-sync-mirror-data-to-your-own-bucket-preview--roadmap) is a **Preview / roadmap** design. The endpoints, headers, and payloads shown for Sync are a design preview and are **not yet live** — build against them only behind a feature check, and expect refinements before general availability. ### 8.1. How QualiBot stores files today (available) Every QualiBot deployment already persists uploaded files — inbound attachments, agent uploads, generated conversation exports, and avatars — in an object store chosen by whoever operates the deployment. Because QualiBot is self-hosted, this is configured once at the **deployment level**, not per API key or per tenant. Supported backends: | Backend | Notes | | --- | --- | | Local disk | Default for evaluation; not recommended for production or multi-node setups. | | Amazon S3 (and S3-compatible: MinIO, Cloudflare R2, Wasabi, DigitalOcean Spaces) | Most common production choice. | | Google Cloud Storage (GCS) | Native GCS bucket support. | | Azure Blob Storage | Native Azure container support. | This storage is an **operational** detail of the deployment. Through the /v1 API you interact with files by their opaque, typed IDs (for example an attachment id looks like `qbatt_7Fh2kQ…`); the API never exposes the raw bucket path, and access is tenant-checked server-side on every request. Where the bytes physically live is transparent to your integration. The rest of this section is about the next step: pushing a copy of that data into a bucket **you** own and control. ### 8.2. Sync — mirror data to your own bucket (Preview / roadmap) > **Coming soon.** Sync is in active design. This is a preview of the intended shape of the API so you can plan integrations. Field names, defaults, and event types may change before launch. The storage in [8.1](#81-how-qualibot-stores-files-today-available) keeps QualiBot's files inside the QualiBot deployment's own bucket. **Sync** is different: it connects a storage provider that **you** own, and mirrors your tenant's data into it. Typical uses: - Long-term archival of transcripts and attachments in your own compliance boundary. - Feeding conversation exports into your data lake or analytics pipeline. - Keeping a warm copy of attachments in a bucket your other systems already read from. A **sync connection** is a durable configuration that pairs a destination (bucket + prefix + credentials) with a policy (what to sync, and when). #### What gets synced Each connection selects one or more data classes: | Class | Contents | | --- | --- | | `transcripts` | Rendered conversation transcripts (JSON, one object per conversation). | | `attachments` | The original attachment files exchanged in conversations. | | `exports` | Full conversation exports produced by QualiBot's export jobs. | Brain summaries and other AI-generated artifacts are included inside `transcripts` when present; there is no separate class for them. #### Destination layout Synced objects are written under the `prefix` you configure, in a stable, predictable layout so downstream tooling can address them deterministically: ``` /transcripts///

/qbcnv_3s9Kd2.json /attachments/qbcnv_3s9Kd2/qbatt_7Fh2kQ.pdf /exports/qbexp_9Lm4dP.zip ``` IDs in the object keys are the same opaque, typed IDs you see elsewhere in the API, so you can join synced files back to /v1 resources without a lookup table. #### Creating a sync connection Sync is configured with the destination provider, a bucket, a prefix, credentials, and a policy. Credentials are **write-only**: they are encrypted at rest and never returned in any API response — read backs show a `credentials_present: true` flag instead. `POST /v1/sync/connections` *(preview — not yet live)* ```bash curl -X POST "https:///v1/sync/connections" \ -H "Authorization: Bearer qb_live_xxx" \ -H "Content-Type: application/json" \ -H "Idempotency-Key: 3f8a1c2e-7b6d-4a10-9f2e-5c1d0a9b8e77" \ -d '{ "provider": "s3", "bucket": "acme-qualibot-archive", "region": "us-east-1", "prefix": "qualibot/prod", "classes": ["transcripts", "attachments", "exports"], "schedule": { "mode": "event" }, "credentials": { "access_key_id": "AKIAEXAMPLE", "secret_access_key": "wJalr...EXAMPLEKEY" } }' ``` `provider` is one of `s3`, `gcs`, or `azure`. The `credentials` object is provider-shaped: - **`s3`** — `access_key_id` + `secret_access_key` (S3-compatible endpoints also accept `endpoint`). - **`gcs`** — `service_account_json` (the full service-account key document). - **`azure`** — `account_name` + `account_key`, or a `sas_token`. `201 Created` *(preview)*: ```json { "object": "sync.connection", "id": "qbsync_5Rk8vN2pQ", "provider": "s3", "bucket": "acme-qualibot-archive", "region": "us-east-1", "prefix": "qualibot/prod", "classes": ["transcripts", "attachments", "exports"], "schedule": { "mode": "event" }, "status": "verifying", "credentials_present": true, "last_synced_at": null, "created_at": "2026-07-24T14:03:22Z" } ``` On creation QualiBot writes a small probe object under the prefix to confirm the credentials and permissions. The connection moves from `verifying` to `active` once the probe succeeds, or to `error` with a diagnostic if it fails. #### Choosing when data syncs The `schedule` field controls timing: - **Event-driven** — `{ "mode": "event" }`. Objects are mirrored shortly after they are created or updated in QualiBot (a conversation closes, an attachment lands, an export finishes). Best for a continuously warm copy. - **Scheduled** — `{ "mode": "cron", "expression": "0 * * * *", "timezone": "UTC" }`. QualiBot batches changes and flushes them on your cron cadence. Best for predictable, lower-frequency archival. Both modes are incremental: only objects created or changed since the connection's `last_synced_at` are written. A sync run never re-uploads unchanged objects. #### Inspecting connections and runs `GET /v1/sync/connections` *(preview)* lists your connections using the standard cursor pagination (`?limit=&cursor=`): ```json { "data": [ { "object": "sync.connection", "id": "qbsync_5Rk8vN2pQ", "provider": "s3", "status": "active", "last_synced_at": "2026-07-24T15:00:11Z" } ], "has_more": false, "next_cursor": null } ``` Each execution is recorded as a **sync run**. `GET /v1/sync/connections/{id}/runs` *(preview)* returns them newest-first: ```json { "data": [ { "object": "sync.run", "id": "qbsyncrun_2Wc7hB", "connection_id": "qbsync_5Rk8vN2pQ", "status": "succeeded", "trigger": "event", "objects_synced": 42, "bytes_synced": 18734592, "started_at": "2026-07-24T15:00:03Z", "finished_at": "2026-07-24T15:00:11Z" } ], "has_more": false, "next_cursor": null } ``` To force an out-of-band run without waiting for the schedule, `POST /v1/sync/connections/{id}/runs` *(preview)*. Send an `Idempotency-Key` to make the trigger safe to retry. #### Sync event webhooks If you subscribe to webhooks, Sync will emit `sync.run.succeeded` and `sync.run.failed` events so your systems learn when a fresh batch has landed. These are delivered with the same signing scheme as every other QualiBot webhook — verify the `QualiBot-Signature` header (`sha256=` HMAC-SHA256 over `{timestamp}.{body}`) against `QualiBot-Timestamp`, and de-duplicate on `QualiBot-Delivery`. See the Webhooks section for the full verification recipe. ```json { "type": "sync.run.succeeded", "data": { "object": "sync.run", "id": "qbsyncrun_2Wc7hB", "connection_id": "qbsync_5Rk8vN2pQ", "objects_synced": 42, "bytes_synced": 18734592, "finished_at": "2026-07-24T15:00:11Z" } } ``` #### Scopes Sync endpoints will require dedicated scopes on your API key, granted in the QualiBot dashboard: | Scope | Grants | | --- | --- | | `sync:read` | List connections and runs. | | `sync:write` | Create, update, and delete connections; trigger runs. | A key without the required scope receives the standard `qualibot/insufficient_scope` error (`403`), carrying a `QualiBot-Request-Id` you can quote in support requests: ```json { "error": { "type": "qualibot/insufficient_scope", "code": "scope_missing", "message": "This key is missing the required scope 'sync:write'.", "request_id": "req_8kD2mQ9fLp" } } ``` #### Deleting a connection `DELETE /v1/sync/connections/{id}` *(preview)* stops all future syncing and purges the stored credentials. Objects already written to your bucket are left untouched — they are yours. Deletion is immediate and returns `204 No Content`. --- **Preview summary:** Section [8.1](#81-how-qualibot-stores-files-today-available) reflects behavior available today; section [8.2](#82-sync-mirror-data-to-your-own-bucket-preview--roadmap) is a roadmap design preview and is not yet callable. Watch the changelog for the launch announcement and the scopes going live in the dashboard.

200Success.

401Missing or invalid API key (qualibot/unauthorized).

403The key lacks a required scope (qualibot/insufficient_scope).

404Unknown, malformed, or cross-tenant id (qualibot/not_found).

429Rate limit exceeded (qualibot/rate_limited); see Retry-After.

502The AI provider failed or is not configured (qualibot/provider_error).