Skip to main content

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.

A plan caps how much your account stores

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​

FieldTypeDescription
idstring
project_idstring
namestring
schemaobject, nullableA JSON Schema every item's data must satisfy, stored as written. null removes it.
created_atstring (date-time)
updated_atstring (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​

FieldTypeDescription
collection_idstring
keystring
dataobjectThe item's JSON object, at most 64 KB serialized. Stored as jsonb, so key order is not kept.
tagsobjectKey-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.
versionintegerBumped by every write; what If-Match names.
created_atstring (date-time)
updated_atstring (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.

  • data is a structured filter over the item's data, as JSON: a value matches exactly, in matches any of a list, and gt, gte, lt, lte order the field against a number or a string.
  • A filter names top-level fields of data only. A nested value is not addressable: lift it to the top level, or into a tag, to filter on it.
  • tags=key:value narrows 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​

naturali create-collection \
--project-id proj_V1StGXR8Z5jdHi6B \
--name support-tickets

Write an item​

naturali put-collection-item \
--project-id proj_V1StGXR8Z5jdHi6B \
--collection-id coll_V1StGXR8Z5jdHi6B \
--key ticket-1042 \
--data '{"status":"open","priority":2}'

Merge into an item at the version you read​

naturali update-collection-item \
--project-id proj_V1StGXR8Z5jdHi6B \
--collection-id coll_V1StGXR8Z5jdHi6B \
--key ticket-1042 \
--data '{"status":"closed"}' \
--expected-version 1

List the open items of priority 2 or more​

naturali list-collection-items \
--project-id proj_V1StGXR8Z5jdHi6B \
--collection-id coll_V1StGXR8Z5jdHi6B \
--data '{"status":"open","priority":{"gte":2}}'

Delete an item​

naturali delete-collection-item \
--project-id proj_V1StGXR8Z5jdHi6B \
--collection-id coll_V1StGXR8Z5jdHi6B \
--key ticket-1042