{ "openapi": "3.1.0", "info": { "title": "SiteVitals", "version": "1.0.0", "description": "The SiteVitals API gives you programmatic access to your site health data.\nUse it to pull live health snapshots into your own tools, dashboards, or AI workflows.\n\n## Authentication\nAll endpoints require a Bearer token. Generate and manage your keys at\n[sitevitals.co.uk\/settings\/api](https:\/\/www.sitevitals.co.uk\/settings\/api).\n\nInclude your token on every request:\n\n```\nAuthorization: Bearer \n```\n\n## Token Scopes\n- **Account-level** \u2014 access all sites in your account\n- **Site-level** \u2014 restricted to a single site; ideal for sharing with third parties\n\n## Testing\nUse the built-in [API Tester](\/settings\/api\/test) to fire live requests\nagainst your own data without needing an external client." }, "servers": [ { "url": "https:\/\/www.sitevitals.co.uk\/api\/v1" } ], "security": [ { "http": [] } ], "paths": { "\/tokens": { "get": { "operationId": "apiKeys.index", "description": "Returns all API keys for the authenticated user.\nThe sensitive token value is never returned after initial creation.", "summary": "List API keys", "tags": [ "API Keys" ], "responses": { "200": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "scope": { "type": "string", "enum": [ "account", "site" ] }, "site_id": { "type": [ "integer", "null" ] }, "last_used_at": { "type": [ "string", "null" ] }, "expires_at": { "type": [ "string", "null" ] }, "created_at": { "type": "string" } }, "required": [ "id", "name", "scope", "site_id", "last_used_at", "expires_at", "created_at" ] } } }, "required": [ "data" ] } } } }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" } } } }, "\/pages": { "get": { "operationId": "pages.index", "description": "Returns all monitored pages accessible to the authenticated user,\nincluding both owned pages and pages shared with you as a collaborator.\n\n> **Page-level tokens** cannot use this endpoint \u2014 they are already\n> scoped to a single page. Use `GET \/api\/v1\/pages\/{page}\/health` directly.", "summary": "List pages", "tags": [ "Pages" ], "responses": { "200": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "url": { "type": "string" }, "name": { "type": [ "string", "null" ] }, "platform": { "type": [ "string", "null" ] }, "role": { "type": "string", "enum": [ "owner", "collaborator" ] }, "is_up": { "type": [ "boolean", "null" ] }, "is_ssl_valid": { "type": "boolean" }, "scores": { "type": "object", "properties": { "uptime": { "type": [ "integer", "null" ] }, "seo": { "type": [ "integer", "null" ] }, "security": { "type": [ "integer", "null" ] }, "integrity": { "type": [ "integer", "null" ] }, "speed": { "type": [ "integer", "null" ] }, "content": { "type": [ "integer", "null" ] } }, "required": [ "uptime", "seo", "security", "integrity", "speed", "content" ] }, "health_endpoint": { "type": "string" }, "created_at": { "type": "string" } }, "required": [ "id", "url", "name", "platform", "role", "is_up", "is_ssl_valid", "scores", "health_endpoint", "created_at" ] } }, "meta": { "type": "object", "properties": { "total": { "type": "integer" } }, "required": [ "total" ] } }, "required": [ "data", "meta" ] } } } }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" } } } }, "\/portfolio\/health": { "get": { "operationId": "portfolioHealth.show", "description": "Returns a full account-wide health rollup, grouped by property.\nSites not assigned to a property appear under an \"ungrouped\" bucket.\nRequires an account-level token.", "summary": "Portfolio health overview", "tags": [ "PortfolioHealth" ], "parameters": [ { "name": "verbose", "in": "query", "schema": { "type": "string", "default": false } } ], "responses": { "200": { "description": "", "content": { "application\/json": { "schema": { "type": "integer", "const": 200 } } } }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" } } } }, "\/properties\/{property}\/health": { "get": { "operationId": "propertyHealth.show", "description": "Returns an aggregated health snapshot for all sites within a property.\nRequires an account-level token (scoped site tokens are not permitted).", "summary": "Property health summary", "tags": [ "PropertyHealth" ], "parameters": [ { "name": "property", "in": "path", "required": true, "description": "The property ID", "schema": { "type": "integer" } }, { "name": "verbose", "in": "query", "schema": { "type": "string", "default": false } } ], "responses": { "200": { "description": "", "content": { "application\/json": { "schema": { "type": "integer", "const": 200 } } } }, "404": { "$ref": "#\/components\/responses\/ModelNotFoundException" }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" } } } }, "\/server-metrics": { "post": { "operationId": "serverMetrics.store", "description": "Authenticated via AuthenticateServerAgent middleware (Bearer API key).\nStores the check, evaluates thresholds, manages incidents,\nevaluates service status changes, creates timeline events,\nand dispatches alert job.", "summary": "POST \/api\/v1\/server-metrics", "tags": [ "ServerMetrics" ], "requestBody": { "required": true, "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/StoreServerMetricsRequest" } } } }, "responses": { "200": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "const": "ok" } }, "required": [ "status" ] } } } }, "422": { "$ref": "#\/components\/responses\/ValidationException" } } } }, "\/server-services\/discover": { "post": { "operationId": "serverService.discover", "description": "Receives the list of services discovered by the agent on first run\n(or on re-scan). Upserts them into server_monitored_services, marking\nknown-interesting services as recommended and pre-enabling them.\n\nThe user then sees a checklist in the dashboard to confirm\/adjust.", "summary": "POST \/api\/v1\/server-services\/discover", "tags": [ "ServerService" ], "requestBody": { "required": true, "content": { "application\/json": { "schema": { "type": "object", "properties": { "services": { "type": "array", "items": { "type": "string", "maxLength": 100 }, "minItems": 1, "maxItems": 200 } }, "required": [ "services" ] } } } }, "responses": { "200": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "const": "ok" }, "count": { "type": "integer" } }, "required": [ "status", "count" ] } } } }, "422": { "$ref": "#\/components\/responses\/ValidationException" } } } }, "\/server-config": { "get": { "operationId": "serverService.config", "description": "Returns the current agent configuration \u2014 specifically the list of\nenabled services to monitor. The agent fetches this after the user\nsaves their service selection in the dashboard.", "summary": "GET \/api\/v1\/server-config", "tags": [ "ServerService" ], "responses": { "200": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "monitored_services": { "type": "string" } }, "required": [ "monitored_services" ] } } } } } } }, "\/pages\/{page}\/health": { "get": { "operationId": "siteHealth.show", "description": "Returns a health snapshot for the given page. By default the response is\ncompact and token-efficient \u2014 designed for LLM consumption. Add\n`?verbose=true` to receive the full payload including score history,\nuptime check logs, and up to 25 recent drift events.\n\nBoth account-level and page-level tokens can access this endpoint.", "summary": "Page health snapshot", "tags": [ "SiteHealth" ], "parameters": [ { "name": "page", "in": "path", "required": true, "description": "The page ID", "schema": { "type": "integer" } }, { "name": "verbose", "in": "query", "schema": { "type": "string", "default": false } } ], "responses": { "200": { "description": "", "content": { "application\/json": { "schema": { "type": "integer", "const": 200 } } } }, "404": { "$ref": "#\/components\/responses\/ModelNotFoundException" }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" } } } }, "\/pages\/{page}\/wordpress-events": { "post": { "operationId": "wordpressEvents.store", "tags": [ "WordpressEvents" ], "parameters": [ { "name": "page", "in": "path", "required": true, "description": "The page ID", "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application\/json": { "schema": { "type": "object", "properties": { "event_type": { "type": "string", "description": "Core fields \u2014 required", "enum": [ "core_update", "plugin_update", "theme_update" ] }, "name": { "type": "string", "maxLength": 125 }, "slug": { "type": "string", "maxLength": 125 }, "from_version": { "type": "string", "maxLength": 50 }, "to_version": { "type": "string", "maxLength": 50 }, "triggered_by": { "type": "string", "enum": [ "auto_update", "manual" ] }, "status": { "type": "string", "enum": [ "success", "failed" ] }, "version_jump": { "type": [ "string", "null" ], "description": "Diagnostic fields \u2014 optional (sent by plugin v0.3.0+)", "enum": [ "major", "minor", "patch", "unknown" ] }, "author": { "type": [ "string", "null" ], "maxLength": 125 }, "requires_wp": { "type": [ "string", "null" ], "maxLength": 20 }, "requires_php": { "type": [ "string", "null" ], "maxLength": 20 }, "tested_up_to": { "type": [ "string", "null" ], "maxLength": 20 }, "update_type": { "type": [ "string", "null" ], "maxLength": 50 } }, "required": [ "event_type", "name", "slug", "from_version", "to_version", "triggered_by", "status" ] } } } }, "responses": { "201": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "const": "Event received." } }, "required": [ "message" ] } } } }, "200": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "const": "Duplicate event ignored." } }, "required": [ "message" ] } } } }, "403": { "description": "An error", "content": { "application\/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview.", "example": "You do not have access to this site." } }, "required": [ "message" ] } } } }, "422": { "$ref": "#\/components\/responses\/ValidationException" }, "404": { "$ref": "#\/components\/responses\/ModelNotFoundException" }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" } } } } }, "components": { "securitySchemes": { "http": { "type": "http", "scheme": "bearer" } }, "responses": { "AuthenticationException": { "description": "Unauthenticated", "content": { "application\/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] } } } }, "ModelNotFoundException": { "description": "Not found", "content": { "application\/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] } } } }, "ValidationException": { "description": "Validation error", "content": { "application\/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Errors overview." }, "errors": { "type": "object", "description": "A detailed description of each field that failed validation.", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "message", "errors" ] } } } } } } }