developers · the entrance · https://api.qdivision.ai/v1
Build on the record.
One API root, one key, standard libraries. Every call returns what it did, what it read, and what it could not do. No repository, no Docker, no model-provider account.
This page is the way in. A dedicated developer site is in preparation; until it opens, the documentation and the API reference below are the whole of it.
01
Documentation
Authentication, idempotency, approvals, streaming, errors and the rest of the contract, each with its exact behaviour and its limits.
open
02
API reference
Every public operation with its policy, scopes, limits and availability, generated from the same registry the service runs on.
open
03
SDKs
Python and TypeScript, prepared at 1.1.0 and qualified locally. Until the exact version is published, HTTP is the supported path.
prepared · publication to be confirmed
the first call · in motion
A call goes in. A receipt comes out.
01 · the call
The card is the request.
It carries the query, the key's scopes and nothing else. The console is idle and the meter is at rest.
1 · the first call
One file, one answer.
Set Q_API_BASE_URL and Q_API_KEY in your backend. Save one file. Run it. The response carries the answer, its sources, its citations and a quality record.
Keys stay on the server. A browser reaches Q through your own backend proxy, never with the key in the page.
A 401 means the credential needs attention. A 403 can mean a missing scope, entitlement or resource permission. A real request can incur usage charges.
first_answer.py
import json, os, urllib.request
base = os.environ["Q_API_BASE_URL"].rstrip("/")
req = urllib.request.Request(
base + "/answer",
data=json.dumps({"query": "Which invoices are more than thirty days overdue?", "stream": False}).encode(),
headers={"Authorization": "Bearer " + os.environ["Q_API_KEY"], "Content-Type": "application/json"},
method="POST",
)
with urllib.request.urlopen(req, timeout=120) as response:
result = json.load(response)
print({k: result.get(k) for k in ("answer", "sources", "citations", "quality")})- answer
- string
- sources
- array · provenance per item
- citations
- array · spans mapped to sources
- quality
- record · read before display
the catalogue
The parts.
Twelve surfaces you will lean on, with the stability the registry gives each one today.
01
beta
Answer
POST /v1/answer
A grounded answer with sources, citations and a quality record. Streaming on request.
02
stable
Search
POST /v1/search
Retrieval inside the tenant boundary, row-level security forced at the database, provenance per result.
03
beta
Runs
POST /v1/agents/{agent_id}/runs
A durable run with a receipt on submission. Poll it, read its events, resume or cancel it.
04
beta
Approvals
POST …/runs/{run_id}/tool-approval/{approval_id}
Decide a protected action with the version in hand. Bound, retained, consumed once.
05
beta
Streaming
GET /v1/answer/streams/{run_id}
Versioned answer streaming over SSE, citation markers mapped as they arrive.
06
beta
Knowledge
POST /v1/knowledge/retrieve
Index private material and retrieve it headless, without a browser session.
07
beta
Webhooks
POST /v1/webhooks
Deliveries with a record, a test endpoint and a replay for any delivery.
08
beta
MCP
POST /v1/mcp
Q's tools over the Model Context Protocol, and servers registered per tenant.
09
stable
Embeddings
POST /v1/embeddings
Embeddings from the configured provider, with the model named in the response.
10
stable
Capabilities
GET /v1/capabilities
Every public operation with its policy, scopes, limits and availability. The schema at openapi.public.json.
11
stable
Status
GET /v1/status
Service status, incidents and a feed, readable without a credential.
12
stable
Reference
GET /v1/reference
The API reference, generated from the registry and served by the API itself.
Stability is the registry's own word, version 2026-10-12. Beta means qualified locally with the production gates still pending.
the rules you lean on
Five pages of the contract.
auth
Authentication
Scoped credentials and tenant identity. Keys stay on the server.
idem
Idempotency
Retained keys and uncertain outcomes. Inspect before you retry.
appr
Approvals
Explicit, version-bound decisions before protected actions.
sse
Streaming
Versioned SSE with citation markers mapped as they arrive.
err
Errors
Stable codes with the state they leave. 409, 422, 503 each mean one thing.
the register
Where it stands.
- 8
- stable
- policies the registry marks stable
- 35
- beta
- qualified locally, production gates pending
- 15
- alpha
- behind flags or not yet implemented
- 0 / 7
- production gates
- none passed yet, stated here until that changes
Not yet.
The SDK archives for Python (getq 1.1.0) and TypeScript (@getq/sdk 1.1.0) are prepared and qualified locally, not published. Confirm the exact version with your Q administrator before installing anything; do not substitute an unrelated package.
The dedicated developer site is in preparation. This page, the documentation and the API reference are the entry points until it opens.
Try the contract without credentials.
The repository ships a sandbox that accepts one fixed fixture token and returns synthetic retrieval, answer and run records. It calls no model, runs no agent and reaches no tenant. It tests your HTTP integration and nothing else.
from a checkout
python3 examples/sandbox/server.py export Q_API_BASE_URL=http://127.0.0.1:8787/v1 export Q_API_KEY=q_local_sandbox sh examples/curl-quickstart/run.sh