Spectra ability reference
Reference for the GoBuildWP Pro 1.12.4 source. Installed schemas and policy remain authoritative.
This Spectra ability reference lists every call GoBuildWP Pro registers for Spectra blocks, popups and editor settings, with the exact slug an agent sends and what the plugin's own contract says it does. Of the 20, 10 read, 4 write and 6 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 Spectra needs before these load
These 20 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)
- 2.19.0
WPPILOT_PRO_SPECTRA_MIN_VERSION - Minimum (pro)
- 1.2.0
WPPILOT_PRO_SPECTRA_PRO_MIN_VERSION - Spectra editions
- free, pro
- Agent skills shipped
spectra-build-page,spectra-integration
Before accepting the result
Custom persistence hooks are separate developer work. Inspect partial_writes when a condition update fails, reread the affected records and review recovery for each completed write before retrying.
Spectra in practice
Which Spectra changes wppilot/rollback-change can reverse
Almost everything here is covered by the change ledger. A created or duplicated popup can be removed again; a popup edit, an enable or disable, and a Spectra Pro display-condition write are snapshotted as the popup post, so a rollback restores its content, status and condition meta together. Editor settings, the Google Fonts delivery mode and the block activation registry are snapshotted as the options they live in. The exception is wppilot/spectra-delete-popup, which skips the trash and is recorded as permanent; disable the popup instead when it may be wanted again.
Because the block activation registry is one option for every block, rolling back one activation change also reverts any other block switched on or off in Spectra's settings since. Check the block list before restoring on a site someone else is configuring.
Recovering from a half-written Spectra Pro condition set
wppilot/spectra-pro-set-popup-conditions writes the trigger, delay, inclusions and exclusions as separate meta rows. If one of them fails part-way, the error lists the rows that did save under partial_writes, and the post cache is cleared so a fresh read shows the mixed state. Read the conditions back with wppilot/spectra-pro-list-popup-conditions before retrying, and remember that inclusions and exclusions are replaced whole, so resend the complete intended bundle rather than only the part that failed. Rolling back the call's ledger entry is the other way out, since the popup was snapshotted before the first row was written.
wppilot/spectra-list-form-blocks returns 100 posts by default and stops at 500, with truncated set when there were more. It finds where forms are placed; Spectra's free form block does not store submissions, so there is nothing for an agent to read back about entries.
Spectra reads
| Ability | What it does |
|---|---|
wppilot/spectra-check-setupCheck Spectra Setup | Returns the Spectra (UAGB / Ultimate Addons for Gutenberg) runtime state in one call: plugin active, version, min-supported, min-satisfied; Spectra Pro add-on active + version + min-satisfied; block registry counts (free + pro); popup count; UAGB form-block usage count. Call this BEFORE any other Spectra ability - every other call is gated on plugin.active && plugin.min_satisfied, and Pro-only abilities additionally require pro.active && pro.min_satisfied. |
wppilot/spectra-get-block-schemaGet Spectra Block Schema | Return the attribute schema of a single Spectra block (name = uagb/xxx or spectra-pro/xxx). Output includes the block title, category, family (free|pro), whether it renders via PHP (dynamic_render), the supports map, and the full attributes map. Use wppilot/spectra-list-blocks first to pick a name, or after check-setup to inspect a specific block. |
wppilot/spectra-get-popupGet Spectra Popup | Read a single Spectra Popup Builder post (spectra-popup CPT) in full: title, status, slug, content (block markup, byte-capped by default), full meta bundle (popup_type, enabled, repetition), modified timestamp. Use max_field_bytes to override the 20_000-byte content cap (0 disables truncation). Progressive-disclosure counterpart of wppilot/spectra-list-popups. |
wppilot/spectra-get-settingsGet Spectra Settings | Read the current Spectra plugin settings - editor UX toggles (uag_enable_*), container defaults, Google Fonts hosting mode, and reCAPTCHA site-key presence. Values are returned as a flat map. reCAPTCHA SECRET keys are NEVER echoed; only a recaptcha.has_secret_v2 / has_secret_v3 boolean flag is exposed. Whitelist-only - settings outside the map are not read here (use wppilot/execute-php for one-off reads of niche keys). |
wppilot/spectra-list-blocksList Spectra Blocks | Enumerate the Spectra blocks registered with WordPress. Returns compact records (name, family free|pro, category, dynamic_render, title). Filters: family (free|pro|all - default all), name_contains (substring match on the block name; case-insensitive), category (exact match on the block editor category). Progressive-disclosure: use wppilot/spectra-get-block-schema for the full attribute schema of a specific block. |
wppilot/spectra-list-form-blocksList Spectra Form Blocks | Locate posts / pages that contain at least one Spectra uagb/forms block. Returns compact records (id, title, status, post_type, form_count) so an agent can pick a target for edit-block via wppilot/gutenberg-*. Bounded LIKE query with a hard 500-row cap and a truncated flag - the ability never scans the entire posts table on production stores. UAGB Free does NOT persist form submissions; use wppilot/execute-php + the uagb_form_success action hook for that surface. |
wppilot/spectra-list-google-fontsList Spectra Google Fonts | Enumerate the Google Fonts Spectra currently loads globally. Merges three UAGB sources: uag_select_font_globally (Settings → Global Fonts), spectra_gbs_google_fonts (per-Global-Block-Style fonts), and spectra_global_fse_fonts (FSE theme.json bridge). Each record reports source. Also returns the three delivery-mode flags - loaded_locally, preload_local, load_fse_globally - so an agent can distinguish "not loaded" from "loaded remotely". |
wppilot/spectra-list-popupsList Spectra Popups | Enumerate Spectra Popup Builder posts (spectra-popup CPT) as compact records: id, title, status, popup_type (modal|slide-in|banner|…), enabled (bool), modified. Filters: status (WP post_status; default: publish+draft+private), enabled (bool), popup_type (exact match), search (title substring). Progressive-disclosure: use wppilot/spectra-get-popup for full content and full meta. |
wppilot/spectra-pro-check-setupCheck Spectra Pro Setup | Returns the Spectra Pro (spectra-pro/spectra-pro.php) runtime state: plugin active, version, min-supported, min-satisfied, plus the Spectra Pro license status. Call this BEFORE any other wppilot/spectra-pro-* ability. Every Pro ability additionally gates on plugin.active && plugin.min_satisfied at registration time (they are not loaded when the gate fails), so this call is only reached when Pro is at or above the supported floor. |
wppilot/spectra-pro-list-popup-conditionsList Spectra Pro Popup Conditions | Read the Spectra Pro display-condition bundle for one popup: trigger (open trigger - click, scroll, exit-intent, time-delay), trigger_delay (seconds), display_inclusions (where the popup MAY appear - page targets), and display_exclusions (where it MUST NOT appear). All four keys are the meta rows the Spectra Pro popup extension (Spectra_Pro_Popup_Builder::register_pro_meta()) writes on the free spectra-popup CPT. Reading is safe on any popup - missing rows return empty defaults, mirroring the reader shape wppilot/spectra-pro-set-popup-conditions writes. |
Spectra writes
| Ability | What it does |
|---|---|
wppilot/spectra-create-popupCreate Spectra Popup | Create a new Spectra Popup Builder post (spectra-popup CPT). Accepts short names (title, content, status) or their WP-native aliases (post_title, post_content, post_status) - passing both is rejected. When content is omitted the popup is seeded with the locked wp:uagb/popup-builder root block so the popup builder editor opens on a valid tree. Meta defaults: popup_type=modal, enabled=true, repetition=0. |
wppilot/spectra-disable-popupDisable Spectra Popup | Flip the spectra-popup-enabled meta flag to false (stores an empty string, the UAGB storage convention). Idempotent - calling on an already-disabled popup returns the same response. Paired with wppilot/spectra-enable-popup for the reverse operation. |
wppilot/spectra-duplicate-popupDuplicate Spectra Popup | Deep-copy a Spectra Popup into a brand-new draft: post content + slug + every canonical meta key (popup_type, enabled, repetition) plus any additional spectra-popup-* / spectra-pro-* meta the source carries (Pro adds display conditions). Optional title_suffix (default " (Copy)") is appended to the copied title so agents can find the new row. |
wppilot/spectra-enable-popupEnable Spectra Popup | Flip the spectra-popup-enabled meta flag to true. Idempotent - calling on an already-enabled popup returns the same response. Paired with wppilot/spectra-disable-popup for the reverse operation. Meta writes flush the post cache so a follow-up read sees the fresh value. |
Destructive Spectra calls
| Ability | What it does |
|---|---|
wppilot/spectra-delete-popupDelete Spectra Popup | Permanently delete a Spectra Popup (skips the trash). Requires confirm: true in the payload - a safety interlock so an agent cannot destroy the row from a single-argument tool call. Returns the deleted id + title so the caller can log which popup went away. |
wppilot/spectra-edit-popupEdit Spectra Popup | Merge-update a Spectra Popup. Every field is optional - only the keys the caller passes are written. Accepts short names (title, content, status, slug) or WP-native aliases (post_title, post_content, post_status, post_name); passing both aliases of the same field returns spectra_alias_conflict. Meta subset (popup_type, enabled, repetition) also mergeable. The post cache is flushed after the write so a follow-up get-popup sees fresh values. |
wppilot/spectra-pro-set-popup-conditionsSet Spectra Pro Popup Conditions | Write the Spectra Pro display-condition bundle for one popup. Every field is optional (at least one MUST accompany id). display_inclusions and display_exclusions are REPLACE-ALL writes (the whole bundle is overwritten). trigger accepts the Spectra Pro trigger vocabulary (typically load, click, time-delay, exit-intent, scroll); the ability stores the string verbatim and lets Spectra Pro validate at render time. written[] in the response lists keys whose stored value actually changed on this call - a key already at target does NOT appear (idempotent no-op). Post cache is flushed after the write. All-or-nothing type validation: every submitted field is type-checked before the first write, so a bad type never leaves a partial write behind. Not transaction-safe against a mid-sequence storage failure (e.g. a caching-plugin filter short-circuiting one row after another has committed) OR against concurrent callers overlapping keys - last-write-wins per meta row. On such a mid-sequence failure the returned WP_Error carries the list of already-persisted rows under data.partial_writes and the post cache is flushed for them. |
wppilot/spectra-set-block-activationSet Spectra Block Activation | Enable or disable a single Spectra block (uagb/xxx or spectra-pro/xxx) in the _uagb_blocks registry. Reads the shared option, changes the requested entry and writes the option back, without a cross-request lock. Concurrent panel or agent writes can overwrite one another. Coordinate edits and read activation state back after the write. The block must be present in the plugin catalogue (verified against wppilot/spectra-list-blocks). Spectra front-end + editor caches are flushed after the write. |
wppilot/spectra-set-editor-settingsSet Spectra Editor Settings | Write one or more Spectra editor / container settings. Whitelist-only - accepts the same 17 keys that wppilot/spectra-get-settings exposes. Toggles (uag_enable_*, uag_load_gfonts_locally, uag_preload_local_fonts, uag_load_fse_font_globally) accept the strings "enabled" / "disabled" (UAGB storage shape); container-default keys and the visibility/dynamic-content mode keys accept free-form strings. Unknown or non-whitelisted keys return spectra_unknown_setting. Cache is flushed after the write so the front end serves fresh CSS. |
wppilot/spectra-set-google-fonts-modeSet Spectra Google Fonts Mode | Toggle Spectra Google Fonts delivery mode. At least one of mode, preload_local, load_fse_globally MUST be provided - omitted keys stay untouched. local enables the UAGB local-hosting pipeline (fonts served from wp-content/uploads/spectra/), remote disables it so the front end links Google's CDN. preload_local and load_fse_globally are secondary flags exposed only for completeness. Same cache-flush semantics as spectra-set-editor-settings - the front end serves refreshed CSS after the write. |
For the task-level view of Spectra, with worked requests and what to check afterwards, see Spectra integration page.