Welcome to qualibot

Before you begin

You need two things:

1. Your QualiBot domain. QualiBot is self-hosted, so your base URL is your own deployment:

   https://<your-qualibot-domain>/v1

2. An API key. Create one from your QualiBot dashboard under Settings → Developers → API Keys. Keys come in two modes — qb_test_… (test) and qb_live_… (live) — and are shown once at creation, so copy it somewhere safe.

   While the dashboard UI is rolling out, your account administrator can provision a key for you. See Authentication for the full key model, scopes, and security guidance.

Step 1 — Authenticate

Every request is authenticated with your key as a Bearer token:

Authorization: Bearer qb_live_9f2a…

That's it — no session, no login flow. Keep the key server-side; never ship it to a browser or mobile app.

Step 2 — Make your first request

List the contacts in your account:

curl https://<your-qualibot-domain>/v1/contacts \
  -H "Authorization: Bearer qb_live_9f2a…"

A successful response is a JSON list envelope:

{
  "object": "list",
  "data": [
    {
      "object": "contact",
      "id": "qbcon_3s9Kd2…",
      "name": "Ada Lovelace",
      "email": "[email protected]",
      "phone_number": null,
      "identifier": null,
      "custom_attributes": {},
      "created_at": "2026-07-26T18:00:00Z"
    }
  ],
  "has_more": false,
  "next_cursor": null
}

Notice id is an opaque token (qbcon_…), not a raw number — QualiBot never exposes internal identifiers. You pass these ids back verbatim in later calls.

Step 3 — Do something useful

Ask QualiBot Brain to summarize a conversation:

curl -X POST https://<your-qualibot-domain>/v1/conversations/qbcnv_3s9Kd2…/summarize \
  -H "Authorization: Bearer qb_live_9f2a…"

{
  "object": "conversation.summary",
  "conversation_id": "qbcnv_3s9Kd2…",
  "summary": "The customer asked about pricing for the Pro plan and requested a callback.",
  "created_at": "2026-07-26T18:05:00Z"
}

In your language

Node.js

const res = await fetch("https://<your-qualibot-domain>/v1/contacts", {
  headers: { Authorization: `Bearer ${process.env.QUALIBOT_API_KEY}` },
});
const { data } = await res.json();
console.log(data);

Python

import os, requests

res = requests.get(
    "https://<your-qualibot-domain>/v1/contacts",
    headers={"Authorization": f"Bearer {os.environ['QUALIBOT_API_KEY']}"},
)
print(res.json()["data"])

Core concepts (the 60-second version)

• Opaque, typed IDs — qbcon_ (contact), qbcnv_ (conversation), qbmsg_ (message), qbwhe_ (webhook endpoint). Treat them as opaque strings.
• Envelope — every object has an object field; lists return { data, has_more, next_cursor }.
• Pagination — cursor-based: pass ?limit= and the previous page's next_cursor as ?cursor=.
• Errors — one shape: { "error": { "type": "qualibot/…", "code": "…", "message": "…", "request_id": "req_…" } }. Always include request_id when contacting support.
• Every response carries QualiBot-Request-Id and QualiBot-Api-Version: v1 headers.
• Idempotency — write endpoints accept an Idempotency-Key header so retries don't double-apply.
• Webhooks — subscribe to conversation.created, message.created, and more; deliveries are signed with QualiBot-Signature.

What you can do

Next steps

• Authentication — keys, scopes, test vs live, rotation, and security.
• The Basics — the full contract: envelopes, pagination, errors, versioning, rate limits.
• Webhooks — subscribe to events and verify signatures.