{ "components": { "responses": { "Error": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "JSON error; branch on code and HTTP status, not message. 405 includes Allow; rate limits may include Retry-After.", "headers": { "Allow": { "description": "Allowed methods on a 405 response.", "schema": { "type": "string" } }, "Retry-After": { "description": "Minimum wait before a permitted retry. Delta seconds or HTTP date; not present on every error. Follow the operation x-retry rule.", "schema": { "type": "string" } } } } }, "schemas": { "Agent": { "additionalProperties": false, "properties": { "cpu_usage": { "type": "number" }, "created_at": { "format": "date-time", "type": "string" }, "disk_percent": { "type": "number" }, "hostname": { "type": "string" }, "id": { "type": "string" }, "last_error": { "type": "string" }, "last_seen_at": { "format": "date-time", "type": "string" }, "mem_percent": { "type": "number" }, "status": { "type": "string" }, "swap_percent": { "type": "number" } }, "required": [ "id", "hostname", "status", "created_at", "last_seen_at", "cpu_usage", "mem_percent", "swap_percent", "disk_percent" ], "type": "object" }, "Error": { "properties": { "code": { "enum": [ "invalid_request", "invalid_json", "unauthorized", "cloud_access_paused", "forbidden", "csrf_invalid", "not_found", "method_not_allowed", "conflict", "payload_too_large", "unsupported_media_type", "rate_limited", "upstream_error", "unavailable", "internal_error" ], "type": "string" }, "error": { "description": "Human-readable message; do not branch on its contents.", "type": "string" }, "status": { "description": "Optional additional state, e.g. paused.", "type": "string" } }, "required": [ "error", "code" ], "type": "object" }, "Point": { "additionalProperties": false, "properties": { "cpu_usage": { "type": "number" }, "cpu_usage_max": { "type": "number" }, "disk_percent": { "type": "number" }, "disk_percent_max": { "type": "number" }, "mem_percent": { "type": "number" }, "mem_percent_max": { "type": "number" }, "recorded_at": { "format": "date-time", "type": "string" }, "resolution_seconds": { "type": "integer" }, "swap_percent": { "type": "number" }, "swap_percent_max": { "type": "number" } }, "required": [ "recorded_at", "resolution_seconds", "cpu_usage", "mem_percent", "swap_percent", "disk_percent" ], "type": "object" }, "billing_EventInput": { "additionalProperties": false, "properties": { "created": { "type": "integer" }, "data": { "additionalProperties": false, "properties": { "object": {} }, "type": "object" }, "id": { "type": "string" }, "livemode": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ] }, "object": { "type": "string" }, "type": { "type": "string" } }, "type": "object" }, "billing_Session": { "additionalProperties": false, "properties": { "expires_at": { "type": "integer" }, "id": { "type": "string" }, "url": { "type": "string" } }, "required": [ "id", "url", "expires_at" ], "type": "object" }, "server_billingReconciliationResult": { "additionalProperties": false, "properties": { "failed": { "type": "integer" }, "reconciled": { "type": "integer" }, "scanned": { "type": "integer" } }, "required": [ "scanned", "reconciled", "failed" ], "type": "object" }, "server_diskCapacityReport": { "additionalProperties": false, "properties": { "available_bytes": { "type": "integer" }, "checked_at": { "format": "date-time", "type": "string" }, "status": { "type": "string" }, "total_bytes": { "type": "integer" }, "used_percent": { "type": "number" }, "volume": { "type": "string" } }, "required": [ "volume", "status", "total_bytes", "available_bytes", "used_percent", "checked_at" ], "type": "object" }, "server_liveProcess": { "additionalProperties": false, "properties": { "cpu": { "type": "number" }, "mem": { "type": "number" }, "name": { "type": "string" } }, "required": [ "name", "cpu", "mem" ], "type": "object" }, "server_liveProcessInput": { "additionalProperties": false, "properties": { "cpu": { "type": "number" }, "mem": { "type": "number" }, "name": { "type": "string" } }, "type": "object" }, "server_liveSample": { "additionalProperties": false, "properties": { "captured_at": { "format": "date-time", "type": "string" }, "top_cpu": { "anyOf": [ { "items": { "$ref": "#/components/schemas/server_liveProcess" }, "type": "array" }, { "type": "null" } ] }, "top_mem": { "anyOf": [ { "items": { "$ref": "#/components/schemas/server_liveProcess" }, "type": "array" }, { "type": "null" } ] }, "version": { "type": "integer" } }, "required": [ "version", "captured_at", "top_cpu", "top_mem" ], "type": "object" }, "server_liveSampleInput": { "additionalProperties": false, "properties": { "captured_at": { "format": "date-time", "type": "string" }, "top_cpu": { "anyOf": [ { "items": { "$ref": "#/components/schemas/server_liveProcessInput" }, "type": "array" }, { "type": "null" } ] }, "top_mem": { "anyOf": [ { "items": { "$ref": "#/components/schemas/server_liveProcessInput" }, "type": "array" }, { "type": "null" } ] }, "version": { "type": "integer" } }, "type": "object" }, "server_liveView": { "additionalProperties": false, "properties": { "expires_at": { "format": "date-time", "type": "string" }, "received_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] }, "sample": { "anyOf": [ { "$ref": "#/components/schemas/server_liveSample" }, { "type": "null" } ] }, "supported": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ] } }, "required": [ "expires_at", "supported" ], "type": "object" }, "server_operationCounts": { "additionalProperties": false, "properties": { "errors": { "type": "integer" }, "rejected": { "type": "integer" }, "requests": { "type": "integer" } }, "required": [ "requests", "rejected", "errors" ], "type": "object" }, "server_operationsReport": { "additionalProperties": false, "properties": { "attention_required": { "type": "boolean" }, "background_failures": { "type": "integer" }, "billing_reconciliation": { "$ref": "#/components/schemas/server_operationCounts" }, "disk_capacity": { "anyOf": [ { "items": { "$ref": "#/components/schemas/server_diskCapacityReport" }, "type": "array" }, { "type": "null" } ] }, "email_delivery_failures": { "type": "integer" }, "stripe_webhook": { "$ref": "#/components/schemas/server_operationCounts" }, "telemetry": { "$ref": "#/components/schemas/server_operationCounts" }, "uptime_seconds": { "type": "integer" } }, "required": [ "uptime_seconds", "telemetry", "stripe_webhook", "billing_reconciliation", "email_delivery_failures", "background_failures", "attention_required" ], "type": "object" }, "store_AgentControl": { "additionalProperties": false, "properties": { "contacted_at": { "format": "date-time", "type": "string" }, "platform": { "type": "string" }, "remote_enabled": { "type": "boolean" }, "version": { "type": "string" } }, "required": [ "version", "platform", "remote_enabled", "contacted_at" ], "type": "object" }, "store_AgentControlReportInput": { "additionalProperties": false, "properties": { "platform": { "type": "string" }, "remote_enabled": { "type": "boolean" }, "result": { "anyOf": [ { "$ref": "#/components/schemas/store_AgentUpdateResultInput" }, { "type": "null" } ] }, "version": { "type": "string" } }, "type": "object" }, "store_AgentUpdate": { "additionalProperties": false, "properties": { "created_at": { "format": "date-time", "type": "string" }, "expires_at": { "format": "date-time", "type": "string" }, "id": { "type": "string" }, "stage": { "type": "string" }, "status": { "type": "string" }, "target_version": { "type": "string" } }, "required": [ "id", "target_version", "status", "created_at", "expires_at" ], "type": "object" }, "store_AgentUpdateResultInput": { "additionalProperties": false, "properties": { "id": { "type": "string" }, "stage": { "type": "string" }, "status": { "type": "string" }, "version": { "type": "string" } }, "type": "object" }, "store_AlertDelivery": { "additionalProperties": false, "properties": { "attempts": { "type": "integer" }, "created_at": { "format": "date-time", "type": "string" }, "event_type": { "type": "string" }, "last_error": { "type": "string" }, "recipient": { "type": "string" }, "sent_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] }, "status": { "type": "string" }, "subject": { "type": "string" } }, "required": [ "event_type", "recipient", "subject", "status", "attempts", "created_at" ], "type": "object" }, "store_AlertDestination": { "additionalProperties": false, "properties": { "deliveries": { "anyOf": [ { "items": { "$ref": "#/components/schemas/store_AlertDelivery" }, "type": "array" }, { "type": "null" } ] }, "delivery_configured": { "type": "boolean" }, "email": { "type": "string" }, "local_verification_only": { "type": "boolean" }, "pending_delivery_error": { "type": "string" }, "pending_delivery_status": { "type": "string" }, "pending_email": { "type": "string" }, "verification_expires_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] }, "verified": { "type": "boolean" } }, "required": [ "verified", "delivery_configured", "local_verification_only", "deliveries" ], "type": "object" }, "store_AlertPolicy": { "additionalProperties": false, "properties": { "cpu_threshold": { "type": "number" }, "disk_threshold": { "type": "number" }, "email_alerts_paused": { "type": "boolean" }, "memory_threshold": { "type": "number" }, "offline_seconds": { "type": "integer" }, "updated_at": { "format": "date-time", "type": "string" } }, "required": [ "email_alerts_paused", "cpu_threshold", "memory_threshold", "disk_threshold", "offline_seconds", "updated_at" ], "type": "object" }, "store_AlertPolicyInput": { "additionalProperties": false, "properties": { "cpu_threshold": { "type": "number" }, "disk_threshold": { "type": "number" }, "email_alerts_paused": { "type": "boolean" }, "memory_threshold": { "type": "number" }, "offline_seconds": { "type": "integer" }, "updated_at": { "format": "date-time", "type": "string" } }, "type": "object" }, "store_AlertPolicyPatchInput": { "additionalProperties": false, "properties": { "cpu_threshold": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "disk_threshold": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "email_alerts_paused": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ] }, "memory_threshold": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "offline_seconds": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] } }, "type": "object" }, "store_AlertWebhook": { "additionalProperties": false, "properties": { "deliveries": { "anyOf": [ { "items": { "$ref": "#/components/schemas/store_AlertDelivery" }, "type": "array" }, { "type": "null" } ] }, "enabled": { "type": "boolean" }, "format": { "type": "string" }, "secret": { "type": "string" }, "url": { "type": "string" } }, "required": [ "url", "format", "enabled", "secret", "deliveries" ], "type": "object" }, "store_ComplimentaryPlanGrant": { "additionalProperties": false, "properties": { "expires_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] }, "granted_at": { "format": "date-time", "type": "string" }, "granted_by": { "type": "string" }, "id": { "type": "integer" }, "reason": { "type": "string" } }, "required": [ "id", "reason", "granted_by", "granted_at" ], "type": "object" }, "store_CurrentSample": { "additionalProperties": false, "properties": { "cpu_alert_average": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "memory_alert_average": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "metrics": { "anyOf": [ { "$ref": "#/components/schemas/store_telemetryMetricData" }, { "type": "null" } ] }, "received_at": { "format": "date-time", "type": "string" } }, "required": [ "cpu_alert_average", "memory_alert_average", "received_at", "metrics" ], "type": "object" }, "store_HistoryPage": { "additionalProperties": false, "properties": { "has_more": { "type": "boolean" }, "next_cursor": { "type": "string" }, "points": { "anyOf": [ { "items": { "$ref": "#/components/schemas/Point" }, "type": "array" }, { "type": "null" } ] } }, "required": [ "points", "has_more" ], "type": "object" }, "store_Incident": { "additionalProperties": false, "properties": { "agent_id": { "type": "string" }, "hostname": { "type": "string" }, "id": { "type": "integer" }, "resolved_at": { "format": "date-time", "type": "string" }, "rule": { "type": "string" }, "severity": { "type": "string" }, "snapshot": {}, "started_at": { "format": "date-time", "type": "string" }, "status": { "type": "string" }, "threshold": { "type": "number" }, "updated_at": { "format": "date-time", "type": "string" }, "value": { "type": "number" } }, "required": [ "id", "agent_id", "hostname", "rule", "status", "severity", "value", "threshold", "started_at", "updated_at", "snapshot" ], "type": "object" }, "store_IncidentPage": { "additionalProperties": false, "properties": { "has_more": { "type": "boolean" }, "incidents": { "anyOf": [ { "items": { "$ref": "#/components/schemas/store_Incident" }, "type": "array" }, { "type": "null" } ] }, "next_cursor": { "type": "string" } }, "required": [ "incidents", "has_more" ], "type": "object" }, "store_OperatorAccount": { "additionalProperties": false, "properties": { "email": { "type": "string" }, "entitlement": { "$ref": "#/components/schemas/store_WorkspaceEntitlement" }, "grant": { "anyOf": [ { "$ref": "#/components/schemas/store_ComplimentaryPlanGrant" }, { "type": "null" } ] }, "verified": { "type": "boolean" } }, "required": [ "email", "verified", "entitlement", "grant" ], "type": "object" }, "store_PairingStatus": { "additionalProperties": false, "properties": { "expires_at": { "format": "date-time", "type": "string" }, "hostname": { "type": "string" }, "server_id": { "type": "string" }, "state": { "type": "string" } }, "required": [ "state" ], "type": "object" }, "store_WorkspaceEntitlement": { "additionalProperties": false, "properties": { "billing_period_end": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] }, "cancel_at_period_end": { "type": "boolean" }, "complimentary": { "type": "boolean" }, "complimentary_ends_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] }, "grace_days_remaining": { "type": "integer" }, "grace_ends_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] }, "server_limit": { "type": "integer" }, "status": { "type": "string" }, "subscription_status": { "type": "string" }, "trial_days_remaining": { "type": "integer" }, "trial_ends_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] }, "trial_started_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] } }, "required": [ "status", "trial_days_remaining", "grace_days_remaining", "server_limit" ], "type": "object" }, "store_telemetryContainerDataInput": { "additionalProperties": false, "properties": { "cpu": { "type": "number" }, "health": { "type": "string" }, "id": { "type": "string" }, "image": { "type": "string" }, "mem": { "type": "number" }, "name": { "type": "string" }, "ports": { "type": "string" }, "restart_count": { "type": "integer" }, "status": { "type": "string" }, "uptime": { "type": "string" } }, "type": "object" }, "store_telemetryDiskData": { "additionalProperties": false, "properties": { "device": { "type": "string" }, "free": { "type": "integer" }, "mount": { "type": "string" }, "percent": { "type": "number" }, "total": { "type": "integer" }, "used": { "type": "integer" } }, "required": [ "mount", "device", "total", "used", "free", "percent" ], "type": "object" }, "store_telemetryDiskDataInput": { "additionalProperties": false, "properties": { "device": { "type": "string" }, "free": { "type": "integer" }, "mount": { "type": "string" }, "percent": { "type": "number" }, "total": { "type": "integer" }, "used": { "type": "integer" } }, "type": "object" }, "store_telemetryEnvelopeInput": { "additionalProperties": false, "properties": { "incident_snapshot": { "anyOf": [ { "$ref": "#/components/schemas/store_telemetrySnapshotInput" }, { "type": "null" } ] }, "metrics": { "anyOf": [ { "$ref": "#/components/schemas/store_telemetryMetricDataInput" }, { "type": "null" } ] }, "sample_id": { "type": "string" }, "sent_at": { "format": "date-time", "type": "string" }, "version": { "type": "integer" } }, "type": "object" }, "store_telemetryMetricData": { "additionalProperties": false, "properties": { "cpu_count": { "type": "integer" }, "cpu_usage": { "type": "number" }, "disks": { "anyOf": [ { "items": { "$ref": "#/components/schemas/store_telemetryDiskData" }, "type": "array" }, { "type": "null" } ] }, "hostname": { "type": "string" }, "load_avg": { "type": "string" }, "mem_percent": { "type": "number" }, "mem_total": { "type": "integer" }, "mem_used": { "type": "integer" }, "net_rx": { "type": "integer" }, "net_rx_speed": { "type": "number" }, "net_tx": { "type": "integer" }, "net_tx_speed": { "type": "number" }, "processes": { "type": "integer" }, "swap_percent": { "type": "number" }, "swap_total": { "type": "integer" }, "swap_used": { "type": "integer" }, "timestamp": { "format": "date-time", "type": "string" }, "uptime": { "type": "string" } }, "required": [ "hostname", "uptime", "load_avg", "cpu_count", "cpu_usage", "mem_total", "mem_used", "mem_percent", "swap_total", "swap_used", "swap_percent", "disks", "net_rx", "net_tx", "net_rx_speed", "net_tx_speed", "processes", "timestamp" ], "type": "object" }, "store_telemetryMetricDataInput": { "additionalProperties": false, "properties": { "cpu_count": { "type": "integer" }, "cpu_usage": { "type": "number" }, "disks": { "anyOf": [ { "items": { "$ref": "#/components/schemas/store_telemetryDiskDataInput" }, "type": "array" }, { "type": "null" } ] }, "hostname": { "type": "string" }, "load_avg": { "type": "string" }, "mem_percent": { "type": "number" }, "mem_total": { "type": "integer" }, "mem_used": { "type": "integer" }, "net_rx": { "type": "integer" }, "net_rx_speed": { "type": "number" }, "net_tx": { "type": "integer" }, "net_tx_speed": { "type": "number" }, "processes": { "type": "integer" }, "swap_percent": { "type": "number" }, "swap_total": { "type": "integer" }, "swap_used": { "type": "integer" }, "timestamp": { "format": "date-time", "type": "string" }, "uptime": { "type": "string" } }, "type": "object" }, "store_telemetryProcessDataInput": { "additionalProperties": false, "properties": { "cpu": { "type": "number" }, "mem": { "type": "number" }, "name": { "type": "string" } }, "type": "object" }, "store_telemetrySnapshotInput": { "additionalProperties": false, "properties": { "captured_at": { "format": "date-time", "type": "string" }, "containers": { "anyOf": [ { "items": { "$ref": "#/components/schemas/store_telemetryContainerDataInput" }, "type": "array" }, { "type": "null" } ] }, "top_cpu": { "anyOf": [ { "items": { "$ref": "#/components/schemas/store_telemetryProcessDataInput" }, "type": "array" }, { "type": "null" } ] }, "top_mem": { "anyOf": [ { "items": { "$ref": "#/components/schemas/store_telemetryProcessDataInput" }, "type": "array" }, { "type": "null" } ] }, "triggers": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ] } }, "type": "object" } }, "securitySchemes": { "agentBearer": { "description": "Agent token returned by agent/pairing; scope is one agent.", "scheme": "bearer", "type": "http" }, "operatorBearer": { "description": "Operator token, subject to source and transport restrictions; scope is the operator workspace.", "scheme": "bearer", "type": "http" }, "sessionCookie": { "in": "cookie", "name": "vpscloud_session", "type": "apiKey" }, "setupBearer": { "description": "One-use pairing token returned by pairing-tokens.", "scheme": "bearer", "type": "http" }, "stripeSignature": { "description": "Timestamped HMAC over the exact JSON request bytes.", "in": "header", "name": "Stripe-Signature", "type": "apiKey" } } }, "info": { "description": "All version 1 Cloud API routes. Workspace operations use /v1/servers, /v1/incidents, /v1/alert-* and /v1/pairing-tokens. Agent transport uses /v1/agent/*. Deprecated routes are compatibility aliases with identical authentication and wire schemas. Customer and operator credentials are distinct; agent credentials authorize only that agent. Session mutations require X-CSRF-Token from auth/me. Availability depends on server configuration.", "title": "vpsmon Cloud API", "version": "1.2.0" }, "openapi": "3.1.0", "paths": { "/v1/admin/agents": { "get": { "deprecated": true, "description": "Compatibility alias for GET /v1/servers. Uses the same handler, authentication, workspace scope and rate limits. ", "operationId": "listAgentsCompatibility4", "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "agents": { "items": { "$ref": "#/components/schemas/Agent" }, "type": "array" }, "now": { "format": "date-time", "type": "string" } }, "required": [ "agents", "now" ], "type": "object" } } }, "description": "Success" }, "default": { "$ref": "#/components/responses/Error" } }, "security": [ { "sessionCookie": [] }, { "operatorBearer": [] } ], "summary": "List agents" } }, "/v1/admin/agents/{id}": { "delete": { "deprecated": true, "description": "Compatibility alias for DELETE /v1/servers/{id}. Uses the same handler, authentication, workspace scope and rate limits. ", "operationId": "removeAgentCompatibility7", "parameters": [ { "description": "Resource ID. Foreign resources are not accessible.", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } }, { "description": "Required for cookie-authenticated mutations; obtain from GET /v1/auth/me. Operator bearer requests do not require it.", "in": "header", "name": "X-CSRF-Token", "required": false, "schema": { "type": "string" } } ], "responses": { "204": { "description": "Success" }, "default": { "$ref": "#/components/responses/Error" } }, "security": [ { "sessionCookie": [] }, { "operatorBearer": [] } ], "summary": "Remove agent", "x-retry": "Deletion is durable; repeating the same ID returns 404. Treat that as already absent for this action only. Never substitute another ID." }, "patch": { "deprecated": true, "description": "Compatibility alias for PATCH /v1/servers/{id}. Uses the same handler, authentication, workspace scope and rate limits. Trim and replace the server name, which must contain 1–255 UTF-8 bytes. Return 204 with no body.", "operationId": "renameAgentCompatibility5", "parameters": [ { "description": "Resource ID. Foreign resources are not accessible.", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } }, { "description": "Required for cookie-authenticated mutations; obtain from GET /v1/auth/me. Operator bearer requests do not require it.", "in": "header", "name": "X-CSRF-Token", "required": false, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "hostname": { "type": "string" } }, "required": [ "hostname" ], "type": "object" } } }, "required": true }, "responses": { "204": { "description": "Success" }, "default": { "$ref": "#/components/responses/Error" } }, "security": [ { "sessionCookie": [] }, { "operatorBearer": [] } ], "summary": "Rename agent", "x-retry": "Safe to repeat the same hostname. GET admin/agents verifies the desired state." }, "put": { "deprecated": true, "description": "Compatibility alias for PUT /v1/servers/{id}. Uses the same handler, authentication, workspace scope and rate limits. Compatibility alias for PATCH; both perform a partial server rename.", "operationId": "renameAgentCompatibility6", "parameters": [ { "description": "Resource ID. Foreign resources are not accessible.", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } }, { "description": "Required for cookie-authenticated mutations; obtain from GET /v1/auth/me. Operator bearer requests do not require it.", "in": "header", "name": "X-CSRF-Token", "required": false, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "hostname": { "type": "string" } }, "required": [ "hostname" ], "type": "object" } } }, "required": true }, "responses": { "204": { "description": "Success" }, "default": { "$ref": "#/components/responses/Error" } }, "security": [ { "sessionCookie": [] }, { "operatorBearer": [] } ], "summary": "Rename agent", "x-retry": "Safe to repeat the same hostname. GET admin/agents verifies the desired state." } }, "/v1/admin/agents/{id}/current": { "get": { "deprecated": true, "description": "Compatibility alias for GET /v1/servers/{id}/metrics/current. Uses the same handler, authentication, workspace scope and rate limits. ", "operationId": "currentMetricsCompatibility11", "parameters": [ { "description": "Resource ID. Foreign resources are not accessible.", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "sample": { "anyOf": [ { "$ref": "#/components/schemas/store_CurrentSample" }, { "type": "null" } ] } }, "required": [ "sample" ], "type": "object" } } }, "description": "Success" }, "default": { "$ref": "#/components/responses/Error" } }, "security": [ { "sessionCookie": [] }, { "operatorBearer": [] } ], "summary": "Current metrics" } }, "/v1/admin/agents/{id}/live": { "delete": { "deprecated": true, "description": "Compatibility alias for DELETE /v1/servers/{id}/live-session. Uses the same handler, authentication, workspace scope and rate limits. Stop the workspace server live-view lease. Repeating the request for an owned server is safe.", "operationId": "stopLiveCompatibility13", "parameters": [ { "description": "Resource ID. Foreign resources are not accessible.", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } }, { "description": "Required for cookie-authenticated mutations; obtain from GET /v1/auth/me. Operator bearer requests do not require it.", "in": "header", "name": "X-CSRF-Token", "required": false, "schema": { "type": "string" } } ], "responses": { "204": { "description": "Success" }, "default": { "$ref": "#/components/responses/Error" } }, "security": [ { "sessionCookie": [] }, { "operatorBearer": [] } ], "summary": "Stop live", "x-retry": "Safe repeat stops the same RAM-only lease; server ownership is still required." }, "post": { "deprecated": true, "description": "Compatibility alias for POST /v1/servers/{id}/live-session. Uses the same handler, authentication, workspace scope and rate limits. Start or renew a 30-second live-view lease and return the latest ephemeral process sample. This POST changes lease state; it is not a pure read.", "operationId": "viewLiveCompatibility12", "parameters": [ { "description": "Resource ID. Foreign resources are not accessible.", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } }, { "description": "Required for cookie-authenticated mutations; obtain from GET /v1/auth/me. Operator bearer requests do not require it.", "in": "header", "name": "X-CSRF-Token", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/server_liveView" } } }, "description": "Success" }, "default": { "$ref": "#/components/responses/Error" } }, "security": [ { "sessionCookie": [] }, { "operatorBearer": [] } ], "summary": "View live", "x-retry": "Safe repeat renews a short RAM-only view lease; it does not create durable history. Rate limits still apply." } }, "/v1/admin/agents/{id}/metrics": { "get": { "deprecated": true, "description": "Compatibility alias for GET /v1/servers/{id}/metrics. Uses the same handler, authentication, workspace scope and rate limits. Bounded keyset pagination. has_more indicates additional rows; next_cursor is present only when has_more is true. Continue until has_more is false. Limits can change between pages. Cursors are not credentials. Incident ordering is active first, updated_at descending, then id descending; concurrent incident updates may move rows, so deduplicate by id or restart. History ordering uses recorded_at, resolution and a stable row key; cursors freeze retention cutoffs and the upper time bound, but do not hold a database snapshot. Retention and late ingestion may change available rows.", "operationId": "historyCompatibility8", "parameters": [ { "description": "Resource ID. Foreign resources are not accessible.", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } }, { "in": "query", "name": "limit", "schema": { "default": 2400, "maximum": 6000, "minimum": 1, "type": "integer" } }, { "description": "Lower time bound; defaults to 24 hours ago.", "in": "query", "name": "since", "schema": { "format": "date-time", "type": "string" } }, { "description": "Opaque next_cursor from the preceding page. Keep agent_id/status filters unchanged. For history, omit since or repeat the original since.", "in": "query", "name": "cursor", "schema": { "maxLength": 2048, "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/store_HistoryPage" } } }, "description": "Success" }, "default": { "$ref": "#/components/responses/Error" } }, "security": [ { "sessionCookie": [] }, { "operatorBearer": [] } ], "summary": "History" } }, "/v1/admin/agents/{id}/update": { "get": { "deprecated": true, "description": "Compatibility alias for GET /v1/servers/{id}/agent-update. Uses the same handler, authentication, workspace scope and rate limits. ", "operationId": "agentUpdateStateCompatibility9", "parameters": [ { "description": "Resource ID. Foreign resources are not accessible.", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "control": { "anyOf": [ { "$ref": "#/components/schemas/store_AgentControl" }, { "type": "null" } ] }, "latest_version": { "type": "string" }, "release_error": { "type": "string" }, "update": { "anyOf": [ { "$ref": "#/components/schemas/store_AgentUpdate" }, { "type": "null" } ] } }, "required": [ "control", "update" ], "type": "object" } } }, "description": "Success" }, "default": { "$ref": "#/components/responses/Error" } }, "security": [ { "sessionCookie": [] }, { "operatorBearer": [] } ], "summary": "Agent update state" }, "post": { "deprecated": true, "description": "Compatibility alias for POST /v1/servers/{id}/agent-update. Uses the same handler, authentication, workspace scope and rate limits. Queue an asynchronous signed agent update. Poll GET on this path for control and update state. A repeated request reuses a pending update; an already-current version returns 409.", "operationId": "requestAgentUpdateCompatibility10", "parameters": [ { "description": "Resource ID. Foreign resources are not accessible.", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } }, { "description": "Required for cookie-authenticated mutations; obtain from GET /v1/auth/me. Operator bearer requests do not require it.", "in": "header", "name": "X-CSRF-Token", "required": false, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": {}, "type": "object" } } }, "required": true }, "responses": { "202": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "update": { "anyOf": [ { "$ref": "#/components/schemas/store_AgentUpdate" }, { "type": "null" } ] } }, "required": [ "update" ], "type": "object" } } }, "description": "Success" }, "default": { "$ref": "#/components/responses/Error" } }, "security": [ { "sessionCookie": [] }, { "operatorBearer": [] } ], "summary": "Request agent update", "x-retry": "An existing queued/running update is reused. Poll GET admin/agents/{id}/update after a lost response. Once terminal or expired, another request may create a new command; do not replay blindly." } }, "/v1/admin/alert-destination": { "get": { "deprecated": true, "description": "Compatibility alias for GET /v1/alert-email. Uses the same handler, authentication, workspace scope and rate limits. ", "operationId": "getAlertDestinationCompatibility20", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/store_AlertDestination" } } }, "description": "Success" }, "default": { "$ref": "#/components/responses/Error" } }, "security": [ { "sessionCookie": [] }, { "operatorBearer": [] } ], "summary": "Get alert destination" } }, "/v1/admin/alert-destination/test": { "post": { "deprecated": true, "description": "Compatibility alias for POST /v1/alert-email/test. Uses the same handler, authentication, workspace scope and rate limits. ", "operationId": "testAlertEmailCompatibility22", "parameters": [ { "description": "Required for cookie-authenticated mutations; obtain from GET /v1/auth/me. Operator bearer requests do not require it.", "in": "header", "name": "X-CSRF-Token", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "email": { "type": "string" }, "status": { "type": "string" } }, "required": [ "status", "email" ], "type": "object" } } }, "description": "Success" }, "default": { "$ref": "#/components/responses/Error" } }, "security": [ { "sessionCookie": [] }, { "operatorBearer": [] } ], "summary": "Test alert email", "x-retry": "Produces a test email subject to quota; not idempotent. Check inbox/delivery history before retrying." } }, "/v1/admin/alert-destination/verification": { "post": { "deprecated": true, "description": "Compatibility alias for POST /v1/alert-email/verification. Uses the same handler, authentication, workspace scope and rate limits. ", "operationId": "startAlertDestinationVerificationCompatibility21", "parameters": [ { "description": "Required for cookie-authenticated mutations; obtain from GET /v1/auth/me. Operator bearer requests do not require it.", "in": "header", "name": "X-CSRF-Token", "required": false, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "email": { "type": "string" } }, "required": [ "email" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "email": { "type": "string" }, "status": { "type": "string" } }, "required": [ "status", "email" ], "type": "object" } } }, "description": "Success" }, "202": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "expires_at": { "format": "date-time", "type": "string" }, "status": { "type": "string" }, "verification_url": { "type": "string" } }, "required": [ "status", "expires_at" ], "type": "object" } } }, "description": "Success" }, "default": { "$ref": "#/components/responses/Error" } }, "security": [ { "sessionCookie": [] }, { "operatorBearer": [] } ], "summary": "Start alert destination verification", "x-retry": "Produces verification mail subject to quota; not idempotent. Check destination status and inbox before deliberate resend." } }, "/v1/admin/alert-policy": { "get": { "deprecated": true, "description": "Compatibility alias for GET /v1/alert-policy. Uses the same handler, authentication, workspace scope and rate limits. ", "operationId": "getAlertPolicyCompatibility16", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/store_AlertPolicy" } } }, "description": "Success" }, "default": { "$ref": "#/components/responses/Error" } }, "security": [ { "sessionCookie": [] }, { "operatorBearer": [] } ], "summary": "Get alert policy" }, "patch": { "deprecated": true, "description": "Compatibility alias for PATCH /v1/alert-policy. Uses the same handler, authentication, workspace scope and rate limits. Partial update applied atomically. Omitted fields preserve their current values. Explicit false is accepted; null, unknown fields, updated_at, empty patches and invalid ranges are rejected. Repeating the same values is safe for desired state; updated_at changes.", "operationId": "patchAlertPolicyCompatibility27", "parameters": [ { "description": "Required for cookie-authenticated mutations; obtain from GET /v1/auth/me. Operator bearer requests do not require it.", "in": "header", "name": "X-CSRF-Token", "required": false, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "minProperties": 1, "properties": { "cpu_threshold": { "maximum": 100, "minimum": 1, "type": "number" }, "disk_threshold": { "maximum": 100, "minimum": 1, "type": "number" }, "email_alerts_paused": { "type": "boolean" }, "memory_threshold": { "maximum": 100, "minimum": 1, "type": "number" }, "offline_seconds": { "maximum": 86400, "minimum": 15, "type": "integer" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/store_AlertPolicy" } } }, "description": "Success" }, "default": { "$ref": "#/components/responses/Error" } }, "security": [ { "sessionCookie": [] }, { "operatorBearer": [] } ], "summary": "Update selected alert policy fields", "x-retry": "Safe desired-state repeat of the same changed fields. Omitted fields stay current; updated_at changes. Pausing cancels pending email and resuming does not replay it." }, "put": { "deprecated": true, "description": "Compatibility alias for PUT /v1/alert-policy. Uses the same handler, authentication, workspace scope and rate limits. Compatibility replacement: supply all four thresholds; omitted email_alerts_paused is preserved atomically. Prefer PATCH for partial updates. updated_at is read-only and ignored by this compatibility route.", "operationId": "updateAlertPolicyCompatibility17", "parameters": [ { "description": "Required for cookie-authenticated mutations; obtain from GET /v1/auth/me. Operator bearer requests do not require it.", "in": "header", "name": "X-CSRF-Token", "required": false, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "cpu_threshold": { "type": "number" }, "disk_threshold": { "type": "number" }, "email_alerts_paused": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ] }, "memory_threshold": { "type": "number" }, "offline_seconds": { "type": "integer" }, "updated_at": { "format": "date-time", "type": "string" } }, "required": [ "cpu_threshold", "memory_threshold", "disk_threshold", "offline_seconds" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/store_AlertPolicy" } } }, "description": "Success" }, "default": { "$ref": "#/components/responses/Error" } }, "security": [ { "sessionCookie": [] }, { "operatorBearer": [] } ], "summary": "Update alert policy", "x-retry": "Safe desired-state repeat with all four thresholds. Omitted pause remains current; updated_at changes. Prefer PATCH for changed fields only." } }, "/v1/admin/alert-webhook": { "get": { "deprecated": true, "description": "Compatibility alias for GET /v1/alert-webhook. Uses the same handler, authentication, workspace scope and rate limits. ", "operationId": "getAlertWebhookCompatibility18", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/store_AlertWebhook" } } }, "description": "Success" }, "default": { "$ref": "#/components/responses/Error" } }, "security": [ { "sessionCookie": [] }, { "operatorBearer": [] } ], "summary": "Get alert webhook" }, "put": { "deprecated": true, "description": "Compatibility alias for PUT /v1/alert-webhook. Uses the same handler, authentication, workspace scope and rate limits. ", "operationId": "updateAlertWebhookCompatibility19", "parameters": [ { "description": "Required for cookie-authenticated mutations; obtain from GET /v1/auth/me. Operator bearer requests do not require it.", "in": "header", "name": "X-CSRF-Token", "required": false, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "enabled": { "type": "boolean" }, "format": { "type": "string" }, "url": { "type": "string" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/store_AlertWebhook" } } }, "description": "Success" }, "default": { "$ref": "#/components/responses/Error" } }, "security": [ { "sessionCookie": [] }, { "operatorBearer": [] } ], "summary": "Update alert webhook", "x-retry": "Same URL/format/settings preserve the signing secret and desired state. Changing URL or format rotates the secret and cancels queued deliveries. Read back settings after ambiguity." } }, "/v1/admin/incidents": { "get": { "deprecated": true, "description": "Compatibility alias for GET /v1/incidents. Uses the same handler, authentication, workspace scope and rate limits. Bounded keyset pagination. has_more indicates additional rows; next_cursor is present only when has_more is true. Continue until has_more is false. Limits can change between pages. Cursors are not credentials. Incident ordering is active first, updated_at descending, then id descending; concurrent incident updates may move rows, so deduplicate by id or restart. History ordering uses recorded_at, resolution and a stable row key; cursors freeze retention cutoffs and the upper time bound, but do not hold a database snapshot. Retention and late ingestion may change available rows.", "operationId": "listIncidentsCompatibility15", "parameters": [ { "in": "query", "name": "limit", "schema": { "default": 50, "maximum": 500, "minimum": 1, "type": "integer" } }, { "in": "query", "name": "agent_id", "schema": { "type": "string" } }, { "in": "query", "name": "status", "schema": { "enum": [ "active", "resolved" ], "type": "string" } }, { "description": "Opaque next_cursor from the preceding page. Keep agent_id/status filters unchanged. For history, omit since or repeat the original since.", "in": "query", "name": "cursor", "schema": { "maxLength": 2048, "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/store_IncidentPage" } } }, "description": "Success" }, "default": { "$ref": "#/components/responses/Error" } }, "security": [ { "sessionCookie": [] }, { "operatorBearer": [] } ], "summary": "List incidents" } }, "/v1/admin/setup-tokens": { "post": { "deprecated": true, "description": "Compatibility alias for POST /v1/pairing-tokens. Uses the same handler, authentication, workspace scope and rate limits. ttl_seconds must be an integer from 0 to 86400; zero or omission selects the 900-second default. Values outside this range are rejected before duration conversion.", "operationId": "createSetupTokenCompatibility24", "parameters": [ { "description": "Required for cookie-authenticated mutations; obtain from GET /v1/auth/me. Operator bearer requests do not require it.", "in": "header", "name": "X-CSRF-Token", "required": false, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "ttl_seconds": { "default": 900, "maximum": 86400, "minimum": 0, "type": "integer" } }, "type": "object" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "dev_mode": { "type": "boolean" }, "expires_at": { "format": "date-time", "type": "string" }, "setup_token": { "type": "string" } }, "required": [ "setup_token", "expires_at", "dev_mode" ], "type": "object" } } }, "description": "Success" }, "default": { "$ref": "#/components/responses/Error" } }, "security": [ { "sessionCookie": [] }, { "operatorBearer": [] } ], "summary": "Create setup token", "x-retry": "Each successful request issues a new one-use credential. Do not automatically retry after an ambiguous response; deliberately issue a replacement if needed." } }, "/v1/admin/setup-tokens/status": { "post": { "deprecated": true, "description": "Compatibility alias for POST /v1/pairing-tokens/status. Uses the same handler, authentication, workspace scope and rate limits. ", "operationId": "setupTokenStatusCompatibility23", "parameters": [ { "description": "Required for cookie-authenticated mutations; obtain from GET /v1/auth/me. Operator bearer requests do not require it.", "in": "header", "name": "X-CSRF-Token", "required": false, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "setup_token": { "type": "string" } }, "required": [ "setup_token" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/store_PairingStatus" } } }, "description": "Success" }, "default": { "$ref": "#/components/responses/Error" } }, "security": [ { "sessionCookie": [] }, { "operatorBearer": [] } ], "summary": "Setup token status", "x-retry": "Read-only lookup carried in POST so the setup credential is not in the URL. Safe to repeat with the same token." } }, "/v1/agent/control": { "post": { "description": "Report agent version, platform, remote-update opt-in and optional update result; at most 4 KiB. Returns the pending command, or null. Before authentication, process-local admission limits allow 120 requests per client IP and 1200 requests across this endpoint per minute. Authenticated reports retain the durable 12-per-agent-per-minute quota. Missing, malformed and invalid credentials consume admission capacity; rate limits return 429 with Retry-After.", "operationId": "agentControl", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/store_AgentControlReportInput" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "update": { "anyOf": [ { "$ref": "#/components/schemas/store_AgentUpdate" }, { "type": "null" } ] } }, "required": [ "update" ], "type": "object" } } }, "description": "Success" }, "default": { "$ref": "#/components/responses/Error" } }, "security": [ { "agentBearer": [] } ], "summary": "Agent control", "x-retry": "Repeat control heartbeat or result reports for the same command ID; terminal results are not overwritten. Heartbeat time advances and quota still applies." } }, "/v1/agent/live-samples": { "post": { "description": "Upload an ephemeral sample, at most 16 KiB; version 1, captured_at and at most five CPU and memory processes. Samples stay in bounded memory, not history.", "operationId": "receiveLive", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/server_liveSampleInput" } } }, "required": true }, "responses": { "204": { "description": "Success" }, "default": { "$ref": "#/components/responses/Error" } }, "security": [ { "agentBearer": [] } ], "summary": "Receive live", "x-retry": "Ephemeral last-value sample. Repeats replace the live sample and update receipt time; no durable history or replay receipt." } }, "/v1/agent/metrics": { "post": { "description": "Upload one signed-in agent sample, at most 256 KiB. Protocol version 1 requires sample_id (32 hexadecimal characters), sent_at, metrics.timestamp and resource readings. Replays of an accepted sample_id return 409 without another write. Required cpu_usage, mem_percent, swap_percent and disks must not be null. Numeric zero and an empty disk array are valid.", "operationId": "receiveMetrics", "requestBody": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/store_telemetryEnvelopeInput" }, { "properties": { "metrics": { "properties": { "cpu_usage": { "maximum": 100, "minimum": 0, "type": "number" }, "disks": { "type": "array" }, "mem_percent": { "maximum": 100, "minimum": 0, "type": "number" }, "swap_percent": { "maximum": 100, "minimum": 0, "type": "number" } }, "required": [ "timestamp", "cpu_usage", "mem_percent", "swap_percent", "disks" ], "type": "object" } }, "required": [ "version", "sample_id", "sent_at", "metrics" ], "type": "object" } ] } } }, "required": true }, "responses": { "204": { "description": "Success" }, "default": { "$ref": "#/components/responses/Error" } }, "security": [ { "agentBearer": [] } ], "summary": "Receive metrics", "x-retry": "sample_id is deduplicated for 24 hours. Repeating accepted telemetry returns 409 and does not add history or refresh heartbeat. Same collection with a new ID remains stale. Respect Retry-After and freshness limits." } }, "/v1/agent/pairing": { "post": { "description": "", "operationId": "claim", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "hostname": { "type": "string" } }, "required": [ "hostname" ], "type": "object" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "server_id": { "type": "string" }, "token": { "type": "string" } }, "required": [ "server_id", "token" ], "type": "object" } } }, "description": "Success" }, "default": { "$ref": "#/components/responses/Error" } }, "security": [ { "setupBearer": [] } ], "summary": "Claim", "x-retry": "One-use setup credential; repeat cannot return the agent token again. If the response was lost, check setup-token status and the fleet, remove the orphaned test server, then pair with a new setup token." } }, "/v1/agents/claim": { "post": { "deprecated": true, "description": "Compatibility alias for POST /v1/agent/pairing. Uses the same handler, authentication, workspace scope and rate limits. ", "operationId": "claimCompatibility25", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "hostname": { "type": "string" } }, "required": [ "hostname" ], "type": "object" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "server_id": { "type": "string" }, "token": { "type": "string" } }, "required": [ "server_id", "token" ], "type": "object" } } }, "description": "Success" }, "default": { "$ref": "#/components/responses/Error" } }, "security": [ { "setupBearer": [] } ], "summary": "Claim", "x-retry": "One-use setup credential; repeat cannot return the agent token again. If the response was lost, check setup-token status and the fleet, remove the orphaned test server, then pair with a new setup token." } }, "/v1/alert-email": { "get": { "description": "", "operationId": "getAlertDestination", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/store_AlertDestination" } } }, "description": "Success" }, "default": { "$ref": "#/components/responses/Error" } }, "security": [ { "sessionCookie": [] }, { "operatorBearer": [] } ], "summary": "Get alert destination" } }, "/v1/alert-email/test": { "post": { "description": "", "operationId": "testAlertEmail", "parameters": [ { "description": "Required for cookie-authenticated mutations; obtain from GET /v1/auth/me. Operator bearer requests do not require it.", "in": "header", "name": "X-CSRF-Token", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "email": { "type": "string" }, "status": { "type": "string" } }, "required": [ "status", "email" ], "type": "object" } } }, "description": "Success" }, "default": { "$ref": "#/components/responses/Error" } }, "security": [ { "sessionCookie": [] }, { "operatorBearer": [] } ], "summary": "Test alert email", "x-retry": "Produces a test email subject to quota; not idempotent. Check inbox/delivery history before retrying." } }, "/v1/alert-email/verification": { "post": { "description": "", "operationId": "startAlertDestinationVerification", "parameters": [ { "description": "Required for cookie-authenticated mutations; obtain from GET /v1/auth/me. Operator bearer requests do not require it.", "in": "header", "name": "X-CSRF-Token", "required": false, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "email": { "type": "string" } }, "required": [ "email" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "email": { "type": "string" }, "status": { "type": "string" } }, "required": [ "status", "email" ], "type": "object" } } }, "description": "Success" }, "202": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "expires_at": { "format": "date-time", "type": "string" }, "status": { "type": "string" }, "verification_url": { "type": "string" } }, "required": [ "status", "expires_at" ], "type": "object" } } }, "description": "Success" }, "default": { "$ref": "#/components/responses/Error" } }, "security": [ { "sessionCookie": [] }, { "operatorBearer": [] } ], "summary": "Start alert destination verification", "x-retry": "Produces verification mail subject to quota; not idempotent. Check destination status and inbox before deliberate resend." } }, "/v1/alert-email/verification/confirm": { "post": { "description": "", "operationId": "confirmAlertEmail", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "token": { "type": "string" } }, "required": [ "token" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "email": { "type": "string" }, "status": { "type": "string" } }, "required": [ "email", "status" ], "type": "object" } } }, "description": "Success" }, "default": { "$ref": "#/components/responses/Error" } }, "security": [], "summary": "Confirm alert email", "x-retry": "One-use token; repeated confirmation is rejected. Verify completion through GET alert-email." } }, "/v1/alert-policy": { "get": { "description": "", "operationId": "getAlertPolicy", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/store_AlertPolicy" } } }, "description": "Success" }, "default": { "$ref": "#/components/responses/Error" } }, "security": [ { "sessionCookie": [] }, { "operatorBearer": [] } ], "summary": "Get alert policy" }, "patch": { "description": "Partial update applied atomically. Omitted fields preserve their current values. Explicit false is accepted; null, unknown fields, updated_at, empty patches and invalid ranges are rejected. Repeating the same values is safe for desired state; updated_at changes.", "operationId": "patchAlertPolicy", "parameters": [ { "description": "Required for cookie-authenticated mutations; obtain from GET /v1/auth/me. Operator bearer requests do not require it.", "in": "header", "name": "X-CSRF-Token", "required": false, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "minProperties": 1, "properties": { "cpu_threshold": { "maximum": 100, "minimum": 1, "type": "number" }, "disk_threshold": { "maximum": 100, "minimum": 1, "type": "number" }, "email_alerts_paused": { "type": "boolean" }, "memory_threshold": { "maximum": 100, "minimum": 1, "type": "number" }, "offline_seconds": { "maximum": 86400, "minimum": 15, "type": "integer" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/store_AlertPolicy" } } }, "description": "Success" }, "default": { "$ref": "#/components/responses/Error" } }, "security": [ { "sessionCookie": [] }, { "operatorBearer": [] } ], "summary": "Update selected alert policy fields", "x-retry": "Safe desired-state repeat of the same changed fields. Omitted fields stay current; updated_at changes. Pausing cancels pending email and resuming does not replay it." }, "put": { "description": "Compatibility replacement: supply all four thresholds; omitted email_alerts_paused is preserved atomically. Prefer PATCH for partial updates. updated_at is read-only and ignored by this compatibility route.", "operationId": "updateAlertPolicy", "parameters": [ { "description": "Required for cookie-authenticated mutations; obtain from GET /v1/auth/me. Operator bearer requests do not require it.", "in": "header", "name": "X-CSRF-Token", "required": false, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "cpu_threshold": { "type": "number" }, "disk_threshold": { "type": "number" }, "email_alerts_paused": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ] }, "memory_threshold": { "type": "number" }, "offline_seconds": { "type": "integer" }, "updated_at": { "format": "date-time", "type": "string" } }, "required": [ "cpu_threshold", "memory_threshold", "disk_threshold", "offline_seconds" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/store_AlertPolicy" } } }, "description": "Success" }, "default": { "$ref": "#/components/responses/Error" } }, "security": [ { "sessionCookie": [] }, { "operatorBearer": [] } ], "summary": "Update alert policy", "x-retry": "Safe desired-state repeat with all four thresholds. Omitted pause remains current; updated_at changes. Prefer PATCH for changed fields only." } }, "/v1/alert-webhook": { "get": { "description": "", "operationId": "getAlertWebhook", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/store_AlertWebhook" } } }, "description": "Success" }, "default": { "$ref": "#/components/responses/Error" } }, "security": [ { "sessionCookie": [] }, { "operatorBearer": [] } ], "summary": "Get alert webhook" }, "put": { "description": "", "operationId": "updateAlertWebhook", "parameters": [ { "description": "Required for cookie-authenticated mutations; obtain from GET /v1/auth/me. Operator bearer requests do not require it.", "in": "header", "name": "X-CSRF-Token", "required": false, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "enabled": { "type": "boolean" }, "format": { "type": "string" }, "url": { "type": "string" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/store_AlertWebhook" } } }, "description": "Success" }, "default": { "$ref": "#/components/responses/Error" } }, "security": [ { "sessionCookie": [] }, { "operatorBearer": [] } ], "summary": "Update alert webhook", "x-retry": "Same URL/format/settings preserve the signing secret and desired state. Changing URL or format rotates the secret and cancels queued deliveries. Read back settings after ambiguity." } }, "/v1/auth/account/delete": { "post": { "operationId": "deleteAccount", "parameters": [ { "description": "Required for cookie-authenticated mutations; obtain from GET /v1/auth/me. Operator bearer requests do not require it.", "in": "header", "name": "X-CSRF-Token", "required": false, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "confirmation": { "type": "string" }, "password": { "type": "string" } }, "required": [ "password", "confirmation" ], "type": "object" } } }, "required": true }, "responses": { "204": { "description": "Success" }, "default": { "$ref": "#/components/responses/Error" } }, "security": [ { "sessionCookie": [] } ], "summary": "Delete account", "x-retry": "Destructive account deletion; do not automatically retry. Verify absence through normal sign-in. Billing races may retain the account." } }, "/v1/auth/config": { "get": { "operationId": "authConfig", "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "email_verification_available": { "type": "boolean" }, "registration_enabled": { "type": "boolean" } }, "required": [ "registration_enabled", "email_verification_available" ], "type": "object" } } }, "description": "Success" }, "default": { "$ref": "#/components/responses/Error" } }, "security": [], "summary": "Auth config" } }, "/v1/auth/email-verification/confirm": { "post": { "description": "", "operationId": "verifyAccountEmail", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "token": { "type": "string" } }, "required": [ "token" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "email": { "type": "string" }, "status": { "type": "string" } }, "required": [ "email", "status" ], "type": "object" } } }, "description": "Success" }, "default": { "$ref": "#/components/responses/Error" } }, "security": [], "summary": "Verify account email", "x-retry": "One-use token. A repeated token is rejected; verify completion through auth/me or normal sign-in." } }, "/v1/auth/email-verification/resend": { "post": { "description": "", "operationId": "resendAccountVerification", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "email": { "type": "string" } }, "type": "object" } } }, "required": true }, "responses": { "202": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "message": { "type": "string" }, "verification_url": { "type": "string" } }, "required": [ "message" ], "type": "object" } } }, "description": "Success" }, "default": { "$ref": "#/components/responses/Error" } }, "security": [], "summary": "Resend account verification", "x-retry": "Mail-producing action subject to quota; not idempotent. Check inbox, then deliberately resend after Retry-After." } }, "/v1/auth/login": { "post": { "operationId": "login", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "email": { "type": "string" }, "password": { "type": "string" } }, "required": [ "email", "password" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "email": { "type": "string" } }, "required": [ "email" ], "type": "object" } } }, "description": "Success" }, "default": { "$ref": "#/components/responses/Error" } }, "security": [], "summary": "Login", "x-retry": "Creates a new session. No automatic retries; sign in deliberately if the first response is lost." } }, "/v1/auth/logout": { "post": { "operationId": "logout", "parameters": [ { "description": "Required for cookie-authenticated mutations; obtain from GET /v1/auth/me. Operator bearer requests do not require it.", "in": "header", "name": "X-CSRF-Token", "required": false, "schema": { "type": "string" } } ], "responses": { "204": { "description": "Success" }, "default": { "$ref": "#/components/responses/Error" } }, "security": [ { "sessionCookie": [] }, { "operatorBearer": [] } ], "summary": "Logout", "x-retry": "Ends the current session; repeat may return 401. Treat unauthorized as already signed out for this action." } }, "/v1/auth/me": { "get": { "operationId": "me", "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "billing": { "additionalProperties": false, "properties": { "checkout_available": { "type": "boolean" }, "portal_available": { "type": "boolean" }, "test_mode": { "type": "boolean" } }, "required": [ "portal_available", "checkout_available", "test_mode" ], "type": "object" }, "csrf_token": { "type": "string" }, "email": { "type": "string" }, "entitlement": { "$ref": "#/components/schemas/store_WorkspaceEntitlement" }, "operator": { "type": "boolean" } }, "required": [ "email", "operator", "csrf_token" ], "type": "object" } } }, "description": "Success" }, "default": { "$ref": "#/components/responses/Error" } }, "security": [ { "sessionCookie": [] }, { "operatorBearer": [] } ], "summary": "Me" } }, "/v1/auth/password": { "post": { "operationId": "changePassword", "parameters": [ { "description": "Required for cookie-authenticated mutations; obtain from GET /v1/auth/me. Operator bearer requests do not require it.", "in": "header", "name": "X-CSRF-Token", "required": false, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "current_password": { "type": "string" }, "new_password": { "type": "string" } }, "required": [ "current_password", "new_password" ], "type": "object" } } }, "required": true }, "responses": { "204": { "description": "Success" }, "default": { "$ref": "#/components/responses/Error" } }, "security": [ { "sessionCookie": [] } ], "summary": "Change password", "x-retry": "Changes credentials and revokes other sessions. Do not blindly retry with the old password; verify using the new credential." } }, "/v1/auth/password-reset": { "post": { "operationId": "requestPasswordReset", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "email": { "type": "string" } }, "type": "object" } } }, "required": true }, "responses": { "202": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "message": { "type": "string" }, "reset_url": { "type": "string" } }, "required": [ "message" ], "type": "object" } } }, "description": "Success" }, "default": { "$ref": "#/components/responses/Error" } }, "security": [], "summary": "Request password reset", "x-retry": "Anti-enumeration mail request; not idempotent. Check inbox before deliberately retrying subject to quota." } }, "/v1/auth/password-reset/confirm": { "post": { "operationId": "confirmPasswordReset", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "new_password": { "type": "string" }, "token": { "type": "string" } }, "required": [ "token", "new_password" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "email": { "type": "string" }, "status": { "type": "string" } }, "required": [ "email", "status" ], "type": "object" } } }, "description": "Success" }, "default": { "$ref": "#/components/responses/Error" } }, "security": [], "summary": "Confirm password reset", "x-retry": "One-use token that changes credentials and revokes sessions. Do not blindly retry; sign in with the chosen password to verify success." } }, "/v1/auth/register": { "post": { "operationId": "register", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "email": { "type": "string" }, "password": { "type": "string" } }, "required": [ "email", "password" ], "type": "object" } } }, "required": true }, "responses": { "202": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "message": { "type": "string" }, "verification_url": { "type": "string" } }, "required": [ "message" ], "type": "object" } } }, "description": "Success" }, "default": { "$ref": "#/components/responses/Error" } }, "security": [], "summary": "Register", "x-retry": "Anti-enumeration response is not a registration receipt. Repeats may send account verification mail subject to quota. Check your inbox before resending." } }, "/v1/auth/sessions/revoke": { "post": { "operationId": "revokeSessions", "parameters": [ { "description": "Required for cookie-authenticated mutations; obtain from GET /v1/auth/me. Operator bearer requests do not require it.", "in": "header", "name": "X-CSRF-Token", "required": false, "schema": { "type": "string" } } ], "responses": { "204": { "description": "Success" }, "default": { "$ref": "#/components/responses/Error" } }, "security": [ { "sessionCookie": [] } ], "summary": "Revoke sessions", "x-retry": "Revokes sessions including the current customer session. A repeated request may be unauthorized; sign in again to verify." } }, "/v1/auth/verification/resend": { "post": { "deprecated": true, "description": "Compatibility alias for POST /v1/auth/email-verification/resend. Uses the same handler, authentication, workspace scope and rate limits. ", "operationId": "resendAccountVerificationCompatibility1", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "email": { "type": "string" } }, "type": "object" } } }, "required": true }, "responses": { "202": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "message": { "type": "string" }, "verification_url": { "type": "string" } }, "required": [ "message" ], "type": "object" } } }, "description": "Success" }, "default": { "$ref": "#/components/responses/Error" } }, "security": [], "summary": "Resend account verification", "x-retry": "Mail-producing action subject to quota; not idempotent. Check inbox, then deliberately resend after Retry-After." } }, "/v1/auth/verify-alert-email": { "post": { "deprecated": true, "description": "Compatibility alias for POST /v1/alert-email/verification/confirm. Uses the same handler, authentication, workspace scope and rate limits. ", "operationId": "confirmAlertEmailCompatibility3", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "token": { "type": "string" } }, "required": [ "token" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "email": { "type": "string" }, "status": { "type": "string" } }, "required": [ "email", "status" ], "type": "object" } } }, "description": "Success" }, "default": { "$ref": "#/components/responses/Error" } }, "security": [], "summary": "Confirm alert email", "x-retry": "One-use token; repeated confirmation is rejected. Verify completion through GET admin/alert-destination." } }, "/v1/auth/verify-email": { "post": { "deprecated": true, "description": "Compatibility alias for POST /v1/auth/email-verification/confirm. Uses the same handler, authentication, workspace scope and rate limits. ", "operationId": "verifyAccountEmailCompatibility2", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "token": { "type": "string" } }, "required": [ "token" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "email": { "type": "string" }, "status": { "type": "string" } }, "required": [ "email", "status" ], "type": "object" } } }, "description": "Success" }, "default": { "$ref": "#/components/responses/Error" } }, "security": [], "summary": "Verify account email", "x-retry": "One-use token. A repeated token is rejected; verify completion through auth/me or normal sign-in." } }, "/v1/billing/checkout": { "post": { "description": "Requires configured local Stripe test billing; live billing is not supported.", "operationId": "createCheckoutSession", "parameters": [ { "description": "Required for cookie-authenticated mutations; obtain from GET /v1/auth/me. Operator bearer requests do not require it.", "in": "header", "name": "X-CSRF-Token", "required": false, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "idempotency_key": { "type": "string" } }, "type": "object" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/billing_Session" } } }, "description": "Success" }, "default": { "$ref": "#/components/responses/Error" } }, "security": [ { "sessionCookie": [] }, { "operatorBearer": [] } ], "summary": "Create checkout session", "x-retry": "Send {}. A durable workspace attempt is reused across retries and restarts. Legacy idempotency_key is accepted but ignored. Unresolved attempts older than 23 hours fail closed with 409; reconcile instead of creating another purchase." } }, "/v1/billing/portal": { "post": { "description": "Requires configured local Stripe test billing; live billing is not supported.", "operationId": "createBillingPortalSession", "parameters": [ { "description": "Required for cookie-authenticated mutations; obtain from GET /v1/auth/me. Operator bearer requests do not require it.", "in": "header", "name": "X-CSRF-Token", "required": false, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "idempotency_key": { "maxLength": 160, "minLength": 16, "pattern": "^[A-Za-z0-9_.:-]+$", "type": "string" } }, "required": [ "idempotency_key" ], "type": "object" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/billing_Session" } } }, "description": "Success" }, "default": { "$ref": "#/components/responses/Error" } }, "security": [ { "sessionCookie": [] }, { "operatorBearer": [] } ], "summary": "Create billing portal session", "x-retry": "Supply a stable 16–160 character idempotency_key for this attempt; reuse on transient failure within the provider window. Cloud hashes it with the workspace ID. A new key starts another portal session. No automatic client retries." } }, "/v1/billing/webhook": { "post": { "description": "Verify Stripe-Signature against the original JSON bytes, at most 1 MiB. Only test-mode events are accepted. Duplicate event IDs succeed without repeating effects.", "operationId": "receiveStripeWebhook", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": true, "properties": { "created": { "type": "integer" }, "data": { "additionalProperties": true, "properties": { "object": {} }, "type": "object" }, "id": { "type": "string" }, "livemode": { "type": "boolean" }, "object": { "type": "string" }, "type": { "type": "string" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "duplicate": { "type": "boolean" }, "received": { "type": "boolean" } }, "required": [ "received" ], "type": "object" } } }, "description": "Success" }, "default": { "$ref": "#/components/responses/Error" } }, "security": [ { "stripeSignature": [] } ], "summary": "Receive stripe webhook", "x-availability": "Registered only when Stripe and its webhook secret are configured.", "x-retry": "Event ID is durably deduplicated only after successful application. The sender may retry failures using a current valid signature; duplicate application succeeds without changing state again." } }, "/v1/incidents": { "get": { "description": "Bounded keyset pagination. has_more indicates additional rows; next_cursor is present only when has_more is true. Continue until has_more is false. Limits can change between pages. Cursors are not credentials. Incident ordering is active first, updated_at descending, then id descending; concurrent incident updates may move rows, so deduplicate by id or restart. History ordering uses recorded_at, resolution and a stable row key; cursors freeze retention cutoffs and the upper time bound, but do not hold a database snapshot. Retention and late ingestion may change available rows.", "operationId": "listIncidents", "parameters": [ { "in": "query", "name": "limit", "schema": { "default": 50, "maximum": 500, "minimum": 1, "type": "integer" } }, { "in": "query", "name": "agent_id", "schema": { "type": "string" } }, { "in": "query", "name": "status", "schema": { "enum": [ "active", "resolved" ], "type": "string" } }, { "description": "Opaque next_cursor from the preceding page. Keep agent_id/status filters unchanged. For history, omit since or repeat the original since.", "in": "query", "name": "cursor", "schema": { "maxLength": 2048, "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/store_IncidentPage" } } }, "description": "Success" }, "default": { "$ref": "#/components/responses/Error" } }, "security": [ { "sessionCookie": [] }, { "operatorBearer": [] } ], "summary": "List incidents" } }, "/v1/live": { "post": { "deprecated": true, "description": "Compatibility alias for POST /v1/agent/live-samples. Uses the same handler, authentication, workspace scope and rate limits. Upload an ephemeral sample, at most 16 KiB; version 1, captured_at and at most five CPU and memory processes. Samples stay in bounded memory, not history.", "operationId": "receiveLiveCompatibility14", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/server_liveSampleInput" } } }, "required": true }, "responses": { "204": { "description": "Success" }, "default": { "$ref": "#/components/responses/Error" } }, "security": [ { "agentBearer": [] } ], "summary": "Receive live", "x-retry": "Ephemeral last-value sample. Repeats replace the live sample and update receipt time; no durable history or replay receipt." } }, "/v1/metrics": { "post": { "deprecated": true, "description": "Compatibility alias for POST /v1/agent/metrics. Uses the same handler, authentication, workspace scope and rate limits. Upload one signed-in agent sample, at most 256 KiB. Protocol version 1 requires sample_id (32 hexadecimal characters), sent_at, metrics.timestamp and resource readings. Replays of an accepted sample_id succeed without another write. Required cpu_usage, mem_percent, swap_percent and disks must not be null. Numeric zero and an empty disk array are valid.", "operationId": "receiveMetricsCompatibility26", "requestBody": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/store_telemetryEnvelopeInput" }, { "properties": { "metrics": { "properties": { "cpu_usage": { "maximum": 100, "minimum": 0, "type": "number" }, "disks": { "type": "array" }, "mem_percent": { "maximum": 100, "minimum": 0, "type": "number" }, "swap_percent": { "maximum": 100, "minimum": 0, "type": "number" } }, "required": [ "timestamp", "cpu_usage", "mem_percent", "swap_percent", "disks" ], "type": "object" } }, "required": [ "version", "sample_id", "sent_at", "metrics" ], "type": "object" } ] } } }, "required": true }, "responses": { "204": { "description": "Success" }, "default": { "$ref": "#/components/responses/Error" } }, "security": [ { "agentBearer": [] } ], "summary": "Receive metrics", "x-retry": "sample_id is deduplicated for 24 hours. Repeating accepted telemetry returns 409 and does not add history or refresh heartbeat. Same collection with a new ID remains stale. Respect Retry-After and freshness limits." } }, "/v1/openapi.json": { "get": { "operationId": "serveOpenAPI", "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": true, "required": [ "openapi", "info", "paths", "components" ], "type": "object" } } }, "description": "Success" }, "default": { "$ref": "#/components/responses/Error" } }, "security": [], "summary": "Read the complete API specification" } }, "/v1/operator/account": { "get": { "operationId": "operatorAccount", "parameters": [ { "description": "Account email to look up.", "in": "query", "name": "email", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/store_OperatorAccount" } } }, "description": "Success" }, "default": { "$ref": "#/components/responses/Error" } }, "security": [ { "sessionCookie": [] }, { "operatorBearer": [] } ], "summary": "Operator account" } }, "/v1/operator/billing/reconcile": { "post": { "description": "Requires configured local Stripe test billing; live billing is not supported.", "operationId": "reconcileStripeBilling", "parameters": [ { "description": "Required for cookie-authenticated mutations; obtain from GET /v1/auth/me. Operator bearer requests do not require it.", "in": "header", "name": "X-CSRF-Token", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/server_billingReconciliationResult" } } }, "description": "Success" }, "502": { "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/server_billingReconciliationResult" }, { "$ref": "#/components/schemas/Error" } ] } } }, "description": "Success" }, "default": { "$ref": "#/components/responses/Error" } }, "security": [ { "sessionCookie": [] }, { "operatorBearer": [] } ], "summary": "Reconcile stripe billing", "x-retry": "Reads canonical provider state and can safely be repeated. Some 502 responses contain counts indicating partial reconciliation; rerun after provider recovery." } }, "/v1/operator/login": { "post": { "operationId": "operatorLogin", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "token": { "type": "string" } }, "required": [ "token" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "email": { "type": "string" } }, "required": [ "email" ], "type": "object" } } }, "description": "Success" }, "default": { "$ref": "#/components/responses/Error" } }, "security": [], "summary": "Operator login", "x-retry": "Creates a new session on each successful request. Do not automatically retry an ambiguous response; sign in again deliberately if needed." } }, "/v1/operator/metrics": { "get": { "operationId": "operatorOperations", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/server_operationsReport" } } }, "description": "Success" }, "default": { "$ref": "#/components/responses/Error" } }, "security": [ { "sessionCookie": [] }, { "operatorBearer": [] } ], "summary": "Operator operations" } }, "/v1/operator/plan-grants": { "post": { "operationId": "grantComplimentaryPlan", "parameters": [ { "description": "Required for cookie-authenticated mutations; obtain from GET /v1/auth/me. Operator bearer requests do not require it.", "in": "header", "name": "X-CSRF-Token", "required": false, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "email": { "type": "string" }, "expires_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] }, "reason": { "type": "string" } }, "required": [ "email", "reason" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/store_OperatorAccount" } } }, "description": "Success" }, "default": { "$ref": "#/components/responses/Error" } }, "security": [ { "sessionCookie": [] }, { "operatorBearer": [] } ], "summary": "Grant complimentary plan", "x-retry": "Repeating replaces the active grant and writes audit history. Not idempotent; read operator/accounts?email=... after a lost response." } }, "/v1/operator/plan-grants/{id}": { "delete": { "operationId": "revokeComplimentaryPlan", "parameters": [ { "description": "Resource ID. Foreign resources are not accessible.", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } }, { "description": "Required for cookie-authenticated mutations; obtain from GET /v1/auth/me. Operator bearer requests do not require it.", "in": "header", "name": "X-CSRF-Token", "required": false, "schema": { "type": "string" } } ], "responses": { "204": { "description": "Success" }, "default": { "$ref": "#/components/responses/Error" } }, "security": [ { "sessionCookie": [] }, { "operatorBearer": [] } ], "summary": "Revoke complimentary plan", "x-retry": "Desired state is revoked, but repeat status may be 409 after the grant changes. Read operator/accounts before retrying." } }, "/v1/pairing-tokens": { "post": { "description": " ttl_seconds must be an integer from 0 to 86400; zero or omission selects the 900-second default. Values outside this range are rejected before duration conversion.", "operationId": "createSetupToken", "parameters": [ { "description": "Required for cookie-authenticated mutations; obtain from GET /v1/auth/me. Operator bearer requests do not require it.", "in": "header", "name": "X-CSRF-Token", "required": false, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "ttl_seconds": { "default": 900, "maximum": 86400, "minimum": 0, "type": "integer" } }, "type": "object" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "dev_mode": { "type": "boolean" }, "expires_at": { "format": "date-time", "type": "string" }, "setup_token": { "type": "string" } }, "required": [ "setup_token", "expires_at", "dev_mode" ], "type": "object" } } }, "description": "Success" }, "default": { "$ref": "#/components/responses/Error" } }, "security": [ { "sessionCookie": [] }, { "operatorBearer": [] } ], "summary": "Create setup token", "x-retry": "Each successful request issues a new one-use credential. Do not automatically retry after an ambiguous response; deliberately issue a replacement if needed." } }, "/v1/pairing-tokens/status": { "post": { "description": "", "operationId": "setupTokenStatus", "parameters": [ { "description": "Required for cookie-authenticated mutations; obtain from GET /v1/auth/me. Operator bearer requests do not require it.", "in": "header", "name": "X-CSRF-Token", "required": false, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "setup_token": { "type": "string" } }, "required": [ "setup_token" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/store_PairingStatus" } } }, "description": "Success" }, "default": { "$ref": "#/components/responses/Error" } }, "security": [ { "sessionCookie": [] }, { "operatorBearer": [] } ], "summary": "Setup token status", "x-retry": "Read-only lookup carried in POST so the setup credential is not in the URL. Safe to repeat with the same token." } }, "/v1/servers": { "get": { "description": "", "operationId": "listAgents", "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "agents": { "items": { "$ref": "#/components/schemas/Agent" }, "type": "array" }, "now": { "format": "date-time", "type": "string" } }, "required": [ "agents", "now" ], "type": "object" } } }, "description": "Success" }, "default": { "$ref": "#/components/responses/Error" } }, "security": [ { "sessionCookie": [] }, { "operatorBearer": [] } ], "summary": "List servers" } }, "/v1/servers/{id}": { "delete": { "description": "", "operationId": "removeAgent", "parameters": [ { "description": "Resource ID. Foreign resources are not accessible.", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } }, { "description": "Required for cookie-authenticated mutations; obtain from GET /v1/auth/me. Operator bearer requests do not require it.", "in": "header", "name": "X-CSRF-Token", "required": false, "schema": { "type": "string" } } ], "responses": { "204": { "description": "Success" }, "default": { "$ref": "#/components/responses/Error" } }, "security": [ { "sessionCookie": [] }, { "operatorBearer": [] } ], "summary": "Remove server", "x-retry": "Deletion is durable; repeating the same ID returns 404. Treat that as already absent for this action only. Never substitute another ID." }, "patch": { "description": "Trim and replace the server name, which must contain 1–255 UTF-8 bytes. Return 204 with no body.", "operationId": "renameAgent", "parameters": [ { "description": "Resource ID. Foreign resources are not accessible.", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } }, { "description": "Required for cookie-authenticated mutations; obtain from GET /v1/auth/me. Operator bearer requests do not require it.", "in": "header", "name": "X-CSRF-Token", "required": false, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "hostname": { "type": "string" } }, "required": [ "hostname" ], "type": "object" } } }, "required": true }, "responses": { "204": { "description": "Success" }, "default": { "$ref": "#/components/responses/Error" } }, "security": [ { "sessionCookie": [] }, { "operatorBearer": [] } ], "summary": "Rename server", "x-retry": "Safe to repeat the same hostname. GET servers verifies the desired state." }, "put": { "deprecated": true, "description": "Compatibility alias for PATCH; both perform a partial server rename.", "operationId": "renameAgentLegacy", "parameters": [ { "description": "Resource ID. Foreign resources are not accessible.", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } }, { "description": "Required for cookie-authenticated mutations; obtain from GET /v1/auth/me. Operator bearer requests do not require it.", "in": "header", "name": "X-CSRF-Token", "required": false, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "hostname": { "type": "string" } }, "required": [ "hostname" ], "type": "object" } } }, "required": true }, "responses": { "204": { "description": "Success" }, "default": { "$ref": "#/components/responses/Error" } }, "security": [ { "sessionCookie": [] }, { "operatorBearer": [] } ], "summary": "Rename server", "x-retry": "Safe to repeat the same hostname. GET servers verifies the desired state." } }, "/v1/servers/{id}/agent-update": { "get": { "description": "", "operationId": "agentUpdateState", "parameters": [ { "description": "Resource ID. Foreign resources are not accessible.", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "control": { "anyOf": [ { "$ref": "#/components/schemas/store_AgentControl" }, { "type": "null" } ] }, "latest_version": { "type": "string" }, "release_error": { "type": "string" }, "update": { "anyOf": [ { "$ref": "#/components/schemas/store_AgentUpdate" }, { "type": "null" } ] } }, "required": [ "control", "update" ], "type": "object" } } }, "description": "Success" }, "default": { "$ref": "#/components/responses/Error" } }, "security": [ { "sessionCookie": [] }, { "operatorBearer": [] } ], "summary": "Agent update state" }, "post": { "description": "Queue an asynchronous signed agent update. Poll GET on this path for control and update state. A repeated request reuses a pending update; an already-current version returns 409.", "operationId": "requestAgentUpdate", "parameters": [ { "description": "Resource ID. Foreign resources are not accessible.", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } }, { "description": "Required for cookie-authenticated mutations; obtain from GET /v1/auth/me. Operator bearer requests do not require it.", "in": "header", "name": "X-CSRF-Token", "required": false, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": {}, "type": "object" } } }, "required": true }, "responses": { "202": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "update": { "anyOf": [ { "$ref": "#/components/schemas/store_AgentUpdate" }, { "type": "null" } ] } }, "required": [ "update" ], "type": "object" } } }, "description": "Success" }, "default": { "$ref": "#/components/responses/Error" } }, "security": [ { "sessionCookie": [] }, { "operatorBearer": [] } ], "summary": "Request agent update", "x-retry": "An existing queued/running update is reused. Poll GET servers/{id}/update after a lost response. Once terminal or expired, another request may create a new command; do not replay blindly." } }, "/v1/servers/{id}/live-session": { "delete": { "description": "Stop the workspace server live-view lease. Repeating the request for an owned server is safe.", "operationId": "stopLive", "parameters": [ { "description": "Resource ID. Foreign resources are not accessible.", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } }, { "description": "Required for cookie-authenticated mutations; obtain from GET /v1/auth/me. Operator bearer requests do not require it.", "in": "header", "name": "X-CSRF-Token", "required": false, "schema": { "type": "string" } } ], "responses": { "204": { "description": "Success" }, "default": { "$ref": "#/components/responses/Error" } }, "security": [ { "sessionCookie": [] }, { "operatorBearer": [] } ], "summary": "Stop live", "x-retry": "Safe repeat stops the same RAM-only lease; server ownership is still required." }, "post": { "description": "Start or renew a 30-second live-view lease and return the latest ephemeral process sample. This POST changes lease state; it is not a pure read.", "operationId": "viewLive", "parameters": [ { "description": "Resource ID. Foreign resources are not accessible.", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } }, { "description": "Required for cookie-authenticated mutations; obtain from GET /v1/auth/me. Operator bearer requests do not require it.", "in": "header", "name": "X-CSRF-Token", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/server_liveView" } } }, "description": "Success" }, "default": { "$ref": "#/components/responses/Error" } }, "security": [ { "sessionCookie": [] }, { "operatorBearer": [] } ], "summary": "View live", "x-retry": "Safe repeat renews a short RAM-only view lease; it does not create durable history. Rate limits still apply." } }, "/v1/servers/{id}/metrics": { "get": { "description": "Bounded keyset pagination. has_more indicates additional rows; next_cursor is present only when has_more is true. Continue until has_more is false. Limits can change between pages. Cursors are not credentials. Incident ordering is active first, updated_at descending, then id descending; concurrent incident updates may move rows, so deduplicate by id or restart. History ordering uses recorded_at, resolution and a stable row key; cursors freeze retention cutoffs and the upper time bound, but do not hold a database snapshot. Retention and late ingestion may change available rows.", "operationId": "history", "parameters": [ { "description": "Resource ID. Foreign resources are not accessible.", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } }, { "in": "query", "name": "limit", "schema": { "default": 2400, "maximum": 6000, "minimum": 1, "type": "integer" } }, { "description": "Lower time bound; defaults to 24 hours ago.", "in": "query", "name": "since", "schema": { "format": "date-time", "type": "string" } }, { "description": "Opaque next_cursor from the preceding page. Keep agent_id/status filters unchanged. For history, omit since or repeat the original since.", "in": "query", "name": "cursor", "schema": { "maxLength": 2048, "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/store_HistoryPage" } } }, "description": "Success" }, "default": { "$ref": "#/components/responses/Error" } }, "security": [ { "sessionCookie": [] }, { "operatorBearer": [] } ], "summary": "History" } }, "/v1/servers/{id}/metrics/current": { "get": { "description": "", "operationId": "currentMetrics", "parameters": [ { "description": "Resource ID. Foreign resources are not accessible.", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "sample": { "anyOf": [ { "$ref": "#/components/schemas/store_CurrentSample" }, { "type": "null" } ] } }, "required": [ "sample" ], "type": "object" } } }, "description": "Success" }, "default": { "$ref": "#/components/responses/Error" } }, "security": [ { "sessionCookie": [] }, { "operatorBearer": [] } ], "summary": "Current metrics" } } }, "servers": [ { "url": "https://vpsmon.cloud" } ] }