Build with Q

Use Q from your own application directory. You do not need the Q repository, Docker, a model-provider account or Q's build tools. You need a provisioned Q organisation, an API key with ai:answer, and Python 3.11+ or Node 22+.

Get accessCopy Anchor Link

Sign in to your deployment's developer portal, create or select an organisation, then generate an API key. Owners and admins can manage keys. If your organisation is managed for you, ask its administrator for access. Copy the key when it is created; it is shown only once.

Use the API root supplied with that environment, including /v1. The standard root is https://api.qdivision.ai/v1. Configure Q_API_BASE_URL and Q_API_KEY in your backend's environment or secret manager. Keep the key out of source files and browser code. See authentication for scopes and organisation access.

A real request can incur usage charges. Confirm your environment's limits before running it; a q_test_ prefix alone does not mean calls are free or data is isolated. To explore without a provisioned account, use the separate local sandbox tutorial.

Get your first answerCopy Anchor Link

These examples use standard libraries and work independently of SDK publication. Save one example in your application directory, configure the two environment variables above, and run it. They make one non-streaming request and display the final answer together with its evidence and quality. They do not retry a failed request automatically.

PythonCopy Anchor Link

Save as first_answer.py, then run python3 first_answer.py.

import json
import os
import urllib.error
import urllib.request

base = os.environ["Q_API_BASE_URL"].rstrip("/")
request = urllib.request.Request(
    base + "/answer",
    data=json.dumps({"query": "What is retrieval augmented generation?", "stream": False}).encode(),
    headers={
        "Authorization": "Bearer " + os.environ["Q_API_KEY"],
        "Content-Type": "application/json",
    },
    method="POST",
)
# Do not forward a service credential to a redirected URL.
class NoRedirect(urllib.request.HTTPRedirectHandler):
    def redirect_request(self, req, fp, code, msg, headers, newurl):
        return None

try:
    with urllib.request.build_opener(NoRedirect).open(request, timeout=120) as response:
        result = json.load(response)
except urllib.error.HTTPError as error:
    raise SystemExit(f"Q returned HTTP {error.code}; check the API root, scopes and troubleshooting guide.") from None

print(json.dumps({name: result.get(name) for name in ("answer", "sources", "citations", "quality")}, indent=2))

JavaScriptCopy Anchor Link

Save as first-answer.mjs, then run node first-answer.mjs.

const { Q_API_BASE_URL, Q_API_KEY } = process.env;
if (!Q_API_BASE_URL || !Q_API_KEY) throw new Error("Set Q_API_BASE_URL and Q_API_KEY on your backend.");
const response = await fetch(`${Q_API_BASE_URL.replace(/\/$/, "")}/answer`, {
  method: "POST",
  redirect: "error",
  headers: { Authorization: `Bearer ${Q_API_KEY}`, "Content-Type": "application/json" },
  body: JSON.stringify({ query: "What is retrieval augmented generation?", stream: false }),
  signal: AbortSignal.timeout(120_000),
});
if (!response.ok) throw new Error(`Q returned HTTP ${response.status}; check the API root, scopes and troubleshooting guide.`);
const { answer, sources, citations, quality } = await response.json();
console.log(JSON.stringify({ answer, sources, citations, quality }, null, 2));

Success returns answer, sources, citations and quality. Read the evidence and quality before displaying an answer as grounded; successful HTTP delivery alone does not establish factual accuracy. Real wording and sources depend on your environment. A 401 means the credential needs attention; a 403 can mean missing scope, entitlement or resource permission. See troubleshooting.

Adopt an SDKCopy Anchor Link

The prepared SDK release is 1.1.0. On 13 October 2026, public npm and PyPI checks returned 404 for @getq/sdk@1.1.0 and getq==1.1.0. Until publication is verified, use the HTTP examples above or request a qualified archive from your Q administrator. You do not need to build an SDK yourself.

After your administrator confirms publication of this exact version, install in your application's environment:

# Python: inside your application's virtual environment
python -m pip install 'getq==1.1.0'

# JavaScript / TypeScript: inside your application package
npm install --save-exact @getq/sdk@1.1.0

Do not substitute an unrelated package or an older version if installation fails. The SDK support matrix describes supported methods, transport behaviour and deployment compatibility. SDK release preparation belongs to Q maintainers, not application setup.

Once installed, use the tested SDK first-answer examples. They are shared with the developer portal and package READMEs.

Build your integrationCopy Anchor Link

• Retrieve private knowledge: headless knowledge.
• Show streaming answers in a browser: backend proxy and answer streaming.
• Execute durable work: run lifecycle.
• Check production readiness: integration checklist.

For Q contributors testing all three journeys from source, use the repository qualification tutorial.

Develop with isolated dataCopy Anchor Link

Create an isolated development organisation for sample knowledge, separate credentials, provider-spend controls and readiness checks before using production data.