Collection operations

5 operations named collection.*. Every one runs in a batch through apply_ops, dry_run_ops, the CLI or the admin.

Updated
OperationWhat it doesPermissionConfirmation
collection.listList the draft collections of the site, in order, each with its fields and its number of items.site.readnone
collection.readRead a draft collection: its key, label, fields, title field and slug field.site.readnone
collection.createCreate a collection with its typed fields.site.editnone
collection.updatePatch the label, fields, title field or slug field of a collection.site.editnone
collection.deleteDelete a collection and its draft items; published versions keep theirs until a publish.site.editdestructive

collection.list

List the draft collections of the site, in order, each with its fields and its number of items. Collections are versioned with the site: publish copies them with their published items, and the public site serves those.

permission: site.readreads onlyclass: read

Example input

{}

Input

The input is a record; see the schema below.

{
  "type": "object",
  "properties": {},
  "additionalProperties": false
}

Output

FieldTypeRequiredNotes
collectionsarray of objectyes
collections[].collectionobjectyes
collections[].itemCountintegeryesAt least 0.

Fields nested deeper are in the output schema that discover_operations answers with outputSchemas: true.

Try it

yarn splash collection.list '{}' --dry-run

collection.read

Read a draft collection: its key, label, fields, title field and slug field. Collections are versioned with the site: publish copies them with their published items, and the public site serves those.

permission: site.readreads onlyclass: read

Example input

{
  "collectionId": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d"
}

Input

FieldTypeRequiredNotes
collectionIdstring (uuid)yes

Output

FieldTypeRequiredNotes
collectionobjectyes
collection.uidstring (uuid)yes
collection.keystringyesAt most 40 characters.
collection.labelstring | record of stringyes
collection.fieldsarray of object | object | object | object | object | object | object | object | object | object | objectyesAt least 1 item. At most 40 items.
collection.titleFieldstringyes
collection.slugFieldstringyes
collection.positionintegeryesAt least 0.

Try it

yarn splash collection.read '{"collectionId":"a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d"}' --dry-run

collection.create

Create a collection with its typed fields. The key is unique on the site and never changes: blueprints, repeaters and dynamic pages name the collection by it. Collections are versioned with the site: publish copies them with their published items, and the public site serves those.

permission: site.editwrites: collectionsclass: transactionundo: yes

Example input

{
  "collection": {
    "key": "events",
    "label": {
      "it": "Eventi",
      "en": "Events"
    },
    "titleField": "title",
    "slugField": "title",
    "fields": [
      {
        "key": "title",
        "type": "text",
        "label": {
          "it": "Titolo",
          "en": "Title"
        },
        "localized": true,
        "required": true
      },
      {
        "key": "date",
        "type": "date",
        "label": {
          "it": "Data",
          "en": "Date"
        },
        "required": true
      },
      {
        "key": "venue",
        "type": "text",
        "label": {
          "it": "Luogo",
          "en": "Venue"
        }
      },
      {
        "key": "poster",
        "type": "media",
        "label": "Poster"
      },
      {
        "key": "photos",
        "type": "mediaList",
        "label": {
          "it": "Foto",
          "en": "Photos"
        }
      },
      {
        "key": "programme",
        "type": "file",
        "label": {
          "it": "Programma (PDF)",
          "en": "Programme (PDF)"
        },
        "localized": true
      },
      {
        "key": "speakers",
        "type": "reference",
        "label": {
          "it": "Relatori",
          "en": "Speakers"
        },
        "collection": "team",
        "multiple": true
      },
      {
        "key": "kind",
        "type": "select",
        "label": {
          "it": "Tipo",
          "en": "Kind"
        },
        "options": [
          {
            "value": "talk",
            "label": {
              "it": "Incontro",
              "en": "Talk"
            }
          },
          {
            "value": "screening",
            "label": {
              "it": "Proiezione",
              "en": "Screening"
            }
          }
        ]
      },
      {
        "key": "chapters",
        "type": "list",
        "label": {
          "it": "Capitoli",
          "en": "Chapters"
        },
        "fields": [
          {
            "key": "time",
            "type": "number",
            "label": "Seconds"
          },
          {
            "key": "title",
            "type": "text",
            "label": "Title",
            "localized": true
          }
        ]
      }
    ]
  }
}

Input

FieldTypeRequiredNotes
collectionobjectyes
collection.keystringyesAt most 40 characters.
collection.labelstring | record of stringyes
collection.fieldsarray of object | object | object | object | object | object | object | object | object | object | objectyesAt least 1 item. At most 40 items.
collection.titleFieldstringyes
collection.slugFieldstringyes

Output

