> 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/meta-fields.md).

# Meta field groups, boxes & fields

Field group, meta box, and meta field definition abilities

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

ACPT's field system has three nested levels — a **field group** contains **meta boxes**, and each box contains **meta fields** — mirroring the [Field groups](/meta-fields/field-groups.md) and [The meta fields manager](/meta-fields/the-meta-fields-manager.md) UI. Each level has its own set of abilities.

{% hint style="info" %}
These abilities manage field **definitions** — the schema of what fields exist and their settings. To read or write the **values** stored on a specific post/term/user/option page, see [Field values](/integrations/abilities-api/field-values.md).
{% endhint %}

## Field groups

| Ability                  | What it does                                                         |
| ------------------------ | -------------------------------------------------------------------- |
| `acpt/list-meta-groups`  | Returns field groups, optionally filtered by name                    |
| `acpt/get-meta-group`    | Returns a single field group by name, including its boxes and fields |
| `acpt/save-meta-group`   | Creates a field group, or updates it if the name already exists      |
| `acpt/delete-meta-group` | Deletes a field group and everything it contains                     |

### acpt/list-meta-groups

**Input** (all optional)

| Property    | Type   | Description          |
| ----------- | ------ | -------------------- |
| `groupName` | string | Filter by group name |

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

### acpt/get-meta-group

**Input**

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

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

```json
{
  "success": true,
  "message": "Operation completed successfully.",
  "data": {
    "id": "b1e2c3d4-5678-4abc-9def-0123456789ab",
    "name": "movie-details",
    "label": "Movie Details",
    "belongs": [
      { "belongsTo": "POST_ID", "operator": "=", "find": "12", "logic": "AND" }
    ],
    "boxes": [ ]
  }
}
```

`belongs` describes the group's [location rules](/meta-fields/the-meta-fields-manager/group-settings.md) — where the group is attached. `find` and `operator` scope it further (e.g. to a specific post type or term).

### acpt/save-meta-group

**Input**

| Property  | Type   | Required | Notes                                                                                                                                                 |
| --------- | ------ | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
| `name`    | string | Yes      | If a group with this name already exists, it's **updated** instead of duplicated                                                                      |
| `label`   | string | No       |                                                                                                                                                       |
| `belongs` | array  | No       | Location rules, see above                                                                                                                             |
| `boxes`   | array  | No       | Full nested boxes/fields definition — you can also manage boxes and fields one at a time with the abilities below instead of resending the whole tree |

```php
$result = wp_get_ability('acpt/save-meta-group')->execute([
    'name'  => 'movie-details',
    'label' => 'Movie Details',
    'belongs' => [
        ['belongsTo' => 'POST_ID', 'find' => 'movie'],
    ],
]);
```

### acpt/delete-meta-group

**Input**

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

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

## Meta boxes

| Ability                | What it does                                                                         |
| ---------------------- | ------------------------------------------------------------------------------------ |
| `acpt/list-meta-boxes` | Returns the boxes in a given field group                                             |
| `acpt/get-meta-box`    | Returns a single box by name, including its fields                                   |
| `acpt/save-meta-box`   | Creates a box inside a group, or updates it if the name already exists in that group |
| `acpt/delete-meta-box` | Deletes a box (and its fields) from a group                                          |

{% hint style="info" %}
There's no ungrouped/global box listing — `acpt/list-meta-boxes` always requires a `group_name`.
{% endhint %}

### acpt/list-meta-boxes

**Input**

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

```php
$result = wp_get_ability('acpt/list-meta-boxes')->execute([
    'group_name' => 'movie-details',
]);
```

### acpt/get-meta-box

**Input**

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

```php
$result = wp_get_ability('acpt/get-meta-box')->execute([
    'name' => 'info',
]);
```

### acpt/save-meta-box

**Input**

