Search
Search answers one term with one ranked response. It reads every searchable doctype the credential can read, inside one domain or across the whole application. It returns labels only, never document content. The application’s command palette calls this endpoint.
For agents:
GET /Api/<domain>/search?q=<term>(one domain) orGET /Api/search?q=<term>(whole application). One parameterq; a term shorter than 2 characters answers200with an empty result, never an error. Hits arrive in per-doctype groups in rank order; each hit carriesid,display_name,rank,root_doctype,root_id,root_display_name,child_label— labels only, no content. Fetch the document byroot_id(orid) to read content. QUERY form:-X QUERYwith{"q": "<term>"}in a JSON body; any query-string parameter answers422.
When to use this
Section titled “When to use this”Reach for search when:
- You build a command-palette-style picker or a global find box.
- You need documents of several doctypes from one term.
- You must match documents without knowing their doctype first.
To filter one known doctype, use the list filters instead — see Use the REST API.
Before you start
Section titled “Before you start”-
A credential with a read grant on the doctypes you expect to match. A doctype without a read grant contributes nothing to the response.
-
A doctype joins search only when its definition declares a non-empty
searchtemplate. Internal doctypes stay out by not declaring one. -
On the raw list API, a doctype with no template still matches by its label through the bare
searchfilter — see Use the REST API.The examples use
https://facet.example.comand thecrmdomain. Replace both with your values.
1. Pick the scope
Section titled “1. Pick the scope”Two routes exist, each with a GET and a QUERY form:
| Route | Scope |
|---|---|
GET /Api/crm/search |
One domain. |
GET /Api/search |
The whole application. |
The app-wide route runs one query per storage group and merges the results by
rank. An unknown domain answers 404. A draft domain answers 200 with an
empty result and is excluded from the app-wide route:
curl "https://facet.example.com/Api/crm/search?q=acme" \ -H "Authorization: Bearer $FACET_API_KEY"
curl "https://facet.example.com/Api/search?q=acme" \ -H "Authorization: Bearer $FACET_API_KEY"2. Send the term
Section titled “2. Send the term”One parameter exists: q. A term shorter than 2 characters after strip, or a
missing term, answers 200 with an empty result — never an error. Gate the
same way in the client before you call.
The QUERY form carries q in a JSON body only:
curl -X QUERY "https://facet.example.com/Api/crm/search" \ -H "Authorization: Bearer $FACET_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "q": "acme" }'Any query-string parameter on a QUERY request answers 422. A body with a
non-JSON Content-Type answers 415.
3. Read the response
Section titled “3. Read the response”The response is the standard envelope. data holds per-doctype groups in
rank order. Every group carries domain and doctype; the hits inherit
these values:
{ "data": [ { "domain": "crm", "doctype": "Company", "hits": [ { "id": "01JD8W2G7Q5M2X9K4T6VBNR8D", "display_name": "Acme", "rank": 0.83, "root_doctype": "Company", "root_id": "01JD8W2G7Q5M2X9K4T6VBNR8D", "root_display_name": "Acme", "child_label": null } ] } ], "meta": { "q": "acme", "count": 1, "scope": "domain" }}| Field | Meaning |
|---|---|
id, display_name |
The matched row: its id and its label. |
rank |
Match score; the server sorts by it, descending. |
root_doctype, root_id, root_display_name |
The root document the hit anchors to. |
child_label |
The matched child’s own label on a child hit; null on a root hit. |
meta.q |
The term as received. |
meta.count |
The number of hits in the response. |
meta.scope |
domain or app. |
Every hit anchors to a root document. A hit on a root doctype anchors to itself. A hit on a composition child anchors to the aggregate root, so the app can always open the page behind the hit. Collapse one entry per root in the client, with the top-ranked child as the subtitle.
Only doctypes with a read grant contribute. A child hit drops when its root is unreadable, deleted, or the chain breaks. Nothing reaches the client that the credential cannot open.
Caps are server constants, not request parameters:
| Constant | Value | Purpose |
|---|---|---|
MIN_TERM_LENGTH |
2 | Shorter terms answer empty. |
PER_DOCTYPE_CAP |
5 | Matches per doctype group. |
OVERALL_CAP |
25 | Hits in the response. |
MAX_COMPOSITION_DEPTH |
8 | Child-to-root walk bound. |
4. Fetch the documents
Section titled “4. Fetch the documents”Hits carry labels only, never content. Fetch the content with a document read
on root_id, or on id when the hit is the root:
curl "https://facet.example.com/Api/crm/Company/01JD8W2G7Q5M2X9K4T6VBNR8D" \ -H "Authorization: Bearer $FACET_API_KEY"See Use the REST API for the document envelope.
Example
Section titled “Example”One fetch renders the labels for a find box:
const response = await fetch("https://facet.example.com/Api/search?q=acme", { headers: { Authorization: `Bearer ${process.env.FACET_API_KEY}` }});if (!response.ok) throw new Error(`search failed: ${response.status}`);
const { data } = await response.json();for (const group of data) { for (const hit of group.hits) { console.log(hit.root_display_name, hit.rank); }}Troubleshooting
Section titled “Troubleshooting”Empty results for a term you know exists.
Four causes answer empty, never an error: the doctype declares no search
template; the term is shorter than 2 characters after strip; the rows are
deleted; or the credential holds no read grant on the doctype.
The app-wide search misses a whole domain.
A draft domain is excluded from the app-wide route. A domain-scoped call on a draft domain also answers empty.
An unknown domain answers 404.
The route checks the domain before it queries. The 404 is non-disclosing.
The hits carry no content.
By design: labels only. Fetch each document by root_id or id (step 4).
Related
Section titled “Related”- Use the REST API — the list filters behind one doctype.
- Agent tools — the
search_documentstool for agents. - Internals on GitHub: search.md.