records

GET /records/{collection}

Query a collection with the closed filter language. Never SQL.

06 §6 and Q19. Each `where` is `field:op:value`, at most eight, all of which must match. - field: a top-level document key matching `^[A-Za-z_][A-Za-z0-9_]*$`, or one of `id`, `created_at`, `updated_at`. No nested paths. Any field may be filtered; `storage.collections[].index` only makes it faster. - op: `eq ne lt lte gt gte in contains exists`. - value: everything after the second `:`, so a value may itself contain `:` (a timestamp, a URL); a field and an operator never do. Parsed as JSON when it is valid JSON (`42`, `true`, `null`, `"42"`), otherwise taken as a literal string. `in` takes a JSON array. `contains` is a case-sensitive substring test when the stored value is a string and a membership test when it is an array. `exists` takes `true` or `false`. `lt`, `lte`, `gt` and `gte` match only stored values of the filter value's JSON type, so `seed:gt:10` never matches a seed stored as the string "42" (M4, signed off by the human at the second review, #5). - `created_at` and `updated_at` take RFC 3339 values and compare as instants (they are stored as milliseconds), so `created_at:gte:2026-09-15T00:00:00Z` works; any other value is `bad_filter`, and so are `contains` and `exists` on them. `id` compares as a string, which for ULIDs is creation order. Every value is bound as a parameter. `order` is `field:asc` or `field:desc` on one field, default `created_at:desc`, with `id` breaking ties in the same direction. Deleted records are never returned. Bad syntax, an unknown operator or more than eight clauses is 400 `bad_filter`.

Needs the records capability.

POST /records/{collection}

Insert a document; returns its id and etag.

06 §6. The body is the document, a JSON object. A studio may write to any collection name matching the manifest schema's pattern, declared or not. Each live record counts toward the `records` quota (Q20).

Needs the records capability.

Request body: JSONObject (application/json)

GET /records/{collection}/{id}

One record. Deleted, in another collection, or another studio's is 404.

Needs the records capability.

PUT /records/{collection}/{id}

Replace a document. If-Match on the etag; 409 on conflict.

Needs the records capability.

Request body: JSONObject (application/json)

PATCH /records/{collection}/{id}

Apply a JSON merge patch (RFC 7396). If-Match on the etag; 409 on conflict.

Needs the records capability.

Request body: JSONObject (application/merge-patch+json)

DELETE /records/{collection}/{id}

Soft-delete, so an undo is possible and a sync never sees a gap.

06 §6. The record stops counting toward the `records` quota.

Needs the records capability.