SDK support and release contract
Choose a supported SDK transport and match its qualified package to your API deployment.
Q2.3/Q2.4 prepare 1.1.0 for Python, TypeScript, React, Go and the CLI. These changes are qualified locally from built packages; this does not mean version 1.1.0 has been uploaded to npm, PyPI or Go tags. sdks/release.json is the release identity manifest.
The default API root is https://api.qdivision.ai/v1. Python, TypeScript and Go accept an origin (append /v1) or an explicit API prefix (preserve it). The CLI accepts either via Q_API_BASE_URL. On 7 October 2026 an anonymous, TLS-verified request to that host returned Q's public OpenAPI schema with 86 paths. api.getq.ai failed DNS resolution from the verification environment. This establishes the chosen hostname, not deployment parity with this checkout. Always use your deployment's capability registry and OpenAPI contract.
Support matrix
| Package | Supported scope in 1.1.0 | Qualification and limits |
|---|---|---|
Python getq | Primary asynchronous client: typed retrieval, embeddings and answers, agent creation/receipt/status, resource helpers, generic JSON/raw requests and version-1 machine answer streams | Installed wheel against shared HTTP fixtures; task cancellation, custom HTTP client ownership, typed errors and pagination. Generic access covers published operations without dedicated wrappers; not every operation has a typed convenience method. |
TypeScript @getq/sdk | Primary Fetch client: equivalent core journeys, resource helpers, generic JSON/raw requests, version-1 machine answer streams | Installed tarball, strict build, unit tests and shared HTTP fixtures; AbortSignal through response consumption. Browser entry excludes Node webhook crypto; use @getq/sdk/webhooks on the server. |
React @getq/embed | QProvider, chat/answer/search, artifacts, skills and spaces widgets/hooks using the TypeScript transport | Installed import and browser bundle, public route selection and mutation failure fixture. Machine answer reduction/reconnect/final evidence qualified with the shared installed-package corpus; Q2.5 additionally qualifies the answer widget in Chromium through the loopback backend proxy; other components remain separately qualified. Requires compatible @getq/sdk and React peers. |
Go github.com/Elementary-Digital/Q/sdks/go | Chat, embeddings, answer, model listing/resolution, context-aware generic raw requests and basic streams | go vet, race-enabled tests, HTTP retry/redirect tests. No typed resource administration, agent receipt helpers or full cursor/event abstraction. Answer stream envelopes remain available through Type, Payload and Raw. |
Python getq-cli / npm @getq/cli | q authentication/account commands, usage, webhook testing and OpenAPI download | Installed wheel/module/entry point, npm launcher and local OpenAPI download. OIDC, account administration and real webhook delivery require separate environment qualification. npm launcher requires installed getq-cli; Q_CLI_PYTHON selects its interpreter. |
Use q.get_json('/capabilities') in Python or q.getJson('/capabilities') in TypeScript for discovery, and /openapi.public.json for exact schemas. Registry SDK annotations record source wrapper coverage. They do not advertise every operation as a convenience method or certify a deployed package version.
Transport behaviour
- Q owns the configured API root and bearer credentials even with an injected Python HTTP client. It leaves caller-owned clients open. Request paths must be relative to that root. Authenticated redirects are not followed; select the final deployment URL explicitly.
- Normal Python and TypeScript requests have a 30-second total deadline, including retries, backoff and response body consumption. Override per request. Python task cancellation and TypeScript
AbortSignalcancel work and backoff. TypeScript retains the signal/deadline while callers consume or cancel raw response bodies. - Streams use a 600-second default. TypeScript and Go apply an overall stream deadline; Python's HTTPX SSE readers use an I/O inactivity timeout. Close readers/streams when stopping early. Version-1 machine answer readers in Python/TypeScript both apply a total 600-second observation deadline across GET reconnections. See answer streaming for event/version/revision/terminal semantics and conservative replay eligibility.
- Maximum retries default to two additional attempts. Only GET/HEAD/OPTIONS or explicitly keyed replayable mutations may retry. Server retry denial,
outcome: unknown, unsupported keys, SSE responses and permanent conflicts stop retries. Only explicitidempotency_in_progressmakes a 409 transient. Retry-After is capped at 30 seconds. Persist operation keys before writes and reconcile uncertain receipts rather than sending a fresh operation. - Python derives a stable request ID from the API root, method, path and idempotency key for keyed calls, including across process restarts; explicit request-header overrides still win. Unkeyed calls receive a fresh ID. Python merges request headers without case-sensitive duplicates, generates a request ID and accepts caller overrides. TypeScript accepts
requestIdand headers; Go accepts headers onRequest. Both primary clients expose returned request/rate-limit metadata and Q's error code, correlation ID, retryability, outcome and receipt. An absent field stays absent; it does not become permission to retry. - Python
with_raw_responseand TypeScriptwithRawResponsepreserve status, headers and JSON or text. Empty 204 responses returnNone/undefined. GoRequestreturns status, headers and raw bytes. Go's configured client timeout applies per attempt, while the caller context bounds the whole operation including backoff. - Cursor helpers reject malformed page envelopes or repeated/missing forward cursors. Follow operation metadata: some resources use offsets or an unpaginated
itemscollection.
Migration from earlier clients
Search wrappers map legacy include_domains and exclude_domains into filters.domains and filters.exclude_domains; explicit nested filters take precedence. Read canonical results, total and mode; legacy hits may be null. Answer quality includes completeness, degraded and issues; unknown completeness remains unknown.
Page creation/listing uses /spaces/{space_id}/pages. Supply a space for listing; this public collection is unpaginated and rejects cursor/limit options. Page lookup remains /pages/{page_id}. Earlier /v1/pages list/create calls targeted an unpublished route.
React uses public /v1 operations by default. An explicit platformBaseUrl selects legacy routes for applicable resource calls; a failed call never triggers a second mutation against another prefix. Keep long-lived service credentials on your backend. The React starter uses a backend-held Q credential and a short-lived local application session. See production authentication requirements before deploying it.
Version-1 answer.events/answer.collect opt in to scoped GET reconnection; React uses the same reducer and exposes explicit approval decisions. Existing answer.stream remains legacy. Explicit POST stream reconnect attempts fail rather than replaying side effects without a qualified replay contract. Go no longer automatically retries unkeyed writes. Go consumers must migrate from the old nicholasgriffintn/getq-go module path. The release tag for the repository submodule is sdks/go/v1.1.0; it must point at the same qualified source revision. Creating that remote tag is a separate release action.
Build, qualify and publish
The following steps are for Q maintainers. Application developers should use Build with Q; building release archives is not an integration prerequisite.
Use the deterministic setup, Node 22, Java 17 and Go 1.22 or later:
.venv/bin/python -m scripts.release.sdk_packages --install
.venv/bin/python -m scripts.release.sdk_packages
.venv/bin/python -m scripts.release.sdk_packages --verify .cache/q-test/release/sdk-packagesThe runner builds in disposable directories using locked npm dependencies and pinned wheel tooling. It installs wheels/tarballs outside the source checkout, bundles the browser entry and React, and exercises one local HTTP fixture matrix for both primary clients. Core retrieval/answer/embedding/agent/resource fixture payloads are validated against the public contract. No providers are called. Go is vetted/tested from the copied source. Existing checked-in dependency deletions and unused legacy generated directories are not restored.
The output contains six archives and a receipt with source/workflow SHA-256 hashes, archive hashes, Git revision and qualification results. A dirty local checkout is identified by its source hashes, not by Git HEAD alone. --expected-sha additionally requires matching checkout/source/version for promotion. An archive-only verification without that option checks the receipt and archive inventory/digests, not remote provenance.
Required CI's sdk-contract job qualifies these archives alongside fresh OpenAPI generation, compilation and the clean developer journeys. The manual Publish SDKs workflow requires a successful main push CI run with all required jobs and CI Passed, a matching sdk-v1.1.0 tag and the qualified-sdk-packages artifact. It downloads that run's archives, validates identity/digests, then uploads those same files through the Production environment. It rechecks CI/tag evidence and debt expiry after the environment gate, and never rebuilds for publication. Partial, failed, PR, foreign, wrong-branch or mismatched evidence fails closed; remote approvals and registry credentials remain operator-managed. Select only unfinished package groups when recovering a partially completed registry upload; already-published versions cannot be replaced.
See release checks, ADR 0012 and Q2.3 evidence. Hosted CI, dependency audits, production deployment and live-provider accuracy/performance remain separate gates.
Confirm public availability
The publication workflow downloads each selected package anonymously from npm or PyPI and checks its SHA-256 against the qualified archive receipt. A successful upload alone does not close the publication gate. The workflow saves sdk-registry-receipt only after the selected downloads match. This verifies package distribution; hosted API compatibility and live journeys remain separate gates.
To recheck distribution without uploading immutable versions again, use the same qualified archives and release checkout:
python -m scripts.release.sdk_registry --archives qualified-sdk-packages --sdk all --output sdk-registry-receipt.jsonFor a partial release, select python, typescript, react or cli; cli checks both its npm launcher and Python package. Missing packages, yanked wheels or different bytes fail verification. Go tags retain their separate release process. After confirming public installation and the matching deployment, update the installation status in the consumer guide and SDK support documentation.
New durable run controls are available through the generic JSON transports in the primary SDKs. Q3.1 adds server lifecycle guarantees. Q3.2 adds managed-agent journal readers to the prepared Python/TypeScript packages; Go/CLI retain generic transport access. Q3.3 adds tool invocation polling, result submission and resume helpers to those prepared packages. Package publication is still a separate release step.