{ "openapi": "3.1.1", "info": { "title": "WP Cloud API", "version": "1.0.0", "description": "The Atomic API allows Automattic partners to manage their sites hosted on our WP Cloud infrastructure. These sites include the latest released version of WordPress and plugin and theme management, as well as client-specific configuration preferences. Client customers have additional access to their site via phpMyAdmin and password-based SFTP.\n\nClients are provided with a client identifier (generally, a lowercase string unique to that client), and both developer and platform API keys. The platform API key is intended for use in production management of sites via the Atomic API; developer keys are for per-person API operations during development. Requests to the Atomic API authenticate via the Auth: API_KEY header. API key access is restricted to specific allowed IPs." }, "externalDocs": { "description": "Find out more about WP Cloud", "url": "https://wp.cloud" }, "servers": [ { "url": "https://atomic-api.wordpress.com/api/v1.0/" } ], "paths": { "/migration/abort/{migration_id}": { "post": { "tags": [ "Migrations" ], "summary": "Abort Migration", "description": "Abort an active migration. Can be called from any resting state.", "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Response status message." } } } } } }, "400": { "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message." }, "data": { "description": "Error details, or an empty array when none are returned." } } } } }, "description": "Invalid migration ID or state transition not allowed." }, "403": { "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message." }, "data": { "description": "Error details, or an empty array when none are returned." } } } } }, "description": "Access denied." }, "404": { "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message." }, "data": { "description": "Error details, or an empty array when none are returned." } } } } }, "description": "Migration not found." } }, "parameters": [ { "name": "migration_id", "in": "path", "description": "Migration ID to abort.", "required": true, "schema": { "type": "number" } } ], "operationId": "post-migration-abort-migration_id" } }, "/custom-certificates/{site}/{custom_certificate_id}/activate": { "post": { "tags": [ "Custom SSL Certificates" ], "summary": "Activate a Staged Custom Certificate", "description": "Activate a previously staged custom SSL certificate for use on one or more domains.", "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Response status message." }, "data": { "type": "object", "description": "Activation result.", "properties": { "activated": { "type": "boolean", "description": "Whether the certificate was activated." }, "domains": { "type": "array", "items": { "type": "string" }, "description": "Domains the certificate was activated for." } } } }, "example": { "message": "OK", "data": { "activated": true, "domains": [ "example.com", "www.example.com" ] } } }, "examples": { "success-48c9d09c3195904ca7df8c6db0e8e9d4": { "summary": "Success-Response", "value": { "message": "OK", "data": { "activated": true, "domains": [ "example.com", "www.example.com" ] } } } } } } }, "400": { "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message." }, "data": { "description": "Error details, or an empty array when none are returned." } } } } }, "description": "Invalid site identifier or missing certificate ID." }, "403": { "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message." }, "data": { "description": "Error details, or an empty array when none are returned." } } } } }, "description": "Access denied." }, "404": { "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message." }, "data": { "description": "Error details, or an empty array when none are returned." } } } } }, "description": "Certificate not found." }, "500": { "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message." }, "data": { "description": "Error details, or an empty array when none are returned." } } } } }, "description": "ACME API error." } }, "parameters": [ { "name": "site", "in": "path", "description": "Site ID or domain.", "required": true, "schema": { "type": "string" } }, { "name": "custom_certificate_id", "in": "path", "description": "ID of the staged custom certificate to activate.", "required": true, "schema": { "type": "number" } } ], "operationId": "post-custom-certificates-site-custom_certificate_id-activate", "requestBody": { "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "properties": { "domains": { "type": "array", "items": { "type": "string" }, "description": "Optional list of domains to activate the certificate for. If omitted the site's primary domain is used." } } } } } } } }, "/client-meta/{client}/{key}/add": { "post": { "tags": [ "Client Meta" ], "summary": "Add Client Meta", "description": "Add a new client meta value.\n\nNote: `max_space_quota` is read-only and cannot be added.", "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Response status message." }, "data": { "type": "array", "description": "Empty array." } }, "example": { "message": "OK", "data": [] } }, "examples": { "success-530a19dfbccd73e4313006d96a3a22db": { "summary": "Success-Response", "value": { "message": "OK", "data": [] } } } } } }, "400": { "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message." }, "data": { "description": "Error details, or an empty array when none are returned." } }, "example": { "message": "Invalid key", "data": [] } }, "examples": { "error-713244277bf85619f15371801214cafd": { "summary": "Error-Response", "value": { "message": "Invalid key", "data": [] } }, "error-102ca70662283f52df157c810067533e": { "summary": "Error-Response", "value": { "message": "A value must be provided", "data": [] } } } } }, "description": "Invalid or unsupported meta key.\n\nA value must be provided.\n\nInvalid URL provided for webhook_url.\n\nInvalid value for default_privacy_model; must be \"wp_uploads\" or \"proxy\"." }, "403": { "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message." }, "data": { "description": "Error details, or an empty array when none are returned." } } } } }, "description": "Access denied or method not allowed for this key." }, "500": { "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message." }, "data": { "description": "Error details, or an empty array when none are returned." } } } } }, "description": "Internal server error." } }, "parameters": [ { "name": "client", "in": "path", "description": "Client name or ID.", "required": true, "schema": { "type": "string" } }, { "name": "key", "in": "path", "description": "Meta key.", "required": true, "schema": { "type": "string", "enum": [ "webhook_url", "webhook_secret_key", "client_ssh_default_from", "client_ssh_force_from", "client_ssh_firewall", "default_privacy_model", "webhook_hmac_key", "skip_force_backup_db" ] } } ], "operationId": "post-client-meta-client-key-add", "requestBody": { "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "properties": { "value": { "type": "string", "description": "Value to set for the meta key." } }, "required": [ "value" ] } } } } } }, "/crontab/{site}/add": { "post": { "tags": [ "Cron" ], "summary": "Add Cron Entry", "description": "Adds a cron entry for a site.\n\nA cron entry runs a `command` on the site according to a given `schedule`.\n\nA `schedule` is defined using the literals `hourly`, `daily`, `twicedaily` or `weekly`. Shorthand formats are also supported, such as `2h` (twice per hour), `6d` (six times per day), and `3w` (three times per week).\n\nIf the site or client supports the advanced cron feature, the `schedule` may be specified as a full crontab expression. For example, `*\\/2 * * * *` runs every two minutes.\n\nThe `command` is executed in an environment similar to an SSH, with utilities such as WP-CLI available. Shell scripts may be used for more complex logic or multi-step commands.\n\nThere are time and concurrency limits for cron entries:\n\n- Each cron entry has a maximum runtime of 8 hours.\n- A cron entry is skipped if its previous execution has not finished.\n- Up to three cron entries can run concurrently per site, additional ones will be postponed.\n\nA webhook named `site-cron-results` is sent if execution of a cron entry fails, either by exiting with a non-zero status code or by breaching concurrency limits.", "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Response status message." }, "data": { "type": "object", "description": "Response data.", "properties": { "cron_id": { "type": "number", "description": "Created cron entry ID." } } } }, "example": { "message": "OK", "data": { "cron_id": 96 } } }, "examples": { "success-ec188386f616deeb9d300440fdaab9a1": { "summary": "Success-Response", "value": { "message": "OK", "data": { "cron_id": 96 } } } } } } }, "400": { "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message." }, "data": { "description": "Error details, or an empty array when none are returned." } } } } }, "description": "Invalid or empty schedule or command, or schedule could not be parsed." }, "403": { "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message." }, "data": { "description": "Error details, or an empty array when none are returned." } } } } }, "description": "Access denied." }, "404": { "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message." }, "data": { "description": "Error details, or an empty array when none are returned." } } } } }, "description": "Site not found." }, "500": { "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message." }, "data": { "description": "Error details, or an empty array when none are returned." } } } } }, "description": "Database error." } }, "parameters": [ { "name": "site", "in": "path", "description": "Site ID or domain.", "required": true, "schema": { "type": "string" } } ], "operationId": "post-crontab-site-add", "requestBody": { "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "properties": { "schedule": { "type": "string", "description": "Cron schedule (hourly, daily, twicedaily, weekly, 2h, 3w, or crontab expression)." }, "command": { "type": "string", "description": "Command to run." } }, "required": [ "schedule", "command" ] } } } } } }, "/firewall-rules/{site}/add": { "post": { "tags": [ "Security" ], "summary": "Add Firewall Rule", "description": "Add a new firewall rule for a site.", "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Response status message." }, "data": { "type": "object", "description": "Created firewall rule.", "properties": { "rule_id": { "type": "number", "description": "Firewall rule ID." }, "direction": { "type": "string", "description": "Rule direction." }, "action": { "type": "string", "description": "Rule action." }, "protocol": { "type": "string", "description": "Protocol type." }, "port": { "type": "number", "description": "Port number." }, "destination": { "type": "string", "description": "Destination IP address or CIDR range." } } } }, "example": { "message": "OK", "data": { "rule_id": 2368992788, "direction": "egress", "action": "allow", "protocol": "tcp", "port": 3306, "destination": "10.20.30.40/32" } } }, "examples": { "success-869852e02880b264ac0533e4e469b758": { "summary": "Success-Response", "value": { "message": "OK", "data": { "rule_id": 2368992788, "direction": "egress", "action": "allow", "protocol": "tcp", "port": 3306, "destination": "10.20.30.40/32" } } } } } } }, "400": { "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message." }, "data": { "description": "Error details, or an empty array when none are returned." } } } } }, "description": "Invalid or missing rule fields, or rule limit (128) exceeded." }, "403": { "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message." }, "data": { "description": "Error details, or an empty array when none are returned." } } } } }, "description": "Access denied." }, "404": { "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message." }, "data": { "description": "Error details, or an empty array when none are returned." } }, "example": { "message": "Site not found", "data": [] } }, "examples": { "error-2e8bc8151370e5f700d95645938b0ec3": { "summary": "Error-Response", "value": { "message": "Site not found", "data": [] } } } } }, "description": "Site not found." }, "409": { "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message." }, "data": { "description": "Error details, or an empty array when none are returned." } } } } }, "description": "This rule already exists or conflicts with another rule." }, "500": { "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message." }, "data": { "description": "Error details, or an empty array when none are returned." } } } } }, "description": "Database error." } }, "parameters": [ { "name": "site", "in": "path", "description": "Site ID or domain.", "required": true, "schema": { "type": "string" } } ], "operationId": "post-firewall-rules-site-add", "requestBody": { "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "properties": { "direction": { "type": "string", "enum": [ "egress" ], "description": "Firewall rule direction (must be \"egress\")." }, "action": { "type": "string", "enum": [ "allow", "deny" ], "description": "Firewall rule action (default: \"allow\")." }, "protocol": { "type": "string", "enum": [ "tcp", "udp" ], "description": "Protocol type." }, "port": { "type": "number", "minimum": 1, "maximum": 65535, "description": "Port number." }, "destination": { "type": "string", "description": "Destination IP address or CIDR range." } }, "required": [ "direction", "action", "protocol", "port", "destination" ] } } } } } }, "/site-persist-data/{site}": { "post": { "tags": [ "Sites" ], "summary": "Add Persistent Site Data", "description": "Add or remove persistent key-value data for a site. Persistent data is preserved across site resets and clones. Parameters use PHP nested array form encoding: data[key][value]=... to set, data[key][delete]=1 to remove.", "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "response_ticket_id": { "type": "string", "description": "Response ticket ID to check on the status of this request." }, "job_id": { "type": "number", "description": "Deprecated. Internal job ID; unreliable indicator of success." }, "data": { "type": "object", "description": "Current persistent data for the site after applying the submitted changes." } } } } } } } }, "400": { "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message." }, "data": { "description": "Error details, or an empty array when none are returned." } } } } }, "description": "The data field is not a valid array." }, "404": { "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message." }, "data": { "description": "Error details, or an empty array when none are returned." } } } } }, "description": "Site not found." }, "429": { "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message." }, "data": { "description": "Error details, or an empty array when none are returned." } } } } }, "description": "Site data lock could not be acquired; retry after the Retry-After header value (10 seconds)." } }, "parameters": [ { "name": "site", "in": "path", "description": "Site ID or domain.", "required": true, "schema": { "type": "string" } } ], "operationId": "post-site-persist-data-site", "requestBody": { "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "properties": { "data": { "type": "object", "description": "Persistent data operations. Each entry is keyed by the data key to set or delete.", "properties": { "key": { "type": "object", "properties": { "value": { "type": "string", "description": "Value to store for this key. Example: data[foo][value]=business." }, "delete": { "type": "boolean", "description": "Set to 1 to delete this key. Example: data[bar][delete]=1." } } } } } } } } } } } }, "/ssh-user/{service}/{identifier}/add": { "post": { "tags": [ "SSH" ], "summary": "Add Site SSH/SFTP User", "description": "Create a new SSH/SFTP user for a site. Username must be 5+ characters and not all numbers. Password behavior: omit for random password, empty string for no password (key-only auth), or provide specific password. Allowed key types: ssh-rsa (2048-16384 bits), ecdsa-sha2-nistp256 (256 bits), ssh-ed25519 (256 bits).", "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Response status message." }, "data": { "type": "object", "description": "User credentials object.", "properties": { "user": { "type": "string", "description": "Username." }, "pass": { "type": "string", "description": "Generated password (empty for key-only authentication)." }, "pkey": { "type": "boolean", "description": "Whether the SSH public key was stored successfully." } } } }, "example": { "message": "OK", "data": { "user": "client-test", "pass": "--redacted--" } } }, "examples": { "success-900669a7449ba373d051d9ce6fda5b08": { "summary": "Success-Response", "value": { "message": "OK", "data": { "user": "client-test", "pass": "--redacted--" } } } } } } }, "400": { "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message." }, "data": { "description": "Error details, or an empty array when none are returned." } } } } }, "description": "Invalid site, service type, username, or SSH key format." }, "409": { "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message." }, "data": { "description": "Error details, or an empty array when none are returned." } } } } }, "description": "Username already exists for this site." }, "500": { "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message." }, "data": { "description": "Error details, or an empty array when none are returned." } } } } }, "description": "Database error." } }, "parameters": [ { "name": "service", "in": "path", "description": "Service type (client name, \"domain\" for domain lookup, or \"wpcom\" for WordPress.com blog ID).", "required": true, "schema": { "type": "string" } }, { "name": "identifier", "in": "path", "description": "Site identifier (domain for \"domain\" service, site ID for client, WordPress.com blog ID for \"wpcom\").", "required": true, "schema": { "type": "string" } } ], "operationId": "post-ssh-user-service-identifier-add", "requestBody": { "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "properties": { "user": { "type": "string", "description": "Username (5+ characters, not all numbers)." }, "pkey": { "type": "string", "description": "SSH public key (authorized_keys format)." }, "pass": { "type": "string", "description": "Password (omit for random, empty for key-only, or specific password)." } }, "required": [ "user" ] } } } } } }, "/site-allow-ssh-migration/{site}": { "post": { "tags": [ "Sites" ], "summary": "Configure a site to accept an incoming SSH migration", "description": "Configure a site to accept an incoming SSH migration. Because an SSH migration, by default is a destructive operation (destroying existing files and database data) you must first configure a site as a migration target before creating a migration for it. In this way you must explicitly signal to us that you accept responsibility for this site and its data being deleted by a migration should one be configured for it. You cannot currently undo this operation.", "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "description": "The response data.", "properties": { "ready_for_migration": { "type": "boolean", "description": "true if the site is now ready to have a migration created. false if the site already has a migration attached to it." } } } } } } } }, "403": { "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message." }, "data": { "description": "Error details, or an empty array when none are returned." } } } } }, "description": "Access denied." }, "404": { "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message." }, "data": { "description": "Error details, or an empty array when none are returned." } } } } }, "description": "Site not found." }, "500": { "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message." }, "data": { "description": "Error details, or an empty array when none are returned." } } } } }, "description": "Database error." } }, "parameters": [ { "name": "site", "in": "path", "description": "Site ID or domain.", "required": true, "schema": { "type": "string" } } ], "operationId": "post-site-allow-ssh-migration-site" } }, "/edge-cache/{site}/ddos_until": { "post": { "tags": [ "Edge Cache" ], "summary": "Configure Defensive Mode for a site.", "description": "Enable or disable Defensive Mode for a site.", "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Response status message." }, "data": { "type": "array", "description": "Empty array." } }, "example": { "message": "OK", "data": [] } }, "examples": { "success-530a19dfbccd73e4313006d96a3a22db": { "summary": "Success-Response", "value": { "message": "OK", "data": [] } } } } } }, "400": { "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message." }, "data": { "description": "Error details, or an empty array when none are returned." } } } } }, "description": "Missing or invalid site/timestamp parameter, or timestamp is in the past or exceeds 1 week." }, "403": { "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message." }, "data": { "description": "Error details, or an empty array when none are returned." } } } } }, "description": "Access denied." }, "404": { "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message." }, "data": { "description": "Error details, or an empty array when none are returned." } } } } }, "description": "Domain not found." }, "500": { "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message." }, "data": { "description": "Error details, or an empty array when none are returned." } } } } }, "description": "Failed to enable or disable Defensive Mode." } }, "parameters": [ { "name": "site", "in": "path", "description": "Site ID or domain.", "required": true, "schema": { "type": "string" } } ], "operationId": "post-edge-cache-site-ddos_until", "requestBody": { "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "properties": { "timestamp": { "type": "number", "description": "Unix timestamp to enable Defensive Mode until, or 0 to disable Defensive Mode. Set to -1 to enable Defensive Mode indefinitely." } }, "required": [ "timestamp" ] } } } } }, "get": { "tags": [ "Edge Cache" ], "summary": "Get the current Defensive Mode status.", "description": "Fetch the current state of Defensive Mode for a site.", "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Response status message." }, "data": { "type": "object", "description": "Response data.", "properties": { "ddos_until": { "type": "number", "description": "0 when Defensive Mode is not enabled. When enabled, a Unix timestamp indicating when it will deactivate, or -1 if enabled indefinitely." } } } } } } } }, "400": { "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message." }, "data": { "description": "Error details, or an empty array when none are returned." } } } } }, "description": "Missing or invalid site parameter." }, "403": { "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message." }, "data": { "description": "Error details, or an empty array when none are returned." } } } } }, "description": "Access denied." }, "404": { "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message." }, "data": { "description": "Error details, or an empty array when none are returned." } } } } }, "description": "Domain not found." }, "500": { "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message." }, "data": { "description": "Error details, or an empty array when none are returned." } } } } }, "description": "Failed to check Defensive Mode." } }, "parameters": [ { "name": "site", "in": "path", "description": "Site ID or domain.", "required": true, "schema": { "type": "string" } } ], "operationId": "get-edge-cache-site-ddos_until" } }, "/edge-cache/{site}/ddos_until/{domain}": { "post": { "tags": [ "Edge Cache" ], "summary": "Configure Defensive Mode for a site.", "description": "Enable or disable Defensive Mode for a site.", "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Response status message." }, "data": { "type": "array", "description": "Empty array." } }, "example": { "message": "OK", "data": [] } }, "examples": { "success-530a19dfbccd73e4313006d96a3a22db": { "summary": "Success-Response", "value": { "message": "OK", "data": [] } } } } } }, "400": { "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message." }, "data": { "description": "Error details, or an empty array when none are returned." } } } } }, "description": "Missing or invalid site/timestamp parameter, or timestamp is in the past or exceeds 1 week." }, "403": { "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message." }, "data": { "description": "Error details, or an empty array when none are returned." } } } } }, "description": "Access denied." }, "404": { "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message." }, "data": { "description": "Error details, or an empty array when none are returned." } } } } }, "description": "Domain not found." }, "500": { "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message." }, "data": { "description": "Error details, or an empty array when none are returned." } } } } }, "description": "Failed to enable or disable Defensive Mode." } }, "parameters": [ { "name": "site", "in": "path", "description": "Site ID or domain.", "required": true, "schema": { "type": "string" } }, { "name": "domain", "in": "path", "description": "Domain to set Defensive Mode for. Defaults to the site's primary domain.", "required": true, "schema": { "type": "string" } } ], "operationId": "post-edge-cache-site-ddos_until-domain", "requestBody": { "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "properties": { "timestamp": { "type": "number", "description": "Unix timestamp to enable Defensive Mode until, or 0 to disable Defensive Mode. Set to -1 to enable Defensive Mode indefinitely." } }, "required": [ "timestamp" ] } } } } }, "get": { "tags": [ "Edge Cache" ], "summary": "Get the current Defensive Mode status.", "description": "Fetch the current state of Defensive Mode for a site.", "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Response status message." }, "data": { "type": "object", "description": "Response data.", "properties": { "ddos_until": { "type": "number", "description": "0 when Defensive Mode is not enabled. When enabled, a Unix timestamp indicating when it will deactivate, or -1 if enabled indefinitely." } } } } } } } }, "400": { "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message." }, "data": { "description": "Error details, or an empty array when none are returned." } } } } }, "description": "Missing or invalid site parameter." }, "403": { "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message." }, "data": { "description": "Error details, or an empty array when none are returned." } } } } }, "description": "Access denied." }, "404": { "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message." }, "data": { "description": "Error details, or an empty array when none are returned." } } } } }, "description": "Domain not found." }, "500": { "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message." }, "data": { "description": "Error details, or an empty array when none are returned." } } } } }, "description": "Failed to check Defensive Mode." } }, "parameters": [ { "name": "site", "in": "path", "description": "Site ID or domain.", "required": true, "schema": { "type": "string" } }, { "name": "domain", "in": "path", "description": "Optional: domain to fetch the status for. Defaults to the site's primary domain.", "required": true, "schema": { "type": "string" } } ], "operationId": "get-edge-cache-site-ddos_until-domain" } }, "/site-convert-db-charset/{service}/{identifier}/{from}/{to}": { "get": { "tags": [ "Sites" ], "summary": "Convert Site Database Character Set", "description": "Convert a site's tables from a known character set to a specified one.", "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Response status message." }, "data": { "type": "object", "description": "Response object.", "properties": { "atomic_site_id": { "type": "number", "description": "Site ID." }, "from": { "type": "string", "description": "Source encoding." }, "to": { "type": "string", "description": "Target encoding." } } } }, "example": { "message": "OK", "data": { "atomic_site_id": "149401633", "from": "latin1", "to": "utf8mb4" } } }, "examples": { "success-c580c2354fe98b2fd94284747bd0f64c": { "summary": "Success-Response", "value": { "message": "OK", "data": { "atomic_site_id": "149401633", "from": "latin1", "to": "utf8mb4" } } } } } } }, "400": { "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message." }, "data": { "description": "Error details, or an empty array when none are returned." } } } } }, "description": "Invalid or mismatched charset values, or could not obtain site lock." }, "404": { "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message." }, "data": { "description": "Error details, or an empty array when none are returned." } } } } }, "description": "Site not found." }, "423": { "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message." }, "data": { "description": "Error details, or an empty array when none are returned." } } } } }, "description": "Site is already locked." }, "500": { "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message." }, "data": { "description": "Error details, or an empty array when none are returned." } } } } }, "description": "No server found for site." } }, "parameters": [ { "name": "service", "in": "path", "description": "Service type (client name, \"domain\" for domain lookup, or \"wpcom\" for WordPress.com blog ID).", "required": true, "schema": { "type": "string" } }, { "name": "identifier", "in": "path", "description": "Site identifier (domain for \"domain\" service, site ID for client, WordPress.com blog ID for \"wpcom\").", "required": true, "schema": { "type": "string" } }, { "name": "from", "in": "path", "description": "Current database character encoding.", "required": true, "schema": { "type": "string", "enum": [ "latin1", "utf8", "utf8mb4" ] } }, { "name": "to", "in": "path", "description": "Desired final database character encoding.", "required": true, "schema": { "type": "string", "enum": [ "latin1", "utf8", "utf8mb4" ] } } ], "operationId": "get-site-convert-db-charset-service-identifier-from-to" } }, "/migration/create/{site}": { "post": { "tags": [ "Migrations" ], "summary": "Create Migration", "description": "Create a new migration for a site. The site must be enabled for migrations via the allow_site_migration meta key. Requires remote server connection details. If no SSH key is provided, one will be generated and the public key returned for installation on the remote server.", "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Response status message." }, "data": { "type": "object", "properties": { "migration-id": { "type": "number", "description": "ID of the created migration." }, "ssh-id-pub": { "type": "string", "description": "Public SSH key (only if auto-generated)." } } } } } } } }, "400": { "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message." }, "data": { "description": "Error details, or an empty array when none are returned." } } } } }, "description": "Site was not created for migration or already has a migration.\n\nA migration already exists for this site.\n\nremote-host parameter is required.\n\nremote-user parameter is required.\n\nInvalid SSH key data or passphrase." }, "403": { "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message." }, "data": { "description": "Error details, or an empty array when none are returned." } } } } }, "description": "Access denied." }, "404": { "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message." }, "data": { "description": "Error details, or an empty array when none are returned." } } } } }, "description": "Site not found." }, "500": { "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message." }, "data": { "description": "Error details, or an empty array when none are returned." } } } } }, "description": "Failed to create migration record." } }, "parameters": [ { "name": "site", "in": "path", "description": "Site ID or domain.", "required": true, "schema": { "type": "string" } } ], "operationId": "post-migration-create-site", "requestBody": { "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "properties": { "remote-host": { "type": "string", "description": "Hostname or IP address of the remote server to migrate from." }, "remote-user": { "type": "string", "description": "SSH username for remote server connection." }, "remote-port": { "type": "string", "description": "SSH port to use when communicating. Defaults to 22." }, "remote-pass": { "type": "string", "description": "Password for SSH authentication (optional if using SSH key)." }, "remote-domain": { "type": "string", "description": "Domain name on remote server (defaults to site's domain)." }, "remote-docroot": { "type": "string", "description": "Path to document root on remote server." }, "ssh-id": { "type": "string", "description": "SSH private key for authentication (auto-generated if not provided)." }, "ssh-id-pass": { "type": "string", "description": "Passphrase for SSH private key." } }, "required": [ "remote-host", "remote-user" ] } } } } } }, "/alias-pkey/set/{client}/{category}/{name}": { "post": { "tags": [ "SSH" ], "summary": "Create or Update Public Key", "description": "Create or update, as appropriate, an aliasable public key.\n\nAssuming your client name is \"foo\", your category is \"bar\", and your name is \"test-key\" this endpoint will create or update the public key at the address 'pub://foo/bar?test-key'\n\nOnce created you can use 'pub://foo/bar?test-key' as the value for pkey in the ssh-user endpoint and also authorized_keys_line in the client-authorized-keys endpoint. If you do then when you update the referenced key (such as changing the public key, or changing the parsed options) those changes will be immediately reflected by all ssh-user and client-authorized-keys referencing this address.\n\nCategories. Categories should be used sparingly, and for the purposes of identifying classes of keys. A good use of categories would be to differentiate between end-user, developer, support, and automation keys. A poor use of categories would be grouping by site-id at scale. Category names are arbitrary, and exist, or not, based on there being keys using them.\n\nNames. Names are arbitrary identifiers. A name does not need to make sense to us, though it is helpful when attempting to support you if they do. It is perfectly acceptable to use something like {userid}, {siteid}-{userid}, {userid}-{keynumber}, or whatever else makes sense for your desired operation. It is suggested that some form of immutable ID number or string be used in the name for your aliases to reduce possible confusion when tracking them later on.\n\nScale. It is acceptable to use alias-pkey's for 0% of your public keys, 100% of your public keys, or anywhere in-between. The main draw for using them is updating the referenced key once updates all N references to it at the same time N being 1 is acceptable but, in our opinion, it's usually very likely that that will change at some point.\n\nUniqueness. Keys are unique based on [client,category,name]. Therefor all of the following are completely unique: pub://client-a/employees?jennifer pub://client-a/users?jennifer pub://client-b/users?jennifer\n\nOf interest is that it is entirely valid for an ssh-user or client-authorized-key to reference an address belonging to a different client entirely. It is assumed that this will not com up often but an example use case would be for allowing atomic staff access to a site for debugging purposes.\n\nOf note is that alias-pkeys cannot reference other alias-pkeys. This may change in the future given a compelling use case but this is not currently planned and there are no known good reasons to start planning.\n\nReferences to an aliasable key are not tracked by atomic. As such removing an aliasable key does not remove references to that address. Likewise removing an aliasable key does not remove objects which reference its address from the system either. If a client should have a use case which requires doing such then the client should plan on tracking where those keys are referenced on their end.", "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Response status message." }, "data": { "type": "object", "description": "Created or updated public key.", "properties": { "id": { "type": "number", "description": "Public key ID." }, "name": { "type": "string", "description": "Key name." }, "category": { "type": "string", "description": "Category name." }, "url": { "type": "string", "description": "Public key URI (pub://client/category?name)." }, "fingerprint": { "type": "string", "description": "SHA256 fingerprint." } } } } } } } }, "400": { "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message." }, "data": { "description": "Error details, or an empty array when none are returned." } } } } }, "description": "Missing or invalid `pkey` body parameter." }, "403": { "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message." }, "data": { "description": "Error details, or an empty array when none are returned." } } } } }, "description": "Access denied." }, "500": { "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message." }, "data": { "description": "Error details, or an empty array when none are returned." } } } } }, "description": "Database error; data contains the error message." } }, "parameters": [ { "name": "client", "in": "path", "description": "Client name or ID.", "required": true, "schema": { "type": "string" } }, { "name": "category", "in": "path", "description": "Category name (categories exist as long as keys reference them).", "required": true, "schema": { "type": "string" } }, { "name": "name", "in": "path", "description": "Key name.", "required": true, "schema": { "type": "string" } } ], "operationId": "post-alias-pkey-set-client-category-name", "requestBody": { "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "properties": { "pkey": { "type": "string", "description": "Authorized keys line for this alias. Honored options: `from=\"\"`, `command=\"\"`, `no-pty`, `no-agent-forwarding`. Allowed key types: ssh-rsa (2048-16384 bits), ecdsa-sha2-nistp256 (256 bits), ssh-ed25519 (256 bits)." } }, "required": [ "pkey" ] } } } } } }, "/create-site/{client}": { "post": { "tags": [ "Sites" ], "summary": "Create Site", "description": "Create a WP Cloud site with the following options.", "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Response status message." }, "data": { "type": "object", "description": "Response object.", "properties": { "job_id": { "type": "number", "description": "Job ID of the queued provisioning job." }, "atomic_site_id": { "type": "number", "description": "Site ID." }, "domain_name": { "type": "string", "description": "Site domain name." } } } }, "example": { "message": "OK", "data": { "job_id": 1234, "atomic_site_id": 5678, "domain_name": "example.com" } } }, "examples": { "success-4e182a83708873c0758247d087541d94": { "summary": "Success-Response", "value": { "message": "OK", "data": { "job_id": 1234, "atomic_site_id": 5678, "domain_name": "example.com" } } } } } } }, "400": { "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message." }, "data": { "description": "Error details, or an empty array when none are returned." } }, "example": { "message": "Missing or invalid admin_user", "data": [] } }, "examples": { "error-806a650dc88199402bad81768aef0974": { "summary": "Error-Response", "value": { "message": "Missing or invalid admin_user", "data": [] } } } } }, "description": "Missing or invalid parameter (e.g. missing admin_user, invalid domain, unsupported arg during restore_from)." }, "403": { "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message." }, "data": { "description": "Error details, or an empty array when none are returned." } } } } }, "description": "Access denied: invalid client, or cloning not available for the source site." }, "404": { "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message." }, "data": { "description": "Error details, or an empty array when none are returned." } } } } }, "description": "Backup record not found." }, "405": { "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message." }, "data": { "description": "Error details, or an empty array when none are returned." } } } } }, "description": "Request method is not POST." }, "409": { "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message." }, "data": { "description": "Error details, or an empty array when none are returned." } } } } }, "description": "Duplicate domain name, or backup restore conflict (mismatched site or backup type)." }, "421": { "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message." }, "data": { "description": "Error details, or an empty array when none are returned." } } } } }, "description": "Requested domain is currently being provisioned on another site; retry later." }, "423": { "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message." }, "data": { "description": "Error details, or an empty array when none are returned." } } } } }, "description": "Source site is already locked (clone in progress)." }, "500": { "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message." }, "data": { "description": "Error details, or an empty array when none are returned." } } } } }, "description": "Unexpected server error." } }, "parameters": [ { "name": "client", "in": "path", "description": "Client identifier.", "required": true, "schema": { "type": "string" } } ], "operationId": "post-create-site-client", "requestBody": { "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "properties": { "domain_name": { "type": "string", "description": "Domain name for the site. Required unless `demo_domain` is true. and the client allows demo domains." }, "demo_domain": { "type": "boolean", "description": "Generate a demo domain if truthy and a domain name is not provided. Default false." }, "admin_user": { "type": "string", "description": "WordPress admin username for the new site." }, "admin_email": { "type": "string", "description": "WordPress admin email for the new site." }, "admin_pass": { "type": "string", "description": "Password for the admin user." }, "db_charset": { "type": "string", "enum": [ "latin1", "utf8", "utf8mb4" ], "description": "Database character set. Default \"utf8mb4\"." }, "db_collate": { "type": "string", "enum": [ "latin1_swedish_ci", "utf8_general_ci", "utf8mb4_general_ci" ], "description": "Database collation. Defaults to the appropriate collation for the given character set." }, "php_version": { "type": "string", "enum": [ "8.2", "8.3", "8.4", "8.5" ], "description": "Desired PHP version. Default \"8.4\"." }, "wordpress-version": { "type": "string", "enum": [ "latest", "previous", "beta", "alpha" ], "description": "WordPress version track. Default \"latest\". Only applies to fresh sites; ignored when `clone_from` or `restore_from` is provided." }, "space_quota": { "type": "string", "description": "Desired space quota. Value must be an integer followed by a size. specifier (e.g. \"50G\"). Defaults to \"200G\"." }, "clone_from": { "type": "string", "description": "Site ID or domain of the site to clone from. Cannot be used together with `restore_from`." }, "skip_db_rewrite": { "type": "boolean", "description": "Skip database URL rewriting when cloning. Default false. More performant for large sites, but URLs will need to be updated manually after cloning." }, "restore_from": { "type": "array", "items": { "type": "number" }, "description": "Array of exactly two backup record IDs to restore from: one filesystem backup and one. database backup. Cannot be used together with `clone_from`. When restoring, the params `php_version`, `db_charset`, `db_collate`, `admin_pass`, `space_quota`, `geo_affinity`, `software`, and `meta` are not supported and will return 400 if provided." }, "firewall_profile": { "type": "string", "enum": [ "default", "inherit", "deny-egress", "none" ], "description": "Firewall rules profile to apply. For clones and restores, \"inherit\" (also the default) copies rules from the source site. For new sites, \"none\" (also the default) adds no rules. \"deny-egress\" adds deny rules for all outbound traffic on ports 80 and 443." }, "geo_affinity": { "type": "string", "enum": [ "ams", "bur", "dca", "dfw" ], "description": "Preferred datacenter for pool server assignment." }, "generation": { "type": "string", "enum": [ "0", "1", "2" ], "description": "Required server hardware generation for pool assignment. Narrows the pools considered rather than replacing another placement constraint, so it can be combined with `geo_affinity` to request a generation within a datacenter. Pools carrying no generation designation are never selected when this is provided. Use `get-available-generations` to discover valid values. Returns 400 when combined with a `pool_id` of a different generation. Honored for `restore_from` as well, which is placed like any other new site." }, "persist_data": { "type": "object", "description": "Key-value pairs of persistent data to provision the site with." }, "software": { "type": "object", "description": "Key-value pairs of software to install/activate/remove at provisioning time." }, "software.key": { "type": "string", "description": "The plugin or theme identifier; formats include: \"plugins/woocommerce/latest\", \"plugins/woocommerce-gateway-paypal-express-checkout/latest\", \"plugins/akismet/latest\", \"themes/storefront/latest\", \"themes/pub/ocean-mist\", \"wordpress/themes/premium/caldwell\", \"mu-plugins/example-slug/latest\", \"mu-plugins/example-slug/latest/custom-loader.php\", \"themes://url\", \"theme://url\", \"plugins://url\", \"plugin://url\".\n\nManaged mu-plugin keys use \"mu-plugins/{slug}/{version}\" or \"mu-plugins/{slug}/{version}/{loader-file}\". If the loader file is omitted, it defaults to \"{slug}-loader.php\".

Note: The key is rfc3986 decoded. This is an important note because PHP will interpret a key, replacing periods ( \".\" ) and spaces ( \" \" ) with underscores ( \"_\" ) so if you are passing a URL which probably has at least a . in it on account of probably ending in .zip then you will need to encode those characters, otherwise it will be interpreted by PHP on the server side as _zip instead. It is acceptable (and even encouraged) to simply %nn encode all not alpha-numeric values to avoid confusion." }, "software.value": { "type": "string", "description": "The action to take, one of \"activate\", \"activate-locked\", \"install\", \"install-locked\", \"deactivate\", \"remove\", \"lock\", or \"unlock\". For \"mu-plugins/...\" keys, only \"install\", \"install-locked\", \"remove\", \"lock\", and \"unlock\" apply. Activation and deactivation actions do not apply to mu-plugins. Locked mu-plugin installs are platform-protected; use \"unlock\" before \"remove\"." }, "meta": { "type": "array", "items": { "type": "array" }, "description": "Key-value pairs of additional site meta. Supported keys: \"development_mode\", \"privacy_model\", \"photon_subsizes\", \"static_file_404\", \"default_php_conns\", \"burst_php_conns\", \"php_memory_limit\", and \"_data\". Note: Not all meta keys can be applied before a site is created. Some keys require a site to exist, so they may only be set after a site is provisioned." }, "meta.key": { "type": "string", "description": "The site meta key." }, "meta.value": { "type": "string", "description": "The site meta value." } }, "required": [ "admin_user", "admin_email", "software.key", "software.value", "meta.key", "meta.value" ] } } } } } }, "/task-create/{client}/{type}": { "post": { "tags": [ "Tasks" ], "summary": "Create Task", "description": "Create a task that will iterate over all client sites.\n\n\"software\" : Perform changes to site software (plugins and themes).\n\n\"site-find-files\" : Search for files that match the provided pattern. Note that * and ? characters can be used: * will be expanded to (.*) and ? will be expanded to (.)\n\n\"run-wp-cli-command\" : Perform a wp-cli command. Note that the command is limited to a run time of 5 minutes and max memory usage of 1200 MB.\n\n\"wpcloud-scan\" : Run WP Cloud Scan checks across sites.", "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Response status message." }, "data": { "type": "object", "description": "Response data.", "properties": { "task_id": { "type": "number", "description": "The new task ID." }, "initial_task_manager_id": { "type": "number", "description": "The initial task manager job ID." }, "meta": { "type": "object", "description": "Task metadata.", "properties": { "concurrency": { "type": "number", "description": "The maximum number of concurrent sites the task will be performed on at any given time." }, "send_webhook_for": { "type": "string", "description": "Condition under which webhooks are sent." } } } } } }, "example": { "message": "OK", "data": { "task_id": 169, "initial_task_manager_id": 67012835, "meta": { "concurrency": 5, "success_count": 0, "failure_count": 0, "took": 0, "took_success": 0, "took_failure": 0, "send_webhook_for": "success", "pattern": "/class\\-scf(.*)\\.php/i", "search_mode": "regex", "last_site_id": "999999999999999999" } } } }, "examples": { "success-fd4abf8a7295d6269bd7ba419dad9849": { "summary": "Success-Response", "value": { "message": "OK", "data": { "task_id": 169, "initial_task_manager_id": 67012835, "meta": { "concurrency": 5, "success_count": 0, "failure_count": 0, "took": 0, "took_success": 0, "took_failure": 0, "send_webhook_for": "success", "pattern": "/class\\-scf(.*)\\.php/i", "search_mode": "regex", "last_site_id": "999999999999999999" } } } } } } } }, "400": { "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message." }, "data": { "description": "Error details, or an empty array when none are returned." } } } } }, "description": "Missing or invalid client, type, or task parameters." }, "409": { "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message." }, "data": { "description": "Error details, or an empty array when none are returned." } } } } }, "description": "An in-progress task already exists for this client." }, "500": { "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message." }, "data": { "description": "Error details, or an empty array when none are returned." } } } } }, "description": "Failed to create the task." } }, "parameters": [ { "name": "client", "in": "path", "description": "Client name (e.g. \"pressable\", \"vip\"). Also accepts \"per-pool\" or \"all-sites\" for internal use.", "required": true, "schema": { "type": "string" } }, { "name": "type", "in": "path", "description": "The type of task to be created. Valid options: \"software\", \"site-find-files\", \"run-wp-cli-command\", \"wpcloud-scan\".", "required": true, "schema": { "type": "string" } } ], "operationId": "post-task-create-client-type", "requestBody": { "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "properties": { "send_webhook_for": { "type": "string", "enum": [ "all", "success", "failure", "none" ], "description": "Under what condition to send webhooks when executing the task on a site." }, "software": { "type": "object", "description": "Required for \"software\" task. Map of software slug to desired action. Valid actions: \"activate\", \"install\", \"deactivate\", \"remove\"." }, "pattern": { "type": "string", "description": "Required for \"site-find-files\" task. The pattern to be compared against full file paths. * will be expanded to (.*) and ? will be expanded to (.)." }, "args": { "type": "array", "items": { "type": "string" }, "description": "Required for \"run-wp-cli-command\" task. Command arguments for `wp` cli. Example: [ \"db\", \"size\", \"--human-readable\" ]." }, "site_count_limit": { "type": "string", "description": "Maximum number of sites to run the task on. Accepts an integer or a percentage string (e.g. \"10%\")." }, "site_run_list": { "type": "array", "items": { "type": "number" }, "description": "Array of up to 200 site IDs to restrict the task to. When provided, the task runs only on the specified sites." }, "cli_mode": { "type": "string", "enum": [ "full", "limited" ], "description": "Options for \"run-wp-cli-command\" task. Should WP_CLI run in full site context, or limited so site specific code is not loaded reducing the chance of core WP CLI command failures from broken sites." }, "scan_type": { "type": "string", "enum": [ "pnt-versions", "wpscan" ], "description": "Required for \"wpcloud-scan\" task. Type of security scan to perform." } } } } } } } }, "/custom-certificates/{site}/{id}/deactivate": { "post": { "tags": [ "Custom SSL Certificates" ], "summary": "Deactivate a Custom Certificate", "description": "Deactivate an active custom SSL certificate. If id is omitted, the currently active certificate is deactivated.", "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Response status message." }, "data": { "type": "object", "description": "Deactivation result.", "properties": { "status": { "type": "string", "description": "Deactivation status (e.g. \"deactivated\")." } } } }, "example": { "message": "OK", "data": { "status": "deactivated" } } }, "examples": { "success-e8b93a5cd27eec4696ca87baddfc7214": { "summary": "Success-Response", "value": { "message": "OK", "data": { "status": "deactivated" } } } } } } }, "400": { "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message." }, "data": { "description": "Error details, or an empty array when none are returned." } } } } }, "description": "Invalid site identifier." }, "403": { "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message." }, "data": { "description": "Error details, or an empty array when none are returned." } } } } }, "description": "Access denied." }, "404": { "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message." }, "data": { "description": "Error details, or an empty array when none are returned." } } } } }, "description": "Certificate not found." }, "500": { "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message." }, "data": { "description": "Error details, or an empty array when none are returned." } } } } }, "description": "ACME API error." } }, "parameters": [ { "name": "site", "in": "path", "description": "Site ID or domain.", "required": true, "schema": { "type": "string" } }, { "name": "id", "in": "path", "description": "ID of the custom certificate to deactivate. If omitted, the currently active certificate is deactivated.", "required": true, "schema": { "type": "number" } } ], "operationId": "post-custom-certificates-site-id-deactivate" } }, "/custom-certificates/{site}/{id}/delete": { "post": { "tags": [ "Custom SSL Certificates" ], "summary": "Delete a Custom Certificate", "description": "Delete a custom certificate by ID. The certificate must not be active.", "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Response status message." }, "data": { "type": "object", "description": "Deletion result.", "properties": { "deleted": { "type": "object", "description": "Deleted certificate identifier.", "properties": { "ssl_custom_certificate_id": { "type": "number", "description": "ID of the deleted certificate." } } } } } }, "example": { "message": "OK", "data": { "deleted": { "ssl_custom_certificate_id": 123 } } } }, "examples": { "success-bb79fc7a8375ec1659ece15d8303c5cd": { "summary": "Success-Response", "value": { "message": "OK", "data": { "deleted": { "ssl_custom_certificate_id": 123 } } } } } } } }, "400": { "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message." }, "data": { "description": "Error details, or an empty array when none are returned." } } } } }, "description": "Invalid site identifier or missing certificate ID." }, "403": { "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message." }, "data": { "description": "Error details, or an empty array when none are returned." } } } } }, "description": "Access denied." }, "404": { "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message." }, "data": { "description": "Error details, or an empty array when none are returned." } } } } }, "description": "Certificate not found." }, "500": { "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message." }, "data": { "description": "Error details, or an empty array when none are returned." } } } } }, "description": "ACME API error." } }, "parameters": [ { "name": "site", "in": "path", "description": "Site ID or domain.", "required": true, "schema": { "type": "string" } }, { "name": "id", "in": "path", "description": "ID of the custom certificate to delete.", "required": true, "schema": { "type": "number" } } ], "operationId": "post-custom-certificates-site-id-delete" } }, "/delete-site/{service}/{identifier}": { "post": { "tags": [ "Sites" ], "summary": "Delete Site", "description": "Mark a site for deletion.", "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Response status message." }, "data": { "type": "object", "description": "Response object.", "properties": { "job_id": { "type": "number", "description": "Job ID of the queued job." } } } }, "example": { "message": "OK", "data": { "job_id": 9876 } } }, "examples": { "success-e5f1c605c2ff71eeb3b7311121a16e48": { "summary": "Success-Response", "value": { "message": "OK", "data": { "job_id": 9876 } } } } } } }, "400": { "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message." }, "data": { "description": "Error details, or an empty array when none are returned." } } } } }, "description": "Site has do_not_delete set, or duplicate delete request." }, "403": { "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message." }, "data": { "description": "Error details, or an empty array when none are returned." } } } } }, "description": "Access denied." }, "404": { "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message." }, "data": { "description": "Error details, or an empty array when none are returned." } } } } }, "description": "Site not found." }, "412": { "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message." }, "data": { "description": "Error details, or an empty array when none are returned." } } } } }, "description": "On-demand backups exist; delete them first." }, "423": { "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message." }, "data": { "description": "Error details, or an empty array when none are returned." } } } } }, "description": "Site is already locked." }, "500": { "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message." }, "data": { "description": "Error details, or an empty array when none are returned." } } } } }, "description": "Unable to find primary server for site's pool." } }, "parameters": [ { "name": "service", "in": "path", "description": "Service type; may be client name or \"domain\". Used to determine site lookup method; use \"domain\" to look up a site by domain, otherwise use the client identifier to look up a site by site ID", "required": true, "schema": { "type": "string" } }, { "name": "identifier", "in": "path", "description": "Site identifier; domain name for \"domain\" lookups,. otherwise the site ID. For \"wpcom\" service, use the WordPress.com blog ID", "required": true, "schema": { "type": "string" } } ], "operationId": "post-delete-site-service-identifier" } }, "/ssl-hsts-preload/{domain}/false": { "post": { "tags": [ "Sites" ], "summary": "Disable HSTS preload directive", "description": "Disable HSTS preload directive.", "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Response status message." }, "data": { "type": "object", "description": "Empty object." } }, "example": { "message": "OK", "data": [] } }, "examples": { "success-530a19dfbccd73e4313006d96a3a22db": { "summary": "Success-Response", "value": { "message": "OK", "data": [] } } } } } }, "400": { "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message." }, "data": { "description": "Error details, or an empty array when none are returned." } } } } }, "description": "Preload directive can only be disabled." }, "403": { "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message." }, "data": { "description": "Error details, or an empty array when none are returned." } } } } }, "description": "Access denied." }, "404": { "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message." }, "data": { "description": "Error details, or an empty array when none are returned." } } } } }, "description": "Site not found." }, "500": { "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message." }, "data": { "description": "Error details, or an empty array when none are returned." } } } } }, "description": "Error communicating with SSL backend." } }, "parameters": [ { "name": "domain", "in": "path", "description": "Site domain name.", "required": true, "schema": { "type": "string" } } ], "operationId": "post-ssl-hsts-preload-domain-false" } }, "/ssl-info/{domain}": { "post": { "tags": [ "Sites" ], "summary": "Fetch SSL Certificate Information", "description": "Fetch SSL certificate information.", "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Response status message." }, "data": { "type": "object", "description": "Certificate information object.", "properties": { "force_ssl": { "type": "string", "description": "Force SSL setting." }, "acme_certificate_id": { "type": "number", "description": "Certificate ID (present if issued correctly)." }, "validation_expiration": { "type": "string", "description": "Validation expiration date." }, "options": { "type": "array", "items": { "type": "string" }, "description": "Array of ACME options." }, "certificate_expiration_date": { "type": "string", "description": "Certificate expiration date." }, "broken_record": { "type": "object", "description": "If not null, the reason provisioning failed." }, "broken_record[reason]": { "type": "string", "description": "Failure reason." }, "broken_record[last_error]": { "type": "string", "description": "Last error timestamp." }, "broken_record[retry_date]": { "type": "string", "description": "Retry date." }, "broken_record[failcount]": { "type": "string", "description": "Number of failures." } } } }, "example": { "message": "OK", "data": { "force_ssl": "2304", "acme_certificate_id": "3137610", "validation_expiration": "2019-08-17 16:20:33", "options": [ "ACME_OPT_HSTS_1D", "ACME_OPT_REDIRECT_TO_HTTPS" ], "certificate_expiration_date": "2019-10-16 15:20:41", "broken_record": null } } }, "examples": { "success-4d2faf56a0956b1bcf6bb37852335b05": { "summary": "Success-Response", "value": { "message": "OK", "data": { "force_ssl": "2304", "acme_certificate_id": "3137610", "validation_expiration": "2019-08-17 16:20:33", "options": [ "ACME_OPT_HSTS_1D", "ACME_OPT_REDIRECT_TO_HTTPS" ], "certificate_expiration_date": "2019-10-16 15:20:41", "broken_record": null } } }, "success-9aca5185e061298a94b07a08f2a3e4da": { "summary": "Success-Response (with broken_record)", "value": { "message": "OK", "data": { "broken_record": { "reason": "not hosted here", "last_error": "2019-07-19 10:48:41", "retry_date": "2019-07-26 10:48:41", "failcount": "44" } } } } } } } }, "403": { "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message." }, "data": { "description": "Error details, or an empty array when none are returned." } } } } }, "description": "Access denied." }, "404": { "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message." }, "data": { "description": "Error details, or an empty array when none are returned." } } } } }, "description": "Site not found." } }, "parameters": [ { "name": "domain", "in": "path", "description": "Domain name.", "required": true, "schema": { "type": "string" } } ], "operationId": "post-ssl-info-domain" } }, "/get-available-datacenters/{client}": { "get": { "tags": [ "Servers" ], "summary": "Get Available Datacenters", "description": "Get a list of datacenters with available (non-full, active) servers.", "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Response status message." }, "data": { "type": "array", "items": { "type": "string" }, "description": "Array of available datacenter identifiers." } }, "example": { "message": "OK", "data": [ "bur", "dca", "dfw" ] } }, "examples": { "success-a6fd744a5cf568c1edcc69cec268be0f": { "summary": "Success-Response", "value": { "message": "OK", "data": [ "bur", "dca", "dfw" ] } } } } } }, "400": { "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message." }, "data": { "description": "Error details, or an empty array when none are returned." } } } } }, "description": "Invalid or unauthorized client." } }, "parameters": [ { "name": "client", "in": "path", "description": "Client identifier.", "required": true, "schema": { "type": "string" } } ], "operationId": "get-get-available-datacenters-client" } }, "/get-available-generations/{client}[/verbose]": { "get": { "tags": [ "Servers" ], "summary": "Get Available Generations", "description": "Get a list of server hardware generations a client may provision onto. Only generations with available (non-full, active) pools are reported.", "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Response status message." }, "data": { "type": "object", "description": "(verbose) Object mapping each available generation identifier to a description of that hardware." } }, "example": { "message": "OK", "data": [ "1", "2" ] } }, "examples": { "success-8913693b51c19bc262bac19d8f882b13": { "summary": "Success-Response", "value": { "message": "OK", "data": [ "1", "2" ] } }, "success-2cd17a58286a7d724269030919e9544e": { "summary": "Success-Response (verbose)", "value": { "message": "OK", "data": { "1": "128 CPUs AMD 7702P or 7713P", "2": "128 CPUs AMD 9555P" } } } } } } }, "400": { "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message." }, "data": { "description": "Error details, or an empty array when none are returned." } } } } }, "description": "Invalid or unauthorized client." } }, "parameters": [ { "name": "client", "in": "path", "description": "Client identifier.", "required": true, "schema": { "type": "string" } }, { "name": "verbose", "in": "query", "description": "If \"verbose\", returns an object describing each available generation instead of a simple list of identifiers.", "required": false, "schema": { "type": "string" } } ], "operationId": "get-get-available-generations-client[-verbose]" } }, "/get-ips/{client}": { "get": { "tags": [ "Sites" ], "summary": "Get Client IP Addresses", "description": "Get the IPs for a client; if a domain is included, get suggested IPs if possible for the client.", "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "description": "Response data.", "properties": { "ips": { "type": "array", "items": { "type": "string" }, "description": "Array of IP addresses or CIDR blocks." }, "suggested": { "type": "array", "items": { "type": "string" }, "description": "Array of suggested IP addresses (only present when a domain is supplied)." } } } }, "example": { "message": "OK", "data": { "ips": [ "192.0.78.128/25" ], "suggested": [ "192.0.78.150", "192.0.78.200" ] } } }, "examples": { "success-213f785f00230d29ad8afba4dc39bef9": { "summary": "Success-Response", "value": { "message": "OK", "data": { "ips": [ "192.0.78.128/25" ], "suggested": [ "192.0.78.150", "192.0.78.200" ] } } } } } } }, "400": { "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message." }, "data": { "description": "Error details, or an empty array when none are returned." } } } } }, "description": "Invalid or unauthorized client." } }, "parameters": [ { "name": "client", "in": "path", "description": "Client ID or client name.", "required": true, "schema": { "type": "string" } } ], "operationId": "get-get-ips-client" } }, "/get-ips/{client}/{domain}": { "get": { "tags": [ "Sites" ], "summary": "Get Client IP Addresses", "description": "Get the IPs for a client; if a domain is included, get suggested IPs if possible for the client.", "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "description": "Response data.", "properties": { "ips": { "type": "array", "items": { "type": "string" }, "description": "Array of IP addresses or CIDR blocks." }, "suggested": { "type": "array", "items": { "type": "string" }, "description": "Array of suggested IP addresses (only present when a domain is supplied)." } } } }, "example": { "message": "OK", "data": { "ips": [ "192.0.78.128/25" ], "suggested": [ "192.0.78.150", "192.0.78.200" ] } } }, "examples": { "success-213f785f00230d29ad8afba4dc39bef9": { "summary": "Success-Response", "value": { "message": "OK", "data": { "ips": [ "192.0.78.128/25" ], "suggested": [ "192.0.78.150", "192.0.78.200" ] } } } } } } }, "400": { "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message." }, "data": { "description": "Error details, or an empty array when none are returned." } } } } }, "description": "Invalid or unauthorized client." } }, "parameters": [ { "name": "client", "in": "path", "description": "Client ID or client name.", "required": true, "schema": { "type": "string" } }, { "name": "domain", "in": "path", "description": "Domain name.", "required": true, "schema": { "type": "string" } } ], "operationId": "get-get-ips-client-domain" } }, "/client-meta/{client}/{key}/get": { "get": { "tags": [ "Client Meta" ], "summary": "Get Client Meta", "description": "Retrieve a client meta value.\n\nNote: `webhook_hmac_key` does not support the `get` method.", "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Response status message." }, "data": { "type": "string", "description": "The meta value." } }, "example": { "message": "OK", "data": "https://example.com/webhook" } }, "examples": { "success-5faf0ddefc798a1753943700426d5549": { "summary": "Success-Response", "value": { "message": "OK", "data": "https://example.com/webhook" } } } } } }, "400": { "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message." }, "data": { "description": "Error details, or an empty array when none are returned." } }, "example": { "message": "Invalid key", "data": [] } }, "examples": { "error-713244277bf85619f15371801214cafd": { "summary": "Error-Response", "value": { "message": "Invalid key", "data": [] } } } } }, "description": "Invalid or unsupported meta key." }, "403": { "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message." }, "data": { "description": "Error details, or an empty array when none are returned." } } } } }, "description": "Access denied or method not allowed for this key." }, "404": { "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message." }, "data": { "description": "Error details, or an empty array when none are returned." } }, "example": { "message": "Not Found", "data": [] } }, "examples": { "error-fcc5021de5fd64295232140c6eeed99a": { "summary": "Error-Response", "value": { "message": "Not Found", "data": [] } } } } }, "description": "Meta key not found for this client." }, "500": { "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message." }, "data": { "description": "Error details, or an empty array when none are returned." } } } } }, "description": "Internal server error." } }, "parameters": [ { "name": "client", "in": "path", "description": "Client name or ID.", "required": true, "schema": { "type": "string" } }, { "name": "key", "in": "path", "description": "Meta key.", "required": true, "schema": { "type": "string", "enum": [ "webhook_url", "webhook_secret_key", "client_ssh_default_from", "client_ssh_force_from", "client_ssh_firewall", "default_privacy_model", "max_space_quota", "skip_force_backup_db" ] } } ], "operationId": "get-client-meta-client-key-get" } }, "/custom-certificates/{site}": { "get": { "tags": [ "Custom SSL Certificates" ], "summary": "Get Custom Certificate details", "description": "Retrieve details about a custom certificate for a site. Omit the certificate ID to fetch the currently active custom certificate (if any).", "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Response status message." }, "data": { "type": "object", "description": "Certificate details.", "properties": { "ssl_custom_certificate_id": { "type": "number", "description": "Certificate ID." }, "domains": { "type": "array", "items": { "type": "string" }, "description": "Domains covered by the certificate." }, "is_active": { "type": "boolean", "description": "Whether the certificate is currently active." }, "certificate_info": { "type": "object", "description": "Certificate metadata.", "properties": { "issuer": { "type": "string", "description": "Certificate issuer." }, "subject": { "type": "string", "description": "Certificate subject." }, "serial": { "type": "string", "description": "Certificate serial number." }, "valid_from": { "type": "string", "description": "Certificate validity start (UTC)." }, "valid_to": { "type": "string", "description": "Certificate validity end (UTC)." }, "signature_algorithm": { "type": "string", "description": "Certificate signature algorithm." }, "days_until_expiry": { "type": "number", "description": "Days until certificate expiry." } } } } } }, "example": { "message": "OK", "data": { "ssl_custom_certificate_id": 123, "domains": [ "example.com", "www.example.com" ], "is_active": true, "certificate_info": { "issuer": "CN=Authority X, O=Example CA", "subject": "CN=example.com", "serial": "ABCDEF12345", "valid_from": "2025-11-01 00:00:00", "valid_to": "2026-11-01 23:59:59", "signature_algorithm": "RSA-SHA384", "days_until_expiry": 123.4 } } } }, "examples": { "success-51a97544c6ac26b4cced047d91ddc0b2": { "summary": "Success-Response", "value": { "message": "OK", "data": { "ssl_custom_certificate_id": 123, "domains": [ "example.com", "www.example.com" ], "is_active": true, "certificate_info": { "issuer": "CN=Authority X, O=Example CA", "subject": "CN=example.com", "serial": "ABCDEF12345", "valid_from": "2025-11-01 00:00:00", "valid_to": "2026-11-01 23:59:59", "signature_algorithm": "RSA-SHA384", "days_until_expiry": 123.4 } } } } } } } }, "400": { "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message." }, "data": { "description": "Error details, or an empty array when none are returned." } } } } }, "description": "Invalid site identifier." }, "403": { "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message." }, "data": { "description": "Error details, or an empty array when none are returned." } } } } }, "description": "Access denied." }, "404": { "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message." }, "data": { "description": "Error details, or an empty array when none are returned." } } } } }, "description": "Certificate not found for the site." }, "500": { "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message." }, "data": { "description": "Error details, or an empty array when none are returned." } } } } }, "description": "ACME API error." } }, "parameters": [ { "name": "site", "in": "path", "description": "Site ID or domain.", "required": true, "schema": { "type": "string" } } ], "operationId": "get-custom-certificates-site" } }, "/custom-certificates/{site}/{id}": { "get": { "tags": [ "Custom SSL Certificates" ], "summary": "Get Custom Certificate details", "description": "Retrieve details about a custom certificate for a site. Omit the certificate ID to fetch the currently active custom certificate (if any).", "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Response status message." }, "data": { "type": "object", "description": "Certificate details.", "properties": { "ssl_custom_certificate_id": { "type": "number", "description": "Certificate ID." }, "domains": { "type": "array", "items": { "type": "string" }, "description": "Domains covered by the certificate." }, "is_active": { "type": "boolean", "description": "Whether the certificate is currently active." }, "certificate_info": { "type": "object", "description": "Certificate metadata.", "properties": { "issuer": { "type": "string", "description": "Certificate issuer." }, "subject": { "type": "string", "description": "Certificate subject." }, "serial": { "type": "string", "description": "Certificate serial number." }, "valid_from": { "type": "string", "description": "Certificate validity start (UTC)." }, "valid_to": { "type": "string", "description": "Certificate validity end (UTC)." }, "signature_algorithm": { "type": "string", "description": "Certificate signature algorithm." }, "days_until_expiry": { "type": "number", "description": "Days until certificate expiry." } } } } } }, "example": { "message": "OK", "data": { "ssl_custom_certificate_id": 123, "domains": [ "example.com", "www.example.com" ], "is_active": true, "certificate_info": { "issuer": "CN=Authority X, O=Example CA", "subject": "CN=example.com", "serial": "ABCDEF12345", "valid_from": "2025-11-01 00:00:00", "valid_to": "2026-11-01 23:59:59", "signature_algorithm": "RSA-SHA384", "days_until_expiry": 123.4 } } } }, "examples": { "success-51a97544c6ac26b4cced047d91ddc0b2": { "summary": "Success-Response", "value": { "message": "OK", "data": { "ssl_custom_certificate_id": 123, "domains": [ "example.com", "www.example.com" ], "is_active": true, "certificate_info": { "issuer": "CN=Authority X, O=Example CA", "subject": "CN=example.com", "serial": "ABCDEF12345", "valid_from": "2025-11-01 00:00:00", "valid_to": "2026-11-01 23:59:59", "signature_algorithm": "RSA-SHA384", "days_until_expiry": 123.4 } } } } } } } }, "400": { "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message." }, "data": { "description": "Error details, or an empty array when none are returned." } } } } }, "description": "Invalid site identifier." }, "403": { "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message." }, "data": { "description": "Error details, or an empty array when none are returned." } } } } }, "description": "Access denied." }, "404": { "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message." }, "data": { "description": "Error details, or an empty array when none are returned." } } } } }, "description": "Certificate not found for the site." }, "500": { "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message." }, "data": { "description": "Error details, or an empty array when none are returned." } } } } }, "description": "ACME API error." } }, "parameters": [ { "name": "site", "in": "path", "description": "Site ID or domain.", "required": true, "schema": { "type": "string" } }, { "name": "id", "in": "path", "description": "ID of the custom certificate to retrieve. If omitted, the currently active certificate for the site is returned.", "required": true, "schema": { "type": "number" } } ], "operationId": "get-custom-certificates-site-id" } }, "/get-domain-verification-code/{client}/{domain}": { "get": { "tags": [ "Sites" ], "summary": "Get Domain Verification Code", "description": "Generates the domain verification code, to be used as a TXT record so that a domain can be \"claimed\" from another WP Cloud client.", "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Response status message." }, "data": { "type": "string", "description": "Generated code." } }, "example": { "message": "OK", "data": "atomic-domain-12b26a511ef62e8ae42c37512b085250a3d0155c72909cdd58af7cfe196713e5" } }, "examples": { "success-55e237ec73bbda432b990dd3ffc9b024": { "summary": "Success-Response", "value": { "message": "OK", "data": "atomic-domain-12b26a511ef62e8ae42c37512b085250a3d0155c72909cdd58af7cfe196713e5" } } } } } }, "400": { "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message." }, "data": { "description": "Error details, or an empty array when none are returned." } }, "example": { "message": "Missing or invalid domain name", "data": [] } }, "examples": { "error-98c29fb2cd7af4030691d5e308e1cf0d": { "summary": "Error-Response", "value": { "message": "Missing or invalid domain name", "data": [] } } } } }, "description": "Invalid or unauthorized client, or missing domain name." } }, "parameters": [ { "name": "client", "in": "path", "description": "Client ID or client name.", "required": true, "schema": { "type": "string" } }, { "name": "domain", "in": "path", "description": "Domain name in question.", "required": true, "schema": { "type": "string" } } ], "operationId": "get-get-domain-verification-code-client-domain" } }, "/edge-cache/{site}": { "get": { "tags": [ "Edge Cache" ], "summary": "Get Edge Cache Settings", "description": "Endpoint for getting a site's edge cache settings.", "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Response status message." }, "data": { "type": "object", "description": "Response data.", "properties": { "status": { "type": "number", "description": "Edge cache status code; one of 0 (Disabled), 1 (Enabled), or 2 (DDoS)." }, "status_name": { "type": "string", "description": "Edge cache status name; one of \"Disabled\", \"Enabled\", or \"DDoS\"." }, "ddos_until": { "type": "number", "description": "Timestamp when defensive mode expires (Unix time); 0 if not enabled, -1 if enabled indefinitely." } } } }, "example": { "message": "OK", "data": { "status": 0, "status_name": "Disabled", "ddos_until": 0 } } }, "examples": { "success-1af5545204a1965f5ccd88060f69343f": { "summary": "Success-Response: Disabled", "value": { "message": "OK", "data": { "status": 0, "status_name": "Disabled", "ddos_until": 0 } } }, "success-ca0f53c7a2f2ca0da46d85e446a0ae89": { "summary": "Success-Response: Enabled", "value": { "message": "OK", "data": { "status": 1, "status_name": "Enabled", "ddos_until": 0 } } }, "success-39faf8c6d480339a584128b5f17e4899": { "summary": "Success-Response: DDoS", "value": { "message": "OK", "data": { "status": 2, "status_name": "DDoS", "ddos_until": -1 } } } } } } }, "400": { "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message." }, "data": { "description": "Error details, or an empty array when none are returned." } } } } }, "description": "Invalid action." }, "403": { "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message." }, "data": { "description": "Error details, or an empty array when none are returned." } } } } }, "description": "Access denied." }, "404": { "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message." }, "data": { "description": "Error details, or an empty array when none are returned." } } } } }, "description": "Site not found." }, "405": { "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message." }, "data": { "description": "Error details, or an empty array when none are returned." } } } } }, "description": "Request method must be GET or POST." } }, "parameters": [ { "name": "site", "in": "path", "description": "Site ID or domain.", "required": true, "schema": { "type": "string" } } ], "operationId": "get-edge-cache-site" } }, "/edge-cache/{site}/{action}": { "get": { "tags": [ "Edge Cache" ], "summary": "Get Edge Cache Settings", "description": "Endpoint for getting a site's edge cache settings.", "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Response status message." }, "data": { "type": "object", "description": "Response data.", "properties": { "status": { "type": "number", "description": "Edge cache status code; one of 0 (Disabled), 1 (Enabled), or 2 (DDoS)." }, "status_name": { "type": "string", "description": "Edge cache status name; one of \"Disabled\", \"Enabled\", or \"DDoS\"." }, "ddos_until": { "type": "number", "description": "Timestamp when defensive mode expires (Unix time); 0 if not enabled, -1 if enabled indefinitely." } } } }, "example": { "message": "OK", "data": { "status": 0, "status_name": "Disabled", "ddos_until": 0 } } }, "examples": { "success-1af5545204a1965f5ccd88060f69343f": { "summary": "Success-Response: Disabled", "value": { "message": "OK", "data": { "status": 0, "status_name": "Disabled", "ddos_until": 0 } } }, "success-ca0f53c7a2f2ca0da46d85e446a0ae89": { "summary": "Success-Response: Enabled", "value": { "message": "OK", "data": { "status": 1, "status_name": "Enabled", "ddos_until": 0 } } }, "success-39faf8c6d480339a584128b5f17e4899": { "summary": "Success-Response: DDoS", "value": { "message": "OK", "data": { "status": 2, "status_name": "DDoS", "ddos_until": -1 } } } } } } }, "400": { "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message." }, "data": { "description": "Error details, or an empty array when none are returned." } } } } }, "description": "Invalid action." }, "403": { "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message." }, "data": { "description": "Error details, or an empty array when none are returned." } } } } }, "description": "Access denied." }, "404": { "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message." }, "data": { "description": "Error details, or an empty array when none are returned." } } } } }, "description": "Site not found." }, "405": { "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message." }, "data": { "description": "Error details, or an empty array when none are returned." } } } } }, "description": "Request method must be GET or POST." } }, "parameters": [ { "name": "site", "in": "path", "description": "Site ID or domain.", "required": true, "schema": { "type": "string" } }, { "name": "action", "in": "path", "description": "Action to perform.", "required": true, "schema": { "type": "string", "enum": [ "get", "purge", "ddos_until" ] } } ], "operationId": "get-edge-cache-site-action" }, "post": { "tags": [ "Edge Cache" ], "summary": "Update Edge Cache Settings", "description": "Endpoint for managing a site's edge cache settings.", "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Response status message." }, "data": { "type": "array", "description": "Empty array." } } } } } }, "400": { "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message." }, "data": { "description": "Error details, or an empty array when none are returned." } } } } }, "description": "Invalid action or invalid purge URIs." }, "403": { "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message." }, "data": { "description": "Error details, or an empty array when none are returned." } } } } }, "description": "Access denied." }, "404": { "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message." }, "data": { "description": "Error details, or an empty array when none are returned." } } } } }, "description": "Site not found." }, "405": { "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message." }, "data": { "description": "Error details, or an empty array when none are returned." } } } } }, "description": "Request method must be GET or POST." }, "500": { "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message." }, "data": { "description": "Error details, or an empty array when none are returned." } } } } }, "description": "Edge cache update or purge failed." } }, "parameters": [ { "name": "site", "in": "path", "description": "Site ID or domain.", "required": true, "schema": { "type": "string" } }, { "name": "action", "in": "path", "description": "Action to perform.", "required": true, "schema": { "type": "string", "enum": [ "on", "off", "ddos", "purge", "ddos_until" ] } } ], "operationId": "post-edge-cache-site-action", "requestBody": { "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "properties": { "timestamp": { "type": "number", "description": "Unix timestamp for ddos_until action; 0 to disable defensive mode, -1 to set it indefinitely." }, "purge_uris": { "type": "array", "items": { "type": "string" }, "description": "Array of URIs to purge for purge action; if not provided, purges entire domain." } } } } } } } }, "/edge-cache/{site}/{action}/{domain}": { "get": { "tags": [ "Edge Cache" ], "summary": "Get Edge Cache Settings", "description": "Endpoint for getting a site's edge cache settings.", "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Response status message." }, "data": { "type": "object", "description": "Response data.", "properties": { "status": { "type": "number", "description": "Edge cache status code; one of 0 (Disabled), 1 (Enabled), or 2 (DDoS)." }, "status_name": { "type": "string", "description": "Edge cache status name; one of \"Disabled\", \"Enabled\", or \"DDoS\"." }, "ddos_until": { "type": "number", "description": "Timestamp when defensive mode expires (Unix time); 0 if not enabled, -1 if enabled indefinitely." } } } }, "example": { "message": "OK", "data": { "status": 0, "status_name": "Disabled", "ddos_until": 0 } } }, "examples": { "success-1af5545204a1965f5ccd88060f69343f": { "summary": "Success-Response: Disabled", "value": { "message": "OK", "data": { "status": 0, "status_name": "Disabled", "ddos_until": 0 } } }, "success-ca0f53c7a2f2ca0da46d85e446a0ae89": { "summary": "Success-Response: Enabled", "value": { "message": "OK", "data": { "status": 1, "status_name": "Enabled", "ddos_until": 0 } } }, "success-39faf8c6d480339a584128b5f17e4899": { "summary": "Success-Response: DDoS", "value": { "message": "OK", "data": { "status": 2, "status_name": "DDoS", "ddos_until": -1 } } } } } } }, "400": { "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message." }, "data": { "description": "Error details, or an empty array when none are returned." } } } } }, "description": "Invalid action." }, "403": { "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message." }, "data": { "description": "Error details, or an empty array when none are returned." } } } } }, "description": "Access denied." }, "404": { "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message." }, "data": { "description": "Error details, or an empty array when none are returned." } } } } }, "description": "Site not found." }, "405": { "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message." }, "data": { "description": "Error details, or an empty array when none are returned." } } } } }, "description": "Request method must be GET or POST." } }, "parameters": [ { "name": "site", "in": "path", "description": "Site ID or domain.", "required": true, "schema": { "type": "string" } }, { "name": "action", "in": "path", "description": "Action to perform.", "required": true, "schema": { "type": "string", "enum": [ "get", "purge", "ddos_until" ] } }, { "name": "domain", "in": "path", "description": "Domain for the status request; defaults to the primary domain.", "required": true, "schema": { "type": "string" } } ], "operationId": "get-edge-cache-site-action-domain" }, "post": { "tags": [ "Edge Cache" ], "summary": "Update Edge Cache Settings", "description": "Endpoint for managing a site's edge cache settings.", "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Response status message." }, "data": { "type": "array", "description": "Empty array." } } } } } }, "400": { "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message." }, "data": { "description": "Error details, or an empty array when none are returned." } } } } }, "description": "Invalid action or invalid purge URIs." }, "403": { "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message." }, "data": { "description": "Error details, or an empty array when none are returned." } } } } }, "description": "Access denied." }, "404": { "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message." }, "data": { "description": "Error details, or an empty array when none are returned." } } } } }, "description": "Site not found." }, "405": { "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message." }, "data": { "description": "Error details, or an empty array when none are returned." } } } } }, "description": "Request method must be GET or POST." }, "500": { "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message." }, "data": { "description": "Error details, or an empty array when none are returned." } } } } }, "description": "Edge cache update or purge failed." } }, "parameters": [ { "name": "site", "in": "path", "description": "Site ID or domain.", "required": true, "schema": { "type": "string" } }, { "name": "action", "in": "path", "description": "Action to perform.", "required": true, "schema": { "type": "string", "enum": [ "on", "off", "ddos", "purge", "ddos_until" ] } }, { "name": "domain", "in": "path", "description": "Domain on which to perform the action; defaults to the primary domain.", "required": true, "schema": { "type": "string" } } ], "operationId": "post-edge-cache-site-action-domain", "requestBody": { "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "properties": { "timestamp": { "type": "number", "description": "Unix timestamp for ddos_until action; 0 to disable defensive mode, -1 to set it indefinitely." }, "purge_uris": { "type": "array", "items": { "type": "string" }, "description": "Array of URIs to purge for purge action; if not provided, purges entire domain." } } } } } } } }, "/logs/site/{site}/edge": { "post": { "tags": [ "Logs" ], "summary": "Get Edge Logs for a Site", "description": "Get edge (CDN) request log data for a single domain of a site. Edge logs are only retained for 24 hours, so the requested time range must fall within the past 24 hours, and a single query may cover at most 1 hour. The window includes start and excludes end: [start, end). Choose end after start for a nonempty window. Results are capped at 5000 records with no cursor or offset pagination. A response at the cap may omit matching records. Narrowing the time slices or adding filters can reduce the result count, but does not guarantee a complete export. Adjacent slices can reuse the previous end as the next start. A domain in the site path identifies the site. To query an alias, also submit it in domain; the default is always the primary domain.\n\nIllustrative filtered request. Replace SITE_ID, API_AUTH_TOKEN, and alias.example.com with your site's ID, an authorized API key, and a mapped domain.\n\n```bash\nLOG_END=$(date +%s)\nLOG_START=$((LOG_END - 300))\ncurl --request POST 'https://atomic-api.wordpress.com/api/v1.0/logs/site/SITE_ID/edge' \\\n --header 'Auth: API_AUTH_TOKEN' \\\n --data-urlencode \"start=$LOG_START\" \\\n --data-urlencode \"end=$LOG_END\" \\\n --data-urlencode 'domain=alias.example.com' \\\n --data-urlencode 'filter[http_status][]=403' \\\n --data-urlencode 'filter[http_status][]=429' \\\n --data-urlencode 'filter[request_method][]=get'\n```", "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Response message (\"OK\" on success)." }, "data": { "type": "object", "description": "Response data.", "properties": { "domain": { "type": "string", "description": "Domain the results were queried for." }, "result_count": { "type": "integer", "description": "Number of returned entries, not the total number of matches. A count of 5000 may be incomplete." }, "max_results": { "type": "integer", "description": "Maximum size of the result window (5000)." }, "logs": { "type": "array", "items": { "type": "object", "properties": { "dt": { "type": "string", "description": "UTC timestamp of the request with millisecond precision (YYYY-MM-DD HH:MM:SS.sss)." }, "http_host": { "type": "string", "description": "Host header value." }, "remote_addr": { "type": "string", "description": "Client IP address (IPv4 or IPv6, human readable)." }, "remote_user": { "type": "string", "description": "Authenticated remote user; usually empty." }, "ja3_hash": { "type": "string", "description": "JA3 TLS fingerprint hash." }, "server_protocol": { "type": "string", "description": "HTTP protocol version (e.g. \"HTTP/2.0\")." }, "request_method": { "type": "string", "description": "HTTP method (e.g. \"GET\", \"POST\")." }, "http_request_url_no_qs": { "type": "string", "description": "Request path without query string." }, "http_request_url_args": { "type": "string", "description": "Request query string arguments." }, "http_status": { "type": "integer", "description": "HTTP response status code." }, "http_referer": { "type": "string", "description": "Referer header value." }, "http_user_agent": { "type": "string", "description": "User-Agent header value." }, "request_time": { "type": "number", "description": "Request processing time in seconds." }, "country_code": { "type": "string", "description": "Two-letter country code of the client." }, "content_type": { "type": "string", "description": "Response Content-Type." }, "proxy_type": { "type": "string", "description": "Proxy classification of the client, when known." }, "edge_cache_status": { "type": "string", "description": "Edge cache status (e.g. \"HIT\", \"MISS\", \"BYPASS\")." }, "is_rate_limited": { "type": "boolean", "description": "Whether the request was rate limited." }, "rate_limit_reason": { "type": "string", "description": "Reason the request was rate limited, when applicable." }, "asn": { "type": "integer", "description": "Autonomous system number of the client IP." }, "defensive_mode_pass_cookie_status": { "type": "string", "description": "Defensive mode pass-cookie status." }, "defensive_mode_challenge_reason": { "type": "string", "description": "Reason a defensive mode challenge was issued, when applicable." }, "defensive_mode_challenge_result": { "type": "string", "description": "Result of the defensive mode challenge, when applicable." } } }, "description": "Array of log entry objects." } } } }, "example": { "message": "OK", "data": { "domain": "alias.example.com", "result_count": 0, "max_results": 5000, "logs": [] } } }, "examples": { "success-390a2287321807e66ca60a66db15b93c": { "summary": "{json} Empty edge response", "value": { "message": "OK", "data": { "domain": "alias.example.com", "result_count": 0, "max_results": 5000, "logs": [] } } }, "success-03b9712d94d77850e7167c9e039fe519": { "summary": "{json} Edge response (fictional log entry)", "value": { "message": "OK", "data": { "domain": "alias.example.com", "result_count": 1, "max_results": 5000, "logs": [ { "dt": "2024-01-01 00:00:00.123", "http_host": "alias.example.com", "remote_addr": "192.0.2.1", "remote_user": "", "ja3_hash": "", "server_protocol": "HTTP/2.0", "request_method": "GET", "http_request_url_no_qs": "/example", "http_request_url_args": "", "http_status": 403, "http_referer": "", "http_user_agent": "Example agent", "request_time": 0.012, "country_code": "US", "content_type": "text/html", "proxy_type": "", "edge_cache_status": "BYPASS", "is_rate_limited": false, "rate_limit_reason": "", "asn": 64496, "defensive_mode_pass_cookie_status": "", "defensive_mode_challenge_reason": "", "defensive_mode_challenge_result": "" } ] } } } } } } }, "400": { "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message." }, "data": { "description": "Error details, or an empty array when none are returned." } }, "example": { "message": "Domain is not associated with this site", "data": [] } }, "examples": { "error-8ecc899a8077946d27edc5c3da593cdd": { "summary": "{json} Invalid domain", "value": { "message": "Domain is not associated with this site", "data": [] } } } } }, "description": "Missing or invalid parameter. Possible causes: missing start or end, unparseable date string, start > end, start older than 24 hours, time range longer than 1 hour, domain not associated with the site, invalid sort_field or sort_order, unrecognized filter key, or invalid filter value." }, "403": { "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message." }, "data": { "description": "Error details, or an empty array when none are returned." } } } } }, "description": "Access denied." }, "404": { "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message." }, "data": { "description": "Error details, or an empty array when none are returned." } } } } }, "description": "Site not found." }, "500": { "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message." }, "data": { "description": "Error details, or an empty array when none are returned." } } } } }, "description": "Failed to connect to or query the edge log data source." } }, "parameters": [ { "name": "site", "in": "path", "description": "Site ID or domain.", "required": true, "schema": { "type": "string" } } ], "operationId": "post-logs-site-site-edge", "requestBody": { "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "properties": { "start": { "oneOf": [ { "type": "integer" }, { "type": "string" } ], "description": "Inclusive start: Unix seconds or a date string parseable by strtotime(). Must be within the past 24 hours." }, "end": { "oneOf": [ { "type": "integer" }, { "type": "string" } ], "description": "Exclusive end: Unix seconds or a date string parseable by strtotime(). Must not precede start or exceed it by more than 1 hour." }, "domain": { "type": "string", "description": "Domain to query. Must be a domain mapped to the site. Defaults to the site's primary domain." }, "sort_field": { "type": "string", "description": "Field to sort by. Any returned log field is accepted. Default \"dt\".", "default": "dt" }, "sort_order": { "type": "string", "enum": [ "asc", "desc" ], "description": "Sort direction for results. Default \"asc\".", "default": "asc" }, "filter[remote_addr][]": { "type": "array", "items": { "type": "string" }, "description": "Client IP addresses to include (IPv4 or IPv6)." }, "filter[ja3_hash][]": { "type": "array", "items": { "type": "string" }, "description": "JA3 TLS fingerprint hashes: exactly 32 hexadecimal characters, converted to lowercase before matching." }, "filter[request_method][]": { "type": "array", "items": { "type": "string" }, "description": "HTTP methods of 1\u201316 ASCII letters. Values are converted to uppercase before matching (e.g. \"get\" matches \"GET\")." }, "filter[http_status][]": { "type": "array", "items": { "type": "integer", "minimum": 100, "maximum": 999 }, "description": "HTTP status codes, submitted as decimal digits." }, "filter[http_user_agent][]": { "type": "array", "items": { "type": "string" }, "description": "User-Agent header values to include (exact match)." }, "filter[asn][]": { "type": "array", "items": { "type": "integer", "minimum": 0, "maximum": 4294967295 }, "description": "Autonomous system numbers. Submit at most 10 decimal digits, with a value no greater than 4294967295." } }, "required": [ "start", "end" ] }, "encoding": { "filter[remote_addr][]": { "style": "form", "explode": true }, "filter[ja3_hash][]": { "style": "form", "explode": true }, "filter[request_method][]": { "style": "form", "explode": true }, "filter[http_status][]": { "style": "form", "explode": true }, "filter[http_user_agent][]": { "style": "form", "explode": true }, "filter[asn][]": { "style": "form", "explode": true } } } }, "required": true } } }, "/job-completion/{id}": { "get": { "tags": [ "Jobs" ], "summary": "Get Job Status", "description": "Get status of a job by ID. Supports getting a single job via GET with URL parameter, or multiple jobs via POST with body parameter.", "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Response status message." }, "data": { "type": "object", "description": "(POST) Object mapping each requested job ID to its status string." } }, "example": { "message": "OK", "data": "success" } }, "examples": { "success-8a4a2d562d582ef9575fa7fd6eeec9dc": { "summary": "Success-Response (GET)", "value": { "message": "OK", "data": "success" } }, "success-3132bb57cd5b302418d1d2a2a8c7e03a": { "summary": "Success-Response (POST)", "value": { "message": "OK", "data": { "1357": "success", "2468": "failure", "9753": "queued" } } } } } } }, "400": { "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message." }, "data": { "description": "Error details, or an empty array when none are returned." } } } } }, "description": "Job ID is not a valid integer (GET only)." }, "404": { "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message." }, "data": { "description": "Error details, or an empty array when none are returned." } } } } }, "description": "Job not found (GET only)." } }, "parameters": [ { "name": "id", "in": "path", "description": "(GET) Job ID given in the return value of an API call.", "required": true, "schema": { "type": "string" } } ], "operationId": "get-job-completion-id" }, "post": { "tags": [ "Jobs" ], "summary": "Get Job Status", "description": "Get status of a job by ID. Supports getting a single job via GET with URL parameter, or multiple jobs via POST with body parameter.", "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Response status message." }, "data": { "type": "object", "description": "(POST) Object mapping each requested job ID to its status string." } }, "example": { "message": "OK", "data": "success" } }, "examples": { "success-8a4a2d562d582ef9575fa7fd6eeec9dc": { "summary": "Success-Response (GET)", "value": { "message": "OK", "data": "success" } }, "success-3132bb57cd5b302418d1d2a2a8c7e03a": { "summary": "Success-Response (POST)", "value": { "message": "OK", "data": { "1357": "success", "2468": "failure", "9753": "queued" } } } } } } }, "400": { "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message." }, "data": { "description": "Error details, or an empty array when none are returned." } } } } }, "description": "Job ID is not a valid integer (GET only)." }, "404": { "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message." }, "data": { "description": "Error details, or an empty array when none are returned." } } } } }, "description": "Job not found (GET only)." } }, "parameters": [ { "name": "id", "in": "path", "description": "(GET) Job ID given in the return value of an API call.", "required": true, "schema": { "type": "string" } } ], "operationId": "post-job-completion-id", "requestBody": { "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "properties": { "jobs": { "type": "array", "items": { "type": "string" }, "description": "(POST) Array of job IDs to check status for." } } } } } } } }, "/job-status": { "get": { "tags": [ "Jobs" ], "summary": "Get Job Statuses", "description": "Get full status details of one or more jobs by ID. Returns complete job object including status, data, and metadata.", "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Response status message." }, "data": { "type": "object", "description": "(POST) Object mapping each requested job ID to its full job object.", "properties": { "_status": { "type": "string", "description": "Job status: \"success\", \"failure\", or \"queued\"." } } } }, "example": { "message": "OK", "data": { "_status": "success", "id": "1357" } } }, "examples": { "success-b4f15cb299da80b3745c6a8541818f03": { "summary": "Success-Response (GET)", "value": { "message": "OK", "data": { "_status": "success", "id": "1357" } } }, "success-e6f50216b2cb3fe54ce78278ad0b5d9a": { "summary": "Success-Response (POST)", "value": { "message": "OK", "data": { "1357": { "_status": "success" }, "2468": { "_status": "failure" }, "9753": { "_status": "queued" } } } } } } } }, "400": { "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message." }, "data": { "description": "Error details, or an empty array when none are returned." } } } } }, "description": "Job ID is not a valid integer (GET only)." }, "404": { "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message." }, "data": { "description": "Error details, or an empty array when none are returned." } } } } }, "description": "Job not found (GET only)." } }, "operationId": "get-job-status" }, "post": { "tags": [ "Jobs" ], "summary": "Get Job Statuses", "description": "Get full status details of one or more jobs by ID. Returns complete job object including status, data, and metadata.", "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Response status message." }, "data": { "type": "object", "description": "(POST) Object mapping each requested job ID to its full job object.", "properties": { "_status": { "type": "string", "description": "Job status: \"success\", \"failure\", or \"queued\"." } } } }, "example": { "message": "OK", "data": { "_status": "success", "id": "1357" } } }, "examples": { "success-b4f15cb299da80b3745c6a8541818f03": { "summary": "Success-Response (GET)", "value": { "message": "OK", "data": { "_status": "success", "id": "1357" } } }, "success-e6f50216b2cb3fe54ce78278ad0b5d9a": { "summary": "Success-Response (POST)", "value": { "message": "OK", "data": { "1357": { "_status": "success" }, "2468": { "_status": "failure" }, "9753": { "_status": "queued" } } } } } } } }, "400": { "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message." }, "data": { "description": "Error details, or an empty array when none are returned." } } } } }, "description": "Job ID is not a valid integer (GET only)." }, "404": { "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message." }, "data": { "description": "Error details, or an empty array when none are returned." } } } } }, "description": "Job not found (GET only)." } }, "operationId": "post-job-status", "requestBody": { "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "properties": { "jobs": { "type": "array", "items": { "type": "string" }, "description": "(POST) Array of job IDs to check status for." } } } } } } } }, "/job-status/{id}": { "get": { "tags": [ "Jobs" ], "summary": "Get Job Statuses", "description": "Get full status details of one or more jobs by ID. Returns complete job object including status, data, and metadata.", "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Response status message." }, "data": { "type": "object", "description": "(POST) Object mapping each requested job ID to its full job object.", "properties": { "_status": { "type": "string", "description": "Job status: \"success\", \"failure\", or \"queued\"." } } } }, "example": { "message": "OK", "data": { "_status": "success", "id": "1357" } } }, "examples": { "success-b4f15cb299da80b3745c6a8541818f03": { "summary": "Success-Response (GET)", "value": { "message": "OK", "data": { "_status": "success", "id": "1357" } } }, "success-e6f50216b2cb3fe54ce78278ad0b5d9a": { "summary": "Success-Response (POST)", "value": { "message": "OK", "data": { "1357": { "_status": "success" }, "2468": { "_status": "failure" }, "9753": { "_status": "queued" } } } } } } } }, "400": { "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message." }, "data": { "description": "Error details, or an empty array when none are returned." } } } } }, "description": "Job ID is not a valid integer (GET only)." }, "404": { "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message." }, "data": { "description": "Error details, or an empty array when none are returned." } } } } }, "description": "Job not found (GET only)." } }, "parameters": [ { "name": "id", "in": "path", "description": "(GET) Job ID.", "required": true, "schema": { "type": "string" } } ], "operationId": "get-job-status-id" }, "post": { "tags": [ "Jobs" ], "summary": "Get Job Statuses", "description": "Get full status details of one or more jobs by ID. Returns complete job object including status, data, and metadata.", "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Response status message." }, "data": { "type": "object", "description": "(POST) Object mapping each requested job ID to its full job object.", "properties": { "_status": { "type": "string", "description": "Job status: \"success\", \"failure\", or \"queued\"." } } } }, "example": { "message": "OK", "data": { "_status": "success", "id": "1357" } } }, "examples": { "success-b4f15cb299da80b3745c6a8541818f03": { "summary": "Success-Response (GET)", "value": { "message": "OK", "data": { "_status": "success", "id": "1357" } } }, "success-e6f50216b2cb3fe54ce78278ad0b5d9a": { "summary": "Success-Response (POST)", "value": { "message": "OK", "data": { "1357": { "_status": "success" }, "2468": { "_status": "failure" }, "9753": { "_status": "queued" } } } } } } } }, "400": { "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message." }, "data": { "description": "Error details, or an empty array when none are returned." } } } } }, "description": "Job ID is not a valid integer (GET only)." }, "404": { "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message." }, "data": { "description": "Error details, or an empty array when none are returned." } } } } }, "description": "Job not found (GET only)." } }, "parameters": [ { "name": "id", "in": "path", "description": "(GET) Job ID.", "required": true, "schema": { "type": "string" } } ], "operationId": "post-job-status-id", "requestBody": { "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "properties": { "jobs": { "type": "array", "items": { "type": "string" }, "description": "(POST) Array of job IDs to check status for." } } } } } } } }, "/migration/get/{migration_id}": { "post": { "tags": [ "Migrations" ], "summary": "Get Migration Details", "description": "Retrieve details of a migration. Sensitive information such as SSH keys and passwords are redacted from the response.", "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Response status message." }, "data": { "type": "object", "description": "Migration object.", "properties": { "atomic_site_migration_id": { "type": "number", "description": "Migration ID." }, "atomic_site_id": { "type": "number", "description": "Site ID." }, "atomic_client_id": { "type": "number", "description": "Client ID." }, "state": { "type": "string", "description": "Current migration state." }, "created": { "type": "string", "description": "Creation timestamp." }, "updated": { "type": "string", "description": "Last update timestamp." }, "args": { "type": "object", "description": "Migration arguments object.", "properties": { "remote-user": { "type": "string", "description": "Remote server username." }, "remote-host": { "type": "string", "description": "Remote server hostname." }, "remote-port": { "type": "string", "description": "Remote port number." }, "remote-domain": { "type": "string", "description": "Remote domain name." }, "migration-type": { "type": "string", "description": "Migration type (\"ssh\" or \"wp-plugin\")." }, "ssh-id-pub": { "type": "string", "description": "SSH public key (for ssh type)." } } } } } } } } } }, "400": { "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message." }, "data": { "description": "Error details, or an empty array when none are returned." } } } } }, "description": "Invalid migration ID format." }, "403": { "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message." }, "data": { "description": "Error details, or an empty array when none are returned." } } } } }, "description": "Access denied." }, "404": { "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message." }, "data": { "description": "Error details, or an empty array when none are returned." } } } } }, "description": "Migration not found." } }, "parameters": [ { "name": "migration_id", "in": "path", "description": "Migration ID.", "required": true, "schema": { "type": "number" } } ], "operationId": "post-migration-get-migration_id" } }, "/response-ticket/multi-status": { "post": { "tags": [ "Response Tickets" ], "summary": "Get Multiple Response Ticket Statuses", "description": "Retrieve the current status of multiple response tickets in a single request. Requires the \"response-ticket/multi-status\" extended endpoint authorization.", "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Response status message." }, "data": { "type": "object", "description": "Result object.", "properties": { "status": { "type": "object", "description": "Object mapping each requested ticket ID to its status string (\"success\", \"failure\", \"running\", or \"unknown\")." } } } }, "example": { "message": "OK", "data": { "status": { "67a3f000.abc123": "success", "67a3f001.def456": "running", "67a3f002.ghi789": "unknown" } } } }, "examples": { "success-70047c8dfb48508da8c47535b32ba994": { "summary": "Success-Response", "value": { "message": "OK", "data": { "status": { "67a3f000.abc123": "success", "67a3f001.def456": "running", "67a3f002.ghi789": "unknown" } } } } } } } }, "400": { "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message." }, "data": { "description": "Error details, or an empty array when none are returned." } } } } }, "description": "Access not authorized for this extended endpoint." } }, "operationId": "post-response-ticket-multi-status", "requestBody": { "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "properties": { "response-tickets": { "type": "array", "items": { "type": "string" }, "description": "Array of response ticket IDs to look up." } } } } } } } }, "/logs/client/{client}/error": { "post": { "tags": [ "Logs" ], "summary": "Get PHP Error Logs for a Client", "description": "Get PHP error log data across all sites for a client. Logs are only guaranteed for 28 days; a start timestamp before that may return incomplete data. The window includes start and excludes end: [start, end). Choose end after start for a nonempty window. For another page, repeat the same fixed window, filters, page size, and ordering with the returned scroll_id. Stop when scroll_id is null.", "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Response message (\"OK\" on success)." }, "data": { "type": "object", "description": "Response data.", "properties": { "total_results": { "oneOf": [ { "type": "number" }, { "type": "null" } ], "description": "Total matching log entries, or null if unavailable." }, "logs": { "type": "array", "items": { "type": "object", "properties": { "atomic_site_id": { "description": "Stored site ID identifying the source site; defaults to 0 when absent." }, "message": { "type": "string", "description": "Error message text." }, "severity": { "type": "string", "description": "Severity level (e.g. \"User\", \"Warning\", \"Deprecated\", \"Fatal error\")." }, "kind": { "type": "string", "description": "Error kind." }, "name": { "type": "string", "description": "Error name." }, "file": { "type": "string", "description": "Absolute server path to the file where the error occurred." }, "line": { "description": "Stored line number where the error occurred; defaults to an empty string when absent." }, "timestamp": { "type": "string", "description": "ISO 8601 timestamp of the log entry." } } }, "description": "Array of log entry objects. Each entry includes atomic_site_id identifying the source site." }, "scroll_id": { "oneOf": [ { "type": "string" }, { "type": "null" } ], "description": "Opaque next-page cursor, or null when no more results are available." } } } }, "example": { "message": "OK", "data": { "total_results": 0, "logs": [], "scroll_id": null } } }, "examples": { "success-3f2c97f0773a15782abc055c69ddd5d9": { "summary": "{json} Empty response", "value": { "message": "OK", "data": { "total_results": 0, "logs": [], "scroll_id": null } } } } } } }, "400": { "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message." }, "data": { "description": "Error details, or an empty array when none are returned." } }, "example": { "message": "Missing required parameter: start", "data": [] } }, "examples": { "error-df759a5b1f6d9c73ebfdda7c7c4235f4": { "summary": "{json} Missing start", "value": { "message": "Missing required parameter: start", "data": [] } } } } }, "description": "Missing or invalid parameter. Possible causes: missing start or end, unparseable date string, start > end, non-integer or out-of-range page_size, malformed scroll_id, invalid sort_order, or unrecognized filter key." }, "403": { "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message." }, "data": { "description": "Error details, or an empty array when none are returned." } } } } }, "description": "Access denied or unknown client." }, "500": { "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message." }, "data": { "description": "Error details, or an empty array when none are returned." } } } } }, "description": "Search backend error." } }, "parameters": [ { "name": "client", "in": "path", "description": "Client ID or client name (slug).", "required": true, "schema": { "type": "string" } } ], "operationId": "post-logs-client-client-error", "requestBody": { "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "properties": { "start": { "oneOf": [ { "type": "integer" }, { "type": "string" } ], "description": "Inclusive start: Unix seconds or a date string parseable by strtotime()." }, "end": { "oneOf": [ { "type": "integer" }, { "type": "string" } ], "description": "Exclusive end: Unix seconds or a date string parseable by strtotime(). Must not precede start." }, "page_size": { "type": "integer", "minimum": 0, "maximum": 10000, "description": "Maximum records per request. Use a positive page size for pagination.", "default": 500 }, "scroll_id": { "type": "string", "description": "Opaque cursor returned by a previous response. Pass it back to retrieve the next page of results." }, "sort_order": { "type": "string", "enum": [ "asc", "desc" ], "description": "Sort direction for results. Default \"asc\".", "default": "asc" }, "filter[severity][]": { "type": "array", "items": { "type": "string", "enum": [ "User", "Warning", "Deprecated", "Fatal error" ] }, "description": "Severity levels to include." } }, "required": [ "start", "end" ] }, "encoding": { "filter[severity][]": { "style": "form", "explode": true } } } }, "required": true } } }, "/logs/site/{site}/error": { "post": { "tags": [ "Logs" ], "summary": "Get PHP Error Logs for a Site", "description": "Get PHP error log data for a site. Logs are only guaranteed for 28 days; a start timestamp before that may return incomplete data. The window includes start and excludes end: [start, end). Choose end after start for a nonempty window. For the next page, repeat the same fixed window, filters, page size, and ordering with the returned scroll_id. Stop when scroll_id is null.\n\nIllustrative severity-filter request. Replace SITE_ID and API_AUTH_TOKEN with your site's ID and an authorized API key. Keep LOG_START and LOG_END unchanged when requesting another page.\n\n```bash\nLOG_END=$(date +%s)\nLOG_START=$((LOG_END - 600))\ncurl --request POST 'https://atomic-api.wordpress.com/api/v1.0/logs/site/SITE_ID/error' \\\n --header 'Auth: API_AUTH_TOKEN' \\\n --data-urlencode \"start=$LOG_START\" \\\n --data-urlencode \"end=$LOG_END\" \\\n --data-urlencode 'filter[severity][]=Warning' \\\n --data-urlencode 'filter[severity][]=Fatal error'\n```\n\nFor another page, repeat the request and add `--data-urlencode 'scroll_id=RETURNED_SCROLL_ID'` with the returned cursor.", "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Response message (\"OK\" on success)." }, "data": { "type": "object", "description": "Response data.", "properties": { "total_results": { "oneOf": [ { "type": "number" }, { "type": "null" } ], "description": "Total matching log entries, or null if unavailable." }, "logs": { "type": "array", "items": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message text." }, "severity": { "type": "string", "description": "Severity level (e.g. \"User\", \"Warning\", \"Deprecated\", \"Fatal error\")." }, "kind": { "type": "string", "description": "Error kind." }, "name": { "type": "string", "description": "Error name." }, "file": { "type": "string", "description": "Absolute server path to the file where the error occurred." }, "line": { "description": "Stored line number where the error occurred; defaults to an empty string when absent." }, "timestamp": { "type": "string", "description": "ISO 8601 timestamp of the log entry." }, "atomic_site_id": { "description": "Stored site ID; defaults to 0 when absent." } } }, "description": "Array of log entry objects." }, "scroll_id": { "oneOf": [ { "type": "string" }, { "type": "null" } ], "description": "Opaque next-page cursor, or null when no more results are available." } } } }, "example": { "message": "OK", "data": { "total_results": 1, "logs": [ { "message": "Example PHP warning", "severity": "Warning", "kind": "plugins", "name": "example-plugin", "file": "/srv/htdocs/wp-content/plugins/example-plugin/example.php", "line": "42", "timestamp": "2024-01-01T00:00:00.000Z", "atomic_site_id": 123456 } ], "scroll_id": null } } }, "examples": { "success-20f4d8b72165da7a7b9abe742a3e14be": { "summary": "{json} Final page (fictional log entry)", "value": { "message": "OK", "data": { "total_results": 1, "logs": [ { "message": "Example PHP warning", "severity": "Warning", "kind": "plugins", "name": "example-plugin", "file": "/srv/htdocs/wp-content/plugins/example-plugin/example.php", "line": "42", "timestamp": "2024-01-01T00:00:00.000Z", "atomic_site_id": 123456 } ], "scroll_id": null } } }, "success-3f2c97f0773a15782abc055c69ddd5d9": { "summary": "{json} Empty response", "value": { "message": "OK", "data": { "total_results": 0, "logs": [], "scroll_id": null } } } } } } }, "400": { "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message." }, "data": { "description": "Error details, or an empty array when none are returned." } }, "example": { "message": "Missing required parameter: start", "data": [] } }, "examples": { "error-df759a5b1f6d9c73ebfdda7c7c4235f4": { "summary": "{json} Missing start", "value": { "message": "Missing required parameter: start", "data": [] } } } } }, "description": "Missing or invalid parameter. Possible causes: missing start or end, unparseable date string, start > end, non-integer or out-of-range page_size, malformed scroll_id, invalid sort_order, or unrecognized filter key." }, "403": { "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message." }, "data": { "description": "Error details, or an empty array when none are returned." } } } } }, "description": "Access denied." }, "404": { "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message." }, "data": { "description": "Error details, or an empty array when none are returned." } } } } }, "description": "Site not found." }, "500": { "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message." }, "data": { "description": "Error details, or an empty array when none are returned." } } } } }, "description": "Search backend error." } }, "parameters": [ { "name": "site", "in": "path", "description": "Site ID or domain.", "required": true, "schema": { "type": "string" } } ], "operationId": "post-logs-site-site-error", "requestBody": { "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "properties": { "start": { "oneOf": [ { "type": "integer" }, { "type": "string" } ], "description": "Inclusive start: Unix seconds or a date string parseable by strtotime()." }, "end": { "oneOf": [ { "type": "integer" }, { "type": "string" } ], "description": "Exclusive end: Unix seconds or a date string parseable by strtotime(). Must not precede start." }, "page_size": { "type": "integer", "minimum": 0, "maximum": 10000, "description": "Maximum records per request. Use a positive page size for pagination.", "default": 500 }, "scroll_id": { "type": "string", "description": "Opaque cursor returned by a previous response. Pass it back to retrieve the next page of results." }, "sort_order": { "type": "string", "enum": [ "asc", "desc" ], "description": "Sort direction for results. Default \"asc\".", "default": "asc" }, "filter[severity][]": { "type": "array", "items": { "type": "string", "enum": [ "User", "Warning", "Deprecated", "Fatal error" ] }, "description": "Severity levels to include." } }, "required": [ "start", "end" ] }, "encoding": { "filter[severity][]": { "style": "form", "explode": true } } } }, "required": true } } }, "/logs/client/{client}/error/summary": { "post": { "tags": [ "Logs" ], "summary": "Get PHP Error Summary for a Client", "description": "Get aggregated PHP error data across all sites for a client: top sites by error volume and top plugins by error count. The window includes start and excludes end: [start, end). Choose end after start for a nonempty window. A bucket interval is selected even when resolution is omitted. Every returned top_sites_by_errors and top_plugins_by_errors entry includes timeseries. The response does not return the selected resolution.", "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Response message (\"OK\" on success)." }, "data": { "type": "object", "description": "Response data.", "properties": { "top_sites_by_errors": { "type": "array", "items": { "type": "object", "properties": { "atomic_site_id": { "type": "integer", "description": "Numeric site ID." }, "domain": { "oneOf": [ { "type": "string" }, { "type": "null" } ], "description": "Primary domain name of the site, or null if unavailable." }, "count": { "type": "integer", "description": "Total error count for this site." }, "severity_breakdown": { "oneOf": [ { "type": "object" }, { "type": "array" } ], "description": "Error counts keyed by severity level (e.g. {\"Fatal error\": 3, \"Warning\": 1}); [] when empty." }, "timeseries": { "type": "array", "items": { "type": "object", "properties": { "timestamp": { "type": "integer", "description": "Unix timestamp for the start of the bucket, in seconds." }, "count": { "type": "integer", "description": "Number of errors in the bucket." } } }, "description": "Per-bucket timeseries, also present when resolution is omitted." } } }, "description": "Top 10 sites by error count." }, "top_plugins_by_errors": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "description": "Plugin or theme slug." }, "type": { "type": "string", "description": "Asset type: \"plugin\", \"theme\", or \"mu-plugin\"." }, "count": { "type": "integer", "description": "Total error count." }, "timeseries": { "type": "array", "items": { "type": "object", "properties": { "timestamp": { "type": "integer", "description": "Unix timestamp for the start of the bucket, in seconds." }, "count": { "type": "integer", "description": "Number of errors in the bucket." } } }, "description": "Per-bucket timeseries, also present when resolution is omitted." } } }, "description": "Top 10 plugins/themes by error count." } } } }, "example": { "message": "OK", "data": { "top_sites_by_errors": [ { "atomic_site_id": 123456, "domain": null, "count": 2, "severity_breakdown": { "Warning": 2 }, "timeseries": [ { "timestamp": 1704067200, "count": 2 } ] } ], "top_plugins_by_errors": [ { "name": "example-plugin", "type": "plugin", "count": 2, "timeseries": [ { "timestamp": 1704067200, "count": 2 } ] } ] } } }, "examples": { "success-1aa31a95618648a6ef4f0cbae3260b38": { "summary": "{json} Summary response (fictional data)", "value": { "message": "OK", "data": { "top_sites_by_errors": [ { "atomic_site_id": 123456, "domain": null, "count": 2, "severity_breakdown": { "Warning": 2 }, "timeseries": [ { "timestamp": 1704067200, "count": 2 } ] } ], "top_plugins_by_errors": [ { "name": "example-plugin", "type": "plugin", "count": 2, "timeseries": [ { "timestamp": 1704067200, "count": 2 } ] } ] } } }, "success-bcfd94bc232e1fe5771a54a4ebe656e9": { "summary": "{json} Empty summary", "value": { "message": "OK", "data": { "top_sites_by_errors": [], "top_plugins_by_errors": [] } } } } } } }, "400": { "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message." }, "data": { "description": "Error details, or an empty array when none are returned." } }, "example": { "message": "Resolution must be a positive integer of at least 60 seconds", "data": [] } }, "examples": { "error-43f7e56e21eda25d33eb3072b8183bfa": { "summary": "{json} Invalid resolution", "value": { "message": "Resolution must be a positive integer of at least 60 seconds", "data": [] } } } } }, "description": "Missing or invalid start/end, start > end, unrecognized filter key, or resolution below 60 or not a decimal-digit integer." }, "403": { "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message." }, "data": { "description": "Error details, or an empty array when none are returned." } } } } }, "description": "Access denied." }, "500": { "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message." }, "data": { "description": "Error details, or an empty array when none are returned." } } } } }, "description": "Search backend error." } }, "parameters": [ { "name": "client", "in": "path", "description": "Client ID or client name (slug).", "required": true, "schema": { "type": "string" } } ], "operationId": "post-logs-client-client-error-summary", "requestBody": { "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "properties": { "start": { "oneOf": [ { "type": "integer" }, { "type": "string" } ], "description": "Inclusive start: Unix seconds or a date string parseable by strtotime()." }, "end": { "oneOf": [ { "type": "integer" }, { "type": "string" } ], "description": "Exclusive end: Unix seconds or a date string parseable by strtotime(). Must not precede start." }, "resolution": { "type": "integer", "minimum": 60, "description": "Bucket interval in seconds. Automatically selected from the requested time range when omitted." }, "filter[severity][]": { "type": "array", "items": { "type": "string", "enum": [ "User", "Warning", "Deprecated", "Fatal error" ] }, "description": "Severity levels to include." } }, "required": [ "start", "end" ] }, "encoding": { "filter[severity][]": { "style": "form", "explode": true } } } }, "required": true } } }, "/logs/site/{site}/error/summary": { "post": { "tags": [ "Logs" ], "summary": "Get PHP Error Summary for a Site", "description": "Get aggregated PHP error data for a site: error rate over time and top plugins by error count. The window includes start and excludes end: [start, end). Choose end after start for a nonempty window. A bucket interval is selected even when resolution is omitted. Each returned plugin entry includes timeseries; the response does not return the selected resolution.", "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Response message (\"OK\" on success)." }, "data": { "type": "object", "description": "Response data.", "properties": { "error_rate": { "type": "array", "items": { "type": "object", "properties": { "timestamp": { "type": "integer", "description": "Unix timestamp for the start of the bucket, in seconds." }, "count": { "type": "integer", "description": "Total errors in this bucket." }, "severities": { "oneOf": [ { "type": "object" }, { "type": "array" } ], "description": "Error counts keyed by severity level (e.g. {\"Fatal error\": 3, \"Warning\": 1}); [] when empty." } } }, "description": "Time-bucketed error counts." }, "top_plugins_by_errors": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "description": "Plugin or theme slug." }, "type": { "type": "string", "description": "Asset type: \"plugin\", \"theme\", or \"mu-plugin\"." }, "count": { "type": "integer", "description": "Number of errors." }, "timeseries": { "type": "array", "items": { "type": "object", "properties": { "timestamp": { "type": "integer", "description": "Unix timestamp for the start of the bucket, in seconds." }, "count": { "type": "integer", "description": "Number of errors in the bucket." } } }, "description": "Per-bucket timeseries (timestamp, count) over the requested range." } } }, "description": "Top 10 plugins/themes by error count." } } } }, "example": { "message": "OK", "data": { "error_rate": [], "top_plugins_by_errors": [] } } }, "examples": { "success-279ff910540fa1e1ad84982d92cafe90": { "summary": "{json} Empty summary", "value": { "message": "OK", "data": { "error_rate": [], "top_plugins_by_errors": [] } } } } } } }, "400": { "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message." }, "data": { "description": "Error details, or an empty array when none are returned." } }, "example": { "message": "Resolution must be a positive integer of at least 60 seconds", "data": [] } }, "examples": { "error-43f7e56e21eda25d33eb3072b8183bfa": { "summary": "{json} Invalid resolution", "value": { "message": "Resolution must be a positive integer of at least 60 seconds", "data": [] } } } } }, "description": "Missing or invalid start/end, start > end, unrecognized filter key, or resolution below 60 or not a decimal-digit integer." }, "403": { "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message." }, "data": { "description": "Error details, or an empty array when none are returned." } } } } }, "description": "Access denied." }, "404": { "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message." }, "data": { "description": "Error details, or an empty array when none are returned." } } } } }, "description": "Site not found." }, "500": { "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message." }, "data": { "description": "Error details, or an empty array when none are returned." } } } } }, "description": "Search backend error." } }, "parameters": [ { "name": "site", "in": "path", "description": "Site ID or domain.", "required": true, "schema": { "type": "string" } } ], "operationId": "post-logs-site-site-error-summary", "requestBody": { "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "properties": { "start": { "oneOf": [ { "type": "integer" }, { "type": "string" } ], "description": "Inclusive start: Unix seconds or a date string parseable by strtotime()." }, "end": { "oneOf": [ { "type": "integer" }, { "type": "string" } ], "description": "Exclusive end: Unix seconds or a date string parseable by strtotime(). Must not precede start." }, "resolution": { "type": "integer", "minimum": 60, "description": "Bucket interval in seconds. Automatically selected from the requested time range when omitted." }, "filter[severity][]": { "type": "array", "items": { "type": "string", "enum": [ "User", "Warning", "Deprecated", "Fatal error" ] }, "description": "Severity levels to include." } }, "required": [ "start", "end" ] }, "encoding": { "filter[severity][]": { "style": "form", "explode": true } } } }, "required": true } } }, "/get-php-versions/{client}[/verbose]": { "get": { "tags": [ "Servers" ], "summary": "Get PHP Versions", "description": "Get a list of available PHP versions, in either simplified (default) or verbose format.", "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Response status message." }, "data": { "type": "object", "description": "(verbose) Object with \"default\" string and \"available\" object mapping version strings to metadata." } }, "example": { "message": "OK", "data": [ "8.1", "8.2", "8.3" ] } }, "examples": { "success-232843953e29725c74f8a51c281d2255": { "summary": "Success-Response", "value": { "message": "OK", "data": [ "8.1", "8.2", "8.3" ] } } } } } }, "400": { "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message." }, "data": { "description": "Error details, or an empty array when none are returned." } } } } }, "description": "Invalid or unauthorized client." } }, "parameters": [ { "name": "client", "in": "path", "description": "Client identifier.", "required": true, "schema": { "type": "string" } }, { "name": "verbose", "in": "query", "description": "If \"verbose\", returns detailed version metadata instead of a simple list.", "required": false, "schema": { "type": "string" } } ], "operationId": "get-get-php-versions-client[-verbose]" } }, "/alias-pkey/get/{client}/{category}/{name}": { "get": { "tags": [ "SSH" ], "summary": "Get Public Key", "description": "Retrieve a single aliasable public key.", "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Response status message." }, "data": { "type": "object", "description": "Public key details, or null if not found.", "properties": { "id": { "type": "number", "description": "Public key ID." }, "name": { "type": "string", "description": "Key name." }, "fingerprint": { "type": "string", "description": "SHA256 fingerprint." } } } } } } } }, "403": { "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message." }, "data": { "description": "Error details, or an empty array when none are returned." } } } } }, "description": "Access denied." } }, "parameters": [ { "name": "client", "in": "path", "description": "Client name or ID.", "required": true, "schema": { "type": "string" } }, { "name": "category", "in": "path", "description": "Category name.", "required": true, "schema": { "type": "string" } }, { "name": "name", "in": "path", "description": "Key name.", "required": true, "schema": { "type": "string" } } ], "operationId": "get-alias-pkey-get-client-category-name" } }, "/response-ticket/get/full": { "post": { "tags": [ "Response Tickets" ], "summary": "Get Response Ticket Details", "description": "Retrieve all data for the response ticket including all messages.", "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Response status message." }, "data": { "type": "object", "description": "Ticket details.", "properties": { "created": { "type": "string", "description": "Creation timestamp." }, "created_ts": { "type": "number", "description": "Creation timestamp (Unix)." }, "response_count": { "type": "number", "description": "Number of responses in the ticket." }, "status": { "type": "string", "description": "Ticket status, or null if not yet set." }, "responses": { "type": "array", "items": { "type": "object", "properties": { "created": { "type": "string", "description": "Message creation timestamp." }, "created_ts": { "type": "number", "description": "Message creation timestamp (Unix)." }, "message": { "type": "string", "description": "Response message content." } } }, "description": "Array of response messages." } } } } } } } }, "400": { "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message." }, "data": { "description": "Error details, or an empty array when none are returned." } } } } }, "description": "Missing response-ticket-id." }, "202": { "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message." }, "data": { "description": "Error details, or an empty array when none are returned." } } } } }, "description": "Ticket has not yet received a response; retry after 1 second." }, "404": { "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message." }, "data": { "description": "Error details, or an empty array when none are returned." } } } } }, "description": "Ticket not found." } }, "operationId": "post-response-ticket-get-full", "requestBody": { "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "properties": { "response-ticket-id": { "type": "string", "description": "Response ticket ID." } }, "required": [ "response-ticket-id" ] } } } } } }, "/response-ticket/get/summary": { "post": { "tags": [ "Response Tickets" ], "summary": "Get Response Ticket Summary", "description": "Retrieve metadata about the response ticket.", "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Response status message." }, "data": { "type": "object", "description": "Ticket metadata.", "properties": { "created": { "type": "string", "description": "Creation timestamp." }, "created_ts": { "type": "number", "description": "Creation timestamp (Unix)." }, "response_count": { "type": "number", "description": "Number of responses in the ticket." }, "status": { "type": "string", "description": "Ticket status, or null if not yet set." } } } } } } } }, "400": { "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message." }, "data": { "description": "Error details, or an empty array when none are returned." } } } } }, "description": "Missing response-ticket-id." }, "202": { "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message." }, "data": { "description": "Error details, or an empty array when none are returned." } } } } }, "description": "Ticket has not yet received a response; retry after 1 second." }, "404": { "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message." }, "data": { "description": "Error details, or an empty array when none are returned." } } } } }, "description": "Ticket not found (and old enough to have been deleted)." } }, "operationId": "post-response-ticket-get-summary", "requestBody": { "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "properties": { "response-ticket-id": { "type": "string", "description": "Response ticket ID." } }, "required": [ "response-ticket-id" ] } } } } } }, "/site-backup-get/{service}/{identifier}/{backup_id}": { "get": { "tags": [ "Backups" ], "summary": "Get Site Backup Data", "description": "Download a site's filesystem or database backup.\n\nThe response body is the raw backup blob, not a JSON envelope. The exact bytes and headers depend on the backup `type` returned by `site-backup-info` and `site-backups-list`:\n\n- `fs` and `ondemand-fs`: `Content-Type: application/octet-stream`, no `Content-Encoding`. Body is a bzip2-compressed tar archive. Recommended filename: `--fs.tar.bz2`.\n- `db` and `ondemand-db`: `Content-Type: application/sql`, always returned with `Content-Encoding: gzip` regardless of the request's `Accept-Encoding`. Body on the wire is a gzip-compressed MySQL dump. Recommended filename: `--db.sql.gz` for the raw bytes, or `--db.sql` if the client decompresses in transit.\n- `ondemand` (legacy): inspect `type` via `site-backup-info` and follow the row above that matches the actual contents.\n\nBecause DB downloads include `Content-Encoding: gzip` unconditionally, clients that honor the header (browsers, `curl --compressed`, most HTTP libraries with default settings) will deliver plain SQL text to disk, while clients that ignore it (default `curl -o file`, `wget` without `--compressed`) will deliver gzip-compressed bytes. The response is identical; only client handling differs. For byte-exact downloads, send `Accept-Encoding: identity` and avoid client-side auto-decompression flags such as `curl --compressed`.\n\n`Content-Disposition` is not set on either response, so callers must choose the filename and extension. `Accept-Ranges: bytes` is honored, which is useful for resuming the multi-GB filesystem downloads.\n\nWhen proxying the response to an end user, stream the body straight through without buffering -- FS backups can exceed several gigabytes. Decide deliberately whether to forward the upstream `Content-Encoding: gzip` to the end user (and serve `.sql.gz`) or decompress server-side first (and serve `.sql`).", "responses": { "200": { "description": "Successful operation" }, "400": { "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message." }, "data": { "description": "Error details, or an empty array when none are returned." } } } } }, "description": "Invalid service identifier or unknown site." }, "404": { "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message." }, "data": { "description": "Error details, or an empty array when none are returned." } }, "example": { "message": "Not Found", "data": [] } }, "examples": { "error-fcc5021de5fd64295232140c6eeed99a": { "summary": "Error-Response", "value": { "message": "Not Found", "data": [] } } } } }, "description": "Backup not found." } }, "parameters": [ { "name": "service", "in": "path", "description": "Service type (client name or \"domain\"). Use \"domain\" to look up by domain, otherwise use client identifier to look up by site ID.", "required": true, "schema": { "type": "string" } }, { "name": "identifier", "in": "path", "description": "Site identifier (domain name for \"domain\" lookups, otherwise site ID or WordPress.com blog ID for \"wpcom\" service).", "required": true, "schema": { "type": "string" } }, { "name": "backup_id", "in": "path", "description": "Backup identifier (the `atomic_backup_id` returned by `site-backup-info` or `site-backups-list`).", "required": true, "schema": { "type": "number" } } ], "operationId": "get-site-backup-get-service-identifier-backup_id" } }, "/site-backup-info/{service}/{identifier}/{backup_id}": { "get": { "tags": [ "Backups" ], "summary": "Get Site Backup Details", "description": "Get the details for a single backup.\n\nPass the returned `atomic_backup_id` (with its `type`) to `site-backup-get` to download the backup. The `type` determines the response format and recommended filename -- see `site-backup-get` for the per-type format details.", "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Response status message." }, "data": { "type": "object", "description": "Backup details.", "properties": { "atomic_backup_id": { "type": "string", "description": "Backup ID." }, "atomic_site_id": { "type": "string", "description": "Site ID." }, "backup_timestamp": { "type": "string", "description": "Backup timestamp in MySQL timestamp format." }, "type": { "type": "string", "enum": [ "fs", "db", "ondemand", "ondemand-fs", "ondemand-db" ], "description": "Backup type; determines the response format from `site-backup-get`." }, "bytes": { "type": "number", "description": "Backup size in bytes (if available)." } } } }, "example": { "message": "OK", "data": { "atomic_backup_id": "1234", "atomic_site_id": "5678", "backup_timestamp": "2019-08-03 00:00:00", "type": "db" } } }, "examples": { "success-b77cec811e536965134d6272237188e5": { "summary": "Success-Response", "value": { "message": "OK", "data": { "atomic_backup_id": "1234", "atomic_site_id": "5678", "backup_timestamp": "2019-08-03 00:00:00", "type": "db" } } } } } } }, "400": { "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message." }, "data": { "description": "Error details, or an empty array when none are returned." } } } } }, "description": "Invalid service identifier, backup ID, or unknown site." }, "404": { "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message." }, "data": { "description": "Error details, or an empty array when none are returned." } } } } }, "description": "Backup not found." }, "500": { "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message." }, "data": { "description": "Error details, or an empty array when none are returned." } } } } }, "description": "Database query failed." } }, "parameters": [ { "name": "service", "in": "path", "description": "Service type (client name or \"domain\"). Use \"domain\" to look up by domain, otherwise use client identifier to look up by site ID.", "required": true, "schema": { "type": "string" } }, { "name": "identifier", "in": "path", "description": "Site identifier (domain name for \"domain\" lookups, otherwise site ID or WordPress.com blog ID for \"wpcom\" service).", "required": true, "schema": { "type": "string" } }, { "name": "backup_id", "in": "path", "description": "Backup ID.", "required": true, "schema": { "type": "number" } } ], "operationId": "get-site-backup-info-service-identifier-backup_id" } }, "/get-site/{site}[/extra]": { "get": { "tags": [ "Sites" ], "summary": "Get Site Details", "description": "Get site details by site ID or domain name.", "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Response status message." }, "data": { "type": "object", "description": "Site details object.", "properties": { "atomic_site_id": { "type": "number", "description": "Site ID." }, "wpcom_blog_id": { "type": "number", "description": "WordPress.com blog ID (only relevant to WordPress.com sites)." }, "domain_name": { "type": "string", "description": "Domain name associated with the site." }, "server_pool_id": { "type": "number", "description": "Server pool ID." }, "atomic_client_id": { "type": "number", "description": "Client ID that owns this site." }, "chroot_path": { "type": "string", "description": "Web chroot path for the site (null if using client default)." }, "chroot_ssh_path": { "type": "string", "description": "SSH chroot path for the site (null if using client default)." }, "db_pass": { "type": "string", "description": "Decrypted database password." }, "jetpack_blog_token": { "type": "string", "description": "Jetpack blog token, prefixed with blog ID." }, "cache_prefix": { "type": "string", "description": "Site's randomly generated cache prefix." }, "wp_admin_user": { "type": "string", "description": "Site admin user login." }, "wp_admin_email": { "type": "string", "description": "Site admin email." }, "db_charset": { "type": "string", "description": "DB character set." }, "db_collate": { "type": "string", "description": "DB collation." }, "php_version": { "type": "string", "description": "PHP version." }, "wp_version": { "type": "string", "description": "WordPress version track (\"latest\", \"previous\", \"beta\", or \"alpha\")." }, "static_file_404": { "type": "string", "description": "Static file 404 handler (\"wordpress\" or \"lightweight\")." }, "smtp_pass": { "type": "string", "description": "SMTP password derived from the site's domain name." }, "suspended": { "type": "number", "description": "HTTP status code the site is suspended with, if suspended." }, "migrate_to_pool": { "type": "number", "description": "Destination pool ID (present when site is queued for migration)." }, "migrate_readonly": { "type": "number", "description": "Whether to set site readonly while migrating (present when queued for migration)." }, "migrate_skip_table_checksum": { "type": "number", "description": "Whether to skip table checksum during migration." }, "photon_subsizes": { "type": "number", "description": "Whether to skip generating intermediate image files (0 or 1)." }, "dereferenced_software": { "type": "number", "description": "Whether the site's software symlinks have been dereferenced (0 or 1)." }, "default_php_conns": { "type": "number", "description": "Default number of PHP connections allowed." }, "burst_php_conns": { "type": "number", "description": "Burst number of PHP connections allowed." }, "php_memory_limit": { "type": "number", "description": "PHP memory limit in MB." }, "opcache_memory_limit_mb": { "type": "number", "description": "OPcache memory limit in MB." }, "gauges_id": { "type": "string", "description": "Gauges analytics ID." }, "development_mode": { "type": "string", "description": "Development mode setting." }, "privacy_model": { "type": "string", "description": "Site privacy model." }, "site_api_key": { "type": "string", "description": "Site API key." }, "apm_until": { "type": "string", "description": "Unix timestamp until which APM is enabled (absent if expired)." }, "apm_driver": { "type": "string", "description": "APM driver (elastic, pfx)." }, "php_fs_permissions": { "type": "string", "description": "PHP filesystem permissions setting." }, "canonicalize_aliases": { "type": "string", "description": "Whether to canonicalize alias domains." }, "restore_data": { "type": "object", "description": "Restore operation metadata, if present." }, "extra": { "type": "object", "description": "Additional site info (when /extra is requested)." }, "extra[server_pool]": { "type": "object", "description": "Info about the server pool the site is running on." }, "extra[meta]": { "type": "object", "description": "Additional site-meta, if present." } } } }, "example": { "message": "OK", "data": { "atomic_site_id": 1234, "wpcom_blog_id": 3456, "domain_name": "example.com", "server_pool_id": 5678, "db_pass": "the-decrypted-database-password", "cache_prefix": "944c12dc5aa0ac2c271d7a582733cfb4", "wp_admin_user": "example-admin", "wp_admin_email": "admin@example.com", "db_charset": "latin1", "db_collate": "latin1_swedish_ci", "php_version": "8.3", "migrate_to_pool": 7890, "migrate_readonly": 12345, "photon_subsizes": 1 } } }, "examples": { "success-2625f4c789da29f53bfa7fb166dbbf7a": { "summary": "Success-Response", "value": { "message": "OK", "data": { "atomic_site_id": 1234, "wpcom_blog_id": 3456, "domain_name": "example.com", "server_pool_id": 5678, "db_pass": "the-decrypted-database-password", "cache_prefix": "944c12dc5aa0ac2c271d7a582733cfb4", "wp_admin_user": "example-admin", "wp_admin_email": "admin@example.com", "db_charset": "latin1", "db_collate": "latin1_swedish_ci", "php_version": "8.3", "migrate_to_pool": 7890, "migrate_readonly": 12345, "photon_subsizes": 1 } } }, "success-4216f8fdbe2010956fd20cbdc71ec25a": { "summary": "Success-Response, with /extra", "value": { "message": "OK", "data": { "atomic_site_id": 1234, "wpcom_blog_id": 3456, "domain_name": "example.com", "server_pool_id": 5678, "db_pass": "the-decrypted-database-password", "cache_prefix": "944c12dc5aa0ac2c271d7a582733cfb4", "wp_admin_user": "example-admin", "wp_admin_email": "admin@example.com", "db_charset": "latin1", "db_collate": "latin1_swedish_ci", "php_version": "8.3", "migrate_to_pool": 7890, "migrate_readonly": 12345, "photon_subsizes": 1, "extra": { "server_pool": { "geo_affinity": "dfw" }, "meta": { "geo_affinity": "bur" } } } } } } } } }, "403": { "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message." }, "data": { "description": "Error details, or an empty array when none are returned." } } } } }, "description": "Access denied." }, "404": { "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message." }, "data": { "description": "Error details, or an empty array when none are returned." } } } } }, "description": "Site not found." }, "500": { "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message." }, "data": { "description": "Error details, or an empty array when none are returned." } } } } }, "description": "Internal server error." } }, "parameters": [ { "name": "site", "in": "path", "description": "Site ID or domain name.", "required": true, "schema": { "oneOf": [ { "type": "string" }, { "type": "number" } ] } }, { "name": "extra", "in": "query", "description": "If present, returns additional data.", "required": false, "schema": { "type": "string" } } ], "operationId": "get-get-site-site[-extra]" } }, "/site-metrics/{site}[/summarize]": { "post": { "tags": [ "Metrics" ], "summary": "Get Site Metrics", "description": "Get time series metrics from a site.\n\n**NOTE:** This endpoint is deprecated in favor of /metrics.", "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Response status message." }, "data": { "type": "object", "description": "Response data." } } } } } }, "400": { "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message." }, "data": { "description": "Error details, or an empty array when none are returned." } } } } }, "description": "Invalid parameter." }, "403": { "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message." }, "data": { "description": "Error details, or an empty array when none are returned." } } } } }, "description": "Access denied." }, "404": { "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message." }, "data": { "description": "Error details, or an empty array when none are returned." } } } } }, "description": "Site not found." }, "500": { "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message." }, "data": { "description": "Error details, or an empty array when none are returned." } } } } }, "description": "Failed to connect to or query metrics data source." } }, "parameters": [ { "name": "site", "in": "path", "description": "Site ID or domain.", "required": true, "schema": { "type": "string" } }, { "name": "summarize", "in": "query", "description": "If present, returns summary instead of time series.", "required": false, "schema": { "type": "string" } } ], "operationId": "post-site-metrics-site[-summarize]", "requestBody": { "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "properties": { "start": { "type": "number", "description": "Unix timestamp for start of metrics data range." }, "end": { "type": "number", "description": "Unix timestamp for end of metrics data range." }, "metric": { "oneOf": [ { "type": "string" }, { "type": "array" } ], "description": "Timeseries metric to report." }, "dimension": { "oneOf": [ { "type": "string" }, { "type": "array" } ], "description": "Dimension to slice by." }, "resolution": { "type": "number", "description": "Desired time resolution in seconds." }, "max_bucket_size": { "type": "number", "description": "Maximum number of time buckets to return (1-20). Default 20." }, "filters": { "type": "array", "description": "Filters to apply to the metric request." }, "filters.column": { "type": "string", "description": "Dimension to filter on." }, "filters.operator": { "type": "string", "description": "Operator: =, !=, >, >=, <, <=, IN, NOT IN." }, "filters.value": { "oneOf": [ { "type": "string" }, { "type": "array" } ], "description": "Value to compare against." } }, "required": [ "start", "end" ] } } } } } }, "/site-phpmyadmin/{site}": { "post": { "tags": [ "Sites" ], "summary": "Get Site phpMyAdmin URL", "description": "Get a time-limited URL for accessing a site's database via phpMyAdmin.", "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Response status message." }, "data": { "type": "object", "description": "The response data.", "properties": { "url": { "type": "string", "description": "A time-limited phpMyAdmin login URL." } } } }, "example": { "message": "OK", "data": { "url": "https://at.site.domain.example.com/_pma_login?timestamp=%d&nonce=%d&token=%s" } } }, "examples": { "success-4ae8524c210ea77ee9f60d84a9fb361e": { "summary": "Success-Response", "value": { "message": "OK", "data": { "url": "https://at.site.domain.example.com/_pma_login?timestamp=%d&nonce=%d&token=%s" } } } } } } }, "404": { "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message." }, "data": { "description": "Error details, or an empty array when none are returned." } } } } }, "description": "Site not found." }, "500": { "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message." }, "data": { "description": "Error details, or an empty array when none are returned." } } } } }, "description": "Failed to generate phpMyAdmin authentication token." } }, "parameters": [ { "name": "site", "in": "path", "description": "Site ID, domain, or WordPress.com blog ID.", "required": true, "schema": { "type": "string" } } ], "operationId": "post-site-phpmyadmin-site" } }, "/usage/{site}": { "post": { "tags": [ "Usage" ], "summary": "Get Site Usage by Time Period", "description": "Get usage data for a site from a time series database.\n\nUsage meters cover compute (compute_php + compute_db), storage (storage_fs + storage_db + storage_backup), billable HTTP bandwidth, cached and uncached HTTP request counts, and email.\n\nThe response is structured for charting libraries: data.periods is an array of time buckets, each carrying a Unix timestamp and one object per selected meter. For forecasts, include the current period in the requested range. Hourly buckets with recorded usage are treated as actuals. Use /usage/:site/summarize for totals instead of time buckets.\n\nAll timestamps and period boundaries are UTC. The start is rounded down and the end is rounded up to a boundary of the requested resolution. The aligned start is inclusive and the aligned end is exclusive; both are echoed as Unix seconds in _meta. Choose end after start for a nonempty range.\n\nSupported ranges after alignment:\n- hour: less than 4 days, with start no earlier than 7 days ago. The duration check uses whole days.\n- day: at most 31 days, with start no earlier than 2 months ago.\n- month: start no earlier than 2 years ago.\n\nUsage data for an hour may be revised for up to 2 hours after the hour closes. A reconciliation pass re-aggregates late-arriving source data before then. Periods that ended more than 2 hours ago are final and safe to bill on.\n\nUnits are raw: byte-seconds, bytes, seconds, or counts. The caller is responsible for display or pricing conversions, such as byte-seconds to GB-hours.\n\nBy default, the response includes storage, compute, bandwidth, requests_uncached, requests_cached, and email. Request breakdown meters explicitly via meters: storage_fs, storage_db, storage_backup, compute_php, and compute_db. A meters selection replaces the defaults; only the selected meters appear in the response and _meta.units.\n\nDay and month forecasts are available through the end of the current month. The endpoint also accepts hourly forecasts and does not enforce the month-end limit. Forecasts use a 7-day rolling average of hourly usage. They do not account for future spikes from sales, advertising, or breaking news.\n\nWith forecast=band, forecast_low and forecast_high give an uncertainty band derived from the standard deviation of hourly usage. Forecast fields are omitted for meters without average statistics. In band mode, missing standard deviation yields a zero-width band. A forecast is the estimated total, including recorded usage, rather than an amount to add to usage.", "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Response status message (\"OK\" on success)." }, "data": { "type": "object", "description": "Response data.", "properties": { "_meta": { "type": "object", "description": "Response metadata.", "properties": { "took": { "type": "number", "description": "Usage query time in seconds; excludes the forecast query." }, "units": { "type": "object", "description": "Units keyed by the selected meter names: byte-seconds, seconds, bytes, or count." }, "meters": { "type": "array", "items": { "type": "string" }, "description": "Selected meter names, in response order." }, "forecast": { "type": "string", "description": "Requested forecast mode (avg or band), even when statistics are unavailable." }, "start": { "type": "integer", "description": "Aligned inclusive start, in Unix seconds." }, "end": { "type": "integer", "description": "Aligned exclusive end, in Unix seconds." }, "resolution": { "type": "string", "enum": [ "hour", "day", "month" ], "description": "Resolution used for the request." } } }, "periods": { "type": "array", "items": { "type": "object", "properties": { "timestamp": { "type": "integer", "description": "Bucket start, in Unix seconds." }, "storage": { "type": "object", "description": "Total storage (file system, database, and backup), in byte-seconds. Returned only when selected.", "properties": { "usage": { "type": "number", "description": "Recorded usage." }, "forecast": { "type": "number", "description": "Estimated total when forecasting applies and average statistics exist." }, "forecast_low": { "type": "number", "description": "Lower estimate in band mode." }, "forecast_high": { "type": "number", "description": "Upper estimate in band mode." } } }, "storage_fs": { "type": "object", "description": "File system storage, in byte-seconds. Request explicitly via meters. Returned only when selected.", "properties": { "usage": { "type": "number", "description": "Recorded usage." }, "forecast": { "type": "number", "description": "Estimated total when forecasting applies and average statistics exist." }, "forecast_low": { "type": "number", "description": "Lower estimate in band mode." }, "forecast_high": { "type": "number", "description": "Upper estimate in band mode." } } }, "storage_db": { "type": "object", "description": "Database storage, in byte-seconds. Request explicitly via meters. Returned only when selected.", "properties": { "usage": { "type": "number", "description": "Recorded usage." }, "forecast": { "type": "number", "description": "Estimated total when forecasting applies and average statistics exist." }, "forecast_low": { "type": "number", "description": "Lower estimate in band mode." }, "forecast_high": { "type": "number", "description": "Upper estimate in band mode." } } }, "storage_backup": { "type": "object", "description": "Backup storage, in byte-seconds. Request explicitly via meters. Returned only when selected.", "properties": { "usage": { "type": "number", "description": "Recorded usage." }, "forecast": { "type": "number", "description": "Estimated total when forecasting applies and average statistics exist." }, "forecast_low": { "type": "number", "description": "Lower estimate in band mode." }, "forecast_high": { "type": "number", "description": "Upper estimate in band mode." } } }, "compute": { "type": "object", "description": "Total PHP-FPM, SSH, and database CPU time, in seconds. Returned only when selected.", "properties": { "usage": { "type": "number", "description": "Recorded usage." }, "forecast": { "type": "number", "description": "Estimated total when forecasting applies and average statistics exist." }, "forecast_low": { "type": "number", "description": "Lower estimate in band mode." }, "forecast_high": { "type": "number", "description": "Upper estimate in band mode." } } }, "compute_php": { "type": "object", "description": "PHP-FPM and SSH CPU time, in seconds. Request explicitly via meters. Returned only when selected.", "properties": { "usage": { "type": "number", "description": "Recorded usage." }, "forecast": { "type": "number", "description": "Estimated total when forecasting applies and average statistics exist." }, "forecast_low": { "type": "number", "description": "Lower estimate in band mode." }, "forecast_high": { "type": "number", "description": "Upper estimate in band mode." } } }, "compute_db": { "type": "object", "description": "Database CPU time, in seconds. Request explicitly via meters. Returned only when selected.", "properties": { "usage": { "type": "number", "description": "Recorded usage." }, "forecast": { "type": "number", "description": "Estimated total when forecasting applies and average statistics exist." }, "forecast_low": { "type": "number", "description": "Lower estimate in band mode." }, "forecast_high": { "type": "number", "description": "Upper estimate in band mode." } } }, "bandwidth": { "type": "object", "description": "Billable HTTP bandwidth, in bytes. Returned only when selected.", "properties": { "usage": { "type": "number", "description": "Recorded usage." }, "forecast": { "type": "number", "description": "Estimated total when forecasting applies and average statistics exist." }, "forecast_low": { "type": "number", "description": "Lower estimate in band mode." }, "forecast_high": { "type": "number", "description": "Upper estimate in band mode." } } }, "requests_uncached": { "type": "object", "description": "Uncached HTTP request count. Returned only when selected.", "properties": { "usage": { "type": "number", "description": "Recorded usage." }, "forecast": { "type": "number", "description": "Estimated total when forecasting applies and average statistics exist." }, "forecast_low": { "type": "number", "description": "Lower estimate in band mode." }, "forecast_high": { "type": "number", "description": "Upper estimate in band mode." } } }, "requests_cached": { "type": "object", "description": "Cached HTTP request count. Returned only when selected.", "properties": { "usage": { "type": "number", "description": "Recorded usage." }, "forecast": { "type": "number", "description": "Estimated total when forecasting applies and average statistics exist." }, "forecast_low": { "type": "number", "description": "Lower estimate in band mode." }, "forecast_high": { "type": "number", "description": "Upper estimate in band mode." } } }, "email": { "type": "object", "description": "Emails sent count. Returned only when selected.", "properties": { "usage": { "type": "number", "description": "Recorded usage." }, "forecast": { "type": "number", "description": "Estimated total when forecasting applies and average statistics exist." }, "forecast_low": { "type": "number", "description": "Lower estimate in band mode." }, "forecast_high": { "type": "number", "description": "Upper estimate in band mode." } } } } }, "description": "Returned buckets in chronological order. Do not assume every bucket in the requested range is present." } } } }, "example": { "message": "OK", "data": { "_meta": { "took": 0.198, "meters": [ "storage", "storage_fs", "storage_db", "storage_backup", "compute", "compute_php", "compute_db", "bandwidth", "requests_uncached", "requests_cached", "email" ], "units": { "storage": "byte-seconds", "storage_fs": "byte-seconds", "storage_db": "byte-seconds", "storage_backup": "byte-seconds", "compute": "seconds", "compute_php": "seconds", "compute_db": "seconds", "bandwidth": "bytes", "requests_uncached": "count", "requests_cached": "count", "email": "count" }, "start": 1758499200, "end": 1758672000, "resolution": "day", "forecast": "band" }, "periods": [ { "timestamp": 1758499200, "storage": { "usage": 150000000000 }, "storage_fs": { "usage": 100000000000 }, "storage_db": { "usage": 40000000000 }, "storage_backup": { "usage": 10000000000 }, "compute": { "usage": 140 }, "compute_php": { "usage": 100 }, "compute_db": { "usage": 40 }, "bandwidth": { "usage": 618318 }, "requests_uncached": { "usage": 1000 }, "requests_cached": { "usage": 5000 }, "email": { "usage": 4 } }, { "timestamp": 1758585600, "storage": { "usage": 75000000000, "forecast": 112500000000, "forecast_low": 110000000000, "forecast_high": 115000000000 }, "storage_fs": { "usage": 50000000000, "forecast": 75000000000, "forecast_low": 73500000000, "forecast_high": 76500000000 }, "storage_db": { "usage": 20000000000, "forecast": 30000000000, "forecast_low": 28000000000, "forecast_high": 32000000000 }, "storage_backup": { "usage": 5000000000, "forecast": 7500000000, "forecast_low": 7500000000, "forecast_high": 7500000000 }, "compute": { "usage": 75, "forecast": 145, "forecast_low": 120, "forecast_high": 170 }, "compute_php": { "usage": 50, "forecast": 90, "forecast_low": 75, "forecast_high": 105 }, "compute_db": { "usage": 25, "forecast": 55, "forecast_low": 35, "forecast_high": 75 }, "bandwidth": { "usage": 300000, "forecast": 350000, "forecast_low": 340000, "forecast_high": 360000 }, "requests_uncached": { "usage": 400, "forecast": 410, "forecast_low": 405, "forecast_high": 415 }, "requests_cached": { "usage": 2000, "forecast": 2050, "forecast_low": 2040, "forecast_high": 2060 }, "email": { "usage": 2, "forecast": 3, "forecast_low": 2.5, "forecast_high": 3.5 } } ] } } }, "examples": { "success-b20a9702e7e7dee5c0c8ad7aa857b1b7": { "summary": "{json} All meters explicitly selected with forecast (illustrative data)", "value": { "message": "OK", "data": { "_meta": { "took": 0.198, "meters": [ "storage", "storage_fs", "storage_db", "storage_backup", "compute", "compute_php", "compute_db", "bandwidth", "requests_uncached", "requests_cached", "email" ], "units": { "storage": "byte-seconds", "storage_fs": "byte-seconds", "storage_db": "byte-seconds", "storage_backup": "byte-seconds", "compute": "seconds", "compute_php": "seconds", "compute_db": "seconds", "bandwidth": "bytes", "requests_uncached": "count", "requests_cached": "count", "email": "count" }, "start": 1758499200, "end": 1758672000, "resolution": "day", "forecast": "band" }, "periods": [ { "timestamp": 1758499200, "storage": { "usage": 150000000000 }, "storage_fs": { "usage": 100000000000 }, "storage_db": { "usage": 40000000000 }, "storage_backup": { "usage": 10000000000 }, "compute": { "usage": 140 }, "compute_php": { "usage": 100 }, "compute_db": { "usage": 40 }, "bandwidth": { "usage": 618318 }, "requests_uncached": { "usage": 1000 }, "requests_cached": { "usage": 5000 }, "email": { "usage": 4 } }, { "timestamp": 1758585600, "storage": { "usage": 75000000000, "forecast": 112500000000, "forecast_low": 110000000000, "forecast_high": 115000000000 }, "storage_fs": { "usage": 50000000000, "forecast": 75000000000, "forecast_low": 73500000000, "forecast_high": 76500000000 }, "storage_db": { "usage": 20000000000, "forecast": 30000000000, "forecast_low": 28000000000, "forecast_high": 32000000000 }, "storage_backup": { "usage": 5000000000, "forecast": 7500000000, "forecast_low": 7500000000, "forecast_high": 7500000000 }, "compute": { "usage": 75, "forecast": 145, "forecast_low": 120, "forecast_high": 170 }, "compute_php": { "usage": 50, "forecast": 90, "forecast_low": 75, "forecast_high": 105 }, "compute_db": { "usage": 25, "forecast": 55, "forecast_low": 35, "forecast_high": 75 }, "bandwidth": { "usage": 300000, "forecast": 350000, "forecast_low": 340000, "forecast_high": 360000 }, "requests_uncached": { "usage": 400, "forecast": 410, "forecast_low": 405, "forecast_high": 415 }, "requests_cached": { "usage": 2000, "forecast": 2050, "forecast_low": 2040, "forecast_high": 2060 }, "email": { "usage": 2, "forecast": 3, "forecast_low": 2.5, "forecast_high": 3.5 } } ] } } } } } } }, "400": { "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message." }, "data": { "description": "Error details, or an empty array when none are returned." } } } } }, "description": "Missing required body values, invalid timestamps, unsupported resolution/range, invalid forecast mode or meter names, or failure to query the usage backend." }, "403": { "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message." }, "data": { "description": "Error details, or an empty array when none are returned." } } } } }, "description": "Access denied." }, "404": { "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message." }, "data": { "description": "Error details, or an empty array when none are returned." } } } } }, "description": "Site not found or unavailable to the caller." } }, "parameters": [ { "name": "site", "in": "path", "description": "Site ID or domain.", "required": true, "schema": { "type": "string" } } ], "operationId": "post-usage-site", "requestBody": { "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "properties": { "start": { "type": "integer", "description": "Inclusive start of the range, in Unix seconds, rounded down to a resolution boundary." }, "end": { "type": "integer", "description": "Exclusive end of the range, in Unix seconds, rounded up to a resolution boundary." }, "resolution": { "type": "string", "enum": [ "hour", "day", "month" ], "description": "Time bucket interval. Values are case-insensitive." }, "forecast": { "type": "string", "enum": [ "avg", "band", "1", "true" ], "description": "avg returns point forecasts; band adds low/high bounds. Values are case-insensitive. Legacy 1 and true mean avg; omission or an empty value disables forecasting." }, "meters": { "type": "string", "description": "Comma-separated meter names. Also accepts PHP array notation (meters[]=compute&meters[]=bandwidth). Names are trimmed and case-insensitive; duplicates are removed. Omitted or empty input uses defaults. Valid names: storage, storage_fs, storage_db, storage_backup, compute, compute_php, compute_db, bandwidth, requests_uncached, requests_cached, email." } }, "required": [ "start", "end", "resolution" ] } } }, "required": true } } }, "/usage/{site}/summarize": { "post": { "tags": [ "Usage" ], "summary": "Get Site Usage Totals", "description": "Get usage totals for a site from a time series database.\n\nUsage meters cover compute (compute_php + compute_db), storage (storage_fs + storage_db + storage_backup), billable HTTP bandwidth, cached and uncached HTTP request counts, and email.\n\nThe response contains data.totals, with one object per selected meter for the aligned range. Use /usage/:site for data.periods, the time buckets used for charting. Forecasts are included when statistics are available and the range has hours left to forecast.\n\nAll timestamps and period boundaries are UTC. The start is rounded down and the end is rounded up to a boundary of the requested resolution. The aligned start is inclusive and the aligned end is exclusive; both are echoed as Unix seconds in _meta. Choose end after start for a nonempty range.\n\nSupported ranges after alignment:\n- hour: less than 4 days, with start no earlier than 7 days ago. The duration check uses whole days.\n- day: at most 31 days, with start no earlier than 2 months ago.\n- month: start no earlier than 2 years ago.\n\nUsage data for an hour may be revised for up to 2 hours after the hour closes. A reconciliation pass re-aggregates late-arriving source data before then. Periods that ended more than 2 hours ago are final and safe to bill on.\n\nUnits are raw: byte-seconds, bytes, seconds, or counts. The caller is responsible for display or pricing conversions, such as byte-seconds to GB-hours.\n\nBy default, the response includes storage, compute, bandwidth, requests_uncached, requests_cached, and email. Request breakdown meters explicitly via meters: storage_fs, storage_db, storage_backup, compute_php, and compute_db. A meters selection replaces the defaults; only the selected meters appear in the response and _meta.units.\n\nDay and month forecasts are available through the end of the current month. The endpoint also accepts hourly forecasts and does not enforce the month-end limit. Forecasts use a 7-day rolling average of hourly usage. They do not account for future spikes from sales, advertising, or breaking news.\n\nWith forecast=band, forecast_low and forecast_high give an uncertainty band derived from the standard deviation of hourly usage. Forecast fields are omitted for meters without average statistics. In band mode, missing standard deviation yields a zero-width band. A forecast is the estimated total, including recorded usage, rather than an amount to add to usage.", "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Response status message (\"OK\" on success)." }, "data": { "type": "object", "description": "Response data.", "properties": { "_meta": { "type": "object", "description": "Response metadata.", "properties": { "took": { "type": "number", "description": "Usage query time in seconds; excludes the forecast query." }, "units": { "type": "object", "description": "Units keyed by the selected meter names: byte-seconds, seconds, bytes, or count." }, "meters": { "type": "array", "items": { "type": "string" }, "description": "Selected meter names, in response order." }, "forecast": { "type": "string", "description": "Requested forecast mode (avg or band), even when statistics are unavailable." }, "start": { "type": "integer", "description": "Aligned inclusive start, in Unix seconds." }, "end": { "type": "integer", "description": "Aligned exclusive end, in Unix seconds." }, "resolution": { "type": "string", "enum": [ "hour", "day", "month" ], "description": "Resolution used for the request." }, "summary": { "type": "string", "enum": [ "true" ], "description": "Present on the summary route; the literal string true." } } }, "totals": { "type": "object", "description": "Usage totals keyed by selected meter names.", "properties": { "storage": { "type": "object", "description": "Total storage (file system, database, and backup), in byte-seconds. Returned only when selected.", "properties": { "usage": { "type": "number", "description": "Recorded usage." }, "forecast": { "type": "number", "description": "Estimated total when forecasting applies and average statistics exist." }, "forecast_low": { "type": "number", "description": "Lower estimate in band mode." }, "forecast_high": { "type": "number", "description": "Upper estimate in band mode." } } }, "storage_fs": { "type": "object", "description": "File system storage, in byte-seconds. Request explicitly via meters. Returned only when selected.", "properties": { "usage": { "type": "number", "description": "Recorded usage." }, "forecast": { "type": "number", "description": "Estimated total when forecasting applies and average statistics exist." }, "forecast_low": { "type": "number", "description": "Lower estimate in band mode." }, "forecast_high": { "type": "number", "description": "Upper estimate in band mode." } } }, "storage_db": { "type": "object", "description": "Database storage, in byte-seconds. Request explicitly via meters. Returned only when selected.", "properties": { "usage": { "type": "number", "description": "Recorded usage." }, "forecast": { "type": "number", "description": "Estimated total when forecasting applies and average statistics exist." }, "forecast_low": { "type": "number", "description": "Lower estimate in band mode." }, "forecast_high": { "type": "number", "description": "Upper estimate in band mode." } } }, "storage_backup": { "type": "object", "description": "Backup storage, in byte-seconds. Request explicitly via meters. Returned only when selected.", "properties": { "usage": { "type": "number", "description": "Recorded usage." }, "forecast": { "type": "number", "description": "Estimated total when forecasting applies and average statistics exist." }, "forecast_low": { "type": "number", "description": "Lower estimate in band mode." }, "forecast_high": { "type": "number", "description": "Upper estimate in band mode." } } }, "compute": { "type": "object", "description": "Total PHP-FPM, SSH, and database CPU time, in seconds. Returned only when selected.", "properties": { "usage": { "type": "number", "description": "Recorded usage." }, "forecast": { "type": "number", "description": "Estimated total when forecasting applies and average statistics exist." }, "forecast_low": { "type": "number", "description": "Lower estimate in band mode." }, "forecast_high": { "type": "number", "description": "Upper estimate in band mode." } } }, "compute_php": { "type": "object", "description": "PHP-FPM and SSH CPU time, in seconds. Request explicitly via meters. Returned only when selected.", "properties": { "usage": { "type": "number", "description": "Recorded usage." }, "forecast": { "type": "number", "description": "Estimated total when forecasting applies and average statistics exist." }, "forecast_low": { "type": "number", "description": "Lower estimate in band mode." }, "forecast_high": { "type": "number", "description": "Upper estimate in band mode." } } }, "compute_db": { "type": "object", "description": "Database CPU time, in seconds. Request explicitly via meters. Returned only when selected.", "properties": { "usage": { "type": "number", "description": "Recorded usage." }, "forecast": { "type": "number", "description": "Estimated total when forecasting applies and average statistics exist." }, "forecast_low": { "type": "number", "description": "Lower estimate in band mode." }, "forecast_high": { "type": "number", "description": "Upper estimate in band mode." } } }, "bandwidth": { "type": "object", "description": "Billable HTTP bandwidth, in bytes. Returned only when selected.", "properties": { "usage": { "type": "number", "description": "Recorded usage." }, "forecast": { "type": "number", "description": "Estimated total when forecasting applies and average statistics exist." }, "forecast_low": { "type": "number", "description": "Lower estimate in band mode." }, "forecast_high": { "type": "number", "description": "Upper estimate in band mode." } } }, "requests_uncached": { "type": "object", "description": "Uncached HTTP request count. Returned only when selected.", "properties": { "usage": { "type": "number", "description": "Recorded usage." }, "forecast": { "type": "number", "description": "Estimated total when forecasting applies and average statistics exist." }, "forecast_low": { "type": "number", "description": "Lower estimate in band mode." }, "forecast_high": { "type": "number", "description": "Upper estimate in band mode." } } }, "requests_cached": { "type": "object", "description": "Cached HTTP request count. Returned only when selected.", "properties": { "usage": { "type": "number", "description": "Recorded usage." }, "forecast": { "type": "number", "description": "Estimated total when forecasting applies and average statistics exist." }, "forecast_low": { "type": "number", "description": "Lower estimate in band mode." }, "forecast_high": { "type": "number", "description": "Upper estimate in band mode." } } }, "email": { "type": "object", "description": "Emails sent count. Returned only when selected.", "properties": { "usage": { "type": "number", "description": "Recorded usage." }, "forecast": { "type": "number", "description": "Estimated total when forecasting applies and average statistics exist." }, "forecast_low": { "type": "number", "description": "Lower estimate in band mode." }, "forecast_high": { "type": "number", "description": "Upper estimate in band mode." } } } } } } } }, "example": { "message": "OK", "data": { "_meta": { "took": 0.198, "meters": [ "storage", "storage_fs", "storage_db", "storage_backup", "compute", "compute_php", "compute_db", "bandwidth", "requests_uncached", "requests_cached", "email" ], "units": { "storage": "byte-seconds", "storage_fs": "byte-seconds", "storage_db": "byte-seconds", "storage_backup": "byte-seconds", "compute": "seconds", "compute_php": "seconds", "compute_db": "seconds", "bandwidth": "bytes", "requests_uncached": "count", "requests_cached": "count", "email": "count" }, "start": 1758499200, "end": 1758672000, "resolution": "day", "summary": "true", "forecast": "band" }, "totals": { "storage": { "usage": 225000000000, "forecast": 262500000000, "forecast_low": 260000000000, "forecast_high": 265000000000 }, "storage_fs": { "usage": 150000000000, "forecast": 175000000000, "forecast_low": 173500000000, "forecast_high": 176500000000 }, "storage_db": { "usage": 60000000000, "forecast": 70000000000, "forecast_low": 68000000000, "forecast_high": 72000000000 }, "storage_backup": { "usage": 15000000000, "forecast": 17500000000, "forecast_low": 17500000000, "forecast_high": 17500000000 }, "compute": { "usage": 215, "forecast": 285, "forecast_low": 260, "forecast_high": 310 }, "compute_php": { "usage": 150, "forecast": 190, "forecast_low": 175, "forecast_high": 205 }, "compute_db": { "usage": 65, "forecast": 95, "forecast_low": 75, "forecast_high": 115 }, "bandwidth": { "usage": 918318, "forecast": 968318, "forecast_low": 958318, "forecast_high": 978318 }, "requests_uncached": { "usage": 1400, "forecast": 1410, "forecast_low": 1405, "forecast_high": 1415 }, "requests_cached": { "usage": 7000, "forecast": 7050, "forecast_low": 7040, "forecast_high": 7060 }, "email": { "usage": 6, "forecast": 7, "forecast_low": 6.5, "forecast_high": 7.5 } } } } }, "examples": { "success-c7f0be1b6ee84e88637de9920a9b0bff": { "summary": "{json} All meters explicitly selected with forecast (illustrative data)", "value": { "message": "OK", "data": { "_meta": { "took": 0.198, "meters": [ "storage", "storage_fs", "storage_db", "storage_backup", "compute", "compute_php", "compute_db", "bandwidth", "requests_uncached", "requests_cached", "email" ], "units": { "storage": "byte-seconds", "storage_fs": "byte-seconds", "storage_db": "byte-seconds", "storage_backup": "byte-seconds", "compute": "seconds", "compute_php": "seconds", "compute_db": "seconds", "bandwidth": "bytes", "requests_uncached": "count", "requests_cached": "count", "email": "count" }, "start": 1758499200, "end": 1758672000, "resolution": "day", "summary": "true", "forecast": "band" }, "totals": { "storage": { "usage": 225000000000, "forecast": 262500000000, "forecast_low": 260000000000, "forecast_high": 265000000000 }, "storage_fs": { "usage": 150000000000, "forecast": 175000000000, "forecast_low": 173500000000, "forecast_high": 176500000000 }, "storage_db": { "usage": 60000000000, "forecast": 70000000000, "forecast_low": 68000000000, "forecast_high": 72000000000 }, "storage_backup": { "usage": 15000000000, "forecast": 17500000000, "forecast_low": 17500000000, "forecast_high": 17500000000 }, "compute": { "usage": 215, "forecast": 285, "forecast_low": 260, "forecast_high": 310 }, "compute_php": { "usage": 150, "forecast": 190, "forecast_low": 175, "forecast_high": 205 }, "compute_db": { "usage": 65, "forecast": 95, "forecast_low": 75, "forecast_high": 115 }, "bandwidth": { "usage": 918318, "forecast": 968318, "forecast_low": 958318, "forecast_high": 978318 }, "requests_uncached": { "usage": 1400, "forecast": 1410, "forecast_low": 1405, "forecast_high": 1415 }, "requests_cached": { "usage": 7000, "forecast": 7050, "forecast_low": 7040, "forecast_high": 7060 }, "email": { "usage": 6, "forecast": 7, "forecast_low": 6.5, "forecast_high": 7.5 } } } } } } } } }, "400": { "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message." }, "data": { "description": "Error details, or an empty array when none are returned." } } } } }, "description": "Missing required body values, invalid timestamps, unsupported resolution/range, invalid forecast mode or meter names, or failure to query the usage backend." }, "403": { "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message." }, "data": { "description": "Error details, or an empty array when none are returned." } } } } }, "description": "Access denied." }, "404": { "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message." }, "data": { "description": "Error details, or an empty array when none are returned." } } } } }, "description": "Site not found or unavailable to the caller." } }, "parameters": [ { "name": "site", "in": "path", "description": "Site ID or domain.", "required": true, "schema": { "type": "string" } } ], "operationId": "post-usage-site-summarize", "requestBody": { "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "properties": { "start": { "type": "integer", "description": "Inclusive start of the range, in Unix seconds, rounded down to a resolution boundary." }, "end": { "type": "integer", "description": "Exclusive end of the range, in Unix seconds, rounded up to a resolution boundary." }, "resolution": { "type": "string", "enum": [ "hour", "day", "month" ], "description": "Time bucket interval. Values are case-insensitive." }, "forecast": { "type": "string", "enum": [ "avg", "band", "1", "true" ], "description": "avg returns point forecasts; band adds low/high bounds. Values are case-insensitive. Legacy 1 and true mean avg; omission or an empty value disables forecasting." }, "meters": { "type": "string", "description": "Comma-separated meter names. Also accepts PHP array notation (meters[]=compute&meters[]=bandwidth). Names are trimmed and case-insensitive; duplicates are removed. Omitted or empty input uses defaults. Valid names: storage, storage_fs, storage_db, storage_backup, compute, compute_php, compute_db, bandwidth, requests_uncached, requests_cached, email." } }, "required": [ "start", "end", "resolution" ] } } }, "required": true } } }, "/get-ssh-user/{username}": { "get": { "tags": [ "SSH" ], "summary": "Get SSH User Details", "description": "Retrieve details for an SSH/SFTP user including site ID and timestamps. Validates that the requesting client has access to the user's site.", "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Response status message." }, "data": { "type": "object", "description": "User details object.", "properties": { "atomic_site_id": { "type": "number", "description": "Site ID." }, "created": { "type": "string", "description": "Creation timestamp." }, "last_updated": { "type": "string", "description": "Last update timestamp." }, "user": { "type": "string", "description": "Username." } } } }, "example": { "message": "OK", "data": { "atomic_site_id": 1234, "created": "2020-03-10 15:07:13", "last_updated": "2020-03-10 16:02:54", "user": "username" } } }, "examples": { "success-56cfa4a01fc874a58f356cd9aa860562": { "summary": "Success-Response", "value": { "message": "OK", "data": { "atomic_site_id": 1234, "created": "2020-03-10 15:07:13", "last_updated": "2020-03-10 16:02:54", "user": "username" } } } } } } }, "404": { "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message." }, "data": { "description": "Error details, or an empty array when none are returned." } } } } }, "description": "User not found." }, "500": { "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message." }, "data": { "description": "Error details, or an empty array when none are returned." } } } } }, "description": "Database query failed." } }, "parameters": [ { "name": "username", "in": "path", "description": "SSH username.", "required": true, "schema": { "type": "string" } } ], "operationId": "get-get-ssh-user-username" } }, "/task-get/{atomic_task_id}": { "post": { "tags": [ "Tasks" ], "summary": "Get Task Details", "description": "Get the details of a task.", "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Response status message." }, "data": { "type": "object", "description": "Response data.", "properties": { "task_id": { "type": "number", "description": "The task ID." }, "client_id": { "type": "number", "description": "Client ID the task was performed for." }, "type": { "type": "string", "description": "The task type." }, "created": { "type": "string", "description": "Datetime when the task was created." }, "complete": { "type": "string", "description": "Datetime when the task completed, or null if still in progress." }, "meta": { "type": "object", "description": "Task metadata.", "properties": { "failure_count": { "type": "number", "description": "The number of jobs that returned a non-zero exit code." }, "success_count": { "type": "number", "description": "The number of jobs that returned with a zero exit code." }, "took": { "type": "number", "description": "The total milliseconds it took all sites to perform the task." }, "took_failure": { "type": "number", "description": "The total milliseconds it took for failed jobs." }, "took_success": { "type": "number", "description": "The total milliseconds it took for successful jobs." } } } } } }, "example": { "message": "OK", "data": { "task_id": "169", "client_id": "207", "type": "site-find-files", "created": "2024-12-12 16:48:57", "complete": "2024-12-12 16:48:59", "meta": { "active_jobs": "", "concurrency": "5", "failure_count": "1", "last_site_id": "150787150", "pattern": "/class\\-acf(.*)\\.php/i", "search_mode": "regex", "send_webhook_for": "success", "success_count": "2", "took": "119", "took_failure": "44", "took_success": "75" } } } }, "examples": { "success-c99cb1699a11c78a06abfda0e877c53f": { "summary": "Success-Response", "value": { "message": "OK", "data": { "task_id": "169", "client_id": "207", "type": "site-find-files", "created": "2024-12-12 16:48:57", "complete": "2024-12-12 16:48:59", "meta": { "active_jobs": "", "concurrency": "5", "failure_count": "1", "last_site_id": "150787150", "pattern": "/class\\-acf(.*)\\.php/i", "search_mode": "regex", "send_webhook_for": "success", "success_count": "2", "took": "119", "took_failure": "44", "took_success": "75" } } } } } } } }, "400": { "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message." }, "data": { "description": "Error details, or an empty array when none are returned." } } } } }, "description": "Missing or invalid task ID." } }, "parameters": [ { "name": "atomic_task_id", "in": "path", "description": "Task Identifier returned by task-create endpoint.", "required": true, "schema": { "type": "number" } } ], "operationId": "post-task-get-atomic_task_id" } }, "/metrics/{type}/{key}[/summarize]": { "post": { "tags": [ "Metrics" ], "summary": "Get Time Series Metrics", "description": "Get time series metrics.\n\nThis endpoint queries a time series database and returns metrics that correspond to a site or client. Each metric can be further analyzed by specifying a dimension to segment the metric data on for sub analysis. In the API response an array of time periods are returned with each array item containing a `timestamp` field that specifies the start time of the span of time that the metric is reported for. The number of seconds for the span is given by the `data._meta.resolution` field in the response.\n\nWe support up to a 10 second resolution for recent data and metrics are downsampled into larger and larger minimum resolutions as time passes. Querying for a shorter and more recent time span will yield higher resolution data. Both longer time spans (longer time between the `start` and `end` parameters) as well as queries for older metrics data will result in lower resolution response data.\n\nThis endpoint supports returning multiple metrics per 1 dimension or up to 5 dimensions per 1 metric. By passing an array of metrics or dimensions to the metric and dimension field respectively.\n\nMetrics can be pulled from multiple sources. Based on the Source different dimensions are available for segmentation. The API will respond with a 400 response if invalid metric, dimensions combinations are requested.\n\nSupported metrics and dimensions to report are:\n\nEdge Logs metrics\n- `requests` - Number of requests\n- `requests_persec` - Number of requests per second.\n- `response_bytes` - Bandwidth consumed for all responses in bytes.\n- `response_bytes_persec` - Bandwidth consumed for all responses in bytes per second.\n- `response_bytes_average` - Average number of bytes of each response.\n- `response_time_average` - (Default) Average response time of each response.\n\nEdge Logs dimensions:\n- `server_protocol` - Protocol version used by the client.\n- `request_method` - Type of request made. (GET, POST, etc.)\n- `http_host` - (Default) Hostname of the request.\n- `http_status` - HTTP status code of the response.\n- `http_user_agent` - HTTP User Agent of the request\n- `referer_domain` - Referer Domain of the request\n- `page_renderer` - The backend that handled the request (PHP, static file, etc.)\n- `page_is_cached` - If the response page came from cache.\n- `wp_admin_ajax_action` - For requests to the WP admin AJAX endpoint, which action was specified.\n- `visitor_asn` - The ASN that the request came from.\n- `visitor_country_code` - The country the request came from according to GeoIP.\n- `visitor_is_crawler` - If the visitor appears to be an automated bot or crawler.\n- `visitor_device_type` - The detected device that the request came from.\n- `visitor_browser` - The detected browser that the request came from.\n- `visitor_os` - The detected os that the request came from.\n- `visitor_is_logged_in` - If the visitor appears to be logged in.\n- `edge_cache_status` - Request Status from Edge.\n- `is_rate_limited` - If the request was rate limited.\n- `rate_limit_reason` - Reason for the request to be limited.\n- `datacenter` - Datacenter that processed the request\n- `path` - Request path/url without query string\n- `remote_address` - IP that the request was issued from.\n- `atomic_site_id` - WP Cloud Site ID associated with the request\n- `proxy_type` - Type of proxy server that the request came from.\n\nPHP Logs metrics\n- `php_cpu_time` - Total CPU time.\n- `php_cpu_time_persec` - CPU time per second.\n- `php_response_time` - Total response time.\n- `php_requests` - Number of requests .\n- `php_requests_persec` - Number of requests per second.\n- `php_workers_average` - Average number of php workers in use.\n- `php_workers_min` - Minimum number of php workers in use.\n- `php_workers_max` - Maximum number of php workers in use.\n- `php_request_burst_percentage` - Percentage of requests in burst mode\n- `php_request_limited_percentage` - Percentage of requests that were limited from burst mode.\n- `php_request_normal_percentage` - Percentage of requests that were not in burst mode.\n\nPHP logs dimensions:\n- `http_verb` - Type of request made. (GET, POST, etc.)\n- `http_host` - Hostname of the request\n- `datacenter` - Datacenter that processed the request\n- `atomic_site_id` - WP Cloud Site ID associated with the request\n- `burst_status` - Request Burst Status [BURST, LIMITED, -]\n\nUniques and Views metrics (aggregated from edge available as daily stat)\n- `uniques` - Number of unique visitors\n- `views` - Number of page views\n\nUniques and Views dimensions:\n- `hostname` - Hostname.\n\nMySQL UserStats metrics\n- `mysql_total_connections` - number of connections.\n- `mysql_concurrent_connections` - number of concurrent connections.\n- `mysql_connected_time` - cumulative number of seconds elapsed while there were connections\n- `mysql_busy_time` - cumulative number of seconds there was activity on connections\n- `mysql_cpu_time` - cumulative CPU time elapsed, in seconds, while servicing connections\n- `mysql_bytes_received` - number of bytes received\n- `mysql_bytes_sent` - number of bytes sent\n- `mysql_binlog_bytes_written` - number of bytes written to the binary log\n- `mysql_rows_read` - number of rows read from tables\n- `mysql_rows_sent` - number of rows sent to tables\n- `mysql_rows_deleted` - number of rows deleted from tables\n- `mysql_rows_inserted` - number of rows inserted to tables\n- `mysql_rows_updated` - number of rows updated in tables\n- `mysql_select_commands` - number of SELECT commands executed\n- `mysql_update_commands` - number of UPDATE commands executed\n- `mysql_other_commands` - number of OTHER commands executed\n- `mysql_commit_transactions` - number of COMMIT commands issued\n- `mysql_rollback_transactions` - number of ROLLBACK commands issued\n- `mysql_denied_connections` - number of connections denied\n- `mysql_lost_connections` - number of connections that were terminated uncleanly\n- `mysql_access_denied` - number of issued commands that were denied.\n- `mysql_empty_queries` - number of empty queries.\n- `mysql_total_ssl_connections` - number of thread connections that used SSL.\n- `mysql_max_statement_time_exceeded` - number of times a query has exceeded the maximum execution time\n\nAll mysql metrics have _persec variants.\n\nMySQL Userstats dimensions:\n- `pool` - Pool Number\n- `server` - Server Name\n- `atomic_site_id` - WP Cloud Site ID\n\nCGroup Userstats metrics:\n- `cgroup_cpu_usage` - PHP CPU usage\n- `cgroup_cpu_usage_persec` - PHP CPU usage per second\n\nCGroup Userstats dimensions:\n- `pool` - Pool Number\n- `server` - Server Name\n- `atomic_site_id` - WP Cloud Site ID", "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Response status message." }, "data": { "type": "object", "description": "Response data.", "properties": { "_meta": { "type": "object", "description": "Metadata about the response data in `data.periods[]`.", "properties": { "start": { "type": "number", "description": "Unix timestamp for the start of the first period of data being reported (inclusive)." }, "end": { "type": "number", "description": "Unix timestamp for the end of the last period of data being reported (exclusive)." }, "resolution": { "type": "number", "description": "Number of seconds for each segment of data within `data.periods[]`." }, "metric": { "type": "string", "description": "Metric that is being reported." }, "dimension": { "type": "string", "description": "Dimension the metric is being segmented on." }, "took": { "type": "number", "description": "Backend response time for this timeseries query, in milliseconds." } } }, "periods": { "type": "array", "items": { "type": "object", "properties": { "timestamp": { "type": "number", "description": "Unix timestamp for the start of the particular period data is reported for." }, "dimension": { "type": "object", "description": "Object where the key is the value of the dimension being segmented on and the value is the metric value." } } }, "description": "Array of time period objects that span the timeseries response." } } } }, "example": { "message": "OK", "data": { "_meta": { "start": 1685577600, "end": 1685581200, "resolution": 300, "metric": "response_time_average", "dimension": "http_host", "took": 123 }, "periods": [ { "timestamp": 1685577600, "dimension": { "example.com": 0.03431913399587993 } }, { "timestamp": 1685580900, "dimension": { "example.com": 0.050371567257529094 } } ] } } }, "examples": { "success-23e1341b96e048ee812659025c523d82": { "summary": "Success-Response (Single)", "value": { "message": "OK", "data": { "_meta": { "start": 1685577600, "end": 1685581200, "resolution": 300, "metric": "response_time_average", "dimension": "http_host", "took": 123 }, "periods": [ { "timestamp": 1685577600, "dimension": { "example.com": 0.03431913399587993 } }, { "timestamp": 1685580900, "dimension": { "example.com": 0.050371567257529094 } } ] } } }, "success-104fe581aa8e031fcc4e2d769b4bc59c": { "summary": "Success-Response (Multiple Metrics)", "value": { "message": "OK", "data": { "_meta": { "start": 1685577600, "end": 1685581200, "resolution": 300, "metrics": [ "response_bytes_average", "response_time_average" ], "dimensions": [ "http_verb" ], "took": 123 }, "periods": [ { "timestamp": 1685577600, "http_verb": { "response_bytes_average": { "GET": 42957.75494847475, "HEAD": 0, "OPTIONS": 10255.802443991854, "POST": 1990.5416771631374 }, "response_time_average": { "GET": 0.06258511425461395, "HEAD": 0.3385846116680759, "OPTIONS": 0.6501140529531567, "POST": 0.4576846168664701 } } } ] } } } } } } }, "400": { "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message." }, "data": { "description": "Error details, or an empty array when none are returned." } } } } }, "description": "Invalid parameters or metric/dimension combination." }, "403": { "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message." }, "data": { "description": "Error details, or an empty array when none are returned." } } } } }, "description": "Access denied or invalid client." }, "404": { "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message." }, "data": { "description": "Error details, or an empty array when none are returned." } } } } }, "description": "Site not found." }, "500": { "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message." }, "data": { "description": "Error details, or an empty array when none are returned." } } } } }, "description": "Failed to connect to or query metrics data source." } }, "parameters": [ { "name": "type", "in": "path", "description": "Type of metrics being requested.", "required": true, "schema": { "type": "string", "enum": [ "client", "site" ] } }, { "name": "key", "in": "path", "description": "ID or name of requested type.", "required": true, "schema": { "type": "string" } }, { "name": "summarize", "in": "query", "description": "If present, returns an overall summary for the timespan given.", "required": false, "schema": { "type": "string" } } ], "operationId": "post-metrics-type-key[-summarize]", "requestBody": { "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "properties": { "start": { "type": "number", "description": "Unix timestamp for the start of the stats data range." }, "end": { "type": "number", "description": "Unix timestamp for the end of the stats data range." }, "metric": { "oneOf": [ { "type": "string" }, { "type": "array" } ], "description": "Timeseries metric to report or array of metrics (Default: response_time_average)." }, "dimension": { "oneOf": [ { "type": "string" }, { "type": "array" } ], "description": "Dimension to slice the metric data by or array of dimensions (Default: http_host)." }, "resolution": { "type": "number", "description": "Desired time resolution in seconds. The API will snap to the nearest supported resolution (10, 30, 60, 300, 600, 1800, 3600, 86400 seconds). Older data is automatically downsampled to coarser resolutions regardless of this value." }, "max_bucket_size": { "type": "number", "description": "Maximum number of time buckets to return (1-20). Default 20." }, "filters": { "type": "array", "description": "Filter to be applied to the metric request." }, "filters.column": { "type": "string", "description": "Dimension to be filtered." }, "filters.operator": { "type": "string", "description": "Operator: =, !=, >, >=, <, <=, IN, NOT IN." }, "filters.value": { "oneOf": [ { "type": "string" }, { "type": "array" } ], "description": "Value to be compared." } }, "required": [ "start", "end" ] } } } } } }, "/logs/client/{client}": { "post": { "tags": [ "Logs" ], "summary": "Get Web Server Logs for a Client", "description": "Get web server (nginx) log data across all sites for a client. Logs are only guaranteed for 28 days; a start timestamp before that may return incomplete data. The window includes start and excludes end: [start, end). Choose end after start for a nonempty window. For another raw-log page, repeat the same fixed window, filters, ranges, page size, and ordering with the returned scroll_id. Stop when scroll_id is null. With summary=top_hosts, the response contains total_results and top_hosts instead of logs and scroll_id. Pagination and sort_order are ignored in this mode.\n\nIllustrative top-host request. Replace CLIENT_ID and API_AUTH_TOKEN with your WP Cloud client account's ID and an authorized API key.\n\n```bash\nLOG_END=$(date +%s)\nLOG_START=$((LOG_END - 600))\ncurl --request POST 'https://atomic-api.wordpress.com/api/v1.0/logs/client/CLIENT_ID' \\\n --header 'Auth: API_AUTH_TOKEN' \\\n --data-urlencode \"start=$LOG_START\" \\\n --data-urlencode \"end=$LOG_END\" \\\n --data-urlencode 'summary=top_hosts' \\\n --data-urlencode 'top_n=10' \\\n --data-urlencode 'filter[status][]=503' \\\n --data-urlencode 'range[request_time][gte]=0.5'\n```", "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Response message (\"OK\" on success)." }, "data": { "type": "object", "description": "Response data for the selected mode.", "properties": { "total_results": { "oneOf": [ { "type": "number" }, { "type": "null" } ], "description": "Total matching entries, or null if unavailable. Returned in raw and summary modes." }, "top_hosts": { "type": "array", "items": { "type": "object", "properties": { "http_host": { "type": "string", "description": "Host header value." }, "count": { "type": "integer", "description": "Number of matching requests for the host." } } }, "description": "Host counts in descending order; summary=top_hosts only." }, "logs": { "type": "array", "items": { "type": "object", "properties": { "atomic_site_id": { "type": "integer", "description": "Numeric site ID identifying the source site; defaults to 0 when absent." }, "blocked_reason": { "description": "Stored reason for blocking the request, or null." }, "body_bytes_sent": { "type": "integer", "description": "Response body size in bytes; defaults to 0 when absent." }, "cached": { "description": "Stored cache status (e.g. \"true\", \"false\"), or null." }, "country_code": { "description": "Stored country code, or null." }, "date": { "description": "Stored ISO 8601 request timestamp." }, "http2": { "description": "Stored HTTP/2 stream ID, empty value for non-HTTP/2 requests, or null." }, "http_host": { "description": "Stored Host header, or null." }, "http_referer": { "description": "Stored Referer header, or null." }, "http_user_agent": { "description": "Stored User-Agent header, or null." }, "http_version": { "description": "Stored HTTP protocol version (e.g. \"HTTP/1.1\"), or null." }, "http_x_forwarded_for": { "description": "Stored X-Forwarded-For header, or null." }, "is_crawler": { "description": "Stored crawler classification, or null." }, "ja3_hash": { "description": "Stored JA3 TLS fingerprint, or null." }, "ja4_hash": { "description": "Stored JA4 TLS fingerprint, or null." }, "php_backlog_time": { "oneOf": [ { "type": "number" }, { "type": "null" } ], "description": "PHP backlog time, or null when absent." }, "php_burst_status": { "description": "Stored PHP burst status, or null." }, "rate_limit_reason": { "description": "Stored rate-limit reason, or null." }, "renderer": { "description": "Stored renderer type (e.g. \"php\", \"static\"), or null." }, "request_completion": { "description": "Stored request completion status (e.g. \"OK\"), or null." }, "request_time": { "type": "number", "description": "Request processing time in seconds; defaults to 0 when absent." }, "request_type": { "description": "Stored HTTP method (e.g. \"GET\", \"POST\"), or null." }, "request_url": { "description": "Stored request path and query string, or null." }, "scheme": { "description": "Stored request scheme (\"http\" or \"https\"), or null." }, "status": { "type": "integer", "description": "HTTP response status code; defaults to 0 when absent." }, "timestamp": { "type": "integer", "description": "Unix timestamp of the request, in seconds." }, "type": { "description": "Stored log record type (e.g. \"nginx_json\"), or null." }, "upstream_response_time": { "oneOf": [ { "type": "number" }, { "type": "null" } ], "description": "Backend-provided upstream response duration, or null when absent." }, "user_ip": { "description": "Stored resolved client IP address, or null." } } }, "description": "Raw-log mode only. Passthrough fields retain their stored types and may be null as noted." }, "scroll_id": { "oneOf": [ { "type": "string" }, { "type": "null" } ], "description": "Raw-log mode only. Opaque next-page cursor, or null when no more results are available." } } } }, "example": { "message": "OK", "data": { "total_results": 3, "top_hosts": [ { "http_host": "example.com", "count": 3 } ] } } }, "examples": { "success-f7c23da45b1d7ead001698ab30f8b8ac": { "summary": "{json} Top-host response (fictional data)", "value": { "message": "OK", "data": { "total_results": 3, "top_hosts": [ { "http_host": "example.com", "count": 3 } ] } } }, "success-3f2c97f0773a15782abc055c69ddd5d9": { "summary": "{json} Empty raw-log response", "value": { "message": "OK", "data": { "total_results": 0, "logs": [], "scroll_id": null } } } } } } }, "400": { "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message." }, "data": { "description": "Error details, or an empty array when none are returned." } }, "example": { "message": "Missing required parameter: start", "data": [] } }, "examples": { "error-df759a5b1f6d9c73ebfdda7c7c4235f4": { "summary": "{json} Missing start", "value": { "message": "Missing required parameter: start", "data": [] } } } } }, "description": "Missing or invalid parameter. Possible causes: missing start or end, unparseable date string, start > end, non-integer or out-of-range page_size, malformed scroll_id, invalid sort_order, unrecognized filter key, unknown range field, invalid range operator, non-numeric range value, or unsupported summary." }, "403": { "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message." }, "data": { "description": "Error details, or an empty array when none are returned." } } } } }, "description": "Access denied or unknown client." }, "500": { "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message." }, "data": { "description": "Error details, or an empty array when none are returned." } } } } }, "description": "Search backend error." } }, "parameters": [ { "name": "client", "in": "path", "description": "Client ID or client name (slug).", "required": true, "schema": { "type": "string" } } ], "operationId": "post-logs-client-client", "requestBody": { "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "properties": { "start": { "oneOf": [ { "type": "integer" }, { "type": "string" } ], "description": "Inclusive start: Unix seconds or a date string parseable by strtotime()." }, "end": { "oneOf": [ { "type": "integer" }, { "type": "string" } ], "description": "Exclusive end: Unix seconds or a date string parseable by strtotime(). Must not precede start." }, "page_size": { "type": "integer", "minimum": 0, "maximum": 10000, "description": "Maximum raw records per request. Use a positive page size for pagination. Ignored in summary mode.", "default": 500 }, "summary": { "type": "string", "enum": [ "top_hosts" ], "description": "Return host request counts instead of raw logs." }, "top_n": { "type": "integer", "description": "Maximum hosts in summary=top_hosts. Decimal-digit values are clamped to 1\u2013100. Omitted or non-digit values use 10. Ignored for raw logs.", "default": 10 }, "scroll_id": { "type": "string", "description": "Opaque cursor returned by a previous response. Pass it back to retrieve the next page of results." }, "sort_order": { "type": "string", "enum": [ "asc", "desc" ], "description": "Sort direction for results. Default \"asc\".", "default": "asc" }, "filter[cached][]": { "type": "array", "items": { "type": "string" }, "description": "Cache status values to include (e.g. \"true\", \"false\")." }, "filter[ja3_hash][]": { "type": "array", "items": { "type": "string" }, "description": "JA3 TLS fingerprint hashes to include." }, "filter[ja4_hash][]": { "type": "array", "items": { "type": "string" }, "description": "JA4 TLS fingerprint hashes to include." }, "filter[renderer][]": { "type": "array", "items": { "type": "string" }, "description": "Renderer types to include (e.g. \"php\", \"static\")." }, "filter[request_type][]": { "type": "array", "items": { "type": "string" }, "description": "HTTP methods to include (e.g. \"GET\", \"POST\")." }, "filter[status][]": { "type": "array", "items": { "type": "number" }, "description": "HTTP status codes to include." }, "filter[user_ip][]": { "type": "array", "items": { "type": "string" }, "description": "Client IP addresses to include." }, "filter[atomic_site_id][]": { "type": "array", "items": { "type": "number" }, "description": "Restrict to specific site IDs within the client." }, "range[request_time][gte]": { "type": "number", "description": "Request time in seconds, inclusive lower bound." }, "range[request_time][lte]": { "type": "number", "description": "Request time in seconds, inclusive upper bound." }, "range[request_time][gt]": { "type": "number", "description": "Request time in seconds, exclusive lower bound." }, "range[request_time][lt]": { "type": "number", "description": "Request time in seconds, exclusive upper bound." }, "range[body_bytes_sent][gte]": { "type": "number", "description": "Response bytes, inclusive lower bound." }, "range[body_bytes_sent][lte]": { "type": "number", "description": "Response bytes, inclusive upper bound." }, "range[body_bytes_sent][gt]": { "type": "number", "description": "Response bytes, exclusive lower bound." }, "range[body_bytes_sent][lt]": { "type": "number", "description": "Response bytes, exclusive upper bound." }, "range[status][gte]": { "type": "number", "description": "HTTP status, inclusive lower bound." }, "range[status][lte]": { "type": "number", "description": "HTTP status, inclusive upper bound." }, "range[status][gt]": { "type": "number", "description": "HTTP status, exclusive lower bound." }, "range[status][lt]": { "type": "number", "description": "HTTP status, exclusive upper bound." } }, "required": [ "start", "end" ] }, "encoding": { "filter[cached][]": { "style": "form", "explode": true }, "filter[ja3_hash][]": { "style": "form", "explode": true }, "filter[ja4_hash][]": { "style": "form", "explode": true }, "filter[renderer][]": { "style": "form", "explode": true }, "filter[request_type][]": { "style": "form", "explode": true }, "filter[status][]": { "style": "form", "explode": true }, "filter[user_ip][]": { "style": "form", "explode": true }, "filter[atomic_site_id][]": { "style": "form", "explode": true } } } }, "required": true } } }, "/logs/site/{site}": { "post": { "tags": [ "Logs" ], "summary": "Get Web Server Logs for a Site", "description": "Get web server (nginx) log data for a site. Logs are only guaranteed for 28 days; a start timestamp before that may return incomplete data. Set summary=over_time to return request counts in time buckets instead of paginated log entries. In summary mode, page_size, scroll_id, and sort_order are not used. The window includes start and excludes end: [start, end). Choose end after start for a nonempty window. For the next raw-log page, repeat the same window, filters, page size, and ordering with the returned scroll_id. Stop when scroll_id is null. Reuse fixed timestamps rather than relative dates while paging.\n\nIllustrative first-page request. Replace SITE_ID and API_AUTH_TOKEN with your site's ID and an authorized API key.\n\n```bash\nLOG_END=$(date +%s)\nLOG_START=$((LOG_END - 600))\ncurl --request POST 'https://atomic-api.wordpress.com/api/v1.0/logs/site/SITE_ID' \\\n --header 'Auth: API_AUTH_TOKEN' \\\n --data-urlencode \"start=$LOG_START\" \\\n --data-urlencode \"end=$LOG_END\" \\\n --data-urlencode 'page_size=500' \\\n --data-urlencode 'filter[status][]=500' \\\n --data-urlencode 'filter[status][]=503'\n```\n\nFor another raw page, repeat this request and add `--data-urlencode 'scroll_id=RETURNED_SCROLL_ID'` with the returned cursor. To count requests instead, use the same fixed window with summary=over_time:\n\n```bash\ncurl --request POST 'https://atomic-api.wordpress.com/api/v1.0/logs/site/SITE_ID' \\\n --header 'Auth: API_AUTH_TOKEN' \\\n --data-urlencode \"start=$LOG_START\" \\\n --data-urlencode \"end=$LOG_END\" \\\n --data-urlencode 'summary=over_time' \\\n --data-urlencode 'resolution=60' \\\n --data-urlencode 'filter[status][]=503'\n```", "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Response message (\"OK\" on success)." }, "data": { "type": "object", "description": "Response data for the selected mode.", "properties": { "resolution": { "type": "integer", "description": "Selected bucket interval in seconds; present with summary=over_time." }, "timeseries": { "type": "array", "items": { "type": "object", "properties": { "timestamp": { "type": "integer", "description": "Unix timestamp of the bucket start, in seconds." }, "count": { "type": "integer", "description": "Number of matching requests in the bucket." } } }, "description": "Request-count buckets; present with summary=over_time instead of logs, total_results, and scroll_id." }, "total_results": { "oneOf": [ { "type": "number" }, { "type": "null" } ], "description": "Total matching entries, or null if unavailable. Raw-log mode only." }, "logs": { "type": "array", "items": { "type": "object", "properties": { "blocked_reason": { "description": "Stored reason for blocking the request, or null." }, "body_bytes_sent": { "type": "integer", "description": "Response body size in bytes; defaults to 0 when absent." }, "cached": { "description": "Stored cache status (e.g. \"true\", \"false\"), or null." }, "country_code": { "description": "Stored country code, or null." }, "date": { "description": "Stored ISO 8601 request timestamp." }, "http2": { "description": "Stored HTTP/2 stream ID, empty value for non-HTTP/2 requests, or null." }, "http_host": { "description": "Stored Host header, or null." }, "http_referer": { "description": "Stored Referer header, or null." }, "http_user_agent": { "description": "Stored User-Agent header, or null." }, "http_version": { "description": "Stored HTTP protocol version (e.g. \"HTTP/1.1\"), or null." }, "http_x_forwarded_for": { "description": "Stored X-Forwarded-For header, or null." }, "is_crawler": { "description": "Stored crawler classification, or null." }, "ja3_hash": { "description": "Stored JA3 TLS fingerprint, or null." }, "ja4_hash": { "description": "Stored JA4 TLS fingerprint, or null." }, "php_backlog_time": { "oneOf": [ { "type": "number" }, { "type": "null" } ], "description": "PHP backlog time, or null when absent." }, "php_burst_status": { "description": "Stored PHP burst status, or null." }, "rate_limit_reason": { "description": "Stored rate-limit reason, or null." }, "renderer": { "description": "Stored renderer type (e.g. \"php\", \"static\"), or null." }, "request_completion": { "description": "Stored request completion status (e.g. \"OK\"), or null." }, "request_time": { "type": "number", "description": "Request processing time in seconds; defaults to 0 when absent." }, "request_type": { "description": "Stored HTTP method (e.g. \"GET\", \"POST\"), or null." }, "request_url": { "description": "Stored request path and query string, or null." }, "scheme": { "description": "Stored request scheme (\"http\" or \"https\"), or null." }, "status": { "type": "integer", "description": "HTTP response status code; defaults to 0 when absent." }, "timestamp": { "type": "integer", "description": "Unix timestamp of the request, in seconds." }, "type": { "description": "Stored log record type (e.g. \"nginx_json\"), or null." }, "upstream_response_time": { "oneOf": [ { "type": "number" }, { "type": "null" } ], "description": "Backend-provided upstream response duration, or null when absent." }, "user_ip": { "description": "Stored resolved client IP address, or null." } } }, "description": "Raw-log mode only. Passthrough fields retain their stored types and may be null as noted." }, "scroll_id": { "oneOf": [ { "type": "string" }, { "type": "null" } ], "description": "Raw-log mode only. Opaque next-page cursor, or null when no more results are available." } } } }, "example": { "message": "OK", "data": { "total_results": 0, "logs": [], "scroll_id": null } } }, "examples": { "success-3f2c97f0773a15782abc055c69ddd5d9": { "summary": "{json} Empty raw-log response", "value": { "message": "OK", "data": { "total_results": 0, "logs": [], "scroll_id": null } } }, "success-4092b6b542c405bc050059ae55a0fb81": { "summary": "{json} Final raw-log page (fictional entry)", "value": { "message": "OK", "data": { "total_results": 1, "logs": [ { "blocked_reason": null, "body_bytes_sent": 128, "cached": "false", "country_code": null, "date": "2024-01-01T00:00:00.000Z", "http2": null, "http_host": "example.com", "http_referer": null, "http_user_agent": "Example agent", "http_version": "HTTP/1.1", "http_x_forwarded_for": null, "is_crawler": null, "ja3_hash": null, "ja4_hash": null, "php_backlog_time": null, "php_burst_status": null, "rate_limit_reason": null, "renderer": "php", "request_completion": "OK", "request_time": 0.01, "request_type": "GET", "request_url": "/example", "scheme": "https", "status": 503, "timestamp": 1704067200, "type": "nginx_json", "upstream_response_time": null, "user_ip": "192.0.2.1" } ], "scroll_id": null } } }, "success-39077405a73c5645298c2d75abe8b742": { "summary": "{json} Over-time response (illustrative buckets)", "value": { "message": "OK", "data": { "resolution": 60, "timeseries": [ { "timestamp": 1704067200, "count": 3 }, { "timestamp": 1704067260, "count": 0 } ] } } } } } } }, "400": { "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message." }, "data": { "description": "Error details, or an empty array when none are returned." } }, "example": { "message": "Missing required parameter: start", "data": [] } }, "examples": { "error-df759a5b1f6d9c73ebfdda7c7c4235f4": { "summary": "{json} Missing start", "value": { "message": "Missing required parameter: start", "data": [] } } } } }, "description": "Missing or invalid parameter. Possible causes: missing start or end, unparseable date string, start > end, non-integer or out-of-range page_size, malformed scroll_id, invalid sort_order, unrecognized filter key, unsupported summary, or resolution below 60 or not a decimal-digit integer in summary mode." }, "403": { "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message." }, "data": { "description": "Error details, or an empty array when none are returned." } } } } }, "description": "Access denied." }, "404": { "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message." }, "data": { "description": "Error details, or an empty array when none are returned." } } } } }, "description": "Site not found." }, "500": { "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message." }, "data": { "description": "Error details, or an empty array when none are returned." } } } } }, "description": "Search backend error." } }, "parameters": [ { "name": "site", "in": "path", "description": "Site ID or domain.", "required": true, "schema": { "type": "string" } } ], "operationId": "post-logs-site-site", "requestBody": { "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "properties": { "summary": { "type": "string", "enum": [ "over_time" ], "description": "Return request counts over time instead of raw logs." }, "resolution": { "type": "integer", "minimum": 60, "description": "Bucket interval in seconds for summary=over_time. Automatically selected from the requested time range when omitted. Ignored for raw logs." }, "start": { "oneOf": [ { "type": "integer" }, { "type": "string" } ], "description": "Inclusive start: Unix seconds or a date string parseable by strtotime()." }, "end": { "oneOf": [ { "type": "integer" }, { "type": "string" } ], "description": "Exclusive end: Unix seconds or a date string parseable by strtotime(). Must not precede start." }, "page_size": { "type": "integer", "minimum": 0, "maximum": 10000, "description": "Maximum raw records per request. Use a positive page size for pagination. Ignored in summary mode.", "default": 500 }, "scroll_id": { "type": "string", "description": "Opaque cursor returned by a previous response. Pass it back to retrieve the next page of results." }, "sort_order": { "type": "string", "enum": [ "asc", "desc" ], "description": "Sort direction for results. Default \"asc\".", "default": "asc" }, "filter[ja3_hash][]": { "type": "array", "items": { "type": "string" }, "description": "JA3 TLS fingerprint hashes to include." }, "filter[ja4_hash][]": { "type": "array", "items": { "type": "string" }, "description": "JA4 TLS fingerprint hashes to include." }, "filter[cached][]": { "type": "array", "items": { "type": "string" }, "description": "Cache status values to include (e.g. \"true\", \"false\")." }, "filter[renderer][]": { "type": "array", "items": { "type": "string" }, "description": "Renderer types to include (e.g. \"php\", \"static\")." }, "filter[request_type][]": { "type": "array", "items": { "type": "string" }, "description": "HTTP methods to include (e.g. \"GET\", \"POST\")." }, "filter[status][]": { "type": "array", "items": { "type": "number" }, "description": "HTTP status codes to include." }, "filter[user_ip][]": { "type": "array", "items": { "type": "string" }, "description": "Client IP addresses to include." } }, "required": [ "start", "end" ] }, "encoding": { "filter[ja3_hash][]": { "style": "form", "explode": true }, "filter[ja4_hash][]": { "style": "form", "explode": true }, "filter[cached][]": { "style": "form", "explode": true }, "filter[renderer][]": { "style": "form", "explode": true }, "filter[request_type][]": { "style": "form", "explode": true }, "filter[status][]": { "style": "form", "explode": true }, "filter[user_ip][]": { "style": "form", "explode": true } } } }, "required": true } } }, "/task-interrupt/{task_id}": { "post": { "tags": [ "Tasks" ], "summary": "Interrupt Task", "description": "Interrupt an incomplete task.", "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Response status message." }, "data": { "type": "array", "description": "Empty array." } } } } } }, "400": { "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message." }, "data": { "description": "Error details, or an empty array when none are returned." } } } } }, "description": "Missing or invalid task ID, or task already completed." }, "500": { "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message." }, "data": { "description": "Error details, or an empty array when none are returned." } } } } }, "description": "Failed to interrupt the task." } }, "parameters": [ { "name": "task_id", "in": "path", "description": "Task ID.", "required": true, "schema": { "type": "number" } } ], "operationId": "post-task-interrupt-task_id" } }, "/get-sites/{client}/+": { "get": { "tags": [ "Sites" ], "summary": "List Client Sites", "description": "List a client's sites, generally for auditing purposes.\n\nAdditional site meta keys can be added to the output by specifying them at the end of the endpoint URI separated by '/'. For example, `/get-sites/:client/php_version` would add each site's `php_version` to the output.\n\nThe following additional site meta keys are supported:\n- `wp_version`\n- `php_version`\n- `space_quota`\n- `db_file_size`\n- `static_file_404`\n- `suspended`\n- `suspend_after`\n- `burst_php_conns`\n- `default_php_conns`\n- `php_memory_limit`\n- `opcache_memory_limit_mb`\n- `chroot_path`\n- `chroot_ssh_path`\n- `_data`", "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "atomic_site_id": { "type": "number", "description": "Site ID." }, "domain_name": { "type": "string", "description": "Primary domain name." }, "created": { "type": "string", "description": "Site creation date." }, "space_used": { "type": "number", "description": "Space used in bytes." } } }, "description": "Array of site objects." } } } } } }, "400": { "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message." }, "data": { "description": "Error details, or an empty array when none are returned." } } } } }, "description": "Invalid or unauthorized client." }, "500": { "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message." }, "data": { "description": "Error details, or an empty array when none are returned." } } } } }, "description": "Database error." } }, "parameters": [ { "name": "client", "in": "path", "description": "Client ID or client name.", "required": true, "schema": { "type": "string" } } ], "operationId": "get-get-sites-client-+" } }, "/get-sites/{client}/+{meta}/": { "get": { "tags": [ "Sites" ], "summary": "List Client Sites", "description": "List a client's sites, generally for auditing purposes.\n\nAdditional site meta keys can be added to the output by specifying them at the end of the endpoint URI separated by '/'. For example, `/get-sites/:client/php_version` would add each site's `php_version` to the output.\n\nThe following additional site meta keys are supported:\n- `wp_version`\n- `php_version`\n- `space_quota`\n- `db_file_size`\n- `static_file_404`\n- `suspended`\n- `suspend_after`\n- `burst_php_conns`\n- `default_php_conns`\n- `php_memory_limit`\n- `opcache_memory_limit_mb`\n- `chroot_path`\n- `chroot_ssh_path`\n- `_data`", "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "atomic_site_id": { "type": "number", "description": "Site ID." }, "domain_name": { "type": "string", "description": "Primary domain name." }, "created": { "type": "string", "description": "Site creation date." }, "space_used": { "type": "number", "description": "Space used in bytes." } } }, "description": "Array of site objects." } } } } } }, "400": { "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message." }, "data": { "description": "Error details, or an empty array when none are returned." } } } } }, "description": "Invalid or unauthorized client." }, "500": { "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message." }, "data": { "description": "Error details, or an empty array when none are returned." } } } } }, "description": "Database error." } }, "parameters": [ { "name": "client", "in": "path", "description": "Client ID or client name.", "required": true, "schema": { "type": "string" } }, { "name": "meta", "in": "path", "description": "Path parameter", "required": true, "schema": { "type": "string" } } ], "operationId": "get-get-sites-client-+meta" } }, "/crontab/{site}/list": { "get": { "tags": [ "Cron" ], "summary": "List Cron Entries", "description": "Returns a list of cron entries for a site.", "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Response status message." }, "data": { "type": "array", "items": { "type": "object", "properties": { "cron_id": { "type": "number", "description": "Cron entry ID." }, "schedule": { "type": "string", "description": "Crontab schedule expression." }, "requested_schedule": { "type": "string", "description": "The requested schedule (daily, weekly, etc.)." }, "command": { "type": "string", "description": "Command to execute." } } }, "description": "Array of cron entries." } }, "example": { "message": "OK", "data": [ { "cron_id": 93, "schedule": "* * * * *", "requested_schedule": "* * * * *", "command": "wp cron event run --due-now" }, { "cron_id": 94, "schedule": "1 4,16 * * *", "requested_schedule": "2h", "command": "wp custom sync-products" } ] } }, "examples": { "success-2636d6d474861609eec6478d0a8ae473": { "summary": "Success-Response", "value": { "message": "OK", "data": [ { "cron_id": 93, "schedule": "* * * * *", "requested_schedule": "* * * * *", "command": "wp cron event run --due-now" }, { "cron_id": 94, "schedule": "1 4,16 * * *", "requested_schedule": "2h", "command": "wp custom sync-products" } ] } } } } } }, "403": { "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message." }, "data": { "description": "Error details, or an empty array when none are returned." } } } } }, "description": "Access denied." }, "404": { "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message." }, "data": { "description": "Error details, or an empty array when none are returned." } } } } }, "description": "Site not found." } }, "parameters": [ { "name": "site", "in": "path", "description": "Site ID or domain.", "required": true, "schema": { "type": "string" } } ], "operationId": "get-crontab-site-list" } }, "/custom-certificates/{site}/list": { "get": { "tags": [ "Custom SSL Certificates" ], "summary": "List Custom Certificates", "description": "List custom SSL certificates, with optional filtering and pagination.", "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Response status message." }, "data": { "type": "object", "description": "Response data.", "properties": { "certificates": { "type": "array", "items": { "type": "object", "properties": { "ssl_custom_certificate_id": { "type": "number", "description": "Certificate ID." }, "active_domains": { "type": "array", "items": { "type": "string" }, "description": "Domains the certificate is active for." }, "is_active": { "type": "boolean", "description": "Whether the certificate is currently active." }, "certificate_expiration": { "type": "string", "description": "Certificate expiration datetime (UTC)." }, "days_until_expiry": { "type": "number", "description": "Days until certificate expiry." } } }, "description": "List of certificates." }, "pagination": { "type": "object", "description": "Pagination metadata.", "properties": { "total_items": { "type": "number", "description": "Total number of matching certificates." }, "limit": { "type": "number", "description": "Records per page." }, "offset": { "type": "number", "description": "Current page offset." }, "has_more": { "type": "boolean", "description": "Whether more results are available." } } } } } }, "example": { "message": "OK", "data": { "certificates": [ { "ssl_custom_certificate_id": 123, "active_domains": [ "example.com", "www.example.com" ], "is_active": true, "certificate_expiration": "2026-11-01 23:59:59", "days_until_expiry": 123.4 } ], "pagination": { "total_items": 25, "limit": 10, "offset": 0, "has_more": true } } } }, "examples": { "success-21e86ab9bfa159d58a92c53d8ed9ce07": { "summary": "Success-Response", "value": { "message": "OK", "data": { "certificates": [ { "ssl_custom_certificate_id": 123, "active_domains": [ "example.com", "www.example.com" ], "is_active": true, "certificate_expiration": "2026-11-01 23:59:59", "days_until_expiry": 123.4 } ], "pagination": { "total_items": 25, "limit": 10, "offset": 0, "has_more": true } } } } } } } }, "400": { "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message." }, "data": { "description": "Error details, or an empty array when none are returned." } } } } }, "description": "Invalid status, order_by, or limit value." }, "403": { "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message." }, "data": { "description": "Error details, or an empty array when none are returned." } } } } }, "description": "Access denied." }, "500": { "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message." }, "data": { "description": "Error details, or an empty array when none are returned." } } } } }, "description": "ACME API error." } }, "parameters": [ { "name": "site", "in": "path", "description": "Site ID or domain.", "required": true, "schema": { "type": "string" } }, { "name": "status", "in": "query", "description": "Filter by certificate status.", "required": false, "schema": { "type": "string", "enum": [ "active", "staged", "all" ] } }, { "name": "limit", "in": "query", "description": "Number of records to return, 1-1000 (default: 100).", "required": false, "schema": { "type": "number" } }, { "name": "offset", "in": "query", "description": "Offset for pagination (default: 0).", "required": false, "schema": { "type": "number" } }, { "name": "expiring_within_days", "in": "query", "description": "Filter certificates expiring within the specified number of days.", "required": false, "schema": { "type": "number" } }, { "name": "order_by", "in": "query", "description": "Field to order results by (default: expiration).", "required": false, "schema": { "type": "string", "enum": [ "expiration", "created" ] } } ], "operationId": "get-custom-certificates-site-list" } }, "/webhook/failures/{client}": { "get": { "tags": [ "Webhooks" ], "summary": "List Failed Webhook Jobs", "description": "Lists recent failed webhook jobs for a client.", "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Response status message." }, "data": { "type": "object", "description": "Result.", "properties": { "job_id": { "type": "number", "description": "New job ID for the re-queued webhook." } } }, "data[]": { "type": "object", "properties": { "id": { "type": "number", "description": "Job ID." }, "created": { "type": "string", "description": "Job creation timestamp." }, "event": { "type": "string", "description": "Webhook event name." }, "atomic_client_id": { "type": "number", "description": "Client ID." }, "atomic_site_id": { "oneOf": [ { "type": "number" }, { "type": "null" } ], "description": "Site ID, or null if client-level." }, "requeued_from_job_id": { "oneOf": [ { "type": "number" }, { "type": "null" } ], "description": "ID of the original job this was requeued from, or null. A non-null value means this job cannot be requeued again." }, "requeue_count": { "type": "number", "description": "Number of times this job has been requeued (max 3)." } } } }, "example": { "message": "OK", "data": [ { "id": 12345, "created": "2026-04-20 14:23:01", "event": "plugin_updates", "atomic_client_id": 3, "atomic_site_id": 678, "requeued_from_job_id": null } ] } }, "examples": { "success-5c827fcebafc7f0ca8dec8e7d0c88772": { "summary": "Success-Response", "value": { "message": "OK", "data": [ { "id": 12345, "created": "2026-04-20 14:23:01", "event": "plugin_updates", "atomic_client_id": 3, "atomic_site_id": 678, "requeued_from_job_id": null } ] } }, "success-0377104c9e2af16faf65d2dea9974326": { "summary": "Success-Response", "value": { "message": "OK", "data": { "job_id": 12346 } } } } } } }, "400": { "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message." }, "data": { "description": "Error details, or an empty array when none are returned." } } } } }, "description": "Unknown or missing client.\n\nMissing job_id." }, "403": { "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message." }, "data": { "description": "Error details, or an empty array when none are returned." } } } } }, "description": "Not authorized to act on this client's webhooks.\n\nNot authorized to act on this client's webhook." }, "404": { "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message." }, "data": { "description": "Error details, or an empty array when none are returned." } } } } }, "description": "Webhook job not found." }, "422": { "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message." }, "data": { "description": "Error details, or an empty array when none are returned." } } } } }, "description": "Already a requeue, max requeue count reached, or a requeue is already pending/succeeded." }, "500": { "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message." }, "data": { "description": "Error details, or an empty array when none are returned." } } } } }, "description": "Failed to parse job data or requeue failed." } }, "parameters": [ { "name": "client", "in": "path", "description": "Client name (e.g. pressable, vip).", "required": true, "schema": { "type": "string" } }, { "name": "job_id", "in": "query", "description": "ID of the failed webhook job to requeue.", "required": true, "schema": { "type": "number" } } ], "operationId": "get-webhook-failures-client" } }, "/firewall-rules/{site}/list": { "get": { "tags": [ "Security" ], "summary": "List Firewall Rules", "description": "Get a list of firewall rules for a site.", "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Response status message." }, "data": { "type": "array", "items": { "type": "object", "properties": { "rule_id": { "type": "number", "description": "Firewall rule ID." }, "direction": { "type": "string", "description": "Rule direction (always \"egress\")." }, "action": { "type": "string", "description": "Rule action (\"allow\" or \"deny\")." }, "protocol": { "type": "string", "description": "Protocol type." }, "port": { "type": "number", "description": "Port number." }, "destination": { "type": "string", "description": "Destination IP address or CIDR range." } } }, "description": "Array of firewall rules." } }, "example": { "message": "OK", "data": [ { "rule_id": 2368992788, "direction": "egress", "action": "allow", "protocol": "tcp", "port": 3306, "destination": "10.20.30.40/32" } ] } }, "examples": { "success-91401f17ea57549bdfa3e0f9ca9fc950": { "summary": "Success-Response", "value": { "message": "OK", "data": [ { "rule_id": 2368992788, "direction": "egress", "action": "allow", "protocol": "tcp", "port": 3306, "destination": "10.20.30.40/32" } ] } } } } } }, "403": { "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message." }, "data": { "description": "Error details, or an empty array when none are returned." } } } } }, "description": "Access denied." }, "404": { "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message." }, "data": { "description": "Error details, or an empty array when none are returned." } }, "example": { "message": "Site not found", "data": [] } }, "examples": { "error-2e8bc8151370e5f700d95645938b0ec3": { "summary": "Error-Response", "value": { "message": "Site not found", "data": [] } } } } }, "description": "Site not found." }, "500": { "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message." }, "data": { "description": "Error details, or an empty array when none are returned." } } } } }, "description": "Database query failed." } }, "parameters": [ { "name": "site", "in": "path", "description": "Site ID or domain.", "required": true, "schema": { "type": "string" } } ], "operationId": "get-firewall-rules-site-list" } }, "/alias-pkey/categories/{client}": { "get": { "tags": [ "SSH" ], "summary": "List Public Key Categories", "description": "Enumerate your category list.", "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Response status message." }, "data": { "type": "array", "items": { "type": "string" }, "description": "Array of category names." } } } } } }, "403": { "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message." }, "data": { "description": "Error details, or an empty array when none are returned." } } } } }, "description": "Access denied." } }, "parameters": [ { "name": "client", "in": "path", "description": "Client name or ID.", "required": true, "schema": { "type": "string" } } ], "operationId": "get-alias-pkey-categories-client" } }, "/alias-pkey/list/{client}/{category}": { "post": { "tags": [ "SSH" ], "summary": "List Public Keys", "description": "Enumerate your aliasable public keys, 1000 records at a time.", "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Response status message." }, "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "number", "description": "Public key ID." }, "name": { "type": "string", "description": "Key name." }, "fingerprint": { "type": "string", "description": "SHA256 fingerprint." } } }, "description": "Array of public keys." } } } } } }, "403": { "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message." }, "data": { "description": "Error details, or an empty array when none are returned." } } } } }, "description": "Access denied." } }, "parameters": [ { "name": "client", "in": "path", "description": "Client name or ID.", "required": true, "schema": { "type": "string" } }, { "name": "category", "in": "path", "description": "Category name.", "required": true, "schema": { "type": "string" } } ], "operationId": "post-alias-pkey-list-client-category", "requestBody": { "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "properties": { "after": { "type": "number", "description": "Begin enumeration after the given key ID (for paging when more than 1000 entries)." } } } } } } } }, "/site-backups-list/{service}/{identifier}": { "get": { "tags": [ "Backups" ], "summary": "List Site Backups", "description": "Get a list of backups for a site.\n\nPass the returned `atomic_backup_id` (with its `type`) to `site-backup-get` to download a backup. The `type` determines the response format and recommended filename -- see `site-backup-get` for the per-type format details.", "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Response status message." }, "data": { "type": "array", "items": { "type": "object", "properties": { "atomic_backup_id": { "type": "string", "description": "Backup ID." }, "atomic_site_id": { "type": "string", "description": "Site ID." }, "backup_timestamp": { "type": "string", "description": "Backup timestamp in MySQL timestamp format." }, "type": { "type": "string", "enum": [ "fs", "db", "ondemand", "ondemand-fs", "ondemand-db" ], "description": "Backup type; determines the response format from `site-backup-get`." }, "bytes": { "type": "number", "description": "Backup size in bytes (if available)." } } }, "description": "List of backups." } }, "example": { "message": "OK", "data": [ { "atomic_backup_id": "1234", "atomic_site_id": "5678", "backup_timestamp": "2019-08-03 00:00:00", "type": "db" }, { "atomic_backup_id": "1235", "atomic_site_id": "5678", "backup_timestamp": "2019-08-02 00:00:00", "type": "fs" }, { "atomic_backup_id": "1236", "atomic_site_id": "5678", "backup_timestamp": "2019-08-01 00:00:00", "type": "fs" } ] } }, "examples": { "success-bae1ad62301252cc566bdd94db9ff33a": { "summary": "Success-Response", "value": { "message": "OK", "data": [ { "atomic_backup_id": "1234", "atomic_site_id": "5678", "backup_timestamp": "2019-08-03 00:00:00", "type": "db" }, { "atomic_backup_id": "1235", "atomic_site_id": "5678", "backup_timestamp": "2019-08-02 00:00:00", "type": "fs" }, { "atomic_backup_id": "1236", "atomic_site_id": "5678", "backup_timestamp": "2019-08-01 00:00:00", "type": "fs" } ] } } } } } }, "400": { "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message." }, "data": { "description": "Error details, or an empty array when none are returned." } }, "example": { "message": "Invalid backup type given.", "data": [] } }, "examples": { "error-b245badf1549234989e8206a378af4d3": { "summary": "Error-Response", "value": { "message": "Invalid backup type given.", "data": [] } } } } }, "description": "Invalid service identifier, unknown site, or invalid backup type." } }, "parameters": [ { "name": "service", "in": "path", "description": "Service type (client name or \"domain\"). Use \"domain\" to look up by domain, otherwise use client identifier to look up by site ID.", "required": true, "schema": { "type": "string" } }, { "name": "identifier", "in": "path", "description": "Site identifier (domain name for \"domain\" lookups, otherwise site ID or WordPress.com blog ID for \"wpcom\" service).", "required": true, "schema": { "type": "string" } } ], "operationId": "get-site-backups-list-service-identifier" } }, "/site-backups-list/{service}/{identifier}/{backup_type}": { "get": { "tags": [ "Backups" ], "summary": "List Site Backups", "description": "Get a list of backups for a site.\n\nPass the returned `atomic_backup_id` (with its `type`) to `site-backup-get` to download a backup. The `type` determines the response format and recommended filename -- see `site-backup-get` for the per-type format details.", "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Response status message." }, "data": { "type": "array", "items": { "type": "object", "properties": { "atomic_backup_id": { "type": "string", "description": "Backup ID." }, "atomic_site_id": { "type": "string", "description": "Site ID." }, "backup_timestamp": { "type": "string", "description": "Backup timestamp in MySQL timestamp format." }, "type": { "type": "string", "enum": [ "fs", "db", "ondemand", "ondemand-fs", "ondemand-db" ], "description": "Backup type; determines the response format from `site-backup-get`." }, "bytes": { "type": "number", "description": "Backup size in bytes (if available)." } } }, "description": "List of backups." } }, "example": { "message": "OK", "data": [ { "atomic_backup_id": "1234", "atomic_site_id": "5678", "backup_timestamp": "2019-08-03 00:00:00", "type": "db" }, { "atomic_backup_id": "1235", "atomic_site_id": "5678", "backup_timestamp": "2019-08-02 00:00:00", "type": "fs" }, { "atomic_backup_id": "1236", "atomic_site_id": "5678", "backup_timestamp": "2019-08-01 00:00:00", "type": "fs" } ] } }, "examples": { "success-bae1ad62301252cc566bdd94db9ff33a": { "summary": "Success-Response", "value": { "message": "OK", "data": [ { "atomic_backup_id": "1234", "atomic_site_id": "5678", "backup_timestamp": "2019-08-03 00:00:00", "type": "db" }, { "atomic_backup_id": "1235", "atomic_site_id": "5678", "backup_timestamp": "2019-08-02 00:00:00", "type": "fs" }, { "atomic_backup_id": "1236", "atomic_site_id": "5678", "backup_timestamp": "2019-08-01 00:00:00", "type": "fs" } ] } } } } } }, "400": { "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message." }, "data": { "description": "Error details, or an empty array when none are returned." } }, "example": { "message": "Invalid backup type given.", "data": [] } }, "examples": { "error-b245badf1549234989e8206a378af4d3": { "summary": "Error-Response", "value": { "message": "Invalid backup type given.", "data": [] } } } } }, "description": "Invalid service identifier, unknown site, or invalid backup type." } }, "parameters": [ { "name": "service", "in": "path", "description": "Service type (client name or \"domain\"). Use \"domain\" to look up by domain, otherwise use client identifier to look up by site ID.", "required": true, "schema": { "type": "string" } }, { "name": "identifier", "in": "path", "description": "Site identifier (domain name for \"domain\" lookups, otherwise site ID or WordPress.com blog ID for \"wpcom\" service).", "required": true, "schema": { "type": "string" } }, { "name": "backup_type", "in": "path", "description": "Optional backup type filter. Can specify multiple types. If not present, all types returned", "required": true, "schema": { "type": "string", "enum": [ "db", "fs", "ondemand", "ondemand-fs", "ondemand-db" ] } } ], "operationId": "get-site-backups-list-service-identifier-backup_type" } }, "/ssh-user/{service}/{identifier}/list": { "get": { "tags": [ "SSH" ], "summary": "List Site SSH/SFTP Users", "description": "List all SSH/SFTP usernames for a site.", "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Response status message." }, "data": { "type": "array", "items": { "type": "string" }, "description": "Array of usernames." } }, "example": { "message": "OK", "data": [ "client-test" ] } }, "examples": { "success-fc4fbd663ad88fc80f97d90c83d6e1ef": { "summary": "Success-Response", "value": { "message": "OK", "data": [ "client-test" ] } } } } } }, "400": { "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message." }, "data": { "description": "Error details, or an empty array when none are returned." } } } } }, "description": "Invalid site or service type." } }, "parameters": [ { "name": "service", "in": "path", "description": "Service type (client name, \"domain\" for domain lookup, or \"wpcom\" for WordPress.com blog ID).", "required": true, "schema": { "type": "string" } }, { "name": "identifier", "in": "path", "description": "Site identifier (domain for \"domain\" service, site ID for client, WordPress.com blog ID for \"wpcom\").", "required": true, "schema": { "type": "string" } } ], "operationId": "get-ssh-user-service-identifier-list" } }, "/email-block/{client}/{action}/{type}": { "get": { "tags": [ "Email" ], "summary": "Manage Blocked Domains", "description": "Manage domains that have been blocked from sending email via the platform-provided mail service.\n\nThe following actions are allowed:\n\n- `list` - List blocked domains for a given client\n\nThe following types are allowed:\n\n- `sasl_block` - Domains that are blocked as a sender", "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Response status message." }, "data": { "type": "array", "items": { "type": "object", "properties": { "atomic_site_id": { "type": "string", "description": "Atomic site ID." }, "domain": { "type": "string", "description": "Domain that is blocked." }, "reason": { "type": "string", "description": "Reason for blocking." }, "expires_on": { "type": "string", "description": "Expiration timestamp of the block." } } }, "description": "Array of blocked domain records." } }, "example": { "message": "OK", "data": [ { "atomic_site_id": "149000000", "domain": "example.com", "reason": "Abuse", "expires_on": "2025-11-07 10:12:03" } ] } }, "examples": { "success-785eb8a4b762f9500646365557c7f82c": { "summary": "Success-Response, list", "value": { "message": "OK", "data": [ { "atomic_site_id": "149000000", "domain": "example.com", "reason": "Abuse", "expires_on": "2025-11-07 10:12:03" } ] } } } } } }, "400": { "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message." }, "data": { "description": "Error details, or an empty array when none are returned." } }, "example": { "message": "Invalid action", "data": [] } }, "examples": { "error-650c6f903608ea5b7fa1389a6635362b": { "summary": "Error-Response", "value": { "message": "Invalid action", "data": [] } } } } }, "description": "Invalid action or block type." }, "403": { "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message." }, "data": { "description": "Error details, or an empty array when none are returned." } } } } }, "description": "Invalid client or API key not authorised for this client." }, "500": { "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message." }, "data": { "description": "Error details, or an empty array when none are returned." } } } } }, "description": "Internal server error." } }, "parameters": [ { "name": "client", "in": "path", "description": "Client name or ID.", "required": true, "schema": { "type": "string" } }, { "name": "action", "in": "path", "description": "Action to perform (currently only \"list\" is supported).", "required": true, "schema": { "type": "string", "enum": [ "list" ] } }, { "name": "type", "in": "path", "description": "Block type (currently only \"sasl_block\" is supported).", "required": true, "schema": { "type": "string", "enum": [ "sasl_block" ] } } ], "operationId": "get-email-block-client-action-type" } }, "/client-authorized-keys/{client}/{action}": { "get": { "tags": [ "SSH" ], "summary": "Manage Client Authorized Keys", "description": "Manage client-level SSH authorized keys that grant access to all sites owned by a client via client-ssh.atomicsites.net. Only available to fully onboarded clients with allowlisted IP addresses. Keys are parsed and validated, with specific SSH options honored (from, command) and enforced (restrict, agent-forwarding, pty). Allowed key types: ssh-rsa (2048-16384 bits), ecdsa-sha2-nistp256 (256 bits), ssh-ed25519 (256 bits). See OpenBSD sshd authorized_keys format for details.", "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Response status message." }, "data": { "type": "object", "description": "Response payload; shape depends on action. For \"list\": object keyed by atomic_client_ssh_id, each entry has the fields below. For \"add\": object with only the new key \"id\". For \"remove\": Number of rows deleted (1 on success).", "properties": { "id": { "type": "number", "description": "(list, add) Key ID." }, "is_alias": { "type": "boolean", "description": "(list) Whether this key is an alias." }, "alias": { "type": "string", "description": "(list) Alias URI if is_alias is true, otherwise empty string." }, "name": { "type": "string", "description": "(list) Key name." }, "fingerprint": { "type": "string", "description": "(list) SHA-256 fingerprint of the key." }, "seen_dt": { "type": "string", "description": "(list) Last-seen datetime." }, "seen_ts": { "type": "number", "description": "(list) Last-seen Unix timestamp." }, "effective_options": { "type": "object", "description": "(list) Applied SSH options (restrict, agent-forwarding, pty, from, command)." } } } } } } } }, "400": { "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message." }, "data": { "description": "Error details, or an empty array when none are returned." } } } } }, "description": "Invalid action, missing parameters, invalid SSH key format, or attempt to remove a protected key." }, "403": { "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message." }, "data": { "description": "Error details, or an empty array when none are returned." } } } } }, "description": "Not authorized to manage this client." }, "500": { "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message." }, "data": { "description": "Error details, or an empty array when none are returned." } } } } }, "description": "Database error on insert." } }, "parameters": [ { "name": "client", "in": "path", "description": "Client name or ID.", "required": true, "schema": { "type": "string" } }, { "name": "action", "in": "path", "description": "Action to perform.", "required": true, "schema": { "type": "string", "enum": [ "list", "add", "remove" ] } } ], "operationId": "get-client-authorized-keys-client-action" }, "post": { "tags": [ "SSH" ], "summary": "Manage Client Authorized Keys", "description": "Manage client-level SSH authorized keys that grant access to all sites owned by a client via client-ssh.atomicsites.net. Only available to fully onboarded clients with allowlisted IP addresses. Keys are parsed and validated, with specific SSH options honored (from, command) and enforced (restrict, agent-forwarding, pty). Allowed key types: ssh-rsa (2048-16384 bits), ecdsa-sha2-nistp256 (256 bits), ssh-ed25519 (256 bits). See OpenBSD sshd authorized_keys format for details.", "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Response status message." }, "data": { "type": "object", "description": "Response payload; shape depends on action. For \"list\": object keyed by atomic_client_ssh_id, each entry has the fields below. For \"add\": object with only the new key \"id\". For \"remove\": Number of rows deleted (1 on success).", "properties": { "id": { "type": "number", "description": "(list, add) Key ID." }, "is_alias": { "type": "boolean", "description": "(list) Whether this key is an alias." }, "alias": { "type": "string", "description": "(list) Alias URI if is_alias is true, otherwise empty string." }, "name": { "type": "string", "description": "(list) Key name." }, "fingerprint": { "type": "string", "description": "(list) SHA-256 fingerprint of the key." }, "seen_dt": { "type": "string", "description": "(list) Last-seen datetime." }, "seen_ts": { "type": "number", "description": "(list) Last-seen Unix timestamp." }, "effective_options": { "type": "object", "description": "(list) Applied SSH options (restrict, agent-forwarding, pty, from, command)." } } } } } } } }, "400": { "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message." }, "data": { "description": "Error details, or an empty array when none are returned." } } } } }, "description": "Invalid action, missing parameters, invalid SSH key format, or attempt to remove a protected key." }, "403": { "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message." }, "data": { "description": "Error details, or an empty array when none are returned." } } } } }, "description": "Not authorized to manage this client." }, "500": { "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message." }, "data": { "description": "Error details, or an empty array when none are returned." } } } } }, "description": "Database error on insert." } }, "parameters": [ { "name": "client", "in": "path", "description": "Client name or ID.", "required": true, "schema": { "type": "string" } }, { "name": "action", "in": "path", "description": "Action to perform.", "required": true, "schema": { "type": "string", "enum": [ "list", "add", "remove" ] } } ], "operationId": "post-client-authorized-keys-client-action", "requestBody": { "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "properties": { "authorized_keys_line": { "type": "string", "description": "SSH authorized_keys line (required for \"add\" action)." }, "name": { "type": "string", "description": "Descriptive name for the key (required for \"add\" action)." } }, "required": [ "authorized_keys_line", "name" ] } } } } } }, "/client-authorized-keys/{client}/{action}/{id}": { "get": { "tags": [ "SSH" ], "summary": "Manage Client Authorized Keys", "description": "Manage client-level SSH authorized keys that grant access to all sites owned by a client via client-ssh.atomicsites.net. Only available to fully onboarded clients with allowlisted IP addresses. Keys are parsed and validated, with specific SSH options honored (from, command) and enforced (restrict, agent-forwarding, pty). Allowed key types: ssh-rsa (2048-16384 bits), ecdsa-sha2-nistp256 (256 bits), ssh-ed25519 (256 bits). See OpenBSD sshd authorized_keys format for details.", "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Response status message." }, "data": { "type": "object", "description": "Response payload; shape depends on action. For \"list\": object keyed by atomic_client_ssh_id, each entry has the fields below. For \"add\": object with only the new key \"id\". For \"remove\": Number of rows deleted (1 on success).", "properties": { "id": { "type": "number", "description": "(list, add) Key ID." }, "is_alias": { "type": "boolean", "description": "(list) Whether this key is an alias." }, "alias": { "type": "string", "description": "(list) Alias URI if is_alias is true, otherwise empty string." }, "name": { "type": "string", "description": "(list) Key name." }, "fingerprint": { "type": "string", "description": "(list) SHA-256 fingerprint of the key." }, "seen_dt": { "type": "string", "description": "(list) Last-seen datetime." }, "seen_ts": { "type": "number", "description": "(list) Last-seen Unix timestamp." }, "effective_options": { "type": "object", "description": "(list) Applied SSH options (restrict, agent-forwarding, pty, from, command)." } } } } } } } }, "400": { "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message." }, "data": { "description": "Error details, or an empty array when none are returned." } } } } }, "description": "Invalid action, missing parameters, invalid SSH key format, or attempt to remove a protected key." }, "403": { "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message." }, "data": { "description": "Error details, or an empty array when none are returned." } } } } }, "description": "Not authorized to manage this client." }, "500": { "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message." }, "data": { "description": "Error details, or an empty array when none are returned." } } } } }, "description": "Database error on insert." } }, "parameters": [ { "name": "client", "in": "path", "description": "Client name or ID.", "required": true, "schema": { "type": "string" } }, { "name": "action", "in": "path", "description": "Action to perform.", "required": true, "schema": { "type": "string", "enum": [ "list", "add", "remove" ] } }, { "name": "id", "in": "path", "description": "Key ID (required for \"remove\" action).", "required": true, "schema": { "type": "number" } } ], "operationId": "get-client-authorized-keys-client-action-id" }, "post": { "tags": [ "SSH" ], "summary": "Manage Client Authorized Keys", "description": "Manage client-level SSH authorized keys that grant access to all sites owned by a client via client-ssh.atomicsites.net. Only available to fully onboarded clients with allowlisted IP addresses. Keys are parsed and validated, with specific SSH options honored (from, command) and enforced (restrict, agent-forwarding, pty). Allowed key types: ssh-rsa (2048-16384 bits), ecdsa-sha2-nistp256 (256 bits), ssh-ed25519 (256 bits). See OpenBSD sshd authorized_keys format for details.", "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Response status message." }, "data": { "type": "object", "description": "Response payload; shape depends on action. For \"list\": object keyed by atomic_client_ssh_id, each entry has the fields below. For \"add\": object with only the new key \"id\". For \"remove\": Number of rows deleted (1 on success).", "properties": { "id": { "type": "number", "description": "(list, add) Key ID." }, "is_alias": { "type": "boolean", "description": "(list) Whether this key is an alias." }, "alias": { "type": "string", "description": "(list) Alias URI if is_alias is true, otherwise empty string." }, "name": { "type": "string", "description": "(list) Key name." }, "fingerprint": { "type": "string", "description": "(list) SHA-256 fingerprint of the key." }, "seen_dt": { "type": "string", "description": "(list) Last-seen datetime." }, "seen_ts": { "type": "number", "description": "(list) Last-seen Unix timestamp." }, "effective_options": { "type": "object", "description": "(list) Applied SSH options (restrict, agent-forwarding, pty, from, command)." } } } } } } } }, "400": { "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message." }, "data": { "description": "Error details, or an empty array when none are returned." } } } } }, "description": "Invalid action, missing parameters, invalid SSH key format, or attempt to remove a protected key." }, "403": { "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message." }, "data": { "description": "Error details, or an empty array when none are returned." } } } } }, "description": "Not authorized to manage this client." }, "500": { "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message." }, "data": { "description": "Error details, or an empty array when none are returned." } } } } }, "description": "Database error on insert." } }, "parameters": [ { "name": "client", "in": "path", "description": "Client name or ID.", "required": true, "schema": { "type": "string" } }, { "name": "action", "in": "path", "description": "Action to perform.", "required": true, "schema": { "type": "string", "enum": [ "list", "add", "remove" ] } }, { "name": "id", "in": "path", "description": "Key ID (required for \"remove\" action).", "required": true, "schema": { "type": "number" } } ], "operationId": "post-client-authorized-keys-client-action-id", "requestBody": { "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "properties": { "authorized_keys_line": { "type": "string", "description": "SSH authorized_keys line (required for \"add\" action)." }, "name": { "type": "string", "description": "Descriptive name for the key (required for \"add\" action)." } }, "required": [ "authorized_keys_line", "name" ] } } } } } }, "/site-alias/{service}/{identifier}/{action}": { "get": { "tags": [ "Sites" ], "summary": "Manage Site Aliases", "description": "Manage domain aliases for a site.", "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Response status message." }, "data": { "type": "object", "description": "Response data.", "properties": { "domains": { "type": "array", "items": { "type": "string" }, "description": "Domain names added or listed (absent for \"remove\" action)." } } } }, "example": { "message": "OK", "data": { "domains": [ "test.example.com" ] } } }, "examples": { "success-898dcf09520eb776033ff6d264b9c121": { "summary": "Success-Response add", "value": { "message": "OK", "data": { "domains": [ "test.example.com" ] } } }, "success-d26b65e1ff612dd9abbf2e90ee2ead1c": { "summary": "Success-Response list", "value": { "message": "OK", "data": { "domains": [ "test.example.com", "custom.example.com" ] } } }, "success-b3010eab0eb445de91f770a866abbb5c": { "summary": "Success-Response remove", "value": { "message": "OK", "data": { "domains": [] } } } } } } }, "400": { "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message." }, "data": { "description": "Error details, or an empty array when none are returned." } } } } }, "description": "Invalid action or attempt to remove primary domain." }, "403": { "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message." }, "data": { "description": "Error details, or an empty array when none are returned." } } } } }, "description": "Access denied." }, "404": { "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message." }, "data": { "description": "Error details, or an empty array when none are returned." } } } } }, "description": "Site not found." }, "501": { "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message." }, "data": { "description": "Error details, or an empty array when none are returned." } } } } }, "description": "The \"wpcom\" and \"atomic\" service types are not supported." } }, "parameters": [ { "name": "service", "in": "path", "description": "Service type; may be client name or \"domain\". Used to determine site lookup method; use \"domain\" to look up a site by domain, otherwise use the client identifier to look up a site by site ID.", "required": true, "schema": { "type": "string" } }, { "name": "identifier", "in": "path", "description": "Site identifier; domain name for \"domain\" lookups,. otherwise the site ID.", "required": true, "schema": { "type": "string" } }, { "name": "action", "in": "path", "description": "Action to perform: \"list\", \"add\", or \"remove\".", "required": true, "schema": { "type": "string" } } ], "operationId": "get-site-alias-service-identifier-action" } }, "/site-alias/{service}/{identifier}/{action}/{domain}": { "get": { "tags": [ "Sites" ], "summary": "Manage Site Aliases", "description": "Manage domain aliases for a site.", "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Response status message." }, "data": { "type": "object", "description": "Response data.", "properties": { "domains": { "type": "array", "items": { "type": "string" }, "description": "Domain names added or listed (absent for \"remove\" action)." } } } }, "example": { "message": "OK", "data": { "domains": [ "test.example.com" ] } } }, "examples": { "success-898dcf09520eb776033ff6d264b9c121": { "summary": "Success-Response add", "value": { "message": "OK", "data": { "domains": [ "test.example.com" ] } } }, "success-d26b65e1ff612dd9abbf2e90ee2ead1c": { "summary": "Success-Response list", "value": { "message": "OK", "data": { "domains": [ "test.example.com", "custom.example.com" ] } } }, "success-b3010eab0eb445de91f770a866abbb5c": { "summary": "Success-Response remove", "value": { "message": "OK", "data": { "domains": [] } } } } } } }, "400": { "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message." }, "data": { "description": "Error details, or an empty array when none are returned." } } } } }, "description": "Invalid action or attempt to remove primary domain." }, "403": { "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message." }, "data": { "description": "Error details, or an empty array when none are returned." } } } } }, "description": "Access denied." }, "404": { "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message." }, "data": { "description": "Error details, or an empty array when none are returned." } } } } }, "description": "Site not found." }, "501": { "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message." }, "data": { "description": "Error details, or an empty array when none are returned." } } } } }, "description": "The \"wpcom\" and \"atomic\" service types are not supported." } }, "parameters": [ { "name": "service", "in": "path", "description": "Service type; may be client name or \"domain\". Used to determine site lookup method; use \"domain\" to look up a site by domain, otherwise use the client identifier to look up a site by site ID.", "required": true, "schema": { "type": "string" } }, { "name": "identifier", "in": "path", "description": "Site identifier; domain name for \"domain\" lookups,. otherwise the site ID.", "required": true, "schema": { "type": "string" } }, { "name": "action", "in": "path", "description": "Action to perform: \"list\", \"add\", or \"remove\".", "required": true, "schema": { "type": "string" } }, { "name": "domain", "in": "path", "description": "Domain name to add or remove (required when action is \"add\" or \"remove\").", "required": true, "schema": { "type": "string" } } ], "operationId": "get-site-alias-service-identifier-action-domain" } }, "/site-meta/{site}/{key}/{action}": { "get": { "tags": [ "Sites" ], "summary": "Manage Site Meta", "description": "Endpoint for managing site meta.\n\nThe following meta keys are supported:\n\n- Values for `db_charset` and `db_collate` include \"latin1\", \"latin1_swedish_ci\"; \"utf8\", \"utf8_general_ci\"; and \"utf8mb4\", \"utf8mb4_general_ci\".\n- `suspended` suspends a site. The value is the HTTP 4xx status code the site will respond with. The supported statuses are \"403\", \"404\", \"410\", \"451\", \"480\", and \"503\".\n- `suspend_after` will suspend a site after a given unixtime timestamp with the status specified in \"suspended\", default 480.\n- `allow_restore` opts a site into self-restore via the \"restore-site\" endpoint. The value must be a positive Unix timestamp, must not be more than 5 minutes in the future, and must be recent (within MONTH_IN_SECONDS) when \"restore-site\" is called. It only authorizes the restore window; the restore is started with the \"restore-site\" endpoint.\n- `php_version` sets the site's PHP version. Supported values include \"8.2\", \"8.3\", \"8.4\", and \"8.5\".\n- `wp_version` is a get-only key that can be used to retrieve the site's current managed WordPress version, which can be \"latest\", \"previous\", \"beta\", or \"alpha\" (the last two are used to test WordPress releases). Use the \"site-wordpress-version\" endpoint to set \"wp_version\".\n- `do_not_delete` may be set to a truthy value to prevent a site from begin deleted. This can be useful in some cases. For example, you might wish to preserve a site while it is being reviewed for Terms of Service violations.\n- `space_used` is a get-only key that returns an integer in bytes; it is updated every 12 hours with the amount of space used by a site's files.\n- `db_file_size` is a get-only key that returns an integer in bytes. It is updated every 12 hours with the amount of space used by a site's database.\n- `space_quota` can be used to get and set the space quota for a site. Value must be an integer followed by a size specifier like \"200G\".\n- `max_space_quota` is get-only and may be present if the platform has set a space_quota\" maximum for a specific site.\n- `photon_subsizes` controls whether WP skips generating intermediate image files when an image is uploaded. The platform is able to satisfy requests for intermediate image files whether or not they exist, so sites can save disk space by not creating them. When the a site's web server receives a request for a non-existent intermediate image file, it proxies the request to Photon which responds with the intermediate image size. Can be set to \"0\" or \"1\" or deleted.\n- `privacy_model` facilitates protection of site assets. May be set to \"wp_uploads\" to block logged-out requests for WP uploads. If set, an AT_PRIVACY_MODEL constant will be defined in the PHP environment.\n- `geo_affinity` may be used to get and set a site's geo-affinity. Allowed values are those returned by the \"get-available-datacenters\" endpoint. It is not currently useful to set a site's geo-affinity after creation unless you have access to an endpoint that allows you to subsequently trigger migration of the site to another server pool.\n- `generation` returns the server hardware generation the site was created with. It is read-only and is set only from the \"create-site\" `generation` parameter, so a site created without that parameter has no value here. Add, update and remove return 403.\n- `static_file_404` may be used to get and set how a site responds to requests for non-existent static files. May be set to \"lightweight\" for simple, fast web server 404s. May be set to \"wordpress\" to delegate such requests to WordPress. The current default is \"wordpress\".\n- `php_memory_limit` may be used to set the per-request PHP memory limit to a value between 512MB and 2048MB. Allowed values are 512, 1024, 1536, 2048. The default if not set is 512.\n- `opcache_memory_limit_mb` may be used to set the per-request PHP memory limit to a value up to 300.\n- `default_php_conns` may be used to either limit site's allowed concurrent PHP connections or to increase the default number of concurrent connections a site can use if the web server has spare PHP connections capacity. Clients may set any value for a site between 2 and 10; the platform has more leeway if needed.\n- `burst_php_conns` controls PHP burst behavior. 0 means burst is disabled, 1 means burst is enabled (legacy), and 2 allows up to 2x default_php_conns. Negative integers (e.g. -8) request a flat additive bonus of abs(value) connections above default_php_conns. All values are clamped to the global ceiling on the server.\n- `php_fs_permissions` may be used to cause HTTP requests being handled by PHP for a site to have that sites filesystem mounted specially. Currently supported values are \"rw\" (readwrite - the default), \"ro\" (readonly), and \"loggedin\" (read only unless logged into WordPress). It is possible that other more complicated settings may be added in the future.\n- `canonicalize_aliases` may be used to change whether a sites domain aliases redirect (default, \"true\") to the sites primary domain name or are served directly (when set to \"false\")\n- `_data` is provided for clients to store a JSON-encoded array of site-specific data not to exceed 1M in size; this string is available via the get-sites endpoint, but is not part of the get-site record, nor is it available in the context of the site itself.", "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "type": "object", "example": { "message": "OK", "data": [] } }, "examples": { "success-530a19dfbccd73e4313006d96a3a22db": { "summary": "Success-Response, remove", "value": { "message": "OK", "data": [] } }, "success-09cba3fda0d3344cff87454ffbae0a4c": { "summary": "Success-Response, get", "value": { "message": "OK", "data": "some data" } } } } } }, "400": { "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message." }, "data": { "description": "Error details, or an empty array when none are returned." } }, "example": { "message": "Invalid key.", "data": [] } }, "examples": { "error-c113344fb830e11feca3cdb45df956bd": { "summary": "Error-Response", "value": { "message": "Invalid key.", "data": [] } } } } }, "description": "Invalid key, invalid action, missing value, or insufficient privileges." }, "403": { "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message." }, "data": { "description": "Error details, or an empty array when none are returned." } } } } }, "description": "Key is admin-only or method not allowed for this key." }, "404": { "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message." }, "data": { "description": "Error details, or an empty array when none are returned." } } } } }, "description": "Site not found." }, "423": { "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message." }, "data": { "description": "Error details, or an empty array when none are returned." } } } } }, "description": "Site is locked; non-get operations are disallowed." }, "500": { "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message." }, "data": { "description": "Error details, or an empty array when none are returned." } } } } }, "description": "Database error." } }, "parameters": [ { "name": "site", "in": "path", "description": "Site ID or domain.", "required": true, "schema": { "type": "string" } }, { "name": "key", "in": "path", "description": "Supported site meta key to get, add/update, or remove. Examples include \"allow_restore\", \"suspended\", \"php_version\", \"space_used\", \"db_charset\", and \"db_collate\".", "required": true, "schema": { "type": "string" } }, { "name": "action", "in": "path", "description": "\"get\", \"add\"/\"update\" or \"remove\".", "required": true, "schema": { "type": "string" } } ], "operationId": "get-site-meta-site-key-action" }, "post": { "tags": [ "Sites" ], "summary": "Manage Site Meta", "description": "Endpoint for managing site meta.\n\nThe following meta keys are supported:\n\n- Values for `db_charset` and `db_collate` include \"latin1\", \"latin1_swedish_ci\"; \"utf8\", \"utf8_general_ci\"; and \"utf8mb4\", \"utf8mb4_general_ci\".\n- `suspended` suspends a site. The value is the HTTP 4xx status code the site will respond with. The supported statuses are \"403\", \"404\", \"410\", \"451\", \"480\", and \"503\".\n- `suspend_after` will suspend a site after a given unixtime timestamp with the status specified in \"suspended\", default 480.\n- `allow_restore` opts a site into self-restore via the \"restore-site\" endpoint. The value must be a positive Unix timestamp, must not be more than 5 minutes in the future, and must be recent (within MONTH_IN_SECONDS) when \"restore-site\" is called. It only authorizes the restore window; the restore is started with the \"restore-site\" endpoint.\n- `php_version` sets the site's PHP version. Supported values include \"8.2\", \"8.3\", \"8.4\", and \"8.5\".\n- `wp_version` is a get-only key that can be used to retrieve the site's current managed WordPress version, which can be \"latest\", \"previous\", \"beta\", or \"alpha\" (the last two are used to test WordPress releases). Use the \"site-wordpress-version\" endpoint to set \"wp_version\".\n- `do_not_delete` may be set to a truthy value to prevent a site from begin deleted. This can be useful in some cases. For example, you might wish to preserve a site while it is being reviewed for Terms of Service violations.\n- `space_used` is a get-only key that returns an integer in bytes; it is updated every 12 hours with the amount of space used by a site's files.\n- `db_file_size` is a get-only key that returns an integer in bytes. It is updated every 12 hours with the amount of space used by a site's database.\n- `space_quota` can be used to get and set the space quota for a site. Value must be an integer followed by a size specifier like \"200G\".\n- `max_space_quota` is get-only and may be present if the platform has set a space_quota\" maximum for a specific site.\n- `photon_subsizes` controls whether WP skips generating intermediate image files when an image is uploaded. The platform is able to satisfy requests for intermediate image files whether or not they exist, so sites can save disk space by not creating them. When the a site's web server receives a request for a non-existent intermediate image file, it proxies the request to Photon which responds with the intermediate image size. Can be set to \"0\" or \"1\" or deleted.\n- `privacy_model` facilitates protection of site assets. May be set to \"wp_uploads\" to block logged-out requests for WP uploads. If set, an AT_PRIVACY_MODEL constant will be defined in the PHP environment.\n- `geo_affinity` may be used to get and set a site's geo-affinity. Allowed values are those returned by the \"get-available-datacenters\" endpoint. It is not currently useful to set a site's geo-affinity after creation unless you have access to an endpoint that allows you to subsequently trigger migration of the site to another server pool.\n- `generation` returns the server hardware generation the site was created with. It is read-only and is set only from the \"create-site\" `generation` parameter, so a site created without that parameter has no value here. Add, update and remove return 403.\n- `static_file_404` may be used to get and set how a site responds to requests for non-existent static files. May be set to \"lightweight\" for simple, fast web server 404s. May be set to \"wordpress\" to delegate such requests to WordPress. The current default is \"wordpress\".\n- `php_memory_limit` may be used to set the per-request PHP memory limit to a value between 512MB and 2048MB. Allowed values are 512, 1024, 1536, 2048. The default if not set is 512.\n- `opcache_memory_limit_mb` may be used to set the per-request PHP memory limit to a value up to 300.\n- `default_php_conns` may be used to either limit site's allowed concurrent PHP connections or to increase the default number of concurrent connections a site can use if the web server has spare PHP connections capacity. Clients may set any value for a site between 2 and 10; the platform has more leeway if needed.\n- `burst_php_conns` controls PHP burst behavior. 0 means burst is disabled, 1 means burst is enabled (legacy), and 2 allows up to 2x default_php_conns. Negative integers (e.g. -8) request a flat additive bonus of abs(value) connections above default_php_conns. All values are clamped to the global ceiling on the server.\n- `php_fs_permissions` may be used to cause HTTP requests being handled by PHP for a site to have that sites filesystem mounted specially. Currently supported values are \"rw\" (readwrite - the default), \"ro\" (readonly), and \"loggedin\" (read only unless logged into WordPress). It is possible that other more complicated settings may be added in the future.\n- `canonicalize_aliases` may be used to change whether a sites domain aliases redirect (default, \"true\") to the sites primary domain name or are served directly (when set to \"false\")\n- `_data` is provided for clients to store a JSON-encoded array of site-specific data not to exceed 1M in size; this string is available via the get-sites endpoint, but is not part of the get-site record, nor is it available in the context of the site itself.", "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "type": "object", "example": { "message": "OK", "data": [] } }, "examples": { "success-530a19dfbccd73e4313006d96a3a22db": { "summary": "Success-Response, remove", "value": { "message": "OK", "data": [] } }, "success-09cba3fda0d3344cff87454ffbae0a4c": { "summary": "Success-Response, get", "value": { "message": "OK", "data": "some data" } } } } } }, "400": { "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message." }, "data": { "description": "Error details, or an empty array when none are returned." } }, "example": { "message": "Invalid key.", "data": [] } }, "examples": { "error-c113344fb830e11feca3cdb45df956bd": { "summary": "Error-Response", "value": { "message": "Invalid key.", "data": [] } } } } }, "description": "Invalid key, invalid action, missing value, or insufficient privileges." }, "403": { "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message." }, "data": { "description": "Error details, or an empty array when none are returned." } } } } }, "description": "Key is admin-only or method not allowed for this key." }, "404": { "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message." }, "data": { "description": "Error details, or an empty array when none are returned." } } } } }, "description": "Site not found." }, "423": { "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message." }, "data": { "description": "Error details, or an empty array when none are returned." } } } } }, "description": "Site is locked; non-get operations are disallowed." }, "500": { "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message." }, "data": { "description": "Error details, or an empty array when none are returned." } } } } }, "description": "Database error." } }, "parameters": [ { "name": "site", "in": "path", "description": "Site ID or domain.", "required": true, "schema": { "type": "string" } }, { "name": "key", "in": "path", "description": "Supported site meta key to get, add/update, or remove. Examples include \"allow_restore\", \"suspended\", \"php_version\", \"space_used\", \"db_charset\", and \"db_collate\".", "required": true, "schema": { "type": "string" } }, { "name": "action", "in": "path", "description": "\"get\", \"add\"/\"update\" or \"remove\".", "required": true, "schema": { "type": "string" } } ], "operationId": "post-site-meta-site-key-action", "requestBody": { "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "properties": { "value": { "type": "string", "description": "(POST) Required. For \"add\"/\"update\" action, the value we're setting." } }, "required": [ "value" ] } } } } } }, "/site-manage-software/{type}/{site}": { "post": { "tags": [ "Sites" ], "summary": "Manage Site Software", "description": "Manage a site's software installation and activation.", "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Response status message." }, "data": { "type": "object", "description": "Response object.", "properties": { "job_id": { "type": "number", "description": "Job ID of the queued job." }, "response_ticket_id": { "type": "string", "description": "Response ticket ID which can be used to check on the status of the request." } } } }, "example": { "message": "OK", "data": { "job_id": 1234, "response_ticket_id": "abcd" } } }, "examples": { "success-ff5ff39165100e822eb118b73cac03f6": { "summary": "Success-Response", "value": { "message": "OK", "data": { "job_id": 1234, "response_ticket_id": "abcd" } } } } } } }, "400": { "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message." }, "data": { "description": "Error details, or an empty array when none are returned." } } } } }, "description": "No valid software actions provided." }, "403": { "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message." }, "data": { "description": "Error details, or an empty array when none are returned." } } } } }, "description": "Access denied." }, "404": { "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message." }, "data": { "description": "Error details, or an empty array when none are returned." } } } } }, "description": "Site not found." }, "500": { "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message." }, "data": { "description": "Error details, or an empty array when none are returned." } } } } }, "description": "Unable to find primary server for site's pool." } }, "parameters": [ { "name": "type", "in": "path", "description": "Service type (\"atomic\" for external clients, \"wpcom\" for WordPress.com).", "required": true, "schema": { "type": "string", "enum": [ "atomic", "wpcom" ] } }, { "name": "site", "in": "path", "description": "Site ID or domain name (for \"atomic\") or WordPress.com blog ID (for \"wpcom\").", "required": true, "schema": { "oneOf": [ { "type": "string" }, { "type": "number" } ] } } ], "operationId": "post-site-manage-software-type-site", "requestBody": { "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "properties": { "software_slug": { "type": "string", "description": "Form-urlencoded key-value pairs where the key is the software slug. and the value is the action to take.\n\n**Key (software_slug)**: The plugin or theme identifier; formats include: \"plugins/woocommerce/latest\", \"plugins/woocommerce-gateway-paypal-express-checkout/latest\", \"plugins/akismet/latest\", \"themes/storefront/latest\", \"themes/pub/ocean-mist\", \"wordpress/themes/premium/caldwell\", \"mu-plugins/example-slug/latest\", \"mu-plugins/example-slug/latest/custom-loader.php\", \"themes://url\", \"theme://url\", \"plugins://url\", \"plugin://url\"\n\nManaged mu-plugin keys use \"mu-plugins/{slug}/{version}\" or \"mu-plugins/{slug}/{version}/{loader-file}\". If the loader file is omitted, it defaults to \"{slug}-loader.php\".\n\nNote: The key is rfc3986 decoded. This is an important note because PHP will interpret a key, replacing periods ( \".\" ) and spaces ( \" \" ) with underscores ( \"_\" ) so if you are passing a URL which probably has at least a . in it on account of probably ending in .zip then you will need to encode those characters, otherwise it will be interpreted by PHP on the server side as _zip instead. It is acceptable (and even encouraged) to simply %nn encode all not alpha-numeric values to avoid confusion.\n\n**Value (action)**: The action to take, one of \"activate\", \"install\", \"activate-locked\", \"install-locked\", \"deactivate\", \"remove\", \"lock\", or \"unlock\"\n\nFor \"mu-plugins/...\" keys, only \"install\", \"install-locked\", \"remove\", \"lock\", and \"unlock\" apply. Activation and deactivation actions do not apply to mu-plugins. Locked mu-plugin installs are platform-protected; use \"unlock\" before \"remove\".", "default": "action" } }, "required": [ "software_slug" ] } } } } } }, "/ssh-disconnect-all-users/{service}/{identifier}": { "get": { "tags": [ "SSH" ], "summary": "Queue SSH Disconnect All Users Job", "description": "Queue a job to terminate all active SSH and SFTP connections for a site. Affects both user-level and client-level connections.", "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Response status message." }, "data": { "type": "object", "description": "Job details object.", "properties": { "job_id": { "type": "number", "description": "Queued job ID." } } } }, "example": { "message": "OK", "data": { "job_id": 1234 } } }, "examples": { "success-d993b590e1710e955d3fd7cfae4f816f": { "summary": "Success-Response", "value": { "message": "OK", "data": { "job_id": 1234 } } } } } } }, "404": { "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message." }, "data": { "description": "Error details, or an empty array when none are returned." } } } } }, "description": "Site not found." }, "500": { "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message." }, "data": { "description": "Error details, or an empty array when none are returned." } } } } }, "description": "Database error, no server found for site, or job queue failure." } }, "parameters": [ { "name": "service", "in": "path", "description": "Service type (client name, \"domain\" for domain lookup, or \"wpcom\" for WordPress.com blog ID).", "required": true, "schema": { "type": "string" } }, { "name": "identifier", "in": "path", "description": "Site identifier (domain for \"domain\" service, site ID for client, WordPress.com blog ID for \"wpcom\").", "required": true, "schema": { "type": "string" } } ], "operationId": "get-ssh-disconnect-all-users-service-identifier" } }, "/client-meta/{client}/{key}/remove": { "get": { "tags": [ "Client Meta" ], "summary": "Remove Client Meta", "description": "Remove a client meta value.\n\nNote: `max_space_quota` is read-only and cannot be removed.", "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Response status message." }, "data": { "type": "array", "description": "Empty array." } }, "example": { "message": "OK", "data": [] } }, "examples": { "success-530a19dfbccd73e4313006d96a3a22db": { "summary": "Success-Response", "value": { "message": "OK", "data": [] } } } } } }, "400": { "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message." }, "data": { "description": "Error details, or an empty array when none are returned." } }, "example": { "message": "Invalid key", "data": [] } }, "examples": { "error-713244277bf85619f15371801214cafd": { "summary": "Error-Response", "value": { "message": "Invalid key", "data": [] } } } } }, "description": "Invalid or unsupported meta key." }, "403": { "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message." }, "data": { "description": "Error details, or an empty array when none are returned." } } } } }, "description": "Access denied or method not allowed for this key." }, "404": { "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message." }, "data": { "description": "Error details, or an empty array when none are returned." } }, "example": { "message": "Not Found", "data": [] } }, "examples": { "error-fcc5021de5fd64295232140c6eeed99a": { "summary": "Error-Response", "value": { "message": "Not Found", "data": [] } } } } }, "description": "Meta key not found for this client." } }, "parameters": [ { "name": "client", "in": "path", "description": "Client name or ID.", "required": true, "schema": { "type": "string" } }, { "name": "key", "in": "path", "description": "Meta key.", "required": true, "schema": { "type": "string", "enum": [ "webhook_url", "webhook_secret_key", "client_ssh_default_from", "client_ssh_force_from", "client_ssh_firewall", "default_privacy_model", "webhook_hmac_key", "skip_force_backup_db" ] } } ], "operationId": "get-client-meta-client-key-remove" } }, "/crontab/{site}/remove": { "post": { "tags": [ "Cron" ], "summary": "Remove Cron Entry", "description": "Removes a cron entry from a site.\n\nIf the event is already running, removing it will prevent future runs, but will not interrupt any existing runs.", "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Response status message." }, "data": { "type": "array", "description": "Empty array." } }, "example": { "message": "OK", "data": [] } }, "examples": { "success-530a19dfbccd73e4313006d96a3a22db": { "summary": "Success-Response", "value": { "message": "OK", "data": [] } } } } } }, "400": { "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message." }, "data": { "description": "Error details, or an empty array when none are returned." } } } } }, "description": "Invalid or empty cron_id." }, "403": { "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message." }, "data": { "description": "Error details, or an empty array when none are returned." } } } } }, "description": "Access denied." }, "404": { "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message." }, "data": { "description": "Error details, or an empty array when none are returned." } } } } }, "description": "Site or cron entry not found." } }, "parameters": [ { "name": "site", "in": "path", "description": "Site ID or domain.", "required": true, "schema": { "type": "string" } } ], "operationId": "post-crontab-site-remove", "requestBody": { "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "properties": { "cron_id": { "type": "number", "description": "Cron ID to remove." } }, "required": [ "cron_id" ] } } } } } }, "/firewall-rules/{site}/remove": { "post": { "tags": [ "Security" ], "summary": "Remove Firewall Rule", "description": "Remove an existing firewall rule from a site.", "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Response status message." }, "data": { "type": "array", "description": "Empty array." } }, "example": { "message": "OK", "data": [] } }, "examples": { "success-530a19dfbccd73e4313006d96a3a22db": { "summary": "Success-Response", "value": { "message": "OK", "data": [] } } } } } }, "400": { "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message." }, "data": { "description": "Error details, or an empty array when none are returned." } } } } }, "description": "Invalid rule ID format." }, "403": { "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message." }, "data": { "description": "Error details, or an empty array when none are returned." } } } } }, "description": "Access denied." }, "404": { "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message." }, "data": { "description": "Error details, or an empty array when none are returned." } }, "example": { "message": "Rule not found.", "data": [] } }, "examples": { "error-08df671f47f6fcd2bd10a8b2e5894681": { "summary": "Error-Response", "value": { "message": "Rule not found.", "data": [] } } } } }, "description": "Site or rule not found." }, "500": { "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message." }, "data": { "description": "Error details, or an empty array when none are returned." } } } } }, "description": "Database error." } }, "parameters": [ { "name": "site", "in": "path", "description": "Site ID or domain.", "required": true, "schema": { "type": "string" } } ], "operationId": "post-firewall-rules-site-remove", "requestBody": { "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "properties": { "rule_id": { "type": "number", "description": "Firewall rule ID to remove." } }, "required": [ "rule_id" ] } } } } } }, "/alias-pkey/remove/{client}/{category}/{name}": { "post": { "tags": [ "SSH" ], "summary": "Remove Public Key", "description": "Delete a single aliasable public key.\n\nRemoves an aliasable public key. Any object referencing this address will still be doing so. An object referencing the address of a nonexistent key will, effectively, have no key. If a key is [re]created at an address then all objects referencing that address will then be accessible via the aliasable key.", "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Response status message." }, "data": { "type": "boolean", "description": "True on success (also true when key was already absent)." } } } } } }, "400": { "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message." }, "data": { "description": "Error details, or an empty array when none are returned." } } } } }, "description": "Attempted to remove a protected key." }, "403": { "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message." }, "data": { "description": "Error details, or an empty array when none are returned." } } } } }, "description": "Access denied." }, "500": { "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message." }, "data": { "description": "Error details, or an empty array when none are returned." } } } } }, "description": "Database error; data contains the error message." } }, "parameters": [ { "name": "client", "in": "path", "description": "Client name or ID.", "required": true, "schema": { "type": "string" } }, { "name": "category", "in": "path", "description": "Category name.", "required": true, "schema": { "type": "string" } }, { "name": "name", "in": "path", "description": "Key name.", "required": true, "schema": { "type": "string" } } ], "operationId": "post-alias-pkey-remove-client-category-name" } }, "/ssh-user/{service}/{identifier}/remove/{username}": { "get": { "tags": [ "SSH" ], "summary": "Remove Site SSH/SFTP User", "description": "Delete an SSH/SFTP user from a site. Also queues a disconnect job to terminate any active SSH sessions for this user.", "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Response status message." }, "data": { "type": "array", "description": "Empty array." } }, "example": { "message": "OK", "data": [] } }, "examples": { "success-530a19dfbccd73e4313006d96a3a22db": { "summary": "Success-Response", "value": { "message": "OK", "data": [] } } } } } }, "400": { "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message." }, "data": { "description": "Error details, or an empty array when none are returned." } } } } }, "description": "Invalid site, service type, or missing/invalid username." }, "404": { "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message." }, "data": { "description": "Error details, or an empty array when none are returned." } } } } }, "description": "Username not found for this site." }, "500": { "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message." }, "data": { "description": "Error details, or an empty array when none are returned." } } } } }, "description": "Database error." } }, "parameters": [ { "name": "service", "in": "path", "description": "Service type (client name, \"domain\" for domain lookup, or \"wpcom\" for WordPress.com blog ID).", "required": true, "schema": { "type": "string" } }, { "name": "identifier", "in": "path", "description": "Site identifier (domain for \"domain\" service, site ID for client, WordPress.com blog ID for \"wpcom\").", "required": true, "schema": { "type": "string" } }, { "name": "username", "in": "path", "description": "Username to remove.", "required": true, "schema": { "type": "string" } } ], "operationId": "get-ssh-user-service-identifier-remove-username" }, "post": { "tags": [ "SSH" ], "summary": "Remove Site SSH/SFTP User", "description": "Delete an SSH/SFTP user from a site. Also queues a disconnect job to terminate any active SSH sessions for this user.", "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Response status message." }, "data": { "type": "array", "description": "Empty array." } }, "example": { "message": "OK", "data": [] } }, "examples": { "success-530a19dfbccd73e4313006d96a3a22db": { "summary": "Success-Response", "value": { "message": "OK", "data": [] } } } } } }, "400": { "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message." }, "data": { "description": "Error details, or an empty array when none are returned." } } } } }, "description": "Invalid site, service type, or missing/invalid username." }, "404": { "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message." }, "data": { "description": "Error details, or an empty array when none are returned." } } } } }, "description": "Username not found for this site." }, "500": { "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message." }, "data": { "description": "Error details, or an empty array when none are returned." } } } } }, "description": "Database error." } }, "parameters": [ { "name": "service", "in": "path", "description": "Service type (client name, \"domain\" for domain lookup, or \"wpcom\" for WordPress.com blog ID).", "required": true, "schema": { "type": "string" } }, { "name": "identifier", "in": "path", "description": "Site identifier (domain for \"domain\" service, site ID for client, WordPress.com blog ID for \"wpcom\").", "required": true, "schema": { "type": "string" } }, { "name": "username", "in": "path", "description": "Username to remove.", "required": true, "schema": { "type": "string" } } ], "operationId": "post-ssh-user-service-identifier-remove-username" } }, "/on-demand-backup/create/{site}/{type}": { "post": { "tags": [ "Backups" ], "summary": "Request Backup Creation", "description": "Request creation of an on-demand backup for a site. The backup will contain either filesystem data, database data, or both depending on the type specified. Backups are subject to quota limits which can be customized via site or client metadata.", "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Response status message." }, "data": { "type": "object", "description": "Created backup request.", "properties": { "atomic_backup_request_id": { "type": "number", "description": "ID of the created backup request." } } } }, "example": { "message": "OK", "data": { "atomic_backup_request_id": 12345 } } }, "examples": { "success-f859e9426dfd075b07ed8f2ed5da96ae": { "summary": "{json} Success-Response", "value": { "message": "OK", "data": { "atomic_backup_request_id": 12345 } } } } } } }, "400": { "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message." }, "data": { "description": "Error details, or an empty array when none are returned." } } } } }, "description": "Invalid backup type (must be \"fs\" or \"db\")." }, "403": { "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message." }, "data": { "description": "Error details, or an empty array when none are returned." } } } } }, "description": "Backup quota reached for this site." }, "404": { "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message." }, "data": { "description": "Error details, or an empty array when none are returned." } } } } }, "description": "Site not found." } }, "parameters": [ { "name": "site", "in": "path", "description": "Site ID or domain name.", "required": true, "schema": { "type": "string" } }, { "name": "type", "in": "path", "description": "Backup type: \"fs\" for filesystem or \"db\" for database.", "required": true, "schema": { "type": "string", "enum": [ "fs", "db" ] } } ], "operationId": "post-on-demand-backup-create-site-type" } }, "/on-demand-backup/delete/{site}/{backup_id}": { "post": { "tags": [ "Backups" ], "summary": "Request Backup Deletion", "description": "Request deletion of an existing on-demand backup. Only backups of type \"ondemand-fs\", \"ondemand-db\", or legacy \"ondemand\" can be deleted.", "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Response status message." }, "data": { "type": "object", "description": "Created deletion request.", "properties": { "atomic_backup_request_id": { "type": "number", "description": "ID of the created deletion request." } } } }, "example": { "message": "OK", "data": { "atomic_backup_request_id": 67890 } } }, "examples": { "success-8d912158d9e96a7b38f6170a3bb4ecb9": { "summary": "{json} Success-Response", "value": { "message": "OK", "data": { "atomic_backup_request_id": 67890 } } } } } } }, "403": { "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message." }, "data": { "description": "Error details, or an empty array when none are returned." } } } } }, "description": "Access denied." }, "404": { "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message." }, "data": { "description": "Error details, or an empty array when none are returned." } } } } }, "description": "Site not found, backup not found, or backup doesn't belong to this site." } }, "parameters": [ { "name": "site", "in": "path", "description": "Site ID or domain name.", "required": true, "schema": { "type": "string" } }, { "name": "backup_id", "in": "path", "description": "ID of the backup record to delete.", "required": true, "schema": { "type": "number" } } ], "operationId": "post-on-demand-backup-delete-site-backup_id" } }, "/reset-db-password/{type}/{site}": { "post": { "tags": [ "Sites" ], "summary": "Reset Database Password", "description": "Reset the database password for a site.", "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Response status message." }, "data": { "type": "object", "description": "Response object.", "properties": { "job_id": { "type": "number", "description": "Job ID of the queued job." } } } }, "example": { "message": "OK", "data": { "job_id": 1234 } } }, "examples": { "success-d993b590e1710e955d3fd7cfae4f816f": { "summary": "Success-Response", "value": { "message": "OK", "data": { "job_id": 1234 } } } } } } }, "403": { "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message." }, "data": { "description": "Error details, or an empty array when none are returned." } } } } }, "description": "Access denied." }, "404": { "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message." }, "data": { "description": "Error details, or an empty array when none are returned." } } } } }, "description": "Site not found." }, "500": { "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message." }, "data": { "description": "Error details, or an empty array when none are returned." } } } } }, "description": "Internal server error." } }, "parameters": [ { "name": "type", "in": "path", "description": "Service type (\"atomic\" for external clients, \"wpcom\" for WordPress.com).", "required": true, "schema": { "type": "string", "enum": [ "atomic", "wpcom" ] } }, { "name": "site", "in": "path", "description": "Site ID or domain name (for \"atomic\") or WordPress.com blog ID (for \"wpcom\").", "required": true, "schema": { "oneOf": [ { "type": "string" }, { "type": "number" } ] } } ], "operationId": "post-reset-db-password-type-site" } }, "/reset-db-password/{type}/{site}/{new}": { "post": { "tags": [ "Sites" ], "summary": "Reset Database Password", "description": "Reset the database password for a site.", "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Response status message." }, "data": { "type": "object", "description": "Response object.", "properties": { "job_id": { "type": "number", "description": "Job ID of the queued job." } } } }, "example": { "message": "OK", "data": { "job_id": 1234 } } }, "examples": { "success-d993b590e1710e955d3fd7cfae4f816f": { "summary": "Success-Response", "value": { "message": "OK", "data": { "job_id": 1234 } } } } } } }, "403": { "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message." }, "data": { "description": "Error details, or an empty array when none are returned." } } } } }, "description": "Access denied." }, "404": { "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message." }, "data": { "description": "Error details, or an empty array when none are returned." } } } } }, "description": "Site not found." }, "500": { "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message." }, "data": { "description": "Error details, or an empty array when none are returned." } } } } }, "description": "Internal server error." } }, "parameters": [ { "name": "type", "in": "path", "description": "Service type (\"atomic\" for external clients, \"wpcom\" for WordPress.com).", "required": true, "schema": { "type": "string", "enum": [ "atomic", "wpcom" ] } }, { "name": "site", "in": "path", "description": "Site ID or domain name (for \"atomic\") or WordPress.com blog ID (for \"wpcom\").", "required": true, "schema": { "oneOf": [ { "type": "string" }, { "type": "number" } ] } }, { "name": "new", "in": "path", "description": "Use \"new\" to generate a completely new password.", "required": true, "schema": { "type": "string", "enum": [ "new" ] } } ], "operationId": "post-reset-db-password-type-site-new" } }, "/reset-cache-prefix/{site}": { "post": { "tags": [ "Sites" ], "summary": "Reset Site Cache Prefix", "description": "Generate a new `cache_prefix` for a site. The site stops using its existing object cache entries and refills the cache from the database. Also queues a job to disconnect all active SSH and SFTP sessions for the site.", "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Response status message." } }, "example": { "message": "OK", "data": [] } }, "examples": { "success-530a19dfbccd73e4313006d96a3a22db": { "summary": "Success-Response", "value": { "message": "OK", "data": [] } } } } } }, "403": { "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message." }, "data": { "description": "Error details, or an empty array when none are returned." } } } } }, "description": "Access denied." }, "404": { "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message." }, "data": { "description": "Error details, or an empty array when none are returned." } } } } }, "description": "Site not found." }, "500": { "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message." }, "data": { "description": "Error details, or an empty array when none are returned." } } } } }, "description": "Database error or job queue failure." } }, "parameters": [ { "name": "site", "in": "path", "description": "Site ID or domain.", "required": true, "schema": { "type": "string" } } ], "operationId": "post-reset-cache-prefix-site" } }, "/restore-site/{site}": { "post": { "tags": [ "Sites" ], "summary": "Restore Existing Site From Its Own Backups", "description": "Restore an existing site from a filesystem + database backup pair belonging to that same site. Requires the customer to have set the `allow_restore` site meta to a recent Unix timestamp (within MONTH_IN_SECONDS), and to have suspended the destination site with status 503 via the `suspended` site meta, using the `site-meta` endpoint.\n\nMirrors the work performed by `site-provisioned/:site_id/restore` after a `create-site` with `restore_from`, but writes against an existing site instead of a freshly provisioned one.", "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Response status message" }, "data": { "type": "object", "description": "Restore information", "properties": { "atomic_job_id": { "type": "number", "description": "Job ID of the queued restore job" }, "response_ticket_id": { "type": "string", "description": "Response ticket ID to check on the status of this request." } } } }, "example": { "message": "OK", "data": { "atomic_job_id": 123456, "response_ticket_id": "67890abc.def12345..." } } }, "examples": { "success-6f8ae057b1d8355bc82ba81c1fc879e5": { "summary": "Success-Response", "value": { "message": "OK", "data": { "atomic_job_id": 123456, "response_ticket_id": "67890abc.def12345..." } } } } } } }, "400": { "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message." }, "data": { "description": "Error details, or an empty array when none are returned." } } } } }, "description": "Missing or stale `allow_restore`, invalid `restore_from`, backup not ready, missing fs/db side of the pair." }, "403": { "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message." }, "data": { "description": "Error details, or an empty array when none are returned." } } } } }, "description": "Caller cannot act on this site's client." }, "404": { "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message." }, "data": { "description": "Error details, or an empty array when none are returned." } } } } }, "description": "Site or backup not found." }, "409": { "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message." }, "data": { "description": "Error details, or an empty array when none are returned." } } } } }, "description": "Backup belongs to a different site, two backups of the same type were supplied, or the site is not suspended with status 503 (the caller must take the site offline first via the `suspended` site meta)." } }, "parameters": [ { "name": "site", "in": "path", "description": "Site ID or domain.", "required": true, "schema": { "oneOf": [ { "type": "number" }, { "type": "string" } ] } } ], "operationId": "post-restore-site-site", "requestBody": { "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "properties": { "restore_from": { "type": "array", "items": { "type": "number" }, "description": "Exactly two backup record IDs (one filesystem backup, one database backup) belonging to the same site as the restore destination." } }, "required": [ "restore_from" ] } } } } } }, "/ssl-retry/{domain}": { "post": { "tags": [ "Sites" ], "summary": "Retry SSL Provisioning", "description": "Retry SSL certificate provisioning.", "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Response status message." }, "data": { "type": "object", "description": "Response object.", "properties": { "queued": { "type": "boolean", "description": "Whether the domain was successfully requeued for provisioning." } } } }, "example": { "message": "OK", "data": { "queued": true } } }, "examples": { "success-5c55edae699a99a9556c349a172edd5f": { "summary": "Success-Response", "value": { "message": "OK", "data": { "queued": true } } } } } } }, "403": { "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message." }, "data": { "description": "Error details, or an empty array when none are returned." } } } } }, "description": "Access denied." }, "404": { "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message." }, "data": { "description": "Error details, or an empty array when none are returned." } } } } }, "description": "Site not found." } }, "parameters": [ { "name": "domain", "in": "path", "description": "Domain name.", "required": true, "schema": { "type": "string" } } ], "operationId": "post-ssl-retry-domain" } }, "/migration/preflight/{migration_id}": { "post": { "tags": [ "Migrations" ], "summary": "Run Preflight Checks", "description": "Initiate preflight checks for a migration. Verifies connectivity and validates the remote site before running the full migration. Creates a response ticket for tracking progress.", "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Response status message." }, "data": { "type": "object", "properties": { "response_ticket_id": { "type": "string", "description": "Ticket ID for tracking preflight progress." } } } } } } } }, "400": { "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message." }, "data": { "description": "Error details, or an empty array when none are returned." } } } } }, "description": "Invalid state transition." }, "403": { "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message." }, "data": { "description": "Error details, or an empty array when none are returned." } } } } }, "description": "Access denied." }, "404": { "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message." }, "data": { "description": "Error details, or an empty array when none are returned." } } } } }, "description": "Migration not found." }, "500": { "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message." }, "data": { "description": "Error details, or an empty array when none are returned." } } } } }, "description": "Failed to update migration state." } }, "parameters": [ { "name": "migration_id", "in": "path", "description": "Migration ID to run preflight checks on.", "required": true, "schema": { "type": "number" } } ], "operationId": "post-migration-preflight-migration_id" } }, "/malware/scan/{site}": { "post": { "tags": [ "Security" ], "summary": "Scan Site for Malware", "description": "Scan a site for malware.", "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Response status message." }, "data": { "type": "object", "description": "Response data.", "properties": { "response_ticket_id": { "type": "string", "description": "Ticket ID for tracking scan progress." } } } }, "example": { "message": "OK", "data": { "response_ticket_id": "67890abc.def12345..." } } }, "examples": { "success-1e9d2856e09f9050dc98c8327ad3748e": { "summary": "Success-Response", "value": { "message": "OK", "data": { "response_ticket_id": "67890abc.def12345..." } } } } } } }, "400": { "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message." }, "data": { "description": "Error details, or an empty array when none are returned." } } } } }, "description": "Invalid site identifier." }, "403": { "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message." }, "data": { "description": "Error details, or an empty array when none are returned." } } } } }, "description": "Access denied." }, "409": { "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message." }, "data": { "description": "Error details, or an empty array when none are returned." } } } } }, "description": "A scan is already pending for this site." }, "500": { "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message." }, "data": { "description": "Error details, or an empty array when none are returned." } } } } }, "description": "Failed to queue the scan job." } }, "parameters": [ { "name": "site", "in": "path", "description": "Site ID or domain.", "required": true, "schema": { "type": "string" } } ], "operationId": "post-malware-scan-site", "requestBody": { "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "properties": { "log": { "type": "string", "enum": [ "true", "false" ], "description": "If \"true\", leaves a log file artifact in the site's SSH home directory." }, "patterns": { "type": "string", "enum": [ "true", "false" ], "description": "If \"false\", skips file content pattern matching." }, "virus": { "type": "string", "enum": [ "true", "false" ], "description": "If \"false\", skips file content virus scanning." }, "fuzzy-patterns": { "type": "string", "enum": [ "true", "false" ], "description": "If \"false\", skips file content fuzzy pattern matching." }, "experimental": { "type": "string", "enum": [ "true", "false" ], "description": "If \"true\", uses experimental rules in addition to production rules." }, "incremental": { "type": "string", "enum": [ "true", "false" ], "description": "If \"true\", does an incremental scan." }, "detailed": { "type": "string", "enum": [ "true", "false" ], "description": "If \"true\", enables detailed YARA output." } } } } } } } }, "/migration/ready/{migration_id}": { "post": { "tags": [ "Migrations" ], "summary": "Set Migration Ready", "description": "Mark a migration as ready to begin full migration. Creates a response ticket for tracking progress.", "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Response status message." }, "data": { "type": "object", "properties": { "response_ticket_id": { "type": "string", "description": "Ticket ID for tracking migration progress." } } } } } } } }, "400": { "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message." }, "data": { "description": "Error details, or an empty array when none are returned." } } } } }, "description": "Invalid state transition." }, "403": { "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message." }, "data": { "description": "Error details, or an empty array when none are returned." } } } } }, "description": "Access denied." }, "404": { "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message." }, "data": { "description": "Error details, or an empty array when none are returned." } } } } }, "description": "Migration not found." }, "500": { "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message." }, "data": { "description": "Error details, or an empty array when none are returned." } } } } }, "description": "Failed to update migration state." } }, "parameters": [ { "name": "migration_id", "in": "path", "description": "Migration ID to mark as ready.", "required": true, "schema": { "type": "number" } } ], "operationId": "post-migration-ready-migration_id" } }, "/site-set-access-type/{service}/{identifier}/{type}": { "get": { "tags": [ "SSH" ], "summary": "Set Site Service Access Type", "description": "Set access type for given service and site.", "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Response status message." }, "data": { "type": "object", "description": "Response object.", "properties": { "atomic_site_id": { "type": "number", "description": "Site ID." }, "type": { "type": "string", "description": "Access type set." } } } }, "example": { "message": "OK", "data": { "atomic_site_id": "149401633", "type": "sftp" } } }, "examples": { "success-da84d229d0dfd334382f6ccc1bacc2dd": { "summary": "Success-Response", "value": { "message": "OK", "data": { "atomic_site_id": "149401633", "type": "sftp" } } } } } } }, "403": { "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message." }, "data": { "description": "Error details, or an empty array when none are returned." } } } } }, "description": "Access denied." }, "404": { "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message." }, "data": { "description": "Error details, or an empty array when none are returned." } } } } }, "description": "Site not found." } }, "parameters": [ { "name": "service", "in": "path", "description": "Service type (client name, \"domain\" for domain lookup, or \"wpcom\" for WordPress.com blog ID).", "required": true, "schema": { "type": "string" } }, { "name": "identifier", "in": "path", "description": "Site identifier (domain for \"domain\" service, site ID for client, WordPress.com blog ID for \"wpcom\").", "required": true, "schema": { "type": "string" } }, { "name": "type", "in": "path", "description": "Access type.", "required": true, "schema": { "type": "string", "enum": [ "ssh", "sftp", "legacy" ] } } ], "operationId": "get-site-set-access-type-service-identifier-type" } }, "/custom-certificates/{site}/stage": { "post": { "tags": [ "Custom SSL Certificates" ], "summary": "Stage a Custom Certificate", "description": "Prepare a certificate for use on one or more domains. Does not activate the certificate immediately.", "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Response status message." }, "data": { "type": "object", "description": "Staged certificate.", "properties": { "ssl_custom_certificate_id": { "type": "number", "description": "Certificate ID." }, "domains": { "type": "array", "items": { "type": "string" }, "description": "Domains covered by the certificate." }, "is_active": { "type": "boolean", "description": "Whether the certificate is active (false for newly staged certificates)." } } } }, "example": { "message": "OK", "data": { "ssl_custom_certificate_id": 12345, "is_active": 0, "domains": [ "example.com", "www.example.com" ] } } }, "examples": { "success-230e5a47c94bbe92a840132121171410": { "summary": "Success-Response", "value": { "message": "OK", "data": { "ssl_custom_certificate_id": 12345, "is_active": 0, "domains": [ "example.com", "www.example.com" ] } } } } } } }, "400": { "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message." }, "data": { "description": "Error details, or an empty array when none are returned." } }, "example": { "message": "Missing or invalid private_key (PEM expected)." } }, "examples": { "error-c5b31b71f48dcc442344eecebf3e3f75": { "summary": "Error-Response (bad PEM private key)", "value": { "message": "Missing or invalid private_key (PEM expected)." } } } } }, "description": "Invalid site identifier, missing required fields, or PEM validation failure." }, "403": { "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message." }, "data": { "description": "Error details, or an empty array when none are returned." } } } } }, "description": "Access denied." }, "500": { "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message." }, "data": { "description": "Error details, or an empty array when none are returned." } } } } }, "description": "ACME API error." } }, "parameters": [ { "name": "site", "in": "path", "description": "Site ID or domain.", "required": true, "schema": { "type": "string" } } ], "operationId": "post-custom-certificates-site-stage", "requestBody": { "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "properties": { "domains": { "type": "array", "items": { "type": "string" }, "description": "Optional list of domains to validate the certificate for. If omitted the site's primary domain is used." }, "certificate": { "type": "string", "description": "PEM-encoded SSL certificate, or certificate chain." }, "private_key": { "type": "string", "description": "PEM-encoded private key corresponding to the certificate." }, "csr": { "type": "string", "description": "PEM-encoded Certificate Signing Request." }, "trusted_certificates": { "type": "string", "description": "PEM-encoded trusted CA certificates if not included in the certificate chain." }, "client_certificate": { "type": "string", "description": "PEM-encoded client certificate, if required for mTLS." } }, "required": [ "certificate", "private_key" ] } } } } } }, "/test-status": { "get": { "tags": [ "Utility" ], "summary": "Test Status", "description": "Utility endpoint for testing interaction with the API.", "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "type": "object", "example": { "message": "Test", "data": [] } }, "examples": { "success-657b216502ca5fcc4a4a4ef55c483cd9": { "summary": "Response, test-status/200/Test", "value": { "message": "Test", "data": [] } } } } } }, "404": { "content": { "application/json": { "schema": { "type": "object", "example": { "message": "Nope", "data": [] } }, "examples": { "success-fed8cf063e579453c3c32acc60ff57e0": { "summary": "Response, test-status/404/Nope", "value": { "message": "Nope", "data": [] } } } } } } }, "operationId": "get-test-status" }, "post": { "tags": [ "Utility" ], "summary": "Test Status", "description": "Utility endpoint for testing interaction with the API.", "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "type": "object", "example": { "message": "Test", "data": [] } }, "examples": { "success-657b216502ca5fcc4a4a4ef55c483cd9": { "summary": "Response, test-status/200/Test", "value": { "message": "Test", "data": [] } } } } } }, "404": { "content": { "application/json": { "schema": { "type": "object", "example": { "message": "Nope", "data": [] } }, "examples": { "success-fed8cf063e579453c3c32acc60ff57e0": { "summary": "Response, test-status/404/Nope", "value": { "message": "Nope", "data": [] } } } } } } }, "operationId": "post-test-status", "requestBody": { "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "properties": { "data": { "type": "string", "description": "POST data to respond with." } } } } } } } }, "/test-status/{status}": { "get": { "tags": [ "Utility" ], "summary": "Test Status", "description": "Utility endpoint for testing interaction with the API.", "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "type": "object", "example": { "message": "Test", "data": [] } }, "examples": { "success-657b216502ca5fcc4a4a4ef55c483cd9": { "summary": "Response, test-status/200/Test", "value": { "message": "Test", "data": [] } } } } } }, "404": { "content": { "application/json": { "schema": { "type": "object", "example": { "message": "Nope", "data": [] } }, "examples": { "success-fed8cf063e579453c3c32acc60ff57e0": { "summary": "Response, test-status/404/Nope", "value": { "message": "Nope", "data": [] } } } } } } }, "parameters": [ { "name": "status", "in": "path", "description": "HTTP status to respond with.", "required": true, "schema": { "type": "string" } } ], "operationId": "get-test-status-status" }, "post": { "tags": [ "Utility" ], "summary": "Test Status", "description": "Utility endpoint for testing interaction with the API.", "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "type": "object", "example": { "message": "Test", "data": [] } }, "examples": { "success-657b216502ca5fcc4a4a4ef55c483cd9": { "summary": "Response, test-status/200/Test", "value": { "message": "Test", "data": [] } } } } } }, "404": { "content": { "application/json": { "schema": { "type": "object", "example": { "message": "Nope", "data": [] } }, "examples": { "success-fed8cf063e579453c3c32acc60ff57e0": { "summary": "Response, test-status/404/Nope", "value": { "message": "Nope", "data": [] } } } } } } }, "parameters": [ { "name": "status", "in": "path", "description": "HTTP status to respond with.", "required": true, "schema": { "type": "string" } } ], "operationId": "post-test-status-status", "requestBody": { "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "properties": { "data": { "type": "string", "description": "POST data to respond with." } } } } } } } }, "/test-status/{status}/{message}": { "get": { "tags": [ "Utility" ], "summary": "Test Status", "description": "Utility endpoint for testing interaction with the API.", "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "type": "object", "example": { "message": "Test", "data": [] } }, "examples": { "success-657b216502ca5fcc4a4a4ef55c483cd9": { "summary": "Response, test-status/200/Test", "value": { "message": "Test", "data": [] } } } } } }, "404": { "content": { "application/json": { "schema": { "type": "object", "example": { "message": "Nope", "data": [] } }, "examples": { "success-fed8cf063e579453c3c32acc60ff57e0": { "summary": "Response, test-status/404/Nope", "value": { "message": "Nope", "data": [] } } } } } } }, "parameters": [ { "name": "status", "in": "path", "description": "HTTP status to respond with.", "required": true, "schema": { "type": "string" } }, { "name": "message", "in": "path", "description": "Message to respond with.", "required": true, "schema": { "type": "string" } } ], "operationId": "get-test-status-status-message" }, "post": { "tags": [ "Utility" ], "summary": "Test Status", "description": "Utility endpoint for testing interaction with the API.", "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "type": "object", "example": { "message": "Test", "data": [] } }, "examples": { "success-657b216502ca5fcc4a4a4ef55c483cd9": { "summary": "Response, test-status/200/Test", "value": { "message": "Test", "data": [] } } } } } }, "404": { "content": { "application/json": { "schema": { "type": "object", "example": { "message": "Nope", "data": [] } }, "examples": { "success-fed8cf063e579453c3c32acc60ff57e0": { "summary": "Response, test-status/404/Nope", "value": { "message": "Nope", "data": [] } } } } } } }, "parameters": [ { "name": "status", "in": "path", "description": "HTTP status to respond with.", "required": true, "schema": { "type": "string" } }, { "name": "message", "in": "path", "description": "Message to respond with.", "required": true, "schema": { "type": "string" } } ], "operationId": "post-test-status-status-message", "requestBody": { "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "properties": { "data": { "type": "string", "description": "POST data to respond with." } } } } } } } }, "/ssl-android-compat/{domain}/{enable}": { "post": { "tags": [ "Sites" ], "summary": "Toggle Android Compatibility", "description": "Enable/disable certificates compatible with older Android devices. Android compatibility is enabled by default.", "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Response status message." }, "data": { "type": "object", "description": "Empty object." } }, "example": { "message": "OK", "data": [] } }, "examples": { "success-530a19dfbccd73e4313006d96a3a22db": { "summary": "Success-Response", "value": { "message": "OK", "data": [] } } } } } }, "400": { "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message." }, "data": { "description": "Error details, or an empty array when none are returned." } } } } }, "description": "Invalid enable value." }, "403": { "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message." }, "data": { "description": "Error details, or an empty array when none are returned." } } } } }, "description": "Access denied." }, "404": { "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message." }, "data": { "description": "Error details, or an empty array when none are returned." } } } } }, "description": "Site not found." } }, "parameters": [ { "name": "domain", "in": "path", "description": "Domain name.", "required": true, "schema": { "type": "string" } }, { "name": "enable", "in": "path", "description": "Whether to enable Android compatibility.", "required": true, "schema": { "type": "string", "enum": [ "true", "false" ] } } ], "operationId": "post-ssl-android-compat-domain-enable" } }, "/ssl-hsts-subdomain/{domain}/{enable}": { "post": { "tags": [ "Sites" ], "summary": "Toggle HSTS includeSubDomains", "description": "Enable/disable HSTS includeSubDomains directive. Includes the preload directive for ease of use.", "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Response status message." }, "data": { "type": "object", "description": "Empty object." } }, "example": { "message": "OK", "data": [] } }, "examples": { "success-530a19dfbccd73e4313006d96a3a22db": { "summary": "Success-Response", "value": { "message": "OK", "data": [] } } } } } }, "400": { "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message." }, "data": { "description": "Error details, or an empty array when none are returned." } } } } }, "description": "Invalid enable value." }, "403": { "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message." }, "data": { "description": "Error details, or an empty array when none are returned." } } } } }, "description": "Access denied." }, "404": { "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message." }, "data": { "description": "Error details, or an empty array when none are returned." } } } } }, "description": "Site not found." } }, "parameters": [ { "name": "domain", "in": "path", "description": "Site domain name.", "required": true, "schema": { "type": "string" } }, { "name": "enable", "in": "path", "description": "Whether to enable the includeSubDomains directive; \"true\" enables, \"false\" disables.", "required": true, "schema": { "type": "string", "enum": [ "true", "false" ] } } ], "operationId": "post-ssl-hsts-subdomain-domain-enable" } }, "/ssl-social-crawler-redirect/{domain}/{enable}": { "post": { "tags": [ "Sites" ], "summary": "Toggle Social Crawler Redirect", "description": "Enable/disable redirect from https to http for social crawlers. This is used to retain share counts between http/https for Facebook/Twitter/LinkedIn, if links were originally shared as http. Social crawler redirect is disabled by default for all new domains since 2022-11-04.", "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Response status message." }, "data": { "type": "object", "description": "Empty object." } }, "example": { "message": "OK", "data": [] } }, "examples": { "success-530a19dfbccd73e4313006d96a3a22db": { "summary": "Success-Response", "value": { "message": "OK", "data": [] } } } } } }, "400": { "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message." }, "data": { "description": "Error details, or an empty array when none are returned." } } } } }, "description": "Invalid enable value." }, "403": { "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message." }, "data": { "description": "Error details, or an empty array when none are returned." } } } } }, "description": "Access denied." }, "404": { "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message." }, "data": { "description": "Error details, or an empty array when none are returned." } } } } }, "description": "Site not found." } }, "parameters": [ { "name": "domain", "in": "path", "description": "Site domain name.", "required": true, "schema": { "type": "string" } }, { "name": "enable", "in": "path", "description": "Whether to enable social crawler redirects; \"true\" enables, \"false\" disables.", "required": true, "schema": { "type": "string", "enum": [ "true", "false" ] } } ], "operationId": "post-ssl-social-crawler-redirect-domain-enable" } }, "/custom-certificates/{site}/{id}/update": { "post": { "tags": [ "Custom SSL Certificates" ], "summary": "Update a Custom Certificate", "description": "Update an existing custom SSL certificate for renewal or rekeying. If id is omitted, the currently active certificate is updated.", "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Response status message." }, "data": { "type": "object", "description": "Update result.", "properties": { "updated": { "type": "boolean", "description": "Whether the certificate was updated." }, "ssl_custom_certificate_id": { "type": "number", "description": "Certificate ID." }, "certificate_expiration": { "type": "string", "description": "Certificate expiration datetime (UTC)." }, "active_domains": { "type": "array", "items": { "type": "string" }, "description": "Domains the certificate is active for." } } } }, "example": { "message": "OK", "data": { "updated": true, "ssl_custom_certificate_id": 12345, "certificate_expiration": "2026-11-01 23:59:59", "active_domains": [ "example.com", "www.example.com" ] } } }, "examples": { "success-a1b82a9b6dc24d2881f882eca4af9e3e": { "summary": "Success-Response", "value": { "message": "OK", "data": { "updated": true, "ssl_custom_certificate_id": 12345, "certificate_expiration": "2026-11-01 23:59:59", "active_domains": [ "example.com", "www.example.com" ] } } } } } } }, "400": { "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message." }, "data": { "description": "Error details, or an empty array when none are returned." } } } } }, "description": "Invalid site identifier, missing required fields, or PEM validation failure." }, "403": { "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message." }, "data": { "description": "Error details, or an empty array when none are returned." } } } } }, "description": "Access denied." }, "404": { "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message." }, "data": { "description": "Error details, or an empty array when none are returned." } } } } }, "description": "Certificate not found." }, "500": { "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message." }, "data": { "description": "Error details, or an empty array when none are returned." } } } } }, "description": "ACME API error." } }, "parameters": [ { "name": "site", "in": "path", "description": "Site ID or domain.", "required": true, "schema": { "type": "string" } }, { "name": "id", "in": "path", "description": "ID of the custom certificate to update. If omitted, the currently active certificate is updated.", "required": true, "schema": { "type": "number" } } ], "operationId": "post-custom-certificates-site-id-update", "requestBody": { "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "properties": { "domains": { "type": "array", "items": { "type": "string" }, "description": "Optional list of domains to validate the certificate for. If omitted the site's primary domain is used." }, "certificate": { "type": "string", "description": "PEM-encoded SSL certificate, or certificate chain." }, "private_key": { "type": "string", "description": "PEM-encoded private key corresponding to the certificate." }, "csr": { "type": "string", "description": "PEM-encoded Certificate Signing Request." }, "trusted_certificates": { "type": "string", "description": "PEM-encoded trusted CA certificates if not included in the certificate chain." }, "client_certificate": { "type": "string", "description": "PEM-encoded client certificate, if required for mTLS." } }, "required": [ "certificate", "private_key" ] } } } } } }, "/client-meta/{client}/{key}/update": { "post": { "tags": [ "Client Meta" ], "summary": "Update Client Meta", "description": "Update an existing client meta value.\n\nNote: `max_space_quota` is read-only and cannot be updated.", "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Response status message." }, "data": { "type": "array", "description": "Empty array." } }, "example": { "message": "OK", "data": [] } }, "examples": { "success-530a19dfbccd73e4313006d96a3a22db": { "summary": "Success-Response", "value": { "message": "OK", "data": [] } } } } } }, "400": { "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message." }, "data": { "description": "Error details, or an empty array when none are returned." } }, "example": { "message": "Invalid key", "data": [] } }, "examples": { "error-713244277bf85619f15371801214cafd": { "summary": "Error-Response", "value": { "message": "Invalid key", "data": [] } }, "error-102ca70662283f52df157c810067533e": { "summary": "Error-Response", "value": { "message": "A value must be provided", "data": [] } } } } }, "description": "Invalid or unsupported meta key.\n\nA value must be provided.\n\nInvalid URL provided for webhook_url.\n\nInvalid value for default_privacy_model; must be \"wp_uploads\" or \"proxy\"." }, "403": { "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message." }, "data": { "description": "Error details, or an empty array when none are returned." } } } } }, "description": "Access denied or method not allowed for this key." }, "500": { "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message." }, "data": { "description": "Error details, or an empty array when none are returned." } } } } }, "description": "Internal server error." } }, "parameters": [ { "name": "client", "in": "path", "description": "Client name or ID.", "required": true, "schema": { "type": "string" } }, { "name": "key", "in": "path", "description": "Meta key.", "required": true, "schema": { "type": "string", "enum": [ "webhook_url", "webhook_secret_key", "client_ssh_default_from", "client_ssh_force_from", "client_ssh_firewall", "default_privacy_model", "webhook_hmac_key", "skip_force_backup_db" ] } } ], "operationId": "post-client-meta-client-key-update", "requestBody": { "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "properties": { "value": { "type": "string", "description": "New value for the meta key." } }, "required": [ "value" ] } } } } } }, "/crontab/{site}/update/{cron_id}": { "post": { "tags": [ "Cron" ], "summary": "Update Cron Entry", "description": "Update an existing cron entry.", "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Response status message." }, "data": { "type": "object", "description": "Response data.", "properties": { "cron_id": { "type": "number", "description": "Updated cron entry ID." } } } }, "example": { "message": "OK", "data": { "cron_id": 96 } } }, "examples": { "success-ec188386f616deeb9d300440fdaab9a1": { "summary": "Success-Response", "value": { "message": "OK", "data": { "cron_id": 96 } } } } } } }, "400": { "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message." }, "data": { "description": "Error details, or an empty array when none are returned." } } } } }, "description": "Invalid or empty cron_id or command, or update failed." }, "403": { "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message." }, "data": { "description": "Error details, or an empty array when none are returned." } } } } }, "description": "Access denied." }, "404": { "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message." }, "data": { "description": "Error details, or an empty array when none are returned." } } } } }, "description": "Site or cron entry not found." }, "500": { "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message." }, "data": { "description": "Error details, or an empty array when none are returned." } } } } }, "description": "Database error." } }, "parameters": [ { "name": "site", "in": "path", "description": "Site ID or domain.", "required": true, "schema": { "type": "string" } }, { "name": "cron_id", "in": "path", "description": "Cron entry ID to update.", "required": true, "schema": { "type": "number" } } ], "operationId": "post-crontab-site-update-cron_id", "requestBody": { "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "properties": { "command": { "type": "string", "description": "Command to run." } }, "required": [ "command" ] } } } } } }, "/migration/update/{migration_id}": { "post": { "tags": [ "Migrations" ], "summary": "Update Migration", "description": "Update migration connection details. The migration must be at rest (not actively migrating). Updating configuration during an active migration would create ambiguity about which settings were used if a failure occurs.", "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Response status message." }, "data": { "type": "object", "description": "Updated values (sensitive values redacted)." } } } } } }, "400": { "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message." }, "data": { "description": "Error details, or an empty array when none are returned." } } } } }, "description": "Invalid migration ID format.\n\nMigration is not at rest and cannot be updated." }, "403": { "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message." }, "data": { "description": "Error details, or an empty array when none are returned." } } } } }, "description": "Access denied." }, "404": { "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message." }, "data": { "description": "Error details, or an empty array when none are returned." } } } } }, "description": "Migration not found." }, "500": { "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message." }, "data": { "description": "Error details, or an empty array when none are returned." } } } } }, "description": "Failed to update migration metadata." } }, "parameters": [ { "name": "migration_id", "in": "path", "description": "Migration ID to update.", "required": true, "schema": { "type": "number" } } ], "operationId": "post-migration-update-migration_id", "requestBody": { "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "properties": { "ssh-id": { "type": "string", "description": "SSH private key for authentication." }, "ssh-id-pass": { "type": "string", "description": "Passphrase for SSH private key." }, "remote-host": { "type": "string", "description": "Remote server hostname or IP address." }, "remote-port": { "type": "string", "description": "Remote server port number." }, "remote-user": { "type": "string", "description": "SSH username for remote server." }, "remote-pass": { "type": "string", "description": "Password for SSH authentication." }, "remote-docroot": { "type": "string", "description": "Path to document root on remote server." }, "remote-domain": { "type": "string", "description": "Remote domain name (empty string uses site's default domain)." } } } } } } } }, "/site-set-chroot/{site}/{desired}": { "post": { "tags": [ "Sites" ], "summary": "Update Site Chroot", "description": "Update the chroot environment for a site. The chroot slug must be one of the allowed values for the client. Queues a job to apply the filesystem changes on the pool server; use the returned job_id to track completion.", "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "description": "Response data.", "properties": { "job_id": { "type": "number", "description": "Queued job ID. When the site is already using the requested chroot, data is the string \"no-op\" instead of an object." } } } } } } } }, "400": { "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message." }, "data": { "description": "Error details, or an empty array when none are returned." } } } } }, "description": "The desired chroot slug is missing." }, "403": { "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message." }, "data": { "description": "Error details, or an empty array when none are returned." } } } } }, "description": "Access denied." }, "404": { "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message." }, "data": { "description": "Error details, or an empty array when none are returned." } } } } }, "description": "Site not found, or the desired chroot slug is not allowed for this client." }, "500": { "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message." }, "data": { "description": "Error details, or an empty array when none are returned." } } } } }, "description": "Server error." } }, "parameters": [ { "name": "site", "in": "path", "description": "Site ID or domain.", "required": true, "schema": { "type": "string" } }, { "name": "desired", "in": "path", "description": "Chroot slug to set (e.g. \"generic\").", "required": true, "schema": { "type": "string" } } ], "operationId": "post-site-set-chroot-site-desired" } }, "/update-site-domain/{service}/{identifier}/{domain}": { "post": { "tags": [ "Sites" ], "summary": "Update Site Domain", "description": "Update a site's primary domain.", "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Response status message." }, "data": { "type": "object", "description": "Response data. Absent when the domain is unchanged.", "properties": { "job_id": { "type": "number", "description": "Job ID of the queued domain-update job." }, "wpcom_blog_id": { "type": "number", "description": "Site's WordPress.com blog ID (only present for WordPress.com sites)." }, "atomic_site_id": { "type": "number", "description": "Site ID." }, "domain_name": { "type": "string", "description": "New primary domain name." }, "old_domain_name": { "type": "string", "description": "Previous primary domain name." } } } }, "example": { "message": "OK", "data": { "job_id": 1234, "wpcom_blog_id": 3456, "atomic_site_id": 5678, "domain_name": "updated-example.com", "old_domain_name": "example.com" } } }, "examples": { "success-059b23349188cf119cf743bb747b3d19": { "summary": "Success-Response", "value": { "message": "OK", "data": { "job_id": 1234, "wpcom_blog_id": 3456, "atomic_site_id": 5678, "domain_name": "updated-example.com", "old_domain_name": "example.com" } } } } } } }, "400": { "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message." }, "data": { "description": "Error details, or an empty array when none are returned." } } } } }, "description": "Missing domain name or invalid domain." }, "403": { "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message." }, "data": { "description": "Error details, or an empty array when none are returned." } } } } }, "description": "Access denied." }, "404": { "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message." }, "data": { "description": "Error details, or an empty array when none are returned." } } } } }, "description": "Site not found." } }, "parameters": [ { "name": "service", "in": "path", "description": "Service type; may be client name or \"domain\". Used to determine site lookup method; use \"domain\" to look up a site by domain, otherwise use the client identifier to look up a site by site ID.", "required": true, "schema": { "type": "string" } }, { "name": "identifier", "in": "path", "description": "Site identifier; domain name for \"domain\" lookups,. otherwise the site ID.", "required": true, "schema": { "type": "string" } }, { "name": "domain", "in": "path", "description": "New primary domain name.", "required": true, "schema": { "type": "string" } } ], "operationId": "post-update-site-domain-service-identifier-domain" } }, "/update-site-domain/{service}/{identifier}/{domain}/{keep}": { "post": { "tags": [ "Sites" ], "summary": "Update Site Domain", "description": "Update a site's primary domain.", "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Response status message." }, "data": { "type": "object", "description": "Response data. Absent when the domain is unchanged.", "properties": { "job_id": { "type": "number", "description": "Job ID of the queued domain-update job." }, "wpcom_blog_id": { "type": "number", "description": "Site's WordPress.com blog ID (only present for WordPress.com sites)." }, "atomic_site_id": { "type": "number", "description": "Site ID." }, "domain_name": { "type": "string", "description": "New primary domain name." }, "old_domain_name": { "type": "string", "description": "Previous primary domain name." } } } }, "example": { "message": "OK", "data": { "job_id": 1234, "wpcom_blog_id": 3456, "atomic_site_id": 5678, "domain_name": "updated-example.com", "old_domain_name": "example.com" } } }, "examples": { "success-059b23349188cf119cf743bb747b3d19": { "summary": "Success-Response", "value": { "message": "OK", "data": { "job_id": 1234, "wpcom_blog_id": 3456, "atomic_site_id": 5678, "domain_name": "updated-example.com", "old_domain_name": "example.com" } } } } } } }, "400": { "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message." }, "data": { "description": "Error details, or an empty array when none are returned." } } } } }, "description": "Missing domain name or invalid domain." }, "403": { "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message." }, "data": { "description": "Error details, or an empty array when none are returned." } } } } }, "description": "Access denied." }, "404": { "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message." }, "data": { "description": "Error details, or an empty array when none are returned." } } } } }, "description": "Site not found." } }, "parameters": [ { "name": "service", "in": "path", "description": "Service type; may be client name or \"domain\". Used to determine site lookup method; use \"domain\" to look up a site by domain, otherwise use the client identifier to look up a site by site ID.", "required": true, "schema": { "type": "string" } }, { "name": "identifier", "in": "path", "description": "Site identifier; domain name for \"domain\" lookups,. otherwise the site ID.", "required": true, "schema": { "type": "string" } }, { "name": "domain", "in": "path", "description": "New primary domain name.", "required": true, "schema": { "type": "string" } }, { "name": "keep", "in": "path", "description": "Old domain retention flag. The old primary domain is kept as an alias by default; pass \"false\" to remove it instead of keeping it as an alias.", "required": true, "schema": { "type": "string" } } ], "operationId": "post-update-site-domain-service-identifier-domain-keep" } }, "/update-site-options/{type}/{site}": { "post": { "tags": [ "Sites" ], "summary": "Update Site Options", "description": "Update a site's WordPress options.", "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Response status message." }, "data": { "type": "object", "description": "Response object.", "properties": { "job_id": { "type": "number", "description": "WordPress.com job ID for updating site options." }, "atomic_site_id": { "type": "number", "description": "Site ID." } } } }, "example": { "message": "OK", "data": { "job_id": 1234, "atomic_site_id": 5678 } } }, "examples": { "success-ddfa23c260767f66565c2cfc8a6322c9": { "summary": "Success-Response", "value": { "message": "OK", "data": { "job_id": 1234, "atomic_site_id": 5678 } } } } } } }, "400": { "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message." }, "data": { "description": "Error details, or an empty array when none are returned." } } } } }, "description": "Invalid service type or missing options parameter." }, "403": { "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message." }, "data": { "description": "Error details, or an empty array when none are returned." } } } } }, "description": "Access denied." }, "404": { "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message." }, "data": { "description": "Error details, or an empty array when none are returned." } } } } }, "description": "Site not found." }, "500": { "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message." }, "data": { "description": "Error details, or an empty array when none are returned." } } } } }, "description": "Unable to find primary server for site's pool." } }, "parameters": [ { "name": "type", "in": "path", "description": "Service type (\"atomic\" for external clients, \"wpcom\" for WordPress.com).", "required": true, "schema": { "type": "string", "enum": [ "atomic", "wpcom" ] } }, { "name": "site", "in": "path", "description": "Site ID or domain name (for \"atomic\") or WordPress.com blog ID (for \"wpcom\").", "required": true, "schema": { "oneOf": [ { "type": "string" }, { "type": "number" } ] } } ], "operationId": "post-update-site-options-type-site", "requestBody": { "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "properties": { "options": { "type": "object", "description": "Options object with two possible keys: `patch` and `set`. `patch` is an array where each entry is the name of an option to patch (the key) and an array of key/value pairs (the value) specifying what parts should be patched. `set` is an array containing name/value pairs of options to set." } }, "required": [ "options" ] } } } } } }, "/ssh-user/{service}/{identifier}/update/{username}": { "post": { "tags": [ "SSH" ], "summary": "Update Site SSH/SFTP User", "description": "Update password or SSH key for an existing SSH/SFTP user. Empty password string disables password authentication (key-only). Allowed key types: ssh-rsa (2048-16384 bits), ecdsa-sha2-nistp256 (256 bits), ssh-ed25519 (256 bits).", "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Response status message." }, "data": { "type": "object", "description": "Updated credential summary.", "properties": { "user": { "type": "string", "description": "Username." }, "pass": { "type": "string", "description": "New plaintext password (only present when a password was updated)." }, "pkey": { "type": "boolean", "description": "Whether the SSH public key was stored successfully (only present when a key was updated)." } } } } } } } }, "400": { "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message." }, "data": { "description": "Error details, or an empty array when none are returned." } } } } }, "description": "Invalid site, service type, username, or SSH key format. Also returned when neither pass nor pkey is provided." }, "404": { "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message." }, "data": { "description": "Error details, or an empty array when none are returned." } } } } }, "description": "Username not found for this site." }, "500": { "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message." }, "data": { "description": "Error details, or an empty array when none are returned." } } } } }, "description": "Database error." } }, "parameters": [ { "name": "service", "in": "path", "description": "Service type (client name, \"domain\" for domain lookup, or \"wpcom\" for WordPress.com blog ID).", "required": true, "schema": { "type": "string" } }, { "name": "identifier", "in": "path", "description": "Site identifier (domain for \"domain\" service, site ID for client, WordPress.com blog ID for \"wpcom\").", "required": true, "schema": { "type": "string" } }, { "name": "username", "in": "path", "description": "Username to update.", "required": true, "schema": { "type": "string" } } ], "operationId": "post-ssh-user-service-identifier-update-username", "requestBody": { "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "properties": { "pkey": { "type": "string", "description": "SSH public key (authorized_keys format)." }, "pass": { "type": "string", "description": "Password (empty string to disable password auth, or a specific password)." }, "allow-disable-password": { "type": "string", "enum": [ "true" ], "description": "Reserved for future use; currently accepted but has no effect on behavior." } } } } } } } }, "/site-wordpress-version/{site}/{version}": { "post": { "tags": [ "Sites" ], "summary": "Update Site WordPress Version", "description": "Configure a site to use a specific managed version of WordPress.", "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "job_id": { "type": "number", "description": "Queued job ID." } } } } } } } }, "400": { "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message." }, "data": { "description": "Error details, or an empty array when none are returned." } } } } }, "description": "Invalid version value." }, "403": { "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message." }, "data": { "description": "Error details, or an empty array when none are returned." } } } } }, "description": "Access denied." }, "404": { "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message." }, "data": { "description": "Error details, or an empty array when none are returned." } } } } }, "description": "Site not found." }, "500": { "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message." }, "data": { "description": "Error details, or an empty array when none are returned." } } } } }, "description": "Database error." } }, "parameters": [ { "name": "site", "in": "path", "description": "Site ID or domain.", "required": true, "schema": { "type": "string" } }, { "name": "version", "in": "path", "description": "WordPress version to use.", "required": true, "schema": { "type": "string", "enum": [ "latest", "previous", "beta", "alpha" ] } } ], "operationId": "post-site-wordpress-version-site-version" } }, "/custom-certificates/{site}/validate": { "post": { "tags": [ "Custom SSL Certificates" ], "summary": "Validate Custom Certificate", "description": "Validate a custom SSL certificate for use on one or more domains.", "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Response status message." }, "data": { "type": "object", "description": "Validation result.", "properties": { "valid": { "type": "boolean", "description": "Whether the certificate passed all validations." }, "errors": { "type": "array", "items": { "type": "string" }, "description": "Validation error messages, if any." }, "warnings": { "type": "array", "items": { "type": "string" }, "description": "Validation warning messages, if any." }, "validations": { "type": "object", "description": "Per-check validation results, keyed by check name." } } } }, "example": { "message": "OK", "data": { "valid": true, "errors": [], "warnings": [ "Certificate expires in 25.3 days (2025-12-05 10:30:00 UTC)" ], "validations": { "pem_format_certificate": { "passed": true }, "pem_format_private_key": { "passed": true }, "pem_format_csr": { "passed": true }, "crypto_match": { "passed": true }, "domain_coverage": { "passed": true }, "chain_trust": { "passed": true }, "certificate_cn": { "passed": true }, "owner_domain": { "passed": true } } } } }, "examples": { "success-3bffe15eeee2319cc43c474922053234": { "summary": "Success-Response (valid certificate)", "value": { "message": "OK", "data": { "valid": true, "errors": [], "warnings": [ "Certificate expires in 25.3 days (2025-12-05 10:30:00 UTC)" ], "validations": { "pem_format_certificate": { "passed": true }, "pem_format_private_key": { "passed": true }, "pem_format_csr": { "passed": true }, "crypto_match": { "passed": true }, "domain_coverage": { "passed": true }, "chain_trust": { "passed": true }, "certificate_cn": { "passed": true }, "owner_domain": { "passed": true } } } } }, "success-302ad39638b1494b592c2ff4c66d047b": { "summary": "Success-Response (invalid certificate)", "value": { "message": "Validation failed", "data": { "valid": false, "errors": [ "Private key does not match certificate/CSR", "Certificate does not cover all requested domains or is expired" ], "warnings": [], "validations": { "pem_format_certificate": { "passed": true }, "pem_format_private_key": { "passed": true }, "pem_format_csr": { "passed": true }, "crypto_match": { "passed": false, "error": "Private key does not match certificate/CSR" }, "domain_coverage": { "passed": false, "error": "Certificate does not cover all requested domains or is expired" } } } } } } } } }, "400": { "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message." }, "data": { "description": "Error details, or an empty array when none are returned." } } } } }, "description": "Invalid site identifier or missing required fields." }, "403": { "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message." }, "data": { "description": "Error details, or an empty array when none are returned." } } } } }, "description": "Access denied." }, "500": { "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message." }, "data": { "description": "Error details, or an empty array when none are returned." } } } } }, "description": "ACME API error." } }, "parameters": [ { "name": "site", "in": "path", "description": "Site ID or domain.", "required": true, "schema": { "type": "string" } } ], "operationId": "post-custom-certificates-site-validate", "requestBody": { "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "properties": { "domains": { "type": "array", "items": { "type": "string" }, "description": "Optional list of domains to validate the certificate for. If omitted the site's primary domain is used." }, "certificate": { "type": "string", "description": "PEM-encoded SSL certificate, or certificate chain." }, "private_key": { "type": "string", "description": "PEM-encoded private key corresponding to the certificate." }, "csr": { "type": "string", "description": "PEM-encoded Certificate Signing Request." }, "trusted_certificates": { "type": "string", "description": "PEM-encoded trusted CA certificates if not included in the certificate chain." }, "client_certificate": { "type": "string", "description": "PEM-encoded client certificate, if required for mTLS." } }, "required": [ "certificate", "private_key" ] } } } } } }, "/check-can-host-domain/{client}/{domain}": { "get": { "tags": [ "Sites" ], "summary": "Validate Domain Eligibility", "description": "Check whether a domain can be hosted on WP Cloud. Note that this check will return false for valid domains that are already hosted on WordPress.com or WP Cloud infrastructure.", "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Response status message." }, "data": { "type": "object", "description": "Response object.", "properties": { "allowed": { "type": "boolean", "description": "Whether the domain can be hosted." } } } }, "example": { "message": "OK", "data": { "allowed": true } } }, "examples": { "success-5246864ce9d26821f5be78e6e4157e15": { "summary": "Success-Response", "value": { "message": "OK", "data": { "allowed": true } } } } } } }, "400": { "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message." }, "data": { "description": "Error details, or an empty array when none are returned." } } } } }, "description": "Invalid or unauthorized client, or domain already in use." } }, "parameters": [ { "name": "client", "in": "path", "description": "Client identifier.", "required": true, "schema": { "type": "string" } }, { "name": "domain", "in": "path", "description": "Domain name in question.", "required": true, "schema": { "type": "string" } } ], "operationId": "get-check-can-host-domain-client-domain" } } }, "components": { "securitySchemes": { "ApiKeyAuth": { "type": "apiKey", "in": "header", "name": "auth" } } }, "security": [ { "ApiKeyAuth": [] } ], "tags": [ { "name": "Backups" }, { "name": "Client Meta" }, { "name": "Cron" }, { "name": "Custom SSL Certificates" }, { "name": "Edge Cache" }, { "name": "Email" }, { "name": "Jobs" }, { "name": "Logs" }, { "name": "Metrics" }, { "name": "Migrations" }, { "name": "Response Tickets" }, { "name": "SSH" }, { "name": "Security" }, { "name": "Servers" }, { "name": "Sites" }, { "name": "Tasks" }, { "name": "Usage" }, { "name": "Utility" }, { "name": "Webhooks" } ] }