Search Endpoints

Overview of the /v1/search namespace: the document filter alias, omnisearch GET and POST variants, saved filters, and the materialize trigger for the index.

The /v1/search namespace gathers Talonic's document search endpoints under one prefix: a filter route that is an alias of the document filter, an omnisearch POST that mirrors GET /v1/search, the read-only saved-filter listing, field autocomplete and field values for building filter UIs, and a materialize trigger that rebuilds the field-value index they all execute against.

Everything in the namespace requires only the read scope except POST /v1/search/materialize, which mutates the index and requires write. All reads are filtered by Sources-IAM visibility as the API key's minting user, so the five surfaces always agree with each other: a value autocomplete suggests, the filter matches, and the count reports the same visible set.

The filter alias exists for integrations that prefer a single base path: POST /v1/search/filter takes exactly the same body as POST /v1/documents/filter and returns the same response, with only links.self differing. Pick one path and stay consistent; the canonical documentation for the body and response lives on the [Filter Documents](filter-documents) page.

Choosing the right entry point: a user typing a query belongs on omnisearch, which searches every entity type at once and explains each hit; a filter-building UI pairs autocomplete (which field?) with field-values (which value?); a machine-to-machine slice goes straight to the filter with registry UUIDs; and a dashboard number is the filter's total with limit: 1. Saved filters bridge the first and last: curated once in the dashboard, replayed verbatim by integrations.

GET /v1/search/autocomplete, GET /v1/search/field-values, GET /v1/search/saved-filters, and the materialized index are documented on their own pages — this page is the namespace map.

POST/v1/search/filter

POST/v1/search/omnisearch

Body parameters

querystringThe search query. Empty or whitespace-only returns all-empty collections.

limitintegerMaximum results per entity type (clamped to 100). Default: 20

POST/v1/search/materialize

Filter via the search namespace alias

curl -X POST https://api.talonic.com/v1/search/filter \
  -H "Authorization: Bearer $TALONIC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "conditions": [
      { "fieldId": "6f1e9a2b-4c3d-4e5f-8a7b-9c0d1e2f3a4b", "operator": "contains", "value": "acme" }
    ],
    "limit": 10
  }'

Omnisearch via POST

curl -X POST https://api.talonic.com/v1/search/omnisearch \
  -H "Authorization: Bearer $TALONIC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "query": "acme", "limit": 5 }'

Frequently asked questions

Is /v1/search/filter the same as /v1/documents/filter?+

Yes. It is an alias with the same request body and response, grouped under the search namespace; only the links.self value differs. Use whichever base path fits your integration and stay consistent.

What is the difference between GET /v1/search and POST /v1/search/omnisearch?+

They run the same global search and return the same categorized result shape. GET takes a q query parameter; POST takes a JSON body with query and limit (clamped to 100), which is easier when queries are long or hard to URL-encode.

Which endpoint in the namespace needs more than the read scope?+

Only POST /v1/search/materialize, which rebuilds the field-value index and requires the write scope. Every other route — filter alias, omnisearch, autocomplete, field-values, saved-filters — is a read.

When do I need to materialize?+

The field-value index backs the filter, autocomplete, and field-values. Trigger materialize to rebuild it after bulk ingestion if those reads look stale; single-document ingestion keeps the index current automatically, so routine integrations never need to call it.

Search Endpoints

Frequently asked questions

Related