Collections
Application data as JSON items addressed by a key you choose — read, written and filtered by an agent or an integration, with no embedding and no backing file.
Overview
Use a collection for records that are looked up and filtered, not searched by meaning: tickets, orders, a user's preferences. Each item is one JSON object under a key unique in its collection. Text an agent should find by similarity belongs in a document or a memory.
This module is a verbatim mirror of the runtime: every field, method, status code and error shape is the runtime's own, re-rooted under the project in the path.
Free stores 1 GB, Pro 30 GB, Business 100 GB; an Enterprise ceiling is set by
contract. Writing an item past that answers 403 PLAN_LIMIT_REACHED with
resource: "storage", and the plan, the limit and what your account is
holding as used in meta.
This holds however the write arrives: a call to this API, a
formation deploy or an agent's tool call.
The ceiling is your account's, not each project's: every project the
account pays for draws on the same figure, shared with files, documents and
memories. Read where you stand from storage on
GET /v1/users/me/billing.
Reading, editing tags and deleting stay open at the ceiling; a put, and a merge
carrying data, are refused.
See the OpenAPI spec for the full endpoint and schema reference, or browse it rendered under API Reference → Collections.
Data Model
Collection
| Field | Type | Description |
|---|---|---|
id | string | |
project_id | string | |
name | string | |
schema | object, nullable | A JSON Schema every item's data must satisfy, stored as written. null removes it. |
created_at | string (date-time) | |
updated_at | string (date-time) |
name is unique in the project; a second collection of the same name is
409 NAME_CONFLICT. A schema that cannot compile is refused rather than
stored; changing it governs each item's next write, not the items stored.
CollectionItem
| Field | Type | Description |
|---|---|---|
collection_id | string | |
key | string | |
data | object | The item's JSON object, at most 64 KB serialized. Stored as jsonb, so key order is not kept. |
tags | object | Key-value labels on a resource. A flat object of string values — an array, a nested object or a number is rejected with 400 VALIDATION_FAILED, never coerced. Keys are opaque and stored verbatim, so cost_center and costCenter are two different tags. Matched by JSONB containment wherever tags are read: the ?tags= filter, knowledge search, and the IAM iam:ResourceTag/<key> condition. Keys beginning system. are reserved: the platform writes them to record which conversation, actor, agent and role a row came from, and a write naming one is refused with 400 RESERVED_TAG_KEY. They are read and filtered like any other tag. The bag is bounded, because every pair reaches the IAM context of every access check on the resource: at most 50 keys, each key at most 128 characters and each value at most 256. A write past a bound — including a merge that would grow the stored bag past the key count — is 400 VALIDATION_FAILED with meta.limit naming the bound it crossed. system.* keys are the platform's and do not count against the 50. |
version | integer | Bumped by every write; what If-Match names. |
created_at | string (date-time) | |
updated_at | string (date-time) |
key is 1–256 letters, digits and . _ : @ -, starting with a letter or
digit. data is at most 64 KB serialized. An item has no actor_id: link one
as data.actor_id, or as a tag.
Key Concepts
Put, merge, delete
PUT /v1/projects/{project_id}/collections/{collection_id}/items/{key}
creates the item (201) or replaces its data (200).
PATCH /v1/projects/{project_id}/collections/{collection_id}/items/{key}
applies a JSON Merge Patch to data: an object merges key by key, null
removes a key, any other value replaces it. Both replace tags when the body
carries them and leave them alone when it does not.
Optimistic concurrency
A write may state the version it read as If-Match or expected_version; an
item at another version refuses it with 409 VERSION_CONFLICT and
meta.current_version. A precondition on a free key is 404.
Filtering
GET /v1/projects/{project_id}/collections/{collection_id}/items
returns items in key order, at most 100 a page.
datais a structured filter over the item'sdata, as JSON: a value matches exactly,inmatches any of a list, andgt,gte,lt,lteorder the field against a number or a string.- A filter names top-level fields of
dataonly. A nested value is not addressable: lift it to the top level, or into a tag, to filter on it. tags=key:valuenarrows by tags; repeat it for several pairs.
A listing runs under a statement timeout; one past it is 422 QUERY_TIMEOUT.
Add an equality condition so the index narrows what a range is evaluated on.
Who may do what
Every route needs any project
member. Deleting a collection
removes its items. A formation may declare a collection
resource.
Examples
Create a collection
- CLI
- SDK
- curl
naturali create-collection \
--project-id proj_V1StGXR8Z5jdHi6B \
--name support-tickets
const { data: collection } = await naturali.collections.createCollection({
path: { project_id: 'proj_V1StGXR8Z5jdHi6B' },
body: { name: 'support-tickets' },
});
curl -X POST https://api.naturali.ai/v1/projects/proj_V1StGXR8Z5jdHi6B/collections \
-H "Authorization: Bearer $NATURALI_TOKEN" \
-H "Content-Type: application/json" \
-d '{ "name": "support-tickets" }'
Write an item
- CLI
- SDK
- curl
naturali put-collection-item \
--project-id proj_V1StGXR8Z5jdHi6B \
--collection-id coll_V1StGXR8Z5jdHi6B \
--key ticket-1042 \
--data '{"status":"open","priority":2}'
const { data: item } = await naturali.collections.putCollectionItem({
path: {
project_id: 'proj_V1StGXR8Z5jdHi6B',
collection_id: 'coll_V1StGXR8Z5jdHi6B',
key: 'ticket-1042',
},
body: { data: { status: 'open', priority: 2 } },
});
curl -X PUT https://api.naturali.ai/v1/projects/proj_V1StGXR8Z5jdHi6B/collections/coll_V1StGXR8Z5jdHi6B/items/ticket-1042 \
-H "Authorization: Bearer $NATURALI_TOKEN" \
-H "Content-Type: application/json" \
-d '{ "data": { "status": "open", "priority": 2 } }'
Merge into an item at the version you read
- CLI
- SDK
- curl
naturali update-collection-item \
--project-id proj_V1StGXR8Z5jdHi6B \
--collection-id coll_V1StGXR8Z5jdHi6B \
--key ticket-1042 \
--data '{"status":"closed"}' \
--expected-version 1
const { data: item } = await naturali.collections.updateCollectionItem({
path: {
project_id: 'proj_V1StGXR8Z5jdHi6B',
collection_id: 'coll_V1StGXR8Z5jdHi6B',
key: 'ticket-1042',
},
body: { data: { status: 'closed' }, expected_version: 1 },
});
curl -X PATCH https://api.naturali.ai/v1/projects/proj_V1StGXR8Z5jdHi6B/collections/coll_V1StGXR8Z5jdHi6B/items/ticket-1042 \
-H "Authorization: Bearer $NATURALI_TOKEN" \
-H "Content-Type: application/json" \
-d '{ "data": { "status": "closed" }, "expected_version": 1 }'
List the open items of priority 2 or more
- CLI
- SDK
- curl
naturali list-collection-items \
--project-id proj_V1StGXR8Z5jdHi6B \
--collection-id coll_V1StGXR8Z5jdHi6B \
--data '{"status":"open","priority":{"gte":2}}'
const { data: page } = await naturali.collections.listCollectionItems({
path: {
project_id: 'proj_V1StGXR8Z5jdHi6B',
collection_id: 'coll_V1StGXR8Z5jdHi6B',
},
query: { data: JSON.stringify({ status: 'open', priority: { gte: 2 } }) },
});
curl -G https://api.naturali.ai/v1/projects/proj_V1StGXR8Z5jdHi6B/collections/coll_V1StGXR8Z5jdHi6B/items \
-H "Authorization: Bearer $NATURALI_TOKEN" \
--data-urlencode 'data={"status":"open","priority":{"gte":2}}'
Delete an item
- CLI
- SDK
- curl
naturali delete-collection-item \
--project-id proj_V1StGXR8Z5jdHi6B \
--collection-id coll_V1StGXR8Z5jdHi6B \
--key ticket-1042
await naturali.collections.deleteCollectionItem({
path: {
project_id: 'proj_V1StGXR8Z5jdHi6B',
collection_id: 'coll_V1StGXR8Z5jdHi6B',
key: 'ticket-1042',
},
});
curl -X DELETE https://api.naturali.ai/v1/projects/proj_V1StGXR8Z5jdHi6B/collections/coll_V1StGXR8Z5jdHi6B/items/ticket-1042 \
-H "Authorization: Bearer $NATURALI_TOKEN"