talonic_search
Omnisearch across documents, fields, sources, and schemas in the workspace. Use for conceptual or fuzzy queries.
`talonic_search` is designed for discovery. When a user asks a question like 'do I have any contracts about indemnification?' or 'find documents from Acme', this is the right tool. It searches across document filenames, extracted field values, schema names, and source metadata using semantic and fuzzy matching.
The response is grouped by entity type: documents, fieldMatches, schemas, sources, and fields. Each result includes a relevance score (0..1) so the agent can assess match quality. Results with scores below 0.5 are typically not relevant and can be omitted when presenting to the user.
For queries that require exact field-value matching (like 'invoices over 1000 EUR'), use `talonic_filter` instead. Search is for exploration and discovery; filter is for precision queries against structured data.
| Parameter | Type | Description |
|---|---|---|
| query * | string | The search query. Supports fuzzy and conceptual matching. |
| limit | integer | Maximum results per entity type. Default: 5. |
A common agent pattern is using talonic_search as a first step to orient within a workspace, then following up with more specific tools. For example, an agent might search for 'Acme contracts' to discover relevant documents, note the canonical field names in the response, and then use talonic_filter with those field names to narrow down to contracts expiring within a specific date range. This search-then-filter pattern is both efficient and reliable.
Search results are scoped to the authenticated workspace. The query runs against all documents, extracted field values, schema definitions, and source metadata within that workspace. There is no cross-workspace search — each API key sees only its own data. The limit parameter controls how many results are returned per entity type (documents, fields, schemas, sources), with a default of 5. Increase the limit when the user needs a broader view of matching content.
fields[].canonicalName. These names can be used directly in talonic_filter conditions, making search a good first step before building precise filters.fieldMatches[] and fields[] entry carries a dataType ("string", "number", "array", etc.). Use it to pick the right talonic_filter operator on the first call — numeric operators (gt, gte, lt, lte, between) only resolve correctly when dataType === "number". See the *Schema typing* section under talonic_filter for the full preventive / reactive pattern.Example
{
"query": "indemnification clauses Acme",
"limit": 10
}{
"documents": [
{
"id": "doc_4e7b...",
"filename": "acme-services-agreement.pdf",
"type_detected": "Services Agreement",
"score": 0.92
}
],
"fieldMatches": [
{
"fieldName": "indemnification.cap_amount",
"documentId": "doc_4e7b...",
"value": "2x annual fees",
"documentCount": 3,
"filterable": true,
"dataType": "string",
"score": 0.88
}
],
"schemas": [],
"sources": [],
"fields": [
{ "canonicalName": "indemnification.cap_amount", "dataType": "string", "filterable": true }
]
}Example: search then filter
// Agent calls talonic_search:
{
"query": "vendor invoices total amount",
"limit": 5
}
// Response includes canonical field names plus dataType:
{
"fields": [
{ "canonicalName": "vendor.name", "dataType": "string", "filterable": true },
{ "canonicalName": "invoice.total_eur", "dataType": "number", "filterable": true },
{ "canonicalName": "invoice.due_date", "dataType": "string", "filterable": true }
]
}// Agent uses canonical names from search to build a filter:
{
"conditions": [
{ "field": "invoice.total_eur", "operator": "gt", "value": 500 }
],
"sort": { "field": "invoice.total_eur", "direction": "desc" }
}