Omnisearch

Run one global search across documents, extracted field values, sources, and schemas. GET /v1/search powers Cmd+K palettes with categorized, grouped results.

The omnisearch endpoint (GET /v1/search) runs a unified search across all entity types in your Talonic workspace: documents, extracted field values, source connections, schemas, and registry fields. A single query returns categorized results, making it ideal for building global search UIs like Cmd+K palettes. A POST variant, POST /v1/search/omnisearch, takes a JSON body (query, limit) and returns the identical shape — use it when a query string is awkward to URL-encode.

Document hits are found two ways and merged: by document metadata (filename, display name), and through their field values — a document whose extracted supplier_name is "Acme Corp" matches the query acme even if its filename never mentions it. Field-level hits carry matchedFieldName and matchedValue so your UI can show *why* a document matched, and deep-link to the exact field row.

The fieldMatches category surfaces the matching values themselves, and each entry's filterable flag tells you whether the hit can be turned into a filter: entries with a non-null resolvedFieldId come from the materialized store and can be passed straight to POST /v1/documents/filter as an eq condition; entries with resolvedFieldId: null come from not-yet-materialized extraction data and are informational. The same flag appears on fields entries, where schema-defined fields without registry backing report filterable: false.

All results respect Sources-IAM visibility, evaluated as the API key's minting user. An empty or whitespace-only query returns 200 with all five collections as empty arrays — never an error — so palettes can safely call the endpoint on every keystroke and debounce purely for performance.

GET/v1/search

Query parameters

q*stringSearch query. Empty or whitespace-only returns empty arrays.

limitintegerMaximum results per entity type. Default: 20

Request

curl "https://api.talonic.com/v1/search?q=acme&limit=5" \
  -H "Authorization: Bearer $TALONIC_API_KEY"

POST/v1/search/omnisearch

Response

Response fields

documentsarrayMatching documents: id, name (display name or filename), filename, sourceId, sourceName, documentType, tags, status — plus matchedFieldName/matchedValue when the hit was field-level.

fieldMatchesarrayValues matching the query: resolvedFieldId (null for unmaterialized hits), displayName, dataType, matchedValue, documentCount, filterable — plus documentId/fieldName on single-document hits for deep links.

sourcesarrayMatching source connections (id, name).

schemasarrayMatching schemas (id, name).

fieldsarrayMatching field definitions: id (null for schema-only fields), canonicalName, displayName, dataType, documentCount, occurrenceCount, filterable — plus schemaName on schema-defined fields.

Response

{
  "documents": [
    {
      "id": "b8b00d51-eecc-49b3-affc-89fee95b9518",
      "name": "Invoice-2026-001.pdf",
      "filename": "Invoice-2026-001.pdf",
      "sourceId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "documentType": "Invoice",
      "tags": [],
      "status": "completed",
      "matchedFieldName": "supplier_name",
      "matchedValue": "Acme Corp"
    }
  ],
  "fieldMatches": [
    {
      "resolvedFieldId": "6f1e9a2b-4c3d-4e5f-8a7b-9c0d1e2f3a4b",
      "displayName": "Supplier Name",
      "dataType": "string",
      "matchedValue": "Acme Corp",
      "documentCount": 47,
      "filterable": true
    }
  ],
  "sources": [
    { "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "name": "Invoice Pipeline" }
  ],
  "schemas": [
    { "id": "c3d4e5f6-a7b8-9012-cdef-123456789012", "name": "Invoice Schema" }
  ],
  "fields": [
    {
      "id": "6f1e9a2b-4c3d-4e5f-8a7b-9c0d1e2f3a4b",
      "canonicalName": "supplier_name",
      "displayName": "Supplier Name",
      "dataType": "string",
      "documentCount": 1794,
      "occurrenceCount": 1842,
      "filterable": true
    }
  ]
}

A filterable fieldMatch converts directly into a drill-down: pass its resolvedFieldId and matchedValue as an eq condition to POST /v1/documents/filter to list exactly the documentCount documents behind the hit.

Errors

Error responses

401unauthorizedMissing or invalid API key.

429rate_limitedToo many requests. Retry after the period indicated in the Retry-After header.

Frequently asked questions

Does omnisearch return results from all entity types in every call?+

Yes. Every call searches documents, field values, sources, schemas, and registry fields simultaneously. Empty categories are returned as empty arrays.

How is the limit parameter applied?+

The `limit` applies independently to each entity type. Setting `limit=5` returns up to 5 documents, 5 field matches, 5 sources, 5 schemas, and 5 fields. On the POST variant, limit is additionally clamped to 100.

What happens if the query is empty?+

An empty or whitespace-only query returns a 200 response with all five collections as empty arrays. No error is raised, so palettes can call the endpoint on every keystroke safely.

What does the filterable flag mean?+

Whether the hit can be turned into a document filter. Filterable entries carry a resolvedFieldId from the materialized store; pass it with the matched value as an eq condition to POST /v1/documents/filter. Non-filterable hits come from extraction data that is not materialized yet and are informational.

Why does a document hit carry matchedFieldName and matchedValue?+

Those are set when the document was found through one of its extracted field values rather than its filename. Show them as the "why it matched" line in your results UI, and use them to deep-link the exact field row on the document detail page.

Omnisearch

Response

Errors

Frequently asked questions

Related