Tools

Start here — zero parameters. Returns the sites; the collections, taxonomies, global sets, asset containers, and navigations (menus, with their max_depth, and the sites they have a tree in on multisite), and forms (with stores_submissions, false when the form only sends email, and their submission count) exposed to MCP and visible to you; your capability flags per resource (can_create, can_edit, can_publish, can_upload, can_delete — delete flags appear only when deletes are enabled; collections whose blueprint has an author field add can_edit_other_authors, can_publish_other_authors, and can_delete_other_authors, which apply to entries you are not an author of); on dated collections, date_behavior (future/past: public, unlisted, or private — a published entry dated in the future is scheduled only where future is private); on multisite, each collection's sites, propagate (whether entries_create makes a localization in every site at once), and origin_behavior (root: entries_localize always localizes from the root entry); the acting user (id, email, roles, is_super — compare id with an entry's author); and the server block: read_only, deletes, and timezone (the zone a date without an offset is read in). When the site has guidelines for agents (voice, tone, rules for all content), they come back in guidelines — follow them in everything you write.

Returns a blueprint's fields (handle, type, rules, required, options, instructions; time_enabled on date fields — without it the Control Panel shows only the day, not the time; on multisite, localizable: only such a field can hold a value of its own in a localization) plus a valid example payload for writes. Pass type (collection|taxonomy|global|form|navigation) and the resource handle from statamic_overview; optionally a specific blueprint handle (defaults to the one entries_create and terms_create use). For a form, the fields are the keys of its submissions' data; nothing writes a submission. For a navigation, the fields are what a branch's data takes in navigations_update, and example is one branch's data; title and url are branch keys beside data, as example_notes says when the blueprint defines them. Relation-field examples are placeholders — replace them with real IDs. Fields with a null example carry a note in example_notes; read a real value from existing content for those. On collection and taxonomy blueprints, slug (and date on dated collections) is left out of the example: the entries_* and terms_* write tools take it as a top-level parameter, as example_notes says. Cross-check each field's rules — examples satisfy shape, not every validation rule. Replicator and Bard fields list their sets (page builder blocks) with each set's display name, group, and instructions — follow a set's instructions when choosing and filling it, and never add a set marked hidden. Pass set with a set's handle to get its fields and an example row. Notes on nested values are keyed by path, like seo.meta_title. Tabs and sections that carry instructions come back in tabs, with the handles of the fields under them — follow those when filling the fields they name. When the site's guidelines for agents cover this collection or taxonomy, they come back in guidelines — follow them.

List entries in a collection — summary columns only (id, title, slug, status, url, date, updated_at); field data is never included, use entries_get for that. Paginated: the response carries total, total_pages, and next_page (null on the last page). Ordering is deterministic: dated collections newest-first by date, others alphabetical by title, with id as tiebreaker.

Get a single entry by id, or by collection + slug. Returns raw field data by default — the round-trippable shape for entries_update. format=augmented returns rendered values for display only: NEVER send augmented data back into entries_update. Large values are truncated to preview objects unless requested via fields (an array of top-level field handles): Bard and Markdown over 500 bytes, and any other value over 4 KB, a Grid excepted. A large Replicator field (a page builder) comes back as an index of its sets — id, type, and a short preview each — unless requested via fields: e.g. "page_builder" fetches the whole field, "page_builder.<id>" one set (of a Replicator or Grid), as an object keyed by its id that entries_update merges back by id. fields selects blueprint fields, and in raw format any other key the entry stores — augmented-only keys such as permalink are not selectable. On revision-enabled entries, has_working_copy reports whether staged (unpublished) changes exist, and the returned data is the staged working copy when there is one, as in the Control Panel's edit form: exactly what entries_update builds on and entries_publish would promote. working_copy: false returns the live entry instead, and source says which one you got. On a collection in more than one site, localizations lists each site you can access with the id and status of the entry there, or null where it has none — add one with entries_localize.

Create a new entry from raw field data (call blueprints_get first for the shape — never send augmented data). Always saves an unpublished draft — nothing goes live here; call entries_publish afterwards. On revision-enabled collections the draft gets an initial revision attributed to you. slug is generated from data.title when omitted, except on a collection with slugs turned off, whose entries have none. Dated collections require date. On a structured collection the entry joins its tree at the top level, or under parent: the id of an entry of the same collection and site. A new Replicator or Grid set whose id is blank, 0, or shared with another new set gets a fresh id; entries_get shows the stored ids. When the blueprint has an author field, you become the author unless data names one; naming anyone else needs 'edit other authors {collection} entries'. On a collection in more than one site the entry exists in site only: add it to another site with entries_localize. When the collection's propagate is on (see statamic_overview), every site gets a localization at once, and the response lists them under localizations.

