Register or update a WordPress site

POST

/v1/sites

<?php

$client = new \GuzzleHttp\Client();

$response = $client->request('POST', 'https://api.ai.wpengine.com/v1/sites', [
  'body' => '{ "site_url": "https://example.wpengine.com", "display_name": "My Blog", "project_id": "proj_01abc", "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 } }',
  'headers' => [
    'Authorization' => 'Bearer <token>',
    'Content-Type' => 'application/json',
  ],
]);

echo $response->getBody();

• Current environment

Registers a WordPress site with the AI Gateway, or updates an existing registration for the same site. The caller must authenticate with a WP Engine oauth-ext access token obtained via Dynamic Client Registration (RFC 7591). The gateway returns a stable site_id for the logical site; client_id continues to identify the current OAuth registration. Re-registering the same OAuth client updates its metadata in place. Request body is capped at 64 KiB. Unknown JSON fields are rejected. Returns 409 if the token’s account_id differs from the account that originally registered the client_id (ownership conflict), or if an existing client moves to a site_url already owned by another site in the same account.

Authorizations

• bearerAuth

Request Body^required

Media typeapplication/json

object

site_url

required

Fully-qualified URL of the WordPress site (scheme + host required). Longer than 2048 bytes is rejected with 400.

string format: uri

<= 2048 characters

Example

https://example.wpengine.com

display_name

Human-readable name for the site, at most 255 characters (characters, not bytes — multi-byte names are measured the same way). Optional; defaults to site_url, truncated to fit.

string

<= 255 characters

Example

My Blog

project_id

WP Engine project to associate the site with. Optional — omit when the site is not scoped to a project.

string

<= 64 characters

Example

proj_01abc

site_info

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

Responses

200

Site registered or updated. Returns the stable site_id, client_id, registration status, the original creation timestamp (unchanged on updates), and the per-site HMAC secret for anonymous user identification.

Media typeapplication/json

object

site_id

required

Stable gateway-owned identifier for the logical site.

string

/^site_[0-9A-Za-z]{22}$/

client_id

required

The current Dynamic Client Registration credential identifier for the site. It can change when the site reconnects.

string

status

required

Current registration status of the site.

string

Allowed values: active revoked suspended

created_at

required

When the site was first registered (UTC). Unchanged on subsequent updates to the same site.

string format: date-time

site_hmac_secret

required

Per-site HMAC secret for deriving anonymous user identifiers. 32 random bytes hex-encoded (64 chars). Preserved across re-registrations. The plugin must store this securely and never send it back to the gateway.

string

/^[0-9a-f]{64}$/

Example

{
  "site_id": "site_01AbCdEfGhIjKlMnOpQrSt",
  "client_id": "client_01abc",
  "status": "active",
  "created_at": "2024-01-15T10:30:00Z",
  "site_hmac_secret": "abcd1234abcd1234abcd1234abcd1234abcd1234abcd1234abcd1234abcd1234"
}

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"

409

The request conflicts with an existing resource

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"
  }
}

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"
  }
}

503

A required dependency is temporarily unavailable. Retry after a short delay with exponential back-off.

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"
  }
}