> For the complete documentation index, see [llms.txt](https://docs.acpt.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.acpt.io/integrations/abilities-api/dynamic-blocks.md).

# Dynamic blocks

acpt/list-blocks, acpt/get-block, acpt/save-block, acpt/delete-block

Category: `acpt-content-model` · Default capability: `manage_options`

| Ability             | What it does                                              |
| ------------------- | --------------------------------------------------------- |
| `acpt/list-blocks`  | Returns every ACPT dynamic block                          |
| `acpt/get-block`    | Returns a single block by name                            |
| `acpt/save-block`   | Creates a block, or updates it if the name already exists |
| `acpt/delete-block` | Deletes a block                                           |

{% hint style="info" %}
These abilities manage a block's **definition** (its controls, TWIG template, availability) — not the content of any specific block instance placed in a post. See [Dynamic blocks → Introduction](/dynamic-blocks/dynamic-blocks.md) for the concepts and [TWIG reference](/dynamic-blocks/twig-reference.md) for templating.
{% endhint %}

## acpt/list-blocks

No input required.

```php
$result = wp_get_ability('acpt/list-blocks')->execute();
```

## acpt/get-block

**Input**

| Property | Type   | Required |
| -------- | ------ | -------- |
| `name`   | string | Yes      |

```php
$result = wp_get_ability('acpt/get-block')->execute([
    'name' => 'movie-hero',
]);
```

```json
{
  "success": true,
  "message": "Operation completed successfully.",
  "data": {
    "id": "a6b7c8d9-0123-4abc-9def-0123456789ab",
    "name": "movie-hero",
    "title": "Movie Hero",
    "category": "acpt",
    "icon": "cover-image",
    "css": null,
    "callback": null,
    "keywords": ["movie", "hero"],
    "postTypes": ["movie"],
    "controls": [
      {
        "id": "b7c8d9e0-1234-4abc-9def-0123456789ab",
        "name": "overlay_opacity",
        "label": "Overlay opacity",
        "type": "Range",
        "default": "50",
        "settings": {}
      }
    ],
    "scriptName": "movie_hero_block_js",
    "blockName": "acpt-dynamic-blocks/movie-hero",
    "supports": []
  }
}
```

{% hint style="info" %}
`icon` is usually a bare Dashicon slug string, but if the block was configured with a custom icon image in the block editor UI, it can also be an object (`{"background": "...", "foreground": "...", "src": "..."}`) instead.
{% endhint %}

## acpt/save-block

**Input**

| Property    | Type           | Required | Notes                                                                                                                                                                                               |
| ----------- | -------------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `name`      | string         | Yes      | If a block with this name already exists, it's **updated** instead of duplicated                                                                                                                    |
| `title`     | string         | Yes      |                                                                                                                                                                                                     |
| `category`  | string         | Yes      | The Gutenberg block category slug                                                                                                                                                                   |
| `icon`      | string         | Yes      | Any [Dashicon](https://developer.wordpress.org/resource/dashicons/) slug                                                                                                                            |
| `postTypes` | array\<string> | Yes      | Post types the block is available in                                                                                                                                                                |
| `controls`  | array          | Yes      | The block's editable controls — each item needs at least a `name`; `type` is one of `Checkbox`, `Radio`, `Select`, `SelectMulti`, `Toggle`, `Text`, `Textarea`, `Number`, `Range`, `Email`, `Phone` |
| `css`       | string\|null   | No       |                                                                                                                                                                                                     |
| `callback`  | string\|null   | No       |                                                                                                                                                                                                     |
| `keywords`  | array\|null    | No       |                                                                                                                                                                                                     |

```php
$result = wp_get_ability('acpt/save-block')->execute([
    'name'      => 'movie-hero',
    'title'     => 'Movie Hero',
    'category'  => 'acpt',
    'icon'      => 'cover-image',
    'postTypes' => ['movie'],
    'controls'  => [
        ['name' => 'overlay_opacity', 'label' => 'Overlay opacity', 'type' => 'Range', 'default' => '50'],
    ],
]);
```

## acpt/delete-block

**Input**

| Property | Type   | Required |
| -------- | ------ | -------- |
| `name`   | string | Yes      |

```php
$result = wp_get_ability('acpt/delete-block')->execute([
    'name' => 'movie-hero',
]);
```