Search the sessions you can read
Full-text search over three session kinds: the caller’s own, the ones marked for the organisation, and — when the caller holds the read-private permission — every session this host has. A share adds none: a colleague named on a share of a private session may read that session’s record and only the entries the share has delivered, up to its bound, while a hit here is an un-redacted excerpt from any matching entry and cannot honour that bound, so the session is left out. Results carry the session, an entry excerpt with the match, and its timestamp. A session outside the three kinds is absent rather than refused — it is not counted, and the page cursor does not step over it.
Authorizations
Enforced on every transport, with no exempt operation. A person's request — over the default local unix socket exactly as over a TCP listener — must carry a JWT issued by the configured identity provider, which the host verifies itself against that issuer's key set: signature, issuer, expiry, and the person and organisation it names. Requests without a valid one receive 401 NRY-0011. The socket's file permissions are transport and are not an authorisation.
Query Parameters
The search query.
1 - 1024Only matches from sessions bound to this repository path. It is the same column listSessions filters on and it carries no authority of its own: it narrows what the caller may already read and can never widen it. A repository nobody worked in is an empty page rather than an error, and so is one whose conversations this caller may not read.
4096Only matches in transcript entries written at or after this instant. It is the half of "that error, some time in August" that paging cannot answer: without it a reader pages back from now until the dates fall out of the window they meant. Served off the same index the page cursor already walks.
Only matches in transcript entries written at or before this instant. Combines with since to bound a window from both ends; either may be given alone. A window whose until precedes its since is a malformed request naming both parameters rather than an empty page, because an empty page reads as "nobody ever said it".
Restrict the search to these parts of a conversation — repeat the parameter to name several (kind=user-message&kind=summary). Omitted, every kind answers, which is what this operation has always done. It is how a person searches what they SAID without wading through everything the agent read. A value outside the vocabulary is a malformed request naming the parameter, and so is naming the parameter with nothing in it: asking for no kinds at all is a mistake rather than a query. Read FindableEntryKind before relying on a narrowing — two of its values are narrower than their names suggest.
What part of a conversation a record search means — the vocabulary of searchRecords's kind filter, and of the kind a match reports.
It is deliberately its OWN vocabulary rather than the transcript's. EntryKind says what a conversation CONTAINS; this says what the record search can FIND, and the two are free to drift as what gets indexed changes. Nothing else on this contract references it.
What the index holds is the PLAIN TEXT of an entry's payload, so what is findable is decided by the payload and not by the kind — which makes two of these values narrower than they look, and both are worth knowing before a reader concludes the search is broken.
assistant-message is only PARTLY findable by text. A round's spoken text is indexed; the same round's thinking is a separate entry of this same kind carrying reasoning, and reasoning has no plain text, so it never reaches the index. Filtering to assistant messages and not finding a phrase the model reasoned about is the index telling the truth, not failing.
tool-call is never findable by text at all — a call carries a tool name and its arguments, and neither is indexed. It is listed here because it IS reachable by the NAME somebody put on that moment: a label is matched on any entry whatever its kind, so a labelled tool call answers an unfiltered search and must stay reachable from a filtered one. Leaving it out would make naming every value of this filter return LESS than naming none.
Making either searchable by its text is a change to what is written into the index and to the backfill behind it, not a value added here.
user-message, assistant-message, tool-call, tool-result, summary, system, intercom, monitor-event Restrict the answer to the conversations the caller owns. It names nobody and takes no name: the subject comes from the verified token and from nowhere else, which is what keeps it from being the owner parameter this contract deliberately does not have — an owner a caller can name is an owner anybody can be. It is not a permission and can only ever narrow. Combines with every other filter here.
Opaque pagination cursor from a previous page's nextCursor or prevCursor.
1024Maximum items per page.
1 <= x <= 100