Tools reference

Report the resolved operating context: GraphQL endpoint, organization_id, store_id, store slug/name, the theme_id you are editing, WHETHER THAT THEME IS THE ONE THE STOREFRONT SERVES, and commerce_enabled. High-level tools auto-fill these; use this to learn the values for raw GraphQL.

Run a raw GraphQL MUTATION against the store. LAST-RESORT escape hatch ONLY for writes with NO dedicated tool. For pages use create_page/update_page/update_page_sections/publish_page; theme files use upsert_theme_file; content use create_content_type/create_content_record; products use create_product; menus use create_menu; publish uses publish_draft_theme. Those apply required contracts + defaults that a raw mutation skips. Remember store/org-scoped mutations need organization_id/store_id — call get_context to fetch them.

Run a raw GraphQL QUERY against the store. Escape hatch for anything not covered by a high-level tool. The API key's org scopes apply. Returns the `data` object.

Discover the GraphQL schema. With type_name, returns that type's fields and their argument/field types (use 'Query' or 'Mutation' to list all operations, or an input type to learn its shape). Without it, lists all type names.

List the shop's products (paged, searched and sorted in SQL). Use it to check what already exists before creating more, and to read back ids for an update. Search is diacritic-insensitive.

Create or update a COLLECTION — a group of products defined by CONDITIONS, not by a list of ids, published at /collections/<slug>. 'everything under 500,000' stays true by itself as the merchant adds products, which a hand-picked list cannot. Conditions use the platform's filter grammar: match all|any over rules of field/op/value.

Create (omit id) or update (set id) a record of a content type. Field values go in `values` keyed by field code.

Define a custom content type (e.g. houses, menu_items, projects) with typed fields. EAV-backed, no new tables. Records render on the storefront via the `content` Liquid Drop and the url_pattern router.

Delete one record. The type, its fields and its sections stay — only this entry goes.

Delete a content type and every record filed under it. Requires confirm:true. Use it to clear a type an earlier build left behind — a type whose records nothing links to is invisible content, and leaving it means the site carries data no visitor can reach.

List records of a content type with optional search, facet filters, sort, and pagination. Filtering/search/sort run server-side over the full set, then the page is returned. Mirrors the storefront content-list (which a theme drives via ?q=/?<field>=/?sort=/?per_page= URL params). Returns { data, total (after filter), total_all, page, per_page }.

List the org's content types and their fields.

Give a content type the LIST surface that makes its route render: a listing section built from the type's real fields plus the template that mounts it. A type with records and no template shows NOTHING — its route answers, and the page is empty. Idempotent: it never overwrites a section a design pass already wrote.

Rename a content type or change where its detail pages live (label, singular, url_pattern, template, icon). Only what you send changes. ⚠️ FIELDS are not edited here: the type's columns are decided once, from the design, and re-deciding them downstream is how a site ends up with two names for one thing.

Generate a customizer-editable Liquid section (body + complete {% schema %}) from a spec and write it to sections/<handle>.liquid. Always ships a preset so it shows in the 'add section' picker. After this, call set_section_settings to place it on a page template.

Purge the storefront edge/Redis cache so theme/product edits show immediately. (Requires a key with settings/full-access scope.)

Create a short-lived preview token to view a theme (e.g. a draft) on the storefront without publishing.

Open a theme for editing — returns or lazily creates an unpublished draft clone you can safely edit before publishing.

Read a single theme file's content by path.

List the Liquid objects, per-template context variables, the dynamic `content` Drop, and custom filters the storefront exposes to theme sections. Use this BEFORE writing a section so you reference real variables (e.g. product.url_key, collection.products, content.<type>) instead of guessing.

List theme files (path + content_type + source), optionally filtered by path prefix.

Publish the theme: what you have been editing becomes what visitors get. A draft (unpublished) theme is also promoted to live (role=main). Publishing the theme you are already on is NOT a no-op — every write lands on the theme's DRAFT surface, which the storefront does not serve until you publish.

Restore the theme to a snapshot taken by snapshot_theme: every file AND settings_data revert to exactly that checkpoint (files added since are deleted).

