MCP tool reference
Every tool, prompt and resource the hosted MCP server (https://mcp.hypervalent.io) offers, generated from the server's tool catalog. See the AI assistants section for setup, authoring guidance, permissions and the error codes these tools answer with.
Every project-scoped tool takes an optional project argument: required for an organization-wide token (call list_projects first), implied by a project-scoped token. Answers are JSON; failures carry the API's { status, code, message }, a hint on writes, and requiredPlan when a plan upgrade would unlock the call.
Read tools
| Tool | Arguments | What it does |
|---|---|---|
list_projects | — | The projects this token can reach: every live project for an org-wide token, exactly its own for a project-scoped one. Call first when the token is org-wide. |
list_doctypes | project?: string — Project slug. Required for an org-wide token (see list_projects); implied by a project-scoped token.status?: published | draft — published (default) reads live content. draft reads the working view — every non-trashed item with its latest working version — and needs a read_write token on a plan with API writes. | Published document types in a project, each with its published-document count, the taxonomies it offers and the molecules it supports. status: "draft" lists draft document types too. |
get_doctype | project?: string — Project slug. Required for an org-wide token (see list_projects); implied by a project-scoped token.slug: string — Document type slug.status?: published | draft — published (default) reads live content. draft reads the working view — every non-trashed item with its latest working version — and needs a read_write token on a plan with API writes. | One document type as an authoring schema: its root-atom fields in editor order (key, field type, required, locked, default, config, showWhen), its root molecules (supports, by slug), the taxonomies it offers, every molecule a document's content tree may hold (each with its own fields and the molecules it may nest; root: true = allowed at the top level), and the exact payload shape create_document / update_document expect (content, blocks, terms). status: "draft" reads a draft document type too and adds its preset tree — read it this way before update_doctype. |
list_documents | project?: string — Project slug. Required for an org-wide token (see list_projects); implied by a project-scoped token.doctype: string — Document type slug.status?: published | draft — published (default) reads live content. draft reads the working view — every non-trashed item with its latest working version — and needs a read_write token on a plan with API writes.limit?: number — Page size (the API clamps to its maximum).page?: number — 1-based page number. | A page of a document type's documents — published by default, or the working view with status: "draft". Each entry carries its version content and projected root atoms. |
get_document | project?: string — Project slug. Required for an org-wide token (see list_projects); implied by a project-scoped token.doctype: string — Document type slug.slug: string — Document slug.status?: published | draft — published (default) reads live content. draft reads the working view — every non-trashed item with its latest working version — and needs a read_write token on a plan with API writes. | One document with its version content, root atoms, taxonomy terms and referenced images. status: "draft" reads the working version. |
search_documents | project?: string — Project slug. Required for an org-wide token (see list_projects); implied by a project-scoped token.query: string — Text to look for in title, slug or description.doctype?: string — Restrict to one document type slug; omitted = every document type.status?: published | draft — published (default) reads live content. draft reads the working view — every non-trashed item with its latest working version — and needs a read_write token on a plan with API writes.maxPages?: number — List pages to walk per document type (default 5, 100 documents each). | Case-insensitive match of a query against document titles, slugs and descriptions, across one document type or all of them. Walks the list pages client-side (there is no server-side search yet), so keep maxPages small on big projects; truncated: true in the answer means some pages were not scanned. |
list_taxonomies | project?: string — Project slug. Required for an org-wide token (see list_projects); implied by a project-scoped token.status?: published | draft — published (default) reads live content. draft reads the working view — every non-trashed item with its latest working version — and needs a read_write token on a plan with API writes. | Published taxonomies in a project with their term counts, the document types that offer them and their root-atom / molecule bindings (uuids). status: "draft" lists draft taxonomies too (each with status) — a draft taxonomy cannot be offered by a document type until it is published. |
get_taxonomy | project?: string — Project slug. Required for an org-wide token (see list_projects); implied by a project-scoped token.slug: string — Taxonomy slug.status?: published | draft — published (default) reads live content. draft reads the working view — every non-trashed item with its latest working version — and needs a read_write token on a plan with API writes.limit?: number — Page size (the API clamps to its maximum).page?: number — 1-based page number. | One taxonomy with its root-atom fields resolved by slug (what create_term / update_term take in content), its root molecules by slug (supports), the molecules a term's content tree may hold (what blocks takes — same shape as get_doctype) and a page of its terms. status: "draft" pages the working view of the terms (drafts included) and adds the taxonomy's preset tree — read it this way before update_taxonomy. |
get_term | project?: string — Project slug. Required for an org-wide token (see list_projects); implied by a project-scoped token.taxonomy: string — Taxonomy slug.slug: string — Term slug.status?: published | draft — published (default) reads live content. draft reads the working view — every non-trashed item with its latest working version — and needs a read_write token on a plan with API writes. | One taxonomy term with its version content. status: "draft" reads the working version. |
list_atoms | project?: string — Project slug. Required for an org-wide token (see list_projects); implied by a project-scoped token.status?: published | draft — published (default) reads live content. draft reads the working view — every non-trashed item with its latest working version — and needs a read_write token on a plan with API writes. | The project's atoms — the field definitions molecules and document types bind: slug, title, field type, category, multiple, config and default. status: "draft" includes drafts (each entry then carries status); only a published atom can be bound. An atom the project lacks may be ready-made: check list_library before create_atom. |
list_molecules | project?: string — Project slug. Required for an org-wide token (see list_projects); implied by a project-scoped token.status?: published | draft — published (default) reads live content. draft reads the working view — every non-trashed item with its latest working version — and needs a read_write token on a plan with API writes. | The project's molecules (reusable blocks), each by slug with its fields (the atoms it binds, in editor order, with required / locked / default / showWhen), supports (molecule slugs it may nest) and preset (the block tree a fresh use starts from) — the shape create_molecule / update_molecule take. status: "draft" includes drafts. A molecule the project lacks may be ready-made: check list_library before create_molecule. |
get_molecule | project?: string — Project slug. Required for an org-wide token (see list_projects); implied by a project-scoped token.slug: string — Molecule slug.status?: published | draft — published (default) reads live content. draft reads the working view — every non-trashed item with its latest working version — and needs a read_write token on a plan with API writes. | One molecule in the list_molecules shape. Read it with status: "draft" before update_molecule: fields, supports and preset are what that call replaces. |
list_library | project?: string — Project slug. Required for an org-wide token (see list_projects); implied by a project-scoped token.kind?: atom | molecule — Only this kind.group?: string — Only molecules of this group (primitives, sections, navigation); leaves atoms out.missingOnly?: boolean — Only items the project does not have yet. | The platform's catalogue of ready-made atoms and molecules, which list_atoms and list_molecules do not show until they are inserted. Each item says whether the project already has its slug (inProject, with projectStatus; a read token sees published rows only, so plan_library_insert is the final word on drafts). Molecules carry their group, their fields (the atoms they bind) and supports (the molecules they may nest). Check here before building an atom or molecule by hand, then use plan_library_insert and insert_library_items. |
plan_library_insert | project?: string — Project slug. Required for an org-wide token (see list_projects); implied by a project-scoped token.items: array — The items to bring in. A molecule brings every atom and child molecule it needs, so name only what you want. | A dry run of insert_library_items against the project; writes nothing. rows lists the item and its whole dependency closure, each with the action an insert would take: add; reuse (the slug exists, and the project's definition wins over the library's); or publish (the slug exists as a draft and would be published in place). Show this to the user before inserting. |
list_settings | project?: string — Project slug. Required for an org-wide token (see list_projects); implied by a project-scoped token. | The project's published General Settings — admin-defined config fields with their current values. |
get_design_tokens | project?: string — Project slug. Required for an org-wide token (see list_projects); implied by a project-scoped token.format?: json | tokens.json | css — json (default — the authoring list), tokens.json, or css. The filters and status apply to json only.type?: color | typography | radius | elevation | state | motion | font-family | component — Only tokens of this type (radius is shape).component?: string — Only the component tokens of this M3 component, e.g. switch, filled-button (comma-separate several).status?: published | draft — published (default) reads live content. draft reads the working view — every non-trashed item with its latest working version — and needs a read_write token on a plan with API writes. | The project's published design tokens (a Material 3 system: color roles and tonal palettes generated from the theme, typography, shape, elevation, state, motion, font-family sets and component tokens) — as the authoring list (default), the W3C tokens.json, or the CSS custom-property sheet. The list answers each token as { slug, title, type, values, … } where values is exactly what update_design_tokens takes: scheme slug → hex for a color role, tone → hex for a palette, default → the value for every other type (a typography composite, a component's { ref } or { value }). Filter with type / component; status: "draft" adds the unpublished component tokens. |
get_design_theme | project?: string — Project slug. Required for an org-wide token (see list_projects); implied by a project-scoped token. | The theme the color system is generated from: the source color, the M3 scheme variant and the optional secondary / tertiary / neutral key colors, plus the variants update_design_theme accepts. |
Write tools (read_write token + API writes on the plan)
| Tool | Arguments | Annotations | What it does |
|---|---|---|---|
create_document | project?: string — Project slug. Required for an org-wide token (see list_projects); implied by a project-scoped token.doctype: string — Document type slug.title: string — Document title.slug?: string — Document slug; omit to derive from the title.description?: string — Short description / summary.content?: object — Root-atom values keyed by FIELD SLUG (the slug of each field in get_doctype — or its uuid). The server maps slugs to the API's root-atom uuids; unknown slugs are refused with the allowed list. An image field takes the image UUID(s) from upload_media (as an array), never a URL; a file field takes file UUID(s) from upload_media the same way (an external URL it already holds must be resent to keep it); a video field takes video UUID(s) from upload_media and/or external http(s) video URLs (YouTube, Vimeo). A uuid of the wrong kind (a file in an image or video field) is dropped silently. Link fields take a string (an array of strings when the field is multiple): an http(s) or protocol-relative URL, a path (/about, docs/intro), a query string (?ref=x), a fragment (#team), or a mailto: / tel: link; a value with any other scheme (javascript:, data:) is refused on save — a single link is saved as '', a refused entry of a multiple link is removed.blocks?: array — The molecule content tree (blocks), by molecule and field slug. REPLACES the whole tree when given — read the draft first and resend every block to keep (with its key); omit to leave the tree untouched. Separate from content, which holds the root-atom fields.terms?: object — Taxonomy terms to tag, keyed by TAXONOMY SLUG → array of term slugs (or uuids). Draft and published terms of that taxonomy both work. | — | Create a DRAFT document of a document type. Nothing is public until publish_document. content takes root-atom field values by slug and blocks the molecule content tree by molecule / field slug (see get_doctype); terms tags taxonomy terms by slug. The slug defaults to the slugified title, made unique. Answers the draft in the get_document shape. |
update_document | project?: string — Project slug. Required for an org-wide token (see list_projects); implied by a project-scoped token.doctype: string — Document type slug.slug: string — Document slug.title?: stringnewSlug?: string — Rename the document slug.description?: string — Short description / summary.content?: object — Root-atom values keyed by FIELD SLUG (the slug of each field in get_doctype — or its uuid). The server maps slugs to the API's root-atom uuids; unknown slugs are refused with the allowed list. An image field takes the image UUID(s) from upload_media (as an array), never a URL; a file field takes file UUID(s) from upload_media the same way (an external URL it already holds must be resent to keep it); a video field takes video UUID(s) from upload_media and/or external http(s) video URLs (YouTube, Vimeo). A uuid of the wrong kind (a file in an image or video field) is dropped silently. Link fields take a string (an array of strings when the field is multiple): an http(s) or protocol-relative URL, a path (/about, docs/intro), a query string (?ref=x), a fragment (#team), or a mailto: / tel: link; a value with any other scheme (javascript:, data:) is refused on save — a single link is saved as '', a refused entry of a multiple link is removed.blocks?: array — The molecule content tree (blocks), by molecule and field slug. REPLACES the whole tree when given — read the draft first and resend every block to keep (with its key); omit to leave the tree untouched. Separate from content, which holds the root-atom fields.terms?: object — Taxonomy terms to tag, keyed by TAXONOMY SLUG → array of term slugs (or uuids). Draft and published terms of that taxonomy both work. | — | Edit the WORKING version of a document (draft or published). content REPLACES the whole set of root-atom values and blocks the whole molecule content tree — read the document first (get_document with status "draft") and send every field and block you want kept (blocks with their key); omit either to leave it untouched. terms replaces the tag set when given. If an editor holds the document open, the save is refused with the holder's name — retry later. A published document gets a new draft version; the live page is unchanged until publish_document. Not safe to retry blindly when newSlug is used. |
publish_document | project?: string — Project slug. Required for an org-wide token (see list_projects); implied by a project-scoped token.doctype: string — Document type slug.slug: string — Document slug. | idempotent, affects live sites | Publish the working version. The document becomes visible IMMEDIATELY on the public read API and on every site consuming it (its title, description, field values, content tree and tagged terms). Idempotent: an already-published working version is left alone. |
unpublish_document | project?: string — Project slug. Required for an org-wide token (see list_projects); implied by a project-scoped token.doctype: string — Document type slug.slug: string — Document slug. | destructive, idempotent, affects live sites | Take a document off the public read API — it goes back to draft and disappears from every consuming site at once. Published versions are kept; publish_document restores it. |
trash_document | project?: string — Project slug. Required for an org-wide token (see list_projects); implied by a project-scoped token.doctype: string — Document type slug.slug: string — Document slug. | destructive, affects live sites | Move a document to the trash. It leaves the public read API immediately, its slug is freed (a retry answers 404), and there is NO restore through this server (an editor can restore it in Studio). Confirm with the user before calling. |
create_term | project?: string — Project slug. Required for an org-wide token (see list_projects); implied by a project-scoped token.taxonomy: string — Taxonomy slug.title: string — Term title.slug?: stringdescription?: string — Short description / summary.parent?: string — Parent term slug (omit for top level).content?: object — Root-atom values keyed by FIELD SLUG (the slug of each field in get_doctype — or its uuid). The server maps slugs to the API's root-atom uuids; unknown slugs are refused with the allowed list. An image field takes the image UUID(s) from upload_media (as an array), never a URL; a file field takes file UUID(s) from upload_media the same way (an external URL it already holds must be resent to keep it); a video field takes video UUID(s) from upload_media and/or external http(s) video URLs (YouTube, Vimeo). A uuid of the wrong kind (a file in an image or video field) is dropped silently. Link fields take a string (an array of strings when the field is multiple): an http(s) or protocol-relative URL, a path (/about, docs/intro), a query string (?ref=x), a fragment (#team), or a mailto: / tel: link; a value with any other scheme (javascript:, data:) is refused on save — a single link is saved as '', a refused entry of a multiple link is removed.blocks?: array — The molecule content tree (blocks), by molecule and field slug. REPLACES the whole tree when given — read the draft first and resend every block to keep (with its key); omit to leave the tree untouched. Separate from content, which holds the root-atom fields. | — | Create a DRAFT term in a taxonomy, optionally under a parent term. content takes the taxonomy's root-atom values by slug; blocks its molecule content tree (see get_taxonomy). |
update_term | project?: string — Project slug. Required for an org-wide token (see list_projects); implied by a project-scoped token.taxonomy: string — Taxonomy slug.slug: string — Term slug.title?: stringnewSlug?: stringdescription?: string — Short description / summary.parent?: string | null — Parent term slug; null makes the term top-level.content?: object — Root-atom values keyed by FIELD SLUG (the slug of each field in get_doctype — or its uuid). The server maps slugs to the API's root-atom uuids; unknown slugs are refused with the allowed list. An image field takes the image UUID(s) from upload_media (as an array), never a URL; a file field takes file UUID(s) from upload_media the same way (an external URL it already holds must be resent to keep it); a video field takes video UUID(s) from upload_media and/or external http(s) video URLs (YouTube, Vimeo). A uuid of the wrong kind (a file in an image or video field) is dropped silently. Link fields take a string (an array of strings when the field is multiple): an http(s) or protocol-relative URL, a path (/about, docs/intro), a query string (?ref=x), a fragment (#team), or a mailto: / tel: link; a value with any other scheme (javascript:, data:) is refused on save — a single link is saved as '', a refused entry of a multiple link is removed.blocks?: array — The molecule content tree (blocks), by molecule and field slug. REPLACES the whole tree when given — read the draft first and resend every block to keep (with its key); omit to leave the tree untouched. Separate from content, which holds the root-atom fields. | — | Edit the working version of a term: title, slug, description, parent (null = make top level), root-atom values by slug (content replaces the whole set) and the molecule content tree (blocks replaces the whole tree; resend each kept block with its key). Refused with the holder's name if an editor has it open. |
publish_term | project?: string — Project slug. Required for an org-wide token (see list_projects); implied by a project-scoped token.taxonomy: string — Taxonomy slug.slug: string — Term slug. | idempotent, affects live sites | Publish a term's working version. The term becomes visible IMMEDIATELY on the public read API and inside every published document tagged with it, on every site consuming them. Idempotent: an already-published working version is left alone. Refused with the holder's name if an editor has it open. |
unpublish_term | project?: string — Project slug. Required for an org-wide token (see list_projects); implied by a project-scoped token.taxonomy: string — Taxonomy slug.slug: string — Term slug. | destructive, idempotent, affects live sites | Take a term off the public read API — it goes back to draft. Refused (CANNOT_DRAFT_IN_USE) while any document is tagged with it: untag those documents first. publish_term restores it. |
trash_term | project?: string — Project slug. Required for an org-wide token (see list_projects); implied by a project-scoped token.taxonomy: string — Taxonomy slug.slug: string — Term slug. | destructive, affects live sites | Move a term to the trash. It leaves the public read API immediately, its slug is freed (a retry answers 404), and there is NO restore through this server (an editor can restore it in Studio). Refused (CANNOT_TRASH_IN_USE) while any document is tagged with it. Child terms keep their now-trashed parent — re-parent them first (update_term parent). Confirm with the user before calling. |
upload_media | project?: string — Project slug. Required for an org-wide token (see list_projects); implied by a project-scoped token.url?: string — Public http(s) URL of the image, file or video.data?: string — Base64-encoded image, file or video bytes (use with filename). The whole call must fit in 1 MB (about 700 KB of file); use url for anything larger.filename?: string — File name for base64 data, e.g. hero.png or price-list.pdf (a .csv name marks plain text as CSV).title?: stringalt?: string — Alt text (images only). | idempotent, affects live sites | Store an image, a file (PDF, Word/Excel/PowerPoint, zip, CSV, plain text) or a video (MP4, WebM, MOV — the API caps videos at 30 MiB unless the deploy changes it) in the project's media library from a public URL (fetched server-side; private/internal addresses are refused) or from base64 data + a filename. A tool call is capped at 1 MB, so base64 data only carries files up to about 700 KB — pass a url for videos and other larger media. Answers the stored media: its uuid is what an image field (images only), a file field or a video field (videos only) takes in create_document / update_document (as [uuid]); cdnUrl is the public address. Identical bytes dedupe to the existing media. A YouTube or Vimeo link needs no upload — a video field takes the URL itself. |
insert_library_items | project?: string — Project slug. Required for an org-wide token (see list_projects); implied by a project-scoped token.items: array — The items to bring in. A molecule brings every atom and child molecule it needs, so name only what you want. | idempotent, affects live sites | Bring ready-made atoms and molecules from list_library into the project, with every atom and child molecule they need, in one all-or-nothing transaction. Inserted items are PUBLISHED IMMEDIATELY, so they can be bound at once and are served by the public read API. An existing slug is reused, NOT overwritten: the project's definition wins, and a matching draft is published in place. Calling it again changes nothing. Run plan_library_insert first and confirm with the user. Answers each row's action and uuid. |
create_atom | project?: string — Project slug. Required for an org-wide token (see list_projects); implied by a project-scoped token.slug?: string — Slug; omit to derive a unique one from the title.title: stringdescription?: string — Short description / summary.icon?: string — Material Design Icons name, e.g. mdi-text.category?: content | media | style — Editor layout: style atoms edit in the side rail, content (default) / media in the canvas.fieldType: text | textarea | html | markdown | number | color | image | select | range | spacing | date | boolean | icon | link | video | file | email | tel | slug — The field type.multiple?: boolean — An array of values instead of one (image, file and video values are arrays either way).config?: object — Field config — only the keys the type reads: select options (required; [{ value, text?, selected? }] or strings); number / range min, max, step; html toolbar (switches such as bold, italic, bulletList, link, headings: [2, 3]); image dragDropEnabled; image / file / video maxFileSizeBytes. Any other key is refused.default?: any — Default value, in the field's shape: a string for text-like types; a number for number / range; true / false; one of the option values for select; { top?, right?, bottom?, left? } pixel numbers for spacing; an array of media uuids for image / file / video; an array of those when multiple. On update, null clears it.status?: draft | published — draft (the default on create) or published. Only a PUBLISHED atom can be bound into a molecule, document type or taxonomy, only a published molecule supported by another, and only a published taxonomy offered by a document type; a published structure is served by the public read API. Unpublishing one that is in use is refused (CANNOT_DRAFT_IN_USE). Confirm with the user before publishing or unpublishing. | — | Create an atom — a field definition (field type + config + default) that molecules and document types bind. Check list_library first: a ready-made atom saves building one, and a hand-built near-copy under another slug gets a second copy on a later library insert. A DRAFT unless status: "published"; it must be published before create_molecule / create_doctype can use it. The API refuses config keys the field type does not read and defaults that do not fit the field, listing every problem in issues. |
update_atom | project?: string — Project slug. Required for an org-wide token (see list_projects); implied by a project-scoped token.slug: string — Atom slug.newSlug?: string — Rename the slug.title?: stringdescription?: string — Short description / summary.icon?: string — Material Design Icons name, e.g. mdi-text.category?: content | media | style — Editor layout: style atoms edit in the side rail, content (default) / media in the canvas.fieldType?: text | textarea | html | markdown | number | color | image | select | range | spacing | date | boolean | icon | link | video | file | email | tel | slug — The field type.multiple?: boolean — An array of values instead of one (image, file and video values are arrays either way).config?: object — Field config — only the keys the type reads: select options (required; [{ value, text?, selected? }] or strings); number / range min, max, step; html toolbar (switches such as bold, italic, bulletList, link, headings: [2, 3]); image dragDropEnabled; image / file / video maxFileSizeBytes. Any other key is refused.default?: any — Default value, in the field's shape: a string for text-like types; a number for number / range; true / false; one of the option values for select; { top?, right?, bottom?, left? } pixel numbers for spacing; an array of media uuids for image / file / video; an array of those when multiple. On update, null clears it.status?: draft | published — draft (the default on create) or published. Only a PUBLISHED atom can be bound into a molecule, document type or taxonomy, only a published molecule supported by another, and only a published taxonomy offered by a document type; a published structure is served by the public read API. Unpublishing one that is in use is refused (CANNOT_DRAFT_IN_USE). Confirm with the user before publishing or unpublishing. | — | Edit an atom (draft or published). Every argument is optional; omitted ones are left alone. While the atom is bound anywhere its fieldType and multiple cannot change (stored values depend on them); a new field type re-checks the stored config and default — resend them if they no longer fit. |
create_molecule | project?: string — Project slug. Required for an org-wide token (see list_projects); implied by a project-scoped token.title: stringslug?: string — Slug; omit to derive a unique one from the title.description?: string — Short description / summary.icon?: string — Material Design Icons name, e.g. mdi-text.fields?: array — The atoms this structure binds, in editor order. REPLACES the whole list on update — read it first and resend every field to keep.supports?: array — Molecule SLUGS that may be inserted here (published molecules). REPLACES the list on update.preset?: array — The preset block tree a fresh use starts from (same shape as create_document blocks; top-level blocks must be molecules in supports). REPLACES the stored preset on update.status?: draft | published — draft (the default on create) or published. Only a PUBLISHED atom can be bound into a molecule, document type or taxonomy, only a published molecule supported by another, and only a published taxonomy offered by a document type; a published structure is served by the public read API. Unpublishing one that is in use is refused (CANNOT_DRAFT_IN_USE). Confirm with the user before publishing or unpublishing. | — | Create a molecule — a reusable block: the atoms it binds (fields, by atom slug), the molecules it may nest (supports, by slug) and its optional preset tree. Check list_library first: insert_library_items brings a ready-made molecule and everything it needs in one step. Every atom and molecule it names must be published. A DRAFT unless status: "published"; it must be published before a document type or another molecule can support it. |
update_molecule | project?: string — Project slug. Required for an org-wide token (see list_projects); implied by a project-scoped token.slug: string — Molecule slug.title?: stringnewSlug?: string — Rename the slug.description?: string — Short description / summary.icon?: string — Material Design Icons name, e.g. mdi-text.fields?: array — The atoms this structure binds, in editor order. REPLACES the whole list on update — read it first and resend every field to keep.supports?: array — Molecule SLUGS that may be inserted here (published molecules). REPLACES the list on update.preset?: array — The preset block tree a fresh use starts from (same shape as create_document blocks; top-level blocks must be molecules in supports). REPLACES the stored preset on update.status?: draft | published — draft (the default on create) or published. Only a PUBLISHED atom can be bound into a molecule, document type or taxonomy, only a published molecule supported by another, and only a published taxonomy offered by a document type; a published structure is served by the public read API. Unpublishing one that is in use is refused (CANNOT_DRAFT_IN_USE). Confirm with the user before publishing or unpublishing. | — | Edit a molecule (draft or published). fields, supports and preset each REPLACE what is stored when given — read it first (get_molecule with status "draft") and resend everything to keep; omit one to leave it alone. Documents already using the molecule keep their stored values. |
create_doctype | project?: string — Project slug. Required for an org-wide token (see list_projects); implied by a project-scoped token.title: stringtitlePlural?: stringslug?: string — Slug; omit to derive a unique one from the title.description?: string — Short description / summary.icon?: string — Material Design Icons name, e.g. mdi-text.versioning?: boolean — Keep a version history of every document (default true).fields?: array — The atoms this structure binds, in editor order. REPLACES the whole list on update — read it first and resend every field to keep.supports?: array — Molecule SLUGS that may be inserted here (published molecules). REPLACES the list on update.taxonomies?: array — Taxonomy SLUGS documents may be tagged in (published taxonomies — see list_taxonomies, create_taxonomy). REPLACES the list on update.preset?: array — The preset block tree a fresh use starts from (same shape as create_document blocks; top-level blocks must be molecules in supports). REPLACES the stored preset on update.status?: draft | published — draft (the default on create) or published. Only a PUBLISHED atom can be bound into a molecule, document type or taxonomy, only a published molecule supported by another, and only a published taxonomy offered by a document type; a published structure is served by the public read API. Unpublishing one that is in use is refused (CANNOT_DRAFT_IN_USE). Confirm with the user before publishing or unpublishing. | — | Create a document type — a content blueprint: its root fields (fields, by atom slug), the molecules its content tree may hold at the top level (supports), the taxonomies it offers (taxonomies, by slug) and an optional preset tree every new document starts from. Every atom, molecule and taxonomy it names must be published. The plan caps how many document types an organization may have. A DRAFT unless status: "published"; create_document works under a draft document type too. |
create_taxonomy | project?: string — Project slug. Required for an org-wide token (see list_projects); implied by a project-scoped token.title: string — Singular name, e.g. Topic.titlePlural?: string — Plural name, e.g. Topics.slug?: string — Slug; omit to derive a unique one from the title.description?: string — Short description / summary.icon?: string — Material Design Icons name, e.g. mdi-text.versioning?: boolean — Keep a version history of every term (default true).fields?: array — The atoms this structure binds, in editor order. REPLACES the whole list on update — read it first and resend every field to keep.supports?: array — Molecule SLUGS that may be inserted here (published molecules). REPLACES the list on update.preset?: array — The preset block tree a fresh use starts from (same shape as create_document blocks; top-level blocks must be molecules in supports). REPLACES the stored preset on update.status?: draft | published — draft (the default on create) or published. Only a PUBLISHED atom can be bound into a molecule, document type or taxonomy, only a published molecule supported by another, and only a published taxonomy offered by a document type; a published structure is served by the public read API. Unpublishing one that is in use is refused (CANNOT_DRAFT_IN_USE). Confirm with the user before publishing or unpublishing. | — | Create a taxonomy — a term blueprint: its root fields (fields, by atom slug — what every term's content holds), the molecules a term's content tree may hold at the top level (supports) and an optional preset tree every new term starts from. Every atom and molecule it names must be published. The plan caps how many taxonomies an organization may have. A DRAFT unless status: "published"; create_term works under a draft taxonomy, but a document type can offer only a published one (then add it with update_doctype taxonomies). |
update_taxonomy | project?: string — Project slug. Required for an org-wide token (see list_projects); implied by a project-scoped token.slug: string — Taxonomy slug.title?: stringtitlePlural?: stringnewSlug?: string — Rename the slug.description?: string — Short description / summary.icon?: string — Material Design Icons name, e.g. mdi-text.versioning?: booleanfields?: array — The atoms this structure binds, in editor order. REPLACES the whole list on update — read it first and resend every field to keep.supports?: array — Molecule SLUGS that may be inserted here (published molecules). REPLACES the list on update.preset?: array — The preset block tree a fresh use starts from (same shape as create_document blocks; top-level blocks must be molecules in supports). REPLACES the stored preset on update.status?: draft | published — draft (the default on create) or published. Only a PUBLISHED atom can be bound into a molecule, document type or taxonomy, only a published molecule supported by another, and only a published taxonomy offered by a document type; a published structure is served by the public read API. Unpublishing one that is in use is refused (CANNOT_DRAFT_IN_USE). Confirm with the user before publishing or unpublishing. | — | Edit a taxonomy (draft or published). fields, supports and preset each REPLACE what is stored when given — read it first (get_taxonomy with status "draft") and resend everything to keep. Existing terms keep their stored values; a field removed from fields drops out of their reads. Unpublishing a taxonomy that a document type offers or that has live terms is refused (CANNOT_DRAFT_IN_USE). Which document types offer it is set on the document type (update_doctype taxonomies). |
update_doctype | project?: string — Project slug. Required for an org-wide token (see list_projects); implied by a project-scoped token.slug: string — Document type slug.title?: stringtitlePlural?: stringnewSlug?: string — Rename the slug.description?: string — Short description / summary.icon?: string — Material Design Icons name, e.g. mdi-text.versioning?: booleanfields?: array — The atoms this structure binds, in editor order. REPLACES the whole list on update — read it first and resend every field to keep.supports?: array — Molecule SLUGS that may be inserted here (published molecules). REPLACES the list on update.taxonomies?: array — Taxonomy SLUGS. REPLACES the list.preset?: array — The preset block tree a fresh use starts from (same shape as create_document blocks; top-level blocks must be molecules in supports). REPLACES the stored preset on update.status?: draft | published — draft (the default on create) or published. Only a PUBLISHED atom can be bound into a molecule, document type or taxonomy, only a published molecule supported by another, and only a published taxonomy offered by a document type; a published structure is served by the public read API. Unpublishing one that is in use is refused (CANNOT_DRAFT_IN_USE). Confirm with the user before publishing or unpublishing. | — | Edit a document type (draft or published). fields, supports, taxonomies and preset each REPLACE what is stored when given — read it first (get_doctype with status "draft") and resend everything to keep. Existing documents keep their stored values; a field removed from fields drops out of their reads. Unpublishing a document type that documents use is refused. |
update_design_theme | project?: string — Project slug. Required for an org-wide token (see list_projects); implied by a project-scoped token.sourceColor?: string — #RRGGBB.variant?: string — M3 scheme variant — one of the variants get_design_theme lists (tonalSpot, vibrant, expressive, … ; default tonalSpot). The API refuses any other.secondaryColor?: string | null — #RRGGBB, or null to derive it from the source again.tertiaryColor?: string | null — #RRGGBB, or null to derive it from the source again.neutralColor?: string | null — #RRGGBB, or null to derive it from the source again. | idempotent, affects live sites | Change the theme and regenerate every tonal palette and color role from it (Studio's "Save & regenerate"): sourceColor drives the whole system; variant picks the M3 scheme style; the optional key colors pin the secondary / tertiary / neutral palettes (null clears one). Color tokens marked manual keep their values. Changes the LIVE CSS / JSON export immediately — confirm with the user first. |
update_design_tokens | project?: string — Project slug. Required for an org-wide token (see list_projects); implied by a project-scoped token.tokens: array — The edits, one per token slug. | idempotent, affects live sites | Edit up to 200 existing design tokens in one all-or-nothing call: their values, their status (how a component is enabled in the export) or a color's valueSource. Read them first with get_design_tokens (status: "draft" to see unpublished component tokens) and send only what changes. Every problem is reported at once in issues by path and nothing is written until all pass. Edits to published tokens change the LIVE CSS / JSON export immediately — confirm with the user first. |
Prompts
| Prompt | Arguments | What it does |
|---|---|---|
draft-document | project?: string — Project slug. Required for an org-wide token (see list_projects); implied by a project-scoped token.doctype: string — Document type slug. | Interview the user for each required field of a document type, then create the draft (never publishes on its own). |
content-audit | project?: string — Project slug. Required for an org-wide token (see list_projects); implied by a project-scoped token.days?: string — Age threshold for stale drafts, in days (default 30).taxonomy?: string — Taxonomy slug every published document should be tagged in.term?: string — A specific term slug to require (omit = any term of the taxonomy). | List drafts older than N days and published documents missing a given taxonomy term. |
Resources
| URI template | What it serves |
|---|---|
hypervalent://{project}/doctypes/{slug} | A document type as its authoring schema (same body as get_doctype). (application/json) |
hypervalent://{project}/documents/{doctype}/{slug} | A published document with its content (same body as get_document). (application/json) |