SearchRequest

The body of POST /v1/search.

A body rather than a query string. The access log records the path and its query, and the store's logs rotate daily for a week - GLOBAL_SEARCH.md is explicit that query text never enters a document, the index, settings, telemetry or the recent-query list, and a URL would put it in the middle of all of them.

Type object

Shape

Field	Type	Description
textrequired	string
entity_picker	boolean	Restrict results to document/file titles and live task nodes for an @ picker. This is a query shape over the existing projection, not a stored index. Default `false`
workspaces	array of WorkspaceId	Empty means every workspace the index knows. The caller resolves a profile to this; the index has never heard of one. Default `[]`
excluded_workspaces	array of WorkspaceId	Default `[]`
kinds	array of string	`Kind::as_str()` values, as documents store them. Default `[]`
tags	array of string	Tag names, not `TagId`s - this is a text-search surface and a person types the word they read. A hit's node must carry every one of them, and a name here matches its own descendants too (`fun` matches `fun/home`), so this is node-scoped filtering rather than a term: nothing here is searched for, ranked, or spelled back in [`SearchPage::corrected_query`] ([ADR-207](../../../docs/decisions/ADR-201-225.md#adr-207-tagfilter--a-tag-in-a-query-is-a-node-scoped-filter-not-a-term-and-it-lives-in-candidates-alone)). A surface may fill this directly; a person fills it by typing `#tag` into [`Self::text`], which the store lifts out before it searches. Default `[]`
attributes	array of AttrFilter	Typed attribute filters. A hit's node must satisfy every one. One general filter rather than a field per attribute, because a workspace defines its own attributes and declares their types: a wire naming `priority` and `due` explicitly would need a new field for every attribute anybody invents, while `key` + `kinds` serves a custom one on the day it exists. Default `[]`
sort	SearchSort	Default `"relevance"`
lifecycle	LifecycleFilter2	Default `"live"`
page_size	integer (uint, >= 0)	Clamped by the store; see [`MAX_PAGE_SIZE`]. Default `50`
offset	integer (uint, >= 0)	Default `0`
request_seq	integer (uint64, >= 0)	Copied to the response, so a surface typing quickly can drop an answer to a keystroke it has already moved past. Default `0`
include_facets	boolean	Also return the workspaces the index knows, for a scope picker. Default `false`
recent_queries	integer (uint, >= 0) or null	Also return this many recent queries. Absent means none. Default `null`

Example

{
  "text": "string",
  "entity_picker": false,
  "workspaces": [],
  "excluded_workspaces": [],
  "kinds": [],
  "tags": [],
  "attributes": [],
  "sort": "relevance",
  "lifecycle": "live",
  "page_size": 50,
  "offset": 0,
  "request_seq": 0,
  "include_facets": false,
  "recent_queries": 0
}

The contract has no example values, so example bodies are generated from each schema: every field is shown with a placeholder of its type.

Used by

POST/v1/store/search
Search every workspace this store holds

Generated from contract version 1. Last updated November 12, 2026.