> 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/developers/public-api.md).

# Public API (level 1)

Versioned PHP functions other plugins call to create field groups and write field values in bulk

The **Public API** is a small, versioned set of PHP functions that another plugin can call to write ACPT data without reaching into ACPT's internals. It was designed for importers and migration tools (ACPT Migrate uses it), but any plugin can call it.

{% hint style="info" %}
Available since **ACPT 2.1.10**, in ACPT **and** ACPT Lite, with no limits in Lite.
{% endhint %}

## Checking the level

`ACPT_PUBLIC_API_VERSION` holds the highest level the installed ACPT provides. Level 1 is the first one.

```php
if (defined('ACPT_PUBLIC_API_VERSION') && ACPT_PUBLIC_API_VERSION >= 1) {
    // the five level 1 functions are available
}
```

A released level never changes. New functions, options or row types will come as a new level, and a function is deprecated for at least one minor release before it is removed.

## The functions

| Function                                                                                                            | What it does                                                                       |
| ------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------- |
| [`save_acpt_meta_group_definition`](https://docs.acpt.io/developers/functions/save_acpt_meta_group_definition.md)   | Create one field group with its boxes and fields, under exactly the names you send |
| [`acpt_meta_group_exists`](https://docs.acpt.io/developers/functions/acpt_meta_group_exists.md)                     | Check whether a field group name is already taken                                  |
| [`bulk_save_acpt_meta_field_values`](https://docs.acpt.io/developers/functions/bulk_save_acpt_meta_field_values.md) | Write (or delete) many field values on posts in one call                           |
| [`get_acpt_field_storage_keys`](https://docs.acpt.io/developers/functions/get_acpt_field_storage_keys.md)           | Get the meta keys a field stores its value under                                   |
| [`flush_acpt_caches`](https://docs.acpt.io/developers/functions/flush_acpt_caches.md)                               | Clean caches and fire the hook after your write is committed                       |

## Rules every function follows

* **Your transaction stays yours.** No function opens, commits or rolls back a database transaction, runs DDL, or causes an implicit commit. If you roll back, everything ACPT wrote in that transaction is rolled back too.
* **No exceptions.** The functions never throw and never return a bare `false`. An unexpected internal failure is returned as a `WP_Error` with the code `acpt_db_error`.
* **No capability checks.** Check the current user's capabilities yourself before calling (for example `current_user_can('manage_options')`).
* **No field values in messages.** No error message and no hook payload contains a field value.
* **Stable error codes.** Branch on the error code, never on the message text.
* **Names are kept exactly.** ACPT never rewrites, lowercases or slugs a name you send.
* **IDs are strings.** Group, box and field IDs are UUID strings.

## Side effects wait for your commit

The two write functions (`save_acpt_meta_group_definition` and `bulk_save_acpt_meta_field_values`) fire no hooks and clean no caches, so no listener or cache ever sees a value you later roll back.

After your transaction is committed, call [`flush_acpt_caches`](https://docs.acpt.io/developers/functions/flush_acpt_caches.md) with the IDs of the posts you saved. It cleans their caches and fires [`acpt/bulk_saved_meta_values`](https://docs.acpt.io/developers/actions/acpt-bulk_saved_meta_values.md). If you skip it, listeners never hear about your write.

## A complete example

```php
global $wpdb;

if (!defined('ACPT_PUBLIC_API_VERSION') || ACPT_PUBLIC_API_VERSION < 1) {
    return;
}

// the function never merges into an existing group: stop if the name is taken
if (acpt_meta_group_exists('book_details')) {
    return;
}

$wpdb->query('START TRANSACTION');

// 1. create the field group
$group = save_acpt_meta_group_definition([
    'name'       => 'book_details',
    'label'      => 'Book details',
    'belongs_to' => [['post_type' => 'book']],
    'boxes'      => [
        [
            'name'   => 'book_box',
            'label'  => 'Book',
            'fields' => [
                ['name' => 'isbn', 'label' => 'ISBN', 'type' => 'Text'],
                ['name' => 'pages', 'label' => 'Pages', 'type' => 'Number'],
                ['name' => 'format', 'label' => 'Format', 'type' => 'Select', 'choices' => [
                    ['value' => 'hardcover', 'label' => 'Hardcover'],
                    ['value' => 'paperback', 'label' => 'Paperback'],
                ]],
            ],
        ],
    ],
]);

if (is_wp_error($group)) {
    $wpdb->query('ROLLBACK');
    return;
}

// 2. write values, using the field IDs returned above
$fields = $group['boxes']['book_box']['fields'];

$result = bulk_save_acpt_meta_field_values([
    ['object_type' => 'post', 'object_id' => 12, 'field_id' => $fields['isbn'],   'value' => '978-0-00-000000-0'],
    ['object_type' => 'post', 'object_id' => 12, 'field_id' => $fields['pages'],  'value' => 320],
    ['object_type' => 'post', 'object_id' => 12, 'field_id' => $fields['format'], 'value' => 'paperback'],
]);

if (is_wp_error($result)) {
    $wpdb->query('ROLLBACK');
    return;
}

$wpdb->query('COMMIT');

// 3. side effects, after the commit
flush_acpt_caches(['post' => [12]]);
```

## What's next

Level 2 is planned to add terms, users, comments and option pages to the bulk save, and more field settings (min, max, formats).
