GET /search/query

Execute a structured search query against the local encrypted search index. Every query requires an unlocked session because result rendering decrypts the encrypted payload.

ADR-008 wire change: total/hasMore are no longer top-level siblings of the envelope — they are folded INTO the data payload alongside the renamed items array (SearchQueryResultDto). The response is the canonical ApiEnvelope<SearchQueryResultDto> ({ data: { items, total, hasMore, state }, ts }).

Index-not-ready handling is query-type-aware (§4.7): a filter-less browse degrades to a direct main-store read and returns HTTP 200 with state: "degraded"; a keyword or filtered query instead returns HTTP 503 index_rebuilding.

get/search/query

Query parameters

querystring required

Required free-text query string.

operatorstring nullable

Optional explicit operator: "and" or "or".

timePresetstring nullable

Optional time preset: today, yesterday, last_24h, last_7d, last_30d, this_week, this_month.

fromMsinteger nullable

Absolute range start (ms since epoch). Must be paired with to_ms.

toMsinteger nullable

Absolute range end (ms since epoch). Must be paired with from_ms.

contentTypesstring nullable

Comma-separated file types (text, html, file, image, other). image here is the physical type of a pure bitmap; copied image files are file and matched via the image tag instead (see tags).

extensionsstring nullable

Comma-separated file extensions (e.g. "md,txt").

sourceDevicesstring nullable

Comma-separated source device ids; restricts results to those origins.

tagsstring nullable

Comma-separated tag ids (e.g. "link,favorited,image"); restricts results to entries carrying any of them. Custom tag ids require an unlocked session.

limitinteger

Maximum results. Default 50, clamped to 200.

offsetinteger

Pagination offset. Default 0.

Response

Search results page (state ready or degraded)

tsinteger required

Server time when the response was built (unix epoch milliseconds).

Changes

Changed in 5 of the 44 revisions of this API.5510

Jun 29, 20262f176512634a1See the full diff
- ○
  added the required property data/items/items/filePaths to the response with the 200 status
  response-required-property-added
Jun 29, 2026d6bf1f5ceb9a1See the full diff
- ○
  added the optional property data/items/items/charCount to the response with the 200 status
  response-optional-property-added
Jun 28, 2026c5ab9e4f0a227See the full diff
- ○
  added the new optional query request parameter tags
  new-optional-request-parameter
- ○
  added the optional property data/items/items/payloadState to the response with the 200 status
  response-optional-property-added
- ○
  added the optional property data/items/items/sourceDevice to the response with the 200 status
  response-optional-property-added
- ○
  added the required property data/items/items/fileNames to the response with the 200 status
  response-required-property-added
- ○
  added the required property data/items/items/linkUrls to the response with the 200 status
  response-required-property-added
- ○
  added the required property data/items/items/tags to the response with the 200 status
  response-required-property-added
- ○
  added the required property data/state to the response with the 200 status
  response-required-property-added
Jun 25, 2026318957db02861See the full diff
- ○
  added the new optional query request parameter sourceDevices
  new-optional-request-parameter
Jun 2, 2026e7038123d26855See the full diff
- ▲
  removed the required property data/items/items/fileNames from the response with the 200 status
  response-required-property-removed
- ▲
  removed the required property data/items/items/filePaths from the response with the 200 status
  response-required-property-removed
- ▲
  removed the required property data/items/items/linkUrls from the response with the 200 status
  response-required-property-removed
- ▲
  removed the required property data/items/items/tags from the response with the 200 status
  response-required-property-removed
- ▲
  removed the required property data/state from the response with the 200 status
  response-required-property-removed
- ●
  deleted the query request parameter sourceDevices
  request-parameter-removed
- ●
  deleted the query request parameter tags
  request-parameter-removed
- ●
  removed the optional property data/items/items/charCount from the response with the 200 status
  response-optional-property-removed
- ●
  removed the optional property data/items/items/payloadState from the response with the 200 status
  response-optional-property-removed
- ●
  removed the optional property data/items/items/sourceDevice from the response with the 200 status
  response-optional-property-removed
This revision also has 74 changes that name no endpoint, such as unreferenced schemas being removed. See the revision's changelog

Full history