/v1/searchFind a record by name
REACH FOR THIS THE MOMENT A QUESTION NAMES A RECORD — 'who is assigned to Just Perfect Cleaning', 'where is Acme', 'what is happening with HGM Capital', 'find the Specter Loans lead' — instead of listing a page's rows and scanning them for the name. NAME EVERY RECORD THE QUESTION NAMES IN ONE CALL: q repeated, one name each (at most 20), answers results, one per term in the order sent, each with the query, groups and truncated that term alone would answer — never one search per name, and never a round per name. Search the whole workspace for a record and get back where it lives. Give it a name, an email address, a phone number, a company or any fragment of a cell and it answers the matching records across every page and every board this seat may read, grouped by the page or board they sit on, each with the record's id, its name and the cell the term was found in. One call covers pages you were not told about, and it is the only read that does: a board is 12,000 rows deep and a page of rows is the first 200, so scanning rows for a name is both slower and wrong. Matching is case-blind and matches inside a word, and a term of several words also finds a record holding every word across its cells (a first and a last name in two columns). It finds by MEANING too: describe a record ('the trucking company that wanted 80k', a misspelt or reordered name) as well as name it. Each hit says match — words, meaning or both; hits by words in the record's own name rank above hits elsewhere, and a hit by meaning alone never outranks an equal hit by words. semantic says whether meaning took part, and why not when it did not — a used: false answer is the words alone, not proof nothing is described that way. meaning is auto by default — an exact name answers by the words at once, saying so — on always waits for meaning, off is the words alone. rerank=on (a tool call's default; the door's own is off) reorders the top 15 hits by a model's reading of the term, within an 800 ms wait — skipped when it would reorder nothing (an exact-name first hit, under three hits) — and the answer's rerank says whether it did — used: false is the search's own order, with why. limit and offset page it, and truncated says there were more matches than came back — when it is true, narrow the term rather than concluding the record does not exist. limit caps each group, not the whole answer, and a phone number matches in any format. Each group's key — a page's, or a made board's board-<hex> beside its boardId — with a hit's rowId, is what the one-record reads and writes take: a board is one door, so get_definitions_key_rows_rowId reads a board's record as it reads a page's. Read the record after the search, not in place of it. Each hit also carries status and statusLabel — where the record stands on its page — so "where is Acme" is this read alone; reading the record (get_definitions_key_rows_rowId) answers what hangs off it too: tasks, files, requests, comms. expand=context puts each of the first five hits' record on it — its labelled cells and everything linked to it (the one-record read's context) — so 'an update on ' is this one call; expanded says how many hits carry one, and the rest are read by id. A hit's label is the record's name: one that does not match the name searched for is a different record, not a near answer. key narrows the search to the page or board on screen — a page's key (leads, deals), a board's board-<hex> or its boardId, repeated for several — and the answer's keys echoes it; a key this seat cannot read is a 400 naming it, never an empty answer. A search phrased by ATTRIBUTES — 'warm leads assigned to josh', 'deals in underwriting over 50k', 'my follow ups this week' (with key for the page on screen) — also answers interpreted when its words name a page or board and at least one of its filters: that page's key (and boardId), the filters the words were read as (by column label, the values filter[<column label or id>] takes on the rows read — a status, a tab's statuses, a colleague's account id, a bound like >50000, $created for 'this week'), the words left over as q, the count of rows this seat can read that match, and read, one sentence per filter saying how the words were read. Absent, the words named no filter and the hits are the answer.
Access class: workspace.
Send request
Use the documented inputs to call this endpoint directly.
Parameters
Values are applied to the request and the example on the right.
Responses
the action's answer
{
"data": {
"expanded": 1,
"groups": [
"string"
],
"interpreted": {
"boardId": "",
"count": 1,
"filters": {},
"key": "string",
"name": "string",
"q": "string",
"read": [
"string"
]
},
"keys": [
"string"
],
"limit": 1.5,
"offset": 1.5,
"query": "string",
"rerank": {
"reason": "string",
"used": true
},
"results": [
{
"groups": "string",
"query": "string",
"truncated": "string"
}
],
"semantic": {
"reason": "string",
"used": true
},
"truncated": true
}
}a refusal: {"error": "<what a person needs to read>"}. 401 no credential, 402 the plan does not include this, 403 the seat does not, 404 the thing does not exist or is not yours to see.
{
"error": "string"
}