Discovering Q capabilities
Discover operation availability, scopes, stability and retry policy from your deployment.
Use GET /v1/capabilities for the versioned public catalogue and GET /v1/openapi.public.json for request/response contracts. Both are anonymous metadata endpoints. /v1/reference renders that same public schema. Neither a /v1 prefix nor an OpenAPI tag grants public status.
The authoritative source is app/capabilities/catalogue.json, validated by typed models in app.capabilities. It records 220 mounted HTTP/WebSocket operations: 167 public, 30 first-party, 7 administrator and 16 experimental. The public schema contains 165 operations; the public reference and HTML status page intentionally have no OpenAPI operation. Nine retained public compatibility operations are explicitly unavailable, as described below. The full inventory includes unpublished paths and the exact implementation handlers; public discovery omits those paths.
curl "$Q_ORIGIN/v1/capabilities"
curl "$Q_ORIGIN/v1/openapi.public.json"
# Maintainers: export all classifications without loading app settings or services.
.venv/bin/python -m app.capabilities > /tmp/q-capabilities.jsonReading an entry
Each entry has an ID (METHOD /v1/path), method/path, policy, availability, contract reference, limits and Python/TypeScript SDK evidence. IDs identify method/path operations. The registry also pins operation_id, which becomes the stable OpenAPI operationId used by generators. See schema and error contracts.
| Field | Meaning |
|---|---|
policy.audience | Public, first-party, administrator or experimental. Experimental means unqualified for publication, not an additional runtime permission. |
policy.auth, scopes, scope_policy | Actual credential family and scope rules. Empty scopes mean no additional capability scope; credentials, tenancy, feature and resource checks still apply. |
policy.tenant, user | Tenant binding and user/principal semantics. Read the referenced operation for accepted body/query/header fields. Tenant-wide administration differs from individually owned data. |
policy.features, settings | Required tenant features/role grants and deployment flags. These contain names, never secret values. |
policy.conditional_scopes | Additional selector-specific scopes, currently for MCP tool calls. |
availability.state | conditional, unavailable, public_metadata, or not_public in the complete inventory. |
availability.readiness | Always not_probed: discovery does not call providers or inspect a caller's feature entitlements. |
contract.url, pointer | Relative OpenAPI URL and JSON Pointer to the exact operation, including request constraints and success responses. Resolve $ref within that document. |
contract.output_status | declared means an outer schema exists; incomplete includes missing or free-form outputs. It does not certify nested fields or stream event conformance. Q2.2 adds typed resource and execution envelopes; flexible provider/tool leaves remain. Q2.4 owns complete event/replay conformance. |
limits | Configured request-rate limits, declared input constraints and embedding batch/character limits. Provider, quota and resource limits may be stricter. |
sdk | source_wrapper includes a concrete transport call in this checkout. unverified makes no wrapper claim; use the HTTP contract. This is not a released-package or transport-conformance guarantee. |
ai_compat accepts the stated scope, ai:* or *, with existing trusted first-party bypass and legacy Q_ENFORCE_AI_SCOPES=false compatibility mode. Workspace scopes accept workspace:*/* and still require resource grants. A2A requires a2a:read, a2a:write or a2a:delegate (or a2a:*/*) even for trusted callers. User delegation requires identity:delegate or *; first-party status alone does not grant that delegation.
conditional is not a promise that an operation will succeed. Callers must satisfy the recorded credentials, scopes, tenant, role/features, resource permissions, quota and provider configuration. unavailable means an explicit deployment gate is off or the implementation rejects the flow. Ordinary authorisation remains in the operation and service boundary; the catalogue grants no authority.
AI jobs and unavailable compatibility flows
The seven supported AI job selectors, their execution adapters and readiness URLs live in the same catalogue. /v1/ai/capabilities remains a compatibility projection. /v1/ai/jobs receipts and discovery now use canonical /v1 URLs; legacy /api/v1/ai/* requests remain mounted. Pack Architect's internal implementation route is explicitly marked non-public; invoke it through its public job selector.
POST /v1/answer/clarify and GET /v1/answer/resume remain discoverable as unavailable. Authenticated use returns 409 permission_aware_replay_required because retained evidence does not yet support permission-aware replay. A new answer request is required. Other retained evidence can also be withheld when permissions or provenance no longer validate.
Q2.2 also marks three agent best-of-n/multitask operations, best-of-n merge and checkpoint branch/resume/rollback unavailable because their current backends reject execution. All nine retain rejection contracts without advertising success responses. This documents existing unavailability; those workflows have not been implemented by Q2.2.
Routing and migration changes
/v1/embeddingsnow reaches the advertised OpenAI-compatible handler (input→data) and theembeddings_apifeature check. The shadowing Q-shaped handler remains at/api/v1/embeddings(inputs→vectors). Migrate payload and response together, or retain the legacy endpoint temporarily. Only float encoding is supported; batches and text lengths are bounded before provider work./v1/chat/completionskeeps the general Q chat handler and now exports its actual schema. Sonar's explicit alias is/v1/sonar/chat/completions;/v1/sonarand the root/chat/completionsalias remain. Sonar-shaped callers must select the Sonar route.- MCP has one handler per public method/path. All
/v1/mcp/*server-management/orchestration routes requirecustom_agents, closing the previously shadowed feature checks. The separate/v1/mcpJSON-RPC endpoint retains its tool-specific scopes. - Operator context diagnostics require a first-party API key on both
/v1/context/*and/api/v1/context/*. Global billing queue status and manual usage recording require trusted first-party credentials./v1/tenants/*requires an administrator session. Tenant-scoped retrieval quality settings remain public. - Agent chat passthrough and Trading Analyst now enforce their recorded AI scopes; Trading Analyst requires tenant context. Static
/rules/effectiveand/context/circuits/statesresolve before dynamic ID routes. - SDK wrappers targeting absent public routes are not made valid by this catalogue. Q2.3 qualifies installed primary SDK transports and documents Go/React/CLI subsets; full stream convergence remains Q2.4. See SDK support and configure the deployment explicitly when overriding the default.
Report ownership rollout
Apply migration 20261007_220000_report_owner before deploying APIs/workers that write jobs. New report jobs store a hash of the creating authenticated principal. Both report creation and reads require ai:answer; reads also require the same tenant and principal. First-party readers must provide tenant context and do not bypass ownership. API key rotation changes principal ownership. Existing rows with null owners return 404; never backfill ownership from an untrusted job ID, tenant guess or requester.
/api/v1/reports/{job_id} remains a legacy endpoint and is not newly advertised as public. A matching report job and draft must both belong to the requested tenant. Database errors propagate; there is no ownership fallback. A rollback that drops the owner column loses ownership history: redeploy compatible code first and plan recovery from an authoritative backup. This change has been verified locally, not deployed.
Maintaining the registry
Add or change the explicit method/path/handler entry together with its policy. Feature flags describe availability without removing entries from the route table. Tags only organise the reference. Startup validation and the required contract suite reject unknown, duplicate, stale, mismatched or visibility-drifted registrations. Contract tests also verify route reachability, direct scope/feature guards, SDK transport evidence, public-schema equality and component-reference closure.
Public OpenAPI includes only registry-selected operations and reachable components. Private schemas and tags are not copied through. Unknown SDK coverage and free-form outputs stay explicit; do not add a quarantine exception merely to publish a new route. Run the required release checks and update the catalogue version when the public contract changes. See release checks, ADR 0010, and the Q2.1 specification.