Headless knowledge and generation

A backend can search authorised knowledge, assemble context, extract structured values and produce verified documents without a Q UI. This additive profile requires HEADLESS_API_ENABLED=true in the provisioned deployment; it defaults to false. Check the deployment's capabilities and public OpenAPI before calling it. The locally qualified SDK 1.1.0 archives include Python, TypeScript and Go methods; they are not published packages yet.

Operations and credentialsCopy Anchor Link

Use a server-side bearer credential. Tenant and owner come from authentication; requests cannot supply another tenant, user, gateway URL or gateway credential. New operations enforce these scopes even when the legacy Q_ENFORCE_AI_SCOPES compatibility switch is off. Exact scopes, the matching namespace wildcard or * satisfy the check; resource permissions still apply.

Existing ingestion status, artifact metadata/download and /v1/memory CRUD remain owner/resource-bound under their existing advertised policies. Ingestion status requires read. Memory CRUD does not acquire a new scope requirement in this compatibility release; context assembly explicitly requires memory:read before including memory. The key issuance API accepts the new scopes.

Retrieval and federationCopy Anchor Link

{
  "query": "What changed in the retention policy?",
  "sources": ["local", "tenant_endpoint"],
  "mode": "hybrid",
  "filters": {"document_type": "policy"},
  "limit": 10,
  "match_threshold": 0.5
}

local uses Q's indexed knowledge. Choose keyword, vector or hybrid; keyword avoids an embedding call. Hybrid runs keyword and vector branches concurrently, uses the tenant's shared reciprocal-rank-fusion configuration, and deduplicates local chunks. Filters support document UUID, document type and authorised space. Local filters apply before ranking; permissions are checked again before emitting hits. Search cannot disclose whether an inaccessible document exists.

tenant_endpoint uses only the authenticated tenant's configured retrieval gateway. It does not fall back to a global endpoint when tenant configuration is absent or unreadable. Operators provision TenantConfig.model_config.retrieval through the existing configuration plane. Its URL, credentials and outbound access are governed by outbound policy. A gateway may search several remote collections. This profile does not add an endpoint-registration API. Requests carry the existing access context; remote results must meet the permission envelope, space and requested filter contracts. Malformed or widened permissions fail closed.

Source discovery reports configuration presence, not a health probe or evidence availability. A missing selected gateway produces not_configured; operational failures produce safe outcomes such as timeout or provider_unavailable. A configuration read failure is a 503. Search preserves authorised hits from successful branches and reports partial if another branch fails. No matches after a successful authorised search are absent; inability to search is unavailable. Inspect the full evidence report, not just hits.length.

Each hit includes source-qualified ID, document/chunk identity, text, optional title, rank and RRF score. Scores are ranking signals, not calibrated confidence. Query length is at most 2,000 characters, result limit 1–50, candidate count at most 50 per branch and combined returned text at most 64,000 characters. truncated reports clipping. A remote chunk ID is prefixed with remote: to avoid local collisions.

Context and extractionCopy Anchor Link

Context takes a retrieval request plus include_memory (default false) and max_characters (100–64,000; default 16,000). Evidence blocks precede up to 50 memories belonging to the authenticated owner. The budget counts block text characters, not tokens or JSON framing. Inspect blocks, characters and truncated; the embedded evidence report describes the retrieval before the context budget is applied. Memory is labelled separately and is not grounding evidence.

Extraction and document creation accept exactly one of text (1–64,000 characters) or retrieval. Extraction adds output_schema and optional instructions (at most 4,000 characters):

{
  "text": "The synthetic fixture has three sections.",
  "output_schema": {
    "json_schema": {
      "type": "object",
      "properties": {"sections": {"type": "integer"}},
      "required": ["sections"],
      "additionalProperties": false
    }
  }
}

The existing bounded schema validator validates the schema and provider output. Read structured_output.status, value, attempts and error_code. Invalid or unavailable provider output returns status=failed, never a successful empty value. Retrieval-backed extraction requires fully available non-empty evidence; absent, partial or unavailable evidence avoids the model call and returns evidence_unavailable. Model configuration failures return a safe 503. Schema validity does not prove factual correctness. Local permission and revision changes during synthesis reject the result; source IDs identify the evidence used.

Documents, refinement and retriesCopy Anchor Link

A document request accepts title, format (document for Markdown, or docx) and optional instructions. Supplied Markdown without instructions is rendered directly. Instructions or retrieval input use the configured model gateway before rendering. The receipt contains artifact ID, version, media type, SHA-256, byte size and a fixed-version download URL. Use the SDK verified download helper. A receipt means bytes were rendered and verified, not that their claims passed human review.

For a document based on Q knowledge, send a server-side retrieval request so Q can retain and revalidate source provenance. Copying a hit into text makes it caller-supplied content and loses that association. Current owner, space, source permissions and revisions govern saved derivatives and their downloads. Remote-derived durable documents return external_evidence_requires_refetch: an old remote ACL envelope cannot establish current download authority. Remote evidence remains usable for immediate retrieval, context and extraction.

Refinement accepts expected_version and instructions. It supports owned Markdown artifacts up to 64,000 characters, checks provenance after the model wait, and appends under an existing database lock. Two writers using the same version cannot both succeed: one gets artifact_version_conflict (409). Earlier versions remain immutable. DOCX refinement returns artifact_refinement_requires_markdown (422); generate a new DOCX instead. Storage bounds permit at most 128 versions.

Supply a stable Idempotency-Key for each logical document/refinement mutation and retain the request and receipt in your backend. Identical retries return the same content-free receipt; changed input with that key conflicts. The existing idempotency contract preserves unknown outcomes after ambiguous failure. It does not promise automatic recovery of every process interruption. Never change a key merely because a response timed out. Private extraction and memory bodies are not retained as replayable responses; their keys guard duplicate execution but may require explicit recovery. A saved receipt does not bypass current download authorisation.

All operations share Q's request/provider capacity and spending controls. The headless operation deadline is 110 seconds, each retrieval branch has a 25-second budget, and the remote call uses at most 20 seconds with no internal retries. Deployment request limits can be shorter. Configure the backend transport timeout to accommodate the chosen deployment (the example uses 120 seconds). Longer durable orchestration belongs to the run APIs.

SDK entry points and exampleCopy Anchor Link

See the executable backend example. Local qualification uses real PostgreSQL, real Markdown/DOCX rendering, a synthetic model and public HTTP contracts. Installed Python/TypeScript packages and the Go source archive exercise the wire types and transports. Real model quality, remote gateways, representative throughput and hosted rollout require separate qualification.