Pro module21 abilities
Ninja Forms
These abilities register when Ninja Forms 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
Ninja Forms registers 21 abilities: 10 that only read, 7 that write, and 4 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
Create and manage Ninja Forms forms, fields, notifications, settings, and submissions with field-type schema discovery.
Before you rely on it: Use test submissions to validate calculations, actions, and delivery after structural edits.
Typical workflows
- Draft a form from the available field types
- Review notifications before editing recipients
- Inspect submissions without exposing unrelated site data
The Ninja Forms 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 Ninja Forms 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/ninja-forms-check-setupCheck Ninja Forms Setup | Reports the Ninja Forms runtime state. Returns the plugin version, the minimum version WPPilot Pro accepts, whether the NF3 storage tables exist, the number of forms on this install, the number of field types the install can build, the capability flags for the current user, and site-global anti-spam integration flags (hCaptcha / reCAPTCHA / Turnstile). Call this FIRST before any other ninja-forms-* ability so the agent can fail fast when Ninja Forms is inactive, below the minimum version, or has not finished its NF3 upgrader. All Ninja Forms management (forms / fields / notifications / submissions) is driven through the WPPilot ninja-forms-* abilities — this integration does not require the native ninjaforms/* abilities. |
wppilot/ninja-forms-get-field-type-schemaGet Ninja Forms Field Type Schema | Describe one Ninja Forms field type — its human label, its editor section, and the WHITELIST of setting keys add-field / edit-field accept under the field descriptor for that type (e.g. label, label_pos, required, default, placeholder, classes, key, …). Call wppilot/ninja-forms-get-field-types-schema first for the catalog of available type slugs, then this ability per chosen type before crafting an add-field payload. Returns ninja_forms_field_type_not_found when the slug is not registered on this install (the add-on that provides it is inactive). |
wppilot/ninja-forms-get-field-types-schemaList Ninja Forms Field Types | Return the catalog of every Ninja Forms field type this install can build via add-field / edit-field. Output is compact: per entry {type, label, category, pro_only}. Use this FIRST when constructing a form, then call wppilot/ninja-forms-get-field-type-schema for the per-type supported-settings whitelist. The catalog is read from the live Ninja Forms field registry (Ninja_Forms()->fields), so it already reflects whichever add-ons are installed — a type only appears when the install can actually render it, so pro_only is always false and pro_active is always true (Ninja Forms has no single Lite/Pro edition split; payment / extra types come from separate add-ons and simply are or are not in the registry). category is the Ninja editor section (common / userinfo / misc / layout / other). Mirrors the catalog-vs-detail pattern used by gravityforms-get-field-types-schema, wpforms-get-field-types-schema, fluentforms-get-field-types-schema, formidable-get-field-types-schema. |
wppilot/ninja-forms-get-formGet a Ninja Forms Form | Fetch one Ninja Forms form by id. Always returns the compact attributes {id, title, key, created_at, updated_at, fields_count, actions_count, submissions_count}. The heavy blocks are OPT-IN via the include array — progressive disclosure keeps the default payload small. Valid include values: "fields" (each field as {id, type, key, label, required, order, settings} where settings is the full per-field settings map, including list-field options), "actions" (each action as {id, type, label, active, settings}), "settings" (the full form-level settings object). Returns ninja_forms_form_not_found (404) when the id is absent. |
wppilot/ninja-forms-get-form-canonicalGet Ninja Forms Form (Canonical) | Reads a single Ninja Forms form by id and returns it mapped to the plugin-agnostic form-model-schema vocabulary (17 canonical types: text/email/tel/url/number/textarea/date/time/datetime/select/radio/checkbox/file/hidden/submit/consent/group) used by the form-model-migration skill. Reads the form through the WPPilot-native Ninja Forms model layer (the same source as ninja-forms-get-form), then folds the Ninja field shape onto the 17 canonical types: composites (firstname + lastname flat, address + address2 + city + zip flat) emit warnings[] because Ninja does not nest them; native list types (listcheckbox, listradio, listselect, listmultiselect, listcountry, liststate, listimage, listmodifier) map to canonical select / radio / checkbox with cardinality; Ninja-specific UI types without a canonical equivalent (starrating, signature, quantity, product, shipping, total, creditcard*) emit warnings[] with severity structural; anti-spam types (hcaptcha, recaptcha, recaptchav3, turnstile, spam, timedsubmit) emit warnings[] with severity informational. Output keys: fields[] with canonical types, mail_config{} from the first email-action (the first actions[] entry with type: "email"), notifications[] from the remaining email-actions, messages{} from the form-level success / error / spam strings, meta{} (source plugin + version + edition + non-email actions echo for round-trip), plus warnings[] for everything that does not fit the canonical shape (composite collapse, Pro / spam fields, redirect actions, save-action, multi-action forms). Honours the max_field_bytes truncation contract (default 8192 bytes for mail_config.body, notifications[].body, with *_truncated flags); pass max_field_bytes: 0 to disable truncation when full-fidelity canonical is required before an execute-mode migration. Returns WP_Error ninjaforms_form_not_found when the id does not exist. Use this ability inside the form-model-migration workflow (Phase 2 — read source schema); for ad-hoc inspection of the Ninja-native shape, use ninja-forms-get-form (include=["fields","actions","settings"]). |
wppilot/ninja-forms-get-notificationGet a Ninja Forms Notification | Fetch one email notification by id with its FULL settings (recipient, subject, message body, from/reply-to, cc/bcc, format). Required: form_id, notification_id. Secret-looking setting values are redacted and has_secrets flags whether any were; large string values (the message body) are byte-capped at max_field_bytes (default 8192, 0 disables). Returns ninja_forms_notification_not_found (404) when the id is not an email action on this form. Returns {form_id, notification: {id, type, label, active, settings, has_secrets}}. |
wppilot/ninja-forms-get-submissionGet a Ninja Forms Submission | Fetch one Ninja Forms submission by id with its decoded field answers. Required: form_id, submission_id (the submission MUST belong to form_id, else ninja_forms_submission_not_found). Optional: fields (a whitelist of field keys — only those answers are returned); max_field_bytes (per-answer byte cap, default 8192, 0 disables — large textarea / file values are truncated with a marker and a full_size). No-value display fields (submit / html / hr / note) are omitted. Returns {form_id, submission_id, seq_num, status, date, answers: [{field_id, field_key, label, value, truncated, full_size}]}. |
wppilot/ninja-forms-list-formsList Ninja Forms | List the Ninja Forms on this site, paginated, as compact rows: {id, title, key, fields_count, actions_count, submissions_count, created_at, updated_at}. The field / action / submission counts are accurate live counts (not the cached nf3_forms.subs column). Does NOT return field or action definitions — call ninja-forms-get-form (with include) for one form's full shape. Optional search filters by title substring. Pagination: page (default 1), per_page (default 25, max 200). Returns {forms: [...], pagination: {page, per_page, total, total_pages}}. |
wppilot/ninja-forms-list-notificationsList Ninja Forms Notifications | List every email notification on a Ninja Forms form. A notification is a Ninja "email" action; the other action types (redirect / success message / save / webhook) are NOT returned here — read them via ninja-forms-get-form (include=["actions"]). Required: form_id. Returns {form_id, notifications: [{id, label, active, to, subject, form_id}]} — compact rows (no message body / headers); call ninja-forms-get-notification for the full settings. Includes both active and inactive notifications (branch on active). |
wppilot/ninja-forms-list-submissionsList Ninja Forms Submissions | List the submissions of a Ninja Forms form, newest first. Submissions are nf_sub posts. Required: form_id. Optional: status ("active" = live submissions [default], "trashed", or "any"); per_page (default 25, max 100); page (1-based). Returns COMPACT rows {id, seq_num, status, date, form_id} with NO field values — call ninja-forms-get-submission for the decoded answers of one. Includes a pagination block {page, per_page, total, total_pages}. |
Writes
Gated by the active profile and your WordPress capabilities. Rate limited to 120 per minute per credential.
| Ability | What it does |
|---|---|
wppilot/ninja-forms-add-fieldAdd a Ninja Forms Field | Add one field to an existing Ninja Forms form. Required: form_id, type (a slug from ninja-forms-get-field-types-schema — an unknown type fails with ninja_forms_invalid_input). Optional: label, key (auto-derived from the label when omitted, made unique per form — read the returned key back, do not guess), required (bool), order (1-based position; omit to append at the end), settings (object of extra per-type setting keys, e.g. placeholder / default / options for list fields; see ninja-forms-get-field-type-schema for the whitelist). Returns the new field as a compact row {id, type, key, label, required, order, form_id} plus warnings[] (e.g. a key that was uniquified). Does NOT auto-add a submit button — that is a create-form concern. Use ninja-forms-get-form (include=["fields"]) for the full per-field settings afterwards. |
wppilot/ninja-forms-create-formCreate a Ninja Forms Form | Create a new Ninja Forms form. Required: title (non-empty string). Optional: fields[] — each {type (required, must be a slug from ninja-forms-get-field-types-schema), label?, key? (auto-derived from label when omitted, made unique per form), required? (bool), settings? (object of extra per-type settings)}; actions[] — each {type (e.g. "email", "successmessage", "redirect"), label?, active? (bool, default true), settings? (object)}. A submit button is appended automatically when fields are supplied and none is of type "submit" (a Ninja form is unusable without one). Field types are validated up front — an unknown type fails the whole call with ninja_forms_invalid_input. Returns the new form as a compact row {id, title, key, fields_count, actions_count, submissions_count, created_at, updated_at} plus warnings[] (auto-added submit, derived/uniquified keys). |
wppilot/ninja-forms-create-notificationCreate a Ninja Forms Notification | Add an email notification to a form. Required: form_id, to (recipient — an email address or a Ninja merge tag like {field:email}). Optional: subject, message (the body), label (admin name), active (bool, default true), and settings (an object of extra native email-action keys, e.g. from_name, from_address, reply_to, cc, bcc, email_format — see ninja-forms-get-notification on an existing one for the shape). The friendly subject/message map to the native email_subject/email_message keys. Returns the new notification as a compact row {id, label, active, to, subject, form_id}. |
wppilot/ninja-forms-duplicate-formDuplicate a Ninja Forms Form | Duplicate an existing Ninja Forms form — copies the form settings, every field, and every action into a brand-new form (submissions are NOT copied). Uses Ninja Forms' own synchronous duplication, so the copy is complete and immediately readable. By default the new title is "<original> - copy"; pass new_title to set it explicitly. Returns the new form as a compact row. Returns ninja_forms_form_not_found (404) when the source id is absent. |
wppilot/ninja-forms-edit-fieldEdit a Ninja Forms Field | Partial-merge edit of one field on a form. Identify the field by field_id (numeric) OR field_key (slug from get-form) — field_id wins when both are given; the field MUST belong to form_id (a stray id/key returns ninja_forms_field_not_found). Mutable: label, key (renamed key is uniquified per form), required (bool), order, and settings (an object merged onto the field's current settings — only the keys you pass are touched). The type is NOT mutable (Ninja re-renders unpredictably on a type swap) — delete the field and add-field a new one instead; a type key inside settings is ignored. Returns the updated compact field + the list of changed setting keys (idempotent: a no-op re-run returns an empty changed[]). |
wppilot/ninja-forms-edit-formEdit a Ninja Forms Form | Edit the FORM-LEVEL settings of an existing Ninja Forms form — a shallow merge: only the keys you pass are touched, the rest are preserved. Pass title to rename, and/or settings (an object of form-level setting keys, e.g. {default_label_pos, show_title, clear_complete, success message keys}). This ability does NOT touch fields or actions — use ninja-forms-add-field / edit-field / delete-field for fields and ninja-forms-create-notification / edit-notification for notifications; passing a fields or actions key here is rejected with ninja_forms_invalid_input. Returns the updated compact form + the list of changed setting keys. Returns ninja_forms_form_not_found (404) when the id is absent. |
wppilot/ninja-forms-edit-notificationEdit a Ninja Forms Notification | Partial-merge edit of one email notification. Required: form_id, notification_id. Optional (only the keys you pass are touched): to, subject, message, label, active, and settings (merged onto the action's current settings). The friendly subject/message map to email_subject/email_message. The action type stays "email" (not mutable). Returns ninja_forms_notification_not_found (404) when the id is not an email action on the form. Returns {notification, changed} (idempotent: a no-op re-run returns an empty changed[]). |
Destructive
Marked destructive in the source, so each call needs an explicit confirmation flag, every time.
| Ability | What it does |
|---|---|
wppilot/ninja-forms-delete-fieldDelete a Ninja Forms Field | Permanently delete one field from a form. Identify it by field_id (numeric) OR field_key (slug from get-form); the field MUST belong to form_id. Idempotent: deleting an already-missing field is a no-op that returns deleted=false (re-running is safe, not a 404). The field row and its nf3_field_meta rows are removed by the model layer; there is no soft-delete / trash for fields. Note a Ninja form needs a submit field to be usable — do not delete the only submit unless you are replacing it. |
wppilot/ninja-forms-delete-formDelete a Ninja Forms Form | Permanently delete a Ninja Forms form by id. This CASCADES: the form, all its fields, all its actions, AND all its submissions are removed (Ninja Forms has no per-form trash — deletion is immediate and irreversible). Idempotent: deleting a form that does not exist returns {deleted: false} rather than an error, so a retry is safe. Returns {deleted: bool, form_id}. |
wppilot/ninja-forms-delete-notificationDelete a Ninja Forms Notification | Permanently delete one email notification from a form. Required: form_id, notification_id. Idempotent: deleting an already-missing notification (or an id that is not an email action) is a no-op that returns deleted=false. To temporarily silence a notification without losing it, use ninja-forms-edit-notification with active=false instead. Returns {form_id, notification_id, deleted}. |
wppilot/ninja-forms-delete-submissionDelete a Ninja Forms Submission | Delete one submission of a form. Required: form_id, submission_id (must belong to form_id). By default the submission is TRASHED (reversible — restore it from the WordPress admin or via wppilot/execute-php wp_untrash_post). Pass force=true to PERMANENTLY delete it (the nf_sub post + all its _field_* postmeta, no undo). Idempotent: deleting an already-missing submission, or re-trashing an already-trashed one, is a no-op that returns deleted=false. Returns {form_id, submission_id, deleted, permanent}. |