Search API
Shared search matching and ranking, semantic keyword fallback, indexed list filters, and palette command and recent-search endpoints.
Overview
This page is the integration reference for search. REST success payloads are inside data, with response metadata in root meta when present. For the Cmd-K command palette, see Global Search.
Relevance on the API
GET /api/v1/search?query=… (ability search:read) shares indexed matching and ordering with the palette and results page. Exact titles lead, then title prefixes, word-boundary substrings and other matches. PostgreSQL uses websearch_to_tsquery and weighted, length-normalized ts_rank_cd (title, content, metadata) within each tier, then descending record ID. Results are grouped and capped per type (per_type, default 5, ceiling 50). Accounts use the same permission-aware account matcher across these surfaces, including its field-specific identity, commercial and contact permissions.
At two characters, indexed candidates match title prefixes or individual complete metadata values (case-insensitive). At three or more characters, title, content and metadata support literal substring matching alongside PostgreSQL full-text matching. SQLite supports the same title ordering and literal matches, without full-text syntax or rank. When embeddings are configured and available and a keyword bucket is below its cap, semantic neighbours can be blended at a lower weight — see AI embeddings. The palette and full results page can also supplement thin keyword groups with semantic neighbours.
| Query | PostgreSQL behaviour |
|---|---|
festival |
Literal substring or stemmed full-text term |
festival lighting |
Literal phrase substring or both full-text terms |
"festival lighting" |
Full-text phrase |
festival -speaker |
Full-text inclusion and exclusion |
festival OR lighting |
Either full-text term |
% and _ |
Literal characters in substring matching |
Quoted phrases and exclusions use full-text matching exclusively; other queries also try literal substrings. Indexed accounts have their own permission-aware field matching rather than this full-text grammar.
GET /api/v1/search/semantic?query=… blends keyword and semantic search while available. When semantic search is paused (for example by the budget or provider circuit), it returns authorized keyword fallback results with meta.embeddings_available: false and meta.message. When embeddings are unconfigured, it returns an empty data object and unavailable metadata. It is not vector-only.
The searchable registry supplies the group schema and reindex model list: accounts, activities, assets, catalogue items, catalogue item groups, credit notes, invoices, invoice payments, purchase orders, rentals, rental projects, repairs, stock checks, virtual stock intakes and warehouse transfers. The API uses their underscore group keys, such as rental_projects. Vehicles, workflows, reports and flightcases are direct palette queries rather than indexed search API groups.
Search results include snippet (a plain-text excerpt, escaped by the UI) and matched_field (title, content, or meta_text). PostgreSQL builds excerpts only for the limited result rows. Each type ranks at most the most recent 50,000 matching index rows (SEARCH_RANKED_CANDIDATE_LIMIT); refine common queries to reach a narrower candidate set. Single-word queries of four or more letters fill thin buckets with title typo matches after literal matches. Every fallback candidate passes the same current-record, privacy and permission checks.
Both search endpoints accept the same query, types[] and per_type contract. Unknown group keys are returned in meta.ignored_types; recognized groups are searched normally. Supplying only unknown keys returns an empty data object.
List / API continuation — filter[search]
What it does
Every searchable model’s index endpoint accepts the filter[search] filter:
GET /api/v1/accounts?filter[search]=Marquee&filter[is_active][eq]=1
filter[search] selects matching IDs from search_index for that model’s morph type, using title prefixes and complete metadata values for short queries, and full-text or literal substring matches from three characters. Accounts require accounts.identity.view; otherwise the filter returns 422 with code unknown_filter_field. It combines with other filter[field][operator] filters via AND. Empty search values are a no-op; % and _ are escaped.
Where it applies
- API index routes that use the shared
filter[field][operator]filter pipeline - Live filters that pass
filter[search]as an explicit filter
The indexed model list above also defines the models eligible for filter[search]; an endpoint must publish the search filter through its filter pipeline. When the model has index rows, the filter uses a semi-join to matching index IDs, so only indexed rows match. When that model has no index rows, it falls back to registered columns on current records: prefix matching for short queries and literal substring matching from three characters. Related identities and computed labels still require an index. Existing scopes, permission checks and privacy exclusions apply to the fallback. Addresses and conversations are not searchable entity types in the palette or this filter.
What it does not do
Cmd-K does not hand off into a Livewire list page with ?filter[search]=…. Choosing a palette hit opens the show page (or the catalogue items-by-group view). List-page DataTable search boxes for registered searchable models use the same indexed filter. These results depend on index freshness unless the model has no index rows and uses the same column fallback; tables outside the registry retain their configured column matching.
Palette endpoints
Palette commands load lazily: the first time the palette opens it calls GET /palette/commands, which returns {"commands": [...], "recent_searches": [...], "recent_records": [...]} — the commands from NavigationService::paletteCommandsFor(), the viewer's own last five distinct recent search terms (strings only, newest first, compared case-insensitively) and their eight most recently viewed records (label, reference, type, icon, url, the same presentation as the list pages' Recently viewed menu) — and the list is cached client-side for the lifetime of the page. Only the static Help entries (Keyboard shortcuts) ship inline in the page, so no permission-gated nav lookup or plugin palette provider runs on a page that never opens the palette. A short skeleton shows while that first fetch is in flight. The palette's documentation matches come from GET /docs/search-index.json?fields=compact, the docs search index without page bodies, fetched the first time a query reaches three characters.
Clicking an entity with a query of 2+ characters also POST /search/record (query, type, id) for analytics. The type and id are sent only for groups that recent searches can save, which excludes workflows, reports and flightcases; fleet clicks use the Vehicle model and project clicks use RentalProject. For those groups only the query text is recorded. DELETE /search/recent removes the viewer's own recent searches: with {"query": "…"} every stored spelling of that term (compared case-insensitively), with no body all of them. It responds {"removed": n} and never touches another user's rows. The palette lists those terms under Recent searches when it opens with an empty query (from the recent_searches field above, plus any search you open a record from during the current page); it does not re-rank results by them.