Collection item operations

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

Updated
OperationWhat it doesPermissionConfirmation
item.listList the draft items of a collection in order, optionally only those with a status, with the collection they fit.site.readnone
item.readRead a draft item.site.readnone
item.historyList the published versions that hold the item, newest first, each with the item as it was published there.site.readnone
item.createAdd a draft item at the end of a collection.content.editnone
item.updatePatch the slug or values of an item: values is merged key by key, and a null removes a key.content.editnone
item.deleteDelete a draft item; the published versions keep it until a publish, and item.rollback can bring it back.content.editdestructive
item.reorderReorder the items of a collection: itemIds names every item once, in the new order.content.editnone
item.importAdd many draft items at once, all or none.content.editnone
item.rollbackRestore an item of the draft to how a published version held it: its slug, values and status.content.editnone
item.setStatusSet an item's status: a published item is served by the next publication.publish, a draft item is not.content.publishnone

item.list

List the draft items of a collection in order, optionally only those with a status, with the collection they fit. 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",
  "status": "published"
}

Input

FieldTypeRequiredNotes
collectionIdstring (uuid)yes
statusstringnoOne of "draft", "published".

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.
itemsarray of objectyes
items[].uidstring (uuid)yes
items[].statusstringyesOne of "draft", "published".
items[].slugstring | record of stringyes
items[].valuesrecord of any JSONyes
items[].positionintegeryesAt least 0.
items[].updatedAtstring (date-time)yes

Try it

yarn splash item.list '{"collectionId":"a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d","status":"published"}' --dry-run

item.read

Read a draft item. 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",
  "itemId": "b2c3d4e5-f6a7-4b8c-9d0e-1f2a3b4c5d6e"
}

Input

FieldTypeRequiredNotes
collectionIdstring (uuid)yes
itemIdstring (uuid)yes

Output

FieldTypeRequiredNotes
collectionIdstring (uuid)yes
itemobjectyes
item.uidstring (uuid)yes
item.statusstringyesOne of "draft", "published".
item.slugstring | record of stringyes
item.valuesrecord of any JSONyes
item.positionintegeryesAt least 0.
item.updatedAtstring (date-time)yes

Try it

yarn splash item.read '{"collectionId":"a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d","itemId":"b2c3d4e5-f6a7-4b8c-9d0e-1f2a3b4c5d6e"}' --dry-run

item.history

List the published versions that hold the item, newest first, each with the item as it was published there. 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",
  "itemId": "b2c3d4e5-f6a7-4b8c-9d0e-1f2a3b4c5d6e"
}

Input

FieldTypeRequiredNotes
collectionIdstring (uuid)yes
itemIdstring (uuid)yes

Output

FieldTypeRequiredNotes
collectionIdstring (uuid)yes
itemIdstring (uuid)yes
versionsarray of objectyes
versions[].versionIdstring (uuid)yes
versions[].publishedAtstring (date-time)yes
versions[].isActivebooleanyes
versions[].notestringno
versions[].itemobjectyes

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

Try it

yarn splash item.history '{"collectionId":"a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d","itemId":"b2c3d4e5-f6a7-4b8c-9d0e-1f2a3b4c5d6e"}' --dry-run

item.create

Add a draft item at the end of a collection. Its values are checked against the collection's fields and the site's locales; a reference names an item of the referenced collection, and a media or file value a media row of the site. Collections are versioned with the site: publish copies them with their published items, and the public site serves those.

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

Example input

{
  "collectionId": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d",
  "slug": {
    "it": "giornata-del-recupero",
    "en": "recovery-day"
  },
  "values": {
    "title": {
      "it": "Giornata del recupero",
      "en": "Recovery day"
    },
    "date": "2026-11-21",
    "venue": "Teatro Comunale",
    "poster": "2c3d4e5f-6a7b-4c8d-9e0f-1a2b3c4d5e6f",
    "photos": [
      "2c3d4e5f-6a7b-4c8d-9e0f-1a2b3c4d5e6f"
    ],
    "speakers": [
      "c3d4e5f6-a7b8-4c9d-8e0f-2a3b4c5d6e7f"
    ]
  }
}

