{ "openapi": "3.1.0", "info": { "title": "WPClientHub API", "version": "1.0.0", "summary": "Sites, updates, backups, uptime, security, clients, tickets, reports, activity and SEO — plus signed webhooks.", "description": "The WPClientHub public REST API, v1. Available on the Scale plan.\n\nAuthenticate with an API key from Settings → API keys: `Authorization: Bearer wch_live_…`. Each key carries scopes; an operation lists the ones that unlock it under `x-required-scopes`.\n\nLists are cursor-paginated (`limit`, `cursor` → `meta.pagination.next_cursor`). Every error is `{\"error\": {\"code\", \"message\", \"details\"}}`. Each key may make 120 requests a minute unless its own limit says otherwise; every answer carries `X-RateLimit-Limit`, `X-RateLimit-Remaining` and `X-RateLimit-Reset`, and a 429 carries `Retry-After`.\n\nGuide: https://wpclienthub.com/docs/api.html", "contact": { "name": "WPClientHub support", "url": "https://wpclienthub.com/contact.html", "email": "hello@wpclienthub.com" } }, "servers": [ { "url": "https://app.wpclienthub.com/api/v1", "description": "Production" }, { "url": "https://app.staging.wpclienthub.com/api/v1", "description": "Staging (keys start wch_test_)" } ], "security": [ { "bearerAuth": [] } ], "tags": [ { "name": "Account", "description": "Who this key belongs to." }, { "name": "Sites", "description": "The sites in your portfolio, and the actions you can start on one." }, { "name": "Updates", "description": "Pending updates and update batches." }, { "name": "Backups", "description": "Restore points." }, { "name": "Uptime", "description": "Up/down status and incidents." }, { "name": "Security", "description": "Vulnerable WordPress core, plugins and themes." }, { "name": "Clients", "description": "Your clients." }, { "name": "Tickets", "description": "The client help desk (when the organization has it)." }, { "name": "Reports", "description": "Client reports and their PDFs." }, { "name": "Activity", "description": "The Activity Log." }, { "name": "SEO", "description": "SEO management (Studio and above): every page's SEO fields and the redirects of a site." }, { "name": "Forms", "description": "Forms on a site and their entries (Agency and above for the form builder; other plugins' forms are read too)." }, { "name": "Webhooks", "description": "Outbound webhook endpoints — what Zapier subscribes through." } ], "paths": { "/me": { "get": { "operationId": "getMe", "summary": "Who this key belongs to", "description": "The organization, the key itself (prefix, scopes, limits) and every scope that exists. Needs no scope — use it to test a key.", "tags": [ "Account" ], "x-required-scopes": [], "responses": { "200": { "description": "OK.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "organization", "api_key", "available_scopes" ], "properties": { "organization": { "$ref": "#/components/schemas/Organization" }, "api_key": { "$ref": "#/components/schemas/ApiKey" }, "available_scopes": { "type": "array", "items": { "type": "string", "enum": [ "sites:read", "sites:write", "updates:read", "updates:write", "backups:read", "backups:write", "uptime:read", "security:read", "clients:read", "tickets:read", "tickets:write", "reports:read", "forms:read", "activity:read", "seo:read", "seo:write", "webhooks:manage" ] } } } } } } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/event-types": { "get": { "operationId": "listEventTypes", "summary": "Webhook event types", "description": "Every event a webhook endpoint can subscribe to, with an example of its `data`. Needs no scope.", "tags": [ "Webhooks" ], "x-required-scopes": [], "responses": { "200": { "description": "OK.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/EventType" } } } } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/sites": { "get": { "operationId": "listSites", "summary": "List sites", "description": "Every site in the portfolio, oldest first.\n\nScope: `sites:read`.", "tags": [ "Sites" ], "x-required-scopes": [ "sites:read" ], "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "name": "status", "in": "query", "required": false, "description": "Only sites with this status.", "schema": { "type": "string", "enum": [ "pending", "connected", "disconnected", "suspended" ] } }, { "name": "client_id", "in": "query", "required": false, "description": "Only this client's sites.", "schema": { "type": "integer" } }, { "name": "q", "in": "query", "required": false, "description": "Name or address contains this text.", "schema": { "type": "string" } }, { "name": "url", "in": "query", "required": false, "description": "The site at this address. Scheme, a leading \"www.\" and a trailing slash are ignored — `example.com` finds `https://www.example.com/`.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "One page. Follow `meta.pagination.next_cursor` while `has_more` is true.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Site" } }, "meta": { "type": "object", "required": [ "pagination" ], "properties": { "pagination": { "$ref": "#/components/schemas/Pagination" } } } } } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/sites/{site}": { "get": { "operationId": "getSite", "summary": "Get a site", "description": "Health score, plugin version, pending updates, last backup and uptime status.\n\nScope: `sites:read`.", "tags": [ "Sites" ], "x-required-scopes": [ "sites:read" ], "parameters": [ { "$ref": "#/components/parameters/SitePath" } ], "responses": { "200": { "description": "OK.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Site" } } } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/sites/{site}/images": { "get": { "operationId": "getSiteImages", "summary": "Image optimization status", "description": "Whether the site's images are optimized by WPClientHub (Agency and above, WPClientHub One 2.0), by another plugin, or not at all — with the totals: images optimized, bytes before and after, WebP/AVIF files written, and how next-gen copies are served. Read-only; settings, runs and restores are in the app.\n\nScope: `sites:read`.", "tags": [ "Sites" ], "x-required-scopes": [ "sites:read" ], "parameters": [ { "$ref": "#/components/parameters/SitePath" } ], "responses": { "200": { "description": "OK.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/SiteImages" } } } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/sites/{site}/cache": { "get": { "operationId": "getSiteCache", "summary": "Page cache status", "description": "Whether the site's pages are cached by WPClientHub (every plan, WPClientHub One 2.0), by another cache plugin or the host (see handled_by), or not at all — with the numbers the site reports: cached pages, bytes, hits and misses over the last seven days and the share of page views answered from the cache, and the last purge.\n\nScope: `sites:read`.", "tags": [ "Sites" ], "x-required-scopes": [ "sites:read" ], "parameters": [ { "$ref": "#/components/parameters/SitePath" } ], "responses": { "200": { "description": "OK.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/SiteCache" } } } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/sites/{site}/cache/purge": { "post": { "operationId": "purgeSiteCache", "summary": "Purge a site's cache", "description": "Purges the site's page cache now — WPClientHub's own cache, any cache plugin or host cache the site's plugin can reach (WP Rocket, LiteSpeed Cache, W3 Total Cache, WP Super Cache, WP Fastest Cache, Cache Enabler, Breeze, Speed Optimizer; Kinsta, WP Engine, Pantheon, Cloudways), and the Cloudflare zone when the site is linked with auto-purge. Without `urls`, everything; with them, only those pages. Done in the request, through the site; 409 when the site is not connected or its plugin is older than 0.15.0.\n\nScope: `sites:write`.", "tags": [ "Sites" ], "x-required-scopes": [ "sites:write" ], "parameters": [ { "$ref": "#/components/parameters/SitePath" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "urls": { "type": "array", "maxItems": 50, "description": "Only these pages (full URLs on the site). Addresses that are not the site's are ignored and listed back.", "items": { "type": "string", "format": "uri" } } } }, "example": { "urls": [ "https://brightleaf.example/pricing/" ] } } } }, "responses": { "200": { "description": "Purged.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/CachePurge" } } } } } }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Invalid" }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/sites/{site}/forms": { "get": { "operationId": "listSiteForms", "summary": "List a site's forms", "description": "Every form on the site: the ones built with WPClientHub (Agency and above, WPClientHub One 2.0) and the ones of Gravity Forms, WPForms, Fluent Forms, Contact Form 7 (with Flamingo) or Ninja Forms WPClientHub One reads, with entry counts. Archived forms are left out. Read-only; building and publishing stay in the app.\n\nScope: `forms:read`.", "tags": [ "Forms" ], "x-required-scopes": [ "forms:read" ], "parameters": [ { "$ref": "#/components/parameters/SitePath" } ], "responses": { "200": { "description": "OK.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Form" } } } } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/sites/{site}/forms/{form}/entries": { "get": { "operationId": "listFormEntries", "summary": "List a form's entries", "description": "Newest first, the answers included (labels as the site stored them). Uploaded files are listed by name and size — the files themselves stay on the site. Spam is included when asked for by `status`.\n\nScope: `forms:read`.", "tags": [ "Forms" ], "x-required-scopes": [ "forms:read" ], "parameters": [ { "$ref": "#/components/parameters/SitePath" }, { "name": "form", "in": "path", "required": true, "description": "The form's id (a UUID).", "schema": { "type": "string", "format": "uuid" } }, { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "name": "status", "in": "query", "required": false, "description": "Only entries with this status.", "schema": { "type": "string", "enum": [ "new", "read", "spam" ] } }, { "name": "since", "in": "query", "required": false, "description": "Only entries submitted at or after this time (ISO 8601).", "schema": { "type": "string", "format": "date-time" } } ], "responses": { "200": { "description": "One page. Follow `meta.pagination.next_cursor` while `has_more` is true.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/FormEntry" } }, "meta": { "type": "object", "required": [ "pagination" ], "properties": { "pagination": { "$ref": "#/components/schemas/Pagination" } } } } } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/sites/{site}/sync": { "post": { "operationId": "syncSite", "summary": "Refresh a site's data", "description": "Queues a fresh state pull from the site (versions, plugins, users, health). Doesn't ask WordPress.org for new versions — use check-updates for that.\n\nScope: `sites:write`.", "tags": [ "Sites" ], "x-required-scopes": [ "sites:write" ], "parameters": [ { "$ref": "#/components/parameters/SitePath" } ], "responses": { "202": { "description": "Queued.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/QueuedAction" } } } } } }, "409": { "$ref": "#/components/responses/Conflict" }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/sites/{site}/check-updates": { "post": { "operationId": "checkSiteUpdates", "summary": "Check a site for updates", "description": "Has WordPress re-check WordPress.org for core, plugin and theme updates, then refreshes the site's data — the app's Resync button.\n\nScope: `sites:write`.", "tags": [ "Sites" ], "x-required-scopes": [ "sites:write" ], "parameters": [ { "$ref": "#/components/parameters/SitePath" } ], "responses": { "202": { "description": "Queued.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/QueuedAction" } } } } } }, "409": { "$ref": "#/components/responses/Conflict" }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/sites/{site}/backups": { "post": { "operationId": "startBackup", "summary": "Back up a site now", "description": "Starts a manual backup. Poll GET /backups/{id} or subscribe to backup.completed / backup.failed. 409 `backup_in_progress` or `restore_in_progress` when one is already running.\n\nScope: `backups:write` or `sites:write`.", "tags": [ "Backups" ], "x-required-scopes": [ "backups:write", "sites:write" ], "parameters": [ { "$ref": "#/components/parameters/SitePath" } ], "responses": { "202": { "description": "Started.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Backup" } } } } } }, "409": { "$ref": "#/components/responses/Conflict" }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/sites/{site}/update-batches": { "post": { "operationId": "startUpdateBatch", "summary": "Start safe updates", "description": "Starts an update batch through the safe-update pipeline — a restore point first, the updates, then before/after screenshots compared, with the site's automatic rollback if it has one. When the site's update policy asks for approval (or `require_approval` is true), the batch waits in the app's approval queue instead (`review_state: awaiting_approval`); the API can't approve it.\n\nWithout `items`, every pending update is included.\n\nScope: `updates:write`.", "tags": [ "Updates" ], "x-required-scopes": [ "updates:write" ], "parameters": [ { "$ref": "#/components/parameters/SitePath" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "minItems": 1, "maxItems": 100, "description": "Only these pending updates (from GET /updates/pending).", "items": { "type": "object", "required": [ "kind" ], "properties": { "kind": { "type": "string", "enum": [ "core", "plugin", "theme" ] }, "slug": { "type": [ "string", "null" ], "description": "The plugin file (\"akismet/akismet.php\") or theme folder. Not used for core." } } } }, "require_approval": { "type": "boolean", "default": false, "description": "Wait for a person to approve it in the app, whatever the site's policy says." } } }, "example": { "items": [ { "kind": "plugin", "slug": "woocommerce/woocommerce.php" } ], "require_approval": false } } } }, "responses": { "202": { "description": "Started, or waiting for approval.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/UpdateBatch" } } } } } }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Invalid" }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/updates/pending": { "get": { "operationId": "listPendingUpdates", "summary": "Pending updates", "description": "Connected sites with at least one pending update, and what is pending — as of each site's last sync. A page can hold fewer than `limit` entries while `has_more` is true; keep following `next_cursor`.\n\nScope: `updates:read`.", "tags": [ "Updates" ], "x-required-scopes": [ "updates:read" ], "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/SiteFilter" } ], "responses": { "200": { "description": "One page. Follow `meta.pagination.next_cursor` while `has_more` is true.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/PendingUpdates" } }, "meta": { "type": "object", "required": [ "pagination" ], "properties": { "pagination": { "$ref": "#/components/schemas/Pagination" } } } } } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/update-batches": { "get": { "operationId": "listUpdateBatches", "summary": "List update batches", "description": "Newest first.\n\nScope: `updates:read`.", "tags": [ "Updates" ], "x-required-scopes": [ "updates:read" ], "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/SiteFilter" }, { "name": "status", "in": "query", "required": false, "description": "Only batches with this status.", "schema": { "type": "string", "enum": [ "pending", "running", "completed", "failed" ] } }, { "name": "mode", "in": "query", "required": false, "description": "manual (started item by item in the app) or autopilot (the safe-update pipeline — scheduled, or started through this API).", "schema": { "type": "string", "enum": [ "manual", "autopilot" ] } } ], "responses": { "200": { "description": "One page. Follow `meta.pagination.next_cursor` while `has_more` is true.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/UpdateBatch" } }, "meta": { "type": "object", "required": [ "pagination" ], "properties": { "pagination": { "$ref": "#/components/schemas/Pagination" } } } } } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/update-batches/{batch}": { "get": { "operationId": "getUpdateBatch", "summary": "Get an update batch", "description": "Per-item results, the visual check and any rollback.\n\nScope: `updates:read`.", "tags": [ "Updates" ], "x-required-scopes": [ "updates:read" ], "parameters": [ { "name": "batch", "in": "path", "required": true, "description": "The update batch's id.", "schema": { "type": "integer", "minimum": 1 } } ], "responses": { "200": { "description": "OK.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/UpdateBatch" } } } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/backups": { "get": { "operationId": "listBackups", "summary": "List backups", "description": "Restore points, newest first.\n\nScope: `backups:read`.", "tags": [ "Backups" ], "x-required-scopes": [ "backups:read" ], "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/SiteFilter" }, { "name": "status", "in": "query", "required": false, "description": "Only backups with this status.", "schema": { "type": "string", "enum": [ "pending", "running", "completed", "failed" ] } }, { "name": "type", "in": "query", "required": false, "description": "Only this kind of backup.", "schema": { "type": "string", "enum": [ "manual", "scheduled", "pre_update", "pre_restore", "pre_cleanup" ] } } ], "responses": { "200": { "description": "One page. Follow `meta.pagination.next_cursor` while `has_more` is true.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Backup" } }, "meta": { "type": "object", "required": [ "pagination" ], "properties": { "pagination": { "$ref": "#/components/schemas/Pagination" } } } } } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/backups/{backup}": { "get": { "operationId": "getBackup", "summary": "Get a backup", "description": "One restore point.\n\nScope: `backups:read`.", "tags": [ "Backups" ], "x-required-scopes": [ "backups:read" ], "parameters": [ { "name": "backup", "in": "path", "required": true, "description": "The backup's id.", "schema": { "type": "integer", "minimum": 1 } } ], "responses": { "200": { "description": "OK.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Backup" } } } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/uptime": { "get": { "operationId": "listUptime", "summary": "Uptime status", "description": "Per site: whether it is monitored, up or down, the open incident and the last 30 days' uptime.\n\nScope: `uptime:read`.", "tags": [ "Uptime" ], "x-required-scopes": [ "uptime:read" ], "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/SiteFilter" } ], "responses": { "200": { "description": "One page. Follow `meta.pagination.next_cursor` while `has_more` is true.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/UptimeStatus" } }, "meta": { "type": "object", "required": [ "pagination" ], "properties": { "pagination": { "$ref": "#/components/schemas/Pagination" } } } } } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/uptime/incidents": { "get": { "operationId": "listIncidents", "summary": "List incidents", "description": "Newest first.\n\nScope: `uptime:read`.", "tags": [ "Uptime" ], "x-required-scopes": [ "uptime:read" ], "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/SiteFilter" }, { "name": "status", "in": "query", "required": false, "description": "open or resolved.", "schema": { "type": "string", "enum": [ "open", "resolved" ] } }, { "name": "check_type", "in": "query", "required": false, "description": "Only incidents from this kind of check.", "schema": { "type": "string", "enum": [ "http", "ssl", "domain" ] } } ], "responses": { "200": { "description": "One page. Follow `meta.pagination.next_cursor` while `has_more` is true.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Incident" } }, "meta": { "type": "object", "required": [ "pagination" ], "properties": { "pagination": { "$ref": "#/components/schemas/Pagination" } } } } } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/security/findings": { "get": { "operationId": "listSecurityFindings", "summary": "List security findings", "description": "Known vulnerabilities in what your sites run, newest first. Open ones unless `status` says otherwise.\n\nScope: `security:read`.", "tags": [ "Security" ], "x-required-scopes": [ "security:read" ], "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/SiteFilter" }, { "name": "status", "in": "query", "required": false, "description": "Default open; `all` for every finding.", "schema": { "type": "string", "enum": [ "open", "resolved", "ignored", "all" ] } }, { "name": "severity", "in": "query", "required": false, "description": "Only this severity.", "schema": { "type": "string", "enum": [ "critical", "high", "medium", "low", "unknown" ] } } ], "responses": { "200": { "description": "One page. Follow `meta.pagination.next_cursor` while `has_more` is true.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Finding" } }, "meta": { "type": "object", "required": [ "pagination" ], "properties": { "pagination": { "$ref": "#/components/schemas/Pagination" } } } } } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/clients": { "get": { "operationId": "listClients", "summary": "List clients", "description": "Oldest first.\n\nScope: `clients:read`.", "tags": [ "Clients" ], "x-required-scopes": [ "clients:read" ], "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "name": "q", "in": "query", "required": false, "description": "Name contains this text.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "One page. Follow `meta.pagination.next_cursor` while `has_more` is true.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Client" } }, "meta": { "type": "object", "required": [ "pagination" ], "properties": { "pagination": { "$ref": "#/components/schemas/Pagination" } } } } } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/clients/{client}": { "get": { "operationId": "getClient", "summary": "Get a client", "description": "With the client's sites.\n\nScope: `clients:read`.", "tags": [ "Clients" ], "x-required-scopes": [ "clients:read" ], "parameters": [ { "name": "client", "in": "path", "required": true, "description": "The client's id.", "schema": { "type": "integer", "minimum": 1 } } ], "responses": { "200": { "description": "OK.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "allOf": [ { "$ref": "#/components/schemas/Client" }, { "type": "object", "required": [ "sites" ], "properties": { "sites": { "type": "array", "items": { "$ref": "#/components/schemas/SiteSummary" } } } } ] } } } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/tickets": { "get": { "operationId": "listTickets", "summary": "List tickets", "description": "Newest first. 403 `help_desk_unavailable` when the organization doesn't have the help desk.\n\nScope: `tickets:read`.", "tags": [ "Tickets" ], "x-required-scopes": [ "tickets:read" ], "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/SiteFilter" }, { "name": "status", "in": "query", "required": false, "description": "One status, or `open` for everything not resolved or closed.", "schema": { "type": "string", "enum": [ "new", "diagnosing", "diagnosed", "awaiting_estimate", "estimated", "approved", "in_progress", "delivered", "resolved", "closed", "needs_human", "waiting_on_client", "open" ] } }, { "name": "client_id", "in": "query", "required": false, "description": "Only this client's tickets.", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "One page. Follow `meta.pagination.next_cursor` while `has_more` is true.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Ticket" } }, "meta": { "type": "object", "required": [ "pagination" ], "properties": { "pagination": { "$ref": "#/components/schemas/Pagination" } } } } } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "post": { "operationId": "createTicket", "summary": "Open a ticket", "description": "Opens a ticket for a client, as your team would in the help desk — written by the person who created the key (or the owner, once they have left). An automatic check runs unless `diagnose` is false.\n\nScope: `tickets:write`.", "tags": [ "Tickets" ], "x-required-scopes": [ "tickets:write" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "client_id", "title", "description" ], "properties": { "client_id": { "type": "integer" }, "site_id": { "type": [ "string", "null" ], "format": "uuid" }, "title": { "type": "string", "maxLength": 200 }, "description": { "type": "string", "maxLength": 20000 }, "page_url": { "type": [ "string", "null" ], "format": "uri" }, "priority": { "type": [ "string", "null" ], "enum": [ "low", "normal", "high", "urgent", null ] }, "category": { "type": [ "string", "null" ], "enum": [ "content_edit", "layout_bug", "plugin_conflict", "php_error", "performance", "form_broken", "ecommerce", "seo", "security", "hosting", "out_of_scope", "unclear", null ] }, "diagnose": { "type": "boolean", "default": true } } }, "example": { "client_id": 12, "site_id": "7f3c2a9e-1b4d-4c8a-9e2f-5a6b7c8d9e0f", "title": "Contact form not sending", "description": "Reported by phone: the contact form shows a spinner and never sends.", "priority": "high" } } } }, "responses": { "201": { "description": "Opened.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/TicketWithConversation" } } } } } }, "422": { "$ref": "#/components/responses/Invalid" }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/tickets/{ticket}": { "get": { "operationId": "getTicket", "summary": "Get a ticket", "description": "With its public conversation. Internal notes never appear in the API.\n\nScope: `tickets:read`.", "tags": [ "Tickets" ], "x-required-scopes": [ "tickets:read" ], "parameters": [ { "name": "ticket", "in": "path", "required": true, "description": "The ticket's id.", "schema": { "type": "integer", "minimum": 1 } } ], "responses": { "200": { "description": "OK.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/TicketWithConversation" } } } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/tickets/{ticket}/replies": { "post": { "operationId": "replyToTicket", "summary": "Reply on a ticket", "description": "Adds a message to the ticket's public conversation — the client sees it and is notified as for any reply from your team.\n\nScope: `tickets:write`.", "tags": [ "Tickets" ], "x-required-scopes": [ "tickets:write" ], "parameters": [ { "name": "ticket", "in": "path", "required": true, "description": "The ticket's id.", "schema": { "type": "integer", "minimum": 1 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "body" ], "properties": { "body": { "type": "string", "maxLength": 20000 } } }, "example": { "body": "Fixed — a caching plugin update had blocked the form. Could you try once more?" } } } }, "responses": { "201": { "description": "Posted.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/TicketReply" } } } } } }, "422": { "$ref": "#/components/responses/Invalid" }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/reports": { "get": { "operationId": "listReports", "summary": "List client reports", "description": "Newest first. A completed report carries `pdf.url`, a signed link that works for 15 minutes without the key.\n\nScope: `reports:read`.", "tags": [ "Reports" ], "x-required-scopes": [ "reports:read" ], "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/SiteFilter" }, { "name": "status", "in": "query", "required": false, "description": "Only reports with this status.", "schema": { "type": "string", "enum": [ "pending", "running", "completed", "failed" ] } } ], "responses": { "200": { "description": "One page. Follow `meta.pagination.next_cursor` while `has_more` is true.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Report" } }, "meta": { "type": "object", "required": [ "pagination" ], "properties": { "pagination": { "$ref": "#/components/schemas/Pagination" } } } } } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/reports/{report}": { "get": { "operationId": "getReport", "summary": "Get a client report", "description": "Fetch it again for a fresh `pdf.url`.\n\nScope: `reports:read`.", "tags": [ "Reports" ], "x-required-scopes": [ "reports:read" ], "parameters": [ { "name": "report", "in": "path", "required": true, "description": "The report's id.", "schema": { "type": "integer", "minimum": 1 } } ], "responses": { "200": { "description": "OK.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Report" } } } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/reports/{report}/pdf": { "get": { "operationId": "downloadReportPdf", "summary": "Download a report PDF (signed link)", "description": "The link in a report's `pdf.url`. Its signature is the credential — no API key is sent. It expires after 15 minutes (403 `link_expired`).", "tags": [ "Reports" ], "x-required-scopes": [], "parameters": [ { "name": "report", "in": "path", "required": true, "description": "The report's id.", "schema": { "type": "integer", "minimum": 1 } }, { "name": "expires", "in": "query", "required": true, "schema": { "type": "integer" } }, { "name": "signature", "in": "query", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "The PDF.", "content": { "application/pdf": { "schema": { "type": "string", "format": "binary" } } } }, "403": { "$ref": "#/components/responses/Forbidden" }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "security": [] } }, "/activity": { "get": { "operationId": "listActivity", "summary": "Activity Log", "description": "Newest first. Names and sentences only; IP and email addresses stay in the app's export.\n\nScope: `activity:read`.", "tags": [ "Activity" ], "x-required-scopes": [ "activity:read" ], "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/SiteFilter" }, { "name": "category", "in": "query", "required": false, "description": "Only this category.", "schema": { "type": "string", "enum": [ "content", "plugins", "themes", "users", "settings", "security", "core", "media", "system", "commerce", "support" ] } }, { "name": "source", "in": "query", "required": false, "description": "wordpress (from the site) or hub (from WPClientHub).", "schema": { "type": "string", "enum": [ "wordpress", "hub" ] } }, { "name": "action", "in": "query", "required": false, "description": "Only this action, e.g. backup.completed.", "schema": { "type": "string" } }, { "name": "since", "in": "query", "required": false, "description": "Only events at or after this time (ISO 8601).", "schema": { "type": "string", "format": "date-time" } } ], "responses": { "200": { "description": "One page. Follow `meta.pagination.next_cursor` while `has_more` is true.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/ActivityEvent" } }, "meta": { "type": "object", "required": [ "pagination" ], "properties": { "pagination": { "$ref": "#/components/schemas/Pagination" } } } } } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/sites/{site}/seo/pages": { "get": { "operationId": "listSeoPages", "summary": "List a site's pages with their SEO fields", "description": "Every published page and post of the site with its SEO fields (title, meta description, canonical, noindex/nofollow, social title/description/image, Twitter card) as WPClientHub last read them from the site — from the SEO plugin's own fields when Yoast SEO, Rank Math, All in One SEO or SEOPress runs the site. `effective_title` / `effective_description` are what the page actually gets (the plugin's template applied). Oldest first. Empty until the app has opened the site's SEO → Pages section once (which reads the pages from the site).\n\nScope: `seo:read`.", "tags": [ "SEO" ], "x-required-scopes": [ "seo:read" ], "parameters": [ { "$ref": "#/components/parameters/SitePath" }, { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "name": "type", "in": "query", "required": false, "description": "Only this post type (e.g. `page`, `post`, `product`).", "schema": { "type": "string" } }, { "name": "noindex", "in": "query", "required": false, "description": "`true` for only the pages set to noindex (their own field or their post type's default).", "schema": { "type": "string", "enum": [ "true", "false" ] } } ], "responses": { "200": { "description": "One page. Follow `meta.pagination.next_cursor` while `has_more` is true.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/SeoPage" } }, "meta": { "type": "object", "required": [ "pagination" ], "properties": { "pagination": { "$ref": "#/components/schemas/Pagination" } } } } } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/sites/{site}/seo/pages/{page}": { "patch": { "operationId": "updateSeoPage", "summary": "Change a page's SEO fields", "description": "Writes the fields you send to the site at once — into the SEO plugin's own fields when one runs the site — and keeps a revision (undoable in the app). Send only the fields to change; an empty string clears one. 409 `page_changed` when the page was changed on the site since it was last read (read it again first); 422 `unsupported` when the site's SEO plugin is one WPClientHub does not edit; 403 `plan_required` below Studio. Nothing is auto-generated: the values you send are what the page gets.\n\nScope: `seo:write`.", "tags": [ "SEO" ], "x-required-scopes": [ "seo:write" ], "parameters": [ { "$ref": "#/components/parameters/SitePath" }, { "name": "page", "in": "path", "required": true, "description": "The page's `post_id` (its WordPress post ID).", "schema": { "type": "integer", "minimum": 1 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "fields" ], "properties": { "fields": { "type": "object", "properties": { "title": { "type": [ "string", "null" ], "maxLength": 300 }, "description": { "type": [ "string", "null" ], "maxLength": 1000 }, "canonical": { "type": [ "string", "null" ], "format": "uri" }, "noindex": { "type": "boolean" }, "nofollow": { "type": "boolean" }, "og_title": { "type": [ "string", "null" ], "maxLength": 300 }, "og_description": { "type": [ "string", "null" ], "maxLength": 1000 }, "og_image": { "type": [ "string", "null" ], "format": "uri" }, "twitter_card": { "type": [ "string", "null" ], "enum": [ "", "summary", "summary_large_image", null ], "description": "Not stored per page by Yoast SEO or SEOPress (site-wide there)." } } } } }, "example": { "fields": { "title": "Emergency plumber in Leeds — 24/7 call-outs", "description": "Burst pipe or blocked drain? Our Leeds plumbers arrive within the hour, day or night. Fixed quotes, no call-out fee." } } } } }, "responses": { "200": { "description": "Applied — the page as it is now.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/SeoPage" } } } } } }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Invalid" }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/sites/{site}/seo/redirects": { "get": { "operationId": "listSeoRedirects", "summary": "List a site's redirects", "description": "The redirects WPClientHub manages on the site, oldest first, with the hit count the site reports.\n\nScope: `seo:read`.", "tags": [ "SEO" ], "x-required-scopes": [ "seo:read" ], "parameters": [ { "$ref": "#/components/parameters/SitePath" }, { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" } ], "responses": { "200": { "description": "One page. Follow `meta.pagination.next_cursor` while `has_more` is true.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/SeoRedirect" } }, "meta": { "type": "object", "required": [ "pagination" ], "properties": { "pagination": { "$ref": "#/components/schemas/Pagination" } } } } } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "post": { "operationId": "createSeoRedirect", "summary": "Add a redirect", "description": "Adds one redirect and sends the site its whole set. `source` is a path on the site (`/old-page`, with or without a trailing slash; a query string makes it match only that query) or, with `match: regex`, a regular expression. `target` is a path or a full URL (not needed for 410). 422 `duplicate_source` when the source already has a redirect, `redirect_loop` when it would lead back to itself, `invalid_redirect` otherwise; 403 `plan_required` below Studio.\n\nScope: `seo:write`.", "tags": [ "SEO" ], "x-required-scopes": [ "seo:write" ], "parameters": [ { "$ref": "#/components/parameters/SitePath" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "source" ], "properties": { "source": { "type": "string", "maxLength": 2048 }, "target": { "type": [ "string", "null" ], "maxLength": 2048 }, "code": { "type": "integer", "enum": [ 301, 302, 307, 308, 410 ], "default": 301 }, "match": { "type": "string", "enum": [ "exact", "regex" ], "default": "exact" }, "note": { "type": [ "string", "null" ], "maxLength": 200 } } }, "example": { "source": "/services/boiler-repairs", "target": "/boiler-repair", "code": 301, "note": "Old service page, merged in the October rebuild" } } } }, "responses": { "201": { "description": "Added.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/SeoRedirect" } } } } } }, "422": { "$ref": "#/components/responses/Invalid" }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/webhooks": { "get": { "operationId": "listWebhooks", "summary": "List webhook endpoints", "description": "Endpoints made in the app and through the API.\n\nScope: `webhooks:manage`.", "tags": [ "Webhooks" ], "x-required-scopes": [ "webhooks:manage" ], "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" } ], "responses": { "200": { "description": "One page. Follow `meta.pagination.next_cursor` while `has_more` is true.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/WebhookEndpoint" } }, "meta": { "type": "object", "required": [ "pagination" ], "properties": { "pagination": { "$ref": "#/components/schemas/Pagination" } } } } } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "post": { "operationId": "createWebhook", "summary": "Create a webhook endpoint", "description": "Subscribes a URL to events — what Zapier's REST hooks call. The answer carries the signing `secret`, once. An endpoint made with a key is switched off if that key is revoked.\n\nScope: `webhooks:manage`.", "tags": [ "Webhooks" ], "x-required-scopes": [ "webhooks:manage" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "url", "events" ], "properties": { "url": { "type": "string", "format": "uri", "description": "https only; must resolve to a public address." }, "events": { "type": "array", "minItems": 1, "items": { "type": "string", "enum": [ "site.down", "site.up", "backup.completed", "backup.failed", "update_batch.completed", "update_batch.failed", "vulnerability.found", "ticket.created", "ticket.replied", "domain.expiring", "form.entry_received" ] } }, "description": { "type": [ "string", "null" ], "maxLength": 200 } } }, "example": { "url": "https://hooks.zapier.com/hooks/standard/123456/abcdef/", "events": [ "site.down" ], "description": "Zap: page on-call when a site goes down" } } } }, "responses": { "201": { "description": "Created.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "allOf": [ { "$ref": "#/components/schemas/WebhookEndpoint" }, { "type": "object", "required": [ "secret" ], "properties": { "secret": { "type": "string", "description": "whsec_… — shown only in this response." } } } ] } } } } } }, "422": { "$ref": "#/components/responses/Invalid" }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/webhooks/{webhook}": { "get": { "operationId": "getWebhook", "summary": "Get a webhook endpoint", "description": "One endpoint.\n\nScope: `webhooks:manage`.", "tags": [ "Webhooks" ], "x-required-scopes": [ "webhooks:manage" ], "parameters": [ { "name": "webhook", "in": "path", "required": true, "description": "The endpoint's id (a UUID).", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/WebhookEndpoint" } } } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "patch": { "operationId": "updateWebhook", "summary": "Change a webhook endpoint", "description": "Change its URL, events or description, or switch it off and on (switching on starts a fresh failure count).\n\nScope: `webhooks:manage`.", "tags": [ "Webhooks" ], "x-required-scopes": [ "webhooks:manage" ], "parameters": [ { "name": "webhook", "in": "path", "required": true, "description": "The endpoint's id (a UUID).", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string", "format": "uri" }, "events": { "type": "array", "minItems": 1, "items": { "type": "string", "enum": [ "site.down", "site.up", "backup.completed", "backup.failed", "update_batch.completed", "update_batch.failed", "vulnerability.found", "ticket.created", "ticket.replied", "domain.expiring", "form.entry_received" ] } }, "description": { "type": [ "string", "null" ] }, "enabled": { "type": "boolean" } } }, "example": { "enabled": true } } } }, "responses": { "200": { "description": "OK.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/WebhookEndpoint" } } } } } }, "422": { "$ref": "#/components/responses/Invalid" }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "delete": { "operationId": "deleteWebhook", "summary": "Delete a webhook endpoint", "description": "Zapier's unsubscribe. Its delivery log goes with it.\n\nScope: `webhooks:manage`.", "tags": [ "Webhooks" ], "x-required-scopes": [ "webhooks:manage" ], "parameters": [ { "name": "webhook", "in": "path", "required": true, "description": "The endpoint's id (a UUID).", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "Deleted." }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/webhooks/{webhook}/test": { "post": { "operationId": "testWebhook", "summary": "Send a test event", "description": "Sends one example of an event (`\"test\": true` in the body), signed like the real thing, right now — the answer says how the receiver responded. Never retried.\n\nScope: `webhooks:manage`.", "tags": [ "Webhooks" ], "x-required-scopes": [ "webhooks:manage" ], "parameters": [ { "name": "webhook", "in": "path", "required": true, "description": "The endpoint's id (a UUID).", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "event": { "type": "string", "enum": [ "site.down", "site.up", "backup.completed", "backup.failed", "update_batch.completed", "update_batch.failed", "vulnerability.found", "ticket.created", "ticket.replied", "domain.expiring", "form.entry_received" ], "description": "Defaults to the endpoint's first event." } } }, "example": { "event": "site.down" } } } }, "responses": { "200": { "description": "OK.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/WebhookDelivery" } } } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } } } } }, "webhooks": { "site.down": { "post": { "operationId": "webhook_site_down", "summary": "Site down", "description": "A site stopped answering its uptime check and was still down at the confirmation recheck, about 3 minutes later.\n\nSigned: `X-WCH-Signature: t=,v1=.\" with the endpoint secret>`. Reject a `t` more than 5 minutes from your clock. Answer 2xx within 10 seconds; anything else is retried 7 more times over about 24 hours. 410 switches the endpoint off.", "tags": [ "Webhooks" ], "parameters": [ { "name": "X-WCH-Signature", "in": "header", "required": true, "schema": { "type": "string" }, "example": "t=1760000000,v1=5257a869e7ecebeda32affa62cdca3fa51cad7e77a0e56ff536d0ce8e108d8bd" }, { "name": "X-WCH-Event", "in": "header", "required": true, "schema": { "type": "string", "const": "site.down" } }, { "name": "X-WCH-Event-Id", "in": "header", "required": true, "description": "The same for every retry and redelivery — use it to de-duplicate.", "schema": { "type": "string" } }, { "name": "X-WCH-Delivery", "in": "header", "required": true, "description": "This delivery (a UUID).", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEvent" }, "example": { "id": "evt_3f0c1a2b4d5e4f60718293a4b5c6d7e8", "type": "site.down", "api_version": "v1", "created_at": "2026-10-07T09:14:03Z", "test": false, "organization": { "id": "0b5e1c2d-3f4a-4b6c-8d9e-0f1a2b3c4d5e", "name": "Northwind Studio" }, "data": { "site": { "id": "7f3c2a9e-1b4d-4c8a-9e2f-5a6b7c8d9e0f", "name": "Acme Bakery", "url": "https://acme-bakery.example", "client": { "id": 12, "name": "Acme Foods" }, "links": { "app": "https://app.wpclienthub.com/sites/42" } }, "incident": { "id": 8812, "site_id": "7f3c2a9e-1b4d-4c8a-9e2f-5a6b7c8d9e0f", "check_type": "http", "status": "open", "cause": "HTTP 503", "region": "eu-fsn", "started_at": "2026-10-07T08:41:00Z", "resolved_at": null, "duration_seconds": 190 } } } } } }, "responses": { "2XX": { "description": "Received. Anything else is retried." } } } }, "site.up": { "post": { "operationId": "webhook_site_up", "summary": "Site back up", "description": "A site that was reported down answers its uptime check again.\n\nSigned: `X-WCH-Signature: t=,v1=.\" with the endpoint secret>`. Reject a `t` more than 5 minutes from your clock. Answer 2xx within 10 seconds; anything else is retried 7 more times over about 24 hours. 410 switches the endpoint off.", "tags": [ "Webhooks" ], "parameters": [ { "name": "X-WCH-Signature", "in": "header", "required": true, "schema": { "type": "string" }, "example": "t=1760000000,v1=5257a869e7ecebeda32affa62cdca3fa51cad7e77a0e56ff536d0ce8e108d8bd" }, { "name": "X-WCH-Event", "in": "header", "required": true, "schema": { "type": "string", "const": "site.up" } }, { "name": "X-WCH-Event-Id", "in": "header", "required": true, "description": "The same for every retry and redelivery — use it to de-duplicate.", "schema": { "type": "string" } }, { "name": "X-WCH-Delivery", "in": "header", "required": true, "description": "This delivery (a UUID).", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEvent" }, "example": { "id": "evt_3f0c1a2b4d5e4f60718293a4b5c6d7e8", "type": "site.up", "api_version": "v1", "created_at": "2026-10-07T09:14:03Z", "test": false, "organization": { "id": "0b5e1c2d-3f4a-4b6c-8d9e-0f1a2b3c4d5e", "name": "Northwind Studio" }, "data": { "site": { "id": "7f3c2a9e-1b4d-4c8a-9e2f-5a6b7c8d9e0f", "name": "Acme Bakery", "url": "https://acme-bakery.example", "client": { "id": 12, "name": "Acme Foods" }, "links": { "app": "https://app.wpclienthub.com/sites/42" } }, "incident": { "id": 8812, "site_id": "7f3c2a9e-1b4d-4c8a-9e2f-5a6b7c8d9e0f", "check_type": "http", "status": "resolved", "cause": "HTTP 503", "region": "eu-fsn", "started_at": "2026-10-07T08:41:00Z", "resolved_at": "2026-10-07T08:53:30Z", "duration_seconds": 750 } } } } } }, "responses": { "2XX": { "description": "Received. Anything else is retried." } } } }, "backup.completed": { "post": { "operationId": "webhook_backup_completed", "summary": "Backup completed", "description": "A backup finished — manual, scheduled, or the restore point taken before updates.\n\nSigned: `X-WCH-Signature: t=,v1=.\" with the endpoint secret>`. Reject a `t` more than 5 minutes from your clock. Answer 2xx within 10 seconds; anything else is retried 7 more times over about 24 hours. 410 switches the endpoint off.", "tags": [ "Webhooks" ], "parameters": [ { "name": "X-WCH-Signature", "in": "header", "required": true, "schema": { "type": "string" }, "example": "t=1760000000,v1=5257a869e7ecebeda32affa62cdca3fa51cad7e77a0e56ff536d0ce8e108d8bd" }, { "name": "X-WCH-Event", "in": "header", "required": true, "schema": { "type": "string", "const": "backup.completed" } }, { "name": "X-WCH-Event-Id", "in": "header", "required": true, "description": "The same for every retry and redelivery — use it to de-duplicate.", "schema": { "type": "string" } }, { "name": "X-WCH-Delivery", "in": "header", "required": true, "description": "This delivery (a UUID).", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEvent" }, "example": { "id": "evt_3f0c1a2b4d5e4f60718293a4b5c6d7e8", "type": "backup.completed", "api_version": "v1", "created_at": "2026-10-07T09:14:03Z", "test": false, "organization": { "id": "0b5e1c2d-3f4a-4b6c-8d9e-0f1a2b3c4d5e", "name": "Northwind Studio" }, "data": { "site": { "id": "7f3c2a9e-1b4d-4c8a-9e2f-5a6b7c8d9e0f", "name": "Acme Bakery", "url": "https://acme-bakery.example", "client": { "id": 12, "name": "Acme Foods" }, "links": { "app": "https://app.wpclienthub.com/sites/42" } }, "backup": { "id": 5120, "site_id": "7f3c2a9e-1b4d-4c8a-9e2f-5a6b7c8d9e0f", "type": "scheduled", "status": "completed", "location": "both", "offsite": { "copied": true, "verified": true }, "restorable": true, "size_bytes": 418381022, "files_count": 12408, "error": null, "created_at": "2026-10-07T02:00:04Z", "updated_at": "2026-10-07T02:06:51Z" } } } } } }, "responses": { "2XX": { "description": "Received. Anything else is retried." } } } }, "backup.failed": { "post": { "operationId": "webhook_backup_failed", "summary": "Backup failed", "description": "A backup did not finish.\n\nSigned: `X-WCH-Signature: t=,v1=.\" with the endpoint secret>`. Reject a `t` more than 5 minutes from your clock. Answer 2xx within 10 seconds; anything else is retried 7 more times over about 24 hours. 410 switches the endpoint off.", "tags": [ "Webhooks" ], "parameters": [ { "name": "X-WCH-Signature", "in": "header", "required": true, "schema": { "type": "string" }, "example": "t=1760000000,v1=5257a869e7ecebeda32affa62cdca3fa51cad7e77a0e56ff536d0ce8e108d8bd" }, { "name": "X-WCH-Event", "in": "header", "required": true, "schema": { "type": "string", "const": "backup.failed" } }, { "name": "X-WCH-Event-Id", "in": "header", "required": true, "description": "The same for every retry and redelivery — use it to de-duplicate.", "schema": { "type": "string" } }, { "name": "X-WCH-Delivery", "in": "header", "required": true, "description": "This delivery (a UUID).", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEvent" }, "example": { "id": "evt_3f0c1a2b4d5e4f60718293a4b5c6d7e8", "type": "backup.failed", "api_version": "v1", "created_at": "2026-10-07T09:14:03Z", "test": false, "organization": { "id": "0b5e1c2d-3f4a-4b6c-8d9e-0f1a2b3c4d5e", "name": "Northwind Studio" }, "data": { "site": { "id": "7f3c2a9e-1b4d-4c8a-9e2f-5a6b7c8d9e0f", "name": "Acme Bakery", "url": "https://acme-bakery.example", "client": { "id": 12, "name": "Acme Foods" }, "links": { "app": "https://app.wpclienthub.com/sites/42" } }, "backup": { "id": 5120, "site_id": "7f3c2a9e-1b4d-4c8a-9e2f-5a6b7c8d9e0f", "type": "scheduled", "status": "failed", "location": "local", "offsite": { "copied": false, "verified": false }, "restorable": false, "size_bytes": null, "files_count": null, "error": "The site ran out of disk space while writing the archive.", "created_at": "2026-10-07T02:00:04Z", "updated_at": "2026-10-07T02:06:51Z" } } } } } }, "responses": { "2XX": { "description": "Received. Anything else is retried." } } } }, "update_batch.completed": { "post": { "operationId": "webhook_update_batch_completed", "summary": "Updates finished", "description": "An update batch finished. The visual check’s result is included when the safe-update pipeline ran.\n\nSigned: `X-WCH-Signature: t=,v1=.\" with the endpoint secret>`. Reject a `t` more than 5 minutes from your clock. Answer 2xx within 10 seconds; anything else is retried 7 more times over about 24 hours. 410 switches the endpoint off.", "tags": [ "Webhooks" ], "parameters": [ { "name": "X-WCH-Signature", "in": "header", "required": true, "schema": { "type": "string" }, "example": "t=1760000000,v1=5257a869e7ecebeda32affa62cdca3fa51cad7e77a0e56ff536d0ce8e108d8bd" }, { "name": "X-WCH-Event", "in": "header", "required": true, "schema": { "type": "string", "const": "update_batch.completed" } }, { "name": "X-WCH-Event-Id", "in": "header", "required": true, "description": "The same for every retry and redelivery — use it to de-duplicate.", "schema": { "type": "string" } }, { "name": "X-WCH-Delivery", "in": "header", "required": true, "description": "This delivery (a UUID).", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEvent" }, "example": { "id": "evt_3f0c1a2b4d5e4f60718293a4b5c6d7e8", "type": "update_batch.completed", "api_version": "v1", "created_at": "2026-10-07T09:14:03Z", "test": false, "organization": { "id": "0b5e1c2d-3f4a-4b6c-8d9e-0f1a2b3c4d5e", "name": "Northwind Studio" }, "data": { "site": { "id": "7f3c2a9e-1b4d-4c8a-9e2f-5a6b7c8d9e0f", "name": "Acme Bakery", "url": "https://acme-bakery.example", "client": { "id": 12, "name": "Acme Foods" }, "links": { "app": "https://app.wpclienthub.com/sites/42" } }, "batch": { "id": 2207, "site_id": "7f3c2a9e-1b4d-4c8a-9e2f-5a6b7c8d9e0f", "mode": "autopilot", "status": "completed", "review_state": "clean", "diff_percent": 0.42, "items": [ { "kind": "plugin", "slug": "woocommerce/woocommerce.php", "from_version": "9.3.1", "to_version": "9.3.3", "status": "succeeded", "error": null }, { "kind": "core", "slug": null, "from_version": "6.8.2", "to_version": "6.8.3", "status": "succeeded", "error": null } ], "rollback": null, "created_at": "2026-10-07T03:00:00Z", "updated_at": "2026-10-07T03:07:12Z", "links": { "app": "https://app.wpclienthub.com/sites/42?tab=updates" } } } } } } }, "responses": { "2XX": { "description": "Received. Anything else is retried." } } } }, "update_batch.failed": { "post": { "operationId": "webhook_update_batch_failed", "summary": "Updates failed", "description": "Every update in a batch failed, or the site could not be reached.\n\nSigned: `X-WCH-Signature: t=,v1=.\" with the endpoint secret>`. Reject a `t` more than 5 minutes from your clock. Answer 2xx within 10 seconds; anything else is retried 7 more times over about 24 hours. 410 switches the endpoint off.", "tags": [ "Webhooks" ], "parameters": [ { "name": "X-WCH-Signature", "in": "header", "required": true, "schema": { "type": "string" }, "example": "t=1760000000,v1=5257a869e7ecebeda32affa62cdca3fa51cad7e77a0e56ff536d0ce8e108d8bd" }, { "name": "X-WCH-Event", "in": "header", "required": true, "schema": { "type": "string", "const": "update_batch.failed" } }, { "name": "X-WCH-Event-Id", "in": "header", "required": true, "description": "The same for every retry and redelivery — use it to de-duplicate.", "schema": { "type": "string" } }, { "name": "X-WCH-Delivery", "in": "header", "required": true, "description": "This delivery (a UUID).", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEvent" }, "example": { "id": "evt_3f0c1a2b4d5e4f60718293a4b5c6d7e8", "type": "update_batch.failed", "api_version": "v1", "created_at": "2026-10-07T09:14:03Z", "test": false, "organization": { "id": "0b5e1c2d-3f4a-4b6c-8d9e-0f1a2b3c4d5e", "name": "Northwind Studio" }, "data": { "site": { "id": "7f3c2a9e-1b4d-4c8a-9e2f-5a6b7c8d9e0f", "name": "Acme Bakery", "url": "https://acme-bakery.example", "client": { "id": 12, "name": "Acme Foods" }, "links": { "app": "https://app.wpclienthub.com/sites/42" } }, "batch": { "id": 2207, "site_id": "7f3c2a9e-1b4d-4c8a-9e2f-5a6b7c8d9e0f", "mode": "autopilot", "status": "failed", "review_state": "needs_review", "diff_percent": null, "items": [ { "kind": "plugin", "slug": "woocommerce/woocommerce.php", "from_version": "9.3.1", "to_version": "9.3.3", "status": "failed", "error": "download_failed" }, { "kind": "core", "slug": null, "from_version": "6.8.2", "to_version": "6.8.3", "status": "failed", "error": "download_failed" } ], "rollback": null, "created_at": "2026-10-07T03:00:00Z", "updated_at": "2026-10-07T03:07:12Z", "links": { "app": "https://app.wpclienthub.com/sites/42?tab=updates" } } } } } } }, "responses": { "2XX": { "description": "Received. Anything else is retried." } } } }, "vulnerability.found": { "post": { "operationId": "webhook_vulnerability_found", "summary": "New vulnerability", "description": "A new security finding on a site, or one that came back after being fixed.\n\nSigned: `X-WCH-Signature: t=,v1=.\" with the endpoint secret>`. Reject a `t` more than 5 minutes from your clock. Answer 2xx within 10 seconds; anything else is retried 7 more times over about 24 hours. 410 switches the endpoint off.", "tags": [ "Webhooks" ], "parameters": [ { "name": "X-WCH-Signature", "in": "header", "required": true, "schema": { "type": "string" }, "example": "t=1760000000,v1=5257a869e7ecebeda32affa62cdca3fa51cad7e77a0e56ff536d0ce8e108d8bd" }, { "name": "X-WCH-Event", "in": "header", "required": true, "schema": { "type": "string", "const": "vulnerability.found" } }, { "name": "X-WCH-Event-Id", "in": "header", "required": true, "description": "The same for every retry and redelivery — use it to de-duplicate.", "schema": { "type": "string" } }, { "name": "X-WCH-Delivery", "in": "header", "required": true, "description": "This delivery (a UUID).", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEvent" }, "example": { "id": "evt_3f0c1a2b4d5e4f60718293a4b5c6d7e8", "type": "vulnerability.found", "api_version": "v1", "created_at": "2026-10-07T09:14:03Z", "test": false, "organization": { "id": "0b5e1c2d-3f4a-4b6c-8d9e-0f1a2b3c4d5e", "name": "Northwind Studio" }, "data": { "site": { "id": "7f3c2a9e-1b4d-4c8a-9e2f-5a6b7c8d9e0f", "name": "Acme Bakery", "url": "https://acme-bakery.example", "client": { "id": 12, "name": "Acme Foods" }, "links": { "app": "https://app.wpclienthub.com/sites/42" } }, "finding": { "id": 3317, "site_id": "7f3c2a9e-1b4d-4c8a-9e2f-5a6b7c8d9e0f", "component": { "kind": "plugin", "slug": "contact-form-7", "installed_version": "5.9.2" }, "title": "Contact Form 7 < 5.9.5 - Unauthenticated Open Redirect", "severity": "medium", "cvss": 6.1, "cve_id": "CVE-2024-4704", "fixed_in": "5.9.5", "status": "open", "source_url": "https://patchstack.com/database/vulnerability/contact-form-7", "first_detected_at": "2026-10-07T09:14:03Z", "resolved_at": null } } } } } }, "responses": { "2XX": { "description": "Received. Anything else is retried." } } } }, "ticket.created": { "post": { "operationId": "webhook_ticket_created", "summary": "New ticket", "description": "A help desk ticket was opened — by a client in the portal, by your team, or through the API.\n\nSigned: `X-WCH-Signature: t=,v1=.\" with the endpoint secret>`. Reject a `t` more than 5 minutes from your clock. Answer 2xx within 10 seconds; anything else is retried 7 more times over about 24 hours. 410 switches the endpoint off.", "tags": [ "Webhooks" ], "parameters": [ { "name": "X-WCH-Signature", "in": "header", "required": true, "schema": { "type": "string" }, "example": "t=1760000000,v1=5257a869e7ecebeda32affa62cdca3fa51cad7e77a0e56ff536d0ce8e108d8bd" }, { "name": "X-WCH-Event", "in": "header", "required": true, "schema": { "type": "string", "const": "ticket.created" } }, { "name": "X-WCH-Event-Id", "in": "header", "required": true, "description": "The same for every retry and redelivery — use it to de-duplicate.", "schema": { "type": "string" } }, { "name": "X-WCH-Delivery", "in": "header", "required": true, "description": "This delivery (a UUID).", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEvent" }, "example": { "id": "evt_3f0c1a2b4d5e4f60718293a4b5c6d7e8", "type": "ticket.created", "api_version": "v1", "created_at": "2026-10-07T09:14:03Z", "test": false, "organization": { "id": "0b5e1c2d-3f4a-4b6c-8d9e-0f1a2b3c4d5e", "name": "Northwind Studio" }, "data": { "ticket": { "id": 731, "number": 58, "reference": "#58", "title": "Contact form not sending", "description": "Since this morning the contact form on /contact shows a spinner and never sends.", "status": "new", "priority": "high", "category": "form_broken", "source": "client", "page_url": "https://acme-bakery.example/contact", "client": { "id": 12, "name": "Acme Foods" }, "site": { "id": "7f3c2a9e-1b4d-4c8a-9e2f-5a6b7c8d9e0f", "name": "Acme Bakery", "url": "https://acme-bakery.example" }, "assignee": null, "created_at": "2026-10-07T09:58:12Z", "updated_at": "2026-10-07T09:58:12Z", "links": { "helpdesk": "https://helpdesk.wpclienthub.com/requests/731" } } } } } } }, "responses": { "2XX": { "description": "Received. Anything else is retried." } } } }, "ticket.replied": { "post": { "operationId": "webhook_ticket_replied", "summary": "Ticket reply", "description": "A new message on a ticket’s public conversation, from the client or your team. Internal notes never fire it.\n\nSigned: `X-WCH-Signature: t=,v1=.\" with the endpoint secret>`. Reject a `t` more than 5 minutes from your clock. Answer 2xx within 10 seconds; anything else is retried 7 more times over about 24 hours. 410 switches the endpoint off.", "tags": [ "Webhooks" ], "parameters": [ { "name": "X-WCH-Signature", "in": "header", "required": true, "schema": { "type": "string" }, "example": "t=1760000000,v1=5257a869e7ecebeda32affa62cdca3fa51cad7e77a0e56ff536d0ce8e108d8bd" }, { "name": "X-WCH-Event", "in": "header", "required": true, "schema": { "type": "string", "const": "ticket.replied" } }, { "name": "X-WCH-Event-Id", "in": "header", "required": true, "description": "The same for every retry and redelivery — use it to de-duplicate.", "schema": { "type": "string" } }, { "name": "X-WCH-Delivery", "in": "header", "required": true, "description": "This delivery (a UUID).", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEvent" }, "example": { "id": "evt_3f0c1a2b4d5e4f60718293a4b5c6d7e8", "type": "ticket.replied", "api_version": "v1", "created_at": "2026-10-07T09:14:03Z", "test": false, "organization": { "id": "0b5e1c2d-3f4a-4b6c-8d9e-0f1a2b3c4d5e", "name": "Northwind Studio" }, "data": { "ticket": { "id": 731, "number": 58, "reference": "#58", "title": "Contact form not sending", "description": "Since this morning the contact form on /contact shows a spinner and never sends.", "status": "new", "priority": "high", "category": "form_broken", "source": "client", "page_url": "https://acme-bakery.example/contact", "client": { "id": 12, "name": "Acme Foods" }, "site": { "id": "7f3c2a9e-1b4d-4c8a-9e2f-5a6b7c8d9e0f", "name": "Acme Bakery", "url": "https://acme-bakery.example" }, "assignee": null, "created_at": "2026-10-07T09:58:12Z", "updated_at": "2026-10-07T09:58:12Z", "links": { "helpdesk": "https://helpdesk.wpclienthub.com/requests/731" } }, "reply": { "id": 9051, "author": { "type": "client", "name": "Dana Ruiz" }, "body": "Thanks — the form sends again. Could you also check the shop page on mobile?", "created_at": "2026-10-07T10:02:41Z" } } } } } }, "responses": { "2XX": { "description": "Received. Anything else is retried." } } } }, "domain.expiring": { "post": { "operationId": "webhook_domain_expiring", "summary": "Domain expiring", "description": "A site’s domain is 30, 14, 7, 3 or 1 day from expiring, or has expired.\n\nSigned: `X-WCH-Signature: t=,v1=.\" with the endpoint secret>`. Reject a `t` more than 5 minutes from your clock. Answer 2xx within 10 seconds; anything else is retried 7 more times over about 24 hours. 410 switches the endpoint off.", "tags": [ "Webhooks" ], "parameters": [ { "name": "X-WCH-Signature", "in": "header", "required": true, "schema": { "type": "string" }, "example": "t=1760000000,v1=5257a869e7ecebeda32affa62cdca3fa51cad7e77a0e56ff536d0ce8e108d8bd" }, { "name": "X-WCH-Event", "in": "header", "required": true, "schema": { "type": "string", "const": "domain.expiring" } }, { "name": "X-WCH-Event-Id", "in": "header", "required": true, "description": "The same for every retry and redelivery — use it to de-duplicate.", "schema": { "type": "string" } }, { "name": "X-WCH-Delivery", "in": "header", "required": true, "description": "This delivery (a UUID).", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEvent" }, "example": { "id": "evt_3f0c1a2b4d5e4f60718293a4b5c6d7e8", "type": "domain.expiring", "api_version": "v1", "created_at": "2026-10-07T09:14:03Z", "test": false, "organization": { "id": "0b5e1c2d-3f4a-4b6c-8d9e-0f1a2b3c4d5e", "name": "Northwind Studio" }, "data": { "site": { "id": "7f3c2a9e-1b4d-4c8a-9e2f-5a6b7c8d9e0f", "name": "Acme Bakery", "url": "https://acme-bakery.example", "client": { "id": 12, "name": "Acme Foods" }, "links": { "app": "https://app.wpclienthub.com/sites/42" } }, "domain": { "name": "acme-bakery.example", "expires_at": "2026-10-21T00:00:00Z", "days_left": 14, "threshold_days": 14, "registrar": "Example Registrar, Inc.", "registrar_url": "https://registrar.example" } } } } } }, "responses": { "2XX": { "description": "Received. Anything else is retried." } } } }, "form.entry_received": { "post": { "operationId": "webhook_form_entry_received", "summary": "Form entry received", "description": "A new entry on a form — one built with WPClientHub, or one of Gravity Forms, WPForms, Fluent Forms, Contact Form 7 (Flamingo) or Ninja Forms — reached the Forms inbox (Agency and above). Spam is not sent.\n\nSigned: `X-WCH-Signature: t=,v1=.\" with the endpoint secret>`. Reject a `t` more than 5 minutes from your clock. Answer 2xx within 10 seconds; anything else is retried 7 more times over about 24 hours. 410 switches the endpoint off.", "tags": [ "Webhooks" ], "parameters": [ { "name": "X-WCH-Signature", "in": "header", "required": true, "schema": { "type": "string" }, "example": "t=1760000000,v1=5257a869e7ecebeda32affa62cdca3fa51cad7e77a0e56ff536d0ce8e108d8bd" }, { "name": "X-WCH-Event", "in": "header", "required": true, "schema": { "type": "string", "const": "form.entry_received" } }, { "name": "X-WCH-Event-Id", "in": "header", "required": true, "description": "The same for every retry and redelivery — use it to de-duplicate.", "schema": { "type": "string" } }, { "name": "X-WCH-Delivery", "in": "header", "required": true, "description": "This delivery (a UUID).", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEvent" }, "example": { "id": "evt_3f0c1a2b4d5e4f60718293a4b5c6d7e8", "type": "form.entry_received", "api_version": "v1", "created_at": "2026-10-07T09:14:03Z", "test": false, "organization": { "id": "0b5e1c2d-3f4a-4b6c-8d9e-0f1a2b3c4d5e", "name": "Northwind Studio" }, "data": { "site": { "id": "7f3c2a9e-1b4d-4c8a-9e2f-5a6b7c8d9e0f", "name": "Acme Bakery", "url": "https://acme-bakery.example", "client": { "id": 12, "name": "Acme Foods" }, "links": { "app": "https://app.wpclienthub.com/sites/42" } }, "form": { "id": "2f6c1a0e-7b3d-4e9a-9c21-5d8f0a1b2c3d", "title": "Contact form", "source": "wpch", "source_name": "WPClientHub", "status": "published", "entries_count": 128, "unread_count": 3, "last_entry_at": "2026-10-07T11:42:18Z", "shortcode": "[wpclienthub_form id=\"12\"]", "links": { "app": "https://app.wpclienthub.com/forms?site=42&form=2f6c1a0e-7b3d-4e9a-9c21-5d8f0a1b2c3d" } }, "entry": { "id": 9120, "form_id": "2f6c1a0e-7b3d-4e9a-9c21-5d8f0a1b2c3d", "source": "wpch", "status": "new", "submitted_at": "2026-10-07T11:42:18Z", "page_url": "https://acme-bakery.example/contact?utm_source=newsletter", "utm": { "utm_source": "newsletter" }, "fields": [ { "id": "name", "key": "your_name", "label": "Your name", "type": "text", "value": "Dana Ruiz" }, { "id": "email", "key": "email_address", "label": "Email address", "type": "email", "value": "dana@example.com" }, { "id": "message", "key": "message", "label": "Message", "type": "textarea", "value": "Could you quote a redesign of the shop page?" }, { "id": "files", "key": "brief", "label": "Brief", "type": "file", "value": [ { "name": "brief.pdf", "size": 182044, "type": "application/pdf" } ] } ], "has_files": true, "ticket": null, "links": { "app": "https://app.wpclienthub.com/forms?entry=9120" } } } } } } }, "responses": { "2XX": { "description": "Received. Anything else is retried." } } } } }, "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "wch_live_ followed by 40 characters", "description": "An API key from Settings → API keys. Shown once when created; only its prefix and last four characters are visible afterwards." } }, "headers": { "RateLimitLimit": { "description": "Requests this key may make a minute.", "schema": { "type": "integer" } }, "RateLimitRemaining": { "description": "Requests left in the current minute.", "schema": { "type": "integer" } }, "RateLimitReset": { "description": "Unix time the window resets.", "schema": { "type": "integer" } } }, "parameters": { "SitePath": { "name": "site", "in": "path", "required": true, "description": "The site's id (a UUID, from GET /sites).", "schema": { "type": "string", "format": "uuid" } }, "SiteFilter": { "name": "site_id", "in": "query", "required": false, "description": "Only this site (its UUID).", "schema": { "type": "string", "format": "uuid" } }, "Limit": { "name": "limit", "in": "query", "required": false, "description": "Page size, 1–100.", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25 } }, "Cursor": { "name": "cursor", "in": "query", "required": false, "description": "The `next_cursor` of the previous page.", "schema": { "type": "string" } } }, "responses": { "Unauthenticated": { "description": "No key, or a key that is not valid, revoked (`api_key_revoked`) or expired (`api_key_expired`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "invalid_api_key", "message": "This API key is not valid. Check that it was copied in full, or create a new one in Settings → API keys.", "details": null } } } } }, "Forbidden": { "description": "The key lacks a scope (`insufficient_scope`), the organization is no longer on Scale (`plan_required` — the key is kept and works again on Scale), the help desk is off (`help_desk_unavailable`) or the account is suspended.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "insufficient_scope", "message": "This API key does not have the sites:write scope.", "details": { "required": [ "sites:write" ], "granted": [ "sites:read" ] } } } } } }, "NotFound": { "description": "No such resource in this organization. Another organization's id looks exactly like one that never existed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "not_found", "message": "No such site.", "details": null } } } } }, "Conflict": { "description": "It can't start right now: `site_not_connected`, `backup_in_progress`, `restore_in_progress`, `update_batch_in_progress`, `no_pending_updates`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "backup_in_progress", "message": "A backup is already in progress for this site.", "details": null } } } } }, "Invalid": { "description": "The request is not valid. `validation_failed` lists the problems by field in `details`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "validation_failed", "message": "The request is not valid. See details for each field.", "details": { "title": [ "The title field is required." ] } } } } } }, "RateLimited": { "description": "Too many requests for this key this minute.", "headers": { "Retry-After": { "description": "Seconds until the key may call again.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "rate_limited", "message": "Too many requests — this key may make 120 a minute. Try again in 12 seconds.", "details": { "limit": 120, "retry_after": 12 } } } } } } }, "schemas": { "Error": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "details" ], "properties": { "code": { "type": "string", "description": "Stable and machine-readable." }, "message": { "type": "string", "description": "A sentence for a person." }, "details": { "type": [ "object", "null" ], "description": "Validation errors by field, the scopes needed, a retry delay — or null." } } } } }, "Pagination": { "type": "object", "required": [ "limit", "has_more", "next_cursor" ], "properties": { "limit": { "type": "integer" }, "has_more": { "type": "boolean" }, "next_cursor": { "type": [ "string", "null" ] } } }, "Organization": { "type": "object", "required": [ "id", "name", "plan", "timezone" ], "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "plan": { "type": "string", "enum": [ "free", "studio", "agency", "scale" ] }, "timezone": { "type": "string" } } }, "ApiKey": { "type": "object", "required": [ "id", "name", "prefix", "masked", "scopes", "rate_limit_per_minute", "expires_at", "last_used_at", "created_at" ], "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "prefix": { "type": "string", "description": "wch_live_ plus the key's first four characters." }, "masked": { "type": "string", "example": "wch_live_8KfQ…a1B2" }, "scopes": { "type": "array", "items": { "type": "string", "enum": [ "sites:read", "sites:write", "updates:read", "updates:write", "backups:read", "backups:write", "uptime:read", "security:read", "clients:read", "tickets:read", "tickets:write", "reports:read", "forms:read", "activity:read", "seo:read", "seo:write", "webhooks:manage" ] } }, "rate_limit_per_minute": { "type": "integer" }, "expires_at": { "type": [ "string", "null" ], "format": "date-time" }, "last_used_at": { "type": [ "string", "null" ], "format": "date-time" }, "created_at": { "type": [ "string", "null" ], "format": "date-time" } } }, "EventType": { "type": "object", "required": [ "type", "label", "description", "example" ], "properties": { "type": { "type": "string", "enum": [ "site.down", "site.up", "backup.completed", "backup.failed", "update_batch.completed", "update_batch.failed", "vulnerability.found", "ticket.created", "ticket.replied", "domain.expiring", "form.entry_received" ] }, "label": { "type": "string" }, "description": { "type": "string" }, "example": { "type": "object" } } }, "SiteSummary": { "type": "object", "required": [ "id", "name", "url", "client", "links" ], "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "url": { "type": "string", "format": "uri" }, "client": { "type": [ "object", "null" ], "properties": { "id": { "type": "integer" }, "name": { "type": "string" } } }, "links": { "type": "object", "required": [ "app" ], "properties": { "app": { "type": "string", "format": "uri" } } } }, "example": { "id": "7f3c2a9e-1b4d-4c8a-9e2f-5a6b7c8d9e0f", "name": "Acme Bakery", "url": "https://acme-bakery.example", "client": { "id": 12, "name": "Acme Foods" }, "links": { "app": "https://app.wpclienthub.com/sites/42" } } }, "Site": { "type": "object", "required": [ "id", "name", "url", "status", "client", "labels", "health_score", "wordpress_version", "php_version", "connector", "pending_updates", "last_backup", "uptime", "last_synced_at", "created_at", "links" ], "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "url": { "type": "string", "format": "uri" }, "status": { "type": "string", "enum": [ "pending", "connected", "disconnected", "suspended" ] }, "client": { "type": [ "object", "null" ], "properties": { "id": { "type": "integer" }, "name": { "type": "string" } } }, "labels": { "type": "array", "items": { "type": "string" } }, "health_score": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 100 }, "wordpress_version": { "type": [ "string", "null" ] }, "php_version": { "type": [ "string", "null" ] }, "connector": { "type": "object", "required": [ "version", "distribution" ], "properties": { "version": { "type": [ "string", "null" ] }, "distribution": { "type": [ "string", "null" ] } } }, "pending_updates": { "type": "object", "required": [ "total", "core", "plugins", "themes" ], "properties": { "total": { "type": "integer" }, "core": { "type": "boolean" }, "plugins": { "type": "integer" }, "themes": { "type": "integer" } } }, "last_backup": { "type": [ "object", "null" ], "properties": { "id": { "type": "integer" }, "type": { "type": "string" }, "completed_at": { "type": [ "string", "null" ], "format": "date-time" }, "size_bytes": { "type": [ "integer", "null" ] } } }, "uptime": { "type": "object", "required": [ "monitored", "status", "down_since", "open_incident_id" ], "properties": { "monitored": { "type": "boolean" }, "status": { "type": "string", "enum": [ "up", "down", "not_monitored" ] }, "down_since": { "type": [ "string", "null" ], "format": "date-time" }, "open_incident_id": { "type": [ "integer", "null" ] } } }, "last_synced_at": { "type": [ "string", "null" ], "format": "date-time" }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "links": { "type": "object", "required": [ "app" ], "properties": { "app": { "type": "string", "format": "uri" } } } }, "example": { "id": "7f3c2a9e-1b4d-4c8a-9e2f-5a6b7c8d9e0f", "name": "Acme Bakery", "url": "https://acme-bakery.example", "status": "connected", "client": { "id": 12, "name": "Acme Foods" }, "labels": [ "woocommerce", "care-plan" ], "health_score": 86, "wordpress_version": "6.8.2", "php_version": "8.3.12", "connector": { "version": "0.13.0", "distribution": "wporg" }, "pending_updates": { "total": 3, "core": true, "plugins": 2, "themes": 0 }, "last_backup": { "id": 5120, "type": "scheduled", "completed_at": "2026-10-07T02:06:51Z", "size_bytes": 418381022 }, "uptime": { "monitored": true, "status": "up", "down_since": null, "open_incident_id": null }, "last_synced_at": "2026-10-07T09:00:12Z", "created_at": "2026-03-14T11:20:00Z", "links": { "app": "https://app.wpclienthub.com/sites/42" } } }, "QueuedAction": { "type": "object", "required": [ "site_id", "action", "status" ], "properties": { "site_id": { "type": "string", "format": "uuid" }, "action": { "type": "string", "enum": [ "sync", "check_updates" ] }, "status": { "type": "string", "const": "queued" } } }, "PendingUpdates": { "type": "object", "required": [ "site", "checked_at", "items" ], "properties": { "site": { "$ref": "#/components/schemas/SiteSummary" }, "checked_at": { "type": [ "string", "null" ], "format": "date-time" }, "items": { "type": "array", "items": { "type": "object", "required": [ "kind", "slug", "name", "from_version", "to_version" ], "properties": { "kind": { "type": "string", "enum": [ "core", "plugin", "theme" ] }, "slug": { "type": [ "string", "null" ] }, "name": { "type": [ "string", "null" ] }, "from_version": { "type": [ "string", "null" ] }, "to_version": { "type": [ "string", "null" ] } } } } } }, "UpdateBatch": { "type": "object", "required": [ "id", "site_id", "mode", "status", "review_state", "diff_percent", "items", "rollback", "created_at", "updated_at", "links" ], "properties": { "id": { "type": "integer" }, "site_id": { "type": [ "string", "null" ], "format": "uuid" }, "mode": { "type": "string", "enum": [ "manual", "autopilot" ] }, "status": { "type": "string", "enum": [ "pending", "running", "completed", "failed" ] }, "review_state": { "type": [ "string", "null" ], "description": "The safe-update pipeline: awaiting_approval, released, screenshotting, clean or needs_review." }, "diff_percent": { "type": [ "number", "null" ], "description": "Largest share of the page that changed in the before/after screenshots." }, "items": { "type": "array", "items": { "type": "object", "required": [ "kind", "slug", "from_version", "to_version", "status", "error" ], "properties": { "kind": { "type": "string", "enum": [ "core", "plugin", "theme" ] }, "slug": { "type": [ "string", "null" ] }, "from_version": { "type": [ "string", "null" ] }, "to_version": { "type": [ "string", "null" ] }, "status": { "type": "string", "enum": [ "pending", "running", "succeeded", "failed", "skipped" ] }, "error": { "type": [ "string", "null" ] } } } }, "rollback": { "type": [ "object", "null" ], "properties": { "state": { "type": "string" }, "error": { "type": [ "string", "null" ] }, "rolled_back_at": { "type": [ "string", "null" ], "format": "date-time" } } }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" }, "links": { "type": "object", "required": [ "app" ], "properties": { "app": { "type": [ "string", "null" ], "format": "uri" } } } }, "example": { "id": 2207, "site_id": "7f3c2a9e-1b4d-4c8a-9e2f-5a6b7c8d9e0f", "mode": "autopilot", "status": "completed", "review_state": "clean", "diff_percent": 0.42, "items": [ { "kind": "plugin", "slug": "woocommerce/woocommerce.php", "from_version": "9.3.1", "to_version": "9.3.3", "status": "succeeded", "error": null }, { "kind": "core", "slug": null, "from_version": "6.8.2", "to_version": "6.8.3", "status": "succeeded", "error": null } ], "rollback": null, "created_at": "2026-10-07T03:00:00Z", "updated_at": "2026-10-07T03:07:12Z", "links": { "app": "https://app.wpclienthub.com/sites/42?tab=updates" } } }, "Backup": { "type": "object", "required": [ "id", "site_id", "type", "status", "location", "offsite", "restorable", "size_bytes", "files_count", "error", "created_at", "updated_at" ], "properties": { "id": { "type": "integer" }, "site_id": { "type": [ "string", "null" ], "format": "uuid" }, "type": { "type": "string", "enum": [ "manual", "scheduled", "pre_update", "pre_restore", "pre_cleanup" ] }, "status": { "type": "string", "enum": [ "pending", "running", "completed", "failed" ] }, "location": { "type": "string", "enum": [ "local", "offsite", "both" ] }, "offsite": { "type": "object", "required": [ "copied", "verified" ], "properties": { "copied": { "type": "boolean" }, "verified": { "type": "boolean" } } }, "restorable": { "type": "boolean" }, "size_bytes": { "type": [ "integer", "null" ] }, "files_count": { "type": [ "integer", "null" ] }, "error": { "type": [ "string", "null" ] }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" } }, "example": { "id": 5120, "site_id": "7f3c2a9e-1b4d-4c8a-9e2f-5a6b7c8d9e0f", "type": "scheduled", "status": "completed", "location": "both", "offsite": { "copied": true, "verified": true }, "restorable": true, "size_bytes": 418381022, "files_count": 12408, "error": null, "created_at": "2026-10-07T02:00:04Z", "updated_at": "2026-10-07T02:06:51Z" } }, "Incident": { "type": "object", "required": [ "id", "site_id", "check_type", "status", "cause", "region", "started_at", "resolved_at", "duration_seconds" ], "properties": { "id": { "type": "integer" }, "site_id": { "type": [ "string", "null" ], "format": "uuid" }, "check_type": { "type": [ "string", "null" ], "enum": [ "http", "ssl", "domain", null ] }, "status": { "type": "string", "enum": [ "open", "resolved" ] }, "cause": { "type": [ "string", "null" ] }, "region": { "type": [ "string", "null" ] }, "started_at": { "type": [ "string", "null" ], "format": "date-time" }, "resolved_at": { "type": [ "string", "null" ], "format": "date-time" }, "duration_seconds": { "type": [ "integer", "null" ] } }, "example": { "id": 8812, "site_id": "7f3c2a9e-1b4d-4c8a-9e2f-5a6b7c8d9e0f", "check_type": "http", "status": "resolved", "cause": "HTTP 503", "region": "eu-fsn", "started_at": "2026-10-07T08:41:00Z", "resolved_at": "2026-10-07T08:53:30Z", "duration_seconds": 750 } }, "SiteImages": { "type": "object", "required": [ "site_id", "state", "enabled", "handled_by", "engine", "formats", "images", "optimized", "skipped", "before_bytes", "after_bytes", "saved_bytes", "saved_percent", "webp_files", "avif_files", "serving", "reported_at", "links" ], "properties": { "site_id": { "type": "string", "format": "uuid" }, "state": { "type": "string", "enum": [ "handled_by_us", "handled_by_other", "off", "not_entitled", "connector_too_old", "not_connected" ], "description": "handled_by_us: WPClientHub optimizes this site's images. handled_by_other: another optimizer plugin is active (see handled_by). not_entitled: the organization is below the Agency plan." }, "enabled": { "type": "boolean" }, "handled_by": { "type": [ "string", "null" ] }, "engine": { "type": [ "string", "null" ], "enum": [ "imagick", "gd", "none", null ], "description": "The image library on the site's server." }, "formats": { "type": "object", "required": [ "webp", "avif" ], "properties": { "webp": { "type": "object", "required": [ "enabled", "supported" ], "properties": { "enabled": { "type": "boolean" }, "supported": { "type": [ "boolean", "null" ] } } }, "avif": { "type": "object", "required": [ "enabled", "supported" ], "properties": { "enabled": { "type": "boolean" }, "supported": { "type": [ "boolean", "null" ], "description": "null until the site has reported; false when its PHP cannot encode AVIF." } } } } }, "images": { "type": "integer", "description": "Images in the media library (JPEG, PNG, GIF, WebP, AVIF)." }, "optimized": { "type": "integer" }, "skipped": { "type": "integer" }, "before_bytes": { "type": "integer" }, "after_bytes": { "type": "integer" }, "saved_bytes": { "type": "integer" }, "saved_percent": { "type": [ "number", "null" ] }, "webp_files": { "type": "integer", "description": "WebP copies written (every size counts)." }, "avif_files": { "type": "integer" }, "serving": { "type": [ "string", "null" ], "enum": [ "htaccess", "rewrite", "off", null ] }, "reported_at": { "type": [ "string", "null" ], "format": "date-time" }, "links": { "type": "object", "required": [ "app" ], "properties": { "app": { "type": "string", "format": "uri" } } } }, "example": { "site_id": "7f3c2a9e-1b4d-4c8a-9e2f-5a6b7c8d9e0f", "state": "handled_by_us", "enabled": true, "handled_by": null, "engine": "imagick", "formats": { "webp": { "enabled": true, "supported": true }, "avif": { "enabled": true, "supported": false } }, "images": 1312, "optimized": 1240, "skipped": 31, "before_bytes": 804000000, "after_bytes": 492000000, "saved_bytes": 312000000, "saved_percent": 38.8, "webp_files": 6200, "avif_files": 0, "serving": "htaccess", "reported_at": "2026-10-08T02:14:09+00:00", "links": { "app": "https://app.wpclienthub.com/sites/42?tab=images" } } }, "SiteCache": { "type": "object", "required": [ "site_id", "state", "enabled", "handled_by", "ttl_hours", "delivery", "pages", "bytes", "hits_7d", "misses_7d", "hit_ratio_7d", "last_purged_at", "last_purge_reason", "reported_at", "links" ], "properties": { "site_id": { "type": "string", "format": "uuid" }, "state": { "type": "string", "enum": [ "on", "pending", "blocked", "handled_by_other", "off", "connector_too_old", "not_connected" ], "description": "on: WPClientHub's page cache serves this site. pending: switched on, the site has not applied it yet. blocked: switched on but something on the site is in the way (another plugin's advanced-cache.php, WP_CACHE false, permissions). handled_by_other: another cache plugin or the host caches pages (see handled_by); purges still reach it." }, "enabled": { "type": "boolean", "description": "The switch in WPClientHub." }, "handled_by": { "type": [ "string", "null" ] }, "ttl_hours": { "type": "integer", "description": "Pages expire after this many hours." }, "delivery": { "type": [ "string", "null" ], "enum": [ "php", "server", null ], "description": "php: the advanced-cache.php drop-in answers cached pages. server: Apache/LiteSpeed answers them from .htaccess rules (self-checked)." }, "pages": { "type": "integer", "description": "Cached pages on disk as last reported." }, "bytes": { "type": "integer" }, "hits_7d": { "type": "integer", "description": "Page views answered from the cache in the last seven days." }, "misses_7d": { "type": "integer", "description": "Page views WordPress rendered (and the cache then stored) in the last seven days." }, "hit_ratio_7d": { "type": [ "number", "null" ], "description": "hits ÷ (hits + misses), in percent; null without data." }, "last_purged_at": { "type": [ "string", "null" ], "format": "date-time" }, "last_purge_reason": { "type": [ "string", "null" ] }, "reported_at": { "type": [ "string", "null" ], "format": "date-time" }, "links": { "type": "object", "required": [ "app" ], "properties": { "app": { "type": "string", "format": "uri" } } } }, "example": { "site_id": "7f3c2a9e-1b4d-4c8a-9e2f-5a6b7c8d9e0f", "state": "on", "enabled": true, "handled_by": null, "ttl_hours": 10, "delivery": "php", "pages": 184, "bytes": 9800000, "hits_7d": 12410, "misses_7d": 1320, "hit_ratio_7d": 90.4, "last_purged_at": "2026-10-08T09:12:40+00:00", "last_purge_reason": "after update batch #12", "reported_at": "2026-10-08T10:00:03+00:00", "links": { "app": "https://app.wpclienthub.com/sites/42?tab=performance" } } }, "CachePurge": { "type": "object", "required": [ "site_id", "action", "status", "scope", "urls", "ignored", "purged" ], "properties": { "site_id": { "type": "string", "format": "uuid" }, "action": { "type": "string", "enum": [ "cache_purge" ] }, "status": { "type": "string", "enum": [ "purged", "recent" ], "description": "recent: everything was purged within the last minute already (the site does that itself after an update or a restore), so nothing stale was left to remove." }, "scope": { "type": "string", "enum": [ "all", "urls" ] }, "urls": { "type": "array", "items": { "type": "string", "format": "uri" } }, "ignored": { "type": "array", "description": "Addresses that are not this site's.", "items": { "type": "string" } }, "purged": { "type": "array", "description": "What was purged: \"wpclienthub\" for WPClientHub's own page cache, else the plugin or host name.", "items": { "type": "string" } } }, "example": { "site_id": "7f3c2a9e-1b4d-4c8a-9e2f-5a6b7c8d9e0f", "action": "cache_purge", "status": "purged", "scope": "all", "urls": [], "ignored": [], "purged": [ "wpclienthub" ] } }, "SeoPage": { "type": "object", "required": [ "site_id", "post_id", "type", "post_title", "url", "fields", "effective_title", "effective_description", "noindex", "key_page", "modified_at", "synced_at", "links" ], "properties": { "site_id": { "type": "string", "format": "uuid" }, "post_id": { "type": "integer", "description": "The WordPress post ID." }, "type": { "type": "string", "description": "The post type: page, post, product …" }, "post_title": { "type": "string" }, "url": { "type": "string", "format": "uri" }, "fields": { "type": "object", "required": [ "title", "description", "canonical", "noindex", "nofollow", "og_title", "og_description", "og_image", "twitter_card" ], "properties": { "title": { "type": "string" }, "description": { "type": "string" }, "canonical": { "type": "string" }, "noindex": { "type": "boolean" }, "nofollow": { "type": "boolean" }, "og_title": { "type": "string" }, "og_description": { "type": "string" }, "og_image": { "type": "string" }, "twitter_card": { "type": "string", "enum": [ "", "summary", "summary_large_image" ] } } }, "effective_title": { "type": [ "string", "null" ], "description": "The title the page actually gets (the template applied); null when the site could not say." }, "effective_description": { "type": [ "string", "null" ] }, "noindex": { "type": "boolean", "description": "The page's own field or its post type's default in the SEO plugin." }, "key_page": { "type": [ "string", "null" ], "description": "Why this page matters (\"Home page\", \"In the “Primary” menu\") — or null." }, "modified_at": { "type": [ "string", "null" ], "format": "date-time" }, "synced_at": { "type": [ "string", "null" ], "format": "date-time", "description": "When WPClientHub last read these fields from the site." }, "links": { "type": "object", "required": [ "app" ], "properties": { "app": { "type": "string", "format": "uri" } } } }, "example": { "site_id": "7f3c2a9e-1b4d-4c8a-9e2f-5a6b7c8d9e0f", "post_id": 42, "type": "page", "post_title": "Boiler repair", "url": "https://acme-plumbing.example/boiler-repair/", "fields": { "title": "Boiler repair in Leeds — same-day engineers", "description": "Gas Safe engineers for every make of boiler, usually the same day. Fixed quotes before any work starts.", "canonical": "", "noindex": false, "nofollow": false, "og_title": "", "og_description": "", "og_image": "", "twitter_card": "" }, "effective_title": "Boiler repair in Leeds — same-day engineers", "effective_description": "Gas Safe engineers for every make of boiler, usually the same day. Fixed quotes before any work starts.", "noindex": false, "key_page": "In the “Primary” menu", "modified_at": "2026-10-02T14:11:08+00:00", "synced_at": "2026-10-08T09:00:12+00:00", "links": { "app": "https://app.wpclienthub.com/sites/42?tab=seo&seo=pages" } } }, "SeoRedirect": { "type": "object", "required": [ "id", "site_id", "source", "match", "target", "code", "hits", "last_hit_at", "note", "created_at" ], "properties": { "id": { "type": "integer" }, "site_id": { "type": "string", "format": "uuid" }, "source": { "type": "string", "description": "A path on the site, or a regular expression when match is regex." }, "match": { "type": "string", "enum": [ "exact", "regex" ] }, "target": { "type": [ "string", "null" ], "description": "A path or a full URL; null for 410." }, "code": { "type": "integer", "enum": [ 301, 302, 307, 308, 410 ] }, "hits": { "type": "integer", "description": "Times the site followed it, as last reported." }, "last_hit_at": { "type": [ "string", "null" ], "format": "date-time" }, "note": { "type": [ "string", "null" ] }, "created_at": { "type": [ "string", "null" ], "format": "date-time" } }, "example": { "id": 318, "site_id": "7f3c2a9e-1b4d-4c8a-9e2f-5a6b7c8d9e0f", "source": "/services/boiler-repairs", "match": "exact", "target": "/boiler-repair", "code": 301, "hits": 212, "last_hit_at": "2026-10-08T08:41:03+00:00", "note": "Old service page, merged in the October rebuild", "created_at": "2026-10-01T10:02:00+00:00" } }, "Form": { "type": "object", "required": [ "id", "title", "source", "source_name", "status", "entries_count", "unread_count", "last_entry_at", "shortcode", "links" ], "properties": { "id": { "type": "string", "format": "uuid" }, "title": { "type": "string" }, "source": { "type": "string", "enum": [ "wpch", "gravity", "wpforms", "fluent", "flamingo", "ninja" ], "description": "wpch: built with WPClientHub. Anything else: another plugin's form WPClientHub One reads." }, "source_name": { "type": "string" }, "status": { "type": "string", "enum": [ "draft", "published", "external" ], "description": "external: another plugin's form (always live there)." }, "entries_count": { "type": "integer" }, "unread_count": { "type": "integer" }, "last_entry_at": { "type": [ "string", "null" ], "format": "date-time" }, "shortcode": { "type": [ "string", "null" ], "description": "For a WPClientHub form that reached the site." }, "links": { "type": "object", "required": [ "app" ], "properties": { "app": { "type": "string", "format": "uri" } } } }, "example": { "id": "2f6c1a0e-7b3d-4e9a-9c21-5d8f0a1b2c3d", "title": "Contact form", "source": "wpch", "source_name": "WPClientHub", "status": "published", "entries_count": 128, "unread_count": 3, "last_entry_at": "2026-10-07T11:42:18Z", "shortcode": "[wpclienthub_form id=\"12\"]", "links": { "app": "https://app.wpclienthub.com/forms?site=42&form=2f6c1a0e-7b3d-4e9a-9c21-5d8f0a1b2c3d" } } }, "FormEntryField": { "type": "object", "required": [ "id", "key", "label", "type", "value" ], "properties": { "id": { "type": "string" }, "key": { "type": "string", "description": "The merge-tag key ({field:key})." }, "label": { "type": "string" }, "type": { "type": "string" }, "value": { "description": "A string; a list of strings for checkboxes; for a file field a list of {name, size, type}.", "oneOf": [ { "type": "string" }, { "type": "array", "items": { "oneOf": [ { "type": "string" }, { "type": "object", "properties": { "name": { "type": "string" }, "size": { "type": "integer" }, "type": { "type": "string" } } } ] } } ] } } }, "FormEntry": { "type": "object", "required": [ "id", "form_id", "source", "status", "submitted_at", "page_url", "utm", "fields", "has_files", "ticket", "links" ], "properties": { "id": { "type": "integer" }, "form_id": { "type": [ "string", "null" ], "format": "uuid" }, "source": { "type": "string" }, "status": { "type": "string", "enum": [ "new", "read", "spam" ] }, "submitted_at": { "type": [ "string", "null" ], "format": "date-time" }, "page_url": { "type": [ "string", "null" ] }, "utm": { "type": [ "object", "null" ], "additionalProperties": { "type": "string" } }, "fields": { "type": "array", "items": { "$ref": "#/components/schemas/FormEntryField" } }, "has_files": { "type": "boolean" }, "ticket": { "type": [ "object", "null" ], "properties": { "id": { "type": "integer" } }, "description": "The help-desk ticket made from this entry, if any." }, "links": { "type": "object", "required": [ "app" ], "properties": { "app": { "type": "string", "format": "uri" } } } }, "example": { "id": 9120, "form_id": "2f6c1a0e-7b3d-4e9a-9c21-5d8f0a1b2c3d", "source": "wpch", "status": "new", "submitted_at": "2026-10-07T11:42:18Z", "page_url": "https://acme-bakery.example/contact?utm_source=newsletter", "utm": { "utm_source": "newsletter" }, "fields": [ { "id": "name", "key": "your_name", "label": "Your name", "type": "text", "value": "Dana Ruiz" }, { "id": "email", "key": "email_address", "label": "Email address", "type": "email", "value": "dana@example.com" }, { "id": "message", "key": "message", "label": "Message", "type": "textarea", "value": "Could you quote a redesign of the shop page?" }, { "id": "files", "key": "brief", "label": "Brief", "type": "file", "value": [ { "name": "brief.pdf", "size": 182044, "type": "application/pdf" } ] } ], "has_files": true, "ticket": null, "links": { "app": "https://app.wpclienthub.com/forms?entry=9120" } } }, "UptimeStatus": { "type": "object", "required": [ "site", "monitored", "status", "open_incident", "uptime_30d_pct" ], "properties": { "site": { "$ref": "#/components/schemas/SiteSummary" }, "monitored": { "type": "boolean" }, "status": { "type": "string", "enum": [ "up", "down", "not_monitored" ] }, "open_incident": { "oneOf": [ { "$ref": "#/components/schemas/Incident" }, { "type": "null" } ] }, "uptime_30d_pct": { "type": [ "number", "null" ] } } }, "Finding": { "type": "object", "required": [ "id", "site_id", "component", "title", "severity", "cvss", "cve_id", "fixed_in", "status", "source_url", "first_detected_at", "resolved_at" ], "properties": { "id": { "type": "integer" }, "site_id": { "type": [ "string", "null" ], "format": "uuid" }, "component": { "type": "object", "required": [ "kind", "slug", "installed_version" ], "properties": { "kind": { "type": [ "string", "null" ], "enum": [ "core", "plugin", "theme", null ] }, "slug": { "type": [ "string", "null" ] }, "installed_version": { "type": [ "string", "null" ] } } }, "title": { "type": [ "string", "null" ] }, "severity": { "type": [ "string", "null" ], "enum": [ "critical", "high", "medium", "low", "unknown", null ] }, "cvss": { "type": [ "number", "null" ] }, "cve_id": { "type": [ "string", "null" ] }, "fixed_in": { "type": [ "string", "null" ] }, "status": { "type": [ "string", "null" ], "enum": [ "open", "resolved", "ignored", null ] }, "source_url": { "type": [ "string", "null" ] }, "first_detected_at": { "type": [ "string", "null" ], "format": "date-time" }, "resolved_at": { "type": [ "string", "null" ], "format": "date-time" } }, "example": { "id": 3317, "site_id": "7f3c2a9e-1b4d-4c8a-9e2f-5a6b7c8d9e0f", "component": { "kind": "plugin", "slug": "contact-form-7", "installed_version": "5.9.2" }, "title": "Contact Form 7 < 5.9.5 - Unauthenticated Open Redirect", "severity": "medium", "cvss": 6.1, "cve_id": "CVE-2024-4704", "fixed_in": "5.9.5", "status": "open", "source_url": "https://patchstack.com/database/vulnerability/contact-form-7", "first_detected_at": "2026-10-07T09:14:03Z", "resolved_at": null } }, "Client": { "type": "object", "required": [ "id", "name", "email", "phone", "sites_count", "created_at" ], "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "email": { "type": [ "string", "null" ] }, "phone": { "type": [ "string", "null" ] }, "sites_count": { "type": "integer" }, "created_at": { "type": [ "string", "null" ], "format": "date-time" } } }, "Ticket": { "type": "object", "required": [ "id", "number", "reference", "title", "description", "status", "priority", "category", "source", "page_url", "client", "site", "assignee", "created_at", "updated_at", "links" ], "properties": { "id": { "type": "integer" }, "number": { "type": "integer" }, "reference": { "type": "string" }, "title": { "type": "string" }, "description": { "type": "string" }, "status": { "type": "string", "enum": [ "new", "diagnosing", "diagnosed", "awaiting_estimate", "estimated", "approved", "in_progress", "delivered", "resolved", "closed", "needs_human", "waiting_on_client" ] }, "priority": { "type": "string", "enum": [ "low", "normal", "high", "urgent" ] }, "category": { "type": [ "string", "null" ], "enum": [ "content_edit", "layout_bug", "plugin_conflict", "php_error", "performance", "form_broken", "ecommerce", "seo", "security", "hosting", "out_of_scope", "unclear", null ] }, "source": { "type": "string", "enum": [ "client", "agency", "lead_magnet" ] }, "page_url": { "type": [ "string", "null" ] }, "client": { "type": [ "object", "null" ], "properties": { "id": { "type": "integer" }, "name": { "type": "string" } } }, "site": { "type": [ "object", "null" ], "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "url": { "type": "string" } } }, "assignee": { "type": [ "object", "null" ], "properties": { "id": { "type": "integer" }, "name": { "type": "string" } } }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" }, "links": { "type": "object", "required": [ "helpdesk" ], "properties": { "helpdesk": { "type": "string", "format": "uri" } } } }, "example": { "id": 731, "number": 58, "reference": "#58", "title": "Contact form not sending", "description": "Since this morning the contact form on /contact shows a spinner and never sends.", "status": "new", "priority": "high", "category": "form_broken", "source": "client", "page_url": "https://acme-bakery.example/contact", "client": { "id": 12, "name": "Acme Foods" }, "site": { "id": "7f3c2a9e-1b4d-4c8a-9e2f-5a6b7c8d9e0f", "name": "Acme Bakery", "url": "https://acme-bakery.example" }, "assignee": null, "created_at": "2026-10-07T09:58:12Z", "updated_at": "2026-10-07T09:58:12Z", "links": { "helpdesk": "https://helpdesk.wpclienthub.com/requests/731" } } }, "TicketReply": { "type": "object", "required": [ "id", "author", "body", "created_at" ], "properties": { "id": { "type": "integer" }, "author": { "type": "object", "required": [ "type", "name" ], "properties": { "type": { "type": "string", "enum": [ "client", "agency", "system" ] }, "name": { "type": [ "string", "null" ] } } }, "body": { "type": "string" }, "created_at": { "type": [ "string", "null" ], "format": "date-time" } }, "example": { "id": 9051, "author": { "type": "client", "name": "Dana Ruiz" }, "body": "Thanks — the form sends again. Could you also check the shop page on mobile?", "created_at": "2026-10-07T10:02:41Z" } }, "TicketWithConversation": { "allOf": [ { "$ref": "#/components/schemas/Ticket" }, { "type": "object", "required": [ "conversation" ], "properties": { "conversation": { "type": "array", "items": { "$ref": "#/components/schemas/TicketReply" } } } } ] }, "Report": { "type": "object", "required": [ "id", "site_id", "site_name", "period_start", "period_end", "status", "error", "sent_to", "pdf", "created_at" ], "properties": { "id": { "type": "integer" }, "site_id": { "type": [ "string", "null" ], "format": "uuid" }, "site_name": { "type": [ "string", "null" ] }, "period_start": { "type": [ "string", "null" ], "format": "date" }, "period_end": { "type": [ "string", "null" ], "format": "date" }, "status": { "type": "string", "enum": [ "pending", "running", "completed", "failed" ] }, "error": { "type": [ "string", "null" ] }, "sent_to": { "type": "array", "items": { "type": "string" } }, "pdf": { "type": [ "object", "null" ], "properties": { "url": { "type": "string", "format": "uri" }, "expires_at": { "type": [ "string", "null" ], "format": "date-time" } } }, "created_at": { "type": [ "string", "null" ], "format": "date-time" } } }, "ActivityEvent": { "type": "object", "required": [ "id", "occurred_at", "site", "source", "category", "action", "summary", "actor", "object" ], "properties": { "id": { "type": "integer" }, "occurred_at": { "type": [ "string", "null" ], "format": "date-time" }, "site": { "type": [ "object", "null" ], "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" } } }, "source": { "type": [ "string", "null" ], "enum": [ "wordpress", "hub", null ] }, "category": { "type": [ "string", "null" ], "enum": [ "content", "plugins", "themes", "users", "settings", "security", "core", "media", "system", "commerce", "support", null ] }, "action": { "type": "string" }, "summary": { "type": "string" }, "actor": { "type": "object", "required": [ "type", "name" ], "properties": { "type": { "type": [ "string", "null" ] }, "name": { "type": [ "string", "null" ] } } }, "object": { "type": [ "object", "null" ], "properties": { "type": { "type": "string" }, "id": { "type": [ "string", "null" ] }, "title": { "type": [ "string", "null" ] } } } } }, "WebhookEndpoint": { "type": "object", "required": [ "id", "url", "description", "events", "enabled", "disabled_reason", "source", "last_delivery_at", "last_success_at", "last_response_status", "created_at" ], "properties": { "id": { "type": "string", "format": "uuid" }, "url": { "type": "string", "format": "uri" }, "description": { "type": [ "string", "null" ] }, "events": { "type": "array", "items": { "type": "string", "enum": [ "site.down", "site.up", "backup.completed", "backup.failed", "update_batch.completed", "update_batch.failed", "vulnerability.found", "ticket.created", "ticket.replied", "domain.expiring", "form.entry_received" ] } }, "enabled": { "type": "boolean" }, "disabled_reason": { "type": [ "string", "null" ] }, "source": { "type": "string", "enum": [ "app", "api" ] }, "last_delivery_at": { "type": [ "string", "null" ], "format": "date-time" }, "last_success_at": { "type": [ "string", "null" ], "format": "date-time" }, "last_response_status": { "type": [ "integer", "null" ] }, "created_at": { "type": [ "string", "null" ], "format": "date-time" } } }, "WebhookDelivery": { "type": "object", "required": [ "id", "event_id", "event_type", "status", "attempts", "response_status", "error", "duration_ms", "next_attempt_at", "last_attempt_at", "test", "created_at" ], "properties": { "id": { "type": "string", "format": "uuid" }, "event_id": { "type": [ "string", "null" ] }, "event_type": { "type": "string" }, "status": { "type": "string", "enum": [ "pending", "sending", "retrying", "succeeded", "failed", "cancelled" ] }, "attempts": { "type": "integer" }, "response_status": { "type": [ "integer", "null" ] }, "error": { "type": [ "string", "null" ] }, "duration_ms": { "type": [ "integer", "null" ] }, "next_attempt_at": { "type": [ "string", "null" ], "format": "date-time" }, "last_attempt_at": { "type": [ "string", "null" ], "format": "date-time" }, "test": { "type": "boolean" }, "created_at": { "type": [ "string", "null" ], "format": "date-time" } } }, "WebhookEvent": { "type": "object", "required": [ "id", "type", "api_version", "created_at", "test", "organization", "data" ], "properties": { "id": { "type": "string", "description": "evt_… — the same on every retry; de-duplicate on it." }, "type": { "type": "string", "enum": [ "site.down", "site.up", "backup.completed", "backup.failed", "update_batch.completed", "update_batch.failed", "vulnerability.found", "ticket.created", "ticket.replied", "domain.expiring", "form.entry_received" ] }, "api_version": { "type": "string", "const": "v1" }, "created_at": { "type": "string", "format": "date-time" }, "test": { "type": "boolean", "description": "true for \"Send test event\" — example data, not your sites." }, "organization": { "type": "object", "required": [ "id", "name" ], "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" } } }, "data": { "type": "object", "description": "site.*: {site, incident} · backup.*: {site, backup} · update_batch.*: {site, batch} · vulnerability.found: {site, finding} · ticket.created: {ticket} · ticket.replied: {ticket, reply} · domain.expiring: {site, domain}." } } } } } }