Update an entry with a shallow top-level merge of raw field data: nested structures (Bard, arrays) are replaced wholesale, never deep-merged — always send the complete new value for a nested field. To change one piece of Bard, Markdown, text, or textarea text, send {"find": "...", "replace": "..."} instead of the whole value: find must match the stored text exactly once, inside one formatting run for Bard, and only that piece changes, also in a set addressed by id. The exception is a Replicator or Grid field (a page builder), whose sets are addressed by the id entries_get shows: an object keyed by set id merges into just those sets — e.g. {"page_builder": {"wKJQXf2s": {"variant": "centered"}}} changes one field of one block; send only the fields you change, and null to remove a set. A list sets the order: an item with a stored id merges into that set the same way, so {"id": "wKJQXf2s"} keeps it as it is, an item in another type replaces its set, an item without an id is a new set, and the sets you leave out are removed — add a block by sending the ids in order with the new set where it goes, never the whole page. Inside a set the merge is shallow: each named field is replaced whole, a Group included, null clears it, and a Replicator or Grid nested in the set merges by id the same way. The whole field is then validated and saved as the Control Panel saves it: keys a set already stores pass, also ones its blueprint no longer defines, but a block that no longer passes its blueprint's rules blocks the write and is named by id in the error. The result lists the ids of new sets under added; a new set whose id is blank, 0, or sent twice gets a fresh one. null clears the field, and an empty list or object is refused. Explicit null clears a field (stores a local null); resetting a field to inherit from its origin localization is not supported in v1. Publish state is never changed here — that is entries_publish / entries_unpublish. Without revisions, re-dating a published entry on a collection whose date_behavior is private (see statamic_overview) can schedule or expire it; status and result report the outcome. On revision-enabled collections, edits to a published entry are staged as a working copy attributed to you (the live entry stays unchanged — promote it with entries_publish); when a working copy already exists the edit rebases onto it (created vs amended is stated in the result), and unpublished drafts are saved directly. site is a selector only — it must match the entry's own site; entries_localize adds an entry to another site. On a localization, data may only name fields the blueprint marks localizable: every other field shows the origin's value in every site, so change it on the origin entry. If the merged result equals the current entry, nothing is saved. When the blueprint has an author field, editing an entry you are not an author of needs 'edit other authors {collection} entries', and so does changing its author. parent moves the entry, with its children, in a structured collection's tree: pass the id of an entry of the same collection and site to make it that entry's last child, or "" for the top level; omitted or null, the entry stays where it is. Moving needs reorder {collection} entries, like the CP's tree, on top of the edit permission and its author rule. A move saves the live tree at once, also when the data goes to a working copy: working copies never stage tree position. The result reports the move under move and the new parent under parent.

Add an entry to another site of its collection, the way the Control Panel's Localize action does. The new entry is a localization of the one passed: it inherits every field it does not override, and data holds the values of its own, such as a translated title and content. A new Replicator or Grid set whose id is blank, 0, or shared with another new set gets a fresh id; entries_get shows the stored ids. Only fields marked localizable in the blueprint take a value of their own; the rest show the origin's value in every site, and the Control Panel makes them read-only there. The origin is the entry passed, or the root entry when the collection's origin_behavior is root (see statamic_overview), as in the Control Panel. slug defaults to the origin's slug, and the date of a dated collection is inherited. Always saves an unpublished draft — nothing goes live here; call entries_publish afterwards. On a structured collection the localization joins the target site's tree under the localization of the origin's parent, or at the top level when the parent has none there. Needs the edit permission for the origin entry, as in the Control Panel, and access to the target site. A site that already has the entry is an error naming that entry: change it with entries_update. Collections whose propagate is on (see statamic_overview) get a localization in every site from entries_create already, and entries_get lists them under localizations. Only registered on multisite installs.

Get a URL that renders an entry through the site's own templates, so you can check how your changes look without a human opening the browser. Fetch the URL to see the page. It uses Statamic's Live Preview, so unpublished drafts render even though the public site returns 404 for them. On revision-enabled entries with a staged working copy, the page shows the working copy, not the live entry. The URL works for anyone who has it until expires_at, an hour after the call, so share it only with people who may see the draft. Requires the collection's edit permission, as Live Preview does in the Control Panel, or 'edit other authors {collection} entries' for an entry you are not an author of when the blueprint has an author field. Entries of a collection without a route have no page to preview. target picks a preview target by label and defaults to the collection's first; targets lists them all. Each call creates a new preview token and changes no content.