FieldTypeRequiredNotes
collectionobjectyes
collection.uidstring (uuid)yes
collection.keystringyesAt most 40 characters.
collection.labelstring | record of stringyes
collection.fieldsarray of object | object | object | object | object | object | object | object | object | object | objectyesAt least 1 item. At most 40 items.
collection.titleFieldstringyes
collection.slugFieldstringyes
collection.positionintegeryesAt least 0.

Try it

yarn splash collection.create '{"collection":{"key":"events","label":{"it":"Eventi","en":"Events"},"titleField":"title","slugField":"title","fields":[{"key":"title","type":"text","label":{"it":"Titolo","en":"Title"},"localized":true,"required":true},{"key":"date","type":"date","label":{"it":"Data","en":"Date"},"required":true},{"key":"venue","type":"text","label":{"it":"Luogo","en":"Venue"}},{"key":"poster","type":"media","label":"Poster"},{"key":"photos","type":"mediaList","label":{"it":"Foto","en":"Photos"}},{"key":"programme","type":"file","label":{"it":"Programma (PDF)","en":"Programme (PDF)"},"localized":true},{"key":"speakers","type":"reference","label":{"it":"Relatori","en":"Speakers"},"collection":"team","multiple":true},{"key":"kind","type":"select","label":{"it":"Tipo","en":"Kind"},"options":[{"value":"talk","label":{"it":"Incontro","en":"Talk"}},{"value":"screening","label":{"it":"Proiezione","en":"Screening"}}]},{"key":"chapters","type":"list","label":{"it":"Capitoli","en":"Chapters"},"fields":[{"key":"time","type":"number","label":"Seconds"},{"key":"title","type":"text","label":"Title","localized":true}]}]}}' --dry-run

collection.update

Patch the label, fields, title field or slug field of a collection. A field removed or retyped is refused while an item holds a value for it. Collections are versioned with the site: publish copies them with their published items, and the public site serves those.

permission: site.editwrites: collection:{collectionId}class: transactionundo: yes

Example input

{
  "collectionId": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d",
  "patch": {
    "label": {
      "it": "Eventi e incontri",
      "en": "Events and talks"
    }
  }
}

Input

FieldTypeRequiredNotes
collectionIdstring (uuid)yes
patchobjectyes
patch.labelstring | record of stringno
patch.fieldsarray of object | object | object | object | object | object | object | object | object | object | objectnoAt least 1 item. At most 40 items.
patch.titleFieldstringno
patch.slugFieldstringno

Output

FieldTypeRequiredNotes
collectionobjectyes
collection.uidstring (uuid)yes
collection.keystringyesAt most 40 characters.
collection.labelstring | record of stringyes
collection.fieldsarray of object | object | object | object | object | object | object | object | object | object | objectyesAt least 1 item. At most 40 items.
collection.titleFieldstringyes
collection.slugFieldstringyes
collection.positionintegeryesAt least 0.

Try it

yarn splash collection.update '{"collectionId":"a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d","patch":{"label":{"it":"Eventi e incontri","en":"Events and talks"}}}' --dry-run

collection.delete

Delete a collection and its draft items; published versions keep theirs until a publish. Collections are versioned with the site: publish copies them with their published items, and the public site serves those.

permission: site.editwrites: collections, collection:{collectionId}class: transactionconfirm: destructiveundo: yes

Example input

{
  "collectionId": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d"
}

Input

FieldTypeRequiredNotes
collectionIdstring (uuid)yes

Output

FieldTypeRequiredNotes
successtrueyes

Needs confirmed: ["destructive"] on the batch, which the single-operation CLI form does not set: put it in a batch file and run yarn splash apply <file> --dry-run.

Generated from the operation registry and the MCP tool catalogue (source 61d7cdac4e4d9a70).

Something wrong on this page? Write to docs@librettocms.com.

Libretto docs

Colophon. These docs are a Libretto site: 68 pages in two languages, 20 guide pages imported from Markdown and 41 reference pages generated from the operation registry. Set in Softcore, with code in IBM Plex Mono. Its outline:

/ Libretto docs /start Get started /start/request-access Request access /start/workspace Your workspace /start/first-site Your first site /start/invite-a-client Invite a client /start/connect-claude Connect Claude to Libretto /build Build /build/first-page Build a page /build/layers-and-canvas Layers and canvas /build/site-components Site components /design-system Design system /design-system/tokens Colours, space and themes /design-system/components Components and variants /design-system/fonts Typography and fonts /motion Motion /motion/scenes Scenes and recipes /motion/image-sequences Image sequences /motion/reduced-motion Reduced motion /publish Publish /publish/languages Site languages /publish/versions Publish and versions /publish/members-and-forms Members and forms /publish/domains Domains /handover Hand a site to a client /glossary Glossary /agents Agents and API /agents/mcp MCP server /agents/cli CLI /agents/batches Batches /agents/errors Errors and findings /agents/operations Operations /search Search