Flatsome
These abilities register when Flatsome is detected on the site and a Pro licence is active. If either is missing the module stays absent rather than failing at call time.
At a glance
Flatsome registers 11 abilities: 6 that only read, 3 that write, and 2 marked destructive. That split is the practical answer to how much of this module can run unattended. Reads cost nothing and are safe to repeat, so discovery is the part to be generous with; the writes are where review belongs, and the destructive calls stop for an explicit confirmation every single time regardless of which profile is active.
What this module is for
Read and write the UX Builder shortcode tree, edit single elements by path, browse the element catalogue and option schemas, insert the theme's own section presets, and work with reusable UX Blocks.
Before you rely on it: Nesting aliases, responsive breakpoint attributes and the editor's element ids are handled for you, and a tree that nests one tag past the tenth level is refused rather than silently flattened. Theme options remain Customizer settings served by the Theme Bridge module, and the module does not register new UX Builder elements.
Typical workflows
- Read a page's tree and change one element without touching the rest
- Start a new section from a preset the theme ships rather than hand-written markup
- Find the reusable block behind a repeated section before rebuilding it
The Flatsome integration page covers the same module from the workflow side, with the capability map and the questions worth asking before a first write.
Availability on your site
The Flatsome module needs three things at once: WPPilot Free as the MCP foundation, an active Pro licence, and the companion plugin detected on the site. Miss any one and the module does not register, which is deliberate: an ability that appears in the tool list but fails at call time is worse than an ability that was never offered. What the connected agent can actually call is then narrowed twice more: by the safety profile active on the site, and by the WordPress capabilities of the user behind the credential. A read that succeeds for an administrator can be absent entirely for an editor.
Every write these abilities perform is recorded in the change ledger, and destructive calls can be routed through the approval queue so a person signs off before anything is applied. A successful tool result means the operation returned, not that the front end, the cache, and every dependent template are correct: that still needs a look.
Reads
Available in every safety profile, including Read Only. Inspection costs nothing and is not rate limited.
| Ability | What it does |
|---|---|
wppilot/flatsome-check-setupCheck Flatsome Setup | Reports the Flatsome theme version, whether a child theme is active, the UX Builder state, and the counts of UX Blocks and portfolio items. Call this before any other Flatsome ability. Note what it says about element_registry: UX Builder loads its element definitions only inside the editor, so on a normal request the catalogue is not in memory. Reading and writing page content does not need it — Flatsome stores pages as ordinary shortcodes and its render shortcodes are always registered — but flatsome-list-elements, flatsome-get-element-schema and flatsome-list-presets load it on demand, and this reports whether that will work here. |
wppilot/flatsome-get-contentGet Flatsome Content | Parses one post's UX Builder content into a tree. Each node carries tag, type (container / element / html), options, a responsive map of per-breakpoint overrides, the editor's _id where one exists, and a path — the list of child indexes that addresses it, which every write ability takes. Nesting aliases are normalized away: a column inside a column is stored as col_inner and reported as col. Loose HTML and Gutenberg block comments between shortcodes are kept as html nodes and returned verbatim rather than being rewritten into [text] elements the way opening the editor would. Set depth to cut the tree off below a level when a full page would be large. |
wppilot/flatsome-get-element-schemaGet Flatsome Element Schema | Describes what options one or more UX Builder elements accept. Each option reports its control type, its default, the choices a select-style control allows, whether it is responsive (meaning it can also be written per breakpoint as name__sm), and the unit and range where the control has one. Group controls are flattened away, because a group is a panel in the editor UI and not an attribute — its children are the attribute names that appear in the markup. An option whose value equals its default is omitted from the markup by the editor; writing it anyway is harmless. Use this before writing options you have not seen on the page already. |
wppilot/flatsome-list-blocksList Flatsome UX Blocks | Lists the reusable UX Blocks on this site — the blocks post type Flatsome uses for headers, footers, banners and any layout dropped into several pages. Each row reports the id, title, slug, status, its block_categories terms, how many UX Builder nodes it holds, and the [block id="..."] shortcode that embeds it. A block is ordinary UX Builder content, so flatsome-get-content and the element abilities work on its post id exactly as they do on a page — which is the point: edit the block once and every page embedding it changes. |
wppilot/flatsome-list-elementsList Flatsome Elements | Lists the UX Builder elements registered on this site: tag, display name, category, whether it is a container or a leaf, whether it nests inside itself, and its allow / allow_in placement rules. Filter with category, name_contains, or type. This is the list to pick a tag from — do not guess ux_* names, because which elements exist depends on the Flatsome version and on any plugin that registered its own. Loads UX Builder's element registry on demand, which a normal request does not have; if that fails the error says so and the tree abilities are unaffected. |
wppilot/flatsome-list-presetsList Flatsome Presets | Returns the ready-made markup UX Builder offers for an element — the section layouts, banner arrangements and column splits its own picker inserts. Each preset is a name plus a block of shortcode markup, already valid and already using this Flatsome version's option names. Parsing a preset with flatsome-get-content on a scratch post, or handing it to flatsome-set-content, is the fastest correct way to build a section: it starts from what the theme ships rather than from guessed attributes. Omit tag for a count per element. |
Writes
Gated by the active profile and your WordPress capabilities. Rate limited to 120 per minute per credential.
| Ability | What it does |
|---|---|
wppilot/flatsome-add-elementAdd Flatsome Element | Inserts one element, or a whole prepared subtree, at a path. The final index in path is the position among the parent's children: [0, 2] puts it third inside the first root node, and an index equal to the current child count appends. Pass node as {tag, type, options, responsive?, children?} — the same shape flatsome-get-content returns, so a node read from one page can be inserted into another unchanged. The _id attribute is not copied when you omit it, which is correct for a new element: ids are the editor's key into its own per-element meta, and two elements sharing one is a page where the editor drops one of them. |
wppilot/flatsome-edit-elementEdit Flatsome Element | Changes the options of the element at a path, leaving its children alone. options is merged over what is there, so only the keys you name change; pass an empty string to drop one, because UX Builder omits an attribute rather than writing an empty value. responsive merges the same way, per breakpoint. Pass replace: true to swap the whole option set instead of merging. The tag can be changed with tag, which is how a heading becomes a different element without rebuilding the subtree — the options are yours to make valid for the new tag. |
wppilot/flatsome-move-elementMove Flatsome Element | Moves the node at path to to_path, taking its children with it. to_path is read against the tree with the node already removed, which is the only way the two ends of a move can be expressed together — so moving the first root node to [2] lands it after what were originally the second and third nodes. Moving a container into its own descendant is refused rather than detaching the branch. |
Destructive
Marked destructive in the source, so each call needs an explicit confirmation flag, every time.
| Ability | What it does |
|---|---|
wppilot/flatsome-delete-elementDelete Flatsome Element | Removes the node at a path, and everything inside it. The returned removed summarizes what went, including the child count, so the caller can report it accurately. Destructive: the subtree is gone from post_content and only a post revision holds it afterwards. |
wppilot/flatsome-set-contentSet Flatsome Content | Replaces one post's entire UX Builder tree with the supplied nodes. Each node is {tag, type, options, responsive?, id?, children?}; type is container for elements that hold children, element for leaves, and html for a verbatim passage carried in content. Nesting aliases are applied on write, so pass the plain tag and let the serializer decide whether it writes col, col_inner or col_inner_3. Option values containing a double quote are refused rather than written, because shortcode attributes are quoted with " and WordPress has no escape for one inside a value. Destructive — it discards whatever the post held. Prefer add / edit / delete / move for anything smaller than a full rebuild. |