custom-data

List this organization's collections, oldest first, each with its declared fields (type, required, personal), its identity field and the ids of the query, get and write tools an agent reaches it through.

Create a collection: the place for every fact of the client's business the agent must read or write, such as opening hours, prices, services, customers. Use when the agent needs to read or write structured data instead of having a fact hard-coded into a prompt, because a record is edited while a prompt is republished.

A collection is a named set of records with a declared schema. Each field has a type, is optional or required, and is marked personal or not. Three tools appear with it — query, get and write — so an agent can reach it with no further setup.

The lean list a picker reads from — id and name only, no fields, no flag. Use when offering a collection picker that only needs names, not schemas.

Read one collection: its declared fields (type, required, personal), its identity field and the ids of the query, get and write tools an agent reaches it through.

Delete a collection, its records and its three tools permanently. Use when the collection and everything in it should stop existing.

Agents that referenced those tools stop being able to call them.

Rename a collection, or say which of its fields identifies a record. Use when the collection's name or identity field needs to change.

The identity field is any field you declared — it is what decides whether two records are the same thing, and what an import merges on.

Declare one more field on a collection, and regenerate its tools' schemas. Use when the collection's existing schema is missing a fact it needs to hold.

Undeclare a field. Use when the field should no longer exist on the collection; its values are dropped from every record.

Change a declared field. Use when a field's type, requiredness or personal-data marking needs to change, not when correcting one record's value.

Changing its type re-reads every stored value and refuses, naming examples, if any of them would not survive. Changing whether it is personal changes what the retention purge deletes.

Import a CSV into a collection. Use when the file and mapping have been checked with propose_import/plan_import and are ready to actually write.

With a mapping — the proposal as the client corrected it — every column it names that this collection does not declare becomes a field, and the columns left out of it are not written. Without one, columns are matched to declared fields by name and the rest are ignored. A cell that does not fit its field's type is discarded and the row is kept; a row that then lacks a required field its default does not fill is rejected whole. A row that adds a record gets the defaults of the fields it leaves empty. What was refused is recorded on the run, and a run that refused anything puts a notice in your inbox.

Say what importing this CSV would do, without doing any of it. Use after propose_import's mapping is confirmed and before import_records, to preview the effect.

How many records it creates and how many it merges onto ones already here, the rows it cannot take and why, the fields it would declare, and the fields of this collection the file says nothing about and will leave alone.

Read a CSV and propose what it would declare, without writing anything. Use first, before plan_import or import_records, to see how a file's columns would be understood.

Answers a field per column — name, type, whether it holds personal data, and the options of a column that repeats a short vocabulary — plus which columns already match this collection, which headers mean the same name, and which dates read equally well both ways round. Every value is a proposal to correct before importing.

Read one CSV import run: whether the file could be read at all, how many rows it had, how many were written or rejected, and why each rejected row was refused.

List a collection's records, oldest first or, at newest_first, newest first, narrowed by any filter. Use when showing or searching the records in a collection.

Add a record. Use when writing a new fact into a collection. Every value must fit its field's declared type.

If the collection declares an identity field and one already has that value, this updates it instead of adding a second. A field you leave empty that has a default gets it; a date defaulting to the day of creation is that day in your organization's timezone. At retention 0 the fields you marked personal are refused before they are written, and the answer says which.

Delete every record a selection names. Use when removing many records at once instead of one at a time; this cannot be undone.

Set one field to one value on every record a selection names. Use when the same correction applies to many records at once instead of one at a time.

Count the records a filter finds, however many pages they span. Use when you need how many records match, not the records themselves — before a bulk action, or to show a total.

List what a collection holds about one person: the records whose contact field names them, the number or address matched however it was written. Use on a person's record, once for each collection that marks a contact field (contact_field_key); empty for one that does not.

Delete everything a collection holds about one person: every record whose contact field names them. Use for the one action on a person's record that deletes all of what a recipe's collection remembers about them; this cannot be undone, so ask the person first. Their conversations stay.

Read one record by id, withdrawn or not: its values, who wrote each cell and when, and withdrawn_at if it was withdrawn. Queries and lists leave withdrawn records out; this read does not.

Withdraw one record by id. Use when a single record should stop being seen by the agent or returned; its history is kept.

Change some of a record's values. Use when correcting or updating one existing record by id; the fields you do not send are untouched.