Flatsome ability reference
Reference for the GoBuildWP Pro 1.12.4 source. Installed schemas and policy remain authoritative.
This Flatsome ability reference lists every call GoBuildWP Pro registers for Flatsome UX Builder elements, presets and blocks, with the exact slug an agent sends and what the plugin's own contract says it does. Of the 11, 6 read, 3 write and 2 are marked destructive in the source.
Read-only, write and destructive groups describe the source annotations. They do not establish a minimum safety profile, human approval or undo support. Those controls are separate: check the installed ability, the connected user and the active site policy before calling it. A read can still return sensitive data. These pages are not evidence that every operation passed an end-to-end runtime test.
What Flatsome needs before these load
These 11 abilities come with GoBuildWP Pro 1.12.4. Pro registration requires the Freemius SDK to permit premium code and any companion dependency the module checks to be available. The floors below apply to the named dependencies or features; an optional add-on or newer feature floor does not necessarily disable the base module. wppilot/integration-health and the module's setup call describe the installed availability.
- Minimum (base)
- 3.20.0
WPPILOT_PRO_FLATSOME_MIN_VERSION - Flatsome editions
- free, pro
- Agent skills shipped
flatsome-build-page
Example Flatsome input: wppilot/flatsome-list-blocks
This one operation declares the 5 top-level input parameters below in wppilot-pro/includes/wppilot-abilities/wppilot-flatsome/wppilot-list-blocks.php, and none is required on its own. Other calls in this module take different arguments. Nested schemas and constraints are not expanded here; the complete live schema a connected client discovers is authoritative.
| Parameter | Type and meaning |
|---|---|
status | string one of publish, draft, pending, private, any |
category | string. Filter by a block_categories term slug. |
search | string |
page | integer |
per_page | integer |
Flatsome in practice
Undoing a Flatsome edit, and the case for UX Blocks
Every Flatsome write, including the destructive set and delete calls, snapshots the whole post before changing it, so wppilot/rollback-change can put a page or a UX Block back to that snapshot through the change ledger; WordPress post revisions, where the site keeps them, are a separate way back. The snapshot is per call. An agent that builds a section in ten add and edit calls leaves ten ledger entries, and returning to the starting point means rolling back the earliest of them; see change ledger and rollback.
Because a UX Block is an ordinary post as far as these calls are concerned, the same undo applies to a header, footer or banner block shared by many pages. That cuts both ways: one edit to a block changes every page that embeds it, so read wppilot/flatsome-list-blocks for the embed shortcode and check a couple of pages that use it after any change.
Validation errors that stop a Flatsome tree before it is written
The tree is checked as a whole before anything is saved, so a refusal means the post is unchanged. The checks follow from how UX Builder stores pages as shortcodes:
- flatsome_invalid_breakpoint: responsive overrides only accept sm, md and lg, the three breakpoints Flatsome has.
- flatsome_nesting_too_deep: an element is nested inside itself more levels than UX Builder has alias tags for. Such a tree cannot be written as shortcodes and would be flattened the next time the editor opened it.
- flatsome_duplicate_id: two nodes carry the same editor _id, which happens when a node read from a page is inserted again without dropping its id. Leave _id out on copies.
- flatsome_not_a_container: the target path points at a leaf element, which cannot hold children.
- flatsome_invalid_tag and flatsome_invalid_id: a node's tag or _id is missing or malformed.
- flatsome_unquotable_value: an option value contains a double quote, which a shortcode attribute has no way to escape. Rewrite the value without one.
When the UX Builder element catalogue will not load
Element lists, schemas and presets need UX Builder's own registry, which Flatsome normally loads only inside the editor. GoBuildWP loads it on demand, and two errors mean that load failed: flatsome_builder_missing when this Flatsome install has no UX Builder at the expected path, and flatsome_builder_incompatible when it loaded but lacks the classes GoBuildWP expects, which points at an unusual or modified Flatsome build. Reading and writing page content does not depend on the registry, so an agent can still edit existing elements; it should not invent ux_ tag names without the catalogue to check them against.
Flatsome reads
| 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. |
Flatsome writes
| 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 Flatsome calls
| 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. The change ledger records the post before the delete, so wppilot/rollback-change can restore the post as it was; a post revision may also hold it. |
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. |
For the task-level view of Flatsome, with worked requests and what to check afterwards, see Flatsome integration page.