Tools: CMS

These tools work with CMS collections and their items. Collections and items aren't files; manage them only with these tools. See When to use a collection and Reading CMS content in code.

list_items

Lists or searches the items in a collection.

When to use it: To browse a collection or find items before updating them.

Needs an open turn: No.

Input	Type	Required	Meaning
collection	string	Yes	The collection's name, such as blogPost.
filter	object	No	Match field values exactly or with operators: $eq, $ne, $gt, $gte, $lt, $lte, $in, $contains, $all, $exists. Example: {"publishedAt": {"$gte": "2026-01-01"}}.
search	string	No	Full-text search across the collection's text fields, ranked by relevance.
sort	object	No	{"field": "publishedAt", "direction": "desc"}. Ignored when search is used.
limit	number	No	Most items to return. Default 20.
offset	number	No	Items to skip, for paging. Default 0.

Example call

{
  "siteId": "0APMiuxGY2yB4xJm5BilJ",
  "collection": "docPage",
  "limit": 1
}

Example result

{
  "success": true,
  "collection": "docPage",
  "total": 2,
  "returned": 1,
  "offset": 0,
  "items": [
    {
      "id": "docPage-bxxr7i",
      "title": "Quickstart",
      "revision": 1,
      "slug": "quickstart",
      "updatedAt": "2026-10-17T21:38:22.739Z"
    }
  ]
}

Errors

You see	What it means	What to do
"Collection … not found"	There's no collection with that name.	Check the name. Collection names are camelCase, such as blogPost.
"Unknown field …" or "Operator … is not supported on …"	The filter uses a field or operator the collection doesn't support.	Fix the filter.

modify_collection

Creates a collection, changes its fields, or asks the user to delete it. Creating can also generate sample items.

When to use it: For structured, repeating content such as blog posts, products or team members. After creating one, build the pages that show it.

Needs an open turn: Yes. Call start_turn first.

Input	Type	Required	Meaning
action	string: create, update or delete	Yes	What to do.
name	string	Yes	The collection's name in camelCase, such as blogPost.
label	string	For create	Human-readable name, such as Blog Post.
fields	object	For create	Field definitions keyed by field name. Each has type, label and optional required, plus type-specific settings (below).
displayField	string	No	The field shown as each item's title. Default: the first text field.
contentDescription	string	No	What sample items should be about, such as blog about sourdough baking.
sampleItemCount	number	No	How many sample items to generate. Default 3.
addFields	object	No	For update: new fields, in the same shape as fields.
updateFields	object	No	For update: changes to existing fields' settings, keyed by field name.
removeFields	array of strings	No	For update: fields to remove.
fillMissing	object	No	For update: values to give existing items when a field becomes required, keyed by field name (dotted path for nested fields).

Example call

{
  "siteId": "0APMiuxGY2yB4xJm5BilJ",
  "action": "create",
  "name": "blogPost",
  "label": "Blog Post",
  "fields": {
    "title": {
      "type": "string",
      "label": "Title",
      "required": true
    },
    "slug": {
      "type": "slug",
      "label": "Slug",
      "slugFrom": "title"
    },
    "cover": {
      "type": "image",
      "label": "Cover",
      "altField": "coverAlt"
    },
    "coverAlt": {
      "type": "string",
      "label": "Cover alt text"
    },
    "body": {
      "type": "markdown",
      "label": "Body"
    }
  },
  "contentDescription": "blog about sourdough baking",
  "sampleItemCount": 3
}

Example result

{
  "success": true,
  "collection": "blogPost"
}

Field types: string, text, markdown, slug, color, enum, link, number, boolean, datetime, image, reference, array, object, dictionary. See Field types.

• An image field SHOULD have a companion text field for alt text, named in altField.
• A reference field lists the collections it can link to in targetTypes. Those collections must exist first.
• An array field has items (one element shape) or itemTypes (named alternatives for a mixed list).
• _key and _type are reserved names.
• A saved field's name and type never change.
• Delete doesn't delete anything by itself. Starjay asks the user, who confirms with a click. Your agent learns the outcome on its next turn.
• Sample items are generated by Starjay and use credits.

Errors

You see	What it means	What to do
already_exists	A collection with that name exists.	Use update, or pick another name.
collection_in_use: "… is used by /blog. Remove it there first."	A page reads the collection, so it can't be deleted.	Remove its use from those pages first.
field_in_use	The site's code uses a field, choice or item type you tried to remove. The message names the pages.	Change those pages first.
validation_failed	A field definition isn't valid.	Fix the field definitions using the message.
insufficient_credits	Not enough credits for sample items.	Create without contentDescription, or ask the user to add credits.
not_lock_holder	Your agent has no open turn on this site, or its turn lapsed.	Call start_turn, then retry.
lock_lost	Someone took the site back (for example with Take back control) or the turn expired and was reopened.	Call start_turn to begin a new turn, then retry.
site_publishing	The site is publishing. Editing is paused until it finishes.	Wait for the publish to finish, then retry.

modify_items

Creates or updates items in a collection, or asks the user to delete items.

When to use it: To add or change specific content the user asks for. For sample content when creating a collection, use modify_collection.

Needs an open turn: Yes. Call start_turn first.

Input	Type	Required	Meaning
action	string: create, update or delete	Yes	What to do.
collection	string	Yes	The collection's name.
items	array of objects	For create and update	For create: each item's field values. For update: {"id": …, …changes}. A list field is replaced whole, so send the full list and keep each entry's _key.
ids	array of strings	For delete	The IDs of the items to ask the user to delete.

Example call

{
  "siteId": "0APMiuxGY2yB4xJm5BilJ",
  "action": "update",
  "collection": "blogPost",
  "items": [
    {
      "id": "blogPost-a1b2c3",
      "title": "Our first loaf"
    }
  ]
}

Example result

{
  "success": true,
  "updated": 1
}

Items are saved as drafts. The user publishes them in the CMS view. See Publish and unpublish items. Deleting works like collections: the user confirms each delete.

Errors

You see	What it means	What to do
validation_failed	A value doesn't fit its field, or a reference points at an item that doesn't exist.	Fix the values using the message.
not_found	An item ID doesn't exist.	Find the right ID with list_items.
delete_blocked	Another item links to it through a required field.	Change or remove the link first.
revision_conflict or edit_conflict	The item changed at the same time, for example in the CMS view.	Read it again with list_items and retry.
not_lock_holder	Your agent has no open turn on this site, or its turn lapsed.	Call start_turn, then retry.
lock_lost	Someone took the site back (for example with Take back control) or the turn expired and was reopened.	Call start_turn to begin a new turn, then retry.
site_publishing	The site is publishing. Editing is paused until it finishes.	Wait for the publish to finish, then retry.

Related

• Create a collection
• Reading CMS content in code