What it does
Retrieval policies are versioned grants that name collections, identities, purposes, tools, row filters and field masks. POST /v1/retrieval-policies/query authorises the caller first, reads a candidate window, re-checks every row and masks fields, and returns the same empty result for denial and for absence. A simulate route previews a decision without reading data. The policies govern this route and no other.
How it works
A policy names the collections it allows (a policy that names none authorises nothing), an optional field allow-list, a field deny-list, and optional scopes: purposes, tools, identity kinds (user or service) and roles, where an empty scope matches anything. An optional row filter is an expression in the same policy language used for row-level security, evaluated per row as an extra gate.
Authorisation starts from deny. An empty policy set, an identity no policy targets and a collection no matching policy names all deny. A service key gets no exemption: a service identity must be targeted by a policy like any other. Policies that match are combined permissively: the allowed fields are the union (a policy that allows all fields makes the union all), the denied fields are the union and always win, and a row must satisfy at least one row filter unless a matching policy is unconditional. The decision draws on the caller identity, role, an optional purpose from the x-retrieval-purpose header and an optional tool from the x-retrieval-tool header.
The query route runs a three-step pipeline. It resolves the decision before touching data. If allowed, it reads a candidate window of up to 1,000 records of the collection for the caller project. It then runs a mandatory post-filter that drops rows from the wrong collection, re-evaluates each row filter and applies the field mask (a denied field is removed at any depth, an allow-list applies to top-level fields and the row id and kind are kept), and truncates to the requested limit afterwards, so denied rows cannot crowd permitted rows out of a page.
A denial, an empty result and an unknown collection all return 200 with a count of 0 and no rows, which closes the difference-in-errors side channel. The audit log records the policy name, version and reason for each decision, and never row data. A denial also counts toward the policy-denial objective on the retrieval service-level dashboard.
Policies are immutable versions. Publishing appends the next version with a compare-and-swap, enforcement resolves the latest, and earlier versions stay readable. Creating, listing and simulating need an admin or service credential. Simulate accepts what-if overrides for purpose, tool, role and identity kind and touches no data.
Where you reach it
- HTTP
POST /v1/retrieval-policies, GET /v1/retrieval-policies, GET /v1/retrieval-policies/{name}, GET .../versions, POST /v1/retrieval-policies/simulate, POST /v1/retrieval-policies/query
Example
curl -s "$KYNETRA_URL/v1/retrieval-policies" \
-H "Authorization: Bearer $KYNETRA_API_KEY" -H "Content-Type: application/json" \
-d '{
"name": "support-tickets",
"allowed_collections": ["tickets"],
"allowed_fields": ["subject", "status"],
"purposes": ["support"],
"tools": ["helpdesk"]
}'
curl -s "$KYNETRA_URL/v1/retrieval-policies/query" \
-H "Authorization: Bearer $KYNETRA_API_KEY" -H "Content-Type: application/json" \
-H "x-retrieval-purpose: support" -H "x-retrieval-tool: helpdesk" \
-d '{ "collection": "tickets", "limit": 20 }'Limits
- Retrieval policies govern the governed query route alone. The search, vector, hybrid and KynQL routes, the REST plane and realtime are governed by tenant scoping and collection rules, and enabling a policy does not change them.
- The first 1,000 candidate rows of a collection are considered and no more; cursor pagination is not implemented.
- The route lists and filters records of one collection. It does not rank or search.
- A store fault or a recovery fence is a typed error, never an empty denial, so clients should treat 5xx as unknown rather than as denied.
Evidence
- On this siteHTTP API reference
- Tests21 policy-engine tests, 6 integration tests and 3 route tests cover default deny, service identities, uniform denial, the mandatory post-filter, field masks, version history and the admin gate
Test coverage is listed as present in the engine repository at this edition. This page does not report test results.
KynetraDB is in private preview
Request a preview to try this against your own workload.