Merge global theme palette/typography/spacing into settings_data (CSS variables). Reads current settings_data, merges the given top-level keys (never clobbering the nested `sections` map), and writes it back.

Add or update a section instance on a page template (templates/<template>.json), setting its per-section settings/blocks and order. Reads the current template (inherited if the store has none), merges, and writes it back. ⚠️ CHROME sections (web-header / web-footer / announcement-bar) are LAYOUT-rendered, not template-placed: pass template:"layout" with their type and this writes the instance into the theme's settings_data.sections map — this is THE way to seed the header nav menu items (blocks: link + nested dropdown entries with real /pages/<slug> urls).

Capture an immutable checkpoint of the theme (every file + settings_data) into theme_versions. Returns the version id to restore later.

Add or update ONE section on a CMS page, INCREMENTALLY (store_pages.sections_data) — the page-record twin of set_section_settings. Reads the page's current sections, merges this one in (settings per-field: keys you don't pass are preserved; blocks replaced only when given), updates the render order, validates, and writes it back (auto-republishing a live page). Use it to build a CMS page SECTION-BY-SECTION so the user watches it fill in: create_page (empty) FIRST, then call this once per section, top to bottom — instead of dumping the whole page at once. Returns the page's storefront `path` so the preview follows to it.

Create or replace a theme file. Writes are validated against the platform design contract and REJECTED on violation: layout/theme.liquid must load assets/theme.js, render content_for_layout/content_for_header, AND carry the <style id="theme-settings-vars"> block (the customizer Theme-settings panel's canonical color_*/font_* keys only apply through it); sections/*.liquid need one complete {% schema %} whose settings include the canonical Style group (visible, bg_color, text_color, heading_color, padding_top/bottom, border_color/width/radius) and whose ids are referenced in the body; templates/*.json must be well-formed and only place existing section types. Error messages include the exact fix.

Publish an article on the store's own blog (posts, categories, tags, authors, permalinks and archives are a PLATFORM surface — never build a content type for articles). Give it the whole body as HTML; the platform mints the slug, the permalink and the taxonomy from the names you pass. Use update_blog_post to change one afterwards.

Create a CMS page (default type 'custom'). store_id is auto-filled. Pass `sections` (page-builder document — THE standard for designed pages, visually editable afterwards) or `body` (prose HTML, text-only pages). Without either the page is BLANK. Publish it with publish_page.

Delete one post permanently. Its categories, tags and author stay — they belong to the blog, not to the post.

Delete a blog category, tag or author. The posts filed under it stay published; they simply lose that term.

PERMANENTLY delete a CMS page (e.g. an accidental duplicate). Find the id with list_pages first; double-check it's the right page — this cannot be undone.

Read whether this site has a blog and the permalink grammar it serves — the post prefix and the category/tag/author bases. Every blog URL is built from these, so read them instead of assembling a path by hand.

List the store's posts with their ids, permalinks, status and taxonomy — the way to find a post before updating or deleting it, and to check what is already published before writing more.

List the blog's categories, tags or authors with their ids, slugs, post counts and archive URLs — read this before naming a term, so a menu links a shelf that exists rather than a slug someone guessed.

List the store's CMS pages (id, title, slug, type, status, content mode). ALWAYS check here before create_page — creating an existing slug mints a -2 duplicate.

Publish a CMS page so it's live on the storefront.

Change an existing post. Only the fields you send are written — everything else is kept, so you can fix a title or add a body without re-sending the article. Supplying category_names or tag_names REPLACES that axis.

Turn the blog on, or change its permalink grammar (post prefix, category/tag/author bases) and its WordPress REST access. Changing a prefix keeps the old one working: the platform 301s every old address. Only the fields you send change.

Update an existing CMS page: title/slug/meta, and its CONTENT — `sections` (page-builder document, the standard for designed pages) or `body` (prose HTML, text-only pages). Use this instead of re-creating a page.

Create or edit a blog CATEGORY, TAG or AUTHOR. Omit the id to create. An update keeps every field you do not send — so an author can be given a bio without losing their name. Categories classify a post; tags refine it; never use the same word for both.

Get the store's default language + the full set of languages the storefront serves (supported_locales). The default is served at the root URL; others at /<locale>/.

List existing translation overrides for a language (optionally filtered by resource type). Returns rows of {resource_type, resource_id, field, value}.

Set which languages the storefront serves (supported_locales on the store). Include the default locale. After this, translate content with upsert_translations and the storefront serves each non-default language at /<locale>/.

Write per-language translation overrides into the content_translations overlay. The default-language record is never changed — only the given language. An empty value removes an override. The storefront serves it at /<locale>/. Enable the language first with set_languages.

Search Pexels for real, royalty-free stock photos and return candidate image URLs. This is the DEFAULT image source for every slot — hero/section/blog/content photos. Pick the best-matching candidate URL and write it straight into the image setting; the server automatically re-hosts it into the store's media library (never hotlinked, no upload_image needed).

Upload an image (from a local file PATH or a remote URL) to the store's media library and return the hosted URL. Use this for ANY image — content-record galleries, section backgrounds, page OG images, blog featured/inline images — then pass the returned url into the matching field (a gallery value, a section image_picker, featured_image_url, etc.).

Load the full content of one shop skill (a build/redesign playbook) by name. Read shop-core-rules first — the other skills reference its §A–§I anchors.

List the available shop build/redesign skills (reusable playbooks) with a one-line description each. Call get_skill to load a full playbook before doing that kind of work.

Attach a hostname the MERCHANT owns to this backend, e.g. api.their-brand.com. Same DNS proof and TLS path a website domain takes — one implementation, two screens. It comes back `pending`: tell the merchant to add EITHER the CNAME (name = the hostname, target = `cname_target`) OR the TXT record (`txt_record_name` = `txt_record_value`) — one is enough, and the TXT is the only one that works behind Cloudflare's orange cloud, which rewrites the CNAME. Read those three values off the tool's reply; never compose them, they must match the verifier byte for byte. Then call verify_backend_api_domain. A hostname already serving their WEBSITE is refused rather than re-pointed — that would take a live site down.

VERIFY every internal link on ONE storefront page resolves (no 404s) — the core-rules §E acceptance check. Fetches the page, follows each internal href, returns the broken ones. Run it on EVERY page you created/changed and once on the homepage at the end; a page is NOT done while this returns broken links.

Set which OFFLINE payment methods the checkout offers (cash on delivery, bank transfer) and the transfer details. There is no online gateway on this platform — do not promise one in the site's copy.

Mint a key for THIS backend and return it ONCE — the plaintext is in `token`. Needed to call an api_key route for real, which is the only way to verify one works — publishing proves a graph is well formed, not that it does the right thing. These are bbk_ keys and are NOT platform keys: they open one merchant's endpoints and carry no platform permissions. Store it immediately; it is never readable again.

Declare a NEW data table for the merchant's backend. The declaration decides everything downstream — what the API accepts, what the admin grid shows, and what the generated MCP tools advertise. Every problem is reported at once, each naming its column.

Create or update a CATALOG price rule — a SALE PRICE on the products a condition selects. No coupon: the price is simply lower on the listing, the product page and in the cart, with the regular price struck through. Use it for 'everything made of wood is 10% off'. Conditions use the platform's filter grammar, including attr.<code> over the store's declared attributes.

Create or update a CART price rule — a coupon code, or a discount that applies by itself, taken off the whole basket at checkout. Use it for 'SALE10 takes 10% off orders over 500,000'. Omit coupon_code for an automatic discount.

Remove a social sign-in provider's configuration, secret included. People who signed up through it KEEP their accounts — but with no password they will have no way back in, so tell the merchant that before doing it.

Delete one stored file by key. Permanent.

Unbind an API path. The endpoint stops answering at once — the workflow itself is left alone, so this is how you retire a path without losing the work behind it.

Delete one record from a backend table.

Forget a stored credential. Any workflow still referring to {{ secret.<code> }} will fail its next call — check first, because the failure surfaces to whoever calls the endpoint, not here.

Remove a data table. Its records go with it.

Remove a stored setting. Publishing any workflow that still names it is then refused, with the node and the reference named — so a delete cannot quietly empty a URL.

Delete a workflow AND the API paths bound to it — a binding to something that is gone is not a binding, and a route left behind is a live endpoint nobody can reach and nobody can remove. To retire a path but keep the work behind it, use delete_backend_route instead.

Switch this website into SELLING mode: it gains /products, /cart, /checkout, /order/<token> and the admin's order desk, and gets default delivery options seeded so the checkout is never a dead end. Idempotent — safe to call on every build.

Fetch the TEXT content of a public http(s) URL — use this to read a design handoff (e.g. a claude.ai/design or Anthropic design-file export, an HTML/CSS file), a reference page to clone, or a JSON/Markdown spec the user links. Handles gzip-compressed responses automatically. Returns the raw body (HTML/CSS/JS/JSON/text), capped at 512KB. NOT for images: to put an image in the store, pass its URL to upload_image instead. Private/internal addresses are refused.

Fill in EVERY missing combination of a product's option axes (2 sizes × 3 colours = 6 rows) in one call. Each row inherits the product's price unless you pass `prices`, and existing rows are left untouched, so it is safe to call again after adding a value to an axis. Use this instead of writing out combinations by hand — hand-written sets are where a size goes missing.

The hostname this website's backend answers on — every route and every auth endpoint is <this>/<path>. Read it BEFORE trying to call anything: the API deliberately does NOT share a hostname with the website, or /orders would be ambiguous between a page and an endpoint. Empty list means no hostname yet — call provision_backend_api_domain.

List every workflow node type, its settings, which of them the publish gate demands, and the Go imports a code node may use. Read this BEFORE drawing a workflow — it is generated from the gate's own table, so a node it lists is a node the gate knows.

Every step of ONE REAL run — what each node returned, what it printed (wm.Log), how long it took and which one failed. list_backend_runs says a run failed; this says where. Not the same as test_backend_workflow, which runs the DRAFT with a request you made up: this is what actually happened to a real caller.

List the WEBSITE's own data a workflow may reach — orders, products, blog posts, contacts, media — with the columns of each, which of them are read-only, what can be filtered and sorted, and the row ceiling per read. These are named as ordinary tables in the db nodes: table: "shop:order". Resolved for THIS website, so shop:product appears only where there is a real catalogue — a content site's products are a content type, not a pretend product. Read this before drawing a workflow that touches website data; it is generated from the publish gate's own registry, so a column it lists is a column the gate accepts. Every update is a PATCH: a column you do not name is left alone.

List the events the WEBSITE publishes — an order placed, a form submitted — and which workflows already answer each. To run a workflow on one, DRAW an `event_trigger` node as its entry with that event name; publishing binds it, and removing the node unbinds it. The event's body arrives as input.body in the SAME shape a shop: read returns, so {{ input.body.total }} on order.placed means what {{ find.rows.0.total }} means in a query. The list is short because the platform emits only these today — there is no product or blog event, and offering one that never fires would be worse than its absence.

The webhook signature schemes a `signed` route may declare, each with the header it arrives in and which stored secret code it reads. Served from the SAME table the verifier uses, so a scheme listed here is one the gateway implements — read it instead of guessing a name, because an unknown scheme is refused rather than falling back.

Write ONE record into a backend table. A key with no declared column is refused with that key named — this API never silently drops a field it was given.

List the keys that open this backend's api_key routes and its built-in /files and /_bb endpoints. Only the prefix comes back — the key itself existed once, in the reply to the call that made it.

List every social sign-in provider this website CAN use, configured or not, with the exact callback URL to register with each. Providers differ in one way that is not cosmetic: asserts_email_verification. Google states whether an address was verified, so a Google sign-in can adopt an existing account with that email. Facebook and GitHub never state it, so a colliding email is REFUSED with an instruction (sign in with the password, then link) rather than silently becoming the same person — matching an unverified address is account takeover.

List the merchant's APP users — the people who register and sign in to what they built, not platform accounts and not storefront customers. Password hashes are never returned.

List what the backend has stored — the objects behind /files/<key>.

List the API paths this website serves, and which workflow each runs.

List recent workflow runs — what ran, how long it took, and what failed. The first place to look when an endpoint misbehaves.

List the workflows that run on a timetable, with the next run, the last run and whether it failed.

List the CODES of the credentials this website stores — API keys a workflow calls other services with. Values are never returned by anything. Use a code as {{ secret.<code> }} in an http_request node's header, URL or body, or as wm.Secret("<code>") in a code node.

List the data tables this website's backend declares, with their columns and record counts. Read this before writing records: the declaration is the contract, and a write naming an undeclared column is refused.

List this website's stored SETTINGS — code, value and note. Unlike a credential these come back WITH their values, because the whole point of a variable is that it can be read and checked. Use one in a workflow as {{ var.<code> }}, anywhere: a URL, a header, a body field, a branch rule, a code node.

The graphs a workflow has previously SERVED, newest first — the current published one is not in the list, it is on the workflow. Publishing overwrites the live graph, so this is the only record of what it used to be; pair it with revert_backend_workflow when a publish made things worse.

List the merchant's workflows with their draft and published graphs.

List the websites this API key can act on — their ids, slugs and whether each sells. A key whose organization owns several sites does not resolve one by itself: pick from this list and send it as the X-Store-Slug (or X-Store-Id) header on every call, which is what pins the session to that site.

Mint api-<slug>.<apex> for this website. Idempotent — calling it again returns the hostname that is already there rather than a second one. Inside the platform's wildcard certificate, so it works immediately with nothing to verify.

Run the publish gate and promote the draft. The gate measures BOTH directions — a required setting left empty, a path that never reaches a respond node, a reference to a node that does not run first, a db node touching an undeclared column, a code node importing outside the allowed set — and REFUSES with the offending node named. Nothing is published when it refuses; fix the node it names and call again.

Read records from a backend table, filtered and paged in SQL.

Detach a custom API hostname. The built-in api-<slug> one cannot be removed — it is what every published route answers on.

Put a previously-live graph back, by version from list_backend_workflow_versions. It PUBLISHES rather than restores: the old graph goes through the same gate as any other publish, because the world it ran in has moved — a table it wrote to may have been deleted, a variable it read may be gone — so you can get violations back instead of a revert. The graph being replaced is archived like any other, so a revert is itself revertible. The DRAFT is left alone.

Revoke one key. Calls using it start failing immediately.

Create or update a workflow's DRAFT graph — UPDATE genuinely works now; it used to fall through to create and fail on the unique index, so the only way to change one line was delete-and-recreate, which also deletes every route bound to it. Saved exactly as drawn — the gate runs at publish, so a half-finished graph can be stored without losing work. Nodes are {id, type, config} — and ONLY those keys plus label. DO NOT SET x/y: you have never seen the canvas, so you cannot know a card is 220x62, and a guessed stride buries each card under the next (measured: a graph saved at 180px apart had 8 overlapping pairs out of 10 nodes, titles cut off mid-word). Omit them and the canvas lays the graph out from its shape. Every key inside config must be one the node catalogue lists for that type, or the save is refused naming the node and the key (nothing is dropped in silence). http_in takes no config: its method and path live on the route. Edges are {from, to, port} where port is 'true'/'false' out of a branch — or 'error' out of ANY node, which is the path taken when that node fails instead of the whole run returning 500. The failing node's id then holds {error, failed} so the recovery path can read {{ ask.error }} and say something true. An error path must still reach a respond node.

Search Pexels for real, royalty-free stock VIDEOS and return candidate looping-clip URLs (mp4, ~720–1080p) + a poster still. Use for a HERO / section BACKGROUND VIDEO when the design calls for a cinematic, motion-led look — NOT every store wants one. Write the returned `url` into the section's `video_url` setting and `poster` into `video_poster`; both auto re-host into the store's media library on write (never hotlinked). The hero renders it muted + autoplay + loop + playsinline with the poster as the still. For a plain still image use search_stock_images instead.

Configure one social sign-in provider. The client secret is sealed and never readable again; OMIT it to keep the stored one, because sending an empty string would erase it. Switching a provider on requires a client id, a secret, and at least one redirect_allowlist entry — a callback that redirects anywhere is an open redirect on the endpoint that issues sessions, so the platform refuses to enable one without the list. Register the callback_url from list_backend_auth_providers with the provider EXACTLY as given: providers compare it byte for byte.

Store or replace a credential. It is sealed and can never be read back — not by this tool, not by the admin. A workflow reaches it by code. The platform substitutes the value at the moment it dials out, so it never enters the process that runs merchant code and is scrubbed out of the run log; publishing is refused if you put one in a respond node.

Store or replace a SETTING — an API base URL, a sender name, a page size, a feature flag, the address a webhook posts back to. Anything a workflow needs that is not a credential belongs here, NOT in a secret. A secret is deliberately unreadable: it never enters the runner, never appears in a step log, is scrubbed from the ones it might, cannot be read back and is refused in a respond node. Put a base URL there and the one value you need while debugging is the one you cannot see. A variable is the opposite on every count, and a mistyped {{ var.… }} is refused at PUBLISH instead of resolving to nothing and calling the wrong host.

Pin the request this workflow is tested with — {method, path, params, query, headers, body}. test_backend_workflow replays it when you call that tool with no input of your own, and the merchant sees the same request on the trigger node, so the case you reproduced does not vanish when you stop. Stored BESIDE the graph: it is never published to the runner.

Toggle the store between a shop (true) and a content-only website (false). Merges store.settings.commerce_enabled. (Requires a key with settings/full-access scope.)

Declare the SPEC FIELDS every product in this shop can fill (material, origin, warranty…). They appear in the admin product form and print on the product page, so declare them BEFORE creating products that carry them — an attrs value with no declared code is dropped.

EXECUTE a workflow's draft once with a request you make up, and get every step back: what each node returned, what it PRINTED (wm.Log from a code node), how long it took, and which one failed. This is how to debug a node — read the steps, not the final answer. If the gate refuses the draft you get violations instead of a run, because a graph the gate refuses cannot be usefully executed. Metered like a real call.

Change part of a record. Keys you send are replaced; keys you omit are left alone.

REPLACE a table's column declaration. Send every column you want to keep — this is not a merge. Records already stored are left exactly as they are: the new declaration governs writes from now on, and nothing walks the existing rows.

Write the store's ADMIN-level SEO + branding (Settings ▸ Branding/SEO): meta_title, meta_description, og_image_url, logo_url, favicon_url. THIS is where the SEO pass PERSISTS store SEO — the storefront <title>/<meta description>/OG read shop.meta_title/meta_description from here (never bake SEO into the theme, and do NOT hand-write a graphql mutation — there is a real tool, this one). Call it in the SEO step from the real brand + what the store sells.

Bind an API path to a workflow, and optionally put it live. For a webhook receiver (auth_mode 'signed') you MUST also pass signature_scheme and signature_secret_code — a signed route left on the default scheme refuses the sender's real deliveries. The reply carries them back, so read it and check what was stored.

Create or update a PRODUCT (the real catalogue, not a content type). Prices are NUMBERS IN MAJOR UNITS — 150000 means 150,000 in the store's currency, never a formatted string like '150,000 d' and never 15000000. A product with option axes MUST also carry its variants (or call generate_product_variants right after), because a shopper cannot add an unresolved combination to the cart and the platform refuses to guess a size. Set status:'published' for anything the shop actually sells — a catalogue of drafts renders empty.

Create or update ONE delivery option the shopper picks at checkout. A shop with no enabled method cannot take an order, so a new shop needs at least one. Fees are MAJOR units.

Run the PUBLISH GATE against a workflow's draft WITHOUT publishing it. Returns the same violations publish would, each naming the node and the setting. Call this after every edit instead of publishing to find out: it is the same rules, so nothing new can appear at publish time.

Re-run the DNS check on a custom API hostname. Returns the row with its new status — `verified` means it is live, `failed` means the records are not visible yet. DNS takes minutes to hours, so a failure right after the records are added is normal; wait and call again rather than telling the merchant something is wrong.