{ "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": { "/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": { "BadRequest": { "type": "string", "description": "Invalid site identifier or missing certificate ID." } } } } }, "description": "Invalid site identifier or missing certificate ID." }, "403": { "content": { "application/json": { "schema": { "type": "object", "properties": { "Forbidden": { "type": "string", "description": "Access denied." } } } } }, "description": "Access denied." }, "404": { "content": { "application/json": { "schema": { "type": "object", "properties": { "NotFound": { "type": "string", "description": "Certificate not found." } } } } }, "description": "Certificate not found." }, "500": { "content": { "application/json": { "schema": { "type": "object", "properties": { "InternalServerError": { "type": "string", "description": "ACME API error." } } } } }, "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": { "InvalidKey": { "type": "string", "description": "Invalid or unsupported meta key." }, "MissingValue": { "type": "string", "description": "A value must be provided." }, "InvalidWebhookURL": { "type": "string", "description": "Invalid URL provided for webhook_url." }, "InvalidPrivacyModel": { "type": "string", "description": "Invalid value for default_privacy_model; must be \"wp_uploads\" or \"proxy\"." } }, "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." }, "403": { "content": { "application/json": { "schema": { "type": "object", "properties": { "Forbidden": { "type": "string", "description": "Access denied or method not allowed for this key." } } } } }, "description": "Access denied or method not allowed for this key." }, "500": { "content": { "application/json": { "schema": { "type": "object", "properties": { "InternalServerError": { "type": "string", "description": "Internal server error." } } } } }, "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": { "BadRequest": { "type": "string", "description": "Invalid or empty schedule or command, or schedule could not be parsed." } } } } }, "description": "Invalid or empty schedule or command, or schedule could not be parsed." }, "403": { "content": { "application/json": { "schema": { "type": "object", "properties": { "Forbidden": { "type": "string", "description": "Access denied." } } } } }, "description": "Access denied." }, "404": { "content": { "application/json": { "schema": { "type": "object", "properties": { "NotFound": { "type": "string", "description": "Site not found." } } } } }, "description": "Site not found." }, "500": { "content": { "application/json": { "schema": { "type": "object", "properties": { "InternalServerError": { "type": "string", "description": "Database error." } } } } }, "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": { "BadRequest": { "type": "string", "description": "Invalid or missing rule fields, or rule limit (128) exceeded." } } } } }, "description": "Invalid or missing rule fields, or rule limit (128) exceeded." }, "403": { "content": { "application/json": { "schema": { "type": "object", "properties": { "Forbidden": { "type": "string", "description": "Access denied." } } } } }, "description": "Access denied." }, "404": { "content": { "application/json": { "schema": { "type": "object", "properties": { "NotFound": { "type": "string", "description": "Site not found." } }, "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": { "Conflict": { "type": "string", "description": "This rule already exists or conflicts with another rule." } } } } }, "description": "This rule already exists or conflicts with another rule." }, "500": { "content": { "application/json": { "schema": { "type": "object", "properties": { "InternalServerError": { "type": "string", "description": "Database error." } } } } }, "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": { "BadRequest": { "type": "string", "description": "The data field is not a valid array." } } } } }, "description": "The data field is not a valid array." }, "404": { "content": { "application/json": { "schema": { "type": "object", "properties": { "NotFound": { "type": "string", "description": "Site not found." } } } } }, "description": "Site not found." }, "429": { "content": { "application/json": { "schema": { "type": "object", "properties": { "TooManyRequests": { "type": "string", "description": "Site data lock could not be acquired; retry after the Retry-After header value (10 seconds)." } } } } }, "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": { "BadRequest": { "type": "string", "description": "Invalid site, service type, username, or SSH key format." } } } } }, "description": "Invalid site, service type, username, or SSH key format." }, "409": { "content": { "application/json": { "schema": { "type": "object", "properties": { "UsernameExists": { "type": "string", "description": "Username already exists for this site." } } } } }, "description": "Username already exists for this site." }, "500": { "content": { "application/json": { "schema": { "type": "object", "properties": { "InternalServerError": { "type": "string", "description": "Database error." } } } } }, "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": { "Forbidden": { "type": "string", "description": "Access denied." } } } } }, "description": "Access denied." }, "404": { "content": { "application/json": { "schema": { "type": "object", "properties": { "NotFound": { "type": "string", "description": "Site not found." } } } } }, "description": "Site not found." }, "500": { "content": { "application/json": { "schema": { "type": "object", "properties": { "InternalServerError": { "type": "string", "description": "Database error." } } } } }, "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": { "BadRequest": { "type": "string", "description": "Missing or invalid site/timestamp parameter, or timestamp is in the past or exceeds 1 week." } } } } }, "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": { "Forbidden": { "type": "string", "description": "Access denied." } } } } }, "description": "Access denied." }, "404": { "content": { "application/json": { "schema": { "type": "object", "properties": { "NotFound": { "type": "string", "description": "Domain not found." } } } } }, "description": "Domain not found." }, "500": { "content": { "application/json": { "schema": { "type": "object", "properties": { "InternalServerError": { "type": "string", "description": "Failed to enable or disable Defensive Mode." } } } } }, "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": { "BadRequest": { "type": "string", "description": "Missing or invalid site parameter." } } } } }, "description": "Missing or invalid site parameter." }, "403": { "content": { "application/json": { "schema": { "type": "object", "properties": { "Forbidden": { "type": "string", "description": "Access denied." } } } } }, "description": "Access denied." }, "404": { "content": { "application/json": { "schema": { "type": "object", "properties": { "NotFound": { "type": "string", "description": "Domain not found." } } } } }, "description": "Domain not found." }, "500": { "content": { "application/json": { "schema": { "type": "object", "properties": { "InternalServerError": { "type": "string", "description": "Failed to check Defensive Mode." } } } } }, "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": { "BadRequest": { "type": "string", "description": "Missing or invalid site/timestamp parameter, or timestamp is in the past or exceeds 1 week." } } } } }, "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": { "Forbidden": { "type": "string", "description": "Access denied." } } } } }, "description": "Access denied." }, "404": { "content": { "application/json": { "schema": { "type": "object", "properties": { "NotFound": { "type": "string", "description": "Domain not found." } } } } }, "description": "Domain not found." }, "500": { "content": { "application/json": { "schema": { "type": "object", "properties": { "InternalServerError": { "type": "string", "description": "Failed to enable or disable Defensive Mode." } } } } }, "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": { "BadRequest": { "type": "string", "description": "Missing or invalid site parameter." } } } } }, "description": "Missing or invalid site parameter." }, "403": { "content": { "application/json": { "schema": { "type": "object", "properties": { "Forbidden": { "type": "string", "description": "Access denied." } } } } }, "description": "Access denied." }, "404": { "content": { "application/json": { "schema": { "type": "object", "properties": { "NotFound": { "type": "string", "description": "Domain not found." } } } } }, "description": "Domain not found." }, "500": { "content": { "application/json": { "schema": { "type": "object", "properties": { "InternalServerError": { "type": "string", "description": "Failed to check Defensive Mode." } } } } }, "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": { "BadRequest": { "type": "string", "description": "Invalid or mismatched charset values, or could not obtain site lock." } } } } }, "description": "Invalid or mismatched charset values, or could not obtain site lock." }, "404": { "content": { "application/json": { "schema": { "type": "object", "properties": { "NotFound": { "type": "string", "description": "Site not found." } } } } }, "description": "Site not found." }, "423": { "content": { "application/json": { "schema": { "type": "object", "properties": { "Locked": { "type": "string", "description": "Site is already locked." } } } } }, "description": "Site is already locked." }, "500": { "content": { "application/json": { "schema": { "type": "object", "properties": { "InternalServerError": { "type": "string", "description": "No server found for site." } } } } }, "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" } }, "/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": { "BadRequest": { "type": "string", "description": "Missing or invalid `pkey` body parameter." } } } } }, "description": "Missing or invalid `pkey` body parameter." }, "403": { "content": { "application/json": { "schema": { "type": "object", "properties": { "Forbidden": { "type": "string", "description": "Access denied." } } } } }, "description": "Access denied." }, "500": { "content": { "application/json": { "schema": { "type": "object", "properties": { "InternalServerError": { "type": "string", "description": "Database error; data contains the error message." } } } } }, "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": { "BadRequest": { "type": "string", "description": "Missing or invalid parameter (e.g. missing admin_user, invalid domain, unsupported arg during restore_from)." } }, "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": { "Forbidden": { "type": "string", "description": "Access denied: invalid client, or cloning not available for the source site." } } } } }, "description": "Access denied: invalid client, or cloning not available for the source site." }, "404": { "content": { "application/json": { "schema": { "type": "object", "properties": { "NotFound": { "type": "string", "description": "Backup record not found." } } } } }, "description": "Backup record not found." }, "405": { "content": { "application/json": { "schema": { "type": "object", "properties": { "MethodNotAllowed": { "type": "string", "description": "Request method is not POST." } } } } }, "description": "Request method is not POST." }, "409": { "content": { "application/json": { "schema": { "type": "object", "properties": { "Conflict": { "type": "string", "description": "Duplicate domain name, or backup restore conflict (mismatched site or backup type)." } } } } }, "description": "Duplicate domain name, or backup restore conflict (mismatched site or backup type)." }, "421": { "content": { "application/json": { "schema": { "type": "object", "properties": { "MisdirectedRequest": { "type": "string", "description": "Requested domain is currently being provisioned on another site; retry later." } } } } }, "description": "Requested domain is currently being provisioned on another site; retry later." }, "423": { "content": { "application/json": { "schema": { "type": "object", "properties": { "Locked": { "type": "string", "description": "Source site is already locked (clone in progress)." } } } } }, "description": "Source site is already locked (clone in progress)." }, "500": { "content": { "application/json": { "schema": { "type": "object", "properties": { "InternalServerError": { "type": "string", "description": "Unexpected server error." } } } } }, "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" ], "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." }, "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": { "BadRequest": { "type": "string", "description": "Missing or invalid client, type, or task parameters." } } } } }, "description": "Missing or invalid client, type, or task parameters." }, "409": { "content": { "application/json": { "schema": { "type": "object", "properties": { "Conflict": { "type": "string", "description": "An in-progress task already exists for this client." } } } } }, "description": "An in-progress task already exists for this client." }, "500": { "content": { "application/json": { "schema": { "type": "object", "properties": { "InternalServerError": { "type": "string", "description": "Failed to create the task." } } } } }, "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": { "BadRequest": { "type": "string", "description": "Invalid site identifier." } } } } }, "description": "Invalid site identifier." }, "403": { "content": { "application/json": { "schema": { "type": "object", "properties": { "Forbidden": { "type": "string", "description": "Access denied." } } } } }, "description": "Access denied." }, "404": { "content": { "application/json": { "schema": { "type": "object", "properties": { "NotFound": { "type": "string", "description": "Certificate not found." } } } } }, "description": "Certificate not found." }, "500": { "content": { "application/json": { "schema": { "type": "object", "properties": { "InternalServerError": { "type": "string", "description": "ACME API error." } } } } }, "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": { "BadRequest": { "type": "string", "description": "Invalid site identifier or missing certificate ID." } } } } }, "description": "Invalid site identifier or missing certificate ID." }, "403": { "content": { "application/json": { "schema": { "type": "object", "properties": { "Forbidden": { "type": "string", "description": "Access denied." } } } } }, "description": "Access denied." }, "404": { "content": { "application/json": { "schema": { "type": "object", "properties": { "NotFound": { "type": "string", "description": "Certificate not found." } } } } }, "description": "Certificate not found." }, "500": { "content": { "application/json": { "schema": { "type": "object", "properties": { "InternalServerError": { "type": "string", "description": "ACME API error." } } } } }, "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": { "BadRequest": { "type": "string", "description": "Site has do_not_delete set, or duplicate delete request." } } } } }, "description": "Site has do_not_delete set, or duplicate delete request." }, "403": { "content": { "application/json": { "schema": { "type": "object", "properties": { "Forbidden": { "type": "string", "description": "Access denied." } } } } }, "description": "Access denied." }, "404": { "content": { "application/json": { "schema": { "type": "object", "properties": { "NotFound": { "type": "string", "description": "Site not found." } } } } }, "description": "Site not found." }, "412": { "content": { "application/json": { "schema": { "type": "object", "properties": { "PreconditionFailed": { "type": "string", "description": "On-demand backups exist; delete them first." } } } } }, "description": "On-demand backups exist; delete them first." }, "423": { "content": { "application/json": { "schema": { "type": "object", "properties": { "Locked": { "type": "string", "description": "Site is already locked." } } } } }, "description": "Site is already locked." }, "500": { "content": { "application/json": { "schema": { "type": "object", "properties": { "InternalServerError": { "type": "string", "description": "Unable to find primary server for site's pool." } } } } }, "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": { "BadRequest": { "type": "string", "description": "Preload directive can only be disabled." } } } } }, "description": "Preload directive can only be disabled." }, "403": { "content": { "application/json": { "schema": { "type": "object", "properties": { "Forbidden": { "type": "string", "description": "Access denied." } } } } }, "description": "Access denied." }, "404": { "content": { "application/json": { "schema": { "type": "object", "properties": { "NotFound": { "type": "string", "description": "Site not found." } } } } }, "description": "Site not found." }, "500": { "content": { "application/json": { "schema": { "type": "object", "properties": { "InternalServerError": { "type": "string", "description": "Error communicating with SSL backend." } } } } }, "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": { "Forbidden": { "type": "string", "description": "Access denied." } } } } }, "description": "Access denied." }, "404": { "content": { "application/json": { "schema": { "type": "object", "properties": { "NotFound": { "type": "string", "description": "Site not found." } } } } }, "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": { "BadRequest": { "type": "string", "description": "Invalid or unauthorized client." } } } } }, "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-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": { "BadRequest": { "type": "string", "description": "Invalid or unauthorized client." } } } } }, "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": { "BadRequest": { "type": "string", "description": "Invalid or unauthorized client." } } } } }, "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": { "InvalidKey": { "type": "string", "description": "Invalid or unsupported meta key." } }, "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": { "Forbidden": { "type": "string", "description": "Access denied or method not allowed for this key." } } } } }, "description": "Access denied or method not allowed for this key." }, "404": { "content": { "application/json": { "schema": { "type": "object", "properties": { "NotFound": { "type": "string", "description": "Meta key not found for this client." } }, "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": { "InternalServerError": { "type": "string", "description": "Internal server error." } } } } }, "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": { "BadRequest": { "type": "string", "description": "Invalid site identifier." } } } } }, "description": "Invalid site identifier." }, "403": { "content": { "application/json": { "schema": { "type": "object", "properties": { "Forbidden": { "type": "string", "description": "Access denied." } } } } }, "description": "Access denied." }, "404": { "content": { "application/json": { "schema": { "type": "object", "properties": { "NotFound": { "type": "string", "description": "Certificate not found for the site." } } } } }, "description": "Certificate not found for the site." }, "500": { "content": { "application/json": { "schema": { "type": "object", "properties": { "InternalServerError": { "type": "string", "description": "ACME API error." } } } } }, "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": { "BadRequest": { "type": "string", "description": "Invalid site identifier." } } } } }, "description": "Invalid site identifier." }, "403": { "content": { "application/json": { "schema": { "type": "object", "properties": { "Forbidden": { "type": "string", "description": "Access denied." } } } } }, "description": "Access denied." }, "404": { "content": { "application/json": { "schema": { "type": "object", "properties": { "NotFound": { "type": "string", "description": "Certificate not found for the site." } } } } }, "description": "Certificate not found for the site." }, "500": { "content": { "application/json": { "schema": { "type": "object", "properties": { "InternalServerError": { "type": "string", "description": "ACME API error." } } } } }, "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": { "BadRequest": { "type": "string", "description": "Invalid or unauthorized client, or missing domain name." } }, "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": { "BadRequest": { "type": "string", "description": "Invalid action." } } } } }, "description": "Invalid action." }, "403": { "content": { "application/json": { "schema": { "type": "object", "properties": { "Forbidden": { "type": "string", "description": "Access denied." } } } } }, "description": "Access denied." }, "404": { "content": { "application/json": { "schema": { "type": "object", "properties": { "NotFound": { "type": "string", "description": "Site not found." } } } } }, "description": "Site not found." }, "405": { "content": { "application/json": { "schema": { "type": "object", "properties": { "MethodNotAllowed": { "type": "string", "description": "Request method must be GET or POST." } } } } }, "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": { "BadRequest": { "type": "string", "description": "Invalid action." } } } } }, "description": "Invalid action." }, "403": { "content": { "application/json": { "schema": { "type": "object", "properties": { "Forbidden": { "type": "string", "description": "Access denied." } } } } }, "description": "Access denied." }, "404": { "content": { "application/json": { "schema": { "type": "object", "properties": { "NotFound": { "type": "string", "description": "Site not found." } } } } }, "description": "Site not found." }, "405": { "content": { "application/json": { "schema": { "type": "object", "properties": { "MethodNotAllowed": { "type": "string", "description": "Request method must be GET or POST." } } } } }, "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": { "BadRequest": { "type": "string", "description": "Invalid action or invalid purge URIs." } } } } }, "description": "Invalid action or invalid purge URIs." }, "403": { "content": { "application/json": { "schema": { "type": "object", "properties": { "Forbidden": { "type": "string", "description": "Access denied." } } } } }, "description": "Access denied." }, "404": { "content": { "application/json": { "schema": { "type": "object", "properties": { "NotFound": { "type": "string", "description": "Site not found." } } } } }, "description": "Site not found." }, "405": { "content": { "application/json": { "schema": { "type": "object", "properties": { "MethodNotAllowed": { "type": "string", "description": "Request method must be GET or POST." } } } } }, "description": "Request method must be GET or POST." }, "500": { "content": { "application/json": { "schema": { "type": "object", "properties": { "InternalServerError": { "type": "string", "description": "Edge cache update or purge failed." } } } } }, "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": { "BadRequest": { "type": "string", "description": "Invalid action." } } } } }, "description": "Invalid action." }, "403": { "content": { "application/json": { "schema": { "type": "object", "properties": { "Forbidden": { "type": "string", "description": "Access denied." } } } } }, "description": "Access denied." }, "404": { "content": { "application/json": { "schema": { "type": "object", "properties": { "NotFound": { "type": "string", "description": "Site not found." } } } } }, "description": "Site not found." }, "405": { "content": { "application/json": { "schema": { "type": "object", "properties": { "MethodNotAllowed": { "type": "string", "description": "Request method must be GET or POST." } } } } }, "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": { "BadRequest": { "type": "string", "description": "Invalid action or invalid purge URIs." } } } } }, "description": "Invalid action or invalid purge URIs." }, "403": { "content": { "application/json": { "schema": { "type": "object", "properties": { "Forbidden": { "type": "string", "description": "Access denied." } } } } }, "description": "Access denied." }, "404": { "content": { "application/json": { "schema": { "type": "object", "properties": { "NotFound": { "type": "string", "description": "Site not found." } } } } }, "description": "Site not found." }, "405": { "content": { "application/json": { "schema": { "type": "object", "properties": { "MethodNotAllowed": { "type": "string", "description": "Request method must be GET or POST." } } } } }, "description": "Request method must be GET or POST." }, "500": { "content": { "application/json": { "schema": { "type": "object", "properties": { "InternalServerError": { "type": "string", "description": "Edge cache update or purge failed." } } } } }, "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." } } } } } } } }, "/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": { "BadRequest": { "type": "string", "description": "Job ID is not a valid integer (GET only)." } } } } }, "description": "Job ID is not a valid integer (GET only)." }, "404": { "content": { "application/json": { "schema": { "type": "object", "properties": { "NotFound": { "type": "string", "description": "Job not found (GET only)." } } } } }, "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": { "BadRequest": { "type": "string", "description": "Job ID is not a valid integer (GET only)." } } } } }, "description": "Job ID is not a valid integer (GET only)." }, "404": { "content": { "application/json": { "schema": { "type": "object", "properties": { "NotFound": { "type": "string", "description": "Job not found (GET only)." } } } } }, "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." } }, "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": { "BadRequest": { "type": "string", "description": "Job ID is not a valid integer (GET only)." } } } } }, "description": "Job ID is not a valid integer (GET only)." }, "404": { "content": { "application/json": { "schema": { "type": "object", "properties": { "NotFound": { "type": "string", "description": "Job not found (GET only)." } } } } }, "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." } }, "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": { "BadRequest": { "type": "string", "description": "Job ID is not a valid integer (GET only)." } } } } }, "description": "Job ID is not a valid integer (GET only)." }, "404": { "content": { "application/json": { "schema": { "type": "object", "properties": { "NotFound": { "type": "string", "description": "Job not found (GET only)." } } } } }, "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." } }, "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": { "BadRequest": { "type": "string", "description": "Job ID is not a valid integer (GET only)." } } } } }, "description": "Job ID is not a valid integer (GET only)." }, "404": { "content": { "application/json": { "schema": { "type": "object", "properties": { "NotFound": { "type": "string", "description": "Job not found (GET only)." } } } } }, "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." } }, "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": { "BadRequest": { "type": "string", "description": "Job ID is not a valid integer (GET only)." } } } } }, "description": "Job ID is not a valid integer (GET only)." }, "404": { "content": { "application/json": { "schema": { "type": "object", "properties": { "NotFound": { "type": "string", "description": "Job not found (GET only)." } } } } }, "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." } } } } } } } }, "/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": { "BadRequest": { "type": "string", "description": "Access not authorized for this extended endpoint." } } } } }, "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." } } } } } } } }, "/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": { "BadRequest": { "type": "string", "description": "Invalid or unauthorized client." } } } } }, "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": { "Forbidden": { "type": "string", "description": "Access denied." } } } } }, "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" }, "description": "Array of response messages.", "properties": { "created": { "type": "string", "description": "Message creation timestamp." }, "created_ts": { "type": "number", "description": "Message creation timestamp (Unix)." }, "message": { "type": "string", "description": "Response message content." } } } } } } } } } }, "400": { "content": { "application/json": { "schema": { "type": "object", "properties": { "BadRequest": { "type": "string", "description": "Missing response-ticket-id." } } } } }, "description": "Missing response-ticket-id." }, "202": { "content": { "application/json": { "schema": { "type": "object", "properties": { "Accepted": { "type": "string", "description": "Ticket has not yet received a response; retry after 1 second." } } } } }, "description": "Ticket has not yet received a response; retry after 1 second." }, "404": { "content": { "application/json": { "schema": { "type": "object", "properties": { "NotFound": { "type": "string", "description": "Ticket not found." } } } } }, "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": { "BadRequest": { "type": "string", "description": "Missing response-ticket-id." } } } } }, "description": "Missing response-ticket-id." }, "202": { "content": { "application/json": { "schema": { "type": "object", "properties": { "Accepted": { "type": "string", "description": "Ticket has not yet received a response; retry after 1 second." } } } } }, "description": "Ticket has not yet received a response; retry after 1 second." }, "404": { "content": { "application/json": { "schema": { "type": "object", "properties": { "NotFound": { "type": "string", "description": "Ticket not found (and old enough to have been deleted)." } } } } }, "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": { "BadRequest": { "type": "string", "description": "Invalid service identifier or unknown site." } } } } }, "description": "Invalid service identifier or unknown site." }, "404": { "content": { "application/json": { "schema": { "type": "object", "properties": { "NotFound": { "type": "string", "description": "Backup not found." } }, "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": { "BadRequest": { "type": "string", "description": "Invalid service identifier, backup ID, or unknown site." } } } } }, "description": "Invalid service identifier, backup ID, or unknown site." }, "404": { "content": { "application/json": { "schema": { "type": "object", "properties": { "NotFound": { "type": "string", "description": "Backup not found." } } } } }, "description": "Backup not found." }, "500": { "content": { "application/json": { "schema": { "type": "object", "properties": { "InternalError": { "type": "string", "description": "Database query failed." } } } } }, "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\", or \"beta\")." }, "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)." }, "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": { "Forbidden": { "type": "string", "description": "Access denied." } } } } }, "description": "Access denied." }, "404": { "content": { "application/json": { "schema": { "type": "object", "properties": { "NotFound": { "type": "string", "description": "Site not found." } } } } }, "description": "Site not found." }, "500": { "content": { "application/json": { "schema": { "type": "object", "properties": { "InternalServerError": { "type": "string", "description": "Internal server error." } } } } }, "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": { "BadRequest": { "type": "string", "description": "Invalid parameter." } } } } }, "description": "Invalid parameter." }, "403": { "content": { "application/json": { "schema": { "type": "object", "properties": { "Forbidden": { "type": "string", "description": "Access denied." } } } } }, "description": "Access denied." }, "404": { "content": { "application/json": { "schema": { "type": "object", "properties": { "NotFound": { "type": "string", "description": "Site not found." } } } } }, "description": "Site not found." }, "500": { "content": { "application/json": { "schema": { "type": "object", "properties": { "InternalServerError": { "type": "string", "description": "Failed to connect to or query metrics data source." } } } } }, "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-error-logs/{site}": { "post": { "tags": [ "Logs" ], "summary": "Get Site PHP Error Logs", "description": "Get PHP error log data from a site. Logs are only guaranteed for 28 days; a start timestamp before that may return incomplete data.", "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "total_results": { "type": "number", "description": "Total number of matching log entries; may be null if unavailable." }, "logs": { "type": "array", "items": { "type": "object" }, "description": "Array of log entry objects.", "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": { "type": "string", "description": "Line number where the error occurred." }, "timestamp": { "type": "string", "description": "ISO 8601 timestamp of the log entry." }, "atomic_site_id": { "type": "number", "description": "Numeric site ID." } } }, "scroll_id": { "type": "string", "description": "Opaque cursor to pass as scroll_id to retrieve the next page; null when no more results are available." } } } }, "example": { "message": "OK", "data": { "total_results": 1243, "logs": [ { "message": "PHP Parse error: syntax error, unexpected", "severity": "Fatal error", "kind": "", "name": "", "file": "/var/www/html/wp-content/themes/example/functions.php", "line": "42", "timestamp": "2020-11-24T13:20:13.000Z", "atomic_site_id": 123456 } ], "scroll_id": "scroll-id-string" } } }, "examples": { "success-742a92036a34826a171eeb6db824865e": { "summary": "Success-Response", "value": { "message": "OK", "data": { "total_results": 1243, "logs": [ { "message": "PHP Parse error: syntax error, unexpected", "severity": "Fatal error", "kind": "", "name": "", "file": "/var/www/html/wp-content/themes/example/functions.php", "line": "42", "timestamp": "2020-11-24T13:20:13.000Z", "atomic_site_id": 123456 } ], "scroll_id": "scroll-id-string" } } } } } } }, "400": { "content": { "application/json": { "schema": { "type": "object", "properties": { "BadRequest": { "type": "string", "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." } } } } }, "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": { "Forbidden": { "type": "string", "description": "Access denied." } } } } }, "description": "Access denied." }, "404": { "content": { "application/json": { "schema": { "type": "object", "properties": { "NotFound": { "type": "string", "description": "Site not found." } } } } }, "description": "Site not found." }, "500": { "content": { "application/json": { "schema": { "type": "object", "properties": { "InternalServerError": { "type": "string", "description": "Search backend error." } } } } }, "description": "Search backend error." } }, "parameters": [ { "name": "site", "in": "path", "description": "Site ID or domain.", "required": true, "schema": { "type": "string" } } ], "operationId": "post-site-error-logs-site", "requestBody": { "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "properties": { "start": { "oneOf": [ { "type": "number" }, { "type": "string" } ], "description": "Start of the log data range. Accepts a Unix timestamp or any date string parseable by PHP strtotime()." }, "end": { "oneOf": [ { "type": "number" }, { "type": "string" } ], "description": "End of the log data range. Same formats as start. Must be later than start." }, "page_size": { "type": "number", "minimum": 1, "maximum": 10000, "description": "Maximum number of records to return per request. Default 500.", "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": { "type": "object", "description": "Filter criteria. Values are submitted as PHP array notation, e.g. filter[severity][]=Warning.", "properties": { "severity": { "type": "array", "items": { "type": "string" }, "description": "Severity levels to include. Known values: \"User\", \"Warning\", \"Deprecated\", \"Fatal error\". Submit each value as a separate field: filter[severity][]=Warning&filter[severity][]=Deprecated" } } } }, "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": { "NotFound": { "type": "string", "description": "Site not found." } } } } }, "description": "Site not found." }, "500": { "content": { "application/json": { "schema": { "type": "object", "properties": { "InternalServerError": { "type": "string", "description": "Failed to generate phpMyAdmin authentication token." } } } } }, "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" } }, "/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": { "NotFound": { "type": "string", "description": "User not found." } } } } }, "description": "User not found." }, "500": { "content": { "application/json": { "schema": { "type": "object", "properties": { "InternalError": { "type": "string", "description": "Database query failed." } } } } }, "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": { "BadRequest": { "type": "string", "description": "Missing or invalid task ID." } } } } }, "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" }, "description": "Array of time period objects that span the timeseries response.", "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." } } } } } }, "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": { "BadRequest": { "type": "string", "description": "Invalid parameters or metric/dimension combination." } } } } }, "description": "Invalid parameters or metric/dimension combination." }, "403": { "content": { "application/json": { "schema": { "type": "object", "properties": { "Forbidden": { "type": "string", "description": "Access denied or invalid client." } } } } }, "description": "Access denied or invalid client." }, "404": { "content": { "application/json": { "schema": { "type": "object", "properties": { "NotFound": { "type": "string", "description": "Site not found." } } } } }, "description": "Site not found." }, "500": { "content": { "application/json": { "schema": { "type": "object", "properties": { "InternalServerError": { "type": "string", "description": "Failed to connect to or query metrics data source." } } } } }, "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" ] } } } } } }, "/usage/{site}": { "post": { "tags": [ "Usage" ], "summary": "Get Time Series Usage Data", "description": "Get the usage data of a site.\n\nThis endpoint queries a time series database and returns usage data for a site. Usage data includes: compute, bandwidth, email and storage.\n\nNote on Supported Resolutions and periods:\n- `hour` - Available for periods spanning 3 days up to 7 days ago\n- `day` - Available for periods spanning 31 days up to 2 months ago\n- `month` - Available for periods up to 2 years ago\n\nForecast Usage:\n\nDay and Month resolution usage forecasts are available up to end of the current month. The forecast is generated from the 7-day rolling average of hourly usage and will not capture spikes in usage from sales, advertising or breaking news.", "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": "Response metadata.", "properties": { "took": { "type": "number", "description": "Backend response time in seconds." }, "units": { "type": "object", "description": "Units for each usage type.", "properties": { "storage": { "type": "string", "description": "Unit for storage (e.g., \"bytes seconds\")." }, "compute": { "type": "string", "description": "Unit for compute (e.g., \"seconds\")." }, "bandwidth": { "type": "string", "description": "Unit for bandwidth (e.g., \"bytes\")." }, "email": { "type": "string", "description": "Unit for email count (e.g., \"#\")." } } }, "forecast": { "type": "string", "description": "Present and set to \"true\" when a forecast is included." }, "start": { "type": "string", "description": "Start datetime of the response (Y-m-d H:i:s)." }, "end": { "type": "string", "description": "End datetime of the response (Y-m-d H:i:s)." }, "resolution": { "type": "string", "description": "Resolution of the data (\"hour\", \"day\", or \"month\")." } } }, "data": { "type": "object", "description": "Usage data arrays keyed by meter type.", "properties": { "storage": { "type": "array", "items": { "type": "object" }, "description": "Storage usage time series.", "properties": { "timestamp": { "type": "string", "description": "Period start datetime (Y-m-d H:i:s)." }, "usage": { "type": "string", "description": "Storage used during the period." }, "forecast": { "type": "number", "description": "Forecasted storage for the period (when forecast requested)." } } }, "compute": { "type": "array", "items": { "type": "object" }, "description": "Compute usage time series.", "properties": { "timestamp": { "type": "string", "description": "Period start datetime (Y-m-d H:i:s)." }, "usage": { "type": "string", "description": "Compute used during the period in seconds." }, "forecast": { "type": "number", "description": "Forecasted compute for the period (when forecast requested)." } } }, "bandwidth": { "type": "array", "items": { "type": "object" }, "description": "Bandwidth usage time series.", "properties": { "timestamp": { "type": "string", "description": "Period start datetime (Y-m-d H:i:s)." }, "usage": { "type": "string", "description": "Bandwidth used during the period in bytes." }, "forecast": { "type": "number", "description": "Forecasted bandwidth for the period (when forecast requested)." } } }, "email": { "type": "array", "items": { "type": "object" }, "description": "Email usage time series.", "properties": { "timestamp": { "type": "string", "description": "Period start datetime (Y-m-d H:i:s)." }, "usage": { "type": "string", "description": "Emails sent during the period." }, "forecast": { "type": "number", "description": "Forecasted emails for the period (when forecast requested)." } } } } } } } }, "example": { "message": "OK", "data": { "_meta": { "took": 0.1983170509338379, "units": { "storage": "bytes seconds", "compute": "seconds", "bandwidth": "bytes", "email": "#" }, "forecast": "true", "start": "2025-09-22 00:00:00", "end": "2025-09-24 00:00:00", "resolution": "day" }, "data": { "storage": [ { "timestamp": "2025-09-22 00:00:00", "usage": "17541676679095" }, { "timestamp": "2025-09-23 00:00:00", "forecast": 7629593790237.179, "usage": "10052491991344" } ], "compute": [ { "timestamp": "2025-09-22 00:00:00", "usage": "143.40000714175403" }, { "timestamp": "2025-09-23 00:00:00", "forecast": 68.68668799961146, "usage": "77.91900319501292" } ], "bandwidth": [ { "timestamp": "2025-09-22 00:00:00", "usage": "618318" }, { "timestamp": "2025-09-23 00:00:00", "forecast": 409164.380952381, "usage": "209871" } ], "email": [ { "timestamp": "2025-09-22 00:00:00", "usage": "0" }, { "timestamp": "2025-09-23 00:00:00", "forecast": 0, "usage": "0" } ] } } } }, "examples": { "success-25c2953117ddaf5518874922c1aa61e9": { "summary": "Forecast-Success-Response", "value": { "message": "OK", "data": { "_meta": { "took": 0.1983170509338379, "units": { "storage": "bytes seconds", "compute": "seconds", "bandwidth": "bytes", "email": "#" }, "forecast": "true", "start": "2025-09-22 00:00:00", "end": "2025-09-24 00:00:00", "resolution": "day" }, "data": { "storage": [ { "timestamp": "2025-09-22 00:00:00", "usage": "17541676679095" }, { "timestamp": "2025-09-23 00:00:00", "forecast": 7629593790237.179, "usage": "10052491991344" } ], "compute": [ { "timestamp": "2025-09-22 00:00:00", "usage": "143.40000714175403" }, { "timestamp": "2025-09-23 00:00:00", "forecast": 68.68668799961146, "usage": "77.91900319501292" } ], "bandwidth": [ { "timestamp": "2025-09-22 00:00:00", "usage": "618318" }, { "timestamp": "2025-09-23 00:00:00", "forecast": 409164.380952381, "usage": "209871" } ], "email": [ { "timestamp": "2025-09-22 00:00:00", "usage": "0" }, { "timestamp": "2025-09-23 00:00:00", "forecast": 0, "usage": "0" } ] } } } } } } } }, "400": { "content": { "application/json": { "schema": { "type": "object", "properties": { "BadRequest": { "type": "string", "description": "Missing or invalid parameters." } } } } }, "description": "Missing or invalid parameters." }, "403": { "content": { "application/json": { "schema": { "type": "object", "properties": { "Forbidden": { "type": "string", "description": "Access denied." } } } } }, "description": "Access denied." }, "404": { "content": { "application/json": { "schema": { "type": "object", "properties": { "NotFound": { "type": "string", "description": "Site not found." } } } } }, "description": "Site not found." } }, "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": "number", "description": "Unix timestamp for the start of the data range." }, "end": { "type": "number", "description": "Unix timestamp for the end of the data range." }, "resolution": { "type": "string", "enum": [ "hour", "day", "month" ], "description": "Resolution interval that data should be returned for." }, "forecast": { "type": "string", "description": "If present, a forecast will be provided for partial and future periods." } }, "required": [ "start", "end", "resolution" ] } } } } } }, "/site-logs/{site}": { "post": { "tags": [ "Logs" ], "summary": "Get Web Server Logs", "description": "Get web server (nginx) log data from a site. Logs are only guaranteed for 28 days; a start timestamp before that may return incomplete data.", "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "total_results": { "type": "number", "description": "Total number of matching log entries; may be null if unavailable." }, "logs": { "type": "array", "items": { "type": "object" }, "description": "Array of log entry objects.", "properties": { "body_bytes_sent": { "type": "number", "description": "Response body size in bytes." }, "cached": { "type": "string", "description": "Cache status (e.g. \"true\", \"false\")." }, "date": { "type": "string", "description": "ISO 8601 timestamp of the request." }, "http2": { "type": "string", "description": "HTTP/2 stream ID, or empty string for non-HTTP/2 requests." }, "http_host": { "type": "string", "description": "Host header value." }, "http_referer": { "type": "string", "description": "Referer header value." }, "http_user_agent": { "type": "string", "description": "User-Agent header value." }, "http_version": { "type": "string", "description": "HTTP protocol version (e.g. \"HTTP/1.1\")." }, "http_x_forwarded_for": { "type": "string", "description": "Original client IP from X-Forwarded-For header." }, "renderer": { "type": "string", "description": "Renderer type (e.g. \"php\", \"static\")." }, "request_completion": { "type": "string", "description": "Request completion status (e.g. \"OK\")." }, "request_time": { "type": "number", "description": "Request processing time in seconds." }, "request_type": { "type": "string", "description": "HTTP method (e.g. \"GET\", \"POST\")." }, "request_url": { "type": "string", "description": "Request path and query string." }, "scheme": { "type": "string", "description": "Request scheme (\"http\" or \"https\")." }, "status": { "type": "number", "description": "HTTP response status code." }, "timestamp": { "type": "number", "description": "Unix timestamp of the request." }, "type": { "type": "string", "description": "Log record type (e.g. \"nginx_json\")." }, "user_ip": { "type": "string", "description": "Resolved client IP address." } } }, "scroll_id": { "type": "string", "description": "Opaque cursor to pass as scroll_id to retrieve the next page; null when no more results are available." } } } }, "example": { "message": "OK", "data": { "total_results": 1243, "logs": [ { "body_bytes_sent": 31, "cached": "false", "date": "2020-12-18T13:20:13.000Z", "http2": "", "http_host": "example.com", "http_referer": "https://example.com/path/to/resource/", "http_user_agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/87.0.4280.67 Safari/537.36", "http_version": "HTTP/1.1", "http_x_forwarded_for": "11.22.33.44", "renderer": "php", "request_completion": "OK", "request_time": 0.009, "request_type": "GET", "request_url": "/path/to/resource", "scheme": "http", "status": 200, "timestamp": 1608297613, "type": "nginx_json", "user_ip": "55.66.77.88" }, { "body_bytes_sent": 22889, "cached": "false", "date": "2020-12-18T13:20:14.000Z", "http2": "", "http_host": "example.com", "http_referer": "https://some-domain.com/", "http_user_agent": "Mozilla/5.0 (iPhone; CPU iPhone OS 14_2 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) CriOS/85.0.4183.109 Mobile/15E148 Safari/604.1", "http_version": "HTTP/1.1", "http_x_forwarded_for": "99.88.77.66", "renderer": "php", "request_completion": "OK", "request_time": 0.539, "request_type": "GET", "request_url": "/path/to/resource", "scheme": "http", "status": 200, "timestamp": 1608297614, "type": "nginx_json", "user_ip": "55.44.33.22" } ], "scroll_id": "scroll-id-string" } } }, "examples": { "success-7b0f3aaa3941a40837b48c411f399d30": { "summary": "Success-Response", "value": { "message": "OK", "data": { "total_results": 1243, "logs": [ { "body_bytes_sent": 31, "cached": "false", "date": "2020-12-18T13:20:13.000Z", "http2": "", "http_host": "example.com", "http_referer": "https://example.com/path/to/resource/", "http_user_agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/87.0.4280.67 Safari/537.36", "http_version": "HTTP/1.1", "http_x_forwarded_for": "11.22.33.44", "renderer": "php", "request_completion": "OK", "request_time": 0.009, "request_type": "GET", "request_url": "/path/to/resource", "scheme": "http", "status": 200, "timestamp": 1608297613, "type": "nginx_json", "user_ip": "55.66.77.88" }, { "body_bytes_sent": 22889, "cached": "false", "date": "2020-12-18T13:20:14.000Z", "http2": "", "http_host": "example.com", "http_referer": "https://some-domain.com/", "http_user_agent": "Mozilla/5.0 (iPhone; CPU iPhone OS 14_2 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) CriOS/85.0.4183.109 Mobile/15E148 Safari/604.1", "http_version": "HTTP/1.1", "http_x_forwarded_for": "99.88.77.66", "renderer": "php", "request_completion": "OK", "request_time": 0.539, "request_type": "GET", "request_url": "/path/to/resource", "scheme": "http", "status": 200, "timestamp": 1608297614, "type": "nginx_json", "user_ip": "55.44.33.22" } ], "scroll_id": "scroll-id-string" } } } } } } }, "400": { "content": { "application/json": { "schema": { "type": "object", "properties": { "BadRequest": { "type": "string", "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." } } } } }, "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": { "Forbidden": { "type": "string", "description": "Access denied." } } } } }, "description": "Access denied." }, "404": { "content": { "application/json": { "schema": { "type": "object", "properties": { "NotFound": { "type": "string", "description": "Site not found." } } } } }, "description": "Site not found." }, "500": { "content": { "application/json": { "schema": { "type": "object", "properties": { "InternalServerError": { "type": "string", "description": "Search backend error." } } } } }, "description": "Search backend error." } }, "parameters": [ { "name": "site", "in": "path", "description": "Site ID or domain.", "required": true, "schema": { "type": "string" } } ], "operationId": "post-site-logs-site", "requestBody": { "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "properties": { "start": { "oneOf": [ { "type": "number" }, { "type": "string" } ], "description": "Start of the log data range. Accepts a Unix timestamp or any date string parseable by PHP strtotime()." }, "end": { "oneOf": [ { "type": "number" }, { "type": "string" } ], "description": "End of the log data range. Same formats as start. Must be later than start." }, "page_size": { "type": "number", "minimum": 1, "maximum": 10000, "description": "Maximum number of records to return per request. Default 500.", "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": { "type": "object", "description": "Filter criteria. Values are submitted as PHP array notation, e.g. filter[status][]=404.", "properties": { "cached": { "type": "array", "items": { "type": "string" }, "description": "Cache status values to include (e.g. \"true\", \"false\"). Submit each as: filter[cached][]=false." }, "renderer": { "type": "array", "items": { "type": "string" }, "description": "Renderer types to include (e.g. \"php\", \"static\"). Submit each as: filter[renderer][]=php." }, "request_type": { "type": "array", "items": { "type": "string" }, "description": "HTTP methods to include (e.g. \"GET\", \"POST\"). Submit each as: filter[request_type][]=GET." }, "status": { "type": "array", "items": { "type": "number" }, "description": "HTTP status codes to include. Submit each as: filter[status][]=404&filter[status][]=500." }, "user_ip": { "type": "array", "items": { "type": "string" }, "description": "Client IP addresses to include. Submit each as: filter[user_ip][]=1.2.3.4." } } } }, "required": [ "start", "end" ] } } } } } }, "/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.", "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "total_results": { "type": "number", "description": "Total number of matching log entries; may be null if unavailable." }, "logs": { "type": "array", "items": { "type": "object" }, "description": "Array of log entry objects. Each entry includes atomic_site_id identifying the source site.", "properties": { "atomic_site_id": { "type": "number", "description": "Numeric site ID identifying the source site." }, "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": { "type": "string", "description": "Line number where the error occurred." }, "timestamp": { "type": "string", "description": "ISO 8601 timestamp of the log entry." } } }, "scroll_id": { "type": "string", "description": "Opaque cursor to pass as scroll_id to retrieve the next page; null when no more results are available." }, "error_rate": { "type": "array", "items": { "type": "object" }, "description": "Time-bucketed error counts. Each bucket has timestamp (Unix seconds), count, and severities object.", "properties": { "timestamp": { "type": "number", "description": "Unix timestamp for the start of the bucket." }, "count": { "type": "number", "description": "Total errors in this bucket." }, "severities": { "type": "object", "description": "Error counts keyed by severity level (e.g. {\"Fatal error\": 3, \"Warning\": 1})." } } }, "top_plugins_by_errors": { "type": "array", "items": { "type": "object" }, "description": "Top 10 plugins/themes by error count.", "properties": { "name": { "type": "string", "description": "Plugin or theme slug." }, "type": { "type": "string", "description": "Asset type: \"plugin\", \"theme\", or \"mu-plugin\"." }, "count": { "type": "number", "description": "Total error count." }, "timeseries": { "type": "array", "items": { "type": "object" }, "description": "Per-bucket timeseries (timestamp, count); present only when resolution is provided." } } }, "top_sites_by_errors": { "type": "array", "items": { "type": "object" }, "description": "Top 10 sites by error count.", "properties": { "atomic_site_id": { "type": "number", "description": "Numeric site ID." }, "domain": { "type": "string", "description": "Primary domain name of the site." }, "count": { "type": "number", "description": "Total error count for this site." }, "severity_breakdown": { "type": "object", "description": "Error counts keyed by severity level (e.g. {\"Fatal error\": 3, \"Warning\": 1})." }, "timeseries": { "type": "array", "items": { "type": "object" }, "description": "Per-bucket timeseries (timestamp, count); present only when resolution is provided." } } } } } } } } } }, "400": { "content": { "application/json": { "schema": { "type": "object", "properties": { "BadRequest": { "type": "string", "description": "Missing or invalid parameter." } } } } }, "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": { "Forbidden": { "type": "string", "description": "Access denied." } } } } }, "description": "Access denied." }, "404": { "content": { "application/json": { "schema": { "type": "object", "properties": { "NotFound": { "type": "string", "description": "Site not found." } } } } }, "description": "Site not found." }, "500": { "content": { "application/json": { "schema": { "type": "object", "properties": { "InternalServerError": { "type": "string", "description": "Search backend error." } } } } }, "description": "Search backend error.\n\n@api {post} /logs/site/:site/error Get PHP Error Logs for a Site" } }, "parameters": [ { "name": "site", "in": "path", "description": "Site ID or domain.", "required": true, "schema": { "type": "string" } }, { "name": "client", "in": "query", "description": "Client ID or client name (slug).", "required": true, "schema": { "type": "string" } } ], "operationId": "post-logs-site-site", "requestBody": { "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "properties": { "start": { "oneOf": [ { "type": "number" }, { "type": "string" } ], "description": "Unix timestamp or date string parseable by strtotime() for the start of the range." }, "end": { "oneOf": [ { "type": "number" }, { "type": "string" } ], "description": "Unix timestamp or date string parseable by strtotime() for the end of the range. Must be later than start." }, "page_size": { "type": "number", "minimum": 1, "maximum": 10000, "description": "Maximum records per request. Default 500.", "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": { "type": "object", "description": "Filter criteria. Values are submitted as PHP array notation.", "properties": { "cached": { "type": "array", "items": { "type": "string" }, "description": "Cache status values to include (e.g. \"true\", \"false\")." }, "renderer": { "type": "array", "items": { "type": "string" }, "description": "Renderer types to include (e.g. \"php\", \"static\")." }, "request_type": { "type": "array", "items": { "type": "string" }, "description": "HTTP methods to include (e.g. \"GET\", \"POST\")." }, "status": { "type": "array", "items": { "type": "number" }, "description": "HTTP status codes to include." }, "user_ip": { "type": "array", "items": { "type": "string" }, "description": "Client IP addresses to include." }, "severity": { "type": "string", "enum": [ "User", "Warning", "Deprecated", "Fatal error" ], "description": "Severity levels to include." }, "atomic_site_id": { "type": "array", "items": { "type": "number" }, "description": "Restrict to specific site IDs within the client." } } }, "resolution": { "type": "number", "description": "Bucket interval in seconds (minimum 60)." }, "range": { "type": "object", "description": "Numeric range filters. Allowed fields: request_time, body_bytes_sent, status. Submit as PHP array notation, e.g. range[request_time][gte]=0.5.", "properties": { "field": { "type": "object", "properties": { "gte": { "type": "number", "description": "Lower bound (inclusive)." }, "lte": { "type": "number", "description": "Upper bound (inclusive)." }, "gt": { "type": "number", "description": "Lower bound (exclusive)." }, "lt": { "type": "number", "description": "Upper bound (exclusive)." } } } } } }, "required": [ "start", "end", "resolution" ] } } } } } }, "/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": { "BadRequest": { "type": "string", "description": "Missing or invalid task ID, or task already completed." } } } } }, "description": "Missing or invalid task ID, or task already completed." }, "500": { "content": { "application/json": { "schema": { "type": "object", "properties": { "InternalServerError": { "type": "string", "description": "Failed to interrupt the task." } } } } }, "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" }, "description": "Array of site objects.", "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." } } } } } } } }, "400": { "content": { "application/json": { "schema": { "type": "object", "properties": { "BadRequest": { "type": "string", "description": "Invalid or unauthorized client." } } } } }, "description": "Invalid or unauthorized client." }, "500": { "content": { "application/json": { "schema": { "type": "object", "properties": { "InternalServerError": { "type": "string", "description": "Database error." } } } } }, "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" }, "description": "Array of site objects.", "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." } } } } } } } }, "400": { "content": { "application/json": { "schema": { "type": "object", "properties": { "BadRequest": { "type": "string", "description": "Invalid or unauthorized client." } } } } }, "description": "Invalid or unauthorized client." }, "500": { "content": { "application/json": { "schema": { "type": "object", "properties": { "InternalServerError": { "type": "string", "description": "Database error." } } } } }, "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" }, "description": "Array of cron entries.", "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." } } } }, "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": { "Forbidden": { "type": "string", "description": "Access denied." } } } } }, "description": "Access denied." }, "404": { "content": { "application/json": { "schema": { "type": "object", "properties": { "NotFound": { "type": "string", "description": "Site not found." } } } } }, "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" }, "description": "List of certificates.", "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." } } }, "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": { "BadRequest": { "type": "string", "description": "Invalid status, order_by, or limit value." } } } } }, "description": "Invalid status, order_by, or limit value." }, "403": { "content": { "application/json": { "schema": { "type": "object", "properties": { "Forbidden": { "type": "string", "description": "Access denied." } } } } }, "description": "Access denied." }, "500": { "content": { "application/json": { "schema": { "type": "object", "properties": { "InternalServerError": { "type": "string", "description": "ACME API error." } } } } }, "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": "string" } ], "description": "Site ID, or null if client-level." }, "requeued_from_job_id": { "oneOf": [ { "type": "number" }, { "type": "string" } ], "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": { "BadRequest": { "type": "string", "description": "Missing job_id." } } } } }, "description": "Unknown or missing client." }, "403": { "content": { "application/json": { "schema": { "type": "object", "properties": { "Forbidden": { "type": "string", "description": "Not authorized to act on this client's webhooks." }, "AccessDenied": { "type": "string", "description": "Not authorized to act on this client's webhook." } } } } }, "description": "Not authorized to act on this client's webhooks." }, "404": { "content": { "application/json": { "schema": { "type": "object", "properties": { "NotFound": { "type": "string", "description": "Webhook job not found." } } } } }, "description": "Webhook job not found." }, "422": { "content": { "application/json": { "schema": { "type": "object", "properties": { "Unprocessable": { "type": "string", "description": "Already a requeue, max requeue count reached, or a requeue is already pending/succeeded." } } } } }, "description": "Already a requeue, max requeue count reached, or a requeue is already pending/succeeded." }, "500": { "content": { "application/json": { "schema": { "type": "object", "properties": { "InternalError": { "type": "string", "description": "Failed to parse job data or requeue failed." } } } } }, "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" }, "description": "Array of firewall rules.", "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." } } } }, "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": { "Forbidden": { "type": "string", "description": "Access denied." } } } } }, "description": "Access denied." }, "404": { "content": { "application/json": { "schema": { "type": "object", "properties": { "NotFound": { "type": "string", "description": "Site not found." } }, "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": { "InternalServerError": { "type": "string", "description": "Database query failed." } } } } }, "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": { "Forbidden": { "type": "string", "description": "Access denied." } } } } }, "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" }, "description": "Array of public keys.", "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": { "Forbidden": { "type": "string", "description": "Access denied." } } } } }, "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" }, "description": "List of backups.", "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" }, { "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": { "BadRequest": { "type": "string", "description": "Invalid service identifier, unknown site, or invalid backup type." } }, "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" }, "description": "List of backups.", "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" }, { "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": { "BadRequest": { "type": "string", "description": "Invalid service identifier, unknown site, or invalid backup type." } }, "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": { "BadRequest": { "type": "string", "description": "Invalid site or service type." } } } } }, "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" }, "description": "Array of blocked domain records.", "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." } } } }, "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": { "BadRequest": { "type": "string", "description": "Invalid action or block type." } }, "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": { "Forbidden": { "type": "string", "description": "Invalid client or API key not authorised for this client." } } } } }, "description": "Invalid client or API key not authorised for this client." }, "500": { "content": { "application/json": { "schema": { "type": "object", "properties": { "InternalServerError": { "type": "string", "description": "Internal server error." } } } } }, "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": { "BadRequest": { "type": "string", "description": "Invalid action, missing parameters, invalid SSH key format, or attempt to remove a protected key." } } } } }, "description": "Invalid action, missing parameters, invalid SSH key format, or attempt to remove a protected key." }, "403": { "content": { "application/json": { "schema": { "type": "object", "properties": { "Forbidden": { "type": "string", "description": "Not authorized to manage this client." } } } } }, "description": "Not authorized to manage this client." }, "500": { "content": { "application/json": { "schema": { "type": "object", "properties": { "InternalServerError": { "type": "string", "description": "Database error on insert." } } } } }, "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": { "BadRequest": { "type": "string", "description": "Invalid action, missing parameters, invalid SSH key format, or attempt to remove a protected key." } } } } }, "description": "Invalid action, missing parameters, invalid SSH key format, or attempt to remove a protected key." }, "403": { "content": { "application/json": { "schema": { "type": "object", "properties": { "Forbidden": { "type": "string", "description": "Not authorized to manage this client." } } } } }, "description": "Not authorized to manage this client." }, "500": { "content": { "application/json": { "schema": { "type": "object", "properties": { "InternalServerError": { "type": "string", "description": "Database error on insert." } } } } }, "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": { "BadRequest": { "type": "string", "description": "Invalid action, missing parameters, invalid SSH key format, or attempt to remove a protected key." } } } } }, "description": "Invalid action, missing parameters, invalid SSH key format, or attempt to remove a protected key." }, "403": { "content": { "application/json": { "schema": { "type": "object", "properties": { "Forbidden": { "type": "string", "description": "Not authorized to manage this client." } } } } }, "description": "Not authorized to manage this client." }, "500": { "content": { "application/json": { "schema": { "type": "object", "properties": { "InternalServerError": { "type": "string", "description": "Database error on insert." } } } } }, "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": { "BadRequest": { "type": "string", "description": "Invalid action, missing parameters, invalid SSH key format, or attempt to remove a protected key." } } } } }, "description": "Invalid action, missing parameters, invalid SSH key format, or attempt to remove a protected key." }, "403": { "content": { "application/json": { "schema": { "type": "object", "properties": { "Forbidden": { "type": "string", "description": "Not authorized to manage this client." } } } } }, "description": "Not authorized to manage this client." }, "500": { "content": { "application/json": { "schema": { "type": "object", "properties": { "InternalServerError": { "type": "string", "description": "Database error on insert." } } } } }, "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": { "BadRequest": { "type": "string", "description": "Invalid action or attempt to remove primary domain." } } } } }, "description": "Invalid action or attempt to remove primary domain." }, "403": { "content": { "application/json": { "schema": { "type": "object", "properties": { "Forbidden": { "type": "string", "description": "Access denied." } } } } }, "description": "Access denied." }, "404": { "content": { "application/json": { "schema": { "type": "object", "properties": { "NotFound": { "type": "string", "description": "Site not found." } } } } }, "description": "Site not found." }, "501": { "content": { "application/json": { "schema": { "type": "object", "properties": { "NotImplemented": { "type": "string", "description": "The \"wpcom\" and \"atomic\" service types are not supported." } } } } }, "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": { "BadRequest": { "type": "string", "description": "Invalid action or attempt to remove primary domain." } } } } }, "description": "Invalid action or attempt to remove primary domain." }, "403": { "content": { "application/json": { "schema": { "type": "object", "properties": { "Forbidden": { "type": "string", "description": "Access denied." } } } } }, "description": "Access denied." }, "404": { "content": { "application/json": { "schema": { "type": "object", "properties": { "NotFound": { "type": "string", "description": "Site not found." } } } } }, "description": "Site not found." }, "501": { "content": { "application/json": { "schema": { "type": "object", "properties": { "NotImplemented": { "type": "string", "description": "The \"wpcom\" and \"atomic\" service types are not supported." } } } } }, "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 either \"latest\", \"previous\", or \"beta\" (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- `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` may be used to enable burst for sites with fewer than 10 default_php_conns. 0 or absent when default_php_conns < 10 means burst is disabled, 1 means burst is enabled.\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": { "BadRequest": { "type": "string", "description": "Invalid key, invalid action, missing value, or insufficient privileges." } }, "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": { "Forbidden": { "type": "string", "description": "Key is admin-only or method not allowed for this key." } } } } }, "description": "Key is admin-only or method not allowed for this key." }, "404": { "content": { "application/json": { "schema": { "type": "object", "properties": { "NotFound": { "type": "string", "description": "Site not found." } } } } }, "description": "Site not found." }, "423": { "content": { "application/json": { "schema": { "type": "object", "properties": { "Locked": { "type": "string", "description": "Site is locked; non-get operations are disallowed." } } } } }, "description": "Site is locked; non-get operations are disallowed." }, "500": { "content": { "application/json": { "schema": { "type": "object", "properties": { "InternalServerError": { "type": "string", "description": "Database error." } } } } }, "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 either \"latest\", \"previous\", or \"beta\" (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- `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` may be used to enable burst for sites with fewer than 10 default_php_conns. 0 or absent when default_php_conns < 10 means burst is disabled, 1 means burst is enabled.\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": { "BadRequest": { "type": "string", "description": "Invalid key, invalid action, missing value, or insufficient privileges." } }, "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": { "Forbidden": { "type": "string", "description": "Key is admin-only or method not allowed for this key." } } } } }, "description": "Key is admin-only or method not allowed for this key." }, "404": { "content": { "application/json": { "schema": { "type": "object", "properties": { "NotFound": { "type": "string", "description": "Site not found." } } } } }, "description": "Site not found." }, "423": { "content": { "application/json": { "schema": { "type": "object", "properties": { "Locked": { "type": "string", "description": "Site is locked; non-get operations are disallowed." } } } } }, "description": "Site is locked; non-get operations are disallowed." }, "500": { "content": { "application/json": { "schema": { "type": "object", "properties": { "InternalServerError": { "type": "string", "description": "Database error." } } } } }, "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": { "BadRequest": { "type": "string", "description": "No valid software actions provided." } } } } }, "description": "No valid software actions provided." }, "403": { "content": { "application/json": { "schema": { "type": "object", "properties": { "Forbidden": { "type": "string", "description": "Access denied." } } } } }, "description": "Access denied." }, "404": { "content": { "application/json": { "schema": { "type": "object", "properties": { "NotFound": { "type": "string", "description": "Site not found." } } } } }, "description": "Site not found." }, "500": { "content": { "application/json": { "schema": { "type": "object", "properties": { "InternalServerError": { "type": "string", "description": "Unable to find primary server for site's pool." } } } } }, "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": { "NotFound": { "type": "string", "description": "Site not found." } } } } }, "description": "Site not found." }, "500": { "content": { "application/json": { "schema": { "type": "object", "properties": { "InternalError": { "type": "string", "description": "Database error, no server found for site, or job queue failure." } } } } }, "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": { "InvalidKey": { "type": "string", "description": "Invalid or unsupported meta key." } }, "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": { "Forbidden": { "type": "string", "description": "Access denied or method not allowed for this key." } } } } }, "description": "Access denied or method not allowed for this key." }, "404": { "content": { "application/json": { "schema": { "type": "object", "properties": { "NotFound": { "type": "string", "description": "Meta key not found for this client." } }, "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": { "BadRequest": { "type": "string", "description": "Invalid or empty cron_id." } } } } }, "description": "Invalid or empty cron_id." }, "403": { "content": { "application/json": { "schema": { "type": "object", "properties": { "Forbidden": { "type": "string", "description": "Access denied." } } } } }, "description": "Access denied." }, "404": { "content": { "application/json": { "schema": { "type": "object", "properties": { "NotFound": { "type": "string", "description": "Site or cron entry not found." } } } } }, "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": { "BadRequest": { "type": "string", "description": "Invalid rule ID format." } } } } }, "description": "Invalid rule ID format." }, "403": { "content": { "application/json": { "schema": { "type": "object", "properties": { "Forbidden": { "type": "string", "description": "Access denied." } } } } }, "description": "Access denied." }, "404": { "content": { "application/json": { "schema": { "type": "object", "properties": { "NotFound": { "type": "string", "description": "Site or rule not found." } }, "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": { "InternalServerError": { "type": "string", "description": "Database error." } } } } }, "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": { "BadRequest": { "type": "string", "description": "Attempted to remove a protected key." } } } } }, "description": "Attempted to remove a protected key." }, "403": { "content": { "application/json": { "schema": { "type": "object", "properties": { "Forbidden": { "type": "string", "description": "Access denied." } } } } }, "description": "Access denied." }, "500": { "content": { "application/json": { "schema": { "type": "object", "properties": { "InternalServerError": { "type": "string", "description": "Database error; data contains the error message." } } } } }, "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": { "BadRequest": { "type": "string", "description": "Invalid site, service type, or missing/invalid username." } } } } }, "description": "Invalid site, service type, or missing/invalid username." }, "404": { "content": { "application/json": { "schema": { "type": "object", "properties": { "NotFound": { "type": "string", "description": "Username not found for this site." } } } } }, "description": "Username not found for this site." }, "500": { "content": { "application/json": { "schema": { "type": "object", "properties": { "InternalServerError": { "type": "string", "description": "Database error." } } } } }, "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": { "BadRequest": { "type": "string", "description": "Invalid site, service type, or missing/invalid username." } } } } }, "description": "Invalid site, service type, or missing/invalid username." }, "404": { "content": { "application/json": { "schema": { "type": "object", "properties": { "NotFound": { "type": "string", "description": "Username not found for this site." } } } } }, "description": "Username not found for this site." }, "500": { "content": { "application/json": { "schema": { "type": "object", "properties": { "InternalServerError": { "type": "string", "description": "Database error." } } } } }, "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": { "InvalidBackupType": { "type": "string", "description": "Invalid backup type (must be \"fs\" or \"db\")." } } } } }, "description": "Invalid backup type (must be \"fs\" or \"db\")." }, "403": { "content": { "application/json": { "schema": { "type": "object", "properties": { "Forbidden": { "type": "string", "description": "Backup quota reached for this site." } } } } }, "description": "Backup quota reached for this site." }, "404": { "content": { "application/json": { "schema": { "type": "object", "properties": { "NotFound": { "type": "string", "description": "Site not found." } } } } }, "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": { "Forbidden": { "type": "string", "description": "Access denied." } } } } }, "description": "Access denied." }, "404": { "content": { "application/json": { "schema": { "type": "object", "properties": { "NotFound": { "type": "string", "description": "Site not found, backup not found, or backup doesn't belong to this site." } } } } }, "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": { "Forbidden": { "type": "string", "description": "Access denied." } } } } }, "description": "Access denied." }, "404": { "content": { "application/json": { "schema": { "type": "object", "properties": { "NotFound": { "type": "string", "description": "Site not found." } } } } }, "description": "Site not found." }, "500": { "content": { "application/json": { "schema": { "type": "object", "properties": { "InternalServerError": { "type": "string", "description": "Internal server error." } } } } }, "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": { "Forbidden": { "type": "string", "description": "Access denied." } } } } }, "description": "Access denied." }, "404": { "content": { "application/json": { "schema": { "type": "object", "properties": { "NotFound": { "type": "string", "description": "Site not found." } } } } }, "description": "Site not found." }, "500": { "content": { "application/json": { "schema": { "type": "object", "properties": { "InternalServerError": { "type": "string", "description": "Internal server error." } } } } }, "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" } }, "/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": { "BadRequest": { "type": "string", "description": "Missing or stale `allow_restore`, invalid `restore_from`, backup not ready, missing fs/db side of the pair." } } } } }, "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": { "Forbidden": { "type": "string", "description": "Caller cannot act on this site's client." } } } } }, "description": "Caller cannot act on this site's client." }, "404": { "content": { "application/json": { "schema": { "type": "object", "properties": { "NotFound": { "type": "string", "description": "Site or backup not found." } } } } }, "description": "Site or backup not found." }, "409": { "content": { "application/json": { "schema": { "type": "object", "properties": { "Conflict": { "type": "string", "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)." } } } } }, "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": { "Forbidden": { "type": "string", "description": "Access denied." } } } } }, "description": "Access denied." }, "404": { "content": { "application/json": { "schema": { "type": "object", "properties": { "NotFound": { "type": "string", "description": "Site not found." } } } } }, "description": "Site not found." } }, "parameters": [ { "name": "domain", "in": "path", "description": "Domain name.", "required": true, "schema": { "type": "string" } } ], "operationId": "post-ssl-retry-domain" } }, "/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": { "BadRequest": { "type": "string", "description": "Invalid site identifier." } } } } }, "description": "Invalid site identifier." }, "403": { "content": { "application/json": { "schema": { "type": "object", "properties": { "Forbidden": { "type": "string", "description": "Access denied." } } } } }, "description": "Access denied." }, "500": { "content": { "application/json": { "schema": { "type": "object", "properties": { "InternalServerError": { "type": "string", "description": "Failed to queue the scan job." } } } } }, "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." } } } } } } } }, "/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": { "BadRequest": { "type": "string", "description": "Invalid site identifier, missing required fields, or PEM validation failure." } }, "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": { "Forbidden": { "type": "string", "description": "Access denied." } } } } }, "description": "Access denied." }, "500": { "content": { "application/json": { "schema": { "type": "object", "properties": { "InternalServerError": { "type": "string", "description": "ACME API error." } } } } }, "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" ] } } } } } }, "/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": { "BadRequest": { "type": "string", "description": "Invalid enable value." } } } } }, "description": "Invalid enable value." }, "403": { "content": { "application/json": { "schema": { "type": "object", "properties": { "Forbidden": { "type": "string", "description": "Access denied." } } } } }, "description": "Access denied." }, "404": { "content": { "application/json": { "schema": { "type": "object", "properties": { "NotFound": { "type": "string", "description": "Site not found." } } } } }, "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": { "BadRequest": { "type": "string", "description": "Invalid enable value." } } } } }, "description": "Invalid enable value." }, "403": { "content": { "application/json": { "schema": { "type": "object", "properties": { "Forbidden": { "type": "string", "description": "Access denied." } } } } }, "description": "Access denied." }, "404": { "content": { "application/json": { "schema": { "type": "object", "properties": { "NotFound": { "type": "string", "description": "Site not found." } } } } }, "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": { "BadRequest": { "type": "string", "description": "Invalid enable value." } } } } }, "description": "Invalid enable value." }, "403": { "content": { "application/json": { "schema": { "type": "object", "properties": { "Forbidden": { "type": "string", "description": "Access denied." } } } } }, "description": "Access denied." }, "404": { "content": { "application/json": { "schema": { "type": "object", "properties": { "NotFound": { "type": "string", "description": "Site not found." } } } } }, "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": { "BadRequest": { "type": "string", "description": "Invalid site identifier, missing required fields, or PEM validation failure." } } } } }, "description": "Invalid site identifier, missing required fields, or PEM validation failure." }, "403": { "content": { "application/json": { "schema": { "type": "object", "properties": { "Forbidden": { "type": "string", "description": "Access denied." } } } } }, "description": "Access denied." }, "404": { "content": { "application/json": { "schema": { "type": "object", "properties": { "NotFound": { "type": "string", "description": "Certificate not found." } } } } }, "description": "Certificate not found." }, "500": { "content": { "application/json": { "schema": { "type": "object", "properties": { "InternalServerError": { "type": "string", "description": "ACME API error." } } } } }, "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": { "InvalidKey": { "type": "string", "description": "Invalid or unsupported meta key." }, "MissingValue": { "type": "string", "description": "A value must be provided." }, "InvalidWebhookURL": { "type": "string", "description": "Invalid URL provided for webhook_url." }, "InvalidPrivacyModel": { "type": "string", "description": "Invalid value for default_privacy_model; must be \"wp_uploads\" or \"proxy\"." } }, "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." }, "403": { "content": { "application/json": { "schema": { "type": "object", "properties": { "Forbidden": { "type": "string", "description": "Access denied or method not allowed for this key." } } } } }, "description": "Access denied or method not allowed for this key." }, "500": { "content": { "application/json": { "schema": { "type": "object", "properties": { "InternalServerError": { "type": "string", "description": "Internal server error." } } } } }, "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": { "BadRequest": { "type": "string", "description": "Invalid or empty cron_id or command, or update failed." } } } } }, "description": "Invalid or empty cron_id or command, or update failed." }, "403": { "content": { "application/json": { "schema": { "type": "object", "properties": { "Forbidden": { "type": "string", "description": "Access denied." } } } } }, "description": "Access denied." }, "404": { "content": { "application/json": { "schema": { "type": "object", "properties": { "NotFound": { "type": "string", "description": "Site or cron entry not found." } } } } }, "description": "Site or cron entry not found." }, "500": { "content": { "application/json": { "schema": { "type": "object", "properties": { "InternalServerError": { "type": "string", "description": "Database error." } } } } }, "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" ] } } } } } }, "/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": { "BadRequest": { "type": "string", "description": "The desired chroot slug is missing." } } } } }, "description": "The desired chroot slug is missing." }, "403": { "content": { "application/json": { "schema": { "type": "object", "properties": { "Forbidden": { "type": "string", "description": "Access denied." } } } } }, "description": "Access denied." }, "404": { "content": { "application/json": { "schema": { "type": "object", "properties": { "NotFound": { "type": "string", "description": "Site not found, or the desired chroot slug is not allowed for this client." } } } } }, "description": "Site not found, or the desired chroot slug is not allowed for this client." }, "500": { "content": { "application/json": { "schema": { "type": "object", "properties": { "InternalServerError": { "type": "string", "description": "Server error." } } } } }, "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": { "BadRequest": { "type": "string", "description": "Missing domain name or invalid domain." } } } } }, "description": "Missing domain name or invalid domain." }, "403": { "content": { "application/json": { "schema": { "type": "object", "properties": { "Forbidden": { "type": "string", "description": "Access denied." } } } } }, "description": "Access denied." }, "404": { "content": { "application/json": { "schema": { "type": "object", "properties": { "NotFound": { "type": "string", "description": "Site not found." } } } } }, "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": { "BadRequest": { "type": "string", "description": "Missing domain name or invalid domain." } } } } }, "description": "Missing domain name or invalid domain." }, "403": { "content": { "application/json": { "schema": { "type": "object", "properties": { "Forbidden": { "type": "string", "description": "Access denied." } } } } }, "description": "Access denied." }, "404": { "content": { "application/json": { "schema": { "type": "object", "properties": { "NotFound": { "type": "string", "description": "Site not found." } } } } }, "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": { "BadRequest": { "type": "string", "description": "Invalid service type or missing options parameter." } } } } }, "description": "Invalid service type or missing options parameter." }, "403": { "content": { "application/json": { "schema": { "type": "object", "properties": { "Forbidden": { "type": "string", "description": "Access denied." } } } } }, "description": "Access denied." }, "404": { "content": { "application/json": { "schema": { "type": "object", "properties": { "NotFound": { "type": "string", "description": "Site not found." } } } } }, "description": "Site not found." }, "500": { "content": { "application/json": { "schema": { "type": "object", "properties": { "InternalServerError": { "type": "string", "description": "Unable to find primary server for site's pool." } } } } }, "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": { "BadRequest": { "type": "string", "description": "Invalid site, service type, username, or SSH key format. Also returned when neither pass nor pkey is provided." } } } } }, "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": { "NotFound": { "type": "string", "description": "Username not found for this site." } } } } }, "description": "Username not found for this site." }, "500": { "content": { "application/json": { "schema": { "type": "object", "properties": { "InternalServerError": { "type": "string", "description": "Database error." } } } } }, "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": { "BadRequest": { "type": "string", "description": "Invalid version value." } } } } }, "description": "Invalid version value." }, "403": { "content": { "application/json": { "schema": { "type": "object", "properties": { "Forbidden": { "type": "string", "description": "Access denied." } } } } }, "description": "Access denied." }, "404": { "content": { "application/json": { "schema": { "type": "object", "properties": { "NotFound": { "type": "string", "description": "Site not found." } } } } }, "description": "Site not found." }, "500": { "content": { "application/json": { "schema": { "type": "object", "properties": { "InternalServerError": { "type": "string", "description": "Database error." } } } } }, "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" ] } } ], "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": { "BadRequest": { "type": "string", "description": "Invalid site identifier or missing required fields." } } } } }, "description": "Invalid site identifier or missing required fields." }, "403": { "content": { "application/json": { "schema": { "type": "object", "properties": { "Forbidden": { "type": "string", "description": "Access denied." } } } } }, "description": "Access denied." }, "500": { "content": { "application/json": { "schema": { "type": "object", "properties": { "InternalServerError": { "type": "string", "description": "ACME API error." } } } } }, "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": { "BadRequest": { "type": "string", "description": "Invalid or unauthorized client, or domain already in use." } } } } }, "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": "Response Tickets" }, { "name": "SSH" }, { "name": "Security" }, { "name": "Servers" }, { "name": "Sites" }, { "name": "Tasks" }, { "name": "Usage" }, { "name": "Webhooks" } ] }