Refresh a site's current state

POST

/v1/sites/{client_id}/heartbeat

<?php

$client = new \GuzzleHttp\Client();

$response = $client->request('POST', 'https://api.ai.wpengine.com/v1/sites/example/heartbeat', [
  'body' => '{ "site_info": { "active_plugins": [ "example" ], "php_version": "8.2.0", "wp_version": "6.5.0", "active_theme": "twentytwentyfour", "locale": "en_US", "server_software": "Apache/2.4.57", "db_version": "8.0.33", "memory_limit": "256M", "timezone": "America/Chicago", "active_plugin_count": 12, "ssl_valid": true, "is_multisite": false, "wp_debug": false }, "plugin_status": "active", "abilities": [ { "name": "example", "label": "example", "description": "example", "category": "example", "input_schema": {}, "output_schema": {}, "meta": {}, "run_url": "https://example.com" } ] }',
  'headers' => [
    'Authorization' => 'Bearer <token>',
    'Content-Type' => 'application/json',
  ],
]);

echo $response->getBody();

• Current environment

Reports current WordPress environment and plugin status. When abilities are included, they replace the site’s cached ability catalog. A registration that exists but is not currently active (for example, temporarily suspended) receives a 403 with error code site_not_active; that state is recoverable, and clients must not clear local credentials on it — only the explicit 404 site_authorization_revoked response is the revocation signal.

Authorizations

• bearerAuth

Parameters

Path Parameters

client_id

required

string

The OAuth client identifier of the reporting site.

Request Body^required

Media typeapplication/json

object

site_info

required

WordPress environment metadata collected by the plugin at registration time. All fields are optional.

object

active_plugins

Names of currently active WordPress plugins.

Array<string>

<= 500 items

php_version

string

<= 64 characters

Example

8.2.0

wp_version

string

<= 64 characters

Example

6.5.0

active_theme

string

<= 256 characters

Example

twentytwentyfour

locale

string

<= 64 characters

Example

en_US

server_software

string

<= 256 characters

Example

Apache/2.4.57

db_version

string

<= 64 characters

Example

8.0.33

memory_limit

string

<= 32 characters

Example

256M

timezone

string

<= 64 characters

Example

America/Chicago

active_plugin_count

Total number of active plugins on the site. May exceed len(active_plugins) when the plugin list was truncated at 500 items.

integer

Example

12

ssl_valid

boolean

Example

true

is_multisite

boolean

Example

false

wp_debug

boolean

Example

false

plugin_status

Power plugin lifecycle status. Omit this property when the heartbeat is sent by a shared auth consumer that does not own Power lifecycle.

string

Allowed values: active inactive

abilities

Current ability descriptors. Omit this property to leave the cached catalog unchanged; send an empty array to clear it.

Array<object>

object

name

required

string

label

string

description

string

category

string

input_schema

object

output_schema

object

meta

object

run_url

string format: uri

Responses

200

Site state was refreshed.

Media typeapplication/json

object

last_site_update_at

required

string format: date-time

plugin_status_updated_at

required

string format: date-time

abilities_synced_at

string format: date-time

abilities_sync_status

required

string

Allowed values: never_synced ok stale error

abilities_count

required

integer

plugin_status

required

string

Allowed values: active inactive

Example

{
  "abilities_sync_status": "never_synced",
  "plugin_status": "active"
}

400

Invalid request body or parameters

Media typeapplication/json

object

error

required

object

message

required

string

type

required

string

code

required

integer

request_id

required

Correlation ID for this request, matching the X-Request-ID response header — a 32-character trace ID behind the load balancer, otherwise a UUID. Quote it in support reports.

string

Example

{
  "error": {
    "type": "invalid_request_error",
    "request_id": "80f1e2c3a4b5c6d7e8f9a0b1c2d3e4f5"
  }
}

401

Missing or invalid bearer token

Media typeapplication/json

object

error

required

object

message

required

string

type

required

string

code

required

integer

request_id

required

Correlation ID for this request, matching the X-Request-ID response header — a 32-character trace ID behind the load balancer, otherwise a UUID. Quote it in support reports.

string

Example

{
  "error": {
    "type": "invalid_request_error",
    "request_id": "80f1e2c3a4b5c6d7e8f9a0b1c2d3e4f5"
  }
}

Headers

WWW-Authenticate

string

Example

Bearer realm="ai-services"

403

The token is valid, but the caller is not permitted to perform this action — either its scope/permission is insufficient or the authenticated user is not authorized for the target account (error type “permission_error”). On /v1/chat/completions specifically, a 403 with error type “content_policy_violation” instead means the request content was blocked by content moderation policy; that response never identifies which filter or category matched.

Media typeapplication/json

object

error

required

object

message

required

string

type

required

string

code

required

integer

request_id

required

Correlation ID for this request, matching the X-Request-ID response header — a 32-character trace ID behind the load balancer, otherwise a UUID. Quote it in support reports.

string

Example

{
  "error": {
    "type": "invalid_request_error",
    "request_id": "80f1e2c3a4b5c6d7e8f9a0b1c2d3e4f5"
  }
}

404

The authenticated site’s authorization has been revoked or no longer exists. The response error code is site_authorization_revoked; clients may use that explicit code to clear local credentials.

Media typeapplication/json

object

error

required

string

Allowed values: site_authorization_revoked

message

required

string

Example

{
  "error": "site_authorization_revoked",
  "message": "this site's authorization has been revoked"
}

413

Request body exceeds the 64 KiB limit

Media typeapplication/json

object

error

required

object

message

required

string

type

required

string

code

required

integer

request_id

required

Correlation ID for this request, matching the X-Request-ID response header — a 32-character trace ID behind the load balancer, otherwise a UUID. Quote it in support reports.

string

Example

{
  "error": {
    "type": "invalid_request_error",
    "request_id": "80f1e2c3a4b5c6d7e8f9a0b1c2d3e4f5"
  }
}