Pro module23 abilities

ACF ability reference

Reference for the GoBuildWP Pro 1.12.4 source. Installed schemas and policy remain authoritative.

This ACF ability reference lists every call GoBuildWP Pro registers for ACF field groups, values, post types and options pages, with the exact slug an agent sends and what the plugin's own contract says it does. Of the 23, 10 read, 6 write and 7 are marked destructive in the source.

By GoBuildWPContent updated 13 October 2026How we check claims

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 ACF needs before these load

These 23 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): 6.5.0 WPPILOT_PRO_ACF_MIN_VERSION
ACF editions: free, pro
Agent skills shipped: acf-integration, content-model-schema, content-model-migration, dynamic-data-binding

ACF in practice

Which ACF changes the change ledger can put back

Undo coverage in this module is uneven, and it is worth knowing before an agent edits a field group. wppilot/acf-write-values is restorable only when the target is a post: the ledger snapshots that post first. Values written to a user, term, comment or options page are stored in meta or option rows that ACF names itself, so those writes are recorded as irreversible. A field group created by wppilot/acf-create-fieldgroup can be removed again with wppilot/rollback-change, and the post type, taxonomy and options page edits are snapshotted by key.

wppilot/acf-edit-fieldgroup cannot be rolled back. A field group is one group post plus a separate acf-field post for every field, and a single post snapshot cannot rebuild that set. Before an edit, save the output of wppilot/acf-get-fieldgroup-schema: it is in ACF's native export shape, so it can be imported through ACF Tools or sent back through the same edit call. The four deletes are permanent for the same reason. See change ledger and rollback for how a restore is requested.

Slug rules ACF definitions must pass first

Every post type, taxonomy and options page slug is checked before anything is saved. Slugs use lower-case letters, digits, hyphens and underscores, and are capped at 20 characters for a post type, 32 for a taxonomy and 50 for an options page. Core names such as post, page, attachment, wp_block and wp_navigation, or category, post_tag and nav_menu for taxonomies, are refused with reserved_slug. A slug already used by another ACF record is refused with slug_collision_acf, while one registered by a theme or another plugin only adds an external_slug_collision warning, so read the warnings on a successful create.

Post types and taxonomies need an ACF build of 6.5.0 or newer that exposes its internal post type API; otherwise the call answers acf_version_unsupported. Options pages additionally need ACF PRO, because the free plugin never registers them and a page saved there would never appear.

Reading ACF refusals before retrying

Most ACF mistakes come from addressing the wrong thing rather than from bad values, so the codes below are mostly about targets and definitions.

validation_failed: acf_validate_value() rejected at least one field in the batch, and nothing was written. Fix the listed fields and resend the whole batch.
target_invalid: target.type is not post, user, term, comment or options, or the id has the wrong shape. An options target takes the page's post_id (or nothing, for the shared options store), never its menu slug.
field_group_not_editable: the group is registered in PHP, so it can only be changed in the theme or plugin file that defines it.
wppilot/acf-delete-post-type and wppilot/acf-delete-taxonomy refuse with delete_blocked_by_content while posts or terms exist, reporting affected_count; force: true deletes the definition and leaves the posts or terms orphaned.
not_authorized: the field group calls also check manage_options for the connected user, on top of GoBuildWP's own permission check.

ACF reads

Ability	What it does
`wppilot/acf-check-setup`Check ACF Setup	Reports the ACF environment: whether ACF is active, edition (free or pro), version, whether the installed runtime exposes the internal post-type and taxonomy API at ACF 6.5+ and the separate Pro options-page API, and how many ACF-managed post types, taxonomies, and options pages already exist. Use before any ACF operation to verify the runtime is ready.
`wppilot/acf-get-fieldgroup-schema`Get ACF Field Group Schema	Returns the full schema of a specific ACF field group in ACF native format: key, title, fields (with sub_fields for repeaters and layouts for flexible_content), location rules, position, conditional logic, plus a _meta block describing where it is defined and whether it can be edited.
`wppilot/acf-get-options-page`Get ACF Options Page	Returns the full payload of a single ACF-managed options page, including page_title, menu_title, parent_slug, capability, icon_url, position, redirect, post_id, autoload, advanced_configuration, and all other ACF UI options-page fields. Accepts either the ACF key (ui_options_page_<menu_slug>) or the bare menu_slug.
`wppilot/acf-get-post-type`Get ACF Post Type	Returns the full payload of a single ACF-managed post type, including all register_post_type() arguments and ACF-specific keys. Accepts either the ACF key (post_type_<slug>) or the bare slug.
`wppilot/acf-get-taxonomy`Get ACF Taxonomy	Returns the full payload of a single ACF-managed taxonomy, including all register_taxonomy() arguments and ACF-specific keys. Accepts either the ACF key (taxonomy_<slug>) or the bare slug.
`wppilot/acf-list-fieldgroups`List ACF Field Groups	Returns a lightweight overview of all ACF field groups: key, id, title, active flag, source (db/json/php), editable flag, fields count, and a one-line location summary. Use to discover what is available before fetching a full schema.
`wppilot/acf-list-options-pages`List ACF Options Pages	Returns a lightweight overview of all ACF-managed options pages: key, slug (menu_slug), title (page_title), active flag, source (db/json/php), parent_slug, capability, menu_title. Use to discover what is available before fetching a full payload via acf-get-options-page.
`wppilot/acf-list-post-types`List ACF Post Types	Returns a lightweight overview of all ACF-managed post types: key, slug, title, active flag, source (db/json/php), public flag, hierarchical flag. Use to discover what is available before fetching a full payload via acf-get-post-type.
`wppilot/acf-list-taxonomies`List ACF Taxonomies	Returns a lightweight overview of all ACF-managed taxonomies: key, slug, title, active flag, source (db/json/php), and the object_type[] (post types this taxonomy is attached to). Use to discover what is available before fetching a full payload via acf-get-taxonomy.
`wppilot/acf-read-values`Read ACF Values	Reads ACF values from a target (post, user, term, comment, options page). If fields[] is omitted, returns all fields whose location rules apply to the target. format_values defaults to true (formatted: images as arrays with sizes, post objects expanded). Set to false for raw stored data (typically IDs). only_with_values: true skips fields whose stored value is empty. Note: get_field returns ACF default values for never-written fields, so a fresh post may appear pre-populated.

ACF writes

Ability	What it does
`wppilot/acf-create-options-page`Create ACF Options Page	Creates a new ACF-managed options page from a payload in ACF native format. Top-level shape mirrors acf_add_options_page() arguments. Required minima: menu_slug (alias slug) and page_title (alias title or menu_title). Idempotent by key. Field values stored on the page are then accessed via acf-read-values / acf-write-values with target.type=options and target.id=<post_id> - note: <post_id> defaults to "options" (the shared default ACF options store) unless you pass an explicit post_id on the options-page payload. The menu_slug and post_id are different concepts - passing menu_slug as target.id will read/write to the wrong location.
`wppilot/acf-create-post-type`Create ACF Post Type	Creates a new ACF-managed post type from a payload in ACF native format. Top-level shape mirrors register_post_type() arguments plus ACF-specific keys (advanced_configuration, active). Required minima: post_type (alias slug) and title (or labels.singular_name). Idempotent by key.
`wppilot/acf-create-taxonomy`Create ACF Taxonomy	Creates a new ACF-managed taxonomy from a payload in ACF native format. Top-level shape mirrors register_taxonomy() arguments plus ACF-specific keys (advanced_configuration, active). Required minima: taxonomy (alias slug) and title (or labels.singular_name). Idempotent by key.
`wppilot/acf-edit-options-page`Edit ACF Options Page	Edits an existing ACF-managed options page in place using ACF native format. Requires key (or menu_slug, resolved by name). Renaming menu_slug only changes the admin URL; field values stored under the page's post_id continue to resolve as long as post_id is preserved.
`wppilot/acf-edit-post-type`Edit ACF Post Type	Edits an existing ACF-managed post type in place using ACF native format. Requires key (or slug, resolved by name). Slug change while content exists attaches a slug_change_orphans_content warning to the response - the edit proceeds, content migration is the agent's responsibility.
`wppilot/acf-edit-taxonomy`Edit ACF Taxonomy	Edits an existing ACF-managed taxonomy in place using ACF native format. Requires key (or slug, resolved by name). Slug change while terms exist attaches a slug_change_orphans_content warning to the response - the edit proceeds.

Destructive ACF calls

Ability	What it does
`wppilot/acf-create-fieldgroup`Create ACF Field Group	Creates a new ACF field group from a payload in ACF native format (the same shape produced by ACF Tools → Export). Missing key values are auto-generated. Returns the resulting key, post id, and whether ACF synced the group to local JSON. Refuses if the supplied key already matches an existing field group.
`wppilot/acf-delete-fieldgroup`Delete ACF Field Group	Deletes a field group permanently. Values previously stored under that group remain in postmeta but become unreachable via the ACF API.
`wppilot/acf-delete-options-page`Delete ACF Options Page	Permanently deletes an ACF-managed options page. The deletion does not touch wp_options; field values previously stored under the page's post_id remain in the database but are no longer reachable through the ACF UI.
`wppilot/acf-delete-post-type`Delete ACF Post Type	Permanently deletes an ACF-managed post type. Refuses to delete when posts of this type exist unless force=true is passed. The deletion does not touch wp_posts; orphaned posts remain in the database with a post_type that is no longer registered.
`wppilot/acf-delete-taxonomy`Delete ACF Taxonomy	Permanently deletes an ACF-managed taxonomy. Refuses to delete when terms exist unless force=true. The deletion does not touch wp_term_taxonomy; orphaned terms remain in the database with a taxonomy that is no longer registered.
`wppilot/acf-edit-fieldgroup`Edit ACF Field Group	Edits an existing ACF field group in place using ACF native format. Top-level keys (title, location, position, active, etc.) follow PATCH semantics - fields the agent omits are preserved from the existing record. The fields[] array, in contrast, follows REPLACE semantics: any field not in the payload is removed. Renaming a field key orphans values stored under the old key, so preserve keys to keep data. Refuses field groups whose source is "php" (registered in code).
`wppilot/acf-write-values`Write ACF Values	Writes a batch of ACF values to a target. Atomic field types accept the value directly: { "subtitle": "Hello" }. Complex field types (repeater, flexible_content, gallery, clone, group) require an explicit consent wrapper: { "features": { "value": [...], "mode": "replace" } }, because writing a complex value replaces the entire previous content. Pre-flight validation via acf_validate_value() enforces required and format constraints; any failure rejects the entire batch - no partial writes. Writes use update_field(), so acf/update_value hooks fire; acf/save_post does not fire because there is no admin save-post submission. Field keys (recommended) and names are both accepted.

For the task-level view of ACF, with worked requests and what to check afterwards, see Advanced Custom Fields integration page.