🗂️ Collections

An app keeps its own data in collections: typed records with fields, rights per role and a history. collections_read reads them and collections_write changes them.

Call collections_read.definitions first. It lists the collections the role may read, each with its key, fields, binding, display template and what the role may do with its records. Every other action takes a collection key from that list.

Use docs.describe for the exact fields, conditions, refusal codes and an example call of each action.

Reading

• list takes the collection and, optionally, filter, search, sort, robot, limit, cursor, count, expand and deleted. A filter is an object such as {"status": {"eq": "idle"}}, at most 6 KiB (6,144 characters) as JSON through MCP, where the REST routes take 16 KiB; sort and expand are lists. App Data has the grammar.
• A page is cut at about 512 KiB, so it can hold fewer than limit records. Only a next_cursor of null ends the list.
• deleted: true lists deleted records instead, newest deletion first. It needs the right to create records.
• get takes the collection and exactly one of record_id and robot. With robot the answer is that robot’s oldest record, which suits a collection with one record per robot.
• history takes the collection and record_id and, optionally, limit and before_seq. It lists the changes newest first and is open to whoever may update the record. Only a next_before_seq of null ends it.
• In a collection that belongs to robots, the person sees the records of the robots the role reaches. A record of another robot answers not_found.

Writing

• create takes the collection, the values by field key, and robot_id in a collection that belongs to robots. It answers the record as stored, with the defaults filled in. A missing required field answers required_missing and names the fields.
• update takes the collection, record_id and values. Only the fields sent change, null clears one, and a required field cannot be cleared. With expected_revision, a record that moved on answers record_changed with the current revision.
• delete takes the collection and record_id and answers {"deleted": true}. The history stays. A record that others point to with on_delete: prevent answers record_referenced and counts the referencing records per collection.
• restore takes the collection, record_id and, optionally, seq. With seq from history it puts the record back to its state after that revision, as a new revision. Without it, it restores a deleted record. The values must still fit today’s schema, or the call is refused and names the fields.
• A collection with one record per robot is filled by Fleetless. It takes no create and no delete.

Rights and refusals

• Rights are decided on every call, by the person’s current role and the access lists of the published schema. A role change applies to the next call, in an open session too.
• A refused action answers 403 forbidden: the role has some right on the collection, but not the one this action needs, or only the right to change the records it created itself.
• A collection the role has no right on at all answers 404 collection_not_found, as one that does not exist, or that a publish has removed. definitions does not list it either, so take the keys from there, not from memory.

Limits

• A request through MCP is at most 1 MiB. A record near the 1 MiB cap is written through the app or the SDK.
• Writes are limited to 120 a minute for one person and 600 for the app. Over that, the answer is 429 rate_limited with retry_after_ms.
• Over the plan’s record or storage limit, a write that adds data answers 409 plan_limit. Reads continue.
• There is no schema, import or export action here. A developer’s tools write the schema, and a server key imports and exports over the REST API.