Metadata and Search Filters
Attach your own key/value metadata to documents, then use it to narrow searches and chat retrieval — for example "only HR documents from 2024 onwards that are not drafts".
Metadata rules
Metadata is a flat JSON object on each document.
| Rule | Value |
|---|---|
| Keys per document | At most 16 (422 metadata_too_many_keys) |
| Key format | ^[a-z][a-z0-9_]{0,63}$ — lower-case letter first, then lower-case letters, digits or _, at most 64 characters (422 metadata_invalid_key) |
| Value types | string (at most 256 characters), finite number, boolean, or date (422 metadata_invalid_value) |
| Not allowed | null, arrays, nested objects |
| Dates | A string that parses as an ISO 8601 date (2025-01-31) or an RFC 3339 date-time (2025-01-31T09:00:00Z) is stored as a date, normalised to UTC YYYY-MM-DDTHH:MM:SSZ, and can be used in range filters |
Reserved keys (422 metadata_key_reserved) — these names belong to platform fields and cannot be used: tenant_id, kb_id, knowledge_base_id, doc_id, document_id, version_id, chunk_index, page, section, profile_id, text, owner_type, location, token_count, created_at, meta, id, and any key starting with _.
The platform stores your metadata in a separate meta. namespace, so a customer key can never collide with or override a platform field such as the organization or document id. You always write and filter with the bare key (department, not meta.department); never send the prefix yourself.
Error bodies name the offending field in param (for example metadata.Department) but never echo your values.
Setting metadata
| How | Behaviour |
|---|---|
Upload form field metadata | JSON object applied to every file of that upload request. |
PATCH /v1/knowledge_bases/{kb_id}/documents/{document_id} with metadata | Replaces the whole metadata object. Send the complete object you want to keep. |
POST /v1/knowledge_bases/{kb_id}/documents:batch_metadata | Adds/overwrites keys (set) and removes keys (unset) on up to 100 documents at once. set and unset must not share a key. A document that would end up with more than 16 keys fails individually with metadata_too_many_keys; the others are updated. |
PUT …/documents/{document_id}/file with metadata | Replaces the metadata when the new file version becomes ready. |
curl -X POST "https://api.infus.ai/v1/knowledge_bases/$KB_ID/documents:batch_metadata" \
-H "Authorization: Bearer $API_KEY" \
-H "Content-Type: application/json" \
-d '{
"document_ids": ["1d2e3f40-5a6b-4c7d-8e9f-0a1b2c3d4e5f", "7a8b9c0d-1e2f-4a3b-8c4d-5e6f7a8b9c0d"],
"set": { "reviewed": true, "effective_date": "2025-01-01" },
"unset": ["draft"]
}'
The response lists a result per id (updated, not_found or error). The document's updated_at changes immediately; the new values reach search filters asynchronously, normally within a few seconds.
Filters
A filter is used by POST /v1/knowledge_bases/{kb_id}/search (filter) and by chat retrieval (retrieval.filter). It has one level with three optional lists:
| List | Matches when |
|---|---|
must | all conditions hold |
should | at least one condition holds (only checked if the list is present) |
must_not | none of the conditions hold |
At most 16 conditions in total. Each condition names a metadata key and exactly one operator:
| Operator | Value | Example |
|---|---|---|
eq | string, number, boolean, or date string | { "key": "department", "eq": "legal" } |
in | array of 1–32 such values | { "key": "region", "in": ["emea", "apac"] } |
range | object with one or more of gt, gte, lt, lte; numbers or dates | { "key": "effective_date", "range": { "gte": "2024-01-01" } } |
exists | true or false | { "key": "reviewed", "exists": true } |
{
"must": [
{ "key": "department", "eq": "legal" },
{ "key": "effective_date", "range": { "gte": "2024-01-01", "lt": "2026-01-01" } }
],
"should": [
{ "key": "region", "in": ["emea", "apac"] },
{ "key": "global", "eq": true }
],
"must_not": [
{ "key": "draft", "eq": true }
]
}
A malformed filter is refused with 422 filter_invalid: unknown operator, more than one operator in a condition, a reserved key, more than 16 conditions, more than 32 in values, or a value whose type does not fit the operator (for example a string in range).
Any metadata key can be filtered. Keys that your platform operator has marked as indexed filter fastest; other keys still work but can be slower on large knowledge bases.
Search parameters
POST /v1/knowledge_bases/{kb_id}/search
| Field | Default | Rule |
|---|---|---|
query | — | 1–2,000 characters (422 query_too_long). Never stored or logged. |
top_k | 5 | 1–20 results. |
filter | none | As above. |
document_ids | none | Restrict to up to 100 documents of this knowledge base. |
include_text | true | false returns hits without text (ids, locations and scores only). |
Each hit has knowledge_base_id, doc_id, document_name, page, chunk_index, section, text, score, location and the document's metadata. These are the same field names as chat citations. Search combines semantic and keyword matching; score ranks hits within one response and is not comparable across searches.
Only ready, non-deleted content is ever returned: a document deleted while a search runs is re-checked and dropped before the response is sent.
Idempotent searches
Send Idempotency-Key to make a search safe to retry. A retry with the same key and the same body within 24 hours returns the same hits (re-checked, so deleted content drops out) with usage.query_units: 0 — it is not charged again. The same key with a different body is refused with 409 idempotency_key_conflict.
What a search costs
One successful search is one query, even when it returns no results. Refused or failed searches are not charged. See Pricing and Billing.