{ "openapi": "3.1.0", "info": { "title": "YamanVM Public API", "version": "1.1.0", "description": "Versioned public integration API for external developers." }, "servers": [ { "url": "https://denemevm.yamanhosting.com" } ], "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer" }, "apiKeyAuth": { "type": "apiKey", "in": "header", "name": "X-YamanVM-Api-Key" } }, "parameters": { "RequestIdHeader": { "name": "X-Request-Id", "in": "header", "required": false, "description": "Optional request correlation ID from the client.", "schema": { "type": "string" } }, "IdempotencyKeyHeader": { "name": "Idempotency-Key", "in": "header", "required": true, "description": "Required for mutating requests so safe retries can replay the original successful response.", "schema": { "type": "string" } } }, "headers": { "RequestIdHeader": { "description": "Server-generated or client-provided request correlation ID.", "schema": { "type": "string" } }, "RateLimitLimitHeader": { "description": "Maximum requests allowed per minute for the API client.", "schema": { "type": "integer" } }, "RateLimitRemainingHeader": { "description": "Remaining requests in the current minute window.", "schema": { "type": "integer" } }, "RetryAfterHeader": { "description": "Seconds until the rate limit window resets.", "schema": { "type": "integer" } }, "IdempotentReplayHeader": { "description": "Indicates whether the response body was replayed from a previous successful request.", "schema": { "type": "string", "enum": [ "true", "false" ] } } }, "schemas": { "ErrorResponse": { "type": "object", "required": [ "message", "code", "errors", "request_id" ], "properties": { "message": { "type": "string" }, "code": { "type": "string" }, "errors": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } }, "request_id": { "type": "string" } }, "example": { "message": "The request payload is invalid.", "code": "validation_error", "errors": { "template_id": [ "Selected template is not allowed for this server." ] }, "request_id": "0f59bfa0-ef7e-4cc8-96e0-8b3cd4bdb12f" } }, "PingResponse": { "type": "object", "properties": { "status": { "type": "string", "example": "ok" }, "service": { "type": "string", "example": "yamanvm-public-api" }, "version": { "type": "string", "example": "v1" }, "client": { "type": "object", "properties": { "id": { "type": "integer", "nullable": true }, "name": { "type": "string", "nullable": true } } } }, "example": { "status": "ok", "service": "yamanvm-public-api", "version": "v1", "client": { "id": 12, "name": "External Integration" } } }, "ServerListResponse": { "type": "object", "properties": { "servers": { "type": "array", "items": { "type": "object" } }, "pagination": { "type": "object" } }, "example": { "servers": [ { "id": 3, "name": "198.51.100.10", "hostname": "198.51.100.10", "primary_ip": "198.51.100.10", "status": "poweredOn", "server_state": "active", "effective_server_state": "active", "provision_status": "completed", "moid": "vm-451", "vcenter_vm_name": "198.51.100.10", "template": "Ubuntu 24.04", "plan": "VPS 4G", "username": "root", "cpu": 2, "cpu_socket_count": 1, "cpu_limit_mhz": null, "ram_mb": 4096, "disk_gb": 80, "snapshot_limit": 5, "usage": { "cpu_mhz": 221, "memory_mb": 1298, "disk_gb": 24.5, "network_kbps": 312.8 }, "vm_tools_status": "guestToolsRunning", "booted_at": "2026-04-12T09:20:00Z", "last_seen_at": "2026-04-12T09:42:00Z", "created_at": "2026-04-10T11:00:00Z", "updated_at": "2026-04-12T09:42:00Z", "has_active_task": false, "active_task": null } ], "pagination": { "current_page": 1, "last_page": 1, "per_page": 25, "total": 1, "has_more_pages": false } } }, "ShowServerResponse": { "type": "object", "properties": { "server": { "type": "object" } }, "example": { "server": { "id": 3, "name": "198.51.100.10", "hostname": "198.51.100.10", "primary_ip": "198.51.100.10", "status": "poweredOn", "server_state": "active", "effective_server_state": "active", "provision_status": "completed", "moid": "vm-451", "template": "Ubuntu 24.04", "plan": "VPS 4G", "username": "root" } } }, "TaskListResponse": { "type": "object", "properties": { "tasks": { "type": "array", "items": { "type": "object" } }, "pagination": { "type": "object" } }, "example": { "tasks": [ { "id": 45, "name": "Format Server", "type": "format", "status": "running", "current_stage": "reconfigure_vm", "progress_percent": 55, "server_id": 3, "payload": { "template_id": 7 }, "result": [], "meta": { "requested_by": "public_api" }, "started_at": "2026-04-12T09:45:10Z", "finished_at": null, "created_at": "2026-04-12T09:45:00Z", "updated_at": "2026-04-12T09:46:30Z", "logs": [ { "id": 701, "level": "info", "message": "VM reconfiguration started.", "context": [], "created_at": "2026-04-12T09:45:32Z" } ] } ], "pagination": { "current_page": 1, "last_page": 1, "per_page": 25, "total": 1, "has_more_pages": false } } }, "ShowTaskResponse": { "type": "object", "properties": { "task": { "type": "object" } }, "example": { "task": { "id": 45, "name": "Format Server", "type": "format", "status": "running", "current_stage": "reconfigure_vm", "progress_percent": 55, "server_id": 3 } } }, "PowerRequest": { "type": "object", "required": [ "action" ], "properties": { "action": { "type": "string", "enum": [ "power_on", "power_off", "restart" ] } }, "example": { "action": "restart" } }, "PowerResponse": { "type": "object", "properties": { "message": { "type": "string" }, "server": { "type": "object" } }, "example": { "message": "Power action completed.", "server": { "id": 3, "name": "198.51.100.10", "status": "poweredOn", "server_state": "active" } } }, "SnapshotCreateRequest": { "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string" }, "description": { "type": "string" } }, "example": { "name": "release-before-upgrade", "description": "Checkpoint before package upgrade" } }, "SnapshotPathRequest": { "type": "object", "required": [ "snapshot_path" ], "properties": { "snapshot_path": { "type": "string" } }, "example": { "snapshot_path": "release-before-upgrade" } }, "SnapshotListResponse": { "type": "object", "properties": { "snapshot_management": { "type": "object" } }, "example": { "snapshot_management": { "available": true, "limit": 5, "count": 1, "items": [ { "name": "release-before-upgrade", "description": "Checkpoint before package upgrade", "snapshot_path": "release-before-upgrade", "created_at": "2026-04-12T08:20:00Z", "state": "poweredOn", "is_current": true } ] } } }, "TaskQueuedResponse": { "type": "object", "properties": { "message": { "type": "string" }, "task": { "type": "object" } }, "example": { "message": "Server reinstall task has been queued.", "task": { "id": 81, "name": "Format Server", "type": "format", "status": "pending", "current_stage": null, "progress_percent": 0, "server_id": 3 } } }, "ProvisionRequest": { "type": "object", "required": [ "template_id", "ip_count" ], "properties": { "plan_id": { "type": "integer" }, "template_id": { "type": "integer" }, "template": { "type": "string" }, "pool_id": { "type": "integer" }, "host_id": { "type": "integer" }, "disk_id": { "type": "integer" }, "cpu_count": { "type": "integer" }, "cpu_limit_mhz": { "type": "integer" }, "ram_gb": { "type": "number" }, "disk_gb": { "type": "number" }, "ip_count": { "type": "integer" }, "ip_pool_id": { "type": "integer" }, "snapshot_limit": { "type": "integer" }, "format_list": { "type": "string" } }, "example": { "template_id": 7, "host_id": 2, "disk_id": 4, "cpu_count": 2, "ram_gb": 4, "disk_gb": 80, "ip_count": 1, "ip_pool_id": 1, "snapshot_limit": 3 } }, "ProvisionResponse": { "type": "object", "properties": { "message": { "type": "string" }, "server": { "type": "object" }, "credentials": { "type": "object" } }, "example": { "message": "Provisioning has been queued.", "server": { "id": 27, "name": "198.51.100.50", "hostname": "198.51.100.50", "primary_ip": "198.51.100.50", "status": "queued", "provision_status": "queued" }, "credentials": { "username": "root", "admin_password": "TempPass!4821" } } }, "FormatRequest": { "type": "object", "required": [ "template_id", "admin_password", "confirm_reset" ], "properties": { "template_id": { "type": "integer" }, "admin_password": { "type": "string" }, "confirm_reset": { "type": "boolean" } }, "example": { "template_id": 7, "admin_password": "NewPass!123", "confirm_reset": true } }, "FormatOptionsResponse": { "type": "object", "properties": { "templates": { "type": "array", "items": { "type": "object" } }, "server": { "type": "object" } }, "example": { "templates": [ { "id": 7, "name": "Ubuntu 24.04", "os_type": "linux", "default_username": "root" } ], "server": { "id": 3, "name": "198.51.100.10", "status": "poweredOn" } } } } }, "security": [ { "bearerAuth": [] }, { "apiKeyAuth": [] } ], "paths": { "/api/v1/ping": { "get": { "summary": "Health check", "description": "Quick way to verify token validity, connectivity and response headers.", "parameters": [ { "$ref": "#/components/parameters/RequestIdHeader" } ], "responses": { "200": { "description": "API is reachable", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestIdHeader" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimitHeader" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemainingHeader" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PingResponse" } } } }, "401": { "description": "Unauthorized", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestIdHeader" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimitHeader" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemainingHeader" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/v1/servers": { "get": { "summary": "List servers", "description": "Returns paginated servers visible in the YamanVM inventory.", "parameters": [ { "$ref": "#/components/parameters/RequestIdHeader" }, { "name": "per_page", "in": "query", "required": false, "schema": { "type": "integer" } }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer" } }, { "name": "status", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "server_state", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "search", "in": "query", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Server list returned", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestIdHeader" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimitHeader" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemainingHeader" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ServerListResponse" } } } }, "401": { "description": "Unauthorized", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestIdHeader" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimitHeader" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemainingHeader" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestIdHeader" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimitHeader" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemainingHeader" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/v1/servers/{server}": { "get": { "summary": "Show server", "parameters": [ { "$ref": "#/components/parameters/RequestIdHeader" }, { "name": "server", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Server returned", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestIdHeader" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimitHeader" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemainingHeader" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ShowServerResponse" } } } }, "401": { "description": "Unauthorized", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestIdHeader" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimitHeader" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemainingHeader" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestIdHeader" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimitHeader" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemainingHeader" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Server not found", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestIdHeader" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimitHeader" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemainingHeader" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/v1/servers/{server}/tasks": { "get": { "summary": "List tasks for a server", "parameters": [ { "$ref": "#/components/parameters/RequestIdHeader" }, { "name": "server", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Task list returned", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestIdHeader" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimitHeader" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemainingHeader" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TaskListResponse" } } } }, "401": { "description": "Unauthorized", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestIdHeader" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimitHeader" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemainingHeader" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestIdHeader" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimitHeader" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemainingHeader" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Server not found", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestIdHeader" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimitHeader" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemainingHeader" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/v1/tasks/{task}": { "get": { "summary": "Show task", "parameters": [ { "$ref": "#/components/parameters/RequestIdHeader" }, { "name": "task", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Task returned", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestIdHeader" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimitHeader" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemainingHeader" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ShowTaskResponse" } } } }, "401": { "description": "Unauthorized", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestIdHeader" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimitHeader" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemainingHeader" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestIdHeader" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimitHeader" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemainingHeader" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Task not found", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestIdHeader" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimitHeader" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemainingHeader" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/v1/servers/{server}/power": { "post": { "summary": "Run power action", "description": "Synchronous power control endpoint. Requires Idempotency-Key for safe retries.", "parameters": [ { "$ref": "#/components/parameters/RequestIdHeader" }, { "$ref": "#/components/parameters/IdempotencyKeyHeader" }, { "name": "server", "in": "path", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PowerRequest" } } } }, "responses": { "200": { "description": "Power action completed", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestIdHeader" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimitHeader" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemainingHeader" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PowerResponse" } } } }, "400": { "description": "Missing Idempotency-Key", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestIdHeader" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimitHeader" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemainingHeader" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestIdHeader" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimitHeader" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemainingHeader" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestIdHeader" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimitHeader" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemainingHeader" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Server not found", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestIdHeader" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimitHeader" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemainingHeader" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Idempotency key conflict", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestIdHeader" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimitHeader" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemainingHeader" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation error", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestIdHeader" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimitHeader" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemainingHeader" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/v1/servers/{server}/snapshots": { "get": { "summary": "List snapshots", "parameters": [ { "$ref": "#/components/parameters/RequestIdHeader" }, { "name": "server", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Snapshot list returned", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestIdHeader" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimitHeader" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemainingHeader" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SnapshotListResponse" } } } }, "401": { "description": "Unauthorized", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestIdHeader" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimitHeader" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemainingHeader" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestIdHeader" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimitHeader" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemainingHeader" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Server not found", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestIdHeader" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimitHeader" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemainingHeader" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "post": { "summary": "Queue snapshot create", "parameters": [ { "$ref": "#/components/parameters/RequestIdHeader" }, { "$ref": "#/components/parameters/IdempotencyKeyHeader" }, { "name": "server", "in": "path", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SnapshotCreateRequest" } } } }, "responses": { "202": { "description": "Snapshot create queued", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestIdHeader" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimitHeader" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemainingHeader" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TaskQueuedResponse" } } } }, "400": { "description": "Missing Idempotency-Key", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestIdHeader" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimitHeader" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemainingHeader" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestIdHeader" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimitHeader" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemainingHeader" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestIdHeader" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimitHeader" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemainingHeader" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Server not found", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestIdHeader" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimitHeader" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemainingHeader" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Idempotency key conflict", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestIdHeader" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimitHeader" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemainingHeader" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation error", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestIdHeader" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimitHeader" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemainingHeader" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "delete": { "summary": "Queue snapshot delete", "parameters": [ { "$ref": "#/components/parameters/RequestIdHeader" }, { "$ref": "#/components/parameters/IdempotencyKeyHeader" }, { "name": "server", "in": "path", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SnapshotPathRequest" } } } }, "responses": { "202": { "description": "Snapshot delete queued", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestIdHeader" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimitHeader" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemainingHeader" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TaskQueuedResponse" } } } }, "400": { "description": "Missing Idempotency-Key", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestIdHeader" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimitHeader" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemainingHeader" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestIdHeader" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimitHeader" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemainingHeader" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestIdHeader" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimitHeader" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemainingHeader" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Server not found", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestIdHeader" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimitHeader" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemainingHeader" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Idempotency key conflict", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestIdHeader" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimitHeader" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemainingHeader" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation error", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestIdHeader" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimitHeader" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemainingHeader" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/v1/servers/{server}/snapshots/revert": { "post": { "summary": "Queue snapshot revert", "parameters": [ { "$ref": "#/components/parameters/RequestIdHeader" }, { "$ref": "#/components/parameters/IdempotencyKeyHeader" }, { "name": "server", "in": "path", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SnapshotPathRequest" } } } }, "responses": { "202": { "description": "Snapshot revert queued", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestIdHeader" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimitHeader" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemainingHeader" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TaskQueuedResponse" } } } }, "400": { "description": "Missing Idempotency-Key", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestIdHeader" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimitHeader" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemainingHeader" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestIdHeader" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimitHeader" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemainingHeader" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestIdHeader" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimitHeader" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemainingHeader" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Server not found", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestIdHeader" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimitHeader" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemainingHeader" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Idempotency key conflict", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestIdHeader" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimitHeader" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemainingHeader" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation error", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestIdHeader" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimitHeader" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemainingHeader" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/v1/provisioning/requests": { "post": { "summary": "Queue server provisioning", "description": "Creates a new queued provisioning task and returns initial credentials.", "parameters": [ { "$ref": "#/components/parameters/RequestIdHeader" }, { "$ref": "#/components/parameters/IdempotencyKeyHeader" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProvisionRequest" } } } }, "responses": { "201": { "description": "Provisioning queued", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestIdHeader" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimitHeader" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemainingHeader" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProvisionResponse" } } } }, "400": { "description": "Missing Idempotency-Key", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestIdHeader" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimitHeader" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemainingHeader" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestIdHeader" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimitHeader" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemainingHeader" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestIdHeader" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimitHeader" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemainingHeader" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Idempotency key conflict", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestIdHeader" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimitHeader" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemainingHeader" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation error", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestIdHeader" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimitHeader" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemainingHeader" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/v1/servers/{server}/format-options": { "get": { "summary": "List allowed format templates", "parameters": [ { "$ref": "#/components/parameters/RequestIdHeader" }, { "name": "server", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Format options returned", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestIdHeader" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimitHeader" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemainingHeader" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FormatOptionsResponse" } } } }, "401": { "description": "Unauthorized", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestIdHeader" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimitHeader" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemainingHeader" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestIdHeader" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimitHeader" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemainingHeader" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Server not found", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestIdHeader" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimitHeader" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemainingHeader" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/v1/servers/{server}/format": { "post": { "summary": "Queue reinstall/format", "parameters": [ { "$ref": "#/components/parameters/RequestIdHeader" }, { "$ref": "#/components/parameters/IdempotencyKeyHeader" }, { "name": "server", "in": "path", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FormatRequest" } } } }, "responses": { "202": { "description": "Format queued", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestIdHeader" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimitHeader" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemainingHeader" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TaskQueuedResponse" } } } }, "400": { "description": "Missing Idempotency-Key", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestIdHeader" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimitHeader" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemainingHeader" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestIdHeader" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimitHeader" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemainingHeader" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestIdHeader" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimitHeader" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemainingHeader" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Server not found", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestIdHeader" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimitHeader" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemainingHeader" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Idempotency key conflict", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestIdHeader" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimitHeader" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemainingHeader" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation error", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestIdHeader" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimitHeader" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemainingHeader" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } } } }