Pods ability reference
Reference for the GoBuildWP Pro 1.12.4 source. Installed schemas and policy remain authoritative.
This Pods ability reference lists every call GoBuildWP Pro registers for Pods, fields, groups and items, with the exact slug an agent sends and what the plugin's own contract says it does. Of the 25, 9 read, 12 write and 4 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 Pods needs before these load
These 25 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.2.1.1
WPPILOT_PRO_PODS_MIN_VERSION - Pods editions
- free, pro
- Agent skills shipped
pods-integration,content-model-schema,content-model-migration,dynamic-data-binding
Pods in practice
Querying Pods items with structured filters
wppilot/pods-list-items does not accept a raw SQL where clause; sending one returns a message naming the change rather than being silently ignored. Instead it takes filters, a list of up to 20 conditions that must all match. Each condition has a field, an operator and a value, and the value reaches the database as a prepared parameter. The operators are =, !=, >, >=, <, <=, LIKE, NOT LIKE, IN, NOT IN, EXISTS and NOT EXISTS. LIKE matches anywhere in the value because Pods adds the wildcards, IN and NOT IN take an array, and the EXISTS pair ignores the value. Regular-expression matching is left out deliberately, since a bad pattern can tie up MySQL from a call every safety profile allows.
For a pod's own fields, use the field name and Pods works out where it is stored. For the underlying object's columns, use t. followed by the column, such as t.post_status or t.post_title on a post-type pod. orderby takes one or more column references with ASC or DESC and nothing else: no functions or expressions. Results come 20 at a time by default, up to 100, with offset for the next page.
Pods writes report failure in the result, not as an error
Pods can signal a failed save in four ways: returning false, returning a WordPress error, throwing an exception, or returning nothing useful. GoBuildWP folds all of them into one shape, success: false with an error message, so the call itself appears to complete. An agent must read success on every Pods write before moving on to the next step; a create-field that failed because the group did not exist will otherwise be followed by item writes into a field that is not there.
Planning Pods changes you cannot roll back
Every write in this module is recorded by the change ledger as irreversible, because Pods spreads a change across its pod definitions, its caches and, for table storage, its own pods_* tables. That includes item creates and edits, not only schema changes. Before an edit, read what will change with wppilot/pods-get-pod, wppilot/pods-get-field or wppilot/pods-get-item and keep it, since the reverse is a second edit with the old values.
Renames deserve the most care. new_name on wppilot/pods-edit-pod renames the post type, taxonomy or table underneath, and new_name on wppilot/pods-edit-field changes the key values are stored under, so templates, shortcodes and code that use the old name stop finding the data. Search the theme and any custom code for the old name first, and try the rename on a staging copy. wppilot/pods-delete-field wipes the stored values as well as the definition, and delete_items: true on wppilot/pods-delete-pod removes the content itself, so take a database backup before either.
Pods reads
| Ability | What it does |
|---|---|
wppilot/pods-check-setupCheck Pods Setup | Reports the Pods environment: version, whether the API surface is loadable, the Advanced Content Types component (required by pods-create-act), the count of pods registered in the DB, and any actionable issues. Run this before any Pods write to confirm the runtime is ready. |
wppilot/pods-get-fieldGet Pods Field | Returns a single Pods field with every type-specific key Pods stored, flattened into the field object at the top level (Pods' Whatsit model does not nest options separately). Use this when you need to inspect or copy an existing field's configuration. |
wppilot/pods-get-field-type-schemaGet Pods Field Type Schema | Returns the agent-relevant options keys for a single Pods field type (e.g. pick, file, number). Each entry has key, type, and a one-line description. Call this before pods-create-field when you need to set type-specific options like pick_object, file_format_type, or number_decimals. Field types not listed here still accept any option keys Pods recognises - this is a hint surface, not a strict schema. |
wppilot/pods-get-itemGet Pods Item | Returns a single item from a pod with all its field values resolved (relationships expanded into IDs, files into attachment IDs, etc.). Use fields to project specific keys when the full payload is too large. |
wppilot/pods-get-podGet Pod | Returns the full schema of a single pod: identifying info (id, name, type, storage, object), the options blob (label, description, public flags, REST settings, …), and the field/group structure. Use this to introspect the schema before editing or to verify what create-cpt / create-taxonomy / create-act actually wrote. |
wppilot/pods-list-fieldsList Pods Fields | Lists every field defined on a pod. Output is compact: name, label, type, group_id, weight. Use pods-get-field for the full options blob of a single field. |
wppilot/pods-list-groupsList Pods Field Groups | Lists every group defined on a pod, compact form: id, name, label, weight. Use this instead of pods-get-pod include_groups=true when you only need the group list - keeps the response small and avoids loading every field at the same time. |
wppilot/pods-list-itemsList Pods Items | Lists items in a pod, paginated. Returns each item as {id, fields}. Pass fields to project specific keys (default: every field on the pod) - useful when items have a wysiwyg / large blob you do not need in the listing. |
wppilot/pods-list-podsList Pods | Lists every Pod (CPT, taxonomy, ACT, settings page, extended built-in) registered through Pods. Output is compact: id, name, label, type, storage, object. Use pods-get-pod for the full schema (fields, groups, options) of a single pod. |
Pods writes
| Ability | What it does |
|---|---|
wppilot/pods-create-actCreate Pods Advanced Content Type | Creates a brand-new Advanced Content Type - a Pods-managed content collection backed by a dedicated database table (wp_pods_<name>) instead of postmeta. Use this when you need scale, fast queries, and data that should not pollute the WP posts table. Requires the Advanced Content Types component to be active (pods-check-setup reports act_component_active). |
wppilot/pods-create-cptCreate Pods CPT | Creates a brand-new Pods-managed Custom Post Type. To attach Pods fields to an existing post type (post, page, attachment, third-party CPT), use pods-extend-builtin instead. After creation use pods-create-field / pods-create-group to model the schema. |
wppilot/pods-create-fieldCreate Pods Field | Adds a new field to a pod. Pods 3.x requires every field to belong to a group - pass group (or group_id). If the pod has no group yet, call pods-create-group pod=<pod> name=details first. For type-specific options (e.g. pick_object, file_format_type, number_decimals) call pods-get-field-type-schema field_type=<type> to discover option keys, then pass them in options. |
wppilot/pods-create-groupCreate Pods Field Group | Adds a new field group to a pod. Pods 3.x requires every field to belong to a group - call this once per pod before any pods-create-field. |
wppilot/pods-create-itemCreate Pods Item | Creates a new item in a pod. data is a flat field_name => value map. For post-type pods the standard WP fields (post_title, post_status, post_content) work alongside Pods custom fields. For pick (relationship) fields, pass an item ID (single) or an array of IDs (multi). |
wppilot/pods-create-settingsCreate Pods Settings Page | Creates a brand-new Pods Settings Page - a custom admin screen whose fields are stored in wp_options and queryable via pods_v / pods_field. Use this for site-wide configuration (e.g. social URLs, footer text, contact info) that does not belong on a single post. |
wppilot/pods-create-taxonomyCreate Pods Taxonomy | Creates a brand-new Pods-managed Taxonomy. To attach Pods fields to an existing taxonomy (category, post_tag, third-party), use pods-extend-builtin instead. After creation, attach the taxonomy to one or more post types via the built_in_post_types_<post_type> options. |
wppilot/pods-edit-fieldEdit Pods Field | Updates an existing Pods field - label, type, weight, options. Pass only the keys you want to change. To rename, set new_name. |
wppilot/pods-edit-groupEdit Pods Field Group | Updates a field group: rename, re-label, reorder, change options. |
wppilot/pods-edit-itemEdit Pods Item | Updates field values on an existing item. Pass id for content pods (post_type, taxonomy, ACT). For settings pods the id is irrelevant - pass any integer; values are merged into the option storage. Only the keys present in data are touched; unset fields keep their existing value. |
wppilot/pods-edit-podEdit Pod | Updates an existing Pod definition - labels, description, public flags, supports, menu, REST settings, custom options. Pass only the keys you want to change; existing options are preserved. To rename the pod, set new_name (renames the post type / taxonomy / table accordingly). |
wppilot/pods-extend-builtinExtend Built-in WP Object with Pods | Registers a Pods-managed wrapper around an existing built-in object so you can attach Pods fields to it. Targets: existing post types (incl. post, page, attachment, third-party CPTs), existing taxonomies (category, post_tag, …), user, comment, and media. After the wrapper is created, attach fields with pods-create-field. |
Destructive Pods calls
| Ability | What it does |
|---|---|
wppilot/pods-delete-fieldDelete Pods Field | Deletes a Pods field. Removes the field schema; values stored for this field are wiped from the storage layer (postmeta / table column / option). Irreversible. |
wppilot/pods-delete-groupDelete Pods Field Group | Deletes a field group. By default fields in the group are preserved (re-parented to no group); pass delete_fields: true to delete them along with the group. |
wppilot/pods-delete-itemDelete Pods Item | Deletes a single pod item. For post-type and taxonomy pods the underlying WP post / term is also removed (posts go to trash, terms are deleted permanently). Pass delete_wp_object: false to keep the WP object and only wipe the Pods-managed data - useful when extending built-ins where the post is shared with other code. ACT items are always permanently removed (custom-table pods have no trash). |
wppilot/pods-delete-podDelete Pod | Deletes a Pod definition. By default the underlying WP objects (posts, terms, ACT rows) are preserved - pass delete_items: true to wipe them as well. Irreversible. |
For the task-level view of Pods, with worked requests and what to check afterwards, see Pods integration page.