Use the Abilities API from PHP and the REST API

Run any Advanced Media Offloader ability from your own code: from PHP, from WP-CLI, or over the WordPress REST API. You need WordPress 6.9 or later, Advanced Media Offloader 4.7.0 or later, and an administrator account.

Use it from PHP

Call any ability after WordPress has loaded. Permissions are checked for the current user.

$ability = wp_get_ability( 'advmo/get-attachment-status' );
$result  = $ability->execute( array( 'attachment_ids' => array( 123, 456 ) ) );

if ( is_wp_error( $result ) ) {
    error_log( $result->get_error_message() );
    return;
}

foreach ( $result['attachments'] as $attachment ) {
    // $attachment['offloaded'], $attachment['url'], $attachment['errors'] ...
}

From WP-CLI, run it as an administrator with --user:

wp eval 'print_r( wp_get_ability( "advmo/get-status" )->execute() );' --user=admin

Use it from the REST API

Every ability runs at this address:

/wp-json/wp-abilities/v1/abilities/{ability-name}/run

Use normal WordPress REST authentication, such as an Application Password.

• Abilities that only read data (get-status, get-attachment-status, list-offload-errors, get-bulk-offload-status) use GET. Send input as query parameters, for example ?input[page]=2.
• All other abilities use POST with a JSON body: {"input": ...}.
• The wrong method returns HTTP 405.

To list every ability this plugin adds, call GET /wp-json/wp-abilities/v1/abilities?category=advmo-media.

Examples

Get the plugin status:

curl -u "your-username:your-application-password" \
  https://example.com/wp-json/wp-abilities/v1/abilities/advmo/get-status/run

Check two files. GET input goes in the query string. The -g option stops curl from reading the brackets as a pattern:

curl -g -u "your-username:your-application-password" \
  "https://example.com/wp-json/wp-abilities/v1/abilities/advmo/get-attachment-status/run?input[attachment_ids][]=123&input[attachment_ids][]=456"

Offload two files:

curl -X POST -u "your-username:your-application-password" \
  -H "Content-Type: application/json" \
  -d '{"input": {"attachment_ids": [123, 456]}}' \
  https://example.com/wp-json/wp-abilities/v1/abilities/advmo/offload-attachments/run

Start a bulk offload. Abilities without input take null:

curl -X POST -u "your-username:your-application-password" \
  -H "Content-Type: application/json" \
  -d '{"input": null}' \
  https://example.com/wp-json/wp-abilities/v1/abilities/advmo/start-bulk-offload/run

Cancel it, using the run_id from the start response:

curl -X POST -u "your-username:your-application-password" \
  -H "Content-Type: application/json" \
  -d '{"input": {"run_id": "3f2b9c1e-8a4d-4c6b-9e2f-1a2b3c4d5e6f"}}' \
  https://example.com/wp-json/wp-abilities/v1/abilities/advmo/cancel-bulk-offload/run

Example response

This is a response from advmo/get-status:

{
  "version": "4.7.0",
  "provider": "cloudflare_r2",
  "provider_available": true,
  "last_connection_test": null,
  "settings": {
    "auto_offload_uploads": true,
    "retention_policy": 1,
    "mirror_delete": true,
    "object_versioning": false
  },
  "counts": {
    "total": 1240,
    "offloaded": 1180,
    "not_offloaded": 60,
    "errors": 2
  }
}

retention_policy is 0 for Retain Local Files, 1 for Smart Local Cleanup, and 2 for Full Cloud Migration. last_connection_test is null until a test is saved for the selected provider.

For every ability’s input, results, and status values, see the Abilities Reference.

Troubleshooting

• HTTP 404 “Ability not found”. Check that you have WordPress 6.9 or later and Advanced Media Offloader 4.7.0 or later, and check the ability name.
• HTTP 405. Abilities that read data need GET. All other abilities need POST.
• HTTP 400 “invalid input”. Check the input format. For GET, send input as query parameters (input[attachment_ids][]=123), not as a JSON string.
• HTTP 401 or 403. The user is not an administrator, the Application Password is wrong, or the user cannot edit one of the files.

Related

• Abilities Reference
• Connect an AI Assistant
• Development Hooks: actions and filters to change how offloading works.