qbrin API Reference

Overview

The qbrin REST API turns everything your team has connected into cited, grounded answers. Every response either links to the exact source it came from, or tells you it does not know — it is built to cite or abstain rather than guess. All requests are made over HTTPS to a single base URL.

Authentication

Every request authenticates with an API key sent as a Bearer token. Create one in the console under Settings → API keys. The key is shown once at creation and always starts with qbrin_ — store it somewhere safe, because it can never be retrieved again.

Authorization: Bearer qbrin_3f9a…c1d7

Key scopes

Give each integration the least privilege it needs. Scope is enforced per HTTP method, so a read-only key that leaks can never write.

Add content

Two ways to push knowledge in over the API. Both feed the same pipeline — text is chunked, embedded into the vector index and entity-extracted automatically. There is no separate "embed" call; you watch it complete (next section) and then it is answerable.

Send text or markdown directly. Best for programmatic, per-document ingestion.

curl https://app.qbrin.com/api/documents \
  -H "Authorization: Bearer qbrin_3f9a…c1d7" \
  -H "Content-Type: application/json" \
  -d '{ "title": "Refund Policy", "content": "Customers may request a full refund within 30 days…" }'

Bulk-ingest a folder of files by uploading a single .zip. qbrin streams the archive to disk (never buffering it in memory), verifies it is a real ZIP by its magic bytes, extracts the text from supported files, and ingests each one. The request returns immediately with a job id; a worker does the heavy lifting.

curl https://app.qbrin.com/api/uploads/zip \
  -H "Authorization: Bearer qbrin_3f9a…c1d7" \
  -F "file=@handbook.zip"

Embedding & status

You never call an embed endpoint directly. Everything you ingest flows through one pipeline — extract text, chunk, embed into the vector index, extract entities — and only becomes answerable once the embedding step finishes. These endpoints let you watch that happen.

Track a ZIP upload

Poll with the jobId from the upload response until phase is "done".

{
  "jobId": "upload-7c1e9a4b2f0d",
  "phase": "embedding",        // queued | extract | embedding | done | error
  "state": "done",
  "ingested": 42,              // files turned into documents
  "skipped": 3,                // unsupported / empty files
  "embed": { "total": 380, "embedded": 294 },   // chunks embedded — progress bar
  "files": [ "handbook/onboarding.md", "handbook/pto.pdf" ],
  "error": null
}

Track a single document

For content added via POST /api/documents, fetch the document and read chunkCounts — it moves from pending to embedded as the vector index fills in.

{
  "document": { "id": "doc_a91f22e0", "title": "Refund Policy", "extractStatus": "done" },
  "chunkCounts": { "pending": 0, "embedded": 6, "extracted": 6 }
}

Use GET /api/documents?limit=50 to list recently ingested documents. Embedding is fully managed — the model, dimensions and hardware are a server-side detail you do not configure per request.

Ask

The core endpoint. Send a question; qbrin retrieves across the connected sources, composes an answer grounded in what it found, verifies it, and returns the answer with its citations. If the answer is not supported, it abstains instead of guessing. Asking logs a query, so it is a POST and needs a write (or admin) key.

Request body

Example request

curl https://app.qbrin.com/api/ask \
  -H "Authorization: Bearer qbrin_3f9a…c1d7" \
  -H "Content-Type: application/json" \
  -d '{ "question": "What is our refund window?", "k": 8 }'

Response 200

{
  "answer": "Customers may request a full refund within 30 days of purchase. [1]",
  "queryId": "qy_8fb2a1c0",
  "citations": [
    {
      "n": 1,
      "documentId": "doc_a91f",
      "source": "gdrive",
      "title": "Refund Policy.pdf",
      "snippet": "…a full refund within 30 days of purchase…",
      "authorEmail": "ops@acme.com",
      "occurredAt": "2026-03-11T00:00:00Z"
    }
  ],
  "trust": {
    "decision": "allow",
    "level": "verified",
    "axes": { "provenance": "cited", "entailment": "passed" },
    "certificateId": "a1b2c3d4e5f6"
  },
  "usage": { "prompt_tokens": 1840, "completion_tokens": 42 },
  "timings": { "retrieveMs": 210, "totalMs": 640 }
}

The trust object

When present, an answer also carries a trust certificate so you can decide programmatically whether to show, flag or withhold it. Use it as an additional signal on top of the citation check above.

Streaming (Server-Sent Events)

Send Accept: text/event-stream to stream the answer token-by-token. Read named events until done.

You may also see informational qwsec and fallback events. Ignore any event name you do not recognise so the stream stays forward-compatible.

curl -N https://app.qbrin.com/api/ask \
  -H "Authorization: Bearer qbrin_3f9a…c1d7" \
  -H "Accept: text/event-stream" \
  -H "Content-Type: application/json" \
  -d '{ "question": "Summarize last quarter wins" }'

event: token
data: {"text":"We closed 12 enterprise "}
event: citations
data: {"citations":[…]}
event: done
data: {"queryId":"qy_8fb2","trust":{"decision":"allow"}}

Search

Retrieve matching documents, people and knowledge across the connected sources without composing an answer. Useful for a search box or feeding your own pipeline. Permission-aware, like everything else.

curl "https://app.qbrin.com/api/search?q=onboarding&sources=gdrive&limit=10" \
  -H "Authorization: Bearer qbrin_3f9a…c1d7"

Answer feedback

Tell qbrin whether an answer was useful, using the queryId returned by /api/ask. This tunes future answers.

curl https://app.qbrin.com/api/qy_8fb2a1c0/feedback \
  -H "Authorization: Bearer qbrin_3f9a…c1d7" \
  -H "Content-Type: application/json" \
  -d '{ "helpful": 1 }'

Manage API keys

You will normally create and revoke keys in the console (Settings → API keys), but the same operations are available programmatically. These run in your signed-in session, not with a Bearer key.

// 201 Created — the raw secret is returned exactly once, at token.token
{
  "token": {
    "id": "tok_a1b2c3",
    "name": "ci-pipeline",
    "prefix": "qbrin_3f9a",
    "scopes": ["read"],
    "expiresAt": null,
    "createdAt": "2026-07-12T00:00:00Z",
    "token": "qbrin_3f9a2b7c8d1e…c1d7"
  }
}

Errors & limits

Errors return a JSON body { "error": "…" } with a standard HTTP status.

Rate limits

Requests are rate-limited per key to protect the service — comfortable for normal interactive and batch use. If you expect sustained high volume, reach out at hello@qbrin.com and we will raise your ceiling.