Search API: schemas
The request and response bodies of the operations in this API.
FacetBucket
| Property | Type | Required | Description |
|---|
count | number | yes | |
key | string | yes | |
subFacets | map of array of FacetBucket | no | |
FacetResponse
FacetResponseDataEnvelope
ModeStatsDto
| Property | Type | Required | Description |
|---|
avgLatencyMs | number | yes | Average latency in milliseconds for this mode |
count | number | yes | Number of queries using this mode |
mode | one of "TEXT", "SEMANTIC", "HYBRID" | yes | Search mode |
ProblemActionableBy
Who can act on this refusal: user (correct the input, sign in), org-admin (an administrator of the organisation), platform (the operators of this installation), none (nobody — it cannot succeed). ABSENT when not known; never guessed.
Type: one of "user", "org-admin", "platform", "none"
ProblemDetailsDto
RFC 9457 problem document. The declared members are the reserved core; extension members are TOP-LEVEL and OPEN, owned by the refusing plane.
| Property | Type | Required | Description |
|---|
actionableBy | ProblemActionableBy | no | Who can act on this refusal: user (correct the input, sign in), org-admin (an administrator of the organisation), platform (the operators of this installation), none (nobody — it cannot succeed). ABSENT when not known; never guessed. |
code | string | yes | SCREAMING_SNAKE_CASE. The machine-branchable refusal, and the value a policy rule, a retry predicate and a UI branch all name. |
detail | string | no | Human-readable and specific to THIS occurrence. |
errors | array of ProblemFieldIssueDto | no | Field-level issues, when the refusal is about the request body. |
instance | string | no | URI reference identifying the occurrence — a request path, a run, a row. |
params | map of string or number or boolean | no | Safe i18n interpolation values for the message keyed by code — typed and allowlisted per code by its declaration. Never server-authored copy, never internal diagnostics. |
retry | ProblemRetry | no | What a retry can achieve: transient (later, unchanged), after-change (only after someone changes something), never (a defect until a fixed version ships). ABSENT when not known. |
status | number | yes | The HTTP status code, repeated in the body so a logged document is self-contained. |
title | string | yes | Short, human-readable, and STABLE for a given type. Never per-occurrence — that is detail. |
traceId | string | no | W3C trace-context trace-id, present when the caller sent a traceparent. Omitted rather than invented when it did not. |
type | string | yes | Absolute URI identifying the refusal TYPE. Derived one-to-one from code, so a caller may branch on either and can never be told two different things. Never about:blank. |
ProblemFieldIssueDto
| Property | Type | Required | Description |
|---|
code | string | no | SCREAMING_SNAKE_CASE code of THIS issue, for a frontend i18n key. Present when the issue was minted by a declared problem. |
detail | string | yes | Prose for logs and developers. A frontend localises from code + params instead. |
params | map of string or number or boolean | no | Safe i18n interpolation values for this issue's code. |
pointer | string | yes | RFC 6901 JSON Pointer into the request body. Root is "/". |
ProblemRetry
What a retry can achieve: transient (later, unchanged), after-change (only after someone changes something), never (a defect until a fixed version ships). ABSENT when not known.
Type: one of "transient", "after-change", "never"
ReindexJobResponseDto
| Property | Type | Required | Description |
|---|
completedAt | object or null | no | Job completion timestamp |
createdAt | string (date-time) | yes | Job creation timestamp |
error | object or null | no | Error message if the job failed |
jobId | string | yes | Unique job ID |
orgId | string | yes | Organization ID |
progress | number | yes | Number of documents processed |
status | one of "PENDING", "RUNNING", "COMPLETED", "FAILED" | yes | Current job status |
total | number | yes | Total documents to process |
ReindexJobResponseDtoDataEnvelope
ReindexTriggerResponseDto
| Property | Type | Required | Description |
|---|
jobId | string | yes | Unique job ID |
orgId | string | yes | Organization ID |
status | string | yes | Job status |
ReindexTriggerResponseDtoDataEnvelope
ResolvedRouteDto
| Property | Type | Required | Description |
|---|
docType | string | no | The matched result-type's docType facet, when it has one. |
naturalKey | string | yes | Natural key of the matched result-type: objectKind, objectKind/docType, or the bare docType for a docType-only result-type. |
objectKind | string | no | The XemaObjectKind of the matched result-type. Absent for a docType-only result-type. |
ref | string | yes | The ref that was resolved (echoed verbatim). |
routeTemplate | string | yes | The declared route template, before expansion. |
url | string | yes | The expanded, site-relative frontend URL for this ref. |
ResolvedRouteDtoDataEnvelope
ResourceVisibilityPattern
Fallback visibility for instances without an explicit pattern.
Type: one of "owner-only", "org-shared", "explicit-share"
SearchHitDto
| Property | Type | Required | Description |
|---|
docType | string | yes | Document type: the OPEN, biome-contributed facet a search source emits (the docType of its IndexableDocument). The set grows with every installed biome, so it is a plain string, never a closed enum. Discover the registered types and their labels via the search:types.list@1 capability or GET /search-types. |
highlights | map of array of string | no | Highlighted matching fragments by field name |
id | string | yes | Document ID |
orgId | string | yes | Organization ID |
projectId | string | yes | Project ID |
ref | string | yes | Canonical xema:// address of this result, reconstructed from its scope + docType + sourceId. Always present — this is the stable handle a consumer passes to GET /search-types/resolve-route or any ref-taking capability. |
routeUrl | string | no | Site-relative frontend URL for this result. Present ONLY when the hit's result-type is registered, declares a renderHints.routeTemplate, and every placeholder in that template resolves from this hit. Absent otherwise — never a partially-substituted or guessed URL. |
score | number | yes | Relevance score |
sourceId | string | yes | Source entity ID in the originating service |
summary | string | no | Document summary or excerpt |
title | string | no | Document title |
SearchResultDto
| Property | Type | Required | Description |
|---|
hits | array of SearchHitDto | yes | Ranked search results |
total | number | yes | Total number of matching documents |
SearchResultDtoDataEnvelope
SearchStatsResponseDto
| Property | Type | Required | Description |
|---|
avgHitCount | number | yes | Average number of hits per query |
avgLatencyMs | number | yes | Average latency in milliseconds |
byMode | array of ModeStatsDto | yes | Breakdown by search mode |
maxLatencyMs | number | yes | Maximum latency in milliseconds |
minLatencyMs | number | yes | Minimum latency in milliseconds |
totalQueries | number | yes | Total number of search queries |
SearchStatsResponseDtoDataEnvelope
SearchTraceResponseDto
| Property | Type | Required | Description |
|---|
callerService | object or null | no | Calling service name |
createdAt | string (date-time) | yes | Trace creation timestamp |
embeddingMs | object or null | no | Embedding generation latency in milliseconds |
hitCount | number | yes | Number of hits returned |
id | string | yes | Trace ID |
orgId | string | yes | Organization ID |
projectId | string | yes | Project ID |
query | string | yes | Search query text |
searchMode | one of "TEXT", "SEMANTIC", "HYBRID" | yes | Search mode used |
searchMs | number | yes | Search execution latency in milliseconds |
topScore | object or null | no | Score of the top-ranked hit |
totalMs | number | yes | Total request latency in milliseconds |
SearchTypeAuthzDto
| Property | Type | Required | Description |
|---|
defaultVisibility | ResourceVisibilityPattern | yes | Fallback visibility for instances without an explicit pattern. |
resourceType | string | yes | FGA/authorization resource-type slug. |
SearchTypeDto
| Property | Type | Required | Description |
|---|
authz | SearchTypeAuthzDto | yes | |
docType | string | no | Biome sub-facet under objectKind. |
embeddingEligibleDefault | boolean | yes | Default embedding-eligibility for instances. |
naturalKey | string | yes | Natural key: objectKind, objectKind/docType, or the bare docType for a docType-only result-type. |
objectKind | string | no | The XemaObjectKind this result-type covers. Absent for a docType-only result-type. |
ownerId | string | yes | Contribution owner id. |
ownerType | string | yes | Contribution owner kind (e.g. biome). |
renderHints | SearchTypeRenderHintsDto | yes | |
searchReplayCapabilityRef | string | no | Capability ref for replaying an instance. |
searchableFields | array of string | yes | Fields carrying searchable text. |
SearchTypeListDto
| Property | Type | Required | Description |
|---|
searchTypes | array of SearchTypeDto | yes | |
SearchTypeListDtoDataEnvelope
SearchTypeRenderHintsDto
| Property | Type | Required | Description |
|---|
icon | string | no | Icon slug the frontend maps to a component. |
label | string | yes | Human-readable result-type label. |
routeTemplate | string | no | Deep-link route template with {placeholder} segments the frontend fills. |
TracesListResponseDto
| Property | Type | Required | Description |
|---|
total | number | yes | Total number of matching traces |
traces | array of SearchTraceResponseDto | yes | List of search traces |
TracesListResponseDtoDataEnvelope