| Property    | Type   | Required | Notes                                                                                        |
| ----------- | ------ | -------- | -------------------------------------------------------------------------------------------- |
| `groupName` | string | Yes      | The field group this box belongs to                                                          |
| `name`      | string | Yes      | If a box with this name already exists **in that group**, it's updated instead of duplicated |
| `new_name`  | string | No       | Renames the box                                                                              |
| `label`     | string | No       |                                                                                              |
| `fields`    | array  | No       | Meta field definitions, see [Meta fields](#meta-fields) below                                |

```php
$result = wp_get_ability('acpt/save-meta-box')->execute([
    'groupName' => 'movie-details',
    'name'      => 'info',
    'label'     => 'Info',
]);
```

### acpt/delete-meta-box

**Input**

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

```php
$result = wp_get_ability('acpt/delete-meta-box')->execute([
    'group_name' => 'movie-details',
    'name'       => 'info',
]);
```

## Meta fields

| Ability                  | What it does                                                                       |
| ------------------------ | ---------------------------------------------------------------------------------- |
| `acpt/list-meta-fields`  | Returns the field definitions attached to a given location                         |
| `acpt/get-meta-field`    | Returns a single field definition by box name and field name                       |
| `acpt/save-meta-field`   | Creates a field inside a box, or updates it if the name already exists in that box |
| `acpt/delete-meta-field` | Deletes a field definition from a box                                              |

### acpt/list-meta-fields

Unlike the other `list` abilities, this one is **scoped by location** rather than returning everything — it mirrors [`get_acpt_meta_field_objects()`](/developers/functions/get_acpt_meta_field_objects.md).

**Input**

| Property       | Type    | Required | Description                                                                                                   |
| -------------- | ------- | -------- | ------------------------------------------------------------------------------------------------------------- |
| `belongsTo`    | string  | Yes      | The location type these fields belong to (e.g. a custom post type, taxonomy, user, or option page identifier) |
| `find`         | string  | No       | Restrict to a specific location slug/id within `belongsTo`                                                    |
| `clonedFields` | boolean | No       |                                                                                                               |

```php
$result = wp_get_ability('acpt/list-meta-fields')->execute([
    'belongsTo' => 'customPostType',
    'find'      => 'movie',
]);
```

### acpt/get-meta-field

**Input**

| Property     | Type   | Required |
| ------------ | ------ | -------- |
| `box_name`   | string | Yes      |
| `field_name` | string | Yes      |

```php
$result = wp_get_ability('acpt/get-meta-field')->execute([
    'box_name'   => 'info',
    'field_name' => 'release_date',
]);
```

```json
{
  "success": true,
  "message": "Operation completed successfully.",
  "data": {
    "id": "c2d3e4f5-6789-4abc-9def-0123456789ab",
    "name": "release_date",
    "type": "Date",
    "defaultValue": null,
    "description": "The movie's theatrical release date",
    "isRequired": true,
    "showInArchive": false,
    "options": [],
    "visibilityConditions": [],
    "advancedOptions": [],
    "relations": [],
    "validationRules": [],
    "hasChildren": false
  }
}
```

### acpt/save-meta-field

**Input**

| Property               | Type         | Required | Notes                                                                                                                                                                                                                       |
| ---------------------- | ------------ | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `groupName`            | string       | Yes      | The field group this field belongs to                                                                                                                                                                                       |
| `boxName`              | string       | Yes      | The meta box this field belongs to                                                                                                                                                                                          |
| `name`                 | string       | Yes      | If a field with this name already exists **in that box**, it's updated instead of duplicated                                                                                                                                |
| `type`                 | string       | Yes      | One of ACPT's [field types](/meta-fields/field-types.md), written exactly as ACPT names it (case-sensitive): `Text`, `Textarea`, `Number`, `Date`, `Image`, `Select`, `Repeater`, `FlexibleContent`, `Post` (relational), … |
| `label`                | string       | No       | The field's label                                                                                                                                                                                                           |
| `new_name`             | string       | No       | Renames the field                                                                                                                                                                                                           |
| `parentName`           | string       | No       | Nests this field as a child of an existing Repeater/List field                                                                                                                                                              |
| `defaultValue`         | string\|null | No       |                                                                                                                                                                                                                             |
| `description`          | string       | No       |                                                                                                                                                                                                                             |
| `isRequired`           | boolean      | No       |                                                                                                                                                                                                                             |
| `showInArchive`        | boolean      | No       |                                                                                                                                                                                                                             |
| `options`              | array        | No       | For Select/Radio/Checkbox fields — see [Select, checkbox, and radio](/meta-fields/field-types/select-checkbox-and-radio.md)                                                                                                 |
| `visibilityConditions` | array        | No       | See [Conditional rendering](/meta-fields/the-meta-fields-manager/conditional-rendering-fields-settings.md)                                                                                                                  |
| `advancedOptions`      | array        | No       | See [Advanced options](/meta-fields/the-meta-fields-manager/advanced-options-fields-settings.md)                                                                                                                            |
| `relations`            | array        | No       | For Relational fields — see [Relational field](/meta-fields/field-types/relational-field.md)                                                                                                                                |
| `validationRules`      | array        | No       | See [Validation rules](/meta-fields/the-meta-fields-manager/validation-rules-fields-settings.md)                                                                                                                            |
| `children`             | array        | No       | Nested field definitions, for Repeater/List fields                                                                                                                                                                          |
| `blocks`               | array        | No       | Nested block definitions, for Flexible Content fields                                                                                                                                                                       |

```php
$result = wp_get_ability('acpt/save-meta-field')->execute([
    'groupName'   => 'movie-details',
    'boxName'     => 'info',
    'name'        => 'release_date',
    'type'        => 'Date',
    'description' => "The movie's theatrical release date",
    'isRequired'  => true,
]);
```

{% hint style="info" %}
Updating an existing field only changes the properties you send: everything else (options, advanced options, validation rules, children, …) is kept, and the field keeps its position in the box. Before ACPT 2.1.1, an updated field was moved to the bottom of its box.
{% endhint %}

### acpt/delete-meta-field

**Input**

| Property     | Type   | Required |
| ------------ | ------ | -------- |
| `group_name` | string | Yes      |
| `box_name`   | string | Yes      |
| `field_name` | string | Yes      |

```php
$result = wp_get_ability('acpt/delete-meta-field')->execute([
    'group_name' => 'movie-details',
    'box_name'   => 'info',
    'field_name' => 'release_date',
]);
```