SUsurrealdb

POST /api/v1/{context_id}/query

Changed on

Phase 7 unified query: four-tier router + fused ranker over the substrate

Request

Path parameters

context_idstring required

Spectron context id

Request body

asOfstring nullable

Phase 11.5 — historical query timestamp (known time). When set the retrieval path walks the supersession chain to surface the row that was current as-of this instant.

atInstantstring nullable

Phase 11.5 — system-time query. Prepends VERSION d'…' to the underlying SELECT so SurrealDB MVCC returns the substrate state at the supplied instant.

includestring[] nullable

Phase 7 — which families of result to include. Defaults to ["facts", "passages"] (both). Pass either alone to scope the response.

includeDuplicatesboolean nullable

When false (the default), document chunks and memory turns flagged as near-duplicates of an older row are excluded from the fused ranker's recall so the same text does not occupy several ranks. Set true to include them (parity with the documents /query opt-in).

kinteger

Max hits to return (default 10, max 50).

labelsstring[]

Label filter (design §4): key=value strings the result rows must all carry. Applied after the scope predicate — labels never widen access, only narrow the already-authorised result set. Empty = no label filter.

mode'hybrid' | 'vector' | 'bm25' | 'graph'

Retrieval mode hint. The default is Hybrid, which engages the full fused ranker. The other modes are kept as escape hatches so callers can debug a single signal in isolation.

querystring required
scopeViewstring nullable

Scope read breadth: strict (default) | merged | crossTeam. Only strict is enforced pre-launch; merged / crossTeam are accepted and behave as strict until their region logic ships (design §7.1).

sessionIdstring nullable
sourcestring nullable

Phase 7 — free-form source label. Recorded on the trace for audit replay; doesn't affect retrieval today.

validFromstring nullable

Phase 11.5 — valid-time (world-time) lower bound. Filters rows whose valid_from is ≥ this timestamp.

validUntilstring nullable

Phase 11.5 — valid-time (world-time) upper bound. Filters rows whose valid_until is ≤ this timestamp.

Response

classificationKind'direct_lookup' | 'hybrid' | 'full_context' required

What kind of question the query represents. Drives tier selection.

queryMsinteger required
seedEntitiesstring[] required
tier'direct' | 'cache' | 'hybrid' | 'escalated' required

Which tier resolved the query. Exposed on the response for the CLI's --tier flag (Phase 8) and so callers can tell when their query went all the way to tier 4.

Changes

  • 9f1598713067Revision changes
    • warning

      added the new action enum value to the // response property for the response status

    • warning

      added the new escalated enum value to the response property for the response status

    • warning

      added the new escalated enum value to the / response property for the response status

    • warning

      added the new turn enum value to the // response property for the response status

    • info

      added the non-success response with the status

    • info

      added the optional property to the response with the status

    • info

      added the optional property // to the response with the status

    • info

      added the optional property // to the response with the status

    • info

      added the optional property // to the response with the status

    • info

      added the optional property to the response with the status

    • info

      removed the full_context enum value from the response property for the response status

    • info

      removed the full_context enum value from the / response property for the response status

  • 52b41ab517b6Revision changes
    • breaking

      the request property became not nullable

    • breaking

      the request property type changed from string null to no type

    • warning

      added the new cache enum value to the / response property for the response status

    • warning

      added the new direct enum value to the / response property for the response status

    • warning

      added the new full_context enum value to the / response property for the response status

    • warning

      added the new hybrid enum value to the / response property for the response status

    • info

      added the new optional request property

    • info

      added subschema #1 to the request property oneOf list