Records search integration

Outcome

When you finish this guide, clients in your integration can call the records search capability with the record:search permission, correct request shape, and ABAC-aware filters — without bypassing datasource exposure rules.

Prerequisites

Certified datasources with dimensions and exposed.filterable fields declared
Caller identity granted record:search permission
Records search and AI context understood (intents, ABAC-first flow)
Metadata schema discovery completed for filterable field names in scope

Where it lives

Surface	Access
Records search service	Platform REST capability (same logic on Enterprise MCP where exposed)
Permission	`record:search` on caller token or role
ABAC inputs	Dimension bindings on datasource manifests and protection projection
Audit	Search responses include audit reference and exclusion counts

The service does not call vendor APIs directly — it filters across normalized platform records with policy enforcement.

How to set

Grant permission — map record:search to integrator, worker, or agent roles that may run cross-datasource discovery. Follow your RBAC manifest pattern; do not grant at user activation time.
Declare filterable fields on each datasource in scope — records search honors normalized names from exposed.filterable and dimension bindings.
Choose intent per request: retrieval, grounding, analytics, or validation.
Compose request body (business terms — no raw route strings in integrator docs):

Field	Required	Purpose
intent	Yes	Why the search runs
resourceTypes	No	Limit to catalog types (`customer`, `document`, …)
datasourceKeys	No	Limit to specific datasources
filters	No	Field predicates after ABAC (`field` → operator → value)
preFilters	No	Predicates applied before ABAC (advanced MCP flows)
exclude	No	Exclusion predicates
searchMode	No	`ids` (default) or `full` metadata
limit	No	Cap results (platform maximum applies)
dryRun	No	Return metadata without executing search

Filter operators — use structured operators per field: equals, not equals, comparisons, contains, in-list, not-in-list.
Prefer ids mode for RAG — retrieve authorized record IDs, then pass IDs to vector retrieval. Use full mode when UI or agents need complete metadata in one step.
Monitor exclusions — response metadata includes counts removed by ABAC versus user filters. High ABAC exclusions usually mean grants or dimension bindings — not bad filters.
Audit — retain audit references for compliance correlation.

Defaults and examples

Minimal retrieval request (conceptual shape)

{
  "intent": "retrieval",
  "resourceTypes": ["customer"],
  "datasourceKeys": ["example-crm-customers"],
  "filters": {
    "country": { "eq": "Finland" }
  },
  "searchMode": "ids",
  "limit": 100
}

Cross-datasource retrieval

{
  "intent": "retrieval",
  "resourceTypes": ["document", "customer"],
  "filters": {
    "country": { "eq": "Finland" }
  },
  "searchMode": "full",
  "limit": 50
}

Response highlights

Area	Content
data	Record IDs or full records depending on searchMode
meta.excluded	Counts filtered by ABAC vs user filters
meta.auditRef	Audit log correlation token

Validate

Run search with dryRun when available to confirm filter shape without returning rows.
Compare exclusion counts for a scoped subject vs over-privileged subject — ABAC should reduce results.
Confirm unauthorized callers receive permission errors without record:search.
For RAG pipelines, verify vector steps receive only IDs from search — never unscoped corpus queries.

Common mistakes

Mistake	Fix
Flat filter values without operators	Use `{"field": {"eq": "value"}}` shape
Guessing filter field names	Discover via metadata schema first
Skipping ABAC review	Inspect `excluded.abac` counts
Full corpus vector search	Narrow with records search ids mode first
Missing permission	Add `record:search` to role

Limits

Result limits, preFilter semantics, and MCP tool naming may differ slightly by deployment. Confirm maximum limit and dry-run support with your operator.

Records search enforces platform ABAC — it does not fix missing dimension bindings on datasources. Complete dimension and protection configuration before relying on search for production AI context.

Documentation Index