A flexible-content field is a repeater whose rows have types. Each row is a layout with its own sub-fields, chosen from the set the field defines — which means you cannot add a row without saying which layout it is.
custom-fields/add-acf-flex-layout appends a named layout, or inserts it at a 1-based position, with its sub-field values in the same call.
At a glance
| Ability | custom-fields/add-acf-flex-layout |
| Toolset | Advanced Custom Fields — toolset/acf |
| Group | Repeater & Flexible Content |
| Requires | Advanced Custom Fields Pro, plus a flexible-content field registered on the site |
| Capability | manage_options |
| Safety | Writes data |
| Repeatable | Not idempotent — each call changes the row set, so re-running is not a no-op |
| Ships in | AcrossAI Abilities Manager 0.0.34 and later |
How it works
The layout name has to be one the field actually defines. Ask custom-fields/get-acf-field for the field, or blocks/get-acf-block-fields when the flexible-content field sits behind an ACF block — both report the available layouts and the sub-fields under each.
Pointed at a plain repeater, the call is rejected with a typed error rather than guessing. Plain repeaters have no layouts; use custom-fields/add-acf-repeater-row for those.
As with repeater rows, appending is a single targeted write and inserting at a position rewrites the array to make room.
Input
| Name | Type | Required | What it is |
|---|---|---|---|
target_type | string | No — defaults to post | What the value is attached to: post, user, term, comment or option. post covers pages and any custom post type. |
target_id | integer | string | Yes, for post, user, term and comment | The ID of the target. Optional for option, where it names a specific options page; omit it for the default options store. |
selector | string | Yes | Repeater or flexible-content field name (e.g. cards) or field key. |
layout | string | Yes | Name of the layout to add, as the flexible-content field defines it. |
values | object | No | Sub-field name => value for the new layout. |
position | integer | No | 1-based position to insert at. Omit to append. |
apply_wp_slash | boolean | No — defaults to true | Runs wp_slash() over your strings before writing, so literal backslashes survive. Set it false only when you have already slashed the payload yourself. |
What comes back
| Name | Type | What it is |
|---|---|---|
index | integer | Where the layout landed, 1-based. |
layout | string | The layout that was added. |
row_count | integer | How many rows the field holds now. |
success | boolean | Whether the call completed. |
message | string | A one-line summary of what happened, suitable for showing a human. |
error_code | string | Present only on failure — a stable machine-readable reason, such as a missing field, a wrong field type or an unmet confirmation. |
Example
Ask your assistant:
Add a testimonial section to the page_sections flexible content on page 87, quoting Maya at Northwind.
It resolves to one call:
{
"ability": "custom-fields/add-acf-flex-layout",
"parameters": {
"target_type": "post",
"target_id": 87,
"selector": "page_sections",
"layout": "testimonial",
"values": {
"quote": "We shipped in a week instead of a quarter.",
"attribution": "Maya, Northwind"
}
}
}Worth knowing
- Not idempotent. A retry adds a second layout — read the field before retrying a call whose outcome you are unsure of.
- Sub-field names differ per layout. Two layouts can both have a
titleand mean different things, so read the layout’s own fields rather than assuming. - Requires ACF Pro. Flexible content is a Pro-only field type, so there is nothing to act on in the free edition.
Related abilities
- Get ACF Field Value — list the layouts the field defines
- Remove Flexible Content Layout — take one back out
- Add Repeater Row — for a plain repeater with no layouts
Get the plugins:
AcrossAI Abilities Manager · AcrossAI MCP Manager
Browse the rest: Every ability, by category