Make an entry live by id. Requires the publish permission for the collection, or 'publish other authors {collection} entries' for an entry you are not an author of when the blueprint has an author field. On revision-enabled collections this promotes the staged working copy (or the draft itself when nothing is staged) and records a publish revision attributed to you — the same flow as the Control Panel's Publish button. On a dated collection whose date_behavior.future is private (see statamic_overview), an entry dated in the future is scheduled instead: status and result say scheduled, and Statamic takes it live on that date with no further call. To schedule a post, set its date with entries_create or entries_update, then publish it. An already-published entry with nothing staged is a no-op. This is the only tool that publishes: entries_create and entries_update never change publish state.

Take a live entry offline by id. Requires the publish permission for the collection (Statamic has no separate unpublish permission — the Control Panel gates both on publish), or 'publish other authors {collection} entries' for an entry you are not an author of when the blueprint has an author field. On revision-enabled collections this records an unpublish revision attributed to you; a staged working copy is applied to the entry and cleared, exactly like the Control Panel. An entry that is already a draft is a no-op.

Permanently delete an entry by id. When the blueprint has an author field, deleting an entry you are not an author of needs 'delete other authors {collection} entries'. Deleting an origin also deletes all of its localizations (this requires site access to every localization's site); the response lists everything that was removed. On revision-enabled collections the entry's revision and working-copy files stay on disk as orphans (the Control Panel behaves the same way). This cannot be undone.

List taxonomy terms with summary columns only (id, title, slug, url, updated_at) — never field data; use terms_get for a term's field data. Terms have no publish state, so there is no status filter. Paginated: the response carries total and next_page (null on the last page). Ordering is deterministic: alphabetical by title, with id as tiebreaker.

Get one taxonomy term by id ("{taxonomy}::{slug}") or by taxonomy + slug. format=raw (default) returns the round-trippable data shape for terms_update; format=augmented is read-only — never send augmented values back into terms_update. With site, data holds that site's local overrides and inherited holds what comes from the term's origin site (the taxonomy's first configured site — a term's localizations are data overrides within one term). Terms have no publish state, so there is no status. Large values are truncated to preview objects (Bard and Markdown over 500 bytes, any other value over 4 KB, a Grid excepted), and a large Replicator field to an index of its sets, unless requested via fields (an array of top-level field handles, or handle.id for one set, as in entries_get).

Create a taxonomy term from raw field data (get the shape from blueprints_get; never send augmented data). Slug is generated from data.title when omitted. A new Replicator or Grid set whose id is blank, 0, or shared with another new set gets a fresh id; terms_get shows the stored ids. Terms are created in the taxonomy's origin site (its first configured site) — localize afterwards with terms_update and its site parameter. Terms have no draft state: a created term is live immediately.

Update a taxonomy term with a shallow top-level-key merge of raw field data onto that site's local overrides (the terms_get raw shape) — nested structures are replaced wholesale; explicit null clears a field. A Replicator or Grid field takes an object keyed by set id that merges into just those sets, or a list of sets in their order where an item with a stored id merges into that set, and a Bard, Markdown, text, or textarea field takes {"find": "...", "replace": "..."} to change one piece of its text, as in entries_update. A new set whose id is blank, 0, or shared with another new set gets a fresh id; terms_get shows the stored ids. With site, writes that site's localized data override, creating it transparently on first write. slug renames the term: on the default site this changes the term id ("{taxonomy}::{slug}") and moves the yaml file; on other sites it stores a localized slug override. An update that changes nothing is a no-op. Terms have no draft state — changes are live immediately. Never send augmented data.

Permanently delete a taxonomy term by id. A term's site localizations are data overrides inside the term itself, so deleting it removes the term from every site at once. Deleting a term that entries still reference is allowed (Control Panel behavior); Statamic's reference updater then strips those references (runs on the queue; skipped when statamic.system.update_references is false). This cannot be undone. Only available when deletes are enabled in config/statamic/mcp.php.

Read global variables in the raw round-trippable shape for globals_update. Pass handle for one set, or omit it to get every set you can access (others are silently omitted). With site, data holds that site's localization; when the set localizes through an origin site, inherited holds the values falling back from it. Globals have no publish state — values are always live.

Update a global set's variables with a shallow top-level-key merge of raw data (the globals_get raw shape) — nested structures are replaced wholesale; explicit null clears a variable. A Replicator or Grid field takes an object keyed by set id that merges into just those sets, or a list of sets in their order where an item with a stored id merges into that set, and a Bard, Markdown, text, or textarea field takes {"find": "...", "replace": "..."} to change one piece of its text, as in entries_update. A new set whose id is blank, 0, or shared with another new set gets a fresh id; globals_get shows the stored ids. With site, writes that site's localization, creating it transparently on first write. An update that changes nothing is a no-op. Globals have no draft state: saved values are live immediately. Never send augmented data.

Read a navigation (a menu) for one site. tree is the raw shape navigations_update accepts: a list of branches {id, entry?, title?, url?, data?, children?}. An entry branch links an entry by id, and a title on it replaces the entry's title in the menu; a branch without an entry is a link (url, usually with a title) or a text item (title only). Entry branches also carry resolved {title, url, status}: the entry's current values, read-only and ignored by navigations_update. status 'missing' means the entry is deleted or not exposed to MCP, so it may be a live page: send the branch back unchanged unless the user asks to remove it. The response also holds what a write must respect: max_depth (null = unlimited), expects_root (the first branch is the root page and cannot have children), collections (the ones entry branches may link), and fields (the navigation blueprint's fields, which data is keyed by). blueprints_get with type navigation describes those fields in full: the sets of a Replicator or Bard field, each set's fields, and an example of a branch's data.

Replace a navigation's tree for one site with the complete tree you send, as the CP's tree save does: send every branch, in order, in the shape navigations_get returns. Keep id on existing branches; omit it on new ones and one is generated. An entry branch links an entry by id, which must exist in one of the navigation's collections, in the same site; an unexposed or deleted entry id the stored tree already links is kept as it is; a branch without an entry needs a url, a title, or both (a title alone is a text item). data takes the navigation blueprint's fields, validated and stored the way the CP stores them. resolved blocks from navigations_get are read-only and ignored. max_depth and the root rule (with expects_root, the first branch cannot have children) are enforced. An update that changes nothing is a no-op, and the result lists the ids of new branches under added. Navigations have no draft state: the saved tree is live immediately.

List assets in a container — summary columns only (path, url, is_image, size, dimensions, alt); use assets_get for full metadata. Optionally filter to a folder subtree. Paginated: the response carries total, total_pages, and next_page (null on the last page); ordered by path.

Read one asset's full detail: the assets_list summary columns plus raw blueprint data (alt text and custom fields — the shape assets_update accepts), mime_type, last_modified, and cp_edit_url. Raw values only, never augmented.

Upload a file into an asset container, from a source_url (the server downloads it — http/https, public hosts only) or inline content_base64 (small files only). filename is required with content_base64, optional with source_url (derived from the URL). Optional folder (e.g. "blog/2026") is created on demand. Existing paths are never overwritten — a collision is an error. Uploads are live immediately; set alt text afterwards with assets_update.

Update an asset's metadata (alt text and any custom fields on the container's asset blueprint) with a shallow top-level-key merge of raw data (the assets_get raw shape) — nested structures are replaced wholesale; explicit null clears a field. The file itself is untouched. An update that changes nothing is a no-op. Assets have no draft state: saved metadata is live immediately. Never send augmented data.

Permanently delete an asset — the file AND its metadata. References to it in entry fields are removed by Statamic's reference updater (runs on the queue; skipped when statamic.system.update_references is false). This cannot be undone. Only available when deletes are enabled in config/statamic/mcp.php.

List a form's submissions, newest first, each with its id, date, and full data keyed by field handle (blueprints_get with type form describes the fields; a field the visitor did not send is absent from data). search is the Control Panel's search: a substring match over the text, textarea, and integer fields, where % matches any run of characters and _ any single character, and over the date in its stored form, YYYY-MM-DD HH:MM:SS in UTC. To filter by date use since (inclusive) and before (exclusive) instead: a time without an offset is read in the server timezone from statamic_overview, and a date alone means midnight, so before 2026-09-27 covers everything up to the end of the 26th. Paginated: the response carries total and next_page (null on the last page). Submissions are not per site. Nothing edits a submission, as in the Control Panel; submissions_delete removes one when deletes are enabled.

Get one form submission by form handle and submission id (ids come from submissions_list or the Control Panel URL). Returns its date and full data keyed by field handle, plus cp_url. Nothing edits a submission, as in the Control Panel.

Permanently delete one form submission by form handle and submission id. Needs 'delete {form} form submissions', or 'configure forms'. Files the submission uploaded stay in their asset container, as when deleting in the Control Panel. This cannot be undone.