Input

FieldTypeRequiredNotes
collectionIdstring (uuid)yes
slugstring | record of stringno
valuesrecord of any JSONyes

Output

FieldTypeRequiredNotes
collectionIdstring (uuid)yes
itemobjectyes
item.uidstring (uuid)yes
item.statusstringyesOne of "draft", "published".
item.slugstring | record of stringyes
item.valuesrecord of any JSONyes
item.positionintegeryesAt least 0.
item.updatedAtstring (date-time)yes

Try it

yarn splash item.create '{"collectionId":"a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d","slug":{"it":"giornata-del-recupero","en":"recovery-day"},"values":{"title":{"it":"Giornata del recupero","en":"Recovery day"},"date":"2026-11-21","venue":"Teatro Comunale","poster":"2c3d4e5f-6a7b-4c8d-9e0f-1a2b3c4d5e6f","photos":["2c3d4e5f-6a7b-4c8d-9e0f-1a2b3c4d5e6f"],"speakers":["c3d4e5f6-a7b8-4c9d-8e0f-2a3b4c5d6e7f"]}}' --dry-run

item.update

Patch the slug or values of an item: values is merged key by key, and a null removes a key. The merged values are checked like item.create's. Collections are versioned with the site: publish copies them with their published items, and the public site serves those.

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

Example input

{
  "collectionId": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d",
  "itemId": "b2c3d4e5-f6a7-4b8c-9d0e-1f2a3b4c5d6e",
  "patch": {
    "values": {
      "venue": "Sala civica",
      "photos": null
    }
  }
}

Input

FieldTypeRequiredNotes
collectionIdstring (uuid)yes
itemIdstring (uuid)yes
patchobjectyes
patch.slugstring | record of stringno
patch.valuesrecord of any JSON | nullno

Output

FieldTypeRequiredNotes
collectionIdstring (uuid)yes
itemobjectyes
item.uidstring (uuid)yes
item.statusstringyesOne of "draft", "published".
item.slugstring | record of stringyes
item.valuesrecord of any JSONyes
item.positionintegeryesAt least 0.
item.updatedAtstring (date-time)yes

Try it

yarn splash item.update '{"collectionId":"a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d","itemId":"b2c3d4e5-f6a7-4b8c-9d0e-1f2a3b4c5d6e","patch":{"values":{"venue":"Sala civica","photos":null}}}' --dry-run

item.delete

Delete a draft item; the published versions keep it until a publish, and item.rollback can bring it back. Collections are versioned with the site: publish copies them with their published items, and the public site serves those.

permission: content.editwrites: collection:{collectionId}class: transactionconfirm: destructiveundo: yes

Example input

{
  "collectionId": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d",
  "itemId": "b2c3d4e5-f6a7-4b8c-9d0e-1f2a3b4c5d6e"
}

Input

FieldTypeRequiredNotes
collectionIdstring (uuid)yes
itemIdstring (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.

item.reorder

Reorder the items of a collection: itemIds names every item once, in the new order. Collections are versioned with the site: publish copies them with their published items, and the public site serves those.

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

Example input

{
  "collectionId": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d",
  "itemIds": [
    "c3d4e5f6-a7b8-4c9d-8e0f-2a3b4c5d6e7f",
    "b2c3d4e5-f6a7-4b8c-9d0e-1f2a3b4c5d6e"
  ]
}

Input

FieldTypeRequiredNotes
collectionIdstring (uuid)yes
itemIdsarray of string (uuid)yesAt least 1 item.

Output

FieldTypeRequiredNotes
itemIdsarray of string (uuid)yes

Try it

yarn splash item.reorder '{"collectionId":"a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d","itemIds":["c3d4e5f6-a7b8-4c9d-8e0f-2a3b4c5d6e7f","b2c3d4e5-f6a7-4b8c-9d0e-1f2a3b4c5d6e"]}' --dry-run

item.import

Add many draft items at once, all or none. A media, media list or file value names each media row by its id or by the exact filename of a file in the media library. Collections are versioned with the site: publish copies them with their published items, and the public site serves those.

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

Example input

{
  "collectionId": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d",
  "rows": [
    {
      "values": {
        "title": "Open day",
        "date": "2026-12-05",
        "poster": "open-day-poster.jpg"
      }
    },
    {
      "slug": "winter-talk",
      "values": {
        "title": {
          "it": "Incontro d'inverno",
          "en": "Winter talk"
        },
        "date": "2027-01-16",
        "poster": "2c3d4e5f-6a7b-4c8d-9e0f-1a2b3c4d5e6f"
      }
    }
  ]
}

Input

FieldTypeRequiredNotes
collectionIdstring (uuid)yes
rowsarray of objectyesAt least 1 item. At most 500 items.
rows[].slugstring | record of stringno
rows[].valuesrecord of any JSONyes

Output

FieldTypeRequiredNotes
collectionIdstring (uuid)yes
itemsarray of objectyes
items[].uidstring (uuid)yes
items[].statusstringyesOne of "draft", "published".
items[].slugstring | record of stringyes
items[].valuesrecord of any JSONyes
items[].positionintegeryesAt least 0.
items[].updatedAtstring (date-time)yes

Try it

yarn splash item.import '{"collectionId":"a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d","rows":[{"values":{"title":"Open day","date":"2026-12-05","poster":"open-day-poster.jpg"}},{"slug":"winter-talk","values":{"title":{"it":"Incontro d'\''inverno","en":"Winter talk"},"date":"2027-01-16","poster":"2c3d4e5f-6a7b-4c8d-9e0f-1a2b3c4d5e6f"}}]}' --dry-run

item.rollback

Restore an item of the draft to how a published version held it: its slug, values and status. When that version did not hold the item, the rollback removes it from the draft. Collections are versioned with the site: publish copies them with their published items, and the public site serves those.

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

Example input

{
  "collectionId": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d",
  "itemId": "b2c3d4e5-f6a7-4b8c-9d0e-1f2a3b4c5d6e",
  "versionId": "8b9c0d1e-2f3a-4b4c-8d5e-6f7a8b9c0d1e"
}

Input

FieldTypeRequiredNotes
collectionIdstring (uuid)yes
itemIdstring (uuid)yes
versionIdstring (uuid)yes

Output

FieldTypeRequiredNotes
collectionIdstring (uuid)yes
itemobject | nullyes

Try it

yarn splash item.rollback '{"collectionId":"a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d","itemId":"b2c3d4e5-f6a7-4b8c-9d0e-1f2a3b4c5d6e","versionId":"8b9c0d1e-2f3a-4b4c-8d5e-6f7a8b9c0d1e"}' --dry-run

item.setStatus

Set an item's status: a published item is served by the next publication.publish, a draft item is not. Collections are versioned with the site: publish copies them with their published items, and the public site serves those.

permission: content.publishwrites: collection:{collectionId}class: transactionundo: yes

Example input

{
  "collectionId": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d",
  "itemId": "b2c3d4e5-f6a7-4b8c-9d0e-1f2a3b4c5d6e",
  "status": "published"
}

Input

FieldTypeRequiredNotes
collectionIdstring (uuid)yes
itemIdstring (uuid)yes
statusstringyesOne of "draft", "published".

Output

FieldTypeRequiredNotes
collectionIdstring (uuid)yes
itemobjectyes
item.uidstring (uuid)yes
item.statusstringyesOne of "draft", "published".
item.slugstring | record of stringyes
item.valuesrecord of any JSONyes
item.positionintegeryesAt least 0.
item.updatedAtstring (date-time)yes

Try it

yarn splash item.setStatus '{"collectionId":"a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d","itemId":"b2c3d4e5-f6a7-4b8c-9d0e-1f2a3b4c5d6e","status":"published"}' --dry-run

Generated from the operation registry and the MCP tool catalogue (source 3c0e72376c54145a).

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