{ "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\/{page}\/health": { "get": { "operationId": "health.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": [ "Health" ], "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": "object", "properties": { "data": { "anyOf": [ { "type": "object", "properties": { "status": { "type": "string", "description": "Top-level triage", "enum": [ "critical", "warning", "ok", "unknown" ] }, "summary": { "type": "string" }, "score": { "type": [ "integer", "null" ] }, "last_check": { "type": "string" }, "data_freshness": { "type": "object", "description": "Data freshness \u2014 flags stale scores so an LLM doesn't confidently\nreport on data that hasn't been refreshed in days", "properties": { "is_stale": { "type": "boolean" }, "stale_monitors": { "type": "array", "items": { "type": "string" } }, "oldest_check_at": { "type": [ "string", "null" ] } }, "required": [ "is_stale", "stale_monitors", "oldest_check_at" ] }, "vitals": { "type": "object", "description": "Vitals \u2014 one value per signal, full Core Web Vitals included", "properties": { "is_up": { "type": "boolean" }, "ssl": { "type": "string" }, "domain": { "type": "string" }, "lcp_ms": { "type": "string" }, "cls": { "type": "string" }, "fcp_ms": { "type": "string" }, "tbt_ms": { "type": "string" }, "ttfb_ms": { "type": "string" }, "inp_ms": { "type": "string" }, "perf_score": { "type": [ "integer", "null" ] }, "seo_score": { "type": [ "integer", "null" ] }, "security_score": { "type": [ "integer", "null" ] }, "integrity_score": { "type": [ "integer", "null" ] }, "content_score": { "type": "integer" }, "improvements": { "type": "string" } }, "required": [ "is_up", "ssl", "domain", "lcp_ms", "cls", "fcp_ms", "tbt_ms", "ttfb_ms", "inp_ms", "perf_score", "seo_score", "security_score", "integrity_score", "content_score", "improvements" ] }, "trends": { "type": "object", "description": "Score trends \u2014 positive = improving, negative = declining", "properties": { "uptime": { "type": "integer" }, "seo": { "type": "integer" }, "security": { "type": "integer" }, "integrity": { "type": "integer" }, "speed": { "type": "integer" } }, "required": [ "uptime", "seo", "security", "integrity", "speed" ] }, "content": { "type": "object", "description": "Content change intelligence\nchange_index: 0.0 = no change, 1.0 = completely different\nsemantic_similarity: 1.0 = same meaning, 0.0 = completely different\nexternal_domains: third-party domains this page currently loads from", "properties": { "change_index": { "type": [ "number", "null" ] }, "semantic_similarity": { "type": [ "number", "null" ] }, "word_count": { "type": "string" }, "last_changed_at": { "type": [ "string", "null" ] }, "external_domains": { "type": "array", "items": {} } }, "required": [ "change_index", "semantic_similarity", "word_count", "last_changed_at", "external_domains" ] }, "assets": { "description": "Asset health \u2014 broken\/total ratio for quick triage", "anyOf": [ { "type": "object", "properties": { "broken": { "type": "integer" }, "total": { "type": "integer" }, "broken_ratio": { "type": [ "number", "null" ] } }, "required": [ "broken", "total", "broken_ratio" ] }, { "type": "object", "properties": { "broken": { "type": "integer" }, "total": { "type": "integer" }, "broken_ratio": { "type": "null" } }, "required": [ "broken", "total", "broken_ratio" ] } ] }, "security_issues": { "description": "Security issue counts \u2014 what's failing, not just the score", "anyOf": [ { "type": "object", "properties": { "failed_checks": { "type": "integer" }, "warning_checks": { "type": "integer" }, "failures": { "type": "array", "items": {} }, "discovered_at": { "type": "string" }, "human_discovery": { "type": "string" } }, "required": [ "failed_checks", "warning_checks", "failures", "discovered_at", "human_discovery" ] }, { "type": "object", "properties": { "failed_checks": { "type": "integer" }, "warning_checks": { "type": "integer" }, "failures": { "type": "array", "items": { "type": "string" }, "minItems": 0, "maxItems": 0, "additionalItems": false }, "discovered_at": { "type": "null" } }, "required": [ "failed_checks", "warning_checks", "failures", "discovered_at" ] } ] }, "recent_drifts": { "type": "array", "description": "Change intelligence \u2014 severity-sorted, human-readable drift events", "items": {} }, "unresolved_drift_count": { "type": "integer" }, "alerts": { "type": "object", "description": "Alert summary \u2014 counts only, minimal token footprint", "properties": { "critical": { "type": "integer" }, "warning": { "type": "integer" }, "active_incident": { "type": "boolean" } }, "required": [ "critical", "warning", "active_incident" ] }, "page": { "type": "object", "properties": { "id": { "type": "integer" }, "url": { "type": [ "string", "null" ] }, "name": { "type": [ "string", "null" ] }, "platform": { "type": [ "string", "null" ] } }, "required": [ "id", "url", "name", "platform" ] }, "wordpress": { "anyOf": [ { "type": "object", "properties": { "enabled": { "type": "boolean" }, "recent_updates": { "type": "string" } }, "required": [ "enabled", "recent_updates" ] }, { "type": "object", "properties": { "recent_updates": { "type": "array", "items": { "type": "string" }, "minItems": 0, "maxItems": 0, "additionalItems": false } }, "required": [ "recent_updates" ] }, { "type": "object", "properties": { "enabled": { "type": "boolean" } }, "required": [ "enabled" ] } ] }, "uptime_detail": { "type": "object", "properties": { "recent_checks": { "type": "array", "items": { "type": "object", "properties": { "success": { "type": "boolean" }, "response_code": { "type": [ "integer", "null" ] }, "response_time_ms": { "type": "integer" }, "error_message": { "type": [ "string", "null" ] }, "checked_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "success", "response_code", "response_time_ms", "error_message", "checked_at" ] } }, "recent_incidents": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "started_at": { "type": "string", "format": "date-time" }, "ended_at": { "type": [ "string", "null" ], "format": "date-time" }, "duration_seconds": { "type": "integer" }, "resolved": { "type": "boolean" } }, "required": [ "id", "started_at", "ended_at", "duration_seconds", "resolved" ] } } }, "required": [ "recent_checks", "recent_incidents" ] }, "score_history": { "type": "array", "items": {} }, "monthly_summary": { "type": [ "object", "null" ], "properties": { "month": { "type": "string" }, "overall_score": { "type": "string" }, "uptime_avg": { "type": "string" }, "downtime_incidents": { "type": "string" }, "total_downtime_seconds": { "type": "string" }, "seo_avg": { "type": "string" }, "security_avg": { "type": "string" }, "performance_avg": { "type": "string" }, "integrity_avg": { "type": "string" }, "ssl_days_remaining": { "type": "string" }, "domain_days_remaining": { "type": "string" } }, "required": [ "month", "overall_score", "uptime_avg", "downtime_incidents", "total_downtime_seconds", "seo_avg", "security_avg", "performance_avg", "integrity_avg", "ssl_days_remaining", "domain_days_remaining" ] }, "monitors_enabled": { "type": "object", "properties": { "uptime": { "type": "boolean" }, "seo": { "type": "boolean" }, "security": { "type": "boolean" }, "integrity": { "type": "boolean" }, "pagespeed": { "type": "boolean" }, "asset": { "type": "boolean" }, "domain": { "type": "boolean" }, "content": { "type": "boolean" } }, "required": [ "uptime", "seo", "security", "integrity", "pagespeed", "asset", "domain", "content" ] }, "last_checked": { "type": "object", "properties": { "uptime": { "type": [ "string", "null" ], "format": "date-time" }, "seo": { "type": [ "string", "null" ], "format": "date-time" }, "pagespeed": { "type": [ "string", "null" ], "format": "date-time" }, "security": { "type": [ "string", "null" ], "format": "date-time" }, "integrity": { "type": [ "string", "null" ], "format": "date-time" }, "asset": { "type": [ "string", "null" ], "format": "date-time" }, "domain": { "type": [ "string", "null" ], "format": "date-time" }, "content": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "uptime", "seo", "pagespeed", "security", "integrity", "asset", "domain", "content" ] } }, "required": [ "status", "summary", "score", "last_check", "data_freshness", "vitals", "trends", "content", "assets", "security_issues", "recent_drifts", "unresolved_drift_count", "alerts", "page", "wordpress", "uptime_detail", "score_history", "monthly_summary", "monitors_enabled", "last_checked" ] }, { "type": "object", "properties": { "status": { "type": "string", "description": "Top-level triage", "enum": [ "critical", "warning", "ok", "unknown" ] }, "summary": { "type": "string" }, "score": { "type": [ "integer", "null" ] }, "last_check": { "type": "string" }, "data_freshness": { "type": "object", "description": "Data freshness \u2014 flags stale scores so an LLM doesn't confidently\nreport on data that hasn't been refreshed in days", "properties": { "is_stale": { "type": "boolean" }, "stale_monitors": { "type": "array", "items": { "type": "string" } }, "oldest_check_at": { "type": [ "string", "null" ] } }, "required": [ "is_stale", "stale_monitors", "oldest_check_at" ] }, "vitals": { "type": "object", "description": "Vitals \u2014 one value per signal, full Core Web Vitals included", "properties": { "is_up": { "type": "boolean" }, "ssl": { "type": "string" }, "domain": { "type": "string" }, "lcp_ms": { "type": "string" }, "cls": { "type": "string" }, "fcp_ms": { "type": "string" }, "tbt_ms": { "type": "string" }, "ttfb_ms": { "type": "string" }, "inp_ms": { "type": "string" }, "perf_score": { "type": [ "integer", "null" ] }, "seo_score": { "type": [ "integer", "null" ] }, "security_score": { "type": [ "integer", "null" ] }, "integrity_score": { "type": [ "integer", "null" ] }, "content_score": { "type": "integer" }, "improvements": { "type": "string" } }, "required": [ "is_up", "ssl", "domain", "lcp_ms", "cls", "fcp_ms", "tbt_ms", "ttfb_ms", "inp_ms", "perf_score", "seo_score", "security_score", "integrity_score", "content_score", "improvements" ] }, "trends": { "type": "object", "description": "Score trends \u2014 positive = improving, negative = declining", "properties": { "uptime": { "type": "integer" }, "seo": { "type": "integer" }, "security": { "type": "integer" }, "integrity": { "type": "integer" }, "speed": { "type": "integer" } }, "required": [ "uptime", "seo", "security", "integrity", "speed" ] }, "content": { "type": "object", "description": "Content change intelligence\nchange_index: 0.0 = no change, 1.0 = completely different\nsemantic_similarity: 1.0 = same meaning, 0.0 = completely different\nexternal_domains: third-party domains this page currently loads from", "properties": { "change_index": { "type": [ "number", "null" ] }, "semantic_similarity": { "type": [ "number", "null" ] }, "word_count": { "type": "string" }, "last_changed_at": { "type": [ "string", "null" ] }, "external_domains": { "type": "array", "items": {} } }, "required": [ "change_index", "semantic_similarity", "word_count", "last_changed_at", "external_domains" ] }, "assets": { "description": "Asset health \u2014 broken\/total ratio for quick triage", "anyOf": [ { "type": "object", "properties": { "broken": { "type": "integer" }, "total": { "type": "integer" }, "broken_ratio": { "type": [ "number", "null" ] } }, "required": [ "broken", "total", "broken_ratio" ] }, { "type": "object", "properties": { "broken": { "type": "integer" }, "total": { "type": "integer" }, "broken_ratio": { "type": "null" } }, "required": [ "broken", "total", "broken_ratio" ] } ] }, "security_issues": { "description": "Security issue counts \u2014 what's failing, not just the score", "anyOf": [ { "type": "object", "properties": { "failed_checks": { "type": "integer" }, "warning_checks": { "type": "integer" }, "failures": { "type": "array", "items": {} }, "discovered_at": { "type": "string" }, "human_discovery": { "type": "string" } }, "required": [ "failed_checks", "warning_checks", "failures", "discovered_at", "human_discovery" ] }, { "type": "object", "properties": { "failed_checks": { "type": "integer" }, "warning_checks": { "type": "integer" }, "failures": { "type": "array", "items": { "type": "string" }, "minItems": 0, "maxItems": 0, "additionalItems": false }, "discovered_at": { "type": "null" } }, "required": [ "failed_checks", "warning_checks", "failures", "discovered_at" ] } ] }, "recent_drifts": { "type": "array", "description": "Change intelligence \u2014 severity-sorted, human-readable drift events", "items": {} }, "unresolved_drift_count": { "type": "integer" }, "alerts": { "type": "object", "description": "Alert summary \u2014 counts only, minimal token footprint", "properties": { "critical": { "type": "integer" }, "warning": { "type": "integer" }, "active_incident": { "type": "boolean" } }, "required": [ "critical", "warning", "active_incident" ] }, "page": { "type": "object", "properties": { "id": { "type": "integer" }, "url": { "type": [ "string", "null" ] }, "name": { "type": [ "string", "null" ] }, "platform": { "type": [ "string", "null" ] } }, "required": [ "id", "url", "name", "platform" ] }, "wordpress": { "anyOf": [ { "type": "object", "properties": { "enabled": { "type": "boolean" }, "recent_updates": { "type": "string" } }, "required": [ "enabled", "recent_updates" ] }, { "type": "object", "properties": { "recent_updates": { "type": "array", "items": { "type": "string" }, "minItems": 0, "maxItems": 0, "additionalItems": false } }, "required": [ "recent_updates" ] }, { "type": "object", "properties": { "enabled": { "type": "boolean" } }, "required": [ "enabled" ] } ] } }, "required": [ "status", "summary", "score", "last_check", "data_freshness", "vitals", "trends", "content", "assets", "security_issues", "recent_drifts", "unresolved_drift_count", "alerts", "page", "wordpress" ] } ] }, "meta": { "type": "object", "properties": { "page_id": { "type": "integer" }, "mode": { "type": "string", "enum": [ "verbose", "snapshot" ] }, "generated_at": { "type": "string" } }, "required": [ "page_id", "mode", "generated_at" ] } }, "required": [ "data", "meta" ] } } } }, "404": { "$ref": "#\/components\/responses\/ModelNotFoundException" }, "403": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "const": "Access denied to this page." } }, "required": [ "error" ] } } } }, "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" } } } }, "\/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 }, "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}\/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" ] } } } } } } }