{ "openapi": "3.1.0", "info": { "title": "XServer Cloud API", "version": "1.0.0", "description": "Public REST API for XServer Cloud. Authenticate with a personal access token (`Authorization: Bearer xsc_live_`), created in the dashboard under Settings → Authentication → API tokens; a token can be limited to a list of source IPs. Scopes are declared per route; a token may carry any subset of the scopes its issuing user holds. Errors always return the `ApiError` envelope.\n\nReselling: everything a reseller needs runs on the account balance — price an order with `POST /orders/preview`, place it with `POST /orders`, follow it with `GET /orders/{id}`, manage the server (power, reinstall, IPs, snapshots, backups, add-ons, resize), renew it with `POST /servers/{name}/renew` and cancel it with `DELETE /servers/{name}`. Every charge has a `…/preview` that names the amount first. The balance is topped up in the dashboard. Prices for the configurator: `GET /pricing`.\n\nRate limits: 3600 requests per token per hour; operations that spend the balance (`billing:write` — orders, renewals, invoice payments) 20 per token per hour by default, raised per account on request to support. Every response carries `RateLimit-Limit`, `RateLimit-Remaining` and `RateLimit-Reset`; a 429 also carries `Retry-After`.", "contact": { "name": "XServer Cloud Support", "url": "https://app.xserver.cloud/support" }, "license": { "name": "XServer Cloud — Terms of Service", "url": "https://xserver.cloud/info/rules" } }, "servers": [ { "url": "https://app.xserver.cloud/api/v1", "description": "Production" } ], "tags": [ { "name": "Account", "description": "Authenticated account resource." }, { "name": "Servers", "description": "Server inventory and state." }, { "name": "Actions", "description": "Background operations (power cycle, reinstall, …)." }, { "name": "SSH Keys", "description": "Public-key inventory. Used when provisioning or reinstalling OS." }, { "name": "Consoles", "description": "Short-lived signed URLs for interactive server consoles (WMKS / IPMI / VNC)." }, { "name": "Reference", "description": "Public reference data (locations, OS templates)." }, { "name": "IP Addresses", "description": "Server IP allocation + reverse-DNS (PTR) management." }, { "name": "Billing", "description": "Invoices, transactions, balance top-ups." }, { "name": "Orders", "description": "New-server purchase flow (order creation, status tracking)." }, { "name": "Services", "description": "Server add-on services (backup, monitoring, etc.)." }, { "name": "Backups", "description": "Unified backup resource — ad-hoc snapshots and service-provided restore points — available on virtual servers only. Physical servers have no backups." }, { "name": "Snapshots", "description": "Snapshot management (create, revert, delete) for virtual servers. Physical servers respond with `conflict` on these routes." }, { "name": "Previews", "description": "Dry-run preview endpoints paired with each destructive / financial mutation. Preview responses are read-only: no Action row is created, no state is mutated, and the numbers are guaranteed to match what the paired mutation would charge / refund. Safe to retry — all preview endpoints are idempotent." } ], "security": [ { "bearerAuth": [] } ], "externalDocs": { "description": "Developer portal", "url": "https://app.xserver.cloud/developers" }, "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "xsc_live_ | xsc_mobile_", "description": "Bearer token. Personal Access Tokens (`xsc_live_`) are issued from the web dashboard; mobile access tokens (`xsc_mobile_`) are issued via `POST /auth/mobile/token`. Supply as `Authorization: Bearer `." } }, "schemas": { "ApiErrorCode": { "type": "string", "description": "Stable error code — clients switch on it. Known values: `unauthorized`, `token_expired`, `tfa_required`, `forbidden`, `insufficient_scope`, `ip_not_allowlisted`, `not_found`, `conflict`, `idempotency_conflict`, `invalid_input`, `rate_limited`, `insufficient_funds`, `action_in_progress`, `server_error`, `service_unavailable`. New codes may be added; treat an unknown value as a generic failure of the HTTP status. Validation reasons (`tfa_not_enabled`, `unsupported_method`, …) are not codes — they arrive in `details.fields[].messages` under `invalid_input`.", "example": "invalid_input" }, "FieldError": { "type": "object", "properties": { "name": { "type": "string", "description": "Dotted path of the offending field (`_root` for top-level errors).", "example": "hostname" }, "messages": { "type": "array", "items": { "type": "string" }, "description": "One or more validation messages for this field." } }, "required": [ "name", "messages" ] }, "ApiError": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "$ref": "#/components/schemas/ApiErrorCode" }, "message": { "type": "string", "description": "Human-readable English fallback." }, "request_id": { "type": "string", "description": "Opaque request correlation id echoed in `X-Request-Id`." }, "details": { "type": "object", "properties": { "fields": { "type": "array", "items": { "$ref": "#/components/schemas/FieldError" } } }, "additionalProperties": {}, "description": "Structured details — shape varies by `code`." } }, "required": [ "code", "message", "request_id" ] } }, "required": [ "error" ], "description": "Stable error envelope returned by every non-2xx response on `/api/v1/*`. See `ApiErrorCode` for the enum of `error.code` values." }, "PaginationMeta": { "type": "object", "properties": { "page": { "type": "integer", "minimum": 1, "example": 1 }, "per_page": { "type": "integer", "minimum": 1, "example": 25 }, "previous_page": { "type": [ "integer", "null" ], "minimum": 1, "example": null }, "next_page": { "type": [ "integer", "null" ], "minimum": 1, "example": 2 }, "last_page": { "type": "integer", "minimum": 1, "example": 8 }, "total_entries": { "type": "integer", "minimum": 0, "example": 192 } }, "required": [ "page", "per_page", "previous_page", "next_page", "last_page", "total_entries" ], "description": "Hetzner-style pagination meta block. Present under `meta.pagination` on every list response." }, "ResourceRef": { "type": "object", "properties": { "id": { "type": "string", "description": "Opaque resource identifier.", "example": "XS-1023" }, "type": { "type": "string", "description": "Short resource type tag.", "example": "server" } }, "required": [ "id", "type" ], "description": "Minimal reference to a resource by id+type. Used when a response points to a related entity without inlining it." }, "Account": { "type": "object", "properties": { "id": { "type": "string" }, "email": { "type": "string", "format": "email" }, "first_name": { "type": "string" }, "last_name": { "type": "string" }, "phone": { "type": [ "string", "null" ] }, "country": { "type": [ "string", "null" ] }, "language": { "type": [ "string", "null" ] }, "balance": { "type": [ "number", "null" ] }, "bonus": { "type": [ "number", "null" ] }, "created_at": { "type": "string" }, "middle_name": { "type": "string" }, "organization": { "type": [ "string", "null" ] }, "city": { "type": [ "string", "null" ] }, "address": { "type": [ "string", "null" ] }, "timezone": { "type": "string" }, "email_confirmed": { "type": "boolean" }, "phone_verified": { "type": "boolean" }, "needs_onboarding": { "type": "boolean" }, "name_incomplete": { "type": "boolean" }, "tfa": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "method": { "type": [ "string", "null" ], "enum": [ "email", "sms", "telegram", "authenticator", null ] }, "oauth": { "type": "boolean" } }, "required": [ "enabled", "method", "oauth" ] }, "connected_accounts": { "type": "array", "items": { "type": "string" } }, "team_member": { "type": "boolean" }, "discount": { "type": [ "object", "null" ], "properties": { "factor": { "type": "number" }, "percent": { "type": "number" }, "source": { "type": "string", "enum": [ "user", "volume", "none" ] } }, "required": [ "factor", "percent", "source" ] } }, "required": [ "id", "email", "first_name", "last_name", "phone", "country", "language", "balance", "bonus", "created_at", "middle_name", "organization", "city", "address", "timezone", "email_confirmed", "phone_verified", "needs_onboarding", "name_incomplete", "tfa", "connected_accounts", "team_member", "discount" ] }, "AccountSession": { "type": "object", "properties": { "id": { "type": "string" }, "kind": { "type": "string", "enum": [ "web", "mobile" ] }, "name": { "type": "string" }, "device": { "type": "string", "enum": [ "phone", "tablet", "desktop", "unknown" ] }, "user_agent": { "type": [ "string", "null" ] }, "ip": { "type": [ "string", "null" ] }, "created_at": { "type": "string" }, "last_seen_at": { "type": [ "string", "null" ] }, "current": { "type": "boolean" } }, "required": [ "id", "kind", "name", "device", "user_agent", "ip", "created_at", "last_seen_at", "current" ] }, "NotificationChannel": { "type": "string", "enum": [ "email", "sms", "telegram", "push" ] }, "ActionError": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] }, "ActionEvent": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "snapshot", "progress", "success", "error" ] }, "action": { "type": "object", "properties": { "id": { "type": "string" }, "command": { "type": "string" }, "status": { "type": "string", "enum": [ "running", "success", "error" ] }, "progress": { "type": "integer", "minimum": 0, "maximum": 100 }, "resources": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string" } }, "required": [ "id", "type" ] } }, "error": { "type": [ "object", "null" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] }, "started_at": { "type": "string" }, "finished_at": { "type": [ "string", "null" ] } }, "required": [ "id", "command", "status", "progress", "resources", "error", "started_at", "finished_at" ] } }, "required": [ "kind", "action" ] }, "ActionListQuery": { "type": "object", "properties": { "server": { "type": "string", "minLength": 1, "maxLength": 64 }, "status": { "type": "string", "enum": [ "running", "success", "error" ] }, "command": { "type": "string", "minLength": 1, "maxLength": 64 }, "since": { "type": "string" } } }, "ActionListResponse": { "type": "object", "properties": { "actions": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "command": { "type": "string" }, "status": { "type": "string", "enum": [ "running", "success", "error" ] }, "progress": { "type": "integer", "minimum": 0, "maximum": 100 }, "resources": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string" } }, "required": [ "id", "type" ] } }, "error": { "type": [ "object", "null" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] }, "started_at": { "type": "string" }, "finished_at": { "type": [ "string", "null" ] } }, "required": [ "id", "command", "status", "progress", "resources", "error", "started_at", "finished_at" ] } } }, "required": [ "actions" ] }, "ActionResponse": { "type": "object", "properties": { "action": { "type": "object", "properties": { "id": { "type": "string" }, "command": { "type": "string" }, "status": { "type": "string", "enum": [ "running", "success", "error" ] }, "progress": { "type": "integer", "minimum": 0, "maximum": 100 }, "resources": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string" } }, "required": [ "id", "type" ] } }, "error": { "type": [ "object", "null" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] }, "started_at": { "type": "string" }, "finished_at": { "type": [ "string", "null" ] } }, "required": [ "id", "command", "status", "progress", "resources", "error", "started_at", "finished_at" ] } }, "required": [ "action" ] }, "Action": { "type": "object", "properties": { "id": { "type": "string" }, "command": { "type": "string" }, "status": { "type": "string", "enum": [ "running", "success", "error" ] }, "progress": { "type": "integer", "minimum": 0, "maximum": 100 }, "resources": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string" } }, "required": [ "id", "type" ] } }, "error": { "type": [ "object", "null" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] }, "started_at": { "type": "string" }, "finished_at": { "type": [ "string", "null" ] } }, "required": [ "id", "command", "status", "progress", "resources", "error", "started_at", "finished_at" ] }, "ActionStatus": { "type": "string", "enum": [ "running", "success", "error" ] }, "BackupActionResponse": { "type": "object", "properties": { "action": { "type": "object", "properties": { "id": { "type": "string" }, "command": { "type": "string" }, "status": { "type": "string", "enum": [ "running", "success", "error" ] }, "progress": { "type": "integer", "minimum": 0, "maximum": 100 }, "resources": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string" } }, "required": [ "id", "type" ] } }, "error": { "type": [ "object", "null" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] }, "started_at": { "type": "string" }, "finished_at": { "type": [ "string", "null" ] } }, "required": [ "id", "command", "status", "progress", "resources", "error", "started_at", "finished_at" ] }, "server": { "type": "object", "properties": { "name": { "type": "string" }, "type": { "type": "string", "enum": [ "virtual", "physical" ] }, "hostname": { "type": [ "string", "null" ] }, "status": { "type": "string", "enum": [ "new", "installing", "inventory", "active" ] }, "power_state": { "type": "string", "enum": [ "running", "stopped", "unknown" ] }, "location": { "type": "string" }, "os": { "type": "object", "properties": { "code": { "type": [ "string", "null" ] }, "name": { "type": [ "string", "null" ] }, "version": { "type": [ "string", "null" ] }, "family": { "type": [ "string", "null" ] } }, "required": [ "code", "name", "version", "family" ] }, "primary_ip": { "type": [ "string", "null" ] }, "ips": { "type": "array", "items": { "type": "string" } }, "ipv6": { "type": "array", "items": { "type": "string" } }, "config": { "type": "object", "properties": { "cpu": { "type": "integer", "minimum": 0 }, "ram": { "type": "integer", "minimum": 0 }, "ssd": { "type": "integer", "minimum": 0 }, "hdd": { "type": [ "integer", "null" ], "minimum": 0 }, "cpu_frequency": { "type": "number", "minimum": 0 }, "tier": { "type": "string", "enum": [ "standard", "high-perf" ] } }, "required": [ "cpu", "ram", "ssd", "hdd", "cpu_frequency", "tier" ] }, "expires_at": { "type": [ "string", "null" ] }, "autorenew": { "type": "boolean" }, "created_at": { "type": "string" } }, "required": [ "name", "type", "hostname", "status", "power_state", "location", "os", "primary_ip", "ips", "ipv6", "config", "expires_at", "autorenew", "created_at" ] } }, "required": [ "action", "server" ] }, "BackupCreateResponse": { "type": "object", "properties": { "action": { "type": "object", "properties": { "id": { "type": "string" }, "command": { "type": "string" }, "status": { "type": "string", "enum": [ "running", "success", "error" ] }, "progress": { "type": "integer", "minimum": 0, "maximum": 100 }, "resources": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string" } }, "required": [ "id", "type" ] } }, "error": { "type": [ "object", "null" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] }, "started_at": { "type": "string" }, "finished_at": { "type": [ "string", "null" ] } }, "required": [ "id", "command", "status", "progress", "resources", "error", "started_at", "finished_at" ] }, "backup": { "type": [ "object", "null" ], "properties": { "id": { "type": "string" }, "kind": { "type": "string", "enum": [ "snapshot", "restore_point" ] }, "name": { "type": "string" }, "created_at": { "type": "string" }, "size_bytes": { "type": [ "integer", "null" ] }, "description": { "type": [ "string", "null" ] }, "status": { "type": "string", "enum": [ "ready", "creating", "restoring", "failed" ] } }, "required": [ "id", "kind", "name", "created_at", "size_bytes", "description", "status" ] } }, "required": [ "action", "backup" ] }, "BackupListResponse": { "type": "object", "properties": { "backups": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "kind": { "type": "string", "enum": [ "snapshot", "restore_point" ] }, "name": { "type": "string" }, "created_at": { "type": "string" }, "size_bytes": { "type": [ "integer", "null" ] }, "description": { "type": [ "string", "null" ] }, "status": { "type": "string", "enum": [ "ready", "creating", "restoring", "failed" ] } }, "required": [ "id", "kind", "name", "created_at", "size_bytes", "description", "status" ] } } }, "required": [ "backups" ] }, "BackupPoint": { "type": "object", "properties": { "id": { "type": "string" }, "kind": { "type": "string", "enum": [ "snapshot", "restore_point" ] }, "name": { "type": "string" }, "created_at": { "type": "string" }, "size_bytes": { "type": [ "integer", "null" ] }, "description": { "type": [ "string", "null" ] }, "status": { "type": "string", "enum": [ "ready", "creating", "restoring", "failed" ] } }, "required": [ "id", "kind", "name", "created_at", "size_bytes", "description", "status" ] }, "CreateBackupInput": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 80 }, "description": { "type": "string", "maxLength": 500 }, "memory": { "type": "boolean", "default": false }, "queue_if_busy": { "type": "boolean", "default": true } } }, "RestoreBackupInput": { "type": "object", "properties": { "tfa_code": { "type": "string" } } }, "InvoiceGateway": { "type": "object", "properties": { "slug": { "type": "string" }, "name": { "type": "string" } }, "required": [ "slug", "name" ] }, "InvoiceItem": { "type": "object", "properties": { "description": { "type": "string" }, "description_text": { "type": "string" }, "quantity": { "type": "number" }, "unit_price": { "type": [ "number", "null" ] }, "total": { "type": [ "number", "null" ] }, "type": { "type": "string" }, "server_name": { "type": [ "string", "null" ] }, "period": { "type": [ "object", "null" ], "properties": { "from": { "type": "string" }, "to": { "type": "string" }, "days": { "type": "number" } }, "required": [ "from", "to", "days" ] } }, "required": [ "description", "description_text", "quantity", "unit_price", "total", "type", "server_name", "period" ] }, "InvoiceListQuery": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "draft", "pending", "partial", "paid", "cancelled", "refunded" ] }, "from": { "type": "string" }, "to": { "type": "string" }, "period": { "type": "string" } } }, "InvoiceListResponse": { "type": "object", "properties": { "invoices": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "number": { "type": "string" }, "status": { "type": "string", "enum": [ "draft", "pending", "partial", "paid", "cancelled", "refunded" ] }, "currency": { "type": "string" }, "amount": { "type": [ "number", "null" ] }, "amount_paid": { "type": [ "number", "null" ] }, "amount_remaining": { "type": [ "number", "null" ] }, "description": { "type": "string" }, "description_text": { "type": "string" }, "items": { "type": "array", "items": { "type": "object", "properties": { "description": { "type": "string" }, "description_text": { "type": "string" }, "quantity": { "type": "number" }, "unit_price": { "type": [ "number", "null" ] }, "total": { "type": [ "number", "null" ] }, "type": { "type": "string" }, "server_name": { "type": [ "string", "null" ] }, "period": { "type": [ "object", "null" ], "properties": { "from": { "type": "string" }, "to": { "type": "string" }, "days": { "type": "number" } }, "required": [ "from", "to", "days" ] } }, "required": [ "description", "description_text", "quantity", "unit_price", "total", "type", "server_name", "period" ] } }, "gateway": { "type": [ "object", "null" ], "properties": { "slug": { "type": "string" }, "name": { "type": "string" } }, "required": [ "slug", "name" ] }, "created_at": { "type": "string" }, "paid_at": { "type": [ "string", "null" ] }, "due_at": { "type": [ "string", "null" ] } }, "required": [ "id", "number", "status", "currency", "amount", "amount_paid", "amount_remaining", "description", "description_text", "items", "gateway", "created_at", "paid_at", "due_at" ] } }, "meta": { "type": "object", "properties": { "pagination": { "type": "object", "properties": { "page": { "type": "integer", "minimum": 0 }, "per_page": { "type": "integer", "exclusiveMinimum": 0 }, "previous_page": { "type": [ "integer", "null" ], "exclusiveMinimum": 0 }, "next_page": { "type": [ "integer", "null" ], "exclusiveMinimum": 0 }, "last_page": { "type": "integer", "exclusiveMinimum": 0 }, "total_entries": { "type": "integer", "minimum": 0 } }, "required": [ "page", "per_page", "previous_page", "next_page", "last_page", "total_entries" ] } }, "required": [ "pagination" ] } }, "required": [ "invoices", "meta" ] }, "InvoiceResponse": { "type": "object", "properties": { "invoice": { "type": "object", "properties": { "id": { "type": "string" }, "number": { "type": "string" }, "status": { "type": "string", "enum": [ "draft", "pending", "partial", "paid", "cancelled", "refunded" ] }, "currency": { "type": "string" }, "amount": { "type": [ "number", "null" ] }, "amount_paid": { "type": [ "number", "null" ] }, "amount_remaining": { "type": [ "number", "null" ] }, "description": { "type": "string" }, "description_text": { "type": "string" }, "items": { "type": "array", "items": { "type": "object", "properties": { "description": { "type": "string" }, "description_text": { "type": "string" }, "quantity": { "type": "number" }, "unit_price": { "type": [ "number", "null" ] }, "total": { "type": [ "number", "null" ] }, "type": { "type": "string" }, "server_name": { "type": [ "string", "null" ] }, "period": { "type": [ "object", "null" ], "properties": { "from": { "type": "string" }, "to": { "type": "string" }, "days": { "type": "number" } }, "required": [ "from", "to", "days" ] } }, "required": [ "description", "description_text", "quantity", "unit_price", "total", "type", "server_name", "period" ] } }, "gateway": { "type": [ "object", "null" ], "properties": { "slug": { "type": "string" }, "name": { "type": "string" } }, "required": [ "slug", "name" ] }, "created_at": { "type": "string" }, "paid_at": { "type": [ "string", "null" ] }, "due_at": { "type": [ "string", "null" ] } }, "required": [ "id", "number", "status", "currency", "amount", "amount_paid", "amount_remaining", "description", "description_text", "items", "gateway", "created_at", "paid_at", "due_at" ] } }, "required": [ "invoice" ] }, "Invoice": { "type": "object", "properties": { "id": { "type": "string" }, "number": { "type": "string" }, "status": { "type": "string", "enum": [ "draft", "pending", "partial", "paid", "cancelled", "refunded" ] }, "currency": { "type": "string" }, "amount": { "type": [ "number", "null" ] }, "amount_paid": { "type": [ "number", "null" ] }, "amount_remaining": { "type": [ "number", "null" ] }, "description": { "type": "string" }, "description_text": { "type": "string" }, "items": { "type": "array", "items": { "type": "object", "properties": { "description": { "type": "string" }, "description_text": { "type": "string" }, "quantity": { "type": "number" }, "unit_price": { "type": [ "number", "null" ] }, "total": { "type": [ "number", "null" ] }, "type": { "type": "string" }, "server_name": { "type": [ "string", "null" ] }, "period": { "type": [ "object", "null" ], "properties": { "from": { "type": "string" }, "to": { "type": "string" }, "days": { "type": "number" } }, "required": [ "from", "to", "days" ] } }, "required": [ "description", "description_text", "quantity", "unit_price", "total", "type", "server_name", "period" ] } }, "gateway": { "type": [ "object", "null" ], "properties": { "slug": { "type": "string" }, "name": { "type": "string" } }, "required": [ "slug", "name" ] }, "created_at": { "type": "string" }, "paid_at": { "type": [ "string", "null" ] }, "due_at": { "type": [ "string", "null" ] } }, "required": [ "id", "number", "status", "currency", "amount", "amount_paid", "amount_remaining", "description", "description_text", "items", "gateway", "created_at", "paid_at", "due_at" ] }, "InvoiceStatus": { "type": "string", "enum": [ "draft", "pending", "partial", "paid", "cancelled", "refunded" ] }, "PayInvoiceInput": { "type": "object", "properties": { "method": { "type": "string", "enum": [ "balance" ] }, "useBonus": { "type": "boolean", "default": false } }, "required": [ "method" ] }, "PaymentMethod": { "type": "object", "properties": { "slug": { "type": "string" }, "name": { "type": "string" }, "names": { "type": [ "object", "null" ], "additionalProperties": { "type": "string" } }, "type": { "type": "string", "enum": [ "redirect", "display", "form_post" ] }, "currency": { "type": "string" }, "exchange_rate": { "type": [ "number", "null" ] }, "min_amount": { "type": [ "number", "null" ] }, "max_amount": { "type": [ "number", "null" ] }, "commission": { "type": [ "number", "null" ] }, "image": { "type": [ "string", "null" ] }, "image_png": { "type": [ "string", "null" ] }, "category": { "type": [ "string", "null" ] }, "accepted_payer_types": { "type": "array", "items": { "type": "string", "enum": [ "individual", "organization" ] } }, "test_only": { "type": "boolean" } }, "required": [ "slug", "name", "names", "type", "currency", "exchange_rate", "min_amount", "max_amount", "commission", "image", "image_png", "category", "accepted_payer_types", "test_only" ] }, "TransactionKind": { "type": "string", "enum": [ "credit", "debit", "refund", "bonus", "adjustment" ] }, "TransactionListQuery": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "credit", "debit", "refund", "bonus", "adjustment" ] }, "from": { "type": "string" }, "to": { "type": "string" }, "period": { "type": "string" } } }, "TransactionListResponse": { "type": "object", "properties": { "transactions": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "kind": { "type": "string", "enum": [ "credit", "debit", "refund", "bonus", "adjustment" ] }, "currency": { "type": "string" }, "amount": { "type": [ "number", "null" ] }, "balance_after": { "type": [ "number", "null" ] }, "bonus_after": { "type": [ "number", "null" ] }, "description": { "type": "string" }, "description_text": { "type": "string" }, "invoice_id": { "type": [ "string", "null" ] }, "server_name": { "type": [ "string", "null" ] }, "created_at": { "type": "string" } }, "required": [ "id", "kind", "currency", "amount", "balance_after", "bonus_after", "description", "description_text", "invoice_id", "server_name", "created_at" ] } }, "meta": { "type": "object", "properties": { "pagination": { "type": "object", "properties": { "page": { "type": "integer", "minimum": 0 }, "per_page": { "type": "integer", "exclusiveMinimum": 0 }, "previous_page": { "type": [ "integer", "null" ], "exclusiveMinimum": 0 }, "next_page": { "type": [ "integer", "null" ], "exclusiveMinimum": 0 }, "last_page": { "type": "integer", "exclusiveMinimum": 0 }, "total_entries": { "type": "integer", "minimum": 0 } }, "required": [ "page", "per_page", "previous_page", "next_page", "last_page", "total_entries" ] } }, "required": [ "pagination" ] } }, "required": [ "transactions", "meta" ] }, "Transaction": { "type": "object", "properties": { "id": { "type": "string" }, "kind": { "type": "string", "enum": [ "credit", "debit", "refund", "bonus", "adjustment" ] }, "currency": { "type": "string" }, "amount": { "type": [ "number", "null" ] }, "balance_after": { "type": [ "number", "null" ] }, "bonus_after": { "type": [ "number", "null" ] }, "description": { "type": "string" }, "description_text": { "type": "string" }, "invoice_id": { "type": [ "string", "null" ] }, "server_name": { "type": [ "string", "null" ] }, "created_at": { "type": "string" } }, "required": [ "id", "kind", "currency", "amount", "balance_after", "bonus_after", "description", "description_text", "invoice_id", "server_name", "created_at" ] }, "ActionRef": { "type": "object", "properties": { "id": { "type": "string" }, "command": { "type": "string" }, "status": { "type": "string", "enum": [ "running", "success", "error" ] }, "progress": { "type": "integer", "minimum": 0, "maximum": 100 }, "started_at": { "type": "string" }, "finished_at": { "type": [ "string", "null" ] } }, "required": [ "id", "command", "status", "progress", "started_at" ] }, "ApiErrorEnvelope": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} }, "request_id": { "type": "string" } }, "required": [ "code", "message", "request_id" ] } }, "required": [ "error" ] }, "MetaEnvelope": { "type": "object", "properties": { "meta": { "type": "object", "properties": { "pagination": { "type": "object", "properties": { "page": { "type": "integer", "minimum": 0 }, "per_page": { "type": "integer", "exclusiveMinimum": 0 }, "previous_page": { "type": [ "integer", "null" ], "exclusiveMinimum": 0 }, "next_page": { "type": [ "integer", "null" ], "exclusiveMinimum": 0 }, "last_page": { "type": "integer", "exclusiveMinimum": 0 }, "total_entries": { "type": "integer", "minimum": 0 } }, "required": [ "page", "per_page", "previous_page", "next_page", "last_page", "total_entries" ] } }, "required": [ "pagination" ] } }, "required": [ "meta" ] }, "AddIpsInput": { "type": "object", "properties": { "ipv4": { "type": "integer", "minimum": 0, "maximum": 8 }, "ipv6": { "type": "boolean" }, "use_bonus": { "type": "boolean" } } }, "AddIpsPreviewQuery": { "type": "object", "properties": { "ipv4": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 8 }, "ipv6": { "type": "boolean" } } }, "AddIpsPreviewResponse": { "type": "object", "properties": { "preview": { "type": "object", "properties": { "action_path": { "type": "string" }, "requires_tfa": { "type": "boolean" }, "financials": { "type": "object", "properties": { "direction": { "type": "string", "enum": [ "refund", "charge", "none" ] }, "amount": { "type": [ "number", "null" ] }, "currency": { "type": "string" }, "days_unused": { "type": [ "integer", "null" ] }, "days_total": { "type": [ "integer", "null" ] }, "breakdown": { "type": "array", "items": { "type": "object", "properties": { "kind": { "type": "string" }, "target": { "type": [ "string", "null" ] }, "amount": { "type": [ "number", "null" ] } }, "required": [ "kind", "target", "amount" ] } } }, "required": [ "direction", "amount", "currency", "days_unused", "days_total" ] }, "effects": { "type": "array", "items": { "type": "object", "properties": { "kind": { "type": "string" }, "target": { "type": [ "string", "null" ] }, "count": { "type": "integer" }, "note": { "type": "string" } }, "required": [ "kind", "target" ] } }, "ips": { "type": "object", "properties": { "ipv4_count": { "type": "integer", "minimum": 0 }, "ipv6": { "type": "boolean" }, "unit_price_v4": { "type": [ "number", "null" ] }, "unit_price_v6": { "type": [ "number", "null" ] }, "prorated_multiplier": { "type": "number" }, "discount_percent": { "type": "integer", "minimum": 0 } }, "required": [ "ipv4_count", "ipv6", "unit_price_v4", "unit_price_v6", "prorated_multiplier", "discount_percent" ] } }, "required": [ "action_path", "requires_tfa", "financials", "effects", "ips" ], "additionalProperties": {} } }, "required": [ "preview" ] }, "Ip6PtrRecord": { "type": "object", "properties": { "address": { "type": "string" }, "ptr": { "type": "string" } }, "required": [ "address", "ptr" ] }, "IpActionResponse": { "type": "object", "properties": { "action": { "type": "object", "properties": { "id": { "type": "string" }, "command": { "type": "string" }, "status": { "type": "string", "enum": [ "running", "success", "error" ] }, "progress": { "type": "integer", "minimum": 0, "maximum": 100 }, "resources": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string" } }, "required": [ "id", "type" ] } }, "error": { "type": [ "object", "null" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] }, "started_at": { "type": "string" }, "finished_at": { "type": [ "string", "null" ] } }, "required": [ "id", "command", "status", "progress", "resources", "error", "started_at", "finished_at" ] }, "server": { "type": "object", "properties": { "name": { "type": "string" }, "type": { "type": "string", "enum": [ "virtual", "physical" ] }, "hostname": { "type": [ "string", "null" ] }, "status": { "type": "string", "enum": [ "new", "installing", "inventory", "active" ] }, "power_state": { "type": "string", "enum": [ "running", "stopped", "unknown" ] }, "location": { "type": "string" }, "os": { "type": "object", "properties": { "code": { "type": [ "string", "null" ] }, "name": { "type": [ "string", "null" ] }, "version": { "type": [ "string", "null" ] }, "family": { "type": [ "string", "null" ] } }, "required": [ "code", "name", "version", "family" ] }, "primary_ip": { "type": [ "string", "null" ] }, "ips": { "type": "array", "items": { "type": "string" } }, "ipv6": { "type": "array", "items": { "type": "string" } }, "config": { "type": "object", "properties": { "cpu": { "type": "integer", "minimum": 0 }, "ram": { "type": "integer", "minimum": 0 }, "ssd": { "type": "integer", "minimum": 0 }, "hdd": { "type": [ "integer", "null" ], "minimum": 0 }, "cpu_frequency": { "type": "number", "minimum": 0 }, "tier": { "type": "string", "enum": [ "standard", "high-perf" ] } }, "required": [ "cpu", "ram", "ssd", "hdd", "cpu_frequency", "tier" ] }, "expires_at": { "type": [ "string", "null" ] }, "autorenew": { "type": "boolean" }, "created_at": { "type": "string" } }, "required": [ "name", "type", "hostname", "status", "power_state", "location", "os", "primary_ip", "ips", "ipv6", "config", "expires_at", "autorenew", "created_at" ] } }, "required": [ "action", "server" ] }, "IpAddress": { "type": "object", "properties": { "ip": { "type": "string" }, "kind": { "type": "string", "enum": [ "v4", "v6" ] }, "is_primary": { "type": "boolean" }, "ptr": { "type": [ "string", "null" ] }, "server_name": { "type": [ "string", "null" ] }, "network_id": { "type": [ "string", "null" ] }, "location": { "type": [ "string", "null" ] }, "assigned_at": { "type": [ "string", "null" ] }, "ptr_records": { "type": [ "array", "null" ], "items": { "type": "object", "properties": { "address": { "type": "string" }, "ptr": { "type": "string" } }, "required": [ "address", "ptr" ] } } }, "required": [ "ip", "kind", "is_primary", "ptr", "server_name", "network_id", "location", "assigned_at", "ptr_records" ] }, "IpPath": { "type": "string", "pattern": "^(?:(?:\\d{1,3}\\.){3}\\d{1,3}|[0-9a-fA-F:]+)$" }, "IpResponse": { "type": "object", "properties": { "ip_address": { "type": "object", "properties": { "ip": { "type": "string" }, "kind": { "type": "string", "enum": [ "v4", "v6" ] }, "is_primary": { "type": "boolean" }, "ptr": { "type": [ "string", "null" ] }, "server_name": { "type": [ "string", "null" ] }, "network_id": { "type": [ "string", "null" ] }, "location": { "type": [ "string", "null" ] }, "assigned_at": { "type": [ "string", "null" ] }, "ptr_records": { "type": [ "array", "null" ], "items": { "type": "object", "properties": { "address": { "type": "string" }, "ptr": { "type": "string" } }, "required": [ "address", "ptr" ] } } }, "required": [ "ip", "kind", "is_primary", "ptr", "server_name", "network_id", "location", "assigned_at", "ptr_records" ] } }, "required": [ "ip_address" ] }, "ServerIpListResponse": { "type": "object", "properties": { "ip_addresses": { "type": "array", "items": { "type": "object", "properties": { "ip": { "type": "string" }, "kind": { "type": "string", "enum": [ "v4", "v6" ] }, "is_primary": { "type": "boolean" }, "ptr": { "type": [ "string", "null" ] }, "server_name": { "type": [ "string", "null" ] }, "network_id": { "type": [ "string", "null" ] }, "location": { "type": [ "string", "null" ] }, "assigned_at": { "type": [ "string", "null" ] }, "ptr_records": { "type": [ "array", "null" ], "items": { "type": "object", "properties": { "address": { "type": "string" }, "ptr": { "type": "string" } }, "required": [ "address", "ptr" ] } } }, "required": [ "ip", "kind", "is_primary", "ptr", "server_name", "network_id", "location", "assigned_at", "ptr_records" ] } } }, "required": [ "ip_addresses" ] }, "SetPtrInput": { "type": "object", "properties": { "ptr": { "type": [ "string", "null" ], "minLength": 1, "maxLength": 253 } }, "required": [ "ptr" ] }, "Location": { "type": "object", "properties": { "code": { "type": "string" }, "name": { "type": "string" }, "city": { "type": [ "string", "null" ] }, "country": { "type": [ "string", "null" ] }, "flag": { "type": [ "string", "null" ] }, "offerings": { "type": "object", "properties": { "dedicated": { "type": "boolean" }, "vps": { "type": "boolean" }, "hiperf": { "type": "boolean" } }, "required": [ "dedicated", "vps", "hiperf" ] } }, "required": [ "code", "name", "city", "country", "flag", "offerings" ] }, "CreateOrderInput": { "type": "object", "properties": { "server_type": { "type": "string", "enum": [ "virtual", "physical" ], "default": "virtual" }, "tier": { "type": "string", "enum": [ "standard", "hiperf" ], "default": "standard" }, "cpu": { "type": "integer", "minimum": 1, "maximum": 64 }, "ram": { "type": "integer", "minimum": 1, "maximum": 256 }, "ssd": { "type": "integer", "minimum": 10, "maximum": 2000 }, "hdd": { "type": "integer", "minimum": 0, "maximum": 8000, "default": 0 }, "location_code": { "type": "string", "minLength": 1, "maxLength": 10 }, "locations": { "type": "array", "items": { "type": "object", "properties": { "location_code": { "type": "string", "minLength": 1, "maxLength": 10 }, "quantity": { "type": "integer", "minimum": 1, "maximum": 10, "default": 1 } }, "required": [ "location_code" ] }, "minItems": 1, "maxItems": 10 }, "os_template_code": { "type": "string", "minLength": 1, "maxLength": 60 }, "hostname": { "type": "string", "minLength": 1, "maxLength": 253 }, "ssh_key_ids": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 40 }, "maxItems": 10 }, "password": { "type": "string", "minLength": 6, "maxLength": 128 }, "ipv4": { "type": "integer", "minimum": 1, "maximum": 8, "default": 1 }, "ipv6": { "type": "boolean", "default": false }, "services": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 40 }, "quantity": { "type": "number", "enum": [ 1 ], "default": 1 } }, "required": [ "id" ] }, "maxItems": 10 }, "period_months": { "anyOf": [ { "type": "number", "enum": [ 1 ] }, { "type": "number", "enum": [ 2 ] }, { "type": "number", "enum": [ 3 ] }, { "type": "number", "enum": [ 6 ] }, { "type": "number", "enum": [ 12 ] } ], "default": 1 }, "auto_renew": { "type": "boolean", "default": true }, "promo_code": { "type": "string", "maxLength": 40 }, "note": { "type": "string", "maxLength": 500 }, "physical_server_id": { "type": "string", "minLength": 1, "maxLength": 40 } }, "required": [ "os_template_code" ] }, "CreateOrderLocation": { "type": "object", "properties": { "location_code": { "type": "string", "minLength": 1, "maxLength": 10 }, "quantity": { "type": "integer", "minimum": 1, "maximum": 10, "default": 1 } }, "required": [ "location_code" ] }, "CreateOrderResponse": { "type": "object", "properties": { "order": { "type": "object", "properties": { "id": { "type": "string" }, "status": { "type": "string", "enum": [ "pending_payment", "provisioning", "completed", "failed", "cancelled", "expired" ] }, "server_type": { "type": "string", "enum": [ "virtual", "physical" ] }, "tier": { "type": [ "string", "null" ], "enum": [ "standard", "hiperf", null ] }, "config": { "type": [ "object", "null" ], "properties": { "cpu": { "type": [ "integer", "null" ] }, "ram": { "type": [ "integer", "null" ] }, "ssd": { "type": [ "integer", "null" ] }, "hdd": { "type": [ "integer", "null" ] } }, "required": [ "cpu", "ram", "ssd", "hdd" ] }, "locations": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string" }, "quantity": { "type": "integer", "minimum": 1 } }, "required": [ "code", "quantity" ] } }, "os_template": { "type": [ "object", "null" ], "properties": { "code": { "type": "string" }, "name": { "type": [ "string", "null" ] } }, "required": [ "code", "name" ] }, "hostname": { "type": [ "string", "null" ] }, "ipv4": { "type": [ "integer", "null" ] }, "ipv6": { "type": [ "integer", "null" ] }, "services": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string" }, "name": { "type": "string" }, "quantity": { "type": "integer", "minimum": 1 } }, "required": [ "code", "name", "quantity" ] } }, "period_months": { "type": "integer" }, "period": { "type": [ "object", "null" ], "properties": { "from": { "type": "string" }, "to": { "type": "string" } }, "required": [ "from", "to" ] }, "amount": { "type": [ "number", "null" ] }, "currency": { "type": "string" }, "invoice_id": { "type": [ "string", "null" ] }, "server_names": { "type": "array", "items": { "type": "string" } }, "created_at": { "type": "string" }, "paid_at": { "type": [ "string", "null" ] }, "completed_at": { "type": [ "string", "null" ] } }, "required": [ "id", "status", "server_type", "tier", "config", "locations", "os_template", "hostname", "ipv4", "ipv6", "services", "period_months", "period", "amount", "currency", "invoice_id", "server_names", "created_at", "paid_at", "completed_at" ] }, "invoice": { "type": "object", "properties": { "id": { "type": "string" }, "number": { "type": "string" }, "status": { "type": "string", "enum": [ "draft", "pending", "partial", "paid", "cancelled", "refunded" ] }, "currency": { "type": "string" }, "amount": { "type": [ "number", "null" ] }, "amount_paid": { "type": [ "number", "null" ] }, "amount_remaining": { "type": [ "number", "null" ] }, "description": { "type": "string" }, "description_text": { "type": "string" }, "items": { "type": "array", "items": { "type": "object", "properties": { "description": { "type": "string" }, "description_text": { "type": "string" }, "quantity": { "type": "number" }, "unit_price": { "type": [ "number", "null" ] }, "total": { "type": [ "number", "null" ] }, "type": { "type": "string" }, "server_name": { "type": [ "string", "null" ] }, "period": { "type": [ "object", "null" ], "properties": { "from": { "type": "string" }, "to": { "type": "string" }, "days": { "type": "number" } }, "required": [ "from", "to", "days" ] } }, "required": [ "description", "description_text", "quantity", "unit_price", "total", "type", "server_name", "period" ] } }, "gateway": { "type": [ "object", "null" ], "properties": { "slug": { "type": "string" }, "name": { "type": "string" } }, "required": [ "slug", "name" ] }, "created_at": { "type": "string" }, "paid_at": { "type": [ "string", "null" ] }, "due_at": { "type": [ "string", "null" ] } }, "required": [ "id", "number", "status", "currency", "amount", "amount_paid", "amount_remaining", "description", "description_text", "items", "gateway", "created_at", "paid_at", "due_at" ] } }, "required": [ "order", "invoice" ] }, "OrderListQuery": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "pending_payment", "provisioning", "completed", "failed", "cancelled", "expired" ] }, "from": { "type": "string" }, "to": { "type": "string" }, "period": { "type": "string" } } }, "OrderListResponse": { "type": "object", "properties": { "orders": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "status": { "type": "string", "enum": [ "pending_payment", "provisioning", "completed", "failed", "cancelled", "expired" ] }, "server_type": { "type": "string", "enum": [ "virtual", "physical" ] }, "tier": { "type": [ "string", "null" ], "enum": [ "standard", "hiperf", null ] }, "config": { "type": [ "object", "null" ], "properties": { "cpu": { "type": [ "integer", "null" ] }, "ram": { "type": [ "integer", "null" ] }, "ssd": { "type": [ "integer", "null" ] }, "hdd": { "type": [ "integer", "null" ] } }, "required": [ "cpu", "ram", "ssd", "hdd" ] }, "locations": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string" }, "quantity": { "type": "integer", "minimum": 1 } }, "required": [ "code", "quantity" ] } }, "os_template": { "type": [ "object", "null" ], "properties": { "code": { "type": "string" }, "name": { "type": [ "string", "null" ] } }, "required": [ "code", "name" ] }, "hostname": { "type": [ "string", "null" ] }, "ipv4": { "type": [ "integer", "null" ] }, "ipv6": { "type": [ "integer", "null" ] }, "services": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string" }, "name": { "type": "string" }, "quantity": { "type": "integer", "minimum": 1 } }, "required": [ "code", "name", "quantity" ] } }, "period_months": { "type": "integer" }, "period": { "type": [ "object", "null" ], "properties": { "from": { "type": "string" }, "to": { "type": "string" } }, "required": [ "from", "to" ] }, "amount": { "type": [ "number", "null" ] }, "currency": { "type": "string" }, "invoice_id": { "type": [ "string", "null" ] }, "server_names": { "type": "array", "items": { "type": "string" } }, "created_at": { "type": "string" }, "paid_at": { "type": [ "string", "null" ] }, "completed_at": { "type": [ "string", "null" ] } }, "required": [ "id", "status", "server_type", "tier", "config", "locations", "os_template", "hostname", "ipv4", "ipv6", "services", "period_months", "period", "amount", "currency", "invoice_id", "server_names", "created_at", "paid_at", "completed_at" ] } }, "meta": { "type": "object", "properties": { "pagination": { "type": "object", "properties": { "page": { "type": "integer", "minimum": 0 }, "per_page": { "type": "integer", "exclusiveMinimum": 0 }, "previous_page": { "type": [ "integer", "null" ], "exclusiveMinimum": 0 }, "next_page": { "type": [ "integer", "null" ], "exclusiveMinimum": 0 }, "last_page": { "type": "integer", "exclusiveMinimum": 0 }, "total_entries": { "type": "integer", "minimum": 0 } }, "required": [ "page", "per_page", "previous_page", "next_page", "last_page", "total_entries" ] } }, "required": [ "pagination" ] } }, "required": [ "orders", "meta" ] }, "OrderLocationRef": { "type": "object", "properties": { "code": { "type": "string" }, "quantity": { "type": "integer", "minimum": 1 } }, "required": [ "code", "quantity" ] }, "OrderPreviewResponse": { "type": "object", "properties": { "preview": { "type": "object", "properties": { "action_path": { "type": "string" }, "requires_tfa": { "type": "boolean" }, "financials": { "type": "object", "properties": { "direction": { "type": "string", "enum": [ "refund", "charge", "none" ] }, "amount": { "type": [ "number", "null" ] }, "currency": { "type": "string" }, "days_unused": { "type": [ "integer", "null" ] }, "days_total": { "type": [ "integer", "null" ] }, "breakdown": { "type": "array", "items": { "type": "object", "properties": { "kind": { "type": "string" }, "target": { "type": [ "string", "null" ] }, "amount": { "type": [ "number", "null" ] } }, "required": [ "kind", "target", "amount" ] } } }, "required": [ "direction", "amount", "currency", "days_unused", "days_total" ] }, "effects": { "type": "array", "items": { "type": "object", "properties": { "kind": { "type": "string" }, "target": { "type": [ "string", "null" ] }, "count": { "type": "integer" }, "note": { "type": "string" } }, "required": [ "kind", "target" ] } }, "order": { "type": "object", "properties": { "server_type": { "type": "string", "enum": [ "virtual", "physical" ] }, "tier": { "type": [ "string", "null" ], "enum": [ "standard", "hiperf", null ] }, "config": { "type": [ "object", "null" ], "properties": { "cpu": { "type": [ "integer", "null" ] }, "ram": { "type": [ "integer", "null" ] }, "ssd": { "type": [ "integer", "null" ] }, "hdd": { "type": [ "integer", "null" ] } }, "required": [ "cpu", "ram", "ssd", "hdd" ] }, "locations": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string" }, "quantity": { "type": "integer", "minimum": 1 } }, "required": [ "code", "quantity" ] } }, "period_months": { "type": "integer" }, "base_price": { "type": [ "number", "null" ] }, "discount_percent": { "type": "integer", "minimum": 0 }, "gross_total": { "type": [ "number", "null" ] }, "total": { "type": [ "number", "null" ] }, "quantity": { "type": "integer", "exclusiveMinimum": 0 }, "promo": { "type": [ "object", "null" ], "properties": { "code": { "type": "string" }, "discount_percent": { "type": "number" }, "discount": { "type": [ "number", "null" ] } }, "required": [ "code", "discount_percent", "discount" ] }, "services_breakdown": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string" }, "quantity": { "type": "integer", "exclusiveMinimum": 0 }, "monthly_price": { "type": [ "number", "null" ] } }, "required": [ "code", "quantity", "monthly_price" ] } } }, "required": [ "server_type", "tier", "config", "locations", "period_months", "base_price", "discount_percent", "gross_total", "total", "quantity" ] } }, "required": [ "action_path", "requires_tfa", "financials", "effects", "order" ], "additionalProperties": {} } }, "required": [ "preview" ] }, "OrderResponse": { "type": "object", "properties": { "order": { "type": "object", "properties": { "id": { "type": "string" }, "status": { "type": "string", "enum": [ "pending_payment", "provisioning", "completed", "failed", "cancelled", "expired" ] }, "server_type": { "type": "string", "enum": [ "virtual", "physical" ] }, "tier": { "type": [ "string", "null" ], "enum": [ "standard", "hiperf", null ] }, "config": { "type": [ "object", "null" ], "properties": { "cpu": { "type": [ "integer", "null" ] }, "ram": { "type": [ "integer", "null" ] }, "ssd": { "type": [ "integer", "null" ] }, "hdd": { "type": [ "integer", "null" ] } }, "required": [ "cpu", "ram", "ssd", "hdd" ] }, "locations": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string" }, "quantity": { "type": "integer", "minimum": 1 } }, "required": [ "code", "quantity" ] } }, "os_template": { "type": [ "object", "null" ], "properties": { "code": { "type": "string" }, "name": { "type": [ "string", "null" ] } }, "required": [ "code", "name" ] }, "hostname": { "type": [ "string", "null" ] }, "ipv4": { "type": [ "integer", "null" ] }, "ipv6": { "type": [ "integer", "null" ] }, "services": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string" }, "name": { "type": "string" }, "quantity": { "type": "integer", "minimum": 1 } }, "required": [ "code", "name", "quantity" ] } }, "period_months": { "type": "integer" }, "period": { "type": [ "object", "null" ], "properties": { "from": { "type": "string" }, "to": { "type": "string" } }, "required": [ "from", "to" ] }, "amount": { "type": [ "number", "null" ] }, "currency": { "type": "string" }, "invoice_id": { "type": [ "string", "null" ] }, "server_names": { "type": "array", "items": { "type": "string" } }, "created_at": { "type": "string" }, "paid_at": { "type": [ "string", "null" ] }, "completed_at": { "type": [ "string", "null" ] } }, "required": [ "id", "status", "server_type", "tier", "config", "locations", "os_template", "hostname", "ipv4", "ipv6", "services", "period_months", "period", "amount", "currency", "invoice_id", "server_names", "created_at", "paid_at", "completed_at" ] } }, "required": [ "order" ] }, "Order": { "type": "object", "properties": { "id": { "type": "string" }, "status": { "type": "string", "enum": [ "pending_payment", "provisioning", "completed", "failed", "cancelled", "expired" ] }, "server_type": { "type": "string", "enum": [ "virtual", "physical" ] }, "tier": { "type": [ "string", "null" ], "enum": [ "standard", "hiperf", null ] }, "config": { "type": [ "object", "null" ], "properties": { "cpu": { "type": [ "integer", "null" ] }, "ram": { "type": [ "integer", "null" ] }, "ssd": { "type": [ "integer", "null" ] }, "hdd": { "type": [ "integer", "null" ] } }, "required": [ "cpu", "ram", "ssd", "hdd" ] }, "locations": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string" }, "quantity": { "type": "integer", "minimum": 1 } }, "required": [ "code", "quantity" ] } }, "os_template": { "type": [ "object", "null" ], "properties": { "code": { "type": "string" }, "name": { "type": [ "string", "null" ] } }, "required": [ "code", "name" ] }, "hostname": { "type": [ "string", "null" ] }, "ipv4": { "type": [ "integer", "null" ] }, "ipv6": { "type": [ "integer", "null" ] }, "services": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string" }, "name": { "type": "string" }, "quantity": { "type": "integer", "minimum": 1 } }, "required": [ "code", "name", "quantity" ] } }, "period_months": { "type": "integer" }, "period": { "type": [ "object", "null" ], "properties": { "from": { "type": "string" }, "to": { "type": "string" } }, "required": [ "from", "to" ] }, "amount": { "type": [ "number", "null" ] }, "currency": { "type": "string" }, "invoice_id": { "type": [ "string", "null" ] }, "server_names": { "type": "array", "items": { "type": "string" } }, "created_at": { "type": "string" }, "paid_at": { "type": [ "string", "null" ] }, "completed_at": { "type": [ "string", "null" ] } }, "required": [ "id", "status", "server_type", "tier", "config", "locations", "os_template", "hostname", "ipv4", "ipv6", "services", "period_months", "period", "amount", "currency", "invoice_id", "server_names", "created_at", "paid_at", "completed_at" ] }, "OrderServiceRef": { "type": "object", "properties": { "code": { "type": "string" }, "name": { "type": "string" }, "quantity": { "type": "integer", "minimum": 1 } }, "required": [ "code", "name", "quantity" ] }, "OrderStatus": { "type": "string", "enum": [ "pending_payment", "provisioning", "completed", "failed", "cancelled", "expired" ] }, "OsArch": { "type": "string", "enum": [ "x86_64", "arm64" ] }, "OsFamily": { "type": "string", "enum": [ "linux", "windows" ] }, "OsSoftwareAddon": { "type": "object", "properties": { "code": { "type": "string" }, "name": { "type": "string" } }, "required": [ "code", "name" ] }, "OsTemplate": { "type": "object", "properties": { "code": { "type": "string" }, "name": { "type": "string" }, "version": { "type": "string" }, "family": { "type": "string", "enum": [ "linux", "windows" ] }, "architectures": { "type": "array", "items": { "type": "string", "enum": [ "x86_64", "arm64" ] } }, "compatibility": { "type": "array", "items": { "type": "string", "enum": [ "virtual", "physical" ] } }, "logo": { "type": [ "string", "null" ] }, "software": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string" }, "name": { "type": "string" } }, "required": [ "code", "name" ] } } }, "required": [ "code", "name", "version", "family", "architectures", "compatibility", "logo", "software" ] }, "PricingIp": { "type": "object", "properties": { "unit_price": { "type": "number" }, "free_per_server": { "type": "integer" } }, "required": [ "unit_price", "free_per_server" ] }, "PricingResource": { "type": "object", "properties": { "unit": { "type": "string", "enum": [ "cores", "GB" ] }, "unit_price": { "type": "number" }, "values": { "type": "array", "items": { "type": "number" } } }, "required": [ "unit", "unit_price", "values" ] }, "Pricing": { "type": "object", "properties": { "version": { "type": "string" }, "currency": { "type": "string" }, "tiers": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "standard", "hiperf" ] }, "label": { "type": "string" }, "description": { "type": "string" }, "resources": { "type": "object", "properties": { "cpu": { "type": "object", "properties": { "unit": { "type": "string", "enum": [ "cores", "GB" ] }, "unit_price": { "type": "number" }, "values": { "type": "array", "items": { "type": "number" } } }, "required": [ "unit", "unit_price", "values" ] }, "ram": { "type": "object", "properties": { "unit": { "type": "string", "enum": [ "cores", "GB" ] }, "unit_price": { "type": "number" }, "values": { "type": "array", "items": { "type": "number" } } }, "required": [ "unit", "unit_price", "values" ] }, "disk": { "type": "object", "properties": { "unit": { "type": "string", "enum": [ "cores", "GB" ] }, "unit_price": { "type": "number" }, "values": { "type": "array", "items": { "type": "number" } }, "kind": { "type": "string", "enum": [ "ssd", "nvme" ] } }, "required": [ "unit", "unit_price", "values", "kind" ] }, "hdd": { "type": "object", "properties": { "unit": { "type": "string", "enum": [ "cores", "GB" ] }, "unit_price": { "type": "number" }, "values": { "type": "array", "items": { "type": "number" } } }, "required": [ "unit", "unit_price", "values" ] } }, "required": [ "cpu", "ram", "disk", "hdd" ] } }, "required": [ "code", "label", "description", "resources" ] } }, "ip": { "type": "object", "properties": { "v4": { "type": "object", "properties": { "unit_price": { "type": "number" }, "free_per_server": { "type": "integer" } }, "required": [ "unit_price", "free_per_server" ] }, "v6": { "type": "object", "properties": { "unit_price": { "type": "number" }, "free_per_server": { "type": "integer" } }, "required": [ "unit_price", "free_per_server" ] } }, "required": [ "v4", "v6" ] }, "period_discounts": { "type": "array", "items": { "type": "object", "properties": { "min_months": { "type": "integer" }, "percent": { "type": "number" } }, "required": [ "min_months", "percent" ] } }, "volume_discounts": { "type": "array", "items": { "type": "object", "properties": { "min_servers": { "type": "integer" }, "percent": { "type": "number" } }, "required": [ "min_servers", "percent" ] } }, "rules": { "type": "object", "properties": { "rounding": { "type": "string", "enum": [ "half_up_2dp_per_step" ] }, "period": { "type": "string", "enum": [ "calendar_months" ] }, "disk_shrink": { "type": "boolean", "enum": [ false ] }, "cpu_ram_decrease_requires_poweroff": { "type": "boolean", "enum": [ true ] } }, "required": [ "rounding", "period", "disk_shrink", "cpu_ram_decrease_requires_poweroff" ] } }, "required": [ "version", "currency", "tiers", "ip", "period_discounts", "volume_discounts", "rules" ] }, "PricingTier": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "standard", "hiperf" ] }, "label": { "type": "string" }, "description": { "type": "string" }, "resources": { "type": "object", "properties": { "cpu": { "type": "object", "properties": { "unit": { "type": "string", "enum": [ "cores", "GB" ] }, "unit_price": { "type": "number" }, "values": { "type": "array", "items": { "type": "number" } } }, "required": [ "unit", "unit_price", "values" ] }, "ram": { "type": "object", "properties": { "unit": { "type": "string", "enum": [ "cores", "GB" ] }, "unit_price": { "type": "number" }, "values": { "type": "array", "items": { "type": "number" } } }, "required": [ "unit", "unit_price", "values" ] }, "disk": { "type": "object", "properties": { "unit": { "type": "string", "enum": [ "cores", "GB" ] }, "unit_price": { "type": "number" }, "values": { "type": "array", "items": { "type": "number" } }, "kind": { "type": "string", "enum": [ "ssd", "nvme" ] } }, "required": [ "unit", "unit_price", "values", "kind" ] }, "hdd": { "type": "object", "properties": { "unit": { "type": "string", "enum": [ "cores", "GB" ] }, "unit_price": { "type": "number" }, "values": { "type": "array", "items": { "type": "number" } } }, "required": [ "unit", "unit_price", "values" ] } }, "required": [ "cpu", "ram", "disk", "hdd" ] } }, "required": [ "code", "label", "description", "resources" ] }, "RenewInput": { "type": "object", "properties": { "months": { "type": "integer", "minimum": 1, "maximum": 12 }, "to": { "type": "string" }, "pay": { "type": "string", "enum": [ "balance", "invoice" ], "default": "balance" }, "use_bonus": { "type": "boolean", "default": false }, "supersede": { "type": "boolean", "default": false } } }, "RenewalConflict": { "type": "object", "properties": { "invoice_id": { "type": "string" }, "total": { "type": "number" }, "currency": { "type": "string" }, "due_at": { "type": [ "string", "null" ] }, "server_names": { "type": "array", "items": { "type": "string" } }, "all_server_names": { "type": "array", "items": { "type": "string" } } }, "required": [ "invoice_id", "total", "currency", "due_at", "server_names", "all_server_names" ] }, "RenewalPreviewQuery": { "type": "object", "properties": { "months": { "type": "integer", "minimum": 1, "maximum": 12 }, "to": { "type": "string" }, "use_bonus": { "type": "string", "enum": [ "true", "false" ] } } }, "RenewalPreviewResponse": { "type": "object", "properties": { "preview": { "type": "object", "properties": { "current_expire": { "type": "string" }, "new_expire": { "type": "string" }, "days": { "type": "integer" }, "price": { "type": "number" }, "gross_price": { "type": "number" }, "discount_percent": { "type": "number" }, "currency": { "type": "string" }, "balance": { "type": "number" }, "bonus": { "type": "number" }, "spendable": { "type": "number" }, "affordable": { "type": "boolean" }, "conflicts": { "type": "array", "items": { "type": "object", "properties": { "invoice_id": { "type": "string" }, "total": { "type": "number" }, "currency": { "type": "string" }, "due_at": { "type": [ "string", "null" ] }, "server_names": { "type": "array", "items": { "type": "string" } }, "all_server_names": { "type": "array", "items": { "type": "string" } } }, "required": [ "invoice_id", "total", "currency", "due_at", "server_names", "all_server_names" ] } } }, "required": [ "current_expire", "new_expire", "days", "price", "gross_price", "discount_percent", "currency", "balance", "bonus", "spendable", "affordable", "conflicts" ] } }, "required": [ "preview" ] }, "RenewalPreview": { "type": "object", "properties": { "current_expire": { "type": "string" }, "new_expire": { "type": "string" }, "days": { "type": "integer" }, "price": { "type": "number" }, "gross_price": { "type": "number" }, "discount_percent": { "type": "number" }, "currency": { "type": "string" }, "balance": { "type": "number" }, "bonus": { "type": "number" }, "spendable": { "type": "number" }, "affordable": { "type": "boolean" }, "conflicts": { "type": "array", "items": { "type": "object", "properties": { "invoice_id": { "type": "string" }, "total": { "type": "number" }, "currency": { "type": "string" }, "due_at": { "type": [ "string", "null" ] }, "server_names": { "type": "array", "items": { "type": "string" } }, "all_server_names": { "type": "array", "items": { "type": "string" } } }, "required": [ "invoice_id", "total", "currency", "due_at", "server_names", "all_server_names" ] } } }, "required": [ "current_expire", "new_expire", "days", "price", "gross_price", "discount_percent", "currency", "balance", "bonus", "spendable", "affordable", "conflicts" ] }, "RenewalResponse": { "type": "object", "properties": { "renewal": { "type": "object", "properties": { "current_expire": { "type": "string" }, "new_expire": { "type": "string" }, "days": { "type": "integer" }, "price": { "type": "number" }, "gross_price": { "type": "number" }, "discount_percent": { "type": "number" }, "currency": { "type": "string" }, "invoice_id": { "type": "string" }, "paid": { "type": "boolean" }, "superseded_invoice_ids": { "type": "array", "items": { "type": "string" } }, "invoice": { "type": "object", "properties": { "id": { "type": "string" }, "number": { "type": "string" }, "status": { "type": "string", "enum": [ "draft", "pending", "partial", "paid", "cancelled", "refunded" ] }, "currency": { "type": "string" }, "amount": { "type": [ "number", "null" ] }, "amount_paid": { "type": [ "number", "null" ] }, "amount_remaining": { "type": [ "number", "null" ] }, "description": { "type": "string" }, "description_text": { "type": "string" }, "items": { "type": "array", "items": { "type": "object", "properties": { "description": { "type": "string" }, "description_text": { "type": "string" }, "quantity": { "type": "number" }, "unit_price": { "type": [ "number", "null" ] }, "total": { "type": [ "number", "null" ] }, "type": { "type": "string" }, "server_name": { "type": [ "string", "null" ] }, "period": { "type": [ "object", "null" ], "properties": { "from": { "type": "string" }, "to": { "type": "string" }, "days": { "type": "number" } }, "required": [ "from", "to", "days" ] } }, "required": [ "description", "description_text", "quantity", "unit_price", "total", "type", "server_name", "period" ] } }, "gateway": { "type": [ "object", "null" ], "properties": { "slug": { "type": "string" }, "name": { "type": "string" } }, "required": [ "slug", "name" ] }, "created_at": { "type": "string" }, "paid_at": { "type": [ "string", "null" ] }, "due_at": { "type": [ "string", "null" ] } }, "required": [ "id", "number", "status", "currency", "amount", "amount_paid", "amount_remaining", "description", "description_text", "items", "gateway", "created_at", "paid_at", "due_at" ] } }, "required": [ "current_expire", "new_expire", "days", "price", "gross_price", "discount_percent", "currency", "invoice_id", "paid", "superseded_invoice_ids", "invoice" ] } }, "required": [ "renewal" ] }, "Renewal": { "type": "object", "properties": { "current_expire": { "type": "string" }, "new_expire": { "type": "string" }, "days": { "type": "integer" }, "price": { "type": "number" }, "gross_price": { "type": "number" }, "discount_percent": { "type": "number" }, "currency": { "type": "string" }, "invoice_id": { "type": "string" }, "paid": { "type": "boolean" }, "superseded_invoice_ids": { "type": "array", "items": { "type": "string" } }, "invoice": { "type": "object", "properties": { "id": { "type": "string" }, "number": { "type": "string" }, "status": { "type": "string", "enum": [ "draft", "pending", "partial", "paid", "cancelled", "refunded" ] }, "currency": { "type": "string" }, "amount": { "type": [ "number", "null" ] }, "amount_paid": { "type": [ "number", "null" ] }, "amount_remaining": { "type": [ "number", "null" ] }, "description": { "type": "string" }, "description_text": { "type": "string" }, "items": { "type": "array", "items": { "type": "object", "properties": { "description": { "type": "string" }, "description_text": { "type": "string" }, "quantity": { "type": "number" }, "unit_price": { "type": [ "number", "null" ] }, "total": { "type": [ "number", "null" ] }, "type": { "type": "string" }, "server_name": { "type": [ "string", "null" ] }, "period": { "type": [ "object", "null" ], "properties": { "from": { "type": "string" }, "to": { "type": "string" }, "days": { "type": "number" } }, "required": [ "from", "to", "days" ] } }, "required": [ "description", "description_text", "quantity", "unit_price", "total", "type", "server_name", "period" ] } }, "gateway": { "type": [ "object", "null" ], "properties": { "slug": { "type": "string" }, "name": { "type": "string" } }, "required": [ "slug", "name" ] }, "created_at": { "type": "string" }, "paid_at": { "type": [ "string", "null" ] }, "due_at": { "type": [ "string", "null" ] } }, "required": [ "id", "number", "status", "currency", "amount", "amount_paid", "amount_remaining", "description", "description_text", "items", "gateway", "created_at", "paid_at", "due_at" ] } }, "required": [ "current_expire", "new_expire", "days", "price", "gross_price", "discount_percent", "currency", "invoice_id", "paid", "superseded_invoice_ids", "invoice" ] }, "CancelImmediateResponse": { "type": "object", "properties": { "action": { "type": "object", "properties": { "id": { "type": "string" }, "command": { "type": "string" }, "status": { "type": "string", "enum": [ "running", "success", "error" ] }, "progress": { "type": "integer", "minimum": 0, "maximum": 100 }, "resources": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string" } }, "required": [ "id", "type" ] } }, "error": { "type": [ "object", "null" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] }, "started_at": { "type": "string" }, "finished_at": { "type": [ "string", "null" ] } }, "required": [ "id", "command", "status", "progress", "resources", "error", "started_at", "finished_at" ] }, "server": { "type": "object", "properties": { "name": { "type": "string" }, "type": { "type": "string", "enum": [ "virtual", "physical" ] }, "hostname": { "type": [ "string", "null" ] }, "status": { "type": "string", "enum": [ "new", "installing", "inventory", "active" ] }, "power_state": { "type": "string", "enum": [ "running", "stopped", "unknown" ] }, "location": { "type": "string" }, "os": { "type": "object", "properties": { "code": { "type": [ "string", "null" ] }, "name": { "type": [ "string", "null" ] }, "version": { "type": [ "string", "null" ] }, "family": { "type": [ "string", "null" ] } }, "required": [ "code", "name", "version", "family" ] }, "primary_ip": { "type": [ "string", "null" ] }, "ips": { "type": "array", "items": { "type": "string" } }, "ipv6": { "type": "array", "items": { "type": "string" } }, "config": { "type": "object", "properties": { "cpu": { "type": "integer", "minimum": 0 }, "ram": { "type": "integer", "minimum": 0 }, "ssd": { "type": "integer", "minimum": 0 }, "hdd": { "type": [ "integer", "null" ], "minimum": 0 }, "cpu_frequency": { "type": "number", "minimum": 0 }, "tier": { "type": "string", "enum": [ "standard", "high-perf" ] } }, "required": [ "cpu", "ram", "ssd", "hdd", "cpu_frequency", "tier" ] }, "expires_at": { "type": [ "string", "null" ] }, "autorenew": { "type": "boolean" }, "created_at": { "type": "string" } }, "required": [ "name", "type", "hostname", "status", "power_state", "location", "os", "primary_ip", "ips", "ipv6", "config", "expires_at", "autorenew", "created_at" ] }, "refund_preview": { "type": "object", "properties": { "amount": { "type": [ "number", "null" ] }, "currency": { "type": "string" } }, "required": [ "amount", "currency" ] } }, "required": [ "action", "server", "refund_preview" ] }, "CancelMode": { "type": "string", "enum": [ "immediate", "on_expiry" ], "default": "on_expiry" }, "CancelOnExpiryResponse": { "type": "object", "properties": { "server": { "type": "object", "properties": { "name": { "type": "string" }, "type": { "type": "string", "enum": [ "virtual", "physical" ] }, "hostname": { "type": [ "string", "null" ] }, "status": { "type": "string", "enum": [ "new", "installing", "inventory", "active" ] }, "power_state": { "type": "string", "enum": [ "running", "stopped", "unknown" ] }, "location": { "type": "string" }, "os": { "type": "object", "properties": { "code": { "type": [ "string", "null" ] }, "name": { "type": [ "string", "null" ] }, "version": { "type": [ "string", "null" ] }, "family": { "type": [ "string", "null" ] } }, "required": [ "code", "name", "version", "family" ] }, "primary_ip": { "type": [ "string", "null" ] }, "ips": { "type": "array", "items": { "type": "string" } }, "ipv6": { "type": "array", "items": { "type": "string" } }, "config": { "type": "object", "properties": { "cpu": { "type": "integer", "minimum": 0 }, "ram": { "type": "integer", "minimum": 0 }, "ssd": { "type": "integer", "minimum": 0 }, "hdd": { "type": [ "integer", "null" ], "minimum": 0 }, "cpu_frequency": { "type": "number", "minimum": 0 }, "tier": { "type": "string", "enum": [ "standard", "high-perf" ] } }, "required": [ "cpu", "ram", "ssd", "hdd", "cpu_frequency", "tier" ] }, "expires_at": { "type": [ "string", "null" ] }, "autorenew": { "type": "boolean" }, "created_at": { "type": "string" } }, "required": [ "name", "type", "hostname", "status", "power_state", "location", "os", "primary_ip", "ips", "ipv6", "config", "expires_at", "autorenew", "created_at" ] } }, "required": [ "server" ] }, "CancelPreviewResponse": { "type": "object", "properties": { "preview": { "type": "object", "properties": { "action_path": { "type": "string" }, "requires_tfa": { "type": "boolean" }, "financials": { "type": "object", "properties": { "direction": { "type": "string", "enum": [ "refund", "charge", "none" ] }, "amount": { "type": [ "number", "null" ] }, "currency": { "type": "string" }, "days_unused": { "type": [ "integer", "null" ] }, "days_total": { "type": [ "integer", "null" ] }, "breakdown": { "type": "array", "items": { "type": "object", "properties": { "kind": { "type": "string" }, "target": { "type": [ "string", "null" ] }, "amount": { "type": [ "number", "null" ] } }, "required": [ "kind", "target", "amount" ] } } }, "required": [ "direction", "amount", "currency", "days_unused", "days_total" ] }, "effects": { "type": "array", "items": { "type": "object", "properties": { "kind": { "type": "string" }, "target": { "type": [ "string", "null" ] }, "count": { "type": "integer" }, "note": { "type": "string" } }, "required": [ "kind", "target" ] } }, "cancel": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "immediate", "on_expiry" ] }, "refund_to": { "type": "string", "enum": [ "balance" ] } }, "required": [ "mode", "refund_to" ] } }, "required": [ "action_path", "requires_tfa", "financials", "effects", "cancel" ], "additionalProperties": {} } }, "required": [ "preview" ] }, "CancelQuery": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "immediate", "on_expiry" ] } } }, "ResizeConfigInput": { "type": "object", "properties": { "cpu": { "type": "integer", "minimum": 1, "maximum": 64 }, "ram": { "type": "integer", "minimum": 1 }, "ssd": { "type": "integer", "minimum": 10 }, "hdd": { "type": [ "integer", "null" ], "minimum": 0 } } }, "ResizeConfig": { "type": "object", "properties": { "cpu": { "type": "integer" }, "ram": { "type": "integer" }, "ssd": { "type": "integer" }, "hdd": { "type": "integer" } }, "required": [ "cpu", "ram", "ssd", "hdd" ] }, "ResizeInput": { "type": "object", "properties": { "config": { "type": "object", "properties": { "cpu": { "type": "integer", "minimum": 1, "maximum": 64 }, "ram": { "type": "integer", "minimum": 1 }, "ssd": { "type": "integer", "minimum": 10 }, "hdd": { "type": [ "integer", "null" ], "minimum": 0 } } }, "use_bonus": { "type": "boolean" } }, "required": [ "config" ] }, "ResizePreviewQuery": { "type": "object", "properties": { "cpu": { "type": "integer", "minimum": 1, "maximum": 64 }, "ram": { "type": "integer", "minimum": 1 }, "ssd": { "type": "integer", "minimum": 10 }, "hdd": { "type": [ "integer", "null" ], "minimum": 0 } } }, "ResizePreviewResponse": { "type": "object", "properties": { "preview": { "type": "object", "properties": { "action_path": { "type": "string" }, "requires_tfa": { "type": "boolean" }, "financials": { "type": "object", "properties": { "direction": { "type": "string", "enum": [ "refund", "charge", "none" ] }, "amount": { "type": [ "number", "null" ] }, "currency": { "type": "string" }, "days_unused": { "type": [ "integer", "null" ] }, "days_total": { "type": [ "integer", "null" ] }, "breakdown": { "type": "array", "items": { "type": "object", "properties": { "kind": { "type": "string" }, "target": { "type": [ "string", "null" ] }, "amount": { "type": [ "number", "null" ] } }, "required": [ "kind", "target", "amount" ] } } }, "required": [ "direction", "amount", "currency", "days_unused", "days_total" ] }, "effects": { "type": "array", "items": { "type": "object", "properties": { "kind": { "type": "string" }, "target": { "type": [ "string", "null" ] }, "count": { "type": "integer" }, "note": { "type": "string" } }, "required": [ "kind", "target" ] } }, "resize": { "type": "object", "properties": { "old_config": { "type": "object", "properties": { "cpu": { "type": "integer" }, "ram": { "type": "integer" }, "ssd": { "type": "integer" }, "hdd": { "type": "integer" } }, "required": [ "cpu", "ram", "ssd", "hdd" ] }, "new_config": { "type": "object", "properties": { "cpu": { "type": "integer" }, "ram": { "type": "integer" }, "ssd": { "type": "integer" }, "hdd": { "type": "integer" } }, "required": [ "cpu", "ram", "ssd", "hdd" ] }, "old_monthly_price": { "type": [ "number", "null" ] }, "new_monthly_price": { "type": [ "number", "null" ] }, "poweroff_required": { "type": "boolean" }, "delta_breakdown": { "type": "array", "items": { "type": "object", "properties": { "kind": { "type": "string" }, "amount": { "type": [ "number", "null" ] }, "note": { "type": "string" } }, "required": [ "kind", "amount" ] } } }, "required": [ "old_config", "new_config", "old_monthly_price", "new_monthly_price", "poweroff_required" ] } }, "required": [ "action_path", "requires_tfa", "financials", "effects", "resize" ], "additionalProperties": {} } }, "required": [ "preview" ] }, "ResizeResponse": { "type": "object", "properties": { "action": { "type": "object", "properties": { "id": { "type": "string" }, "command": { "type": "string" }, "status": { "type": "string", "enum": [ "running", "success", "error" ] }, "progress": { "type": "integer", "minimum": 0, "maximum": 100 }, "resources": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string" } }, "required": [ "id", "type" ] } }, "error": { "type": [ "object", "null" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] }, "started_at": { "type": "string" }, "finished_at": { "type": [ "string", "null" ] } }, "required": [ "id", "command", "status", "progress", "resources", "error", "started_at", "finished_at" ] }, "server": { "type": "object", "properties": { "name": { "type": "string" }, "type": { "type": "string", "enum": [ "virtual", "physical" ] }, "hostname": { "type": [ "string", "null" ] }, "status": { "type": "string", "enum": [ "new", "installing", "inventory", "active" ] }, "power_state": { "type": "string", "enum": [ "running", "stopped", "unknown" ] }, "location": { "type": "string" }, "os": { "type": "object", "properties": { "code": { "type": [ "string", "null" ] }, "name": { "type": [ "string", "null" ] }, "version": { "type": [ "string", "null" ] }, "family": { "type": [ "string", "null" ] } }, "required": [ "code", "name", "version", "family" ] }, "primary_ip": { "type": [ "string", "null" ] }, "ips": { "type": "array", "items": { "type": "string" } }, "ipv6": { "type": "array", "items": { "type": "string" } }, "config": { "type": "object", "properties": { "cpu": { "type": "integer", "minimum": 0 }, "ram": { "type": "integer", "minimum": 0 }, "ssd": { "type": "integer", "minimum": 0 }, "hdd": { "type": [ "integer", "null" ], "minimum": 0 }, "cpu_frequency": { "type": "number", "minimum": 0 }, "tier": { "type": "string", "enum": [ "standard", "high-perf" ] } }, "required": [ "cpu", "ram", "ssd", "hdd", "cpu_frequency", "tier" ] }, "expires_at": { "type": [ "string", "null" ] }, "autorenew": { "type": "boolean" }, "created_at": { "type": "string" } }, "required": [ "name", "type", "hostname", "status", "power_state", "location", "os", "primary_ip", "ips", "ipv6", "config", "expires_at", "autorenew", "created_at" ] }, "invoice": { "type": [ "object", "null" ], "properties": { "id": { "type": "string" }, "number": { "type": "string" }, "status": { "type": "string", "enum": [ "draft", "pending", "partial", "paid", "cancelled", "refunded" ] }, "currency": { "type": "string" }, "amount": { "type": [ "number", "null" ] }, "amount_paid": { "type": [ "number", "null" ] }, "amount_remaining": { "type": [ "number", "null" ] }, "description": { "type": "string" }, "description_text": { "type": "string" }, "items": { "type": "array", "items": { "type": "object", "properties": { "description": { "type": "string" }, "description_text": { "type": "string" }, "quantity": { "type": "number" }, "unit_price": { "type": [ "number", "null" ] }, "total": { "type": [ "number", "null" ] }, "type": { "type": "string" }, "server_name": { "type": [ "string", "null" ] }, "period": { "type": [ "object", "null" ], "properties": { "from": { "type": "string" }, "to": { "type": "string" }, "days": { "type": "number" } }, "required": [ "from", "to", "days" ] } }, "required": [ "description", "description_text", "quantity", "unit_price", "total", "type", "server_name", "period" ] } }, "gateway": { "type": [ "object", "null" ], "properties": { "slug": { "type": "string" }, "name": { "type": "string" } }, "required": [ "slug", "name" ] }, "created_at": { "type": "string" }, "paid_at": { "type": [ "string", "null" ] }, "due_at": { "type": [ "string", "null" ] } }, "required": [ "id", "number", "status", "currency", "amount", "amount_paid", "amount_remaining", "description", "description_text", "items", "gateway", "created_at", "paid_at", "due_at" ] }, "poweroff_required": { "type": "boolean" } }, "required": [ "action", "server", "invoice", "poweroff_required" ] }, "ReinstallInput": { "type": "object", "properties": { "os_template": { "type": "string", "minLength": 1, "maxLength": 100 }, "ssh_key_ids": { "type": "array", "items": { "type": "string", "minLength": 1 }, "maxItems": 10 }, "password": { "type": "string", "minLength": 8, "maxLength": 128 }, "tfa_code": { "type": "string", "minLength": 1, "maxLength": 32 }, "hostname": { "type": "string", "minLength": 1, "maxLength": 253, "pattern": "^[a-zA-Z0-9]([a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?(\\.[a-zA-Z0-9]([a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?)*$" } }, "required": [ "os_template" ] }, "ReinstallResponse": { "type": "object", "properties": { "action": { "type": "object", "properties": { "id": { "type": "string" }, "command": { "type": "string" }, "status": { "type": "string", "enum": [ "running", "success", "error" ] }, "progress": { "type": "integer", "minimum": 0, "maximum": 100 }, "resources": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string" } }, "required": [ "id", "type" ] } }, "error": { "type": [ "object", "null" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] }, "started_at": { "type": "string" }, "finished_at": { "type": [ "string", "null" ] } }, "required": [ "id", "command", "status", "progress", "resources", "error", "started_at", "finished_at" ] }, "server": { "type": "object", "properties": { "name": { "type": "string" }, "type": { "type": "string", "enum": [ "virtual", "physical" ] }, "hostname": { "type": [ "string", "null" ] }, "status": { "type": "string", "enum": [ "new", "installing", "inventory", "active" ] }, "power_state": { "type": "string", "enum": [ "running", "stopped", "unknown" ] }, "location": { "type": "string" }, "os": { "type": "object", "properties": { "code": { "type": [ "string", "null" ] }, "name": { "type": [ "string", "null" ] }, "version": { "type": [ "string", "null" ] }, "family": { "type": [ "string", "null" ] } }, "required": [ "code", "name", "version", "family" ] }, "primary_ip": { "type": [ "string", "null" ] }, "ips": { "type": "array", "items": { "type": "string" } }, "ipv6": { "type": "array", "items": { "type": "string" } }, "config": { "type": "object", "properties": { "cpu": { "type": "integer", "minimum": 0 }, "ram": { "type": "integer", "minimum": 0 }, "ssd": { "type": "integer", "minimum": 0 }, "hdd": { "type": [ "integer", "null" ], "minimum": 0 }, "cpu_frequency": { "type": "number", "minimum": 0 }, "tier": { "type": "string", "enum": [ "standard", "high-perf" ] } }, "required": [ "cpu", "ram", "ssd", "hdd", "cpu_frequency", "tier" ] }, "expires_at": { "type": [ "string", "null" ] }, "autorenew": { "type": "boolean" }, "created_at": { "type": "string" } }, "required": [ "name", "type", "hostname", "status", "power_state", "location", "os", "primary_ip", "ips", "ipv6", "config", "expires_at", "autorenew", "created_at" ] } }, "required": [ "action", "server" ] }, "ActionWithServerResponse": { "type": "object", "properties": { "action": { "type": "object", "properties": { "id": { "type": "string" }, "command": { "type": "string" }, "status": { "type": "string", "enum": [ "running", "success", "error" ] }, "progress": { "type": "integer", "minimum": 0, "maximum": 100 }, "resources": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string" } }, "required": [ "id", "type" ] } }, "error": { "type": [ "object", "null" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] }, "started_at": { "type": "string" }, "finished_at": { "type": [ "string", "null" ] } }, "required": [ "id", "command", "status", "progress", "resources", "error", "started_at", "finished_at" ] }, "server": { "type": "object", "properties": { "name": { "type": "string" }, "type": { "type": "string", "enum": [ "virtual", "physical" ] }, "hostname": { "type": [ "string", "null" ] }, "status": { "type": "string", "enum": [ "new", "installing", "inventory", "active" ] }, "power_state": { "type": "string", "enum": [ "running", "stopped", "unknown" ] }, "location": { "type": "string" }, "os": { "type": "object", "properties": { "code": { "type": [ "string", "null" ] }, "name": { "type": [ "string", "null" ] }, "version": { "type": [ "string", "null" ] }, "family": { "type": [ "string", "null" ] } }, "required": [ "code", "name", "version", "family" ] }, "primary_ip": { "type": [ "string", "null" ] }, "ips": { "type": "array", "items": { "type": "string" } }, "ipv6": { "type": "array", "items": { "type": "string" } }, "config": { "type": "object", "properties": { "cpu": { "type": "integer", "minimum": 0 }, "ram": { "type": "integer", "minimum": 0 }, "ssd": { "type": "integer", "minimum": 0 }, "hdd": { "type": [ "integer", "null" ], "minimum": 0 }, "cpu_frequency": { "type": "number", "minimum": 0 }, "tier": { "type": "string", "enum": [ "standard", "high-perf" ] } }, "required": [ "cpu", "ram", "ssd", "hdd", "cpu_frequency", "tier" ] }, "expires_at": { "type": [ "string", "null" ] }, "autorenew": { "type": "boolean" }, "created_at": { "type": "string" } }, "required": [ "name", "type", "hostname", "status", "power_state", "location", "os", "primary_ip", "ips", "ipv6", "config", "expires_at", "autorenew", "created_at" ] } }, "required": [ "action", "server" ] }, "ConsoleInfo": { "type": "object", "properties": { "url": { "type": "string" }, "type": { "type": "string", "enum": [ "wmks", "ipmi", "vnc" ] }, "expires_at": { "type": "string" }, "password": { "type": "string" } }, "required": [ "url", "type", "expires_at" ] }, "ConsoleRequestInput": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "wmks", "ipmi", "vnc" ] } } }, "ConsoleResponse": { "type": "object", "properties": { "console": { "type": "object", "properties": { "url": { "type": "string" }, "type": { "type": "string", "enum": [ "wmks", "ipmi", "vnc" ] }, "expires_at": { "type": "string" }, "password": { "type": "string" } }, "required": [ "url", "type", "expires_at" ] } }, "required": [ "console" ] }, "ConsoleType": { "type": "string", "enum": [ "wmks", "ipmi", "vnc" ] }, "PatchServerInput": { "type": "object", "properties": { "hostname": { "type": "string", "minLength": 1, "maxLength": 253, "pattern": "^[a-zA-Z0-9]([a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?(\\.[a-zA-Z0-9]([a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?)*$" }, "note": { "type": "string", "maxLength": 500 }, "autorenew": { "type": "boolean" } } }, "PatchServerResponse": { "type": "object", "properties": { "server": { "type": "object", "properties": { "name": { "type": "string" }, "type": { "type": "string", "enum": [ "virtual", "physical" ] }, "hostname": { "type": [ "string", "null" ] }, "status": { "type": "string", "enum": [ "new", "installing", "inventory", "active" ] }, "power_state": { "type": "string", "enum": [ "running", "stopped", "unknown" ] }, "location": { "type": "string" }, "os": { "type": "object", "properties": { "code": { "type": [ "string", "null" ] }, "name": { "type": [ "string", "null" ] }, "version": { "type": [ "string", "null" ] }, "family": { "type": [ "string", "null" ] } }, "required": [ "code", "name", "version", "family" ] }, "primary_ip": { "type": [ "string", "null" ] }, "ips": { "type": "array", "items": { "type": "string" } }, "ipv6": { "type": "array", "items": { "type": "string" } }, "config": { "type": "object", "properties": { "cpu": { "type": "integer", "minimum": 0 }, "ram": { "type": "integer", "minimum": 0 }, "ssd": { "type": "integer", "minimum": 0 }, "hdd": { "type": [ "integer", "null" ], "minimum": 0 }, "cpu_frequency": { "type": "number", "minimum": 0 }, "tier": { "type": "string", "enum": [ "standard", "high-perf" ] } }, "required": [ "cpu", "ram", "ssd", "hdd", "cpu_frequency", "tier" ] }, "expires_at": { "type": [ "string", "null" ] }, "autorenew": { "type": "boolean" }, "created_at": { "type": "string" } }, "required": [ "name", "type", "hostname", "status", "power_state", "location", "os", "primary_ip", "ips", "ipv6", "config", "expires_at", "autorenew", "created_at" ] } }, "required": [ "server" ] }, "PatchServerWithActionResponse": { "type": "object", "properties": { "action": { "type": "object", "properties": { "id": { "type": "string" }, "command": { "type": "string" }, "status": { "type": "string", "enum": [ "running", "success", "error" ] }, "progress": { "type": "integer", "minimum": 0, "maximum": 100 }, "resources": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string" } }, "required": [ "id", "type" ] } }, "error": { "type": [ "object", "null" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] }, "started_at": { "type": "string" }, "finished_at": { "type": [ "string", "null" ] } }, "required": [ "id", "command", "status", "progress", "resources", "error", "started_at", "finished_at" ] }, "server": { "type": "object", "properties": { "name": { "type": "string" }, "type": { "type": "string", "enum": [ "virtual", "physical" ] }, "hostname": { "type": [ "string", "null" ] }, "status": { "type": "string", "enum": [ "new", "installing", "inventory", "active" ] }, "power_state": { "type": "string", "enum": [ "running", "stopped", "unknown" ] }, "location": { "type": "string" }, "os": { "type": "object", "properties": { "code": { "type": [ "string", "null" ] }, "name": { "type": [ "string", "null" ] }, "version": { "type": [ "string", "null" ] }, "family": { "type": [ "string", "null" ] } }, "required": [ "code", "name", "version", "family" ] }, "primary_ip": { "type": [ "string", "null" ] }, "ips": { "type": "array", "items": { "type": "string" } }, "ipv6": { "type": "array", "items": { "type": "string" } }, "config": { "type": "object", "properties": { "cpu": { "type": "integer", "minimum": 0 }, "ram": { "type": "integer", "minimum": 0 }, "ssd": { "type": "integer", "minimum": 0 }, "hdd": { "type": [ "integer", "null" ], "minimum": 0 }, "cpu_frequency": { "type": "number", "minimum": 0 }, "tier": { "type": "string", "enum": [ "standard", "high-perf" ] } }, "required": [ "cpu", "ram", "ssd", "hdd", "cpu_frequency", "tier" ] }, "expires_at": { "type": [ "string", "null" ] }, "autorenew": { "type": "boolean" }, "created_at": { "type": "string" } }, "required": [ "name", "type", "hostname", "status", "power_state", "location", "os", "primary_ip", "ips", "ipv6", "config", "expires_at", "autorenew", "created_at" ] } }, "required": [ "action", "server" ] }, "PowerActionInput": { "type": "object", "properties": { "action": { "type": "string", "enum": [ "on", "off", "restart", "graceful_shutdown", "reset" ] } }, "required": [ "action" ] }, "PowerActionResponse": { "type": "object", "properties": { "action": { "type": "object", "properties": { "id": { "type": "string" }, "command": { "type": "string" }, "status": { "type": "string", "enum": [ "running", "success", "error" ] }, "progress": { "type": "integer", "minimum": 0, "maximum": 100 }, "resources": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string" } }, "required": [ "id", "type" ] } }, "error": { "type": [ "object", "null" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] }, "started_at": { "type": "string" }, "finished_at": { "type": [ "string", "null" ] } }, "required": [ "id", "command", "status", "progress", "resources", "error", "started_at", "finished_at" ] }, "server": { "type": "object", "properties": { "name": { "type": "string" }, "type": { "type": "string", "enum": [ "virtual", "physical" ] }, "hostname": { "type": [ "string", "null" ] }, "status": { "type": "string", "enum": [ "new", "installing", "inventory", "active" ] }, "power_state": { "type": "string", "enum": [ "running", "stopped", "unknown" ] }, "location": { "type": "string" }, "os": { "type": "object", "properties": { "code": { "type": [ "string", "null" ] }, "name": { "type": [ "string", "null" ] }, "version": { "type": [ "string", "null" ] }, "family": { "type": [ "string", "null" ] } }, "required": [ "code", "name", "version", "family" ] }, "primary_ip": { "type": [ "string", "null" ] }, "ips": { "type": "array", "items": { "type": "string" } }, "ipv6": { "type": "array", "items": { "type": "string" } }, "config": { "type": "object", "properties": { "cpu": { "type": "integer", "minimum": 0 }, "ram": { "type": "integer", "minimum": 0 }, "ssd": { "type": "integer", "minimum": 0 }, "hdd": { "type": [ "integer", "null" ], "minimum": 0 }, "cpu_frequency": { "type": "number", "minimum": 0 }, "tier": { "type": "string", "enum": [ "standard", "high-perf" ] } }, "required": [ "cpu", "ram", "ssd", "hdd", "cpu_frequency", "tier" ] }, "expires_at": { "type": [ "string", "null" ] }, "autorenew": { "type": "boolean" }, "created_at": { "type": "string" } }, "required": [ "name", "type", "hostname", "status", "power_state", "location", "os", "primary_ip", "ips", "ipv6", "config", "expires_at", "autorenew", "created_at" ] } }, "required": [ "action", "server" ] }, "ServerConfig": { "type": "object", "properties": { "cpu": { "type": "integer", "minimum": 0 }, "ram": { "type": "integer", "minimum": 0 }, "ssd": { "type": "integer", "minimum": 0 }, "hdd": { "type": [ "integer", "null" ], "minimum": 0 }, "cpu_frequency": { "type": "number", "minimum": 0 }, "tier": { "type": "string", "enum": [ "standard", "high-perf" ] } }, "required": [ "cpu", "ram", "ssd", "hdd", "cpu_frequency", "tier" ] }, "ServerDetail": { "type": "object", "properties": { "name": { "type": "string" }, "type": { "type": "string", "enum": [ "virtual", "physical" ] }, "hostname": { "type": [ "string", "null" ] }, "status": { "type": "string", "enum": [ "new", "installing", "inventory", "active" ] }, "power_state": { "type": "string", "enum": [ "running", "stopped", "unknown" ] }, "location": { "type": "string" }, "os": { "type": "object", "properties": { "code": { "type": [ "string", "null" ] }, "name": { "type": [ "string", "null" ] }, "version": { "type": [ "string", "null" ] }, "family": { "type": [ "string", "null" ] } }, "required": [ "code", "name", "version", "family" ] }, "primary_ip": { "type": [ "string", "null" ] }, "ips": { "type": "array", "items": { "type": "string" } }, "ipv6": { "type": "array", "items": { "type": "string" } }, "config": { "type": "object", "properties": { "cpu": { "type": "integer", "minimum": 0 }, "ram": { "type": "integer", "minimum": 0 }, "ssd": { "type": "integer", "minimum": 0 }, "hdd": { "type": [ "integer", "null" ], "minimum": 0 }, "cpu_frequency": { "type": "number", "minimum": 0 }, "tier": { "type": "string", "enum": [ "standard", "high-perf" ] } }, "required": [ "cpu", "ram", "ssd", "hdd", "cpu_frequency", "tier" ] }, "expires_at": { "type": [ "string", "null" ] }, "autorenew": { "type": "boolean" }, "created_at": { "type": "string" }, "note": { "type": [ "string", "null" ] } }, "required": [ "name", "type", "hostname", "status", "power_state", "location", "os", "primary_ip", "ips", "ipv6", "config", "expires_at", "autorenew", "created_at", "note" ] }, "ServerListQuery": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "new", "installing", "inventory", "active" ] } } }, "ServerOsRef": { "type": "object", "properties": { "code": { "type": [ "string", "null" ] }, "name": { "type": [ "string", "null" ] }, "version": { "type": [ "string", "null" ] }, "family": { "type": [ "string", "null" ] } }, "required": [ "code", "name", "version", "family" ] }, "ServerPowerState": { "type": "string", "enum": [ "running", "stopped", "unknown" ] }, "Server": { "type": "object", "properties": { "name": { "type": "string" }, "type": { "type": "string", "enum": [ "virtual", "physical" ] }, "hostname": { "type": [ "string", "null" ] }, "status": { "type": "string", "enum": [ "new", "installing", "inventory", "active" ] }, "power_state": { "type": "string", "enum": [ "running", "stopped", "unknown" ] }, "location": { "type": "string" }, "os": { "type": "object", "properties": { "code": { "type": [ "string", "null" ] }, "name": { "type": [ "string", "null" ] }, "version": { "type": [ "string", "null" ] }, "family": { "type": [ "string", "null" ] } }, "required": [ "code", "name", "version", "family" ] }, "primary_ip": { "type": [ "string", "null" ] }, "ips": { "type": "array", "items": { "type": "string" } }, "ipv6": { "type": "array", "items": { "type": "string" } }, "config": { "type": "object", "properties": { "cpu": { "type": "integer", "minimum": 0 }, "ram": { "type": "integer", "minimum": 0 }, "ssd": { "type": "integer", "minimum": 0 }, "hdd": { "type": [ "integer", "null" ], "minimum": 0 }, "cpu_frequency": { "type": "number", "minimum": 0 }, "tier": { "type": "string", "enum": [ "standard", "high-perf" ] } }, "required": [ "cpu", "ram", "ssd", "hdd", "cpu_frequency", "tier" ] }, "expires_at": { "type": [ "string", "null" ] }, "autorenew": { "type": "boolean" }, "created_at": { "type": "string" } }, "required": [ "name", "type", "hostname", "status", "power_state", "location", "os", "primary_ip", "ips", "ipv6", "config", "expires_at", "autorenew", "created_at" ] }, "ServerStatus": { "type": "string", "enum": [ "new", "installing", "inventory", "active" ] }, "ServerTier": { "type": "string", "enum": [ "standard", "high-perf" ] }, "ServerType": { "type": "string", "enum": [ "virtual", "physical" ] }, "OrderServiceInput": { "type": "object", "properties": { "code": { "type": "string", "minLength": 1, "maxLength": 60 }, "quantity": { "type": "integer", "minimum": 1, "default": 1 } }, "required": [ "code" ] }, "OrderServicePreviewInput": { "type": "object", "properties": { "code": { "type": "string", "minLength": 1, "maxLength": 60 } }, "required": [ "code" ] }, "OrderServicePreviewResponse": { "type": "object", "properties": { "preview": { "type": "object", "properties": { "action_path": { "type": "string" }, "requires_tfa": { "type": "boolean" }, "financials": { "type": "object", "properties": { "direction": { "type": "string", "enum": [ "refund", "charge", "none" ] }, "amount": { "type": [ "number", "null" ] }, "currency": { "type": "string" }, "days_unused": { "type": [ "integer", "null" ] }, "days_total": { "type": [ "integer", "null" ] }, "breakdown": { "type": "array", "items": { "type": "object", "properties": { "kind": { "type": "string" }, "target": { "type": [ "string", "null" ] }, "amount": { "type": [ "number", "null" ] } }, "required": [ "kind", "target", "amount" ] } } }, "required": [ "direction", "amount", "currency", "days_unused", "days_total" ] }, "effects": { "type": "array", "items": { "type": "object", "properties": { "kind": { "type": "string" }, "target": { "type": [ "string", "null" ] }, "count": { "type": "integer" }, "note": { "type": "string" } }, "required": [ "kind", "target" ] } }, "service": { "type": "object", "properties": { "code": { "type": "string" }, "name": { "type": "string" }, "monthly_price": { "type": [ "number", "null" ] }, "prorated_charge": { "type": [ "number", "null" ] }, "prorated_multiplier": { "type": "number" }, "discount_percent": { "type": "integer", "minimum": 0 } }, "required": [ "code", "name", "monthly_price", "prorated_charge", "prorated_multiplier", "discount_percent" ] } }, "required": [ "action_path", "requires_tfa", "financials", "effects", "service" ], "additionalProperties": {} } }, "required": [ "preview" ] }, "ServerServiceCancelResponse": { "type": "object", "properties": { "action": { "type": "object", "properties": { "id": { "type": "string" }, "command": { "type": "string" }, "status": { "type": "string", "enum": [ "running", "success", "error" ] }, "progress": { "type": "integer", "minimum": 0, "maximum": 100 }, "resources": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string" } }, "required": [ "id", "type" ] } }, "error": { "type": [ "object", "null" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] }, "started_at": { "type": "string" }, "finished_at": { "type": [ "string", "null" ] } }, "required": [ "id", "command", "status", "progress", "resources", "error", "started_at", "finished_at" ] }, "server": { "type": "object", "properties": { "name": { "type": "string" }, "type": { "type": "string", "enum": [ "virtual", "physical" ] }, "hostname": { "type": [ "string", "null" ] }, "status": { "type": "string", "enum": [ "new", "installing", "inventory", "active" ] }, "power_state": { "type": "string", "enum": [ "running", "stopped", "unknown" ] }, "location": { "type": "string" }, "os": { "type": "object", "properties": { "code": { "type": [ "string", "null" ] }, "name": { "type": [ "string", "null" ] }, "version": { "type": [ "string", "null" ] }, "family": { "type": [ "string", "null" ] } }, "required": [ "code", "name", "version", "family" ] }, "primary_ip": { "type": [ "string", "null" ] }, "ips": { "type": "array", "items": { "type": "string" } }, "ipv6": { "type": "array", "items": { "type": "string" } }, "config": { "type": "object", "properties": { "cpu": { "type": "integer", "minimum": 0 }, "ram": { "type": "integer", "minimum": 0 }, "ssd": { "type": "integer", "minimum": 0 }, "hdd": { "type": [ "integer", "null" ], "minimum": 0 }, "cpu_frequency": { "type": "number", "minimum": 0 }, "tier": { "type": "string", "enum": [ "standard", "high-perf" ] } }, "required": [ "cpu", "ram", "ssd", "hdd", "cpu_frequency", "tier" ] }, "expires_at": { "type": [ "string", "null" ] }, "autorenew": { "type": "boolean" }, "created_at": { "type": "string" } }, "required": [ "name", "type", "hostname", "status", "power_state", "location", "os", "primary_ip", "ips", "ipv6", "config", "expires_at", "autorenew", "created_at" ] } }, "required": [ "action", "server" ] }, "ServerServiceResponse": { "type": "object", "properties": { "action": { "type": "object", "properties": { "id": { "type": "string" }, "command": { "type": "string" }, "status": { "type": "string", "enum": [ "running", "success", "error" ] }, "progress": { "type": "integer", "minimum": 0, "maximum": 100 }, "resources": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string" } }, "required": [ "id", "type" ] } }, "error": { "type": [ "object", "null" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] }, "started_at": { "type": "string" }, "finished_at": { "type": [ "string", "null" ] } }, "required": [ "id", "command", "status", "progress", "resources", "error", "started_at", "finished_at" ] }, "server": { "type": "object", "properties": { "name": { "type": "string" }, "type": { "type": "string", "enum": [ "virtual", "physical" ] }, "hostname": { "type": [ "string", "null" ] }, "status": { "type": "string", "enum": [ "new", "installing", "inventory", "active" ] }, "power_state": { "type": "string", "enum": [ "running", "stopped", "unknown" ] }, "location": { "type": "string" }, "os": { "type": "object", "properties": { "code": { "type": [ "string", "null" ] }, "name": { "type": [ "string", "null" ] }, "version": { "type": [ "string", "null" ] }, "family": { "type": [ "string", "null" ] } }, "required": [ "code", "name", "version", "family" ] }, "primary_ip": { "type": [ "string", "null" ] }, "ips": { "type": "array", "items": { "type": "string" } }, "ipv6": { "type": "array", "items": { "type": "string" } }, "config": { "type": "object", "properties": { "cpu": { "type": "integer", "minimum": 0 }, "ram": { "type": "integer", "minimum": 0 }, "ssd": { "type": "integer", "minimum": 0 }, "hdd": { "type": [ "integer", "null" ], "minimum": 0 }, "cpu_frequency": { "type": "number", "minimum": 0 }, "tier": { "type": "string", "enum": [ "standard", "high-perf" ] } }, "required": [ "cpu", "ram", "ssd", "hdd", "cpu_frequency", "tier" ] }, "expires_at": { "type": [ "string", "null" ] }, "autorenew": { "type": "boolean" }, "created_at": { "type": "string" } }, "required": [ "name", "type", "hostname", "status", "power_state", "location", "os", "primary_ip", "ips", "ipv6", "config", "expires_at", "autorenew", "created_at" ] }, "server_service": { "type": "object", "properties": { "id": { "type": "string" }, "code": { "type": "string" }, "name": { "type": "string" }, "status": { "type": "string", "enum": [ "active", "pending", "cancelled", "expired" ] }, "ordered_at": { "type": "string" }, "expires_at": { "type": [ "string", "null" ] }, "price": { "type": [ "number", "null" ] } }, "required": [ "id", "code", "name", "status", "ordered_at", "expires_at", "price" ] } }, "required": [ "action", "server", "server_service" ] }, "ServerService": { "type": "object", "properties": { "id": { "type": "string" }, "code": { "type": "string" }, "name": { "type": "string" }, "status": { "type": "string", "enum": [ "active", "pending", "cancelled", "expired" ] }, "ordered_at": { "type": "string" }, "expires_at": { "type": [ "string", "null" ] }, "price": { "type": [ "number", "null" ] } }, "required": [ "id", "code", "name", "status", "ordered_at", "expires_at", "price" ] }, "ServiceListResponse": { "type": "object", "properties": { "services": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string" }, "name": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "price": { "type": [ "number", "null" ] }, "currency": { "type": "string" }, "billing_period": { "type": "string", "enum": [ "monthly", "annual", "one_time" ] }, "category": { "type": [ "string", "null" ] }, "max_per_server": { "type": [ "integer", "null" ] } }, "required": [ "code", "name", "description", "price", "currency", "billing_period", "category", "max_per_server" ] } } }, "required": [ "services" ] }, "Service": { "type": "object", "properties": { "code": { "type": "string" }, "name": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "price": { "type": [ "number", "null" ] }, "currency": { "type": "string" }, "billing_period": { "type": "string", "enum": [ "monthly", "annual", "one_time" ] }, "category": { "type": [ "string", "null" ] }, "max_per_server": { "type": [ "integer", "null" ] } }, "required": [ "code", "name", "description", "price", "currency", "billing_period", "category", "max_per_server" ] }, "CreateSnapshotInput": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 80 }, "description": { "type": "string", "maxLength": 500 }, "with_memory": { "type": "boolean" }, "quiesce": { "type": "boolean" }, "tfa_code": { "type": "string" } }, "required": [ "name" ] }, "DeleteSnapshotQuery": { "type": "object", "properties": { "remove_children": { "type": "string", "enum": [ "true", "false" ] } } }, "RevertSnapshotInput": { "type": "object", "properties": { "tfa_code": { "type": "string" } } }, "SnapshotActionResponse": { "type": "object", "properties": { "action": { "type": "object", "properties": { "id": { "type": "string" }, "command": { "type": "string" }, "status": { "type": "string", "enum": [ "running", "success", "error" ] }, "progress": { "type": "integer", "minimum": 0, "maximum": 100 }, "resources": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string" } }, "required": [ "id", "type" ] } }, "error": { "type": [ "object", "null" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] }, "started_at": { "type": "string" }, "finished_at": { "type": [ "string", "null" ] } }, "required": [ "id", "command", "status", "progress", "resources", "error", "started_at", "finished_at" ] }, "server": { "type": "object", "properties": { "name": { "type": "string" }, "type": { "type": "string", "enum": [ "virtual", "physical" ] }, "hostname": { "type": [ "string", "null" ] }, "status": { "type": "string", "enum": [ "new", "installing", "inventory", "active" ] }, "power_state": { "type": "string", "enum": [ "running", "stopped", "unknown" ] }, "location": { "type": "string" }, "os": { "type": "object", "properties": { "code": { "type": [ "string", "null" ] }, "name": { "type": [ "string", "null" ] }, "version": { "type": [ "string", "null" ] }, "family": { "type": [ "string", "null" ] } }, "required": [ "code", "name", "version", "family" ] }, "primary_ip": { "type": [ "string", "null" ] }, "ips": { "type": "array", "items": { "type": "string" } }, "ipv6": { "type": "array", "items": { "type": "string" } }, "config": { "type": "object", "properties": { "cpu": { "type": "integer", "minimum": 0 }, "ram": { "type": "integer", "minimum": 0 }, "ssd": { "type": "integer", "minimum": 0 }, "hdd": { "type": [ "integer", "null" ], "minimum": 0 }, "cpu_frequency": { "type": "number", "minimum": 0 }, "tier": { "type": "string", "enum": [ "standard", "high-perf" ] } }, "required": [ "cpu", "ram", "ssd", "hdd", "cpu_frequency", "tier" ] }, "expires_at": { "type": [ "string", "null" ] }, "autorenew": { "type": "boolean" }, "created_at": { "type": "string" } }, "required": [ "name", "type", "hostname", "status", "power_state", "location", "os", "primary_ip", "ips", "ipv6", "config", "expires_at", "autorenew", "created_at" ] }, "snapshot": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "server_name": { "type": "string" }, "created_at": { "type": "string" }, "size_bytes": { "type": [ "integer", "null" ] }, "parent_id": { "type": [ "string", "null" ] }, "state": { "type": "string", "enum": [ "created", "current", "old" ] }, "quiesced": { "type": "boolean" }, "with_memory": { "type": "boolean" } }, "required": [ "id", "name", "description", "server_name", "created_at", "size_bytes", "parent_id", "state", "quiesced", "with_memory" ] } }, "required": [ "action", "server" ] }, "SnapshotListResponse": { "type": "object", "properties": { "snapshots": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "server_name": { "type": "string" }, "created_at": { "type": "string" }, "size_bytes": { "type": [ "integer", "null" ] }, "parent_id": { "type": [ "string", "null" ] }, "state": { "type": "string", "enum": [ "created", "current", "old" ] }, "quiesced": { "type": "boolean" }, "with_memory": { "type": "boolean" } }, "required": [ "id", "name", "description", "server_name", "created_at", "size_bytes", "parent_id", "state", "quiesced", "with_memory" ] } }, "meta": { "type": "object", "properties": { "pagination": { "type": "object", "properties": { "page": { "type": "integer", "minimum": 0 }, "per_page": { "type": "integer", "exclusiveMinimum": 0 }, "previous_page": { "type": [ "integer", "null" ], "exclusiveMinimum": 0 }, "next_page": { "type": [ "integer", "null" ], "exclusiveMinimum": 0 }, "last_page": { "type": "integer", "exclusiveMinimum": 0 }, "total_entries": { "type": "integer", "minimum": 0 } }, "required": [ "page", "per_page", "previous_page", "next_page", "last_page", "total_entries" ] } }, "required": [ "pagination" ] } }, "required": [ "snapshots", "meta" ] }, "SnapshotResponse": { "type": "object", "properties": { "snapshot": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "server_name": { "type": "string" }, "created_at": { "type": "string" }, "size_bytes": { "type": [ "integer", "null" ] }, "parent_id": { "type": [ "string", "null" ] }, "state": { "type": "string", "enum": [ "created", "current", "old" ] }, "quiesced": { "type": "boolean" }, "with_memory": { "type": "boolean" } }, "required": [ "id", "name", "description", "server_name", "created_at", "size_bytes", "parent_id", "state", "quiesced", "with_memory" ] } }, "required": [ "snapshot" ] }, "Snapshot": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "server_name": { "type": "string" }, "created_at": { "type": "string" }, "size_bytes": { "type": [ "integer", "null" ] }, "parent_id": { "type": [ "string", "null" ] }, "state": { "type": "string", "enum": [ "created", "current", "old" ] }, "quiesced": { "type": "boolean" }, "with_memory": { "type": "boolean" } }, "required": [ "id", "name", "description", "server_name", "created_at", "size_bytes", "parent_id", "state", "quiesced", "with_memory" ] }, "SnapshotState": { "type": "string", "enum": [ "created", "current", "old" ] }, "CreateSshKeyInput": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 64 }, "public_key": { "type": "string", "minLength": 1, "maxLength": 8192 }, "comment": { "type": "string", "maxLength": 255 } }, "required": [ "name", "public_key" ] }, "SshKeyListResponse": { "type": "object", "properties": { "ssh_keys": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "public_key": { "type": "string" }, "fingerprint": { "type": "string" }, "key_type": { "type": "string", "enum": [ "rsa", "ed25519", "ecdsa", "dsa", "unknown" ] }, "bits": { "type": [ "integer", "null" ] }, "comment": { "type": [ "string", "null" ] }, "created_at": { "type": "string" } }, "required": [ "id", "name", "public_key", "fingerprint", "key_type", "bits", "comment", "created_at" ] } } }, "required": [ "ssh_keys" ] }, "SshKeyResponse": { "type": "object", "properties": { "ssh_key": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "public_key": { "type": "string" }, "fingerprint": { "type": "string" }, "key_type": { "type": "string", "enum": [ "rsa", "ed25519", "ecdsa", "dsa", "unknown" ] }, "bits": { "type": [ "integer", "null" ] }, "comment": { "type": [ "string", "null" ] }, "created_at": { "type": "string" } }, "required": [ "id", "name", "public_key", "fingerprint", "key_type", "bits", "comment", "created_at" ] } }, "required": [ "ssh_key" ] }, "SshKey": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "public_key": { "type": "string" }, "fingerprint": { "type": "string" }, "key_type": { "type": "string", "enum": [ "rsa", "ed25519", "ecdsa", "dsa", "unknown" ] }, "bits": { "type": [ "integer", "null" ] }, "comment": { "type": [ "string", "null" ] }, "created_at": { "type": "string" } }, "required": [ "id", "name", "public_key", "fingerprint", "key_type", "bits", "comment", "created_at" ] } }, "parameters": {} }, "paths": { "/account": { "get": { "summary": "Get the authenticated account", "description": "Returns the account that the bearer token belongs to.", "tags": [ "Account" ], "security": [ { "bearerAuth": [ "account:read" ] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "account": { "type": "object", "properties": { "id": { "type": "string" }, "email": { "type": "string", "format": "email" }, "first_name": { "type": "string" }, "last_name": { "type": "string" }, "phone": { "type": [ "string", "null" ] }, "country": { "type": [ "string", "null" ] }, "language": { "type": [ "string", "null" ] }, "balance": { "type": [ "number", "null" ] }, "bonus": { "type": [ "number", "null" ] }, "created_at": { "type": "string" }, "middle_name": { "type": "string" }, "organization": { "type": [ "string", "null" ] }, "city": { "type": [ "string", "null" ] }, "address": { "type": [ "string", "null" ] }, "timezone": { "type": "string" }, "email_confirmed": { "type": "boolean" }, "phone_verified": { "type": "boolean" }, "needs_onboarding": { "type": "boolean" }, "name_incomplete": { "type": "boolean" }, "tfa": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "method": { "type": [ "string", "null" ], "enum": [ "email", "sms", "telegram", "authenticator", null ] }, "oauth": { "type": "boolean" } }, "required": [ "enabled", "method", "oauth" ] }, "connected_accounts": { "type": "array", "items": { "type": "string" } }, "team_member": { "type": "boolean" }, "discount": { "type": [ "object", "null" ], "properties": { "factor": { "type": "number" }, "percent": { "type": "number" }, "source": { "type": "string", "enum": [ "user", "volume", "none" ] } }, "required": [ "factor", "percent", "source" ] } }, "required": [ "id", "email", "first_name", "last_name", "phone", "country", "language", "balance", "bonus", "created_at", "middle_name", "organization", "city", "address", "timezone", "email_confirmed", "phone_verified", "needs_onboarding", "name_incomplete", "tfa", "connected_accounts", "team_member", "discount" ] } }, "required": [ "account" ] } } } }, "401": { "description": "unauthorized: Authentication is required to access this resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "insufficient_scope: Your token does not grant the required scope for this action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "not_found: The requested resource was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "rate_limited: Too many requests. Please retry later.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "server_error: An unexpected error occurred. Please try again later.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } } }, "/servers": { "get": { "summary": "List servers", "description": "List all servers owned by the authenticated account.", "tags": [ "Servers" ], "security": [ { "bearerAuth": [ "server:read" ] } ], "parameters": [ { "schema": { "type": "integer", "minimum": 1, "description": "1-based page number. Defaults to 1.", "example": 1 }, "required": false, "description": "1-based page number. Defaults to 1.", "name": "page", "in": "query" }, { "schema": { "type": "integer", "minimum": 1, "maximum": 100, "description": "Page size. Defaults to 25, capped at 100.", "example": 25 }, "required": false, "description": "Page size. Defaults to 25, capped at 100.", "name": "per_page", "in": "query" }, { "schema": { "type": "string", "enum": [ "new", "installing", "inventory", "active" ] }, "required": false, "name": "status", "in": "query" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "servers": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "type": { "type": "string", "enum": [ "virtual", "physical" ] }, "hostname": { "type": [ "string", "null" ] }, "status": { "type": "string", "enum": [ "new", "installing", "inventory", "active" ] }, "power_state": { "type": "string", "enum": [ "running", "stopped", "unknown" ] }, "location": { "type": "string" }, "os": { "type": "object", "properties": { "code": { "type": [ "string", "null" ] }, "name": { "type": [ "string", "null" ] }, "version": { "type": [ "string", "null" ] }, "family": { "type": [ "string", "null" ] } }, "required": [ "code", "name", "version", "family" ] }, "primary_ip": { "type": [ "string", "null" ] }, "ips": { "type": "array", "items": { "type": "string" } }, "ipv6": { "type": "array", "items": { "type": "string" } }, "config": { "type": "object", "properties": { "cpu": { "type": "integer", "minimum": 0 }, "ram": { "type": "integer", "minimum": 0 }, "ssd": { "type": "integer", "minimum": 0 }, "hdd": { "type": [ "integer", "null" ], "minimum": 0 }, "cpu_frequency": { "type": "number", "minimum": 0 }, "tier": { "type": "string", "enum": [ "standard", "high-perf" ] } }, "required": [ "cpu", "ram", "ssd", "hdd", "cpu_frequency", "tier" ] }, "expires_at": { "type": [ "string", "null" ] }, "autorenew": { "type": "boolean" }, "created_at": { "type": "string" } }, "required": [ "name", "type", "hostname", "status", "power_state", "location", "os", "primary_ip", "ips", "ipv6", "config", "expires_at", "autorenew", "created_at" ] } }, "meta": { "type": "object", "properties": { "pagination": { "$ref": "#/components/schemas/PaginationMeta" } }, "required": [ "pagination" ] } }, "required": [ "servers", "meta" ] } } } }, "401": { "description": "unauthorized: Authentication is required to access this resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "insufficient_scope: Your token does not grant the required scope for this action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "not_found: The requested resource was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "422": { "description": "invalid_input: The request contains invalid or missing fields.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "rate_limited: Too many requests. Please retry later.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "server_error: An unexpected error occurred. Please try again later.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } } }, "/servers/{name}": { "get": { "summary": "Get a single server", "tags": [ "Servers" ], "security": [ { "bearerAuth": [ "server:read" ] } ], "parameters": [ { "schema": { "type": "string", "description": "Server identifier, e.g. `XS-1023`.", "example": "XS-1023" }, "required": true, "description": "Server identifier, e.g. `XS-1023`.", "name": "name", "in": "path" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "server": { "type": "object", "properties": { "name": { "type": "string" }, "type": { "type": "string", "enum": [ "virtual", "physical" ] }, "hostname": { "type": [ "string", "null" ] }, "status": { "type": "string", "enum": [ "new", "installing", "inventory", "active" ] }, "power_state": { "type": "string", "enum": [ "running", "stopped", "unknown" ] }, "location": { "type": "string" }, "os": { "type": "object", "properties": { "code": { "type": [ "string", "null" ] }, "name": { "type": [ "string", "null" ] }, "version": { "type": [ "string", "null" ] }, "family": { "type": [ "string", "null" ] } }, "required": [ "code", "name", "version", "family" ] }, "primary_ip": { "type": [ "string", "null" ] }, "ips": { "type": "array", "items": { "type": "string" } }, "ipv6": { "type": "array", "items": { "type": "string" } }, "config": { "type": "object", "properties": { "cpu": { "type": "integer", "minimum": 0 }, "ram": { "type": "integer", "minimum": 0 }, "ssd": { "type": "integer", "minimum": 0 }, "hdd": { "type": [ "integer", "null" ], "minimum": 0 }, "cpu_frequency": { "type": "number", "minimum": 0 }, "tier": { "type": "string", "enum": [ "standard", "high-perf" ] } }, "required": [ "cpu", "ram", "ssd", "hdd", "cpu_frequency", "tier" ] }, "expires_at": { "type": [ "string", "null" ] }, "autorenew": { "type": "boolean" }, "created_at": { "type": "string" }, "note": { "type": [ "string", "null" ] } }, "required": [ "name", "type", "hostname", "status", "power_state", "location", "os", "primary_ip", "ips", "ipv6", "config", "expires_at", "autorenew", "created_at", "note" ] } }, "required": [ "server" ] } } } }, "401": { "description": "unauthorized: Authentication is required to access this resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "insufficient_scope: Your token does not grant the required scope for this action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "not_found: The requested resource was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "rate_limited: Too many requests. Please retry later.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "server_error: An unexpected error occurred. Please try again later.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } }, "patch": { "summary": "Update server settings", "description": "Partial update. Provide at least one of `hostname`, `note`, `autorenew`. Changing `hostname` creates an Action (command `server.rename`) and returns 202; updating only `note` or `autorenew` returns 200.", "tags": [ "Servers" ], "security": [ { "bearerAuth": [ "server:write" ] } ], "parameters": [ { "schema": { "type": "string", "description": "Server identifier, e.g. `XS-1023`.", "example": "XS-1023" }, "required": true, "description": "Server identifier, e.g. `XS-1023`.", "name": "name", "in": "path" }, { "schema": { "type": "string", "minLength": 1, "maxLength": 255, "description": "Client-supplied key (recommended: ULID). Same key + same body returns the cached response; different body returns `idempotency_conflict`. Stored for 24 h.", "example": "01HXYZABCDEFGHJKMNPQRSTVWX" }, "required": true, "description": "Client-supplied key (recommended: ULID). Same key + same body returns the cached response; different body returns `idempotency_conflict`. Stored for 24 h.", "name": "Idempotency-Key", "in": "header" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "hostname": { "type": "string", "minLength": 1, "maxLength": 253, "pattern": "^[a-zA-Z0-9]([a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?(\\.[a-zA-Z0-9]([a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?)*$" }, "note": { "type": "string", "maxLength": 500 }, "autorenew": { "type": "boolean" } } } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "server": { "type": "object", "properties": { "name": { "type": "string" }, "type": { "type": "string", "enum": [ "virtual", "physical" ] }, "hostname": { "type": [ "string", "null" ] }, "status": { "type": "string", "enum": [ "new", "installing", "inventory", "active" ] }, "power_state": { "type": "string", "enum": [ "running", "stopped", "unknown" ] }, "location": { "type": "string" }, "os": { "type": "object", "properties": { "code": { "type": [ "string", "null" ] }, "name": { "type": [ "string", "null" ] }, "version": { "type": [ "string", "null" ] }, "family": { "type": [ "string", "null" ] } }, "required": [ "code", "name", "version", "family" ] }, "primary_ip": { "type": [ "string", "null" ] }, "ips": { "type": "array", "items": { "type": "string" } }, "ipv6": { "type": "array", "items": { "type": "string" } }, "config": { "type": "object", "properties": { "cpu": { "type": "integer", "minimum": 0 }, "ram": { "type": "integer", "minimum": 0 }, "ssd": { "type": "integer", "minimum": 0 }, "hdd": { "type": [ "integer", "null" ], "minimum": 0 }, "cpu_frequency": { "type": "number", "minimum": 0 }, "tier": { "type": "string", "enum": [ "standard", "high-perf" ] } }, "required": [ "cpu", "ram", "ssd", "hdd", "cpu_frequency", "tier" ] }, "expires_at": { "type": [ "string", "null" ] }, "autorenew": { "type": "boolean" }, "created_at": { "type": "string" } }, "required": [ "name", "type", "hostname", "status", "power_state", "location", "os", "primary_ip", "ips", "ipv6", "config", "expires_at", "autorenew", "created_at" ] } }, "required": [ "server" ] } } } }, "401": { "description": "unauthorized: Authentication is required to access this resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "insufficient_scope: Your token does not grant the required scope for this action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "not_found: The requested resource was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "idempotency_conflict: An earlier request with the same Idempotency-Key had a different body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "422": { "description": "invalid_input: The request contains invalid or missing fields.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "rate_limited: Too many requests. Please retry later.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "server_error: An unexpected error occurred. Please try again later.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } }, "delete": { "summary": "Cancel / delete a server", "description": "Cancel the server. `?mode=on_expiry` (default) flags the server so it stops auto-renewing; `?mode=immediate` destroys the server now, issues a prorated refund to balance, and returns 202 with the delete Action. `?mode=immediate` requires TFA when the account has it enabled — supply either the `X-Tfa-Token` header (from `POST /account/tfa/verify`, supports Passkey) or the legacy `X-Tfa-Code` TOTP header. The token header takes precedence when both are present.", "tags": [ "Servers" ], "security": [ { "bearerAuth": [ "server:write" ] } ], "parameters": [ { "schema": { "type": "string", "description": "Server identifier, e.g. `XS-1023`.", "example": "XS-1023" }, "required": true, "description": "Server identifier, e.g. `XS-1023`.", "name": "name", "in": "path" }, { "schema": { "type": "string", "enum": [ "immediate", "on_expiry" ] }, "required": false, "name": "mode", "in": "query" }, { "schema": { "type": "string", "minLength": 1, "maxLength": 255, "description": "Client-supplied key (recommended: ULID). Same key + same body returns the cached response; different body returns `idempotency_conflict`. Stored for 24 h.", "example": "01HXYZABCDEFGHJKMNPQRSTVWX" }, "required": true, "description": "Client-supplied key (recommended: ULID). Same key + same body returns the cached response; different body returns `idempotency_conflict`. Stored for 24 h.", "name": "Idempotency-Key", "in": "header" }, { "schema": { "type": "string", "description": "One-shot proof from `POST /account/tfa/verify` (TOTP or Passkey). Required when the account has TFA enabled, unless `X-Tfa-Code` (or an inline `tfa_code` body field) is sent. Missing or invalid → 401 `tfa_required` / 422 `tfa_invalid`.", "example": "tfa_01HXYZABCDEFGHJKMNPQRSTVWX" }, "required": false, "description": "One-shot proof from `POST /account/tfa/verify` (TOTP or Passkey). Required when the account has TFA enabled, unless `X-Tfa-Code` (or an inline `tfa_code` body field) is sent. Missing or invalid → 401 `tfa_required` / 422 `tfa_invalid`.", "name": "X-Tfa-Token", "in": "header" }, { "schema": { "type": "string", "description": "Inline 6-digit TOTP code (Authenticator accounts only). `X-Tfa-Token` wins when both are present.", "example": "123456" }, "required": false, "description": "Inline 6-digit TOTP code (Authenticator accounts only). `X-Tfa-Token` wins when both are present.", "name": "X-Tfa-Code", "in": "header" } ], "responses": { "202": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "action": { "type": "object", "properties": { "id": { "type": "string" }, "command": { "type": "string" }, "status": { "type": "string", "enum": [ "running", "success", "error" ] }, "progress": { "type": "integer", "minimum": 0, "maximum": 100 }, "resources": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string" } }, "required": [ "id", "type" ] } }, "error": { "type": [ "object", "null" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] }, "started_at": { "type": "string" }, "finished_at": { "type": [ "string", "null" ] } }, "required": [ "id", "command", "status", "progress", "resources", "error", "started_at", "finished_at" ] } }, "required": [ "action" ] } } } }, "401": { "description": "unauthorized: Authentication is required to access this resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "insufficient_scope: Your token does not grant the required scope for this action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "not_found: The requested resource was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "conflict | idempotency_conflict: The request conflicts with the current state of the resource. An earlier request with the same Idempotency-Key had a different body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "422": { "description": "invalid_input: The request contains invalid or missing fields.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "rate_limited: Too many requests. Please retry later.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "server_error: An unexpected error occurred. Please try again later.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "service_unavailable: The service is temporarily unavailable. Please try again later.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } } }, "/actions": { "get": { "summary": "List actions", "description": "List background actions initiated by this account. The response is a flat newest-first feed capped at 100 records — no pagination meta. Narrow the result set with optional query filters: `server` (filter by server name, e.g. `XS-1023` — matches actions whose `resources[]` carries `{ id: , type: \"server\" }`), `status` (`running|success|error`), `command` (any ActionCommand enum value, e.g. `server.reinstall`), and `since` (ISO timestamp — returns only actions with `started_at > since`, suitable for polling).", "tags": [ "Actions" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "required": false, "name": "server", "in": "query" }, { "schema": { "type": "string", "enum": [ "running", "success", "error" ] }, "required": false, "name": "status", "in": "query" }, { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "required": false, "name": "command", "in": "query" }, { "schema": { "type": "string" }, "required": false, "name": "since", "in": "query" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "actions": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "command": { "type": "string" }, "status": { "type": "string", "enum": [ "running", "success", "error" ] }, "progress": { "type": "integer", "minimum": 0, "maximum": 100 }, "resources": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string" } }, "required": [ "id", "type" ] } }, "error": { "type": [ "object", "null" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] }, "started_at": { "type": "string" }, "finished_at": { "type": [ "string", "null" ] } }, "required": [ "id", "command", "status", "progress", "resources", "error", "started_at", "finished_at" ] } } }, "required": [ "actions" ] } } } }, "401": { "description": "unauthorized: Authentication is required to access this resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "insufficient_scope: Your token does not grant the required scope for this action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "not_found: The requested resource was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "422": { "description": "invalid_input: The request contains invalid or missing fields.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "rate_limited: Too many requests. Please retry later.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "server_error: An unexpected error occurred. Please try again later.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } } }, "/actions/{id}": { "get": { "summary": "Get a single action", "tags": [ "Actions" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "description": "Action ObjectId (24 hex chars)." }, "required": true, "description": "Action ObjectId (24 hex chars).", "name": "id", "in": "path" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "action": { "type": "object", "properties": { "id": { "type": "string" }, "command": { "type": "string" }, "status": { "type": "string", "enum": [ "running", "success", "error" ] }, "progress": { "type": "integer", "minimum": 0, "maximum": 100 }, "resources": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string" } }, "required": [ "id", "type" ] } }, "error": { "type": [ "object", "null" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] }, "started_at": { "type": "string" }, "finished_at": { "type": [ "string", "null" ] } }, "required": [ "id", "command", "status", "progress", "resources", "error", "started_at", "finished_at" ] } }, "required": [ "action" ] } } } }, "401": { "description": "unauthorized: Authentication is required to access this resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "insufficient_scope: Your token does not grant the required scope for this action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "not_found: The requested resource was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "rate_limited: Too many requests. Please retry later.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "server_error: An unexpected error occurred. Please try again later.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } } }, "/actions/{id}/events": { "get": { "summary": "Stream action progress (SSE)", "description": "Server-Sent Events stream for a single Action. Content-Type: `text/event-stream`. Replaces polling `GET /v1/actions/{id}` in a tight loop. The server emits an initial `snapshot` event with the current state, then a series of `progress` events while the action runs, and finally exactly one terminal `success` or `error` event before closing the stream. Each frame is a named event whose `data:` line is an `ActionEvent` JSON object. See docs/API_MOBILE.md §5.2 for the full event shape.", "tags": [ "Actions" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "description": "Action ObjectId (24 hex chars)." }, "required": true, "description": "Action ObjectId (24 hex chars).", "name": "id", "in": "path" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "event": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "snapshot", "progress", "success", "error" ] }, "action": { "type": "object", "properties": { "id": { "type": "string" }, "command": { "type": "string" }, "status": { "type": "string", "enum": [ "running", "success", "error" ] }, "progress": { "type": "integer", "minimum": 0, "maximum": 100 }, "resources": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string" } }, "required": [ "id", "type" ] } }, "error": { "type": [ "object", "null" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] }, "started_at": { "type": "string" }, "finished_at": { "type": [ "string", "null" ] } }, "required": [ "id", "command", "status", "progress", "resources", "error", "started_at", "finished_at" ] } }, "required": [ "kind", "action" ] } }, "required": [ "event" ] } } } }, "401": { "description": "unauthorized: Authentication is required to access this resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "insufficient_scope: Your token does not grant the required scope for this action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "not_found: The requested resource was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "rate_limited: Too many requests. Please retry later.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "server_error: An unexpected error occurred. Please try again later.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } } }, "/locations": { "get": { "summary": "List locations", "description": "Public reference data — no authentication required.", "tags": [ "Reference" ], "security": [], "parameters": [ { "schema": { "type": "integer", "minimum": 1, "description": "1-based page number. Defaults to 1.", "example": 1 }, "required": false, "description": "1-based page number. Defaults to 1.", "name": "page", "in": "query" }, { "schema": { "type": "integer", "minimum": 1, "maximum": 100, "description": "Page size. Defaults to 25, capped at 100.", "example": 25 }, "required": false, "description": "Page size. Defaults to 25, capped at 100.", "name": "per_page", "in": "query" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "locations": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string" }, "name": { "type": "string" }, "city": { "type": [ "string", "null" ] }, "country": { "type": [ "string", "null" ] }, "flag": { "type": [ "string", "null" ] }, "offerings": { "type": "object", "properties": { "dedicated": { "type": "boolean" }, "vps": { "type": "boolean" }, "hiperf": { "type": "boolean" } }, "required": [ "dedicated", "vps", "hiperf" ] } }, "required": [ "code", "name", "city", "country", "flag", "offerings" ] } }, "meta": { "type": "object", "properties": { "pagination": { "$ref": "#/components/schemas/PaginationMeta" } }, "required": [ "pagination" ] } }, "required": [ "locations", "meta" ] } } } }, "404": { "description": "not_found: The requested resource was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "rate_limited: Too many requests. Please retry later.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "server_error: An unexpected error occurred. Please try again later.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } } }, "/pricing": { "get": { "summary": "Get the price list", "description": "Public reference data — no authentication required. The configuration steps of every VPS tier (the only values an order or a resize accepts) with the monthly unit prices, the IP prices with the free allocation, the prepayment discount tiers (by full calendar months) and the volume discount tiers (by active servers; the account's own figure is `GET /account` → `discount`). `version` is the ETag: send `If-None-Match` and get 304 while nothing changed. The formulas a client needs to reproduce `POST /orders/preview` and `GET /servers/{name}/renew/preview` to the cent are in docs/API_MOBILE.md §4.5.1; a resize charge depends on the server's paid billing segments and stays a `GET /servers/{name}/resize/preview` call.", "tags": [ "Reference" ], "security": [], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "pricing": { "type": "object", "properties": { "version": { "type": "string" }, "currency": { "type": "string" }, "tiers": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "standard", "hiperf" ] }, "label": { "type": "string" }, "description": { "type": "string" }, "resources": { "type": "object", "properties": { "cpu": { "type": "object", "properties": { "unit": { "type": "string", "enum": [ "cores", "GB" ] }, "unit_price": { "type": "number" }, "values": { "type": "array", "items": { "type": "number" } } }, "required": [ "unit", "unit_price", "values" ] }, "ram": { "type": "object", "properties": { "unit": { "type": "string", "enum": [ "cores", "GB" ] }, "unit_price": { "type": "number" }, "values": { "type": "array", "items": { "type": "number" } } }, "required": [ "unit", "unit_price", "values" ] }, "disk": { "type": "object", "properties": { "unit": { "type": "string", "enum": [ "cores", "GB" ] }, "unit_price": { "type": "number" }, "values": { "type": "array", "items": { "type": "number" } }, "kind": { "type": "string", "enum": [ "ssd", "nvme" ] } }, "required": [ "unit", "unit_price", "values", "kind" ] }, "hdd": { "type": "object", "properties": { "unit": { "type": "string", "enum": [ "cores", "GB" ] }, "unit_price": { "type": "number" }, "values": { "type": "array", "items": { "type": "number" } } }, "required": [ "unit", "unit_price", "values" ] } }, "required": [ "cpu", "ram", "disk", "hdd" ] } }, "required": [ "code", "label", "description", "resources" ] } }, "ip": { "type": "object", "properties": { "v4": { "type": "object", "properties": { "unit_price": { "type": "number" }, "free_per_server": { "type": "integer" } }, "required": [ "unit_price", "free_per_server" ] }, "v6": { "type": "object", "properties": { "unit_price": { "type": "number" }, "free_per_server": { "type": "integer" } }, "required": [ "unit_price", "free_per_server" ] } }, "required": [ "v4", "v6" ] }, "period_discounts": { "type": "array", "items": { "type": "object", "properties": { "min_months": { "type": "integer" }, "percent": { "type": "number" } }, "required": [ "min_months", "percent" ] } }, "volume_discounts": { "type": "array", "items": { "type": "object", "properties": { "min_servers": { "type": "integer" }, "percent": { "type": "number" } }, "required": [ "min_servers", "percent" ] } }, "rules": { "type": "object", "properties": { "rounding": { "type": "string", "enum": [ "half_up_2dp_per_step" ] }, "period": { "type": "string", "enum": [ "calendar_months" ] }, "disk_shrink": { "type": "boolean", "enum": [ false ] }, "cpu_ram_decrease_requires_poweroff": { "type": "boolean", "enum": [ true ] } }, "required": [ "rounding", "period", "disk_shrink", "cpu_ram_decrease_requires_poweroff" ] } }, "required": [ "version", "currency", "tiers", "ip", "period_discounts", "volume_discounts", "rules" ] } }, "required": [ "pricing" ] } } } }, "404": { "description": "not_found: The requested resource was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "rate_limited: Too many requests. Please retry later.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "server_error: An unexpected error occurred. Please try again later.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } } }, "/os-templates": { "get": { "summary": "List OS templates", "description": "Public reference data — no authentication required.", "tags": [ "Reference" ], "security": [], "parameters": [ { "schema": { "type": "integer", "minimum": 1, "description": "1-based page number. Defaults to 1.", "example": 1 }, "required": false, "description": "1-based page number. Defaults to 1.", "name": "page", "in": "query" }, { "schema": { "type": "integer", "minimum": 1, "maximum": 100, "description": "Page size. Defaults to 25, capped at 100.", "example": 25 }, "required": false, "description": "Page size. Defaults to 25, capped at 100.", "name": "per_page", "in": "query" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "os_templates": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string" }, "name": { "type": "string" }, "version": { "type": "string" }, "family": { "type": "string", "enum": [ "linux", "windows" ] }, "architectures": { "type": "array", "items": { "type": "string", "enum": [ "x86_64", "arm64" ] } }, "compatibility": { "type": "array", "items": { "type": "string", "enum": [ "virtual", "physical" ] } }, "logo": { "type": [ "string", "null" ] }, "software": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string" }, "name": { "type": "string" } }, "required": [ "code", "name" ] } } }, "required": [ "code", "name", "version", "family", "architectures", "compatibility", "logo", "software" ] } }, "meta": { "type": "object", "properties": { "pagination": { "$ref": "#/components/schemas/PaginationMeta" } }, "required": [ "pagination" ] } }, "required": [ "os_templates", "meta" ] } } } }, "404": { "description": "not_found: The requested resource was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "422": { "description": "invalid_input: The request contains invalid or missing fields.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "rate_limited: Too many requests. Please retry later.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "server_error: An unexpected error occurred. Please try again later.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } } }, "/ssh-keys": { "get": { "summary": "List SSH keys", "description": "List the authenticated account's SSH public keys as a flat array, sorted by creation time ascending. Not paginated — the per-user hard cap (20) makes page-cursor machinery pure overhead.", "tags": [ "SSH Keys" ], "security": [ { "bearerAuth": [ "ssh_keys:read" ] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "ssh_keys": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "public_key": { "type": "string" }, "fingerprint": { "type": "string" }, "key_type": { "type": "string", "enum": [ "rsa", "ed25519", "ecdsa", "dsa", "unknown" ] }, "bits": { "type": [ "integer", "null" ] }, "comment": { "type": [ "string", "null" ] }, "created_at": { "type": "string" } }, "required": [ "id", "name", "public_key", "fingerprint", "key_type", "bits", "comment", "created_at" ] } } }, "required": [ "ssh_keys" ] } } } }, "401": { "description": "unauthorized: Authentication is required to access this resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "insufficient_scope: Your token does not grant the required scope for this action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "not_found: The requested resource was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "conflict: The request conflicts with the current state of the resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "422": { "description": "invalid_input: The request contains invalid or missing fields.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "rate_limited: Too many requests. Please retry later.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "server_error: An unexpected error occurred. Please try again later.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } }, "post": { "summary": "Add an SSH key", "description": "Upload an OpenSSH public key. The server parses the key, extracts its fingerprint, and rejects duplicates (409 `conflict`). Hard-capped at 20 keys per account — the 21st attempt also returns 409 `conflict`.", "tags": [ "SSH Keys" ], "security": [ { "bearerAuth": [ "ssh_keys:write" ] } ], "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 255, "description": "Client-supplied key (recommended: ULID). Same key + same body returns the cached response; different body returns `idempotency_conflict`. Stored for 24 h.", "example": "01HXYZABCDEFGHJKMNPQRSTVWX" }, "required": true, "description": "Client-supplied key (recommended: ULID). Same key + same body returns the cached response; different body returns `idempotency_conflict`. Stored for 24 h.", "name": "Idempotency-Key", "in": "header" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 64 }, "public_key": { "type": "string", "minLength": 1, "maxLength": 8192 }, "comment": { "type": "string", "maxLength": 255 } }, "required": [ "name", "public_key" ] } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "ssh_key": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "public_key": { "type": "string" }, "fingerprint": { "type": "string" }, "key_type": { "type": "string", "enum": [ "rsa", "ed25519", "ecdsa", "dsa", "unknown" ] }, "bits": { "type": [ "integer", "null" ] }, "comment": { "type": [ "string", "null" ] }, "created_at": { "type": "string" } }, "required": [ "id", "name", "public_key", "fingerprint", "key_type", "bits", "comment", "created_at" ] } }, "required": [ "ssh_key" ] } } } }, "401": { "description": "unauthorized: Authentication is required to access this resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "insufficient_scope: Your token does not grant the required scope for this action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "not_found: The requested resource was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "idempotency_conflict: An earlier request with the same Idempotency-Key had a different body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "422": { "description": "invalid_input: The request contains invalid or missing fields.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "rate_limited: Too many requests. Please retry later.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "server_error: An unexpected error occurred. Please try again later.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } } }, "/ssh-keys/{id}": { "delete": { "summary": "Delete an SSH key", "description": "Remove an SSH key by id.", "tags": [ "SSH Keys" ], "security": [ { "bearerAuth": [ "ssh_keys:write" ] } ], "parameters": [ { "schema": { "type": "string", "description": "SSH key ObjectId." }, "required": true, "description": "SSH key ObjectId.", "name": "id", "in": "path" }, { "schema": { "type": "string", "minLength": 1, "maxLength": 255, "description": "Client-supplied key (recommended: ULID). Same key + same body returns the cached response; different body returns `idempotency_conflict`. Stored for 24 h.", "example": "01HXYZABCDEFGHJKMNPQRSTVWX" }, "required": true, "description": "Client-supplied key (recommended: ULID). Same key + same body returns the cached response; different body returns `idempotency_conflict`. Stored for 24 h.", "name": "Idempotency-Key", "in": "header" } ], "responses": { "204": { "description": "Success — no content" }, "401": { "description": "unauthorized: Authentication is required to access this resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "insufficient_scope: Your token does not grant the required scope for this action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "not_found: The requested resource was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "idempotency_conflict: An earlier request with the same Idempotency-Key had a different body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "rate_limited: Too many requests. Please retry later.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "server_error: An unexpected error occurred. Please try again later.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } } }, "/servers/{name}/power": { "post": { "summary": "Power action", "description": "Execute a power operation: `on`, `off`, `restart`, `graceful_shutdown`, or `reset`. Returns `{ action, server }` with status 202 once the job is accepted.", "tags": [ "Servers" ], "security": [ { "bearerAuth": [ "server:power" ] } ], "parameters": [ { "schema": { "type": "string", "description": "Server identifier, e.g. `XS-1023`.", "example": "XS-1023" }, "required": true, "description": "Server identifier, e.g. `XS-1023`.", "name": "name", "in": "path" }, { "schema": { "type": "string", "minLength": 1, "maxLength": 255, "description": "Client-supplied key (recommended: ULID). Same key + same body returns the cached response; different body returns `idempotency_conflict`. Stored for 24 h.", "example": "01HXYZABCDEFGHJKMNPQRSTVWX" }, "required": true, "description": "Client-supplied key (recommended: ULID). Same key + same body returns the cached response; different body returns `idempotency_conflict`. Stored for 24 h.", "name": "Idempotency-Key", "in": "header" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "action": { "type": "string", "enum": [ "on", "off", "restart", "graceful_shutdown", "reset" ] } }, "required": [ "action" ] } } } }, "responses": { "202": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "action": { "type": "object", "properties": { "id": { "type": "string" }, "command": { "type": "string" }, "status": { "type": "string", "enum": [ "running", "success", "error" ] }, "progress": { "type": "integer", "minimum": 0, "maximum": 100 }, "resources": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string" } }, "required": [ "id", "type" ] } }, "error": { "type": [ "object", "null" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] }, "started_at": { "type": "string" }, "finished_at": { "type": [ "string", "null" ] } }, "required": [ "id", "command", "status", "progress", "resources", "error", "started_at", "finished_at" ] }, "server": { "type": "object", "properties": { "name": { "type": "string" }, "type": { "type": "string", "enum": [ "virtual", "physical" ] }, "hostname": { "type": [ "string", "null" ] }, "status": { "type": "string", "enum": [ "new", "installing", "inventory", "active" ] }, "power_state": { "type": "string", "enum": [ "running", "stopped", "unknown" ] }, "location": { "type": "string" }, "os": { "type": "object", "properties": { "code": { "type": [ "string", "null" ] }, "name": { "type": [ "string", "null" ] }, "version": { "type": [ "string", "null" ] }, "family": { "type": [ "string", "null" ] } }, "required": [ "code", "name", "version", "family" ] }, "primary_ip": { "type": [ "string", "null" ] }, "ips": { "type": "array", "items": { "type": "string" } }, "ipv6": { "type": "array", "items": { "type": "string" } }, "config": { "type": "object", "properties": { "cpu": { "type": "integer", "minimum": 0 }, "ram": { "type": "integer", "minimum": 0 }, "ssd": { "type": "integer", "minimum": 0 }, "hdd": { "type": [ "integer", "null" ], "minimum": 0 }, "cpu_frequency": { "type": "number", "minimum": 0 }, "tier": { "type": "string", "enum": [ "standard", "high-perf" ] } }, "required": [ "cpu", "ram", "ssd", "hdd", "cpu_frequency", "tier" ] }, "expires_at": { "type": [ "string", "null" ] }, "autorenew": { "type": "boolean" }, "created_at": { "type": "string" } }, "required": [ "name", "type", "hostname", "status", "power_state", "location", "os", "primary_ip", "ips", "ipv6", "config", "expires_at", "autorenew", "created_at" ] } }, "required": [ "action", "server" ] } } } }, "401": { "description": "unauthorized: Authentication is required to access this resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "insufficient_scope | forbidden: Your token does not grant the required scope for this action. You do not have permission to access this resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "not_found: The requested resource was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "conflict | idempotency_conflict: The request conflicts with the current state of the resource. An earlier request with the same Idempotency-Key had a different body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "422": { "description": "invalid_input: The request contains invalid or missing fields.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "rate_limited: Too many requests. Please retry later.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "server_error: An unexpected error occurred. Please try again later.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } } }, "/servers/{name}/console": { "post": { "summary": "Mint a console URL", "description": "Issue a short-lived signed URL for the server console. Type auto-detected from server kind (virtual→WMKS, physical→IPMI). Rate-limited to 10 per minute. 409 `conflict` while a backup restore runs, while the server is blocked and, for a virtual server, while it is powered off — start it first. 500 `server_error` only when the hypervisor refused the ticket: retry once after a moment.", "tags": [ "Consoles" ], "security": [ { "bearerAuth": [ "server:console" ] } ], "parameters": [ { "schema": { "type": "string", "description": "Server identifier, e.g. `XS-1023`.", "example": "XS-1023" }, "required": true, "description": "Server identifier, e.g. `XS-1023`.", "name": "name", "in": "path" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "wmks", "ipmi", "vnc" ] } } } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "console": { "type": "object", "properties": { "url": { "type": "string" }, "type": { "type": "string", "enum": [ "wmks", "ipmi", "vnc" ] }, "expires_at": { "type": "string" }, "password": { "type": "string" } }, "required": [ "url", "type", "expires_at" ] } }, "required": [ "console" ] } } } }, "401": { "description": "unauthorized: Authentication is required to access this resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "insufficient_scope: Your token does not grant the required scope for this action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "not_found: The requested resource was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "conflict: The request conflicts with the current state of the resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "422": { "description": "invalid_input: The request contains invalid or missing fields.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "rate_limited: Too many requests. Please retry later.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "server_error: An unexpected error occurred. Please try again later.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } } }, "/servers/{name}/reinstall": { "post": { "summary": "Reinstall OS", "description": "Wipe the server and reinstall the requested OS template. `ssh_key_ids` and `password` are both optional: without a password the platform generates one and sends it in the install-complete email; with keys only, SSH password login is disabled and the password serves the console. If the account has TFA enabled, the caller MUST supply a proof — either the `X-Tfa-Token` header (obtained from `POST /account/tfa/verify`, supports TOTP and Passkey) or an inline `tfa_code` body field (TOTP only). The header takes precedence when both are present. Idempotency-Key required.", "tags": [ "Servers" ], "security": [ { "bearerAuth": [ "server:reinstall" ] } ], "parameters": [ { "schema": { "type": "string", "description": "Server identifier, e.g. `XS-1023`.", "example": "XS-1023" }, "required": true, "description": "Server identifier, e.g. `XS-1023`.", "name": "name", "in": "path" }, { "schema": { "type": "string", "minLength": 1, "maxLength": 255, "description": "Client-supplied key (recommended: ULID). Same key + same body returns the cached response; different body returns `idempotency_conflict`. Stored for 24 h.", "example": "01HXYZABCDEFGHJKMNPQRSTVWX" }, "required": true, "description": "Client-supplied key (recommended: ULID). Same key + same body returns the cached response; different body returns `idempotency_conflict`. Stored for 24 h.", "name": "Idempotency-Key", "in": "header" }, { "schema": { "type": "string", "description": "One-shot proof from `POST /account/tfa/verify` (TOTP or Passkey). Required when the account has TFA enabled, unless `X-Tfa-Code` (or an inline `tfa_code` body field) is sent. Missing or invalid → 401 `tfa_required` / 422 `tfa_invalid`.", "example": "tfa_01HXYZABCDEFGHJKMNPQRSTVWX" }, "required": false, "description": "One-shot proof from `POST /account/tfa/verify` (TOTP or Passkey). Required when the account has TFA enabled, unless `X-Tfa-Code` (or an inline `tfa_code` body field) is sent. Missing or invalid → 401 `tfa_required` / 422 `tfa_invalid`.", "name": "X-Tfa-Token", "in": "header" }, { "schema": { "type": "string", "description": "Inline 6-digit TOTP code (Authenticator accounts only). `X-Tfa-Token` wins when both are present.", "example": "123456" }, "required": false, "description": "Inline 6-digit TOTP code (Authenticator accounts only). `X-Tfa-Token` wins when both are present.", "name": "X-Tfa-Code", "in": "header" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "os_template": { "type": "string", "minLength": 1, "maxLength": 100 }, "ssh_key_ids": { "type": "array", "items": { "type": "string", "minLength": 1 }, "maxItems": 10 }, "password": { "type": "string", "minLength": 8, "maxLength": 128 }, "tfa_code": { "type": "string", "minLength": 1, "maxLength": 32 }, "hostname": { "type": "string", "minLength": 1, "maxLength": 253, "pattern": "^[a-zA-Z0-9]([a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?(\\.[a-zA-Z0-9]([a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?)*$" } }, "required": [ "os_template" ] } } } }, "responses": { "202": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "action": { "type": "object", "properties": { "id": { "type": "string" }, "command": { "type": "string" }, "status": { "type": "string", "enum": [ "running", "success", "error" ] }, "progress": { "type": "integer", "minimum": 0, "maximum": 100 }, "resources": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string" } }, "required": [ "id", "type" ] } }, "error": { "type": [ "object", "null" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] }, "started_at": { "type": "string" }, "finished_at": { "type": [ "string", "null" ] } }, "required": [ "id", "command", "status", "progress", "resources", "error", "started_at", "finished_at" ] }, "server": { "type": "object", "properties": { "name": { "type": "string" }, "type": { "type": "string", "enum": [ "virtual", "physical" ] }, "hostname": { "type": [ "string", "null" ] }, "status": { "type": "string", "enum": [ "new", "installing", "inventory", "active" ] }, "power_state": { "type": "string", "enum": [ "running", "stopped", "unknown" ] }, "location": { "type": "string" }, "os": { "type": "object", "properties": { "code": { "type": [ "string", "null" ] }, "name": { "type": [ "string", "null" ] }, "version": { "type": [ "string", "null" ] }, "family": { "type": [ "string", "null" ] } }, "required": [ "code", "name", "version", "family" ] }, "primary_ip": { "type": [ "string", "null" ] }, "ips": { "type": "array", "items": { "type": "string" } }, "ipv6": { "type": "array", "items": { "type": "string" } }, "config": { "type": "object", "properties": { "cpu": { "type": "integer", "minimum": 0 }, "ram": { "type": "integer", "minimum": 0 }, "ssd": { "type": "integer", "minimum": 0 }, "hdd": { "type": [ "integer", "null" ], "minimum": 0 }, "cpu_frequency": { "type": "number", "minimum": 0 }, "tier": { "type": "string", "enum": [ "standard", "high-perf" ] } }, "required": [ "cpu", "ram", "ssd", "hdd", "cpu_frequency", "tier" ] }, "expires_at": { "type": [ "string", "null" ] }, "autorenew": { "type": "boolean" }, "created_at": { "type": "string" } }, "required": [ "name", "type", "hostname", "status", "power_state", "location", "os", "primary_ip", "ips", "ipv6", "config", "expires_at", "autorenew", "created_at" ] } }, "required": [ "action", "server" ] } } } }, "401": { "description": "unauthorized: Authentication is required to access this resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "402": { "description": "insufficient_funds: Your account balance is insufficient for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "insufficient_scope | forbidden: Your token does not grant the required scope for this action. You do not have permission to access this resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "not_found: The requested resource was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "conflict | idempotency_conflict: The request conflicts with the current state of the resource. An earlier request with the same Idempotency-Key had a different body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "422": { "description": "invalid_input: The request contains invalid or missing fields.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "rate_limited: Too many requests. Please retry later.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "server_error: An unexpected error occurred. Please try again later.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "service_unavailable: The service is temporarily unavailable. Please try again later.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } } }, "/servers/{name}/ips": { "get": { "summary": "List the IP addresses of a server", "description": "Every address the server holds with its PTR (rDNS): the IPv4 rows first (`is_primary` marks the main address), then the IPv6 /64 ranges in CIDR form with the PTR records set inside them (`ptr_records`). Set a PTR with `PATCH /ip-addresses/{ip}`.", "tags": [ "IP Addresses" ], "security": [ { "bearerAuth": [ "server:read" ] } ], "parameters": [ { "schema": { "type": "string", "description": "Server identifier, e.g. `XS-1023`.", "example": "XS-1023" }, "required": true, "description": "Server identifier, e.g. `XS-1023`.", "name": "name", "in": "path" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "ip_addresses": { "type": "array", "items": { "type": "object", "properties": { "ip": { "type": "string" }, "kind": { "type": "string", "enum": [ "v4", "v6" ] }, "is_primary": { "type": "boolean" }, "ptr": { "type": [ "string", "null" ] }, "server_name": { "type": [ "string", "null" ] }, "network_id": { "type": [ "string", "null" ] }, "location": { "type": [ "string", "null" ] }, "assigned_at": { "type": [ "string", "null" ] }, "ptr_records": { "type": [ "array", "null" ], "items": { "type": "object", "properties": { "address": { "type": "string" }, "ptr": { "type": "string" } }, "required": [ "address", "ptr" ] } } }, "required": [ "ip", "kind", "is_primary", "ptr", "server_name", "network_id", "location", "assigned_at", "ptr_records" ] } } }, "required": [ "ip_addresses" ] } } } }, "401": { "description": "unauthorized: Authentication is required to access this resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "insufficient_scope: Your token does not grant the required scope for this action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "not_found: The requested resource was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "rate_limited: Too many requests. Please retry later.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "server_error: An unexpected error occurred. Please try again later.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } }, "post": { "summary": "Add IP addresses to a server", "description": "Allocate additional IPv4 addresses and/or an IPv6 block to a server. Prorated cost is debited from the account balance; insufficient balance returns `insufficient_funds`. Idempotency-Key required.", "tags": [ "IP Addresses" ], "security": [ { "bearerAuth": [ "server:network" ] } ], "parameters": [ { "schema": { "type": "string", "description": "Server identifier, e.g. `XS-1023`.", "example": "XS-1023" }, "required": true, "description": "Server identifier, e.g. `XS-1023`.", "name": "name", "in": "path" }, { "schema": { "type": "string", "minLength": 1, "maxLength": 255, "description": "Client-supplied key (recommended: ULID). Same key + same body returns the cached response; different body returns `idempotency_conflict`. Stored for 24 h.", "example": "01HXYZABCDEFGHJKMNPQRSTVWX" }, "required": true, "description": "Client-supplied key (recommended: ULID). Same key + same body returns the cached response; different body returns `idempotency_conflict`. Stored for 24 h.", "name": "Idempotency-Key", "in": "header" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "ipv4": { "type": "integer", "minimum": 0, "maximum": 8 }, "ipv6": { "type": "boolean" }, "use_bonus": { "type": "boolean" } } } } } }, "responses": { "202": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "action": { "type": "object", "properties": { "id": { "type": "string" }, "command": { "type": "string" }, "status": { "type": "string", "enum": [ "running", "success", "error" ] }, "progress": { "type": "integer", "minimum": 0, "maximum": 100 }, "resources": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string" } }, "required": [ "id", "type" ] } }, "error": { "type": [ "object", "null" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] }, "started_at": { "type": "string" }, "finished_at": { "type": [ "string", "null" ] } }, "required": [ "id", "command", "status", "progress", "resources", "error", "started_at", "finished_at" ] }, "server": { "type": "object", "properties": { "name": { "type": "string" }, "type": { "type": "string", "enum": [ "virtual", "physical" ] }, "hostname": { "type": [ "string", "null" ] }, "status": { "type": "string", "enum": [ "new", "installing", "inventory", "active" ] }, "power_state": { "type": "string", "enum": [ "running", "stopped", "unknown" ] }, "location": { "type": "string" }, "os": { "type": "object", "properties": { "code": { "type": [ "string", "null" ] }, "name": { "type": [ "string", "null" ] }, "version": { "type": [ "string", "null" ] }, "family": { "type": [ "string", "null" ] } }, "required": [ "code", "name", "version", "family" ] }, "primary_ip": { "type": [ "string", "null" ] }, "ips": { "type": "array", "items": { "type": "string" } }, "ipv6": { "type": "array", "items": { "type": "string" } }, "config": { "type": "object", "properties": { "cpu": { "type": "integer", "minimum": 0 }, "ram": { "type": "integer", "minimum": 0 }, "ssd": { "type": "integer", "minimum": 0 }, "hdd": { "type": [ "integer", "null" ], "minimum": 0 }, "cpu_frequency": { "type": "number", "minimum": 0 }, "tier": { "type": "string", "enum": [ "standard", "high-perf" ] } }, "required": [ "cpu", "ram", "ssd", "hdd", "cpu_frequency", "tier" ] }, "expires_at": { "type": [ "string", "null" ] }, "autorenew": { "type": "boolean" }, "created_at": { "type": "string" } }, "required": [ "name", "type", "hostname", "status", "power_state", "location", "os", "primary_ip", "ips", "ipv6", "config", "expires_at", "autorenew", "created_at" ] } }, "required": [ "action", "server" ] } } } }, "401": { "description": "unauthorized: Authentication is required to access this resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "402": { "description": "insufficient_funds: Your account balance is insufficient for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "insufficient_scope | forbidden: Your token does not grant the required scope for this action. You do not have permission to access this resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "not_found: The requested resource was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "conflict | idempotency_conflict: The request conflicts with the current state of the resource. An earlier request with the same Idempotency-Key had a different body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "422": { "description": "invalid_input: The request contains invalid or missing fields.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "rate_limited: Too many requests. Please retry later.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "server_error: An unexpected error occurred. Please try again later.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } } }, "/servers/{name}/ips/{ip}": { "delete": { "summary": "Release an IP from a server", "description": "Release an additional IP. The primary IP cannot be removed this way (demote it first). Releases are not refunded — they free the slot for the next cycle.", "tags": [ "IP Addresses" ], "security": [ { "bearerAuth": [ "server:network" ] } ], "parameters": [ { "schema": { "type": "string", "description": "Server identifier, e.g. `XS-1023`.", "example": "XS-1023" }, "required": true, "description": "Server identifier, e.g. `XS-1023`.", "name": "name", "in": "path" }, { "schema": { "type": "string", "description": "IPv4 or IPv6 address to release." }, "required": true, "description": "IPv4 or IPv6 address to release.", "name": "ip", "in": "path" }, { "schema": { "type": "string", "minLength": 1, "maxLength": 255, "description": "Client-supplied key (recommended: ULID). Same key + same body returns the cached response; different body returns `idempotency_conflict`. Stored for 24 h.", "example": "01HXYZABCDEFGHJKMNPQRSTVWX" }, "required": true, "description": "Client-supplied key (recommended: ULID). Same key + same body returns the cached response; different body returns `idempotency_conflict`. Stored for 24 h.", "name": "Idempotency-Key", "in": "header" } ], "responses": { "202": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "action": { "type": "object", "properties": { "id": { "type": "string" }, "command": { "type": "string" }, "status": { "type": "string", "enum": [ "running", "success", "error" ] }, "progress": { "type": "integer", "minimum": 0, "maximum": 100 }, "resources": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string" } }, "required": [ "id", "type" ] } }, "error": { "type": [ "object", "null" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] }, "started_at": { "type": "string" }, "finished_at": { "type": [ "string", "null" ] } }, "required": [ "id", "command", "status", "progress", "resources", "error", "started_at", "finished_at" ] }, "server": { "type": "object", "properties": { "name": { "type": "string" }, "type": { "type": "string", "enum": [ "virtual", "physical" ] }, "hostname": { "type": [ "string", "null" ] }, "status": { "type": "string", "enum": [ "new", "installing", "inventory", "active" ] }, "power_state": { "type": "string", "enum": [ "running", "stopped", "unknown" ] }, "location": { "type": "string" }, "os": { "type": "object", "properties": { "code": { "type": [ "string", "null" ] }, "name": { "type": [ "string", "null" ] }, "version": { "type": [ "string", "null" ] }, "family": { "type": [ "string", "null" ] } }, "required": [ "code", "name", "version", "family" ] }, "primary_ip": { "type": [ "string", "null" ] }, "ips": { "type": "array", "items": { "type": "string" } }, "ipv6": { "type": "array", "items": { "type": "string" } }, "config": { "type": "object", "properties": { "cpu": { "type": "integer", "minimum": 0 }, "ram": { "type": "integer", "minimum": 0 }, "ssd": { "type": "integer", "minimum": 0 }, "hdd": { "type": [ "integer", "null" ], "minimum": 0 }, "cpu_frequency": { "type": "number", "minimum": 0 }, "tier": { "type": "string", "enum": [ "standard", "high-perf" ] } }, "required": [ "cpu", "ram", "ssd", "hdd", "cpu_frequency", "tier" ] }, "expires_at": { "type": [ "string", "null" ] }, "autorenew": { "type": "boolean" }, "created_at": { "type": "string" } }, "required": [ "name", "type", "hostname", "status", "power_state", "location", "os", "primary_ip", "ips", "ipv6", "config", "expires_at", "autorenew", "created_at" ] } }, "required": [ "action", "server" ] } } } }, "401": { "description": "unauthorized: Authentication is required to access this resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "402": { "description": "insufficient_funds: Your account balance is insufficient for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "insufficient_scope | forbidden: Your token does not grant the required scope for this action. You do not have permission to access this resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "not_found: The requested resource was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "conflict | idempotency_conflict: The request conflicts with the current state of the resource. An earlier request with the same Idempotency-Key had a different body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "422": { "description": "invalid_input: The request contains invalid or missing fields.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "rate_limited: Too many requests. Please retry later.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "server_error: An unexpected error occurred. Please try again later.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } } }, "/servers/{name}/ips/{ip}/primary": { "post": { "summary": "Make an IP the primary", "description": "Make an IPv4 address already assigned to the server its primary — the address the list shows, the default of PTR and invoices. Nothing changes on the network: the OS keeps every address. The old primary stays on the server as an additional address. Already the primary → 202 with a succeeded action and nothing written. 404 for an IPv4 not on this server, 422 for an IPv6 prefix or a malformed address, 409 while another IP change on the server is in flight.", "tags": [ "IP Addresses" ], "security": [ { "bearerAuth": [ "server:network" ] } ], "parameters": [ { "schema": { "type": "string", "description": "Server identifier, e.g. `XS-1023`.", "example": "XS-1023" }, "required": true, "description": "Server identifier, e.g. `XS-1023`.", "name": "name", "in": "path" }, { "schema": { "type": "string", "description": "IPv4 address assigned to the server." }, "required": true, "description": "IPv4 address assigned to the server.", "name": "ip", "in": "path" }, { "schema": { "type": "string", "minLength": 1, "maxLength": 255, "description": "Client-supplied key (recommended: ULID). Same key + same body returns the cached response; different body returns `idempotency_conflict`. Stored for 24 h.", "example": "01HXYZABCDEFGHJKMNPQRSTVWX" }, "required": true, "description": "Client-supplied key (recommended: ULID). Same key + same body returns the cached response; different body returns `idempotency_conflict`. Stored for 24 h.", "name": "Idempotency-Key", "in": "header" } ], "responses": { "202": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "action": { "type": "object", "properties": { "id": { "type": "string" }, "command": { "type": "string" }, "status": { "type": "string", "enum": [ "running", "success", "error" ] }, "progress": { "type": "integer", "minimum": 0, "maximum": 100 }, "resources": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string" } }, "required": [ "id", "type" ] } }, "error": { "type": [ "object", "null" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] }, "started_at": { "type": "string" }, "finished_at": { "type": [ "string", "null" ] } }, "required": [ "id", "command", "status", "progress", "resources", "error", "started_at", "finished_at" ] }, "server": { "type": "object", "properties": { "name": { "type": "string" }, "type": { "type": "string", "enum": [ "virtual", "physical" ] }, "hostname": { "type": [ "string", "null" ] }, "status": { "type": "string", "enum": [ "new", "installing", "inventory", "active" ] }, "power_state": { "type": "string", "enum": [ "running", "stopped", "unknown" ] }, "location": { "type": "string" }, "os": { "type": "object", "properties": { "code": { "type": [ "string", "null" ] }, "name": { "type": [ "string", "null" ] }, "version": { "type": [ "string", "null" ] }, "family": { "type": [ "string", "null" ] } }, "required": [ "code", "name", "version", "family" ] }, "primary_ip": { "type": [ "string", "null" ] }, "ips": { "type": "array", "items": { "type": "string" } }, "ipv6": { "type": "array", "items": { "type": "string" } }, "config": { "type": "object", "properties": { "cpu": { "type": "integer", "minimum": 0 }, "ram": { "type": "integer", "minimum": 0 }, "ssd": { "type": "integer", "minimum": 0 }, "hdd": { "type": [ "integer", "null" ], "minimum": 0 }, "cpu_frequency": { "type": "number", "minimum": 0 }, "tier": { "type": "string", "enum": [ "standard", "high-perf" ] } }, "required": [ "cpu", "ram", "ssd", "hdd", "cpu_frequency", "tier" ] }, "expires_at": { "type": [ "string", "null" ] }, "autorenew": { "type": "boolean" }, "created_at": { "type": "string" } }, "required": [ "name", "type", "hostname", "status", "power_state", "location", "os", "primary_ip", "ips", "ipv6", "config", "expires_at", "autorenew", "created_at" ] } }, "required": [ "action", "server" ] } } } }, "401": { "description": "unauthorized: Authentication is required to access this resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "402": { "description": "insufficient_funds: Your account balance is insufficient for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "insufficient_scope | forbidden: Your token does not grant the required scope for this action. You do not have permission to access this resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "not_found: The requested resource was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "conflict | idempotency_conflict: The request conflicts with the current state of the resource. An earlier request with the same Idempotency-Key had a different body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "422": { "description": "invalid_input: The request contains invalid or missing fields.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "rate_limited: Too many requests. Please retry later.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "server_error: An unexpected error occurred. Please try again later.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } } }, "/ip-addresses/{ip}": { "get": { "summary": "Get an IP address", "description": "Inspect an IP allocated to a server owned by the caller. Shows the server it is attached to, the PTR record, and the network it was allocated from.", "tags": [ "IP Addresses" ], "security": [ { "bearerAuth": [ "server:read" ] } ], "parameters": [ { "schema": { "type": "string", "description": "IPv4 or IPv6 address." }, "required": true, "description": "IPv4 or IPv6 address.", "name": "ip", "in": "path" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "ip_address": { "type": "object", "properties": { "ip": { "type": "string" }, "kind": { "type": "string", "enum": [ "v4", "v6" ] }, "is_primary": { "type": "boolean" }, "ptr": { "type": [ "string", "null" ] }, "server_name": { "type": [ "string", "null" ] }, "network_id": { "type": [ "string", "null" ] }, "location": { "type": [ "string", "null" ] }, "assigned_at": { "type": [ "string", "null" ] }, "ptr_records": { "type": [ "array", "null" ], "items": { "type": "object", "properties": { "address": { "type": "string" }, "ptr": { "type": "string" } }, "required": [ "address", "ptr" ] } } }, "required": [ "ip", "kind", "is_primary", "ptr", "server_name", "network_id", "location", "assigned_at", "ptr_records" ] } }, "required": [ "ip_address" ] } } } }, "401": { "description": "unauthorized: Authentication is required to access this resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "insufficient_scope: Your token does not grant the required scope for this action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "not_found: The requested resource was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "rate_limited: Too many requests. Please retry later.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "server_error: An unexpected error occurred. Please try again later.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } }, "patch": { "summary": "Update PTR (rDNS) for an IP", "description": "Set or clear the reverse-DNS record for the IP. Pass `ptr: null` to clear. Upstream DNS validation applies; invalid zones return `invalid_input`.", "tags": [ "IP Addresses" ], "security": [ { "bearerAuth": [ "server:network" ] } ], "parameters": [ { "schema": { "type": "string", "description": "IPv4 or IPv6 address." }, "required": true, "description": "IPv4 or IPv6 address.", "name": "ip", "in": "path" }, { "schema": { "type": "string", "minLength": 1, "maxLength": 255, "description": "Client-supplied key (recommended: ULID). Same key + same body returns the cached response; different body returns `idempotency_conflict`. Stored for 24 h.", "example": "01HXYZABCDEFGHJKMNPQRSTVWX" }, "required": true, "description": "Client-supplied key (recommended: ULID). Same key + same body returns the cached response; different body returns `idempotency_conflict`. Stored for 24 h.", "name": "Idempotency-Key", "in": "header" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "ptr": { "type": [ "string", "null" ], "minLength": 1, "maxLength": 253 } }, "required": [ "ptr" ] } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "ip_address": { "type": "object", "properties": { "ip": { "type": "string" }, "kind": { "type": "string", "enum": [ "v4", "v6" ] }, "is_primary": { "type": "boolean" }, "ptr": { "type": [ "string", "null" ] }, "server_name": { "type": [ "string", "null" ] }, "network_id": { "type": [ "string", "null" ] }, "location": { "type": [ "string", "null" ] }, "assigned_at": { "type": [ "string", "null" ] }, "ptr_records": { "type": [ "array", "null" ], "items": { "type": "object", "properties": { "address": { "type": "string" }, "ptr": { "type": "string" } }, "required": [ "address", "ptr" ] } } }, "required": [ "ip", "kind", "is_primary", "ptr", "server_name", "network_id", "location", "assigned_at", "ptr_records" ] } }, "required": [ "ip_address" ] } } } }, "401": { "description": "unauthorized: Authentication is required to access this resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "insufficient_scope: Your token does not grant the required scope for this action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "not_found: The requested resource was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "idempotency_conflict: An earlier request with the same Idempotency-Key had a different body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "422": { "description": "invalid_input: The request contains invalid or missing fields.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "rate_limited: Too many requests. Please retry later.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "server_error: An unexpected error occurred. Please try again later.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } } }, "/invoices": { "get": { "summary": "List invoices", "description": "Paginated invoice list scoped to the caller. Supports `status`, `period`, and explicit `from` / `to` date filters.", "tags": [ "Billing" ], "security": [ { "bearerAuth": [ "billing:read" ] } ], "parameters": [ { "schema": { "type": "integer", "minimum": 1, "description": "1-based page number. Defaults to 1.", "example": 1 }, "required": false, "description": "1-based page number. Defaults to 1.", "name": "page", "in": "query" }, { "schema": { "type": "integer", "minimum": 1, "maximum": 100, "description": "Page size. Defaults to 25, capped at 100.", "example": 25 }, "required": false, "description": "Page size. Defaults to 25, capped at 100.", "name": "per_page", "in": "query" }, { "schema": { "type": "string", "enum": [ "draft", "pending", "partial", "paid", "cancelled", "refunded" ] }, "required": false, "name": "status", "in": "query" }, { "schema": { "type": "string" }, "required": false, "name": "from", "in": "query" }, { "schema": { "type": "string" }, "required": false, "name": "to", "in": "query" }, { "schema": { "type": "string" }, "required": false, "name": "period", "in": "query" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "invoices": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "number": { "type": "string" }, "status": { "type": "string", "enum": [ "draft", "pending", "partial", "paid", "cancelled", "refunded" ] }, "currency": { "type": "string" }, "amount": { "type": [ "number", "null" ] }, "amount_paid": { "type": [ "number", "null" ] }, "amount_remaining": { "type": [ "number", "null" ] }, "description": { "type": "string" }, "description_text": { "type": "string" }, "items": { "type": "array", "items": { "type": "object", "properties": { "description": { "type": "string" }, "description_text": { "type": "string" }, "quantity": { "type": "number" }, "unit_price": { "type": [ "number", "null" ] }, "total": { "type": [ "number", "null" ] }, "type": { "type": "string" }, "server_name": { "type": [ "string", "null" ] }, "period": { "type": [ "object", "null" ], "properties": { "from": { "type": "string" }, "to": { "type": "string" }, "days": { "type": "number" } }, "required": [ "from", "to", "days" ] } }, "required": [ "description", "description_text", "quantity", "unit_price", "total", "type", "server_name", "period" ] } }, "gateway": { "type": [ "object", "null" ], "properties": { "slug": { "type": "string" }, "name": { "type": "string" } }, "required": [ "slug", "name" ] }, "created_at": { "type": "string" }, "paid_at": { "type": [ "string", "null" ] }, "due_at": { "type": [ "string", "null" ] } }, "required": [ "id", "number", "status", "currency", "amount", "amount_paid", "amount_remaining", "description", "description_text", "items", "gateway", "created_at", "paid_at", "due_at" ] } }, "meta": { "type": "object", "properties": { "pagination": { "$ref": "#/components/schemas/PaginationMeta" } }, "required": [ "pagination" ] } }, "required": [ "invoices", "meta" ] } } } }, "401": { "description": "unauthorized: Authentication is required to access this resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "insufficient_scope: Your token does not grant the required scope for this action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "not_found: The requested resource was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "422": { "description": "invalid_input: The request contains invalid or missing fields.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "rate_limited: Too many requests. Please retry later.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "server_error: An unexpected error occurred. Please try again later.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } } }, "/transactions": { "get": { "summary": "List balance transactions", "description": "The account's balance ledger — charges, deposits, refunds, bonus credits, adjustments — newest first. Filter with `?kind=` (`credit` · `debit` · `refund` · `bonus` · `adjustment`) and `?period=` / `?from=&to=` like the invoice list. Amounts are `null` for a caller without `billing.view`.", "tags": [ "Billing" ], "security": [ { "bearerAuth": [ "billing:read" ] } ], "parameters": [ { "schema": { "type": "integer", "minimum": 1, "description": "1-based page number. Defaults to 1.", "example": 1 }, "required": false, "description": "1-based page number. Defaults to 1.", "name": "page", "in": "query" }, { "schema": { "type": "integer", "minimum": 1, "maximum": 100, "description": "Page size. Defaults to 25, capped at 100.", "example": 25 }, "required": false, "description": "Page size. Defaults to 25, capped at 100.", "name": "per_page", "in": "query" }, { "schema": { "type": "string", "enum": [ "credit", "debit", "refund", "bonus", "adjustment" ] }, "required": false, "name": "kind", "in": "query" }, { "schema": { "type": "string" }, "required": false, "name": "from", "in": "query" }, { "schema": { "type": "string" }, "required": false, "name": "to", "in": "query" }, { "schema": { "type": "string" }, "required": false, "name": "period", "in": "query" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "transactions": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "kind": { "type": "string", "enum": [ "credit", "debit", "refund", "bonus", "adjustment" ] }, "currency": { "type": "string" }, "amount": { "type": [ "number", "null" ] }, "balance_after": { "type": [ "number", "null" ] }, "bonus_after": { "type": [ "number", "null" ] }, "description": { "type": "string" }, "description_text": { "type": "string" }, "invoice_id": { "type": [ "string", "null" ] }, "server_name": { "type": [ "string", "null" ] }, "created_at": { "type": "string" } }, "required": [ "id", "kind", "currency", "amount", "balance_after", "bonus_after", "description", "description_text", "invoice_id", "server_name", "created_at" ] } }, "meta": { "type": "object", "properties": { "pagination": { "$ref": "#/components/schemas/PaginationMeta" } }, "required": [ "pagination" ] } }, "required": [ "transactions", "meta" ] } } } }, "401": { "description": "unauthorized: Authentication is required to access this resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "insufficient_scope: Your token does not grant the required scope for this action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "not_found: The requested resource was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "422": { "description": "invalid_input: The request contains invalid or missing fields.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "rate_limited: Too many requests. Please retry later.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "server_error: An unexpected error occurred. Please try again later.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } } }, "/invoices/{id}": { "get": { "summary": "Get an invoice", "tags": [ "Billing" ], "security": [ { "bearerAuth": [ "billing:read" ] } ], "parameters": [ { "schema": { "type": "string", "description": "Invoice numeric id." }, "required": true, "description": "Invoice numeric id.", "name": "id", "in": "path" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "invoice": { "type": "object", "properties": { "id": { "type": "string" }, "number": { "type": "string" }, "status": { "type": "string", "enum": [ "draft", "pending", "partial", "paid", "cancelled", "refunded" ] }, "currency": { "type": "string" }, "amount": { "type": [ "number", "null" ] }, "amount_paid": { "type": [ "number", "null" ] }, "amount_remaining": { "type": [ "number", "null" ] }, "description": { "type": "string" }, "description_text": { "type": "string" }, "items": { "type": "array", "items": { "type": "object", "properties": { "description": { "type": "string" }, "description_text": { "type": "string" }, "quantity": { "type": "number" }, "unit_price": { "type": [ "number", "null" ] }, "total": { "type": [ "number", "null" ] }, "type": { "type": "string" }, "server_name": { "type": [ "string", "null" ] }, "period": { "type": [ "object", "null" ], "properties": { "from": { "type": "string" }, "to": { "type": "string" }, "days": { "type": "number" } }, "required": [ "from", "to", "days" ] } }, "required": [ "description", "description_text", "quantity", "unit_price", "total", "type", "server_name", "period" ] } }, "gateway": { "type": [ "object", "null" ], "properties": { "slug": { "type": "string" }, "name": { "type": "string" } }, "required": [ "slug", "name" ] }, "created_at": { "type": "string" }, "paid_at": { "type": [ "string", "null" ] }, "due_at": { "type": [ "string", "null" ] } }, "required": [ "id", "number", "status", "currency", "amount", "amount_paid", "amount_remaining", "description", "description_text", "items", "gateway", "created_at", "paid_at", "due_at" ] } }, "required": [ "invoice" ] } } } }, "401": { "description": "unauthorized: Authentication is required to access this resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "insufficient_scope: Your token does not grant the required scope for this action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "not_found: The requested resource was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "rate_limited: Too many requests. Please retry later.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "server_error: An unexpected error occurred. Please try again later.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } } }, "/invoices/{id}/pay": { "post": { "summary": "Pay an invoice from balance", "description": "Charge the account balance for an outstanding invoice. Returns the paid invoice, or `insufficient_funds` if balance + bonus are below the due total. Idempotency-Key required.", "tags": [ "Billing" ], "security": [ { "bearerAuth": [ "billing:write" ] } ], "parameters": [ { "schema": { "type": "string", "description": "Invoice numeric id." }, "required": true, "description": "Invoice numeric id.", "name": "id", "in": "path" }, { "schema": { "type": "string", "minLength": 1, "maxLength": 255, "description": "Client-supplied key (recommended: ULID). Same key + same body returns the cached response; different body returns `idempotency_conflict`. Stored for 24 h.", "example": "01HXYZABCDEFGHJKMNPQRSTVWX" }, "required": true, "description": "Client-supplied key (recommended: ULID). Same key + same body returns the cached response; different body returns `idempotency_conflict`. Stored for 24 h.", "name": "Idempotency-Key", "in": "header" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "method": { "type": "string", "enum": [ "balance" ] }, "useBonus": { "type": "boolean", "default": false } }, "required": [ "method" ] } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "invoice": { "type": "object", "properties": { "id": { "type": "string" }, "number": { "type": "string" }, "status": { "type": "string", "enum": [ "draft", "pending", "partial", "paid", "cancelled", "refunded" ] }, "currency": { "type": "string" }, "amount": { "type": [ "number", "null" ] }, "amount_paid": { "type": [ "number", "null" ] }, "amount_remaining": { "type": [ "number", "null" ] }, "description": { "type": "string" }, "description_text": { "type": "string" }, "items": { "type": "array", "items": { "type": "object", "properties": { "description": { "type": "string" }, "description_text": { "type": "string" }, "quantity": { "type": "number" }, "unit_price": { "type": [ "number", "null" ] }, "total": { "type": [ "number", "null" ] }, "type": { "type": "string" }, "server_name": { "type": [ "string", "null" ] }, "period": { "type": [ "object", "null" ], "properties": { "from": { "type": "string" }, "to": { "type": "string" }, "days": { "type": "number" } }, "required": [ "from", "to", "days" ] } }, "required": [ "description", "description_text", "quantity", "unit_price", "total", "type", "server_name", "period" ] } }, "gateway": { "type": [ "object", "null" ], "properties": { "slug": { "type": "string" }, "name": { "type": "string" } }, "required": [ "slug", "name" ] }, "created_at": { "type": "string" }, "paid_at": { "type": [ "string", "null" ] }, "due_at": { "type": [ "string", "null" ] } }, "required": [ "id", "number", "status", "currency", "amount", "amount_paid", "amount_remaining", "description", "description_text", "items", "gateway", "created_at", "paid_at", "due_at" ] } }, "required": [ "invoice" ] } } } }, "401": { "description": "unauthorized: Authentication is required to access this resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "402": { "description": "insufficient_funds: Your account balance is insufficient for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "insufficient_scope: Your token does not grant the required scope for this action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "not_found: The requested resource was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "conflict | action_in_progress | idempotency_conflict: The request conflicts with the current state of the resource. Another action is already running on this resource. An earlier request with the same Idempotency-Key had a different body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "422": { "description": "invalid_input: The request contains invalid or missing fields.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "rate_limited: Too many requests. Please retry later.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "server_error: An unexpected error occurred. Please try again later.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } } }, "/servers/{name}/renew": { "post": { "summary": "Renew a server", "description": "Renew one server for `months` calendar months from its expiry (1–12) or up to the day `to` — exactly one of the two. `pay: balance` (default) opens the renewal invoice and pays it from the balance (bonus credits only with `use_bonus`); an invoice the balance does not cover stays pending — 402 `insufficient_funds` names it in `details.invoice_id`, top up the balance and pay it with `POST /invoices/{id}/pay`. `pay: invoice` only opens it (`paid: false`). Open renewal invoices for the server answer 409 `conflict` with `details.conflicts` unless `supersede: true` cancels them. One month costs the monthly price; longer terms earn the prepayment discount (`GET /servers/{name}/renew/preview` shows it first). Idempotency-Key required.", "tags": [ "Billing" ], "security": [ { "bearerAuth": [ "billing:write" ] } ], "parameters": [ { "schema": { "type": "string", "description": "Server identifier, e.g. `XS-1023`.", "example": "XS-1023" }, "required": true, "description": "Server identifier, e.g. `XS-1023`.", "name": "name", "in": "path" }, { "schema": { "type": "string", "minLength": 1, "maxLength": 255, "description": "Client-supplied key (recommended: ULID). Same key + same body returns the cached response; different body returns `idempotency_conflict`. Stored for 24 h.", "example": "01HXYZABCDEFGHJKMNPQRSTVWX" }, "required": true, "description": "Client-supplied key (recommended: ULID). Same key + same body returns the cached response; different body returns `idempotency_conflict`. Stored for 24 h.", "name": "Idempotency-Key", "in": "header" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "months": { "type": "integer", "minimum": 1, "maximum": 12 }, "to": { "type": "string" }, "pay": { "type": "string", "enum": [ "balance", "invoice" ], "default": "balance" }, "use_bonus": { "type": "boolean", "default": false }, "supersede": { "type": "boolean", "default": false } } } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "renewal": { "type": "object", "properties": { "current_expire": { "type": "string" }, "new_expire": { "type": "string" }, "days": { "type": "integer" }, "price": { "type": "number" }, "gross_price": { "type": "number" }, "discount_percent": { "type": "number" }, "currency": { "type": "string" }, "invoice_id": { "type": "string" }, "paid": { "type": "boolean" }, "superseded_invoice_ids": { "type": "array", "items": { "type": "string" } }, "invoice": { "type": "object", "properties": { "id": { "type": "string" }, "number": { "type": "string" }, "status": { "type": "string", "enum": [ "draft", "pending", "partial", "paid", "cancelled", "refunded" ] }, "currency": { "type": "string" }, "amount": { "type": [ "number", "null" ] }, "amount_paid": { "type": [ "number", "null" ] }, "amount_remaining": { "type": [ "number", "null" ] }, "description": { "type": "string" }, "description_text": { "type": "string" }, "items": { "type": "array", "items": { "type": "object", "properties": { "description": { "type": "string" }, "description_text": { "type": "string" }, "quantity": { "type": "number" }, "unit_price": { "type": [ "number", "null" ] }, "total": { "type": [ "number", "null" ] }, "type": { "type": "string" }, "server_name": { "type": [ "string", "null" ] }, "period": { "type": [ "object", "null" ], "properties": { "from": { "type": "string" }, "to": { "type": "string" }, "days": { "type": "number" } }, "required": [ "from", "to", "days" ] } }, "required": [ "description", "description_text", "quantity", "unit_price", "total", "type", "server_name", "period" ] } }, "gateway": { "type": [ "object", "null" ], "properties": { "slug": { "type": "string" }, "name": { "type": "string" } }, "required": [ "slug", "name" ] }, "created_at": { "type": "string" }, "paid_at": { "type": [ "string", "null" ] }, "due_at": { "type": [ "string", "null" ] } }, "required": [ "id", "number", "status", "currency", "amount", "amount_paid", "amount_remaining", "description", "description_text", "items", "gateway", "created_at", "paid_at", "due_at" ] } }, "required": [ "current_expire", "new_expire", "days", "price", "gross_price", "discount_percent", "currency", "invoice_id", "paid", "superseded_invoice_ids", "invoice" ] } }, "required": [ "renewal" ] } } } }, "401": { "description": "unauthorized: Authentication is required to access this resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "402": { "description": "insufficient_funds: Your account balance is insufficient for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "insufficient_scope | forbidden: Your token does not grant the required scope for this action. You do not have permission to access this resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "not_found: The requested resource was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "conflict | idempotency_conflict: The request conflicts with the current state of the resource. An earlier request with the same Idempotency-Key had a different body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "422": { "description": "invalid_input: The request contains invalid or missing fields.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "rate_limited: Too many requests. Please retry later.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "server_error: An unexpected error occurred. Please try again later.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } } }, "/orders": { "get": { "summary": "List orders", "description": "Paginated list of the caller account's server-purchase orders, with status and provisioning progress.", "tags": [ "Orders" ], "security": [ { "bearerAuth": [ "billing:read" ] } ], "parameters": [ { "schema": { "type": "integer", "minimum": 1, "description": "1-based page number. Defaults to 1.", "example": 1 }, "required": false, "description": "1-based page number. Defaults to 1.", "name": "page", "in": "query" }, { "schema": { "type": "integer", "minimum": 1, "maximum": 100, "description": "Page size. Defaults to 25, capped at 100.", "example": 25 }, "required": false, "description": "Page size. Defaults to 25, capped at 100.", "name": "per_page", "in": "query" }, { "schema": { "type": "string", "enum": [ "pending_payment", "provisioning", "completed", "failed", "cancelled", "expired" ] }, "required": false, "name": "status", "in": "query" }, { "schema": { "type": "string" }, "required": false, "name": "from", "in": "query" }, { "schema": { "type": "string" }, "required": false, "name": "to", "in": "query" }, { "schema": { "type": "string" }, "required": false, "name": "period", "in": "query" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "orders": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "status": { "type": "string", "enum": [ "pending_payment", "provisioning", "completed", "failed", "cancelled", "expired" ] }, "server_type": { "type": "string", "enum": [ "virtual", "physical" ] }, "tier": { "type": [ "string", "null" ], "enum": [ "standard", "hiperf", null ] }, "config": { "type": [ "object", "null" ], "properties": { "cpu": { "type": [ "integer", "null" ] }, "ram": { "type": [ "integer", "null" ] }, "ssd": { "type": [ "integer", "null" ] }, "hdd": { "type": [ "integer", "null" ] } }, "required": [ "cpu", "ram", "ssd", "hdd" ] }, "locations": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string" }, "quantity": { "type": "integer", "minimum": 1 } }, "required": [ "code", "quantity" ] } }, "os_template": { "type": [ "object", "null" ], "properties": { "code": { "type": "string" }, "name": { "type": [ "string", "null" ] } }, "required": [ "code", "name" ] }, "hostname": { "type": [ "string", "null" ] }, "ipv4": { "type": [ "integer", "null" ] }, "ipv6": { "type": [ "integer", "null" ] }, "services": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string" }, "name": { "type": "string" }, "quantity": { "type": "integer", "minimum": 1 } }, "required": [ "code", "name", "quantity" ] } }, "period_months": { "type": "integer" }, "period": { "type": [ "object", "null" ], "properties": { "from": { "type": "string" }, "to": { "type": "string" } }, "required": [ "from", "to" ] }, "amount": { "type": [ "number", "null" ] }, "currency": { "type": "string" }, "invoice_id": { "type": [ "string", "null" ] }, "server_names": { "type": "array", "items": { "type": "string" } }, "created_at": { "type": "string" }, "paid_at": { "type": [ "string", "null" ] }, "completed_at": { "type": [ "string", "null" ] } }, "required": [ "id", "status", "server_type", "tier", "config", "locations", "os_template", "hostname", "ipv4", "ipv6", "services", "period_months", "period", "amount", "currency", "invoice_id", "server_names", "created_at", "paid_at", "completed_at" ] } }, "meta": { "type": "object", "properties": { "pagination": { "$ref": "#/components/schemas/PaginationMeta" } }, "required": [ "pagination" ] } }, "required": [ "orders", "meta" ] } } } }, "401": { "description": "unauthorized: Authentication is required to access this resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "insufficient_scope: Your token does not grant the required scope for this action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "not_found: The requested resource was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "422": { "description": "invalid_input: The request contains invalid or missing fields.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "rate_limited: Too many requests. Please retry later.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "server_error: An unexpected error occurred. Please try again later.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } }, "post": { "summary": "Place a new server order", "description": "Order a virtual server (`cpu` / `ram` / `ssd`, one or more `locations`) or a dedicated one (`server_type: physical` + `physical_server_id`). The order is paid from the account balance at once; the answer is 202 with the `order` and its paid `invoice`, and provisioning runs in the background — follow `GET /orders/{id}` (`status: provisioning` → `completed`) or `GET /servers`. When the balance does not cover it, 402 `insufficient_funds` names the open invoice in `details.invoice_id` (kept 24 h): top up and pay it with `POST /invoices/{id}/pay`. Price it first with `POST /orders/preview` — same body, same total to the cent, including the account's personal discount and `promo_code`. Add-ons (`services`, from `GET /services`) are priced from the catalogue, each once per order. `ssh_key_ids` and `password` are both optional: without a password the platform generates one and sends it in the install-complete email. `auto_renew` is ignored — a new server takes the account's auto-renewal setting; change it with `PATCH /servers/{name}`. Idempotency-Key required.", "tags": [ "Orders" ], "security": [ { "bearerAuth": [ "billing:write" ] } ], "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 255, "description": "Client-supplied key (recommended: ULID). Same key + same body returns the cached response; different body returns `idempotency_conflict`. Stored for 24 h.", "example": "01HXYZABCDEFGHJKMNPQRSTVWX" }, "required": true, "description": "Client-supplied key (recommended: ULID). Same key + same body returns the cached response; different body returns `idempotency_conflict`. Stored for 24 h.", "name": "Idempotency-Key", "in": "header" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "server_type": { "type": "string", "enum": [ "virtual", "physical" ], "default": "virtual" }, "tier": { "type": "string", "enum": [ "standard", "hiperf" ], "default": "standard" }, "cpu": { "type": "integer", "minimum": 1, "maximum": 64 }, "ram": { "type": "integer", "minimum": 1, "maximum": 256 }, "ssd": { "type": "integer", "minimum": 10, "maximum": 2000 }, "hdd": { "type": "integer", "minimum": 0, "maximum": 8000, "default": 0 }, "location_code": { "type": "string", "minLength": 1, "maxLength": 10 }, "locations": { "type": "array", "items": { "type": "object", "properties": { "location_code": { "type": "string", "minLength": 1, "maxLength": 10 }, "quantity": { "type": "integer", "minimum": 1, "maximum": 10, "default": 1 } }, "required": [ "location_code" ] }, "minItems": 1, "maxItems": 10 }, "os_template_code": { "type": "string", "minLength": 1, "maxLength": 60 }, "hostname": { "type": "string", "minLength": 1, "maxLength": 253 }, "ssh_key_ids": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 40 }, "maxItems": 10 }, "password": { "type": "string", "minLength": 6, "maxLength": 128 }, "ipv4": { "type": "integer", "minimum": 1, "maximum": 8, "default": 1 }, "ipv6": { "type": "boolean", "default": false }, "services": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 40 }, "quantity": { "type": "number", "enum": [ 1 ], "default": 1 } }, "required": [ "id" ] }, "maxItems": 10 }, "period_months": { "anyOf": [ { "type": "number", "enum": [ 1 ] }, { "type": "number", "enum": [ 2 ] }, { "type": "number", "enum": [ 3 ] }, { "type": "number", "enum": [ 6 ] }, { "type": "number", "enum": [ 12 ] } ], "default": 1 }, "auto_renew": { "type": "boolean", "default": true }, "promo_code": { "type": "string", "maxLength": 40 }, "note": { "type": "string", "maxLength": 500 }, "physical_server_id": { "type": "string", "minLength": 1, "maxLength": 40 } }, "required": [ "os_template_code" ] } } } }, "responses": { "202": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "order": { "type": "object", "properties": { "id": { "type": "string" }, "status": { "type": "string", "enum": [ "pending_payment", "provisioning", "completed", "failed", "cancelled", "expired" ] }, "server_type": { "type": "string", "enum": [ "virtual", "physical" ] }, "tier": { "type": [ "string", "null" ], "enum": [ "standard", "hiperf", null ] }, "config": { "type": [ "object", "null" ], "properties": { "cpu": { "type": [ "integer", "null" ] }, "ram": { "type": [ "integer", "null" ] }, "ssd": { "type": [ "integer", "null" ] }, "hdd": { "type": [ "integer", "null" ] } }, "required": [ "cpu", "ram", "ssd", "hdd" ] }, "locations": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string" }, "quantity": { "type": "integer", "minimum": 1 } }, "required": [ "code", "quantity" ] } }, "os_template": { "type": [ "object", "null" ], "properties": { "code": { "type": "string" }, "name": { "type": [ "string", "null" ] } }, "required": [ "code", "name" ] }, "hostname": { "type": [ "string", "null" ] }, "ipv4": { "type": [ "integer", "null" ] }, "ipv6": { "type": [ "integer", "null" ] }, "services": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string" }, "name": { "type": "string" }, "quantity": { "type": "integer", "minimum": 1 } }, "required": [ "code", "name", "quantity" ] } }, "period_months": { "type": "integer" }, "period": { "type": [ "object", "null" ], "properties": { "from": { "type": "string" }, "to": { "type": "string" } }, "required": [ "from", "to" ] }, "amount": { "type": [ "number", "null" ] }, "currency": { "type": "string" }, "invoice_id": { "type": [ "string", "null" ] }, "server_names": { "type": "array", "items": { "type": "string" } }, "created_at": { "type": "string" }, "paid_at": { "type": [ "string", "null" ] }, "completed_at": { "type": [ "string", "null" ] } }, "required": [ "id", "status", "server_type", "tier", "config", "locations", "os_template", "hostname", "ipv4", "ipv6", "services", "period_months", "period", "amount", "currency", "invoice_id", "server_names", "created_at", "paid_at", "completed_at" ] }, "invoice": { "type": "object", "properties": { "id": { "type": "string" }, "number": { "type": "string" }, "status": { "type": "string", "enum": [ "draft", "pending", "partial", "paid", "cancelled", "refunded" ] }, "currency": { "type": "string" }, "amount": { "type": [ "number", "null" ] }, "amount_paid": { "type": [ "number", "null" ] }, "amount_remaining": { "type": [ "number", "null" ] }, "description": { "type": "string" }, "description_text": { "type": "string" }, "items": { "type": "array", "items": { "type": "object", "properties": { "description": { "type": "string" }, "description_text": { "type": "string" }, "quantity": { "type": "number" }, "unit_price": { "type": [ "number", "null" ] }, "total": { "type": [ "number", "null" ] }, "type": { "type": "string" }, "server_name": { "type": [ "string", "null" ] }, "period": { "type": [ "object", "null" ], "properties": { "from": { "type": "string" }, "to": { "type": "string" }, "days": { "type": "number" } }, "required": [ "from", "to", "days" ] } }, "required": [ "description", "description_text", "quantity", "unit_price", "total", "type", "server_name", "period" ] } }, "gateway": { "type": [ "object", "null" ], "properties": { "slug": { "type": "string" }, "name": { "type": "string" } }, "required": [ "slug", "name" ] }, "created_at": { "type": "string" }, "paid_at": { "type": [ "string", "null" ] }, "due_at": { "type": [ "string", "null" ] } }, "required": [ "id", "number", "status", "currency", "amount", "amount_paid", "amount_remaining", "description", "description_text", "items", "gateway", "created_at", "paid_at", "due_at" ] } }, "required": [ "order", "invoice" ] } } } }, "401": { "description": "unauthorized: Authentication is required to access this resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "402": { "description": "insufficient_funds: Your account balance is insufficient for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "insufficient_scope: Your token does not grant the required scope for this action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "not_found: The requested resource was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "conflict | action_in_progress | idempotency_conflict: The request conflicts with the current state of the resource. Another action is already running on this resource. An earlier request with the same Idempotency-Key had a different body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "422": { "description": "invalid_input: The request contains invalid or missing fields.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "rate_limited: Too many requests. Please retry later.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "server_error: An unexpected error occurred. Please try again later.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } } }, "/orders/{id}": { "get": { "summary": "Get an order", "tags": [ "Orders" ], "security": [ { "bearerAuth": [ "billing:read" ] } ], "parameters": [ { "schema": { "type": "string", "description": "Order numeric id or ObjectId." }, "required": true, "description": "Order numeric id or ObjectId.", "name": "id", "in": "path" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "order": { "type": "object", "properties": { "id": { "type": "string" }, "status": { "type": "string", "enum": [ "pending_payment", "provisioning", "completed", "failed", "cancelled", "expired" ] }, "server_type": { "type": "string", "enum": [ "virtual", "physical" ] }, "tier": { "type": [ "string", "null" ], "enum": [ "standard", "hiperf", null ] }, "config": { "type": [ "object", "null" ], "properties": { "cpu": { "type": [ "integer", "null" ] }, "ram": { "type": [ "integer", "null" ] }, "ssd": { "type": [ "integer", "null" ] }, "hdd": { "type": [ "integer", "null" ] } }, "required": [ "cpu", "ram", "ssd", "hdd" ] }, "locations": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string" }, "quantity": { "type": "integer", "minimum": 1 } }, "required": [ "code", "quantity" ] } }, "os_template": { "type": [ "object", "null" ], "properties": { "code": { "type": "string" }, "name": { "type": [ "string", "null" ] } }, "required": [ "code", "name" ] }, "hostname": { "type": [ "string", "null" ] }, "ipv4": { "type": [ "integer", "null" ] }, "ipv6": { "type": [ "integer", "null" ] }, "services": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string" }, "name": { "type": "string" }, "quantity": { "type": "integer", "minimum": 1 } }, "required": [ "code", "name", "quantity" ] } }, "period_months": { "type": "integer" }, "period": { "type": [ "object", "null" ], "properties": { "from": { "type": "string" }, "to": { "type": "string" } }, "required": [ "from", "to" ] }, "amount": { "type": [ "number", "null" ] }, "currency": { "type": "string" }, "invoice_id": { "type": [ "string", "null" ] }, "server_names": { "type": "array", "items": { "type": "string" } }, "created_at": { "type": "string" }, "paid_at": { "type": [ "string", "null" ] }, "completed_at": { "type": [ "string", "null" ] } }, "required": [ "id", "status", "server_type", "tier", "config", "locations", "os_template", "hostname", "ipv4", "ipv6", "services", "period_months", "period", "amount", "currency", "invoice_id", "server_names", "created_at", "paid_at", "completed_at" ] } }, "required": [ "order" ] } } } }, "401": { "description": "unauthorized: Authentication is required to access this resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "insufficient_scope: Your token does not grant the required scope for this action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "not_found: The requested resource was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "rate_limited: Too many requests. Please retry later.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "server_error: An unexpected error occurred. Please try again later.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } } }, "/servers/{name}/resize": { "post": { "summary": "Resize a server", "description": "Change a VPS's cpu / ram / ssd / hdd (`config`; omitted sizes keep their value). A downgrade is applied at once and the unused difference credited; an upgrade is a `resize` invoice paid from the balance (`use_bonus` spends the bonus pool too; 402 when the balance does not cover it, nothing changes) — its fulfilment applies the new sizes. CPU or RAM shrink only on a powered-off server (409); SSD / HDD never shrink (422). The work finishes in the request; the Action is the receipt. Idempotency-Key required.", "tags": [ "Servers" ], "security": [ { "bearerAuth": [ "server:write" ] } ], "parameters": [ { "schema": { "type": "string", "description": "Server identifier, e.g. `XS-1023`.", "example": "XS-1023" }, "required": true, "description": "Server identifier, e.g. `XS-1023`.", "name": "name", "in": "path" }, { "schema": { "type": "string", "minLength": 1, "maxLength": 255, "description": "Client-supplied key (recommended: ULID). Same key + same body returns the cached response; different body returns `idempotency_conflict`. Stored for 24 h.", "example": "01HXYZABCDEFGHJKMNPQRSTVWX" }, "required": true, "description": "Client-supplied key (recommended: ULID). Same key + same body returns the cached response; different body returns `idempotency_conflict`. Stored for 24 h.", "name": "Idempotency-Key", "in": "header" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "config": { "type": "object", "properties": { "cpu": { "type": "integer", "minimum": 1, "maximum": 64 }, "ram": { "type": "integer", "minimum": 1 }, "ssd": { "type": "integer", "minimum": 10 }, "hdd": { "type": [ "integer", "null" ], "minimum": 0 } } }, "use_bonus": { "type": "boolean" } }, "required": [ "config" ] } } } }, "responses": { "202": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "action": { "type": "object", "properties": { "id": { "type": "string" }, "command": { "type": "string" }, "status": { "type": "string", "enum": [ "running", "success", "error" ] }, "progress": { "type": "integer", "minimum": 0, "maximum": 100 }, "resources": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string" } }, "required": [ "id", "type" ] } }, "error": { "type": [ "object", "null" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] }, "started_at": { "type": "string" }, "finished_at": { "type": [ "string", "null" ] } }, "required": [ "id", "command", "status", "progress", "resources", "error", "started_at", "finished_at" ] }, "server": { "type": "object", "properties": { "name": { "type": "string" }, "type": { "type": "string", "enum": [ "virtual", "physical" ] }, "hostname": { "type": [ "string", "null" ] }, "status": { "type": "string", "enum": [ "new", "installing", "inventory", "active" ] }, "power_state": { "type": "string", "enum": [ "running", "stopped", "unknown" ] }, "location": { "type": "string" }, "os": { "type": "object", "properties": { "code": { "type": [ "string", "null" ] }, "name": { "type": [ "string", "null" ] }, "version": { "type": [ "string", "null" ] }, "family": { "type": [ "string", "null" ] } }, "required": [ "code", "name", "version", "family" ] }, "primary_ip": { "type": [ "string", "null" ] }, "ips": { "type": "array", "items": { "type": "string" } }, "ipv6": { "type": "array", "items": { "type": "string" } }, "config": { "type": "object", "properties": { "cpu": { "type": "integer", "minimum": 0 }, "ram": { "type": "integer", "minimum": 0 }, "ssd": { "type": "integer", "minimum": 0 }, "hdd": { "type": [ "integer", "null" ], "minimum": 0 }, "cpu_frequency": { "type": "number", "minimum": 0 }, "tier": { "type": "string", "enum": [ "standard", "high-perf" ] } }, "required": [ "cpu", "ram", "ssd", "hdd", "cpu_frequency", "tier" ] }, "expires_at": { "type": [ "string", "null" ] }, "autorenew": { "type": "boolean" }, "created_at": { "type": "string" } }, "required": [ "name", "type", "hostname", "status", "power_state", "location", "os", "primary_ip", "ips", "ipv6", "config", "expires_at", "autorenew", "created_at" ] }, "invoice": { "type": [ "object", "null" ], "properties": { "id": { "type": "string" }, "number": { "type": "string" }, "status": { "type": "string", "enum": [ "draft", "pending", "partial", "paid", "cancelled", "refunded" ] }, "currency": { "type": "string" }, "amount": { "type": [ "number", "null" ] }, "amount_paid": { "type": [ "number", "null" ] }, "amount_remaining": { "type": [ "number", "null" ] }, "description": { "type": "string" }, "description_text": { "type": "string" }, "items": { "type": "array", "items": { "type": "object", "properties": { "description": { "type": "string" }, "description_text": { "type": "string" }, "quantity": { "type": "number" }, "unit_price": { "type": [ "number", "null" ] }, "total": { "type": [ "number", "null" ] }, "type": { "type": "string" }, "server_name": { "type": [ "string", "null" ] }, "period": { "type": [ "object", "null" ], "properties": { "from": { "type": "string" }, "to": { "type": "string" }, "days": { "type": "number" } }, "required": [ "from", "to", "days" ] } }, "required": [ "description", "description_text", "quantity", "unit_price", "total", "type", "server_name", "period" ] } }, "gateway": { "type": [ "object", "null" ], "properties": { "slug": { "type": "string" }, "name": { "type": "string" } }, "required": [ "slug", "name" ] }, "created_at": { "type": "string" }, "paid_at": { "type": [ "string", "null" ] }, "due_at": { "type": [ "string", "null" ] } }, "required": [ "id", "number", "status", "currency", "amount", "amount_paid", "amount_remaining", "description", "description_text", "items", "gateway", "created_at", "paid_at", "due_at" ] }, "poweroff_required": { "type": "boolean" } }, "required": [ "action", "server", "invoice", "poweroff_required" ] } } } }, "401": { "description": "unauthorized: Authentication is required to access this resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "402": { "description": "insufficient_funds: Your account balance is insufficient for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "insufficient_scope: Your token does not grant the required scope for this action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "not_found: The requested resource was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "conflict | idempotency_conflict: The request conflicts with the current state of the resource. An earlier request with the same Idempotency-Key had a different body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "422": { "description": "invalid_input: The request contains invalid or missing fields.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "rate_limited: Too many requests. Please retry later.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "server_error: An unexpected error occurred. Please try again later.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } } }, "/services": { "get": { "summary": "List available services", "description": "Catalogue of add-on services (backup, monitoring, etc.) that can be attached to a server. Public reference data.", "tags": [ "Services" ], "security": [], "parameters": [ { "schema": { "type": "integer", "minimum": 1, "description": "1-based page number. Defaults to 1.", "example": 1 }, "required": false, "description": "1-based page number. Defaults to 1.", "name": "page", "in": "query" }, { "schema": { "type": "integer", "minimum": 1, "maximum": 100, "description": "Page size. Defaults to 25, capped at 100.", "example": 25 }, "required": false, "description": "Page size. Defaults to 25, capped at 100.", "name": "per_page", "in": "query" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "services": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string" }, "name": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "price": { "type": [ "number", "null" ] }, "currency": { "type": "string" }, "billing_period": { "type": "string", "enum": [ "monthly", "annual", "one_time" ] }, "category": { "type": [ "string", "null" ] }, "max_per_server": { "type": [ "integer", "null" ] } }, "required": [ "code", "name", "description", "price", "currency", "billing_period", "category", "max_per_server" ] } }, "meta": { "type": "object", "properties": { "pagination": { "$ref": "#/components/schemas/PaginationMeta" } }, "required": [ "pagination" ] } }, "required": [ "services", "meta" ] } } } }, "404": { "description": "not_found: The requested resource was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "rate_limited: Too many requests. Please retry later.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "server_error: An unexpected error occurred. Please try again later.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } } }, "/servers/{name}/services": { "get": { "summary": "List services on a server", "description": "Active + pending services attached to the given server.", "tags": [ "Services" ], "security": [ { "bearerAuth": [ "server:read" ] } ], "parameters": [ { "schema": { "type": "string", "description": "Server identifier, e.g. `XS-1023`.", "example": "XS-1023" }, "required": true, "description": "Server identifier, e.g. `XS-1023`.", "name": "name", "in": "path" }, { "schema": { "type": "integer", "minimum": 1, "description": "1-based page number. Defaults to 1.", "example": 1 }, "required": false, "description": "1-based page number. Defaults to 1.", "name": "page", "in": "query" }, { "schema": { "type": "integer", "minimum": 1, "maximum": 100, "description": "Page size. Defaults to 25, capped at 100.", "example": 25 }, "required": false, "description": "Page size. Defaults to 25, capped at 100.", "name": "per_page", "in": "query" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "services": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "code": { "type": "string" }, "name": { "type": "string" }, "status": { "type": "string", "enum": [ "active", "pending", "cancelled", "expired" ] }, "ordered_at": { "type": "string" }, "expires_at": { "type": [ "string", "null" ] }, "price": { "type": [ "number", "null" ] } }, "required": [ "id", "code", "name", "status", "ordered_at", "expires_at", "price" ] } }, "meta": { "type": "object", "properties": { "pagination": { "$ref": "#/components/schemas/PaginationMeta" } }, "required": [ "pagination" ] } }, "required": [ "services", "meta" ] } } } }, "401": { "description": "unauthorized: Authentication is required to access this resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "insufficient_scope: Your token does not grant the required scope for this action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "not_found: The requested resource was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "rate_limited: Too many requests. Please retry later.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "server_error: An unexpected error occurred. Please try again later.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } }, "post": { "summary": "Order a service for a server", "description": "Order an add-on for the server: `{ code, quantity? }`. The prorated charge for the rest of the paid period is paid from the balance at once (402 when it does not cover it — the API has no gateway flow); an active server gets the service right away, an expired one as `pending` until the next renewal. An add-on has no term of its own: it renews with the server. 409 with `details.conflicts` when another service of the same exclusive group is attached — cancel it first. The work finishes in the request; the Action is the receipt. Idempotency-Key required.", "tags": [ "Services" ], "security": [ { "bearerAuth": [ "server:write" ] } ], "parameters": [ { "schema": { "type": "string", "description": "Server identifier, e.g. `XS-1023`.", "example": "XS-1023" }, "required": true, "description": "Server identifier, e.g. `XS-1023`.", "name": "name", "in": "path" }, { "schema": { "type": "string", "minLength": 1, "maxLength": 255, "description": "Client-supplied key (recommended: ULID). Same key + same body returns the cached response; different body returns `idempotency_conflict`. Stored for 24 h.", "example": "01HXYZABCDEFGHJKMNPQRSTVWX" }, "required": true, "description": "Client-supplied key (recommended: ULID). Same key + same body returns the cached response; different body returns `idempotency_conflict`. Stored for 24 h.", "name": "Idempotency-Key", "in": "header" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string", "minLength": 1, "maxLength": 60 }, "quantity": { "type": "integer", "minimum": 1, "default": 1 } }, "required": [ "code" ] } } } }, "responses": { "202": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "action": { "type": "object", "properties": { "id": { "type": "string" }, "command": { "type": "string" }, "status": { "type": "string", "enum": [ "running", "success", "error" ] }, "progress": { "type": "integer", "minimum": 0, "maximum": 100 }, "resources": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string" } }, "required": [ "id", "type" ] } }, "error": { "type": [ "object", "null" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] }, "started_at": { "type": "string" }, "finished_at": { "type": [ "string", "null" ] } }, "required": [ "id", "command", "status", "progress", "resources", "error", "started_at", "finished_at" ] }, "server": { "type": "object", "properties": { "name": { "type": "string" }, "type": { "type": "string", "enum": [ "virtual", "physical" ] }, "hostname": { "type": [ "string", "null" ] }, "status": { "type": "string", "enum": [ "new", "installing", "inventory", "active" ] }, "power_state": { "type": "string", "enum": [ "running", "stopped", "unknown" ] }, "location": { "type": "string" }, "os": { "type": "object", "properties": { "code": { "type": [ "string", "null" ] }, "name": { "type": [ "string", "null" ] }, "version": { "type": [ "string", "null" ] }, "family": { "type": [ "string", "null" ] } }, "required": [ "code", "name", "version", "family" ] }, "primary_ip": { "type": [ "string", "null" ] }, "ips": { "type": "array", "items": { "type": "string" } }, "ipv6": { "type": "array", "items": { "type": "string" } }, "config": { "type": "object", "properties": { "cpu": { "type": "integer", "minimum": 0 }, "ram": { "type": "integer", "minimum": 0 }, "ssd": { "type": "integer", "minimum": 0 }, "hdd": { "type": [ "integer", "null" ], "minimum": 0 }, "cpu_frequency": { "type": "number", "minimum": 0 }, "tier": { "type": "string", "enum": [ "standard", "high-perf" ] } }, "required": [ "cpu", "ram", "ssd", "hdd", "cpu_frequency", "tier" ] }, "expires_at": { "type": [ "string", "null" ] }, "autorenew": { "type": "boolean" }, "created_at": { "type": "string" } }, "required": [ "name", "type", "hostname", "status", "power_state", "location", "os", "primary_ip", "ips", "ipv6", "config", "expires_at", "autorenew", "created_at" ] }, "server_service": { "type": "object", "properties": { "id": { "type": "string" }, "code": { "type": "string" }, "name": { "type": "string" }, "status": { "type": "string", "enum": [ "active", "pending", "cancelled", "expired" ] }, "ordered_at": { "type": "string" }, "expires_at": { "type": [ "string", "null" ] }, "price": { "type": [ "number", "null" ] } }, "required": [ "id", "code", "name", "status", "ordered_at", "expires_at", "price" ] } }, "required": [ "action", "server", "server_service" ] } } } }, "401": { "description": "unauthorized: Authentication is required to access this resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "402": { "description": "insufficient_funds: Your account balance is insufficient for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "insufficient_scope | forbidden: Your token does not grant the required scope for this action. You do not have permission to access this resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "not_found: The requested resource was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "conflict | idempotency_conflict: The request conflicts with the current state of the resource. An earlier request with the same Idempotency-Key had a different body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "422": { "description": "invalid_input: The request contains invalid or missing fields.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "rate_limited: Too many requests. Please retry later.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "server_error: An unexpected error occurred. Please try again later.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } } }, "/servers/{name}/services/{id}": { "delete": { "summary": "Cancel a server service", "description": "Cancel an attached add-on. `{id}` is the `${serverName}:${code}` handle from the list, or the bare code. The service leaves the server at once, the server is re-priced, and the unused part of the paid period is credited to the balance when the catalogue marks the add-on refundable (`action.metadata.refund_amount`). 422 when the catalogue keeps it. Idempotency-Key required.", "tags": [ "Services" ], "security": [ { "bearerAuth": [ "server:write" ] } ], "parameters": [ { "schema": { "type": "string", "description": "Server identifier, e.g. `XS-1023`.", "example": "XS-1023" }, "required": true, "description": "Server identifier, e.g. `XS-1023`.", "name": "name", "in": "path" }, { "schema": { "type": "string", "description": "The `${serverName}:${code}` handle from the list, or the service code." }, "required": true, "description": "The `${serverName}:${code}` handle from the list, or the service code.", "name": "id", "in": "path" }, { "schema": { "type": "string", "minLength": 1, "maxLength": 255, "description": "Client-supplied key (recommended: ULID). Same key + same body returns the cached response; different body returns `idempotency_conflict`. Stored for 24 h.", "example": "01HXYZABCDEFGHJKMNPQRSTVWX" }, "required": true, "description": "Client-supplied key (recommended: ULID). Same key + same body returns the cached response; different body returns `idempotency_conflict`. Stored for 24 h.", "name": "Idempotency-Key", "in": "header" } ], "responses": { "202": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "action": { "type": "object", "properties": { "id": { "type": "string" }, "command": { "type": "string" }, "status": { "type": "string", "enum": [ "running", "success", "error" ] }, "progress": { "type": "integer", "minimum": 0, "maximum": 100 }, "resources": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string" } }, "required": [ "id", "type" ] } }, "error": { "type": [ "object", "null" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] }, "started_at": { "type": "string" }, "finished_at": { "type": [ "string", "null" ] } }, "required": [ "id", "command", "status", "progress", "resources", "error", "started_at", "finished_at" ] }, "server": { "type": "object", "properties": { "name": { "type": "string" }, "type": { "type": "string", "enum": [ "virtual", "physical" ] }, "hostname": { "type": [ "string", "null" ] }, "status": { "type": "string", "enum": [ "new", "installing", "inventory", "active" ] }, "power_state": { "type": "string", "enum": [ "running", "stopped", "unknown" ] }, "location": { "type": "string" }, "os": { "type": "object", "properties": { "code": { "type": [ "string", "null" ] }, "name": { "type": [ "string", "null" ] }, "version": { "type": [ "string", "null" ] }, "family": { "type": [ "string", "null" ] } }, "required": [ "code", "name", "version", "family" ] }, "primary_ip": { "type": [ "string", "null" ] }, "ips": { "type": "array", "items": { "type": "string" } }, "ipv6": { "type": "array", "items": { "type": "string" } }, "config": { "type": "object", "properties": { "cpu": { "type": "integer", "minimum": 0 }, "ram": { "type": "integer", "minimum": 0 }, "ssd": { "type": "integer", "minimum": 0 }, "hdd": { "type": [ "integer", "null" ], "minimum": 0 }, "cpu_frequency": { "type": "number", "minimum": 0 }, "tier": { "type": "string", "enum": [ "standard", "high-perf" ] } }, "required": [ "cpu", "ram", "ssd", "hdd", "cpu_frequency", "tier" ] }, "expires_at": { "type": [ "string", "null" ] }, "autorenew": { "type": "boolean" }, "created_at": { "type": "string" } }, "required": [ "name", "type", "hostname", "status", "power_state", "location", "os", "primary_ip", "ips", "ipv6", "config", "expires_at", "autorenew", "created_at" ] } }, "required": [ "action", "server" ] } } } }, "401": { "description": "unauthorized: Authentication is required to access this resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "402": { "description": "insufficient_funds: Your account balance is insufficient for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "insufficient_scope | forbidden: Your token does not grant the required scope for this action. You do not have permission to access this resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "not_found: The requested resource was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "conflict | idempotency_conflict: The request conflicts with the current state of the resource. An earlier request with the same Idempotency-Key had a different body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "422": { "description": "invalid_input: The request contains invalid or missing fields.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "rate_limited: Too many requests. Please retry later.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "server_error: An unexpected error occurred. Please try again later.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } } }, "/servers/{name}/backups": { "get": { "summary": "List backups for a server", "description": "Virtual servers only — physical servers have no backups and respond with `conflict`. The list unifies two kinds of entries: ad-hoc `snapshot`s taken on demand and `restore_point`s produced by the attached backup service. Each entry carries a `kind` discriminator so clients can treat them uniformly.", "tags": [ "Backups" ], "security": [ { "bearerAuth": [ "server:read" ] } ], "parameters": [ { "schema": { "type": "string", "description": "Server identifier, e.g. `XS-1023`.", "example": "XS-1023" }, "required": true, "description": "Server identifier, e.g. `XS-1023`.", "name": "name", "in": "path" }, { "schema": { "type": "integer", "minimum": 1, "description": "1-based page number. Defaults to 1.", "example": 1 }, "required": false, "description": "1-based page number. Defaults to 1.", "name": "page", "in": "query" }, { "schema": { "type": "integer", "minimum": 1, "maximum": 100, "description": "Page size. Defaults to 25, capped at 100.", "example": 25 }, "required": false, "description": "Page size. Defaults to 25, capped at 100.", "name": "per_page", "in": "query" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "backups": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "kind": { "type": "string", "enum": [ "snapshot", "restore_point" ] }, "name": { "type": "string" }, "created_at": { "type": "string" }, "size_bytes": { "type": [ "integer", "null" ] }, "description": { "type": [ "string", "null" ] }, "status": { "type": "string", "enum": [ "ready", "creating", "restoring", "failed" ] } }, "required": [ "id", "kind", "name", "created_at", "size_bytes", "description", "status" ] } }, "meta": { "type": "object", "properties": { "pagination": { "$ref": "#/components/schemas/PaginationMeta" } }, "required": [ "pagination" ] } }, "required": [ "backups", "meta" ] } } } }, "401": { "description": "unauthorized: Authentication is required to access this resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "insufficient_scope: Your token does not grant the required scope for this action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "not_found: The requested resource was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "conflict: The request conflicts with the current state of the resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "rate_limited: Too many requests. Please retry later.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "server_error: An unexpected error occurred. Please try again later.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "service_unavailable: The service is temporarily unavailable. Please try again later.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } } }, "/servers/{name}/backups/{id}": { "get": { "summary": "Get a backup", "tags": [ "Backups" ], "security": [ { "bearerAuth": [ "server:read" ] } ], "parameters": [ { "schema": { "type": "string", "description": "Server identifier, e.g. `XS-1023`.", "example": "XS-1023" }, "required": true, "description": "Server identifier, e.g. `XS-1023`.", "name": "name", "in": "path" }, { "schema": { "type": "string", "description": "Backup id." }, "required": true, "description": "Backup id.", "name": "id", "in": "path" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "backup": { "type": "object", "properties": { "id": { "type": "string" }, "kind": { "type": "string", "enum": [ "snapshot", "restore_point" ] }, "name": { "type": "string" }, "created_at": { "type": "string" }, "size_bytes": { "type": [ "integer", "null" ] }, "description": { "type": [ "string", "null" ] }, "status": { "type": "string", "enum": [ "ready", "creating", "restoring", "failed" ] } }, "required": [ "id", "kind", "name", "created_at", "size_bytes", "description", "status" ] } }, "required": [ "backup" ] } } } }, "401": { "description": "unauthorized: Authentication is required to access this resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "insufficient_scope: Your token does not grant the required scope for this action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "not_found: The requested resource was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "rate_limited: Too many requests. Please retry later.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "server_error: An unexpected error occurred. Please try again later.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } }, "delete": { "summary": "Delete a backup point", "description": "Virtual servers only: removes an ad-hoc snapshot (VMware RemoveSnapshot) and returns 202 + an Action to poll. Restore points of the attached backup service are retention-managed and answer `conflict`; physical servers answer `conflict`. Irreversible: requires a TFA clearance — `X-Tfa-Token` from `POST /account/tfa/verify` or an inline `X-Tfa-Code` (TOTP) header; accounts without TFA pass through. Idempotency-Key required.", "tags": [ "Backups" ], "security": [ { "bearerAuth": [ "server:reinstall" ] } ], "parameters": [ { "schema": { "type": "string", "description": "Server identifier, e.g. `XS-1023`.", "example": "XS-1023" }, "required": true, "description": "Server identifier, e.g. `XS-1023`.", "name": "name", "in": "path" }, { "schema": { "type": "string", "description": "Backup id (snapshot id)." }, "required": true, "description": "Backup id (snapshot id).", "name": "id", "in": "path" }, { "schema": { "type": "string", "minLength": 1, "maxLength": 255, "description": "Client-supplied key (recommended: ULID). Same key + same body returns the cached response; different body returns `idempotency_conflict`. Stored for 24 h.", "example": "01HXYZABCDEFGHJKMNPQRSTVWX" }, "required": true, "description": "Client-supplied key (recommended: ULID). Same key + same body returns the cached response; different body returns `idempotency_conflict`. Stored for 24 h.", "name": "Idempotency-Key", "in": "header" }, { "schema": { "type": "string", "description": "One-shot proof from `POST /account/tfa/verify` (TOTP or Passkey). Required when the account has TFA enabled, unless `X-Tfa-Code` (or an inline `tfa_code` body field) is sent. Missing or invalid → 401 `tfa_required` / 422 `tfa_invalid`.", "example": "tfa_01HXYZABCDEFGHJKMNPQRSTVWX" }, "required": false, "description": "One-shot proof from `POST /account/tfa/verify` (TOTP or Passkey). Required when the account has TFA enabled, unless `X-Tfa-Code` (or an inline `tfa_code` body field) is sent. Missing or invalid → 401 `tfa_required` / 422 `tfa_invalid`.", "name": "X-Tfa-Token", "in": "header" }, { "schema": { "type": "string", "description": "Inline 6-digit TOTP code (Authenticator accounts only). `X-Tfa-Token` wins when both are present.", "example": "123456" }, "required": false, "description": "Inline 6-digit TOTP code (Authenticator accounts only). `X-Tfa-Token` wins when both are present.", "name": "X-Tfa-Code", "in": "header" } ], "responses": { "202": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "action": { "type": "object", "properties": { "id": { "type": "string" }, "command": { "type": "string" }, "status": { "type": "string", "enum": [ "running", "success", "error" ] }, "progress": { "type": "integer", "minimum": 0, "maximum": 100 }, "resources": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string" } }, "required": [ "id", "type" ] } }, "error": { "type": [ "object", "null" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] }, "started_at": { "type": "string" }, "finished_at": { "type": [ "string", "null" ] } }, "required": [ "id", "command", "status", "progress", "resources", "error", "started_at", "finished_at" ] } }, "required": [ "action" ] } } } }, "401": { "description": "unauthorized: Authentication is required to access this resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "402": { "description": "insufficient_funds: Your account balance is insufficient for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "insufficient_scope | forbidden: Your token does not grant the required scope for this action. You do not have permission to access this resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "not_found: The requested resource was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "conflict | idempotency_conflict: The request conflicts with the current state of the resource. An earlier request with the same Idempotency-Key had a different body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "422": { "description": "invalid_input: The request contains invalid or missing fields.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "rate_limited: Too many requests. Please retry later.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "server_error: An unexpected error occurred. Please try again later.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "service_unavailable: The service is temporarily unavailable. Please try again later.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } } }, "/servers/{name}/backups/{id}/restore": { "post": { "summary": "Restore from a backup", "description": "Restore the server from the chosen snapshot / restore point. 202 + Action; progress polled via `/actions/{id}`. Idempotency-Key required.", "tags": [ "Backups" ], "security": [ { "bearerAuth": [ "server:reinstall" ] } ], "parameters": [ { "schema": { "type": "string", "description": "Server identifier, e.g. `XS-1023`.", "example": "XS-1023" }, "required": true, "description": "Server identifier, e.g. `XS-1023`.", "name": "name", "in": "path" }, { "schema": { "type": "string", "description": "Backup id." }, "required": true, "description": "Backup id.", "name": "id", "in": "path" }, { "schema": { "type": "string", "minLength": 1, "maxLength": 255, "description": "Client-supplied key (recommended: ULID). Same key + same body returns the cached response; different body returns `idempotency_conflict`. Stored for 24 h.", "example": "01HXYZABCDEFGHJKMNPQRSTVWX" }, "required": true, "description": "Client-supplied key (recommended: ULID). Same key + same body returns the cached response; different body returns `idempotency_conflict`. Stored for 24 h.", "name": "Idempotency-Key", "in": "header" }, { "schema": { "type": "string", "description": "One-shot proof from `POST /account/tfa/verify` (TOTP or Passkey). Required when the account has TFA enabled, unless `X-Tfa-Code` (or an inline `tfa_code` body field) is sent. Missing or invalid → 401 `tfa_required` / 422 `tfa_invalid`.", "example": "tfa_01HXYZABCDEFGHJKMNPQRSTVWX" }, "required": false, "description": "One-shot proof from `POST /account/tfa/verify` (TOTP or Passkey). Required when the account has TFA enabled, unless `X-Tfa-Code` (or an inline `tfa_code` body field) is sent. Missing or invalid → 401 `tfa_required` / 422 `tfa_invalid`.", "name": "X-Tfa-Token", "in": "header" }, { "schema": { "type": "string", "description": "Inline 6-digit TOTP code (Authenticator accounts only). `X-Tfa-Token` wins when both are present.", "example": "123456" }, "required": false, "description": "Inline 6-digit TOTP code (Authenticator accounts only). `X-Tfa-Token` wins when both are present.", "name": "X-Tfa-Code", "in": "header" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "tfa_code": { "type": "string" } } } } } }, "responses": { "202": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "action": { "type": "object", "properties": { "id": { "type": "string" }, "command": { "type": "string" }, "status": { "type": "string", "enum": [ "running", "success", "error" ] }, "progress": { "type": "integer", "minimum": 0, "maximum": 100 }, "resources": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string" } }, "required": [ "id", "type" ] } }, "error": { "type": [ "object", "null" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] }, "started_at": { "type": "string" }, "finished_at": { "type": [ "string", "null" ] } }, "required": [ "id", "command", "status", "progress", "resources", "error", "started_at", "finished_at" ] }, "server": { "type": "object", "properties": { "name": { "type": "string" }, "type": { "type": "string", "enum": [ "virtual", "physical" ] }, "hostname": { "type": [ "string", "null" ] }, "status": { "type": "string", "enum": [ "new", "installing", "inventory", "active" ] }, "power_state": { "type": "string", "enum": [ "running", "stopped", "unknown" ] }, "location": { "type": "string" }, "os": { "type": "object", "properties": { "code": { "type": [ "string", "null" ] }, "name": { "type": [ "string", "null" ] }, "version": { "type": [ "string", "null" ] }, "family": { "type": [ "string", "null" ] } }, "required": [ "code", "name", "version", "family" ] }, "primary_ip": { "type": [ "string", "null" ] }, "ips": { "type": "array", "items": { "type": "string" } }, "ipv6": { "type": "array", "items": { "type": "string" } }, "config": { "type": "object", "properties": { "cpu": { "type": "integer", "minimum": 0 }, "ram": { "type": "integer", "minimum": 0 }, "ssd": { "type": "integer", "minimum": 0 }, "hdd": { "type": [ "integer", "null" ], "minimum": 0 }, "cpu_frequency": { "type": "number", "minimum": 0 }, "tier": { "type": "string", "enum": [ "standard", "high-perf" ] } }, "required": [ "cpu", "ram", "ssd", "hdd", "cpu_frequency", "tier" ] }, "expires_at": { "type": [ "string", "null" ] }, "autorenew": { "type": "boolean" }, "created_at": { "type": "string" } }, "required": [ "name", "type", "hostname", "status", "power_state", "location", "os", "primary_ip", "ips", "ipv6", "config", "expires_at", "autorenew", "created_at" ] } }, "required": [ "action", "server" ] } } } }, "401": { "description": "unauthorized: Authentication is required to access this resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "402": { "description": "insufficient_funds: Your account balance is insufficient for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "insufficient_scope | forbidden: Your token does not grant the required scope for this action. You do not have permission to access this resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "not_found: The requested resource was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "conflict | idempotency_conflict: The request conflicts with the current state of the resource. An earlier request with the same Idempotency-Key had a different body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "422": { "description": "invalid_input: The request contains invalid or missing fields.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "rate_limited: Too many requests. Please retry later.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "server_error: An unexpected error occurred. Please try again later.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "service_unavailable: The service is temporarily unavailable. Please try again later.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } } }, "/servers/{name}/snapshots": { "get": { "summary": "List snapshots on a server", "description": "List snapshots on a virtual server. Physical servers respond with `conflict` — snapshots are only available on virtual servers. Sorted newest first. System snapshots created by automated backup jobs are omitted.", "tags": [ "Snapshots" ], "security": [ { "bearerAuth": [ "server:read" ] } ], "parameters": [ { "schema": { "type": "string", "description": "Server identifier, e.g. `XS-1023`.", "example": "XS-1023" }, "required": true, "description": "Server identifier, e.g. `XS-1023`.", "name": "name", "in": "path" }, { "schema": { "type": "integer", "minimum": 1, "description": "1-based page number. Defaults to 1.", "example": 1 }, "required": false, "description": "1-based page number. Defaults to 1.", "name": "page", "in": "query" }, { "schema": { "type": "integer", "minimum": 1, "maximum": 100, "description": "Page size. Defaults to 25, capped at 100.", "example": 25 }, "required": false, "description": "Page size. Defaults to 25, capped at 100.", "name": "per_page", "in": "query" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "snapshots": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "server_name": { "type": "string" }, "created_at": { "type": "string" }, "size_bytes": { "type": [ "integer", "null" ] }, "parent_id": { "type": [ "string", "null" ] }, "state": { "type": "string", "enum": [ "created", "current", "old" ] }, "quiesced": { "type": "boolean" }, "with_memory": { "type": "boolean" } }, "required": [ "id", "name", "description", "server_name", "created_at", "size_bytes", "parent_id", "state", "quiesced", "with_memory" ] } }, "meta": { "type": "object", "properties": { "pagination": { "$ref": "#/components/schemas/PaginationMeta" } }, "required": [ "pagination" ] } }, "required": [ "snapshots", "meta" ] } } } }, "401": { "description": "unauthorized: Authentication is required to access this resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "insufficient_scope: Your token does not grant the required scope for this action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "not_found: The requested resource was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "conflict: The request conflicts with the current state of the resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "rate_limited: Too many requests. Please retry later.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "server_error: An unexpected error occurred. Please try again later.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "service_unavailable: The service is temporarily unavailable. Please try again later.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } }, "post": { "summary": "Create a snapshot", "description": "Take a snapshot of a virtual server. Accepts optional `with_memory` (capture guest RAM — larger snapshot, brief freeze) and `quiesce` (ask the guest agent to flush pending I/O — requires a guest agent with quiesced-I/O support). Returns 202 + Action; the snapshot id is assigned asynchronously. Idempotency-Key required.", "tags": [ "Snapshots" ], "security": [ { "bearerAuth": [ "server:write" ] } ], "parameters": [ { "schema": { "type": "string", "description": "Server identifier, e.g. `XS-1023`.", "example": "XS-1023" }, "required": true, "description": "Server identifier, e.g. `XS-1023`.", "name": "name", "in": "path" }, { "schema": { "type": "string", "minLength": 1, "maxLength": 255, "description": "Client-supplied key (recommended: ULID). Same key + same body returns the cached response; different body returns `idempotency_conflict`. Stored for 24 h.", "example": "01HXYZABCDEFGHJKMNPQRSTVWX" }, "required": true, "description": "Client-supplied key (recommended: ULID). Same key + same body returns the cached response; different body returns `idempotency_conflict`. Stored for 24 h.", "name": "Idempotency-Key", "in": "header" }, { "schema": { "type": "string", "description": "One-shot proof from `POST /account/tfa/verify` (TOTP or Passkey). Required when the account has TFA enabled, unless `X-Tfa-Code` (or an inline `tfa_code` body field) is sent. Missing or invalid → 401 `tfa_required` / 422 `tfa_invalid`.", "example": "tfa_01HXYZABCDEFGHJKMNPQRSTVWX" }, "required": false, "description": "One-shot proof from `POST /account/tfa/verify` (TOTP or Passkey). Required when the account has TFA enabled, unless `X-Tfa-Code` (or an inline `tfa_code` body field) is sent. Missing or invalid → 401 `tfa_required` / 422 `tfa_invalid`.", "name": "X-Tfa-Token", "in": "header" }, { "schema": { "type": "string", "description": "Inline 6-digit TOTP code (Authenticator accounts only). `X-Tfa-Token` wins when both are present.", "example": "123456" }, "required": false, "description": "Inline 6-digit TOTP code (Authenticator accounts only). `X-Tfa-Token` wins when both are present.", "name": "X-Tfa-Code", "in": "header" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 80 }, "description": { "type": "string", "maxLength": 500 }, "with_memory": { "type": "boolean" }, "quiesce": { "type": "boolean" }, "tfa_code": { "type": "string" } }, "required": [ "name" ] } } } }, "responses": { "202": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "action": { "type": "object", "properties": { "id": { "type": "string" }, "command": { "type": "string" }, "status": { "type": "string", "enum": [ "running", "success", "error" ] }, "progress": { "type": "integer", "minimum": 0, "maximum": 100 }, "resources": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string" } }, "required": [ "id", "type" ] } }, "error": { "type": [ "object", "null" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] }, "started_at": { "type": "string" }, "finished_at": { "type": [ "string", "null" ] } }, "required": [ "id", "command", "status", "progress", "resources", "error", "started_at", "finished_at" ] }, "server": { "type": "object", "properties": { "name": { "type": "string" }, "type": { "type": "string", "enum": [ "virtual", "physical" ] }, "hostname": { "type": [ "string", "null" ] }, "status": { "type": "string", "enum": [ "new", "installing", "inventory", "active" ] }, "power_state": { "type": "string", "enum": [ "running", "stopped", "unknown" ] }, "location": { "type": "string" }, "os": { "type": "object", "properties": { "code": { "type": [ "string", "null" ] }, "name": { "type": [ "string", "null" ] }, "version": { "type": [ "string", "null" ] }, "family": { "type": [ "string", "null" ] } }, "required": [ "code", "name", "version", "family" ] }, "primary_ip": { "type": [ "string", "null" ] }, "ips": { "type": "array", "items": { "type": "string" } }, "ipv6": { "type": "array", "items": { "type": "string" } }, "config": { "type": "object", "properties": { "cpu": { "type": "integer", "minimum": 0 }, "ram": { "type": "integer", "minimum": 0 }, "ssd": { "type": "integer", "minimum": 0 }, "hdd": { "type": [ "integer", "null" ], "minimum": 0 }, "cpu_frequency": { "type": "number", "minimum": 0 }, "tier": { "type": "string", "enum": [ "standard", "high-perf" ] } }, "required": [ "cpu", "ram", "ssd", "hdd", "cpu_frequency", "tier" ] }, "expires_at": { "type": [ "string", "null" ] }, "autorenew": { "type": "boolean" }, "created_at": { "type": "string" } }, "required": [ "name", "type", "hostname", "status", "power_state", "location", "os", "primary_ip", "ips", "ipv6", "config", "expires_at", "autorenew", "created_at" ] } }, "required": [ "action", "server" ] } } } }, "401": { "description": "unauthorized: Authentication is required to access this resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "402": { "description": "insufficient_funds: Your account balance is insufficient for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "insufficient_scope | forbidden: Your token does not grant the required scope for this action. You do not have permission to access this resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "not_found: The requested resource was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "conflict | idempotency_conflict: The request conflicts with the current state of the resource. An earlier request with the same Idempotency-Key had a different body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "422": { "description": "invalid_input: The request contains invalid or missing fields.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "rate_limited: Too many requests. Please retry later.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "server_error: An unexpected error occurred. Please try again later.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "service_unavailable: The service is temporarily unavailable. Please try again later.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } } }, "/servers/{name}/snapshots/{id}": { "get": { "summary": "Get a snapshot", "tags": [ "Snapshots" ], "security": [ { "bearerAuth": [ "server:read" ] } ], "parameters": [ { "schema": { "type": "string", "description": "Server identifier, e.g. `XS-1023`.", "example": "XS-1023" }, "required": true, "description": "Server identifier, e.g. `XS-1023`.", "name": "name", "in": "path" }, { "schema": { "type": "string", "description": "Snapshot id." }, "required": true, "description": "Snapshot id.", "name": "id", "in": "path" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "snapshot": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "server_name": { "type": "string" }, "created_at": { "type": "string" }, "size_bytes": { "type": [ "integer", "null" ] }, "parent_id": { "type": [ "string", "null" ] }, "state": { "type": "string", "enum": [ "created", "current", "old" ] }, "quiesced": { "type": "boolean" }, "with_memory": { "type": "boolean" } }, "required": [ "id", "name", "description", "server_name", "created_at", "size_bytes", "parent_id", "state", "quiesced", "with_memory" ] } }, "required": [ "snapshot" ] } } } }, "401": { "description": "unauthorized: Authentication is required to access this resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "insufficient_scope: Your token does not grant the required scope for this action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "not_found: The requested resource was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "conflict: The request conflicts with the current state of the resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "rate_limited: Too many requests. Please retry later.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "server_error: An unexpected error occurred. Please try again later.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "service_unavailable: The service is temporarily unavailable. Please try again later.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } }, "delete": { "summary": "Delete a snapshot", "description": "Remove a snapshot. Pass `?remove_children=true` to also remove every descendant in the snapshot tree (destructive). TFA code must be supplied in the `X-Tfa-Code` header when the account has TFA enabled (DELETE bodies are poorly supported by proxies). Returns 202 + Action.", "tags": [ "Snapshots" ], "security": [ { "bearerAuth": [ "server:write" ] } ], "parameters": [ { "schema": { "type": "string", "description": "Server identifier, e.g. `XS-1023`.", "example": "XS-1023" }, "required": true, "description": "Server identifier, e.g. `XS-1023`.", "name": "name", "in": "path" }, { "schema": { "type": "string", "description": "Snapshot id." }, "required": true, "description": "Snapshot id.", "name": "id", "in": "path" }, { "schema": { "type": "string", "enum": [ "true", "false" ] }, "required": false, "name": "remove_children", "in": "query" }, { "schema": { "type": "string", "minLength": 1, "maxLength": 255, "description": "Client-supplied key (recommended: ULID). Same key + same body returns the cached response; different body returns `idempotency_conflict`. Stored for 24 h.", "example": "01HXYZABCDEFGHJKMNPQRSTVWX" }, "required": true, "description": "Client-supplied key (recommended: ULID). Same key + same body returns the cached response; different body returns `idempotency_conflict`. Stored for 24 h.", "name": "Idempotency-Key", "in": "header" }, { "schema": { "type": "string", "description": "One-shot proof from `POST /account/tfa/verify` (TOTP or Passkey). Required when the account has TFA enabled, unless `X-Tfa-Code` (or an inline `tfa_code` body field) is sent. Missing or invalid → 401 `tfa_required` / 422 `tfa_invalid`.", "example": "tfa_01HXYZABCDEFGHJKMNPQRSTVWX" }, "required": false, "description": "One-shot proof from `POST /account/tfa/verify` (TOTP or Passkey). Required when the account has TFA enabled, unless `X-Tfa-Code` (or an inline `tfa_code` body field) is sent. Missing or invalid → 401 `tfa_required` / 422 `tfa_invalid`.", "name": "X-Tfa-Token", "in": "header" }, { "schema": { "type": "string", "description": "Inline 6-digit TOTP code (Authenticator accounts only). `X-Tfa-Token` wins when both are present.", "example": "123456" }, "required": false, "description": "Inline 6-digit TOTP code (Authenticator accounts only). `X-Tfa-Token` wins when both are present.", "name": "X-Tfa-Code", "in": "header" } ], "responses": { "202": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "action": { "type": "object", "properties": { "id": { "type": "string" }, "command": { "type": "string" }, "status": { "type": "string", "enum": [ "running", "success", "error" ] }, "progress": { "type": "integer", "minimum": 0, "maximum": 100 }, "resources": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string" } }, "required": [ "id", "type" ] } }, "error": { "type": [ "object", "null" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] }, "started_at": { "type": "string" }, "finished_at": { "type": [ "string", "null" ] } }, "required": [ "id", "command", "status", "progress", "resources", "error", "started_at", "finished_at" ] }, "server": { "type": "object", "properties": { "name": { "type": "string" }, "type": { "type": "string", "enum": [ "virtual", "physical" ] }, "hostname": { "type": [ "string", "null" ] }, "status": { "type": "string", "enum": [ "new", "installing", "inventory", "active" ] }, "power_state": { "type": "string", "enum": [ "running", "stopped", "unknown" ] }, "location": { "type": "string" }, "os": { "type": "object", "properties": { "code": { "type": [ "string", "null" ] }, "name": { "type": [ "string", "null" ] }, "version": { "type": [ "string", "null" ] }, "family": { "type": [ "string", "null" ] } }, "required": [ "code", "name", "version", "family" ] }, "primary_ip": { "type": [ "string", "null" ] }, "ips": { "type": "array", "items": { "type": "string" } }, "ipv6": { "type": "array", "items": { "type": "string" } }, "config": { "type": "object", "properties": { "cpu": { "type": "integer", "minimum": 0 }, "ram": { "type": "integer", "minimum": 0 }, "ssd": { "type": "integer", "minimum": 0 }, "hdd": { "type": [ "integer", "null" ], "minimum": 0 }, "cpu_frequency": { "type": "number", "minimum": 0 }, "tier": { "type": "string", "enum": [ "standard", "high-perf" ] } }, "required": [ "cpu", "ram", "ssd", "hdd", "cpu_frequency", "tier" ] }, "expires_at": { "type": [ "string", "null" ] }, "autorenew": { "type": "boolean" }, "created_at": { "type": "string" } }, "required": [ "name", "type", "hostname", "status", "power_state", "location", "os", "primary_ip", "ips", "ipv6", "config", "expires_at", "autorenew", "created_at" ] } }, "required": [ "action", "server" ] } } } }, "401": { "description": "unauthorized: Authentication is required to access this resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "402": { "description": "insufficient_funds: Your account balance is insufficient for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "insufficient_scope | forbidden: Your token does not grant the required scope for this action. You do not have permission to access this resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "not_found: The requested resource was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "conflict | idempotency_conflict: The request conflicts with the current state of the resource. An earlier request with the same Idempotency-Key had a different body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "422": { "description": "invalid_input: The request contains invalid or missing fields.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "rate_limited: Too many requests. Please retry later.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "server_error: An unexpected error occurred. Please try again later.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "service_unavailable: The service is temporarily unavailable. Please try again later.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } } }, "/servers/{name}/snapshots/{id}/revert": { "post": { "summary": "Revert to a snapshot", "description": "Roll the server back to the chosen snapshot. Destructive — changes after the snapshot are discarded. TFA required when enabled on the account. Idempotency-Key required.", "tags": [ "Snapshots" ], "security": [ { "bearerAuth": [ "server:write" ] } ], "parameters": [ { "schema": { "type": "string", "description": "Server identifier, e.g. `XS-1023`.", "example": "XS-1023" }, "required": true, "description": "Server identifier, e.g. `XS-1023`.", "name": "name", "in": "path" }, { "schema": { "type": "string", "description": "Snapshot id." }, "required": true, "description": "Snapshot id.", "name": "id", "in": "path" }, { "schema": { "type": "string", "minLength": 1, "maxLength": 255, "description": "Client-supplied key (recommended: ULID). Same key + same body returns the cached response; different body returns `idempotency_conflict`. Stored for 24 h.", "example": "01HXYZABCDEFGHJKMNPQRSTVWX" }, "required": true, "description": "Client-supplied key (recommended: ULID). Same key + same body returns the cached response; different body returns `idempotency_conflict`. Stored for 24 h.", "name": "Idempotency-Key", "in": "header" }, { "schema": { "type": "string", "description": "One-shot proof from `POST /account/tfa/verify` (TOTP or Passkey). Required when the account has TFA enabled, unless `X-Tfa-Code` (or an inline `tfa_code` body field) is sent. Missing or invalid → 401 `tfa_required` / 422 `tfa_invalid`.", "example": "tfa_01HXYZABCDEFGHJKMNPQRSTVWX" }, "required": false, "description": "One-shot proof from `POST /account/tfa/verify` (TOTP or Passkey). Required when the account has TFA enabled, unless `X-Tfa-Code` (or an inline `tfa_code` body field) is sent. Missing or invalid → 401 `tfa_required` / 422 `tfa_invalid`.", "name": "X-Tfa-Token", "in": "header" }, { "schema": { "type": "string", "description": "Inline 6-digit TOTP code (Authenticator accounts only). `X-Tfa-Token` wins when both are present.", "example": "123456" }, "required": false, "description": "Inline 6-digit TOTP code (Authenticator accounts only). `X-Tfa-Token` wins when both are present.", "name": "X-Tfa-Code", "in": "header" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "tfa_code": { "type": "string" } } } } } }, "responses": { "202": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "action": { "type": "object", "properties": { "id": { "type": "string" }, "command": { "type": "string" }, "status": { "type": "string", "enum": [ "running", "success", "error" ] }, "progress": { "type": "integer", "minimum": 0, "maximum": 100 }, "resources": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string" } }, "required": [ "id", "type" ] } }, "error": { "type": [ "object", "null" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] }, "started_at": { "type": "string" }, "finished_at": { "type": [ "string", "null" ] } }, "required": [ "id", "command", "status", "progress", "resources", "error", "started_at", "finished_at" ] }, "server": { "type": "object", "properties": { "name": { "type": "string" }, "type": { "type": "string", "enum": [ "virtual", "physical" ] }, "hostname": { "type": [ "string", "null" ] }, "status": { "type": "string", "enum": [ "new", "installing", "inventory", "active" ] }, "power_state": { "type": "string", "enum": [ "running", "stopped", "unknown" ] }, "location": { "type": "string" }, "os": { "type": "object", "properties": { "code": { "type": [ "string", "null" ] }, "name": { "type": [ "string", "null" ] }, "version": { "type": [ "string", "null" ] }, "family": { "type": [ "string", "null" ] } }, "required": [ "code", "name", "version", "family" ] }, "primary_ip": { "type": [ "string", "null" ] }, "ips": { "type": "array", "items": { "type": "string" } }, "ipv6": { "type": "array", "items": { "type": "string" } }, "config": { "type": "object", "properties": { "cpu": { "type": "integer", "minimum": 0 }, "ram": { "type": "integer", "minimum": 0 }, "ssd": { "type": "integer", "minimum": 0 }, "hdd": { "type": [ "integer", "null" ], "minimum": 0 }, "cpu_frequency": { "type": "number", "minimum": 0 }, "tier": { "type": "string", "enum": [ "standard", "high-perf" ] } }, "required": [ "cpu", "ram", "ssd", "hdd", "cpu_frequency", "tier" ] }, "expires_at": { "type": [ "string", "null" ] }, "autorenew": { "type": "boolean" }, "created_at": { "type": "string" } }, "required": [ "name", "type", "hostname", "status", "power_state", "location", "os", "primary_ip", "ips", "ipv6", "config", "expires_at", "autorenew", "created_at" ] } }, "required": [ "action", "server" ] } } } }, "401": { "description": "unauthorized: Authentication is required to access this resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "402": { "description": "insufficient_funds: Your account balance is insufficient for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "insufficient_scope | forbidden: Your token does not grant the required scope for this action. You do not have permission to access this resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "not_found: The requested resource was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "conflict | idempotency_conflict: The request conflicts with the current state of the resource. An earlier request with the same Idempotency-Key had a different body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "422": { "description": "invalid_input: The request contains invalid or missing fields.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "rate_limited: Too many requests. Please retry later.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "server_error: An unexpected error occurred. Please try again later.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "service_unavailable: The service is temporarily unavailable. Please try again later.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } } }, "/servers/{name}/renew/preview": { "get": { "summary": "Preview a server renewal", "description": "The price of renewing the server for `months` (1–12) or up to `to` — exactly one of the two — with the prepayment discount, the funds the renewal may spend (`balance`, `bonus`, `spendable` = balance + bonus when `use_bonus=true`; the credit limit never counts) and the open renewal invoices a renewal would cancel (`conflicts`). Read-only.", "tags": [ "Previews" ], "security": [ { "bearerAuth": [ "server:read", "billing:read" ] } ], "parameters": [ { "schema": { "type": "string", "description": "Server identifier, e.g. `XS-1023`.", "example": "XS-1023" }, "required": true, "description": "Server identifier, e.g. `XS-1023`.", "name": "name", "in": "path" }, { "schema": { "type": "integer", "minimum": 1, "maximum": 12 }, "required": false, "name": "months", "in": "query" }, { "schema": { "type": "string" }, "required": false, "name": "to", "in": "query" }, { "schema": { "type": "string", "enum": [ "true", "false" ] }, "required": false, "name": "use_bonus", "in": "query" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "preview": { "type": "object", "properties": { "current_expire": { "type": "string" }, "new_expire": { "type": "string" }, "days": { "type": "integer" }, "price": { "type": "number" }, "gross_price": { "type": "number" }, "discount_percent": { "type": "number" }, "currency": { "type": "string" }, "balance": { "type": "number" }, "bonus": { "type": "number" }, "spendable": { "type": "number" }, "affordable": { "type": "boolean" }, "conflicts": { "type": "array", "items": { "type": "object", "properties": { "invoice_id": { "type": "string" }, "total": { "type": "number" }, "currency": { "type": "string" }, "due_at": { "type": [ "string", "null" ] }, "server_names": { "type": "array", "items": { "type": "string" } }, "all_server_names": { "type": "array", "items": { "type": "string" } } }, "required": [ "invoice_id", "total", "currency", "due_at", "server_names", "all_server_names" ] } } }, "required": [ "current_expire", "new_expire", "days", "price", "gross_price", "discount_percent", "currency", "balance", "bonus", "spendable", "affordable", "conflicts" ] } }, "required": [ "preview" ] } } } }, "401": { "description": "unauthorized: Authentication is required to access this resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "insufficient_scope: Your token does not grant the required scope for this action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "not_found: The requested resource was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "422": { "description": "invalid_input: The request contains invalid or missing fields.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "rate_limited: Too many requests. Please retry later.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "server_error: An unexpected error occurred. Please try again later.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } } }, "/servers/{name}/cancel/preview": { "get": { "summary": "Preview a server cancellation", "description": "Dry-run companion to `DELETE /servers/{name}`. Returns the refund amount, effect list, and `requires_tfa` flag the destructive call would produce. Supports `?mode=immediate|on_expiry` (default `on_expiry`). No state is mutated.", "tags": [ "Previews" ], "security": [ { "bearerAuth": [ "server:read" ] } ], "parameters": [ { "schema": { "type": "string", "description": "Server identifier, e.g. `XS-1023`.", "example": "XS-1023" }, "required": true, "description": "Server identifier, e.g. `XS-1023`.", "name": "name", "in": "path" }, { "schema": { "type": "string", "enum": [ "immediate", "on_expiry" ] }, "required": false, "name": "mode", "in": "query" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "preview": { "type": "object", "properties": { "action_path": { "type": "string" }, "requires_tfa": { "type": "boolean" }, "financials": { "type": "object", "properties": { "direction": { "type": "string", "enum": [ "refund", "charge", "none" ] }, "amount": { "type": [ "number", "null" ] }, "currency": { "type": "string" }, "days_unused": { "type": [ "integer", "null" ] }, "days_total": { "type": [ "integer", "null" ] }, "breakdown": { "type": "array", "items": { "type": "object", "properties": { "kind": { "type": "string" }, "target": { "type": [ "string", "null" ] }, "amount": { "type": [ "number", "null" ] } }, "required": [ "kind", "target", "amount" ] } } }, "required": [ "direction", "amount", "currency", "days_unused", "days_total" ] }, "effects": { "type": "array", "items": { "type": "object", "properties": { "kind": { "type": "string" }, "target": { "type": [ "string", "null" ] }, "count": { "type": "integer" }, "note": { "type": "string" } }, "required": [ "kind", "target" ] } }, "cancel": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "immediate", "on_expiry" ] }, "refund_to": { "type": "string", "enum": [ "balance" ] } }, "required": [ "mode", "refund_to" ] } }, "required": [ "action_path", "requires_tfa", "financials", "effects", "cancel" ], "additionalProperties": {} } }, "required": [ "preview" ] } } } }, "401": { "description": "unauthorized: Authentication is required to access this resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "insufficient_scope: Your token does not grant the required scope for this action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "not_found: The requested resource was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "422": { "description": "invalid_input: The request contains invalid or missing fields.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "rate_limited: Too many requests. Please retry later.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "server_error: An unexpected error occurred. Please try again later.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } } }, "/servers/{name}/resize/preview": { "get": { "summary": "Preview a server resize", "description": "Dry-run companion to `POST /servers/{name}/resize`. Returns the prorated delta (positive = charge, negative = refund), the old/new monthly prices, and a `poweroff_required` flag. At least one of `cpu` / `ram` / `ssd` / `hdd` must be supplied in the query — all sizes in whole GB.", "tags": [ "Previews" ], "security": [ { "bearerAuth": [ "server:read" ] } ], "parameters": [ { "schema": { "type": "string", "description": "Server identifier, e.g. `XS-1023`.", "example": "XS-1023" }, "required": true, "description": "Server identifier, e.g. `XS-1023`.", "name": "name", "in": "path" }, { "schema": { "type": "integer", "minimum": 1, "maximum": 64 }, "required": false, "name": "cpu", "in": "query" }, { "schema": { "type": "integer", "minimum": 1 }, "required": false, "name": "ram", "in": "query" }, { "schema": { "type": "integer", "minimum": 10 }, "required": false, "name": "ssd", "in": "query" }, { "schema": { "type": [ "integer", "null" ], "minimum": 0 }, "required": false, "name": "hdd", "in": "query" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "preview": { "type": "object", "properties": { "action_path": { "type": "string" }, "requires_tfa": { "type": "boolean" }, "financials": { "type": "object", "properties": { "direction": { "type": "string", "enum": [ "refund", "charge", "none" ] }, "amount": { "type": [ "number", "null" ] }, "currency": { "type": "string" }, "days_unused": { "type": [ "integer", "null" ] }, "days_total": { "type": [ "integer", "null" ] }, "breakdown": { "type": "array", "items": { "type": "object", "properties": { "kind": { "type": "string" }, "target": { "type": [ "string", "null" ] }, "amount": { "type": [ "number", "null" ] } }, "required": [ "kind", "target", "amount" ] } } }, "required": [ "direction", "amount", "currency", "days_unused", "days_total" ] }, "effects": { "type": "array", "items": { "type": "object", "properties": { "kind": { "type": "string" }, "target": { "type": [ "string", "null" ] }, "count": { "type": "integer" }, "note": { "type": "string" } }, "required": [ "kind", "target" ] } }, "resize": { "type": "object", "properties": { "old_config": { "type": "object", "properties": { "cpu": { "type": "integer" }, "ram": { "type": "integer" }, "ssd": { "type": "integer" }, "hdd": { "type": "integer" } }, "required": [ "cpu", "ram", "ssd", "hdd" ] }, "new_config": { "type": "object", "properties": { "cpu": { "type": "integer" }, "ram": { "type": "integer" }, "ssd": { "type": "integer" }, "hdd": { "type": "integer" } }, "required": [ "cpu", "ram", "ssd", "hdd" ] }, "old_monthly_price": { "type": [ "number", "null" ] }, "new_monthly_price": { "type": [ "number", "null" ] }, "poweroff_required": { "type": "boolean" }, "delta_breakdown": { "type": "array", "items": { "type": "object", "properties": { "kind": { "type": "string" }, "amount": { "type": [ "number", "null" ] }, "note": { "type": "string" } }, "required": [ "kind", "amount" ] } } }, "required": [ "old_config", "new_config", "old_monthly_price", "new_monthly_price", "poweroff_required" ] } }, "required": [ "action_path", "requires_tfa", "financials", "effects", "resize" ], "additionalProperties": {} } }, "required": [ "preview" ] } } } }, "401": { "description": "unauthorized: Authentication is required to access this resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "insufficient_scope: Your token does not grant the required scope for this action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "not_found: The requested resource was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "422": { "description": "invalid_input: The request contains invalid or missing fields.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "rate_limited: Too many requests. Please retry later.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "server_error: An unexpected error occurred. Please try again later.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } } }, "/servers/{name}/ips/preview": { "get": { "summary": "Preview IP address allocation", "description": "Dry-run companion to `POST /servers/{name}/ips`. Returns the prorated charge for allocating the requested mix of IPv4 and/or IPv6 addresses, using the server location's pricing and the discount tier the server is already on.", "tags": [ "Previews" ], "security": [ { "bearerAuth": [ "server:read" ] } ], "parameters": [ { "schema": { "type": "string", "description": "Server identifier, e.g. `XS-1023`.", "example": "XS-1023" }, "required": true, "description": "Server identifier, e.g. `XS-1023`.", "name": "name", "in": "path" }, { "schema": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 8 }, "required": false, "name": "ipv4", "in": "query" }, { "schema": { "type": "boolean" }, "required": false, "name": "ipv6", "in": "query" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "preview": { "type": "object", "properties": { "action_path": { "type": "string" }, "requires_tfa": { "type": "boolean" }, "financials": { "type": "object", "properties": { "direction": { "type": "string", "enum": [ "refund", "charge", "none" ] }, "amount": { "type": [ "number", "null" ] }, "currency": { "type": "string" }, "days_unused": { "type": [ "integer", "null" ] }, "days_total": { "type": [ "integer", "null" ] }, "breakdown": { "type": "array", "items": { "type": "object", "properties": { "kind": { "type": "string" }, "target": { "type": [ "string", "null" ] }, "amount": { "type": [ "number", "null" ] } }, "required": [ "kind", "target", "amount" ] } } }, "required": [ "direction", "amount", "currency", "days_unused", "days_total" ] }, "effects": { "type": "array", "items": { "type": "object", "properties": { "kind": { "type": "string" }, "target": { "type": [ "string", "null" ] }, "count": { "type": "integer" }, "note": { "type": "string" } }, "required": [ "kind", "target" ] } }, "ips": { "type": "object", "properties": { "ipv4_count": { "type": "integer", "minimum": 0 }, "ipv6": { "type": "boolean" }, "unit_price_v4": { "type": [ "number", "null" ] }, "unit_price_v6": { "type": [ "number", "null" ] }, "prorated_multiplier": { "type": "number" }, "discount_percent": { "type": "integer", "minimum": 0 } }, "required": [ "ipv4_count", "ipv6", "unit_price_v4", "unit_price_v6", "prorated_multiplier", "discount_percent" ] } }, "required": [ "action_path", "requires_tfa", "financials", "effects", "ips" ], "additionalProperties": {} } }, "required": [ "preview" ] } } } }, "401": { "description": "unauthorized: Authentication is required to access this resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "insufficient_scope: Your token does not grant the required scope for this action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "not_found: The requested resource was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "conflict: The request conflicts with the current state of the resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "422": { "description": "invalid_input: The request contains invalid or missing fields.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "rate_limited: Too many requests. Please retry later.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "server_error: An unexpected error occurred. Please try again later.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } } }, "/servers/{name}/services/preview": { "post": { "summary": "Preview a server service attachment", "description": "Dry-run companion to `POST /servers/{name}/services`. Body is `{ code }`. An add-on has no term of its own: it is prorated to the server's expiry and renews with the server, so the charge is `monthly_price × prorated_multiplier` less the discount tier of the remaining full months. When the server is expired (or expires today) the preview shows `direction: \"none\"`, `amount: 0` — the add-on attaches as `pending` and activates with the next renewal.", "tags": [ "Previews" ], "security": [ { "bearerAuth": [ "server:read" ] } ], "parameters": [ { "schema": { "type": "string", "description": "Server identifier, e.g. `XS-1023`.", "example": "XS-1023" }, "required": true, "description": "Server identifier, e.g. `XS-1023`.", "name": "name", "in": "path" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string", "minLength": 1, "maxLength": 60 } }, "required": [ "code" ] } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "preview": { "type": "object", "properties": { "action_path": { "type": "string" }, "requires_tfa": { "type": "boolean" }, "financials": { "type": "object", "properties": { "direction": { "type": "string", "enum": [ "refund", "charge", "none" ] }, "amount": { "type": [ "number", "null" ] }, "currency": { "type": "string" }, "days_unused": { "type": [ "integer", "null" ] }, "days_total": { "type": [ "integer", "null" ] }, "breakdown": { "type": "array", "items": { "type": "object", "properties": { "kind": { "type": "string" }, "target": { "type": [ "string", "null" ] }, "amount": { "type": [ "number", "null" ] } }, "required": [ "kind", "target", "amount" ] } } }, "required": [ "direction", "amount", "currency", "days_unused", "days_total" ] }, "effects": { "type": "array", "items": { "type": "object", "properties": { "kind": { "type": "string" }, "target": { "type": [ "string", "null" ] }, "count": { "type": "integer" }, "note": { "type": "string" } }, "required": [ "kind", "target" ] } }, "service": { "type": "object", "properties": { "code": { "type": "string" }, "name": { "type": "string" }, "monthly_price": { "type": [ "number", "null" ] }, "prorated_charge": { "type": [ "number", "null" ] }, "prorated_multiplier": { "type": "number" }, "discount_percent": { "type": "integer", "minimum": 0 } }, "required": [ "code", "name", "monthly_price", "prorated_charge", "prorated_multiplier", "discount_percent" ] } }, "required": [ "action_path", "requires_tfa", "financials", "effects", "service" ], "additionalProperties": {} } }, "required": [ "preview" ] } } } }, "401": { "description": "unauthorized: Authentication is required to access this resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "insufficient_scope: Your token does not grant the required scope for this action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "not_found: The requested resource was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "422": { "description": "invalid_input: The request contains invalid or missing fields.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "rate_limited: Too many requests. Please retry later.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "server_error: An unexpected error occurred. Please try again later.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } } }, "/orders/preview": { "post": { "summary": "Preview a new-server order", "description": "Dry-run companion to `POST /orders`. Body is the same `CreateOrderInput`. Returns the computed totals (base price, period multiplier, tiered discount, services breakdown) without creating an invoice.", "tags": [ "Previews" ], "security": [ { "bearerAuth": [ "billing:read" ] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "server_type": { "type": "string", "enum": [ "virtual", "physical" ], "default": "virtual" }, "tier": { "type": "string", "enum": [ "standard", "hiperf" ], "default": "standard" }, "cpu": { "type": "integer", "minimum": 1, "maximum": 64 }, "ram": { "type": "integer", "minimum": 1, "maximum": 256 }, "ssd": { "type": "integer", "minimum": 10, "maximum": 2000 }, "hdd": { "type": "integer", "minimum": 0, "maximum": 8000, "default": 0 }, "location_code": { "type": "string", "minLength": 1, "maxLength": 10 }, "locations": { "type": "array", "items": { "type": "object", "properties": { "location_code": { "type": "string", "minLength": 1, "maxLength": 10 }, "quantity": { "type": "integer", "minimum": 1, "maximum": 10, "default": 1 } }, "required": [ "location_code" ] }, "minItems": 1, "maxItems": 10 }, "os_template_code": { "type": "string", "minLength": 1, "maxLength": 60 }, "hostname": { "type": "string", "minLength": 1, "maxLength": 253 }, "ssh_key_ids": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 40 }, "maxItems": 10 }, "password": { "type": "string", "minLength": 6, "maxLength": 128 }, "ipv4": { "type": "integer", "minimum": 1, "maximum": 8, "default": 1 }, "ipv6": { "type": "boolean", "default": false }, "services": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 40 }, "quantity": { "type": "number", "enum": [ 1 ], "default": 1 } }, "required": [ "id" ] }, "maxItems": 10 }, "period_months": { "anyOf": [ { "type": "number", "enum": [ 1 ] }, { "type": "number", "enum": [ 2 ] }, { "type": "number", "enum": [ 3 ] }, { "type": "number", "enum": [ 6 ] }, { "type": "number", "enum": [ 12 ] } ], "default": 1 }, "auto_renew": { "type": "boolean", "default": true }, "promo_code": { "type": "string", "maxLength": 40 }, "note": { "type": "string", "maxLength": 500 }, "physical_server_id": { "type": "string", "minLength": 1, "maxLength": 40 } }, "required": [ "os_template_code" ] } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "preview": { "type": "object", "properties": { "action_path": { "type": "string" }, "requires_tfa": { "type": "boolean" }, "financials": { "type": "object", "properties": { "direction": { "type": "string", "enum": [ "refund", "charge", "none" ] }, "amount": { "type": [ "number", "null" ] }, "currency": { "type": "string" }, "days_unused": { "type": [ "integer", "null" ] }, "days_total": { "type": [ "integer", "null" ] }, "breakdown": { "type": "array", "items": { "type": "object", "properties": { "kind": { "type": "string" }, "target": { "type": [ "string", "null" ] }, "amount": { "type": [ "number", "null" ] } }, "required": [ "kind", "target", "amount" ] } } }, "required": [ "direction", "amount", "currency", "days_unused", "days_total" ] }, "effects": { "type": "array", "items": { "type": "object", "properties": { "kind": { "type": "string" }, "target": { "type": [ "string", "null" ] }, "count": { "type": "integer" }, "note": { "type": "string" } }, "required": [ "kind", "target" ] } }, "order": { "type": "object", "properties": { "server_type": { "type": "string", "enum": [ "virtual", "physical" ] }, "tier": { "type": [ "string", "null" ], "enum": [ "standard", "hiperf", null ] }, "config": { "type": [ "object", "null" ], "properties": { "cpu": { "type": [ "integer", "null" ] }, "ram": { "type": [ "integer", "null" ] }, "ssd": { "type": [ "integer", "null" ] }, "hdd": { "type": [ "integer", "null" ] } }, "required": [ "cpu", "ram", "ssd", "hdd" ] }, "locations": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string" }, "quantity": { "type": "integer", "minimum": 1 } }, "required": [ "code", "quantity" ] } }, "period_months": { "type": "integer" }, "base_price": { "type": [ "number", "null" ] }, "discount_percent": { "type": "integer", "minimum": 0 }, "gross_total": { "type": [ "number", "null" ] }, "total": { "type": [ "number", "null" ] }, "quantity": { "type": "integer", "exclusiveMinimum": 0 }, "promo": { "type": [ "object", "null" ], "properties": { "code": { "type": "string" }, "discount_percent": { "type": "number" }, "discount": { "type": [ "number", "null" ] } }, "required": [ "code", "discount_percent", "discount" ] }, "services_breakdown": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string" }, "quantity": { "type": "integer", "exclusiveMinimum": 0 }, "monthly_price": { "type": [ "number", "null" ] } }, "required": [ "code", "quantity", "monthly_price" ] } } }, "required": [ "server_type", "tier", "config", "locations", "period_months", "base_price", "discount_percent", "gross_total", "total", "quantity" ] } }, "required": [ "action_path", "requires_tfa", "financials", "effects", "order" ], "additionalProperties": {} } }, "required": [ "preview" ] } } } }, "401": { "description": "unauthorized: Authentication is required to access this resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "insufficient_scope: Your token does not grant the required scope for this action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "not_found: The requested resource was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "422": { "description": "invalid_input: The request contains invalid or missing fields.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "rate_limited: Too many requests. Please retry later.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "server_error: An unexpected error occurred. Please try again later.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } } } }, "webhooks": {} }