> For the complete documentation index, see [llms.txt](https://kb.craftformswp.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://kb.craftformswp.com/documentation/for-developers/wp-abilities-api.md).

# WP Abilities API

This page contains information for developers related to WP Abilities API included in CraftForms

CraftForms registers abilities with the [WordPress Abilities API](https://developer.wordpress.org/apis/abilities-api/) (introduced in WordPress 6.9). This allows AI assistants and automation tools that are aware of the Abilities API to discover and interact with CraftForms programmatically — creating forms, adding fields, and more — without requiring custom code or direct database access.

***

### Requirements <a href="#requirements" id="requirements"></a>

* WordPress 6.9 or later
* CraftForms (any version)
* The user making requests must be logged in. Per-ability permissions are listed below (`craftforms_access` is granted to Administrator, Editor, and Shop Manager by default — filterable via `craftforms_access_roles`)

***

### Registered Abilities <a href="#registered-abilities" id="registered-abilities"></a>

#### `craftforms/create-form` <a href="#craftformscreate-form" id="craftformscreate-form"></a>

Creates a new CraftForms form with optional price formula, transformations, and submit actions.

**Inputs**

| Parameter         | Type    | Required | Description                                                                                                                               |
| ----------------- | ------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
| `title`           | string  | ✓        | Form title                                                                                                                                |
| `description`     | string  |          | Short description shown in the form picker                                                                                                |
| `formula`         | string  |          | Jexl price formula (e.g. `base_price * qty`)                                                                                              |
| `transformations` | array   |          | Transformation definitions (see [Form Meta reference](/documentation/for-developers/ai-form-builder-guide.md#form-meta-schema-reference)) |
| `submit_actions`  | array   |          | Submit action definitions (defaults to `save_submission` if omitted)                                                                      |
| `send_emails`     | boolean |          | Enable email notifications on submit (default: `true`)                                                                                    |
| `create_entries`  | boolean |          | Save submissions to the database (default: `true`)                                                                                        |

**Output**

| Field      | Type    | Description                                                                     |
| ---------- | ------- | ------------------------------------------------------------------------------- |
| `form_id`  | integer | Post ID of the new form                                                         |
| `uuid`     | string  | Auto-generated form identifier (used as `data-craftforms-form` in the frontend) |
| `edit_url` | string  | Block-editor URL to open and further configure the form                         |

**Permission required:** `craftforms_access` (Administrator, Editor, Shop Manager by default)

***

#### `craftforms/add-field` <a href="#craftformsadd-field" id="craftformsadd-field"></a>

Appends a new input field to an existing form. The field is inserted as a properly structured Gutenberg block inside the form's block content, immediately before the submit button.

**Inputs**

| Parameter    | Type    | Required                      | Description                                                                    |
| ------------ | ------- | ----------------------------- | ------------------------------------------------------------------------------ |
| `form_id`    | integer | ✓                             | Post ID of the target form                                                     |
| `field_type` | string  | ✓                             | One of: `text`, `email`, `number`, `textarea`, `select`, `radio`, `checkboxes` |
| `name`       | string  | ✓                             | Machine-readable field name (no spaces, lowercase)                             |
| `label`      | string  | ✓                             | Human-readable field label shown above the input                               |
| `required`   | boolean |                               | Whether the field must be filled before submit                                 |
| `options`    | array   | ✓ for select/radio/checkboxes | Array of `{ label, value }` objects                                            |

**Output**

| Field        | Type    | Description                                |
| ------------ | ------- | ------------------------------------------ |
| `form_id`    | integer | ID of the updated form                     |
| `field_name` | string  | The `name` of the inserted field           |
| `block_html` | string  | The generated block HTML that was inserted |

**Permission required:** `edit_post` on the specific form (Editor or higher, or the form author)

***

### Example: Build a Contact Form with an AI Agent <a href="#example-build-a-contact-form-with-an-ai-agent" id="example-build-a-contact-form-with-an-ai-agent"></a>

An AI assistant that supports the WordPress Abilities API can build a complete form in two steps:

**Step 1 — Create the form:**

{% code collapsedlinecount="10" %}

```json
{
  "ability": "craftforms/create-form",
  "input": {
    "title": "Contact Us",
    "description": "Simple contact form with name, email, and message",
    "send_emails": true,
    "create_entries": true
  }
}
```

{% endcode %}

Response includes `form_id: 42`.

**Step 2 — Add fields:**

{% code collapsedlinecount="10" %}

```json
{ "ability": "craftforms/add-field", "input": { "form_id": 42, "field_type": "text",     "name": "name",    "label": "Your Name",    "required": true } }
{ "ability": "craftforms/add-field", "input": { "form_id": 42, "field_type": "email",    "name": "email",   "label": "Email Address", "required": true } }
{ "ability": "craftforms/add-field", "input": { "form_id": 42, "field_type": "textarea", "name": "message", "label": "Message",       "required": true } }
```

{% endcode %}

The form is now ready to embed on any page via the **CraftForms** block (selecting form ID 42).

***

### Discovering Abilities <a href="#discovering-abilities" id="discovering-abilities"></a>

WordPress registers the Abilities API REST routes under the `wp-abilities/v1` namespace:

{% code collapsedlinecount="10" %}

```
GET  /wp-json/wp-abilities/v1/abilities              # list
GET  /wp-json/wp-abilities/v1/abilities/{name}       # single ability
POST /wp-json/wp-abilities/v1/abilities/{name}/run   # execute
GET  /wp-json/wp-abilities/v1/categories             # categories
```

{% endcode %}

Filter by category to see only CraftForms abilities:

{% code collapsedlinecount="10" %}

```
GET /wp-json/wp-abilities/v1/abilities?category=craftforms
```

{% endcode %}

These endpoints return full input/output schema definitions, so AI tools can understand how to call each ability without additional documentation. **They are not public** — the list controller requires `current_user_can( 'read' )`, i.e. an authenticated user; `run` additionally enforces the ability's own `permission_callback`.

### Exposing the abilities over MCP <a href="#exposing-the-abilities-over-mcp" id="exposing-the-abilities-over-mcp"></a>

The Abilities API is a registry, not an MCP server. To let an MCP client (Claude, Cursor, etc.) discover and call these abilities, install the [WordPress MCP Adapter](https://github.com/WordPress/mcp-adapter) and register a server that allowlists them:

{% code collapsedlinecount="10" %}

```php
add_action( 'mcp_adapter_init', function ( $adapter ) {
    $adapter->create_server(
        'craftforms', 'craftforms-mcp', 'mcp',
        'CraftForms MCP Server',
        'Build and configure CraftForms forms from an AI agent.',
        '1.0.0',
        [ \WP\MCP\Transport\HttpTransport::class ],
        \WP\MCP\Infrastructure\ErrorHandling\ErrorLogMcpErrorHandler::class,
        null,
        [ 'craftforms/create-form', 'craftforms/add-field' ]
    );
} );
```

{% endcode %}

The endpoint becomes `POST /wp-json/craftforms-mcp/mcp`. Note that MCP tool names are slugified: `craftforms/create-form` is exposed as the tool **`craftforms-create-form`**.

***

### Notes for AI Agents <a href="#notes-for-ai-agents" id="notes-for-ai-agents"></a>

* After using `create-form`, the form has a scaffold with a submit button and notification block already in place. Use `add-field` to populate it with fields.
* Field `name` values must be unique within a form and use only lowercase letters, numbers, and underscores.
* For `radio` and `checkboxes`, always provide at least one option in the `options` array.
* For price-calculating forms (with `formula` and `transformations`), set those when creating the form — they live in form meta, not in field blocks. See the [AI Form Build Guide](/documentation/for-developers/ai-form-builder-guide.md) for the full meta schema and authoring conventions.