# Collections and Outputs

> Where a loop keeps what it learns — collections of records — and where it sends a result when a run ends

A loop keeps what its runs produce in **collections**: named sets of records with declared
fields. It sends a result out of the platform through its **outputs**: a signed webhook to your
system, or an email.

## Declare a collection

A run may write only the collections its loop declares:

```yaml
collections:
  - name: leads
    key: email
    fields:
      email: string
      company: string
      company_size: string
      score: number
```

| Key | What it says |
|---|---|
| `name` | The collection's name, such as `leads`. |
| `key` | The field that identifies a record. Its value becomes the record's id. |
| `fields` | Each field and its type: `string`, `number`, `boolean`, `date`, `file` or `row`, or `generated` for the key alone. A write that carries a field the declaration does not have is refused. A `file` field holds a file a reader uploads through a page form ([Let readers upload a file](/docs/guide/pages.md#let-readers-upload-a-file)); only that upload fills it, and a loop's run or an automation that writes one is refused. |
| `shared` | `true` when other loops in the account may read and write this collection too. |
| `choices` | Optional. The only values a `string` field takes, by field: `status: [open, doing, done]`. See [Fixed values for a field](#fixed-values-for-a-field). |

The collection is created when you save the draft that declares it, so you can try the loop on
**My conversations** at once. A run writes records with `records_put` and reads them with
`records_query`.

### Let the platform make the key

When nothing in a record names it, such as a task or a ticket, declare the key `generated`:

```yaml
collections:
  - name: tasks
    key: task_id
    fields:
      task_id: generated
      title: string
      status: string
```

- **To create a record**, the run leaves `task_id` out. The platform makes a new id, a UUIDv7,
  and the answer to `records_put` names it. Three writes make three records.
- **To edit a record**, the run sends the `task_id` of a record it created or read, with the
  fields to change. The fields it leaves out keep their values, and the record keeps the time it
  was created. A `task_id` that no record holds is refused, and the refusal tells the
  model to leave the key out to create a record. So a model can never choose an id.
- Only the key can be `generated`, and such a collection takes no `writes: create`, because every
  new record has a new key. Saving the draft refuses both, and names the fix.
- A [page form](/docs/guide/pages.md#let-readers-add-a-record) on such a collection leaves the key
  out too: each save makes a new record.

To keep what a person types in a record, see
[Keep a value in a collection without the model](/docs/guide/asking-the-user.md#keep-a-value-in-a-collection-without-the-model).

### Fixed values for a field

A `string` field can name the only values it takes, such as a task's `status`: `open` or `done`.
On **Collections**, press **New collection**, tick **Only these values** under the field, and type
them, separated by commas. The card names them before you press **Create**: "Adds status (Text,
only open, done).". With the
API, give the field `"choices": ["open", "done"]` in its declaration.

To change the values of a field the collection already has, press **Change fields of**
the collection, and edit the values beside the field. Clear them to remove them all. The card
says the values now and after the press before you press **Save**: "Changes the choices of
status. Now: open, done. After the press: open, doing, done.".

- At most 50 values, each 1 to 100 characters. The console drops repeats.
- Only a `string` field takes choices; the review refuses another type and names the fix.
- A write sets a field's choices to what it sends, so a declaration that sends a field back as
  the collection lists it keeps them.
- Removing a value does not change the records that hold it. The card says how many hold each
  value you remove before you press **Save**: "1 record holds “blocked”; it keeps that value and
  no form offers it." A collection of more than 500 records reads "At least". A page's board shows
  such a record in a column of its own value, said as not one of the field's values.

In a loop, list them under the collection's `choices`, in the order a page shows them:

```yaml
collections:
  - name: tasks
    key: task_id
    fields:
      task_id: generated
      title: string
      status: string
    choices:
      status: [open, doing, done]
```

- Saving the draft refuses a list on a field that is not `string`, an empty list, and a value
  listed twice, and names the fix.
- A value outside the list is refused, naming the list: a run's `records_put`, a page form, a
  row's **Edit**, an action button and a block's `where=` all check it.
- Approving a version that lists different values for a field sets that field's list to them. A
  field the version lists none for keeps the values it has.
- A [page](/docs/guide/pages.md#blocks) shows a choice field's values as labels, asks for it with a
  list to choose from, and offers every value as a filter button.

### A field that refers to a row

A `row` field holds the record id of one row of a collection, such as the task a comment is on, or
a row of its own collection, such as a task's parent task. On **Collections**, give the field the
kind **A row of a collection** and choose its collection under **A row of…**, where a new
collection lists itself as "(this collection)"; the card names it: "Adds task (A row of tasks).". With the API, give the field
`"type": "row", "of": "tasks"`. The claim keeps it under the collection's `refs`:
`refs: {task: tasks}`.

- The collection must be one the account has; the review refuses another and names the ones it has.
- A collection has at most one `row` field.
- A write whose `row` field names no row of its collection is refused, naming the collection, and
  nothing is written.

### Who may change or remove rows from a page

A collection says who may change and who may remove its rows from a page, in `access`. Without
it, no page changes or removes a row:

```json
{"access": {"change": {"by": ["member", "user"], "rows": "own"},
            "remove": {"by": ["admin"], "rows": "any"}}}
```

- `by` names the readers who hold the right: any of `anonymous`, `user`, `invited`, `member` and
  `admin`. An invited reader's own rows are the ones they added from a page that invited them.
- `rows` is `own` (only the rows that reader added) or `any` (every row).
- A record remembers who added it: the person or visitor whose run or form wrote it. Records
  written before 2026-10-18, by a pipeline, or by an anonymous visitor have no one who added them,
  so they are nobody's own. An `own` right for `anonymous` is refused for that reason.
- A page may only narrow this: fewer readers, or `own` in place of `any`
  ([Who may change rows](/docs/guide/pages.md#the-page-document)).
- Set it on **Collections**: open the collection, which says who may change and remove its rows
  now, and press **Who may change rows of …**. This is the place for every collection, one a
  published loop declares too: the loop owns its key, fields and choices, and the rights are
  yours. A change to the fields of a loop's collection is refused here, naming the loop. Or set it
  with the collection's declaration,
  `PUT /api/workspace/collections/<name>` with an `access` key. A declaration without `access` keeps the one the collection has, and so does a
  loop that widens the collection; `"access": {}` removes it.
- The card that comes before the write says who may change and remove the rows once you press,
  and for a change to them, who may now and who may after.

A page's Edit, Delete and action buttons use it: see
[Let readers change and remove rows](/docs/guide/pages.md#let-readers-change-and-remove-rows).

### One collection, one loop, unless it is shared

A collection belongs to the account, and its name is its identity. If two loops declare the same
name, they read and write the same records. So saving a draft refuses a name that another loop
already declares, unless every loop that declares it says `shared: true`. The refusal names the
collection, the other loops, and both fixes: rename it, or declare it shared everywhere. Two
loops that already declare the same name can each be saved while you add `shared: true` to them
one at a time; a save that adds a new clash is still refused.

### Change a collection

A later version can add fields: records written before simply lack them. Saving the draft refuses
an edit that removes a field the loop declared before (in its published version or its saved draft), or changes a field's type or key,
and names the fields: keep them, or declare a new collection. A loop never removes a field it did
not add: a field you, a pipeline or another loop added stays, and leaving it out refuses nothing.

### Ask LoopAssistant for a collection or a field

You can ask LoopAssistant for a collection, or for a change to one you have: "add a due date to my
tasks", "let status be blocked too". It proposes the change on a card, and approving installs it.

- For a new collection, the card shows it whole: every field with its type and choices, and the
  field that names each record. Nobody may change or remove its rows from a page until you say so
  on the Collections page.
- For a change, the card shows only what changes: the fields it adds, and a field's choices before
  and after. Every field it does not name stays as it is.
- LoopAssistant never changes who may change or remove a collection's rows: you set that on the
  Collections page.
- A change from LoopAssistant only adds. It never removes a field or a choice; to remove a choice,
  edit the collection on the Collections page, whose card says how many records hold each value
  it removes.
- Create (or Save, for a change) installs it; Decline leaves the collection as it is.
- The card runs the same checks as the Collections page. A change that would change a field's type
  or the key is refused, naming the field, and a collection a published loop declares is changed
  in that loop.
- When a page you ask for needs a field the collection lacks, LoopAssistant proposes the field
  first, then the page. Saving such a page yourself is refused in words that say to add the field
  to the collection first.

### An automation that writes a collection

An automation step that writes a declared collection is held to its field types and its
[fixed values](#fixed-values-for-a-field), as a run's `records_put` is. If one row has a value of
another type, or a value outside a field's list, the step fails, names the row and the field, and
writes nothing. A field the collection does not declare is still written. The card you approve the
automation on warns about it and names the step that makes it: declare the field in the
collection, or remove what makes it.

## Read your records

**Collections** in the console shows your collections, one at a time. Each one says who writes
it: each loop that saves records into it, a crawl by the site it fetches, or an automation by its
name. An empty one says who will fill it.

**New collection** asks what the collection is called and what each record holds: each field's name
and its kind (Text, Number, Yes or no, Date, A file, or A row of a collection). Each record
gets its own id, so no record replaces another. To name each record by one of its fields instead,
such as a customer's email, open **More options**: the form and the card then say "A second record
with the same email replaces the first." **Review** says what is still missing. Your loops and pages
add records, and an owner can add one by hand; the collection then says it is written by *an owner,
by hand on Collections*.

- **Definition** shows what the collection is: each field with its kind in words and, where it has
  them, its only values; what the key does to a second record; and which fields are **sealed**: filled from what a person gave, never by the model, and never read back by a model.
  It says what each loop fills from its inputs, which loops and pages read the collection, and who
  may change or remove its rows from a page. A write that does not fit it is refused.
- **Records** shows the records, sorted by record id. Each row leads with its fields, then when it
  was written, then the ids: a field pio generates, such as a generated key, and the record id.
  When the key is a generated id, that one column is the record id.
- **Add a record…** on the Records tab, for an owner of a collection that declares its fields,
  opens one input per field by its kind, the field key first: a list of its values for a field with
  only some values, Yes or No, a date, and the records of the other collection for a row, each named
  by its first text, such as **Front desk (r-1)**. Reactor gives the record its
  own id, and a file is added through a page's form, so neither has an input. **Add the record**
  saves it; anything refused is said under the field it names. A field key must be filled: it
  names the record, and one already saved is refused rather than replaced.

To change the definition, press **Change fields of** the collection to add fields or change a
field's values, or **Who may change rows of** it. Each change shows its card before you save. To
show the records on a page of your own design, write a [page](/docs/guide/pages.md).

To serve records to another server, create an API with **New API** on **Schedules**, then open it
there and press its **Mint a key for** button, which names the API. See [Collections](/docs/api/collections.md) in the API reference.

## Outputs

`outputs` say where a result goes when something happens in a run. A run with no user must
declare at least one.

A webhook or an email output names the `event` that sends it:

- `run.ended`: once, when a run ends.
- `run.escalated`: when a run, or a task inside it, hands the work to your team.
- `record.written`: each time a run saves a record, while the run goes on. Two records saved
  make two deliveries, each naming its collection and record.

`run.started` and `check.failed` are not sent yet, so publishing an output on either is refused.

### A webhook

```yaml
outputs:
  - kind: webhook
    event: run.ended
    url: https://crm.example.com/hooks/pio
```

When a run ends, the platform POSTs a short JSON body to your `url`: the event, the loop and its
version, the run, and how it ended. The body carries identifiers, never text a model wrote; read
the run itself through the run API. Each delivery is signed with the loop's **webhook signing
secret**, shown on the loop's **Keys** tab. [Webhooks](/docs/api/webhooks.md#out-of-a-loop) shows the body, how to check
the signature, and the retries.

### An email

```yaml
outputs:
  - kind: email
    event: run.ended
    to: sales@example.com
```

`to` is one address. To email several people, add one email output for each: a list in `to`
is refused when you save the loop.

When a run ends, the platform sends an email to `to`, but only to a **verified** recipient:

- An address that belongs to a member of your account is verified already.
- Any other address gets one confirmation email from plutonium.io when you publish the loop. It
  receives nothing from the loop until that person confirms. The link in the confirmation is
  valid for 7 days.
- Every email carries a one-click **unsubscribe** link. After an unsubscribe the address gets
  nothing more, and adding it again needs a new confirmation.

An email for an address that is not verified is **held**: it is not sent, and it is not sent
later either. After the person confirms, the next run's email goes to them. A held email is not
charged, and on **Loops** its output counts it as not sent and says why. While an address a
published loop emails waits on a confirmation, **Home** names it under **Needs you**, with how many
of the loop's emails are held.

When you publish, the loop's page lists each address its email outputs name and what the publish
did about it. Afterwards, under each email output, **Loops** shows where its recipient stands:
confirmed, asked, lapsed, never asked, unsubscribed, or bounced. If no confirmation is waiting
(it lapsed, none could be sent, or the person unsubscribed), press **Send a confirmation email**
there. A confirmation that is still valid is not sent again.

If the confirmation email **bounces**, the address does not accept mail. Its recipient reads
"the confirmation bounced", and nothing asks that address again: correct the address in the email
output and publish the loop again. An address in a loop published before confirmations existed
has no recipient line; publish the loop again to send it a confirmation.

A page's form can email at each save, without a loop, with the same confirmation for an
address that is no member's: see
[Email someone when a form saves](/docs/guide/pages.md#email-someone-when-a-form-saves).

### Delivery status

On **Loops**, each webhook or email output says how its deliveries are doing: how many failed, how
many are waiting or retrying, how many emails were held and not sent, and the last error. A
delivery that fails never changes how the run ended.
