{"openapi":"3.1.0","info":{"title":"Partner API","version":"1.0.0","description":"HTTP API for provisioning virtual servers, managing server operations and retrieving usage. Requests use bearer authentication. Request and response bodies use JSON."},"servers":[{"url":"https://enterprise.chartvps.com/v1","description":"API base URL"}],"x-endpoint-configured":true,"security":[{"bearer":[]}],"tags":[{"name":"Account"},{"name":"Catalog"},{"name":"Servers"},{"name":"SSH keys"},{"name":"Backups"},{"name":"Tasks"},{"name":"Events"},{"name":"Webhooks"},{"name":"Billing"}],"paths":{"/me":{"get":{"tags":["Account"],"summary":"Retrieve account details","description":"Returns account status, server quotas, concurrent provisioning limits and credit availability for the authenticated account.","responses":{"200":{"description":"Account details.","content":{"application/json":{"schema":{"type":"object","properties":{"partner":{"type":"object","properties":{"id":{"type":"integer"},"status":{"type":"string","enum":["active","frozen","suspended"]},"tenant_key":{"type":"string"}},"required":["id","status","tenant_key"],"additionalProperties":false},"inflight":{"type":"object","properties":{"current":{"type":"integer"},"max":{"type":"integer"}},"required":["current","max"],"additionalProperties":false},"servers":{"type":"object","properties":{"count":{"type":"integer"},"max":{"anyOf":[{"type":"integer"},{"type":"null"}]}},"required":["count","max"],"additionalProperties":false},"limits":{"type":"object","properties":{"max_inflight":{"type":"integer"},"max_servers":{"anyOf":[{"type":"integer"},{"type":"null"}]},"credit_limit":{"type":["string","null"]}},"required":["max_inflight","max_servers","credit_limit"],"additionalProperties":false},"credit":{"type":"object","properties":{"limit":{"type":["string","null"],"description":"Credit limit; null = no limit"},"unbilled":{"type":["string","null"],"description":"Current usage + closed uninvoiced usage + open invoice balances - free credit, floored at 0; null while billing data is degraded"},"available":{"type":["string","null"],"description":"limit - unbilled; creates are refused with 402 CREDIT_LIMIT at 0"},"breakdown":{"type":"object","properties":{"usage_month_to_date":{"type":["string","null"]},"closed_uninvoiced":{"type":["string","null"]},"open_invoices":{"type":["string","null"]},"credit_balance":{"type":["string","null"]}},"required":["usage_month_to_date","closed_uninvoiced","open_invoices","credit_balance"],"additionalProperties":false},"degraded":{"type":"boolean","description":"True when current billing data is unavailable. Credit availability is treated as zero until recovery."},"as_of":{"type":"string"},"snapshot_as_of":{"type":["string","null"],"description":"Native financial snapshot time; null while degraded"}},"required":["limit","unbilled","available","breakdown","degraded","as_of","snapshot_as_of"],"additionalProperties":false},"key":{"type":"object","properties":{"key_id":{"type":"string"},"label":{"type":["string","null"]}},"required":["key_id","label"],"additionalProperties":false}},"required":["partner","inflight","servers","limits","credit","key"],"additionalProperties":false},"example":{"partner":{"id":42,"status":"active","tenant_key":"partner-42"},"inflight":{"current":0,"max":20},"servers":{"count":1,"max":300},"limits":{"max_inflight":20,"max_servers":300,"credit_limit":"1000.00"},"credit":{"limit":"1000.00","unbilled":"2.40","available":"997.60","breakdown":{"usage_month_to_date":"2.40","closed_uninvoiced":"0.00","open_invoices":"0.00","credit_balance":"0.00"},"degraded":false,"as_of":"2026-09-10T00:00:00.000Z","snapshot_as_of":"2026-09-10T00:00:00.000Z"},"key":{"key_id":"a1b2c3d4e5f6","label":"Provisioning integration"}}}},"headers":{"X-Request-Id":{"description":"Request identifier. Include this value when contacting support.","schema":{"type":"string"}}}},"401":{"description":"Authentication failed. The API key is missing, invalid or revoked, or API access is not approved.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["UNAUTHENTICATED","FORBIDDEN","NETWORK_RESTRICTED","FROZEN","PARTNER_SUSPENDED","QUOTA","NOT_FOUND","VALIDATION","CONFLICT","IDEMPOTENCY_MISMATCH","CREDIT_LIMIT","INFLIGHT_LIMIT","RATE_LIMITED","KEY_LIMIT","UPSTREAM","STORE_BUSY","STORE_UNAVAILABLE","MAINTENANCE","BAD_REQUEST","INTERNAL"]},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}},"headers":{"X-Request-Id":{"description":"Request identifier. Include this value when contacting support.","schema":{"type":"string"}},"WWW-Authenticate":{"description":"Bearer authentication challenge.","schema":{"type":"string"}}}},"403":{"description":"NETWORK_RESTRICTED: the request source is outside this deployment's approved IP networks.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["UNAUTHENTICATED","FORBIDDEN","NETWORK_RESTRICTED","FROZEN","PARTNER_SUSPENDED","QUOTA","NOT_FOUND","VALIDATION","CONFLICT","IDEMPOTENCY_MISMATCH","CREDIT_LIMIT","INFLIGHT_LIMIT","RATE_LIMITED","KEY_LIMIT","UPSTREAM","STORE_BUSY","STORE_UNAVAILABLE","MAINTENANCE","BAD_REQUEST","INTERNAL"]},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}},"headers":{"X-Request-Id":{"description":"Request identifier. Include this value when contacting support.","schema":{"type":"string"}}}},"429":{"description":"Rate limit exceeded. See Retry-After before retrying.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["UNAUTHENTICATED","FORBIDDEN","NETWORK_RESTRICTED","FROZEN","PARTNER_SUSPENDED","QUOTA","NOT_FOUND","VALIDATION","CONFLICT","IDEMPOTENCY_MISMATCH","CREDIT_LIMIT","INFLIGHT_LIMIT","RATE_LIMITED","KEY_LIMIT","UPSTREAM","STORE_BUSY","STORE_UNAVAILABLE","MAINTENANCE","BAD_REQUEST","INTERNAL"]},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}},"headers":{"X-Request-Id":{"description":"Request identifier. Include this value when contacting support.","schema":{"type":"string"}},"Retry-After":{"description":"Minimum delay in seconds before retrying, when present. Some dependency failures omit this header; use exponential backoff with jitter.","schema":{"type":"integer"}}}},"500":{"description":"INTERNAL: unexpected server error. Retain X-Request-Id for support; resolve the outcome before repeating a write.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["UNAUTHENTICATED","FORBIDDEN","NETWORK_RESTRICTED","FROZEN","PARTNER_SUSPENDED","QUOTA","NOT_FOUND","VALIDATION","CONFLICT","IDEMPOTENCY_MISMATCH","CREDIT_LIMIT","INFLIGHT_LIMIT","RATE_LIMITED","KEY_LIMIT","UPSTREAM","STORE_BUSY","STORE_UNAVAILABLE","MAINTENANCE","BAD_REQUEST","INTERNAL"]},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}},"headers":{"X-Request-Id":{"description":"Request identifier. Include this value when contacting support.","schema":{"type":"string"}}}},"503":{"description":"Service temporarily unavailable: MAINTENANCE, STORE_BUSY, STORE_UNAVAILABLE or UPSTREAM.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["UNAUTHENTICATED","FORBIDDEN","NETWORK_RESTRICTED","FROZEN","PARTNER_SUSPENDED","QUOTA","NOT_FOUND","VALIDATION","CONFLICT","IDEMPOTENCY_MISMATCH","CREDIT_LIMIT","INFLIGHT_LIMIT","RATE_LIMITED","KEY_LIMIT","UPSTREAM","STORE_BUSY","STORE_UNAVAILABLE","MAINTENANCE","BAD_REQUEST","INTERNAL"]},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}},"headers":{"X-Request-Id":{"description":"Request identifier. Include this value when contacting support.","schema":{"type":"string"}},"Retry-After":{"description":"Minimum delay in seconds before retrying, when present. Some dependency failures omit this header; use exponential backoff with jitter.","schema":{"type":"integer"}}}},"default":{"description":"Other API error. Inspect the HTTP status and error envelope; request parsing can return 400, 413 or 415.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["UNAUTHENTICATED","FORBIDDEN","NETWORK_RESTRICTED","FROZEN","PARTNER_SUSPENDED","QUOTA","NOT_FOUND","VALIDATION","CONFLICT","IDEMPOTENCY_MISMATCH","CREDIT_LIMIT","INFLIGHT_LIMIT","RATE_LIMITED","KEY_LIMIT","UPSTREAM","STORE_BUSY","STORE_UNAVAILABLE","MAINTENANCE","BAD_REQUEST","INTERNAL"]},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}},"headers":{"X-Request-Id":{"description":"Request identifier. Include this value when contacting support.","schema":{"type":"string"}}}}},"operationId":"get_me"}},"/plans":{"get":{"tags":["Catalog"],"summary":"List plans","description":"Returns active plans in the account's assigned price book. Prices and discounts are account-specific. An empty list means no plans are currently available to order.","responses":{"200":{"description":"Available plans and prices.","content":{"application/json":{"schema":{"type":"object","properties":{"plans":{"type":"array","items":{"type":"object","properties":{"discount_basis":{"type":"string","enum":["vm_months_per_plan","allocated_per_plan","allocated_combined"]},"current_tier":{"type":"object","properties":{"qualifying_count":{"type":"integer","description":"Allocated server count used to select this rate."},"monthly_price":{"type":"string","description":"Monthly price at this allocation count."},"hourly_price":{"type":"string","description":"Displayed hourly rate at this allocation count; use returned charges for billing totals."},"next_from_count":{"anyOf":[{"type":"integer"},{"type":"null"}],"description":"Next discount threshold, or null when there is no higher tier."}},"required":["qualifying_count","monthly_price","hourly_price","next_from_count"],"additionalProperties":false},"code":{"type":"string"},"name":{"type":"string"},"hourly_price":{"type":"string","description":"Base per-hour rate: monthly_price / 672"},"monthly_price":{"type":"string","description":"Base price per VM-month (the first tier)"},"monthly_cap_hours":{"type":"integer"},"backups":{"type":"object","properties":{"enabled":{"type":"boolean"}},"required":["enabled"],"additionalProperties":false},"specs":{"anyOf":[{},{"type":"null"}]},"tiers":{"type":"array","items":{"type":"object","properties":{"from_vm_months":{"type":"number"},"monthly_price":{"type":"string"}},"required":["from_vm_months","monthly_price"],"additionalProperties":false},"description":"Volume tiers on your price book; one entry means a flat price"},"scheme":{"type":"string","enum":["volume","graduated"],"description":"For VM-month basis: whole-month volume or graduated brackets. Allocated-count bases require volume, applied separately to each started hour"}},"required":["code","name","hourly_price","monthly_cap_hours","backups"],"additionalProperties":false}}},"required":["plans"],"additionalProperties":false},"example":{"plans":[{"code":"standard-2","name":"Standard 2","hourly_price":"0.1000","monthly_price":"67.20","monthly_cap_hours":672,"backups":{"enabled":true},"specs":null}]}}},"headers":{"X-Request-Id":{"description":"Request identifier. Include this value when contacting support.","schema":{"type":"string"}}}},"401":{"description":"Authentication failed. The API key is missing, invalid or revoked, or API access is not approved.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["UNAUTHENTICATED","FORBIDDEN","NETWORK_RESTRICTED","FROZEN","PARTNER_SUSPENDED","QUOTA","NOT_FOUND","VALIDATION","CONFLICT","IDEMPOTENCY_MISMATCH","CREDIT_LIMIT","INFLIGHT_LIMIT","RATE_LIMITED","KEY_LIMIT","UPSTREAM","STORE_BUSY","STORE_UNAVAILABLE","MAINTENANCE","BAD_REQUEST","INTERNAL"]},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}},"headers":{"X-Request-Id":{"description":"Request identifier. Include this value when contacting support.","schema":{"type":"string"}},"WWW-Authenticate":{"description":"Bearer authentication challenge.","schema":{"type":"string"}}}},"403":{"description":"NETWORK_RESTRICTED: the request source is outside this deployment's approved IP networks.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["UNAUTHENTICATED","FORBIDDEN","NETWORK_RESTRICTED","FROZEN","PARTNER_SUSPENDED","QUOTA","NOT_FOUND","VALIDATION","CONFLICT","IDEMPOTENCY_MISMATCH","CREDIT_LIMIT","INFLIGHT_LIMIT","RATE_LIMITED","KEY_LIMIT","UPSTREAM","STORE_BUSY","STORE_UNAVAILABLE","MAINTENANCE","BAD_REQUEST","INTERNAL"]},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}},"headers":{"X-Request-Id":{"description":"Request identifier. Include this value when contacting support.","schema":{"type":"string"}}}},"429":{"description":"Rate limit exceeded. See Retry-After before retrying.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["UNAUTHENTICATED","FORBIDDEN","NETWORK_RESTRICTED","FROZEN","PARTNER_SUSPENDED","QUOTA","NOT_FOUND","VALIDATION","CONFLICT","IDEMPOTENCY_MISMATCH","CREDIT_LIMIT","INFLIGHT_LIMIT","RATE_LIMITED","KEY_LIMIT","UPSTREAM","STORE_BUSY","STORE_UNAVAILABLE","MAINTENANCE","BAD_REQUEST","INTERNAL"]},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}},"headers":{"X-Request-Id":{"description":"Request identifier. Include this value when contacting support.","schema":{"type":"string"}},"Retry-After":{"description":"Minimum delay in seconds before retrying, when present. Some dependency failures omit this header; use exponential backoff with jitter.","schema":{"type":"integer"}}}},"500":{"description":"INTERNAL: unexpected server error. Retain X-Request-Id for support; resolve the outcome before repeating a write.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["UNAUTHENTICATED","FORBIDDEN","NETWORK_RESTRICTED","FROZEN","PARTNER_SUSPENDED","QUOTA","NOT_FOUND","VALIDATION","CONFLICT","IDEMPOTENCY_MISMATCH","CREDIT_LIMIT","INFLIGHT_LIMIT","RATE_LIMITED","KEY_LIMIT","UPSTREAM","STORE_BUSY","STORE_UNAVAILABLE","MAINTENANCE","BAD_REQUEST","INTERNAL"]},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}},"headers":{"X-Request-Id":{"description":"Request identifier. Include this value when contacting support.","schema":{"type":"string"}}}},"503":{"description":"Service temporarily unavailable: MAINTENANCE, STORE_BUSY, STORE_UNAVAILABLE or UPSTREAM.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["UNAUTHENTICATED","FORBIDDEN","NETWORK_RESTRICTED","FROZEN","PARTNER_SUSPENDED","QUOTA","NOT_FOUND","VALIDATION","CONFLICT","IDEMPOTENCY_MISMATCH","CREDIT_LIMIT","INFLIGHT_LIMIT","RATE_LIMITED","KEY_LIMIT","UPSTREAM","STORE_BUSY","STORE_UNAVAILABLE","MAINTENANCE","BAD_REQUEST","INTERNAL"]},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}},"headers":{"X-Request-Id":{"description":"Request identifier. Include this value when contacting support.","schema":{"type":"string"}},"Retry-After":{"description":"Minimum delay in seconds before retrying, when present. Some dependency failures omit this header; use exponential backoff with jitter.","schema":{"type":"integer"}}}},"default":{"description":"Other API error. Inspect the HTTP status and error envelope; request parsing can return 400, 413 or 415.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["UNAUTHENTICATED","FORBIDDEN","NETWORK_RESTRICTED","FROZEN","PARTNER_SUSPENDED","QUOTA","NOT_FOUND","VALIDATION","CONFLICT","IDEMPOTENCY_MISMATCH","CREDIT_LIMIT","INFLIGHT_LIMIT","RATE_LIMITED","KEY_LIMIT","UPSTREAM","STORE_BUSY","STORE_UNAVAILABLE","MAINTENANCE","BAD_REQUEST","INTERNAL"]},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}},"headers":{"X-Request-Id":{"description":"Request identifier. Include this value when contacting support.","schema":{"type":"string"}}}}},"operationId":"get_plans"}},"/regions":{"get":{"tags":["Catalog"],"summary":"List regions","description":"Use the returned region code in server creation requests.","responses":{"200":{"description":"Available regions.","content":{"application/json":{"schema":{"type":"object","properties":{"regions":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string"},"name":{"type":"string"}},"required":["code","name"],"additionalProperties":false}}},"required":["regions"],"additionalProperties":false},"example":{"regions":[{"code":"chicago","name":"Chicago"}]}}},"headers":{"X-Request-Id":{"description":"Request identifier. Include this value when contacting support.","schema":{"type":"string"}}}},"401":{"description":"Authentication failed. The API key is missing, invalid or revoked, or API access is not approved.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["UNAUTHENTICATED","FORBIDDEN","NETWORK_RESTRICTED","FROZEN","PARTNER_SUSPENDED","QUOTA","NOT_FOUND","VALIDATION","CONFLICT","IDEMPOTENCY_MISMATCH","CREDIT_LIMIT","INFLIGHT_LIMIT","RATE_LIMITED","KEY_LIMIT","UPSTREAM","STORE_BUSY","STORE_UNAVAILABLE","MAINTENANCE","BAD_REQUEST","INTERNAL"]},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}},"headers":{"X-Request-Id":{"description":"Request identifier. Include this value when contacting support.","schema":{"type":"string"}},"WWW-Authenticate":{"description":"Bearer authentication challenge.","schema":{"type":"string"}}}},"403":{"description":"NETWORK_RESTRICTED: the request source is outside this deployment's approved IP networks.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["UNAUTHENTICATED","FORBIDDEN","NETWORK_RESTRICTED","FROZEN","PARTNER_SUSPENDED","QUOTA","NOT_FOUND","VALIDATION","CONFLICT","IDEMPOTENCY_MISMATCH","CREDIT_LIMIT","INFLIGHT_LIMIT","RATE_LIMITED","KEY_LIMIT","UPSTREAM","STORE_BUSY","STORE_UNAVAILABLE","MAINTENANCE","BAD_REQUEST","INTERNAL"]},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}},"headers":{"X-Request-Id":{"description":"Request identifier. Include this value when contacting support.","schema":{"type":"string"}}}},"429":{"description":"Rate limit exceeded. See Retry-After before retrying.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["UNAUTHENTICATED","FORBIDDEN","NETWORK_RESTRICTED","FROZEN","PARTNER_SUSPENDED","QUOTA","NOT_FOUND","VALIDATION","CONFLICT","IDEMPOTENCY_MISMATCH","CREDIT_LIMIT","INFLIGHT_LIMIT","RATE_LIMITED","KEY_LIMIT","UPSTREAM","STORE_BUSY","STORE_UNAVAILABLE","MAINTENANCE","BAD_REQUEST","INTERNAL"]},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}},"headers":{"X-Request-Id":{"description":"Request identifier. Include this value when contacting support.","schema":{"type":"string"}},"Retry-After":{"description":"Minimum delay in seconds before retrying, when present. Some dependency failures omit this header; use exponential backoff with jitter.","schema":{"type":"integer"}}}},"500":{"description":"INTERNAL: unexpected server error. Retain X-Request-Id for support; resolve the outcome before repeating a write.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["UNAUTHENTICATED","FORBIDDEN","NETWORK_RESTRICTED","FROZEN","PARTNER_SUSPENDED","QUOTA","NOT_FOUND","VALIDATION","CONFLICT","IDEMPOTENCY_MISMATCH","CREDIT_LIMIT","INFLIGHT_LIMIT","RATE_LIMITED","KEY_LIMIT","UPSTREAM","STORE_BUSY","STORE_UNAVAILABLE","MAINTENANCE","BAD_REQUEST","INTERNAL"]},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}},"headers":{"X-Request-Id":{"description":"Request identifier. Include this value when contacting support.","schema":{"type":"string"}}}},"503":{"description":"Service temporarily unavailable: MAINTENANCE, STORE_BUSY, STORE_UNAVAILABLE or UPSTREAM.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["UNAUTHENTICATED","FORBIDDEN","NETWORK_RESTRICTED","FROZEN","PARTNER_SUSPENDED","QUOTA","NOT_FOUND","VALIDATION","CONFLICT","IDEMPOTENCY_MISMATCH","CREDIT_LIMIT","INFLIGHT_LIMIT","RATE_LIMITED","KEY_LIMIT","UPSTREAM","STORE_BUSY","STORE_UNAVAILABLE","MAINTENANCE","BAD_REQUEST","INTERNAL"]},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}},"headers":{"X-Request-Id":{"description":"Request identifier. Include this value when contacting support.","schema":{"type":"string"}},"Retry-After":{"description":"Minimum delay in seconds before retrying, when present. Some dependency failures omit this header; use exponential backoff with jitter.","schema":{"type":"integer"}}}},"default":{"description":"Other API error. Inspect the HTTP status and error envelope; request parsing can return 400, 413 or 415.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["UNAUTHENTICATED","FORBIDDEN","NETWORK_RESTRICTED","FROZEN","PARTNER_SUSPENDED","QUOTA","NOT_FOUND","VALIDATION","CONFLICT","IDEMPOTENCY_MISMATCH","CREDIT_LIMIT","INFLIGHT_LIMIT","RATE_LIMITED","KEY_LIMIT","UPSTREAM","STORE_BUSY","STORE_UNAVAILABLE","MAINTENANCE","BAD_REQUEST","INTERNAL"]},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}},"headers":{"X-Request-Id":{"description":"Request identifier. Include this value when contacting support.","schema":{"type":"string"}}}}},"operationId":"get_regions"}},"/images":{"get":{"tags":["Catalog"],"summary":"List operating system images","description":"Use the returned image code in create or rebuild requests. Images with cloud_init set to true accept user_data.","responses":{"200":{"description":"Available images.","content":{"application/json":{"schema":{"type":"object","properties":{"images":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string"},"name":{"type":"string"},"cloud_init":{"type":"boolean"}},"required":["code","name","cloud_init"],"additionalProperties":false}}},"required":["images"],"additionalProperties":false},"example":{"images":[{"code":"ubuntu-24.04","name":"Ubuntu 24.04 LTS","cloud_init":true}]}}},"headers":{"X-Request-Id":{"description":"Request identifier. Include this value when contacting support.","schema":{"type":"string"}}}},"401":{"description":"Authentication failed. The API key is missing, invalid or revoked, or API access is not approved.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["UNAUTHENTICATED","FORBIDDEN","NETWORK_RESTRICTED","FROZEN","PARTNER_SUSPENDED","QUOTA","NOT_FOUND","VALIDATION","CONFLICT","IDEMPOTENCY_MISMATCH","CREDIT_LIMIT","INFLIGHT_LIMIT","RATE_LIMITED","KEY_LIMIT","UPSTREAM","STORE_BUSY","STORE_UNAVAILABLE","MAINTENANCE","BAD_REQUEST","INTERNAL"]},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}},"headers":{"X-Request-Id":{"description":"Request identifier. Include this value when contacting support.","schema":{"type":"string"}},"WWW-Authenticate":{"description":"Bearer authentication challenge.","schema":{"type":"string"}}}},"403":{"description":"NETWORK_RESTRICTED: the request source is outside this deployment's approved IP networks.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["UNAUTHENTICATED","FORBIDDEN","NETWORK_RESTRICTED","FROZEN","PARTNER_SUSPENDED","QUOTA","NOT_FOUND","VALIDATION","CONFLICT","IDEMPOTENCY_MISMATCH","CREDIT_LIMIT","INFLIGHT_LIMIT","RATE_LIMITED","KEY_LIMIT","UPSTREAM","STORE_BUSY","STORE_UNAVAILABLE","MAINTENANCE","BAD_REQUEST","INTERNAL"]},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}},"headers":{"X-Request-Id":{"description":"Request identifier. Include this value when contacting support.","schema":{"type":"string"}}}},"429":{"description":"Rate limit exceeded. See Retry-After before retrying.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["UNAUTHENTICATED","FORBIDDEN","NETWORK_RESTRICTED","FROZEN","PARTNER_SUSPENDED","QUOTA","NOT_FOUND","VALIDATION","CONFLICT","IDEMPOTENCY_MISMATCH","CREDIT_LIMIT","INFLIGHT_LIMIT","RATE_LIMITED","KEY_LIMIT","UPSTREAM","STORE_BUSY","STORE_UNAVAILABLE","MAINTENANCE","BAD_REQUEST","INTERNAL"]},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}},"headers":{"X-Request-Id":{"description":"Request identifier. Include this value when contacting support.","schema":{"type":"string"}},"Retry-After":{"description":"Minimum delay in seconds before retrying, when present. Some dependency failures omit this header; use exponential backoff with jitter.","schema":{"type":"integer"}}}},"500":{"description":"INTERNAL: unexpected server error. Retain X-Request-Id for support; resolve the outcome before repeating a write.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["UNAUTHENTICATED","FORBIDDEN","NETWORK_RESTRICTED","FROZEN","PARTNER_SUSPENDED","QUOTA","NOT_FOUND","VALIDATION","CONFLICT","IDEMPOTENCY_MISMATCH","CREDIT_LIMIT","INFLIGHT_LIMIT","RATE_LIMITED","KEY_LIMIT","UPSTREAM","STORE_BUSY","STORE_UNAVAILABLE","MAINTENANCE","BAD_REQUEST","INTERNAL"]},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}},"headers":{"X-Request-Id":{"description":"Request identifier. Include this value when contacting support.","schema":{"type":"string"}}}},"503":{"description":"Service temporarily unavailable: MAINTENANCE, STORE_BUSY, STORE_UNAVAILABLE or UPSTREAM.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["UNAUTHENTICATED","FORBIDDEN","NETWORK_RESTRICTED","FROZEN","PARTNER_SUSPENDED","QUOTA","NOT_FOUND","VALIDATION","CONFLICT","IDEMPOTENCY_MISMATCH","CREDIT_LIMIT","INFLIGHT_LIMIT","RATE_LIMITED","KEY_LIMIT","UPSTREAM","STORE_BUSY","STORE_UNAVAILABLE","MAINTENANCE","BAD_REQUEST","INTERNAL"]},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}},"headers":{"X-Request-Id":{"description":"Request identifier. Include this value when contacting support.","schema":{"type":"string"}},"Retry-After":{"description":"Minimum delay in seconds before retrying, when present. Some dependency failures omit this header; use exponential backoff with jitter.","schema":{"type":"integer"}}}},"default":{"description":"Other API error. Inspect the HTTP status and error envelope; request parsing can return 400, 413 or 415.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["UNAUTHENTICATED","FORBIDDEN","NETWORK_RESTRICTED","FROZEN","PARTNER_SUSPENDED","QUOTA","NOT_FOUND","VALIDATION","CONFLICT","IDEMPOTENCY_MISMATCH","CREDIT_LIMIT","INFLIGHT_LIMIT","RATE_LIMITED","KEY_LIMIT","UPSTREAM","STORE_BUSY","STORE_UNAVAILABLE","MAINTENANCE","BAD_REQUEST","INTERNAL"]},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}},"headers":{"X-Request-Id":{"description":"Request identifier. Include this value when contacting support.","schema":{"type":"string"}}}}},"operationId":"get_images"}},"/servers":{"get":{"tags":["Servers"],"summary":"List servers","description":"Returns a cursor-paginated list of servers owned by the authenticated account. Supports filtering and conditional requests.","parameters":[{"name":"status","in":"query","required":false,"schema":{"type":"string","enum":["requested","provisioning","active","rebuilding","suspended","destroying","destroyed","failed"]}},{"name":"updated_after","in":"query","required":false,"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}[ T]\\d{2}:\\d{2}:\\d{2}(\\.\\d{1,3})?Z?$","description":"Return servers updated after this UTC timestamp."},"description":"Return servers updated after this UTC timestamp."},{"name":"ids","in":"query","required":false,"schema":{"type":"string","maxLength":4000,"description":"Comma-separated server IDs."},"description":"Comma-separated server IDs."},{"name":"batch","in":"query","required":false,"schema":{"type":"string","maxLength":64,"description":"Filter by batch label."},"description":"Filter by batch label."},{"name":"external_id","in":"query","required":false,"schema":{"type":"string","maxLength":64,"description":"Filter by the identifier from your system."},"description":"Filter by the identifier from your system."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":100,"default":50,"description":"Maximum number of servers to return."},"description":"Maximum number of servers to return."},{"name":"after","in":"query","required":false,"schema":{"type":"string","maxLength":30,"description":"Pagination cursor from the preceding next_after value."},"description":"Pagination cursor from the preceding next_after value."},{"name":"If-None-Match","in":"header","required":false,"schema":{"type":"string"},"description":"ETag from a previous response. A matching representation returns 304 with no response body."}],"responses":{"200":{"description":"Server list.","content":{"application/json":{"schema":{"type":"object","properties":{"servers":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Server identifier in srv_<ulid> format."},"name":{"type":"string","description":"Server hostname."},"status":{"type":"string","enum":["requested","provisioning","active","rebuilding","suspended","destroying","destroyed","failed"],"description":"Provisioning or lifecycle state; does not indicate application health."},"failure":{"anyOf":[{"type":"string","enum":["create_call","ambiguous_create","task_failed","timeout","vanished","destroy_timeout"]},{"type":"null"}],"description":"Failure classification, or null when no failure has been recorded."},"plan":{"type":"string","description":"Plan code."},"region":{"type":"string","description":"Region code."},"image":{"type":"string","description":"Operating system image code."},"ipv4":{"type":["string","null"],"description":"Assigned IPv4 address, or null before allocation."},"ipv6":{"type":["string","null"],"description":"Reserved for IPv6. Null in this API version."},"locked":{"type":"boolean","description":"Whether deletion through the API is blocked."},"external_id":{"type":["string","null"],"description":"Identifier supplied by the integration, or null."},"batch":{"type":["string","null"],"description":"Group label supplied by the integration, or null."},"backups":{"type":"object","properties":{"enabled":{"type":"boolean"}},"required":["enabled"],"additionalProperties":false},"created_at":{"type":"string","format":"date-time","description":"Creation acceptance timestamp. Billing starts here for vm_months_per_plan, and at active_at for allocation-based pricing."},"active_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"description":"Timestamp when provisioning completed, or null while pending."},"ssh_reachable_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"description":"First successful TCP connection to port 22. Does not verify SSH authentication."},"destroy_requested_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"description":"Deletion acceptance timestamp and end of billing, or null."},"version":{"type":"integer","description":"Resource revision, incremented when the record changes."},"updated_at":{"type":"string","format":"date-time","description":"Timestamp of the most recent record update."},"cost":{"type":"object","properties":{"hourly":{"type":"string","description":"Current hourly rate as a decimal string."},"month_to_date":{"type":"string","description":"Accrued charges for the current billing month."},"projected":{"type":"string","description":"Projected charge through month end if the server remains allocated."}},"required":["hourly","month_to_date","projected"],"additionalProperties":false}},"required":["id","name","status","failure","plan","region","image","ipv4","ipv6","locked","external_id","batch","backups","created_at","active_at","ssh_reachable_at","destroy_requested_at","version","updated_at","cost"],"additionalProperties":false}},"next_after":{"type":["string","null"]}},"required":["servers","next_after"],"additionalProperties":false},"example":{"servers":[{"id":"srv_01J8Z3M4N5P6Q7R8S9T0V1W2X3","name":"web-01","status":"active","failure":null,"plan":"standard-2","region":"chicago","image":"ubuntu-24.04","ipv4":"203.0.113.10","ipv6":null,"locked":false,"external_id":"customer-4711","batch":null,"backups":{"enabled":true},"created_at":"2026-09-09T00:00:00.000Z","active_at":"2026-09-09T00:00:30.000Z","ssh_reachable_at":"2026-09-09T00:01:00.000Z","destroy_requested_at":null,"version":3,"updated_at":"2026-09-09T00:01:00.000Z","cost":{"hourly":"0.1000","month_to_date":"2.40","projected":"52.80"}}],"next_after":null}}},"headers":{"X-Request-Id":{"description":"Request identifier. Include this value when contacting support.","schema":{"type":"string"}},"ETag":{"description":"Identifier for the current representation.","schema":{"type":"string"}},"Cache-Control":{"description":"Private response cache policy; max-age is 5 seconds.","schema":{"type":"string"}}}},"304":{"description":"Not Modified. The representation matches If-None-Match; no response body.","headers":{"X-Request-Id":{"description":"Request identifier. Include this value when contacting support.","schema":{"type":"string"}},"ETag":{"description":"Identifier for the current representation.","schema":{"type":"string"}},"Cache-Control":{"description":"Private response cache policy; max-age is 5 seconds.","schema":{"type":"string"}}}},"401":{"description":"Authentication failed. The API key is missing, invalid or revoked, or API access is not approved.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["UNAUTHENTICATED","FORBIDDEN","NETWORK_RESTRICTED","FROZEN","PARTNER_SUSPENDED","QUOTA","NOT_FOUND","VALIDATION","CONFLICT","IDEMPOTENCY_MISMATCH","CREDIT_LIMIT","INFLIGHT_LIMIT","RATE_LIMITED","KEY_LIMIT","UPSTREAM","STORE_BUSY","STORE_UNAVAILABLE","MAINTENANCE","BAD_REQUEST","INTERNAL"]},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}},"headers":{"X-Request-Id":{"description":"Request identifier. Include this value when contacting support.","schema":{"type":"string"}},"WWW-Authenticate":{"description":"Bearer authentication challenge.","schema":{"type":"string"}}}},"403":{"description":"NETWORK_RESTRICTED: the request source is outside this deployment's approved IP networks.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["UNAUTHENTICATED","FORBIDDEN","NETWORK_RESTRICTED","FROZEN","PARTNER_SUSPENDED","QUOTA","NOT_FOUND","VALIDATION","CONFLICT","IDEMPOTENCY_MISMATCH","CREDIT_LIMIT","INFLIGHT_LIMIT","RATE_LIMITED","KEY_LIMIT","UPSTREAM","STORE_BUSY","STORE_UNAVAILABLE","MAINTENANCE","BAD_REQUEST","INTERNAL"]},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}},"headers":{"X-Request-Id":{"description":"Request identifier. Include this value when contacting support.","schema":{"type":"string"}}}},"422":{"description":"Invalid query parameters.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["UNAUTHENTICATED","FORBIDDEN","NETWORK_RESTRICTED","FROZEN","PARTNER_SUSPENDED","QUOTA","NOT_FOUND","VALIDATION","CONFLICT","IDEMPOTENCY_MISMATCH","CREDIT_LIMIT","INFLIGHT_LIMIT","RATE_LIMITED","KEY_LIMIT","UPSTREAM","STORE_BUSY","STORE_UNAVAILABLE","MAINTENANCE","BAD_REQUEST","INTERNAL"]},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}},"headers":{"X-Request-Id":{"description":"Request identifier. Include this value when contacting support.","schema":{"type":"string"}}}},"429":{"description":"Rate limit exceeded. See Retry-After before retrying.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["UNAUTHENTICATED","FORBIDDEN","NETWORK_RESTRICTED","FROZEN","PARTNER_SUSPENDED","QUOTA","NOT_FOUND","VALIDATION","CONFLICT","IDEMPOTENCY_MISMATCH","CREDIT_LIMIT","INFLIGHT_LIMIT","RATE_LIMITED","KEY_LIMIT","UPSTREAM","STORE_BUSY","STORE_UNAVAILABLE","MAINTENANCE","BAD_REQUEST","INTERNAL"]},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}},"headers":{"X-Request-Id":{"description":"Request identifier. Include this value when contacting support.","schema":{"type":"string"}},"Retry-After":{"description":"Minimum delay in seconds before retrying, when present. Some dependency failures omit this header; use exponential backoff with jitter.","schema":{"type":"integer"}}}},"500":{"description":"INTERNAL: unexpected server error. Retain X-Request-Id for support; resolve the outcome before repeating a write.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["UNAUTHENTICATED","FORBIDDEN","NETWORK_RESTRICTED","FROZEN","PARTNER_SUSPENDED","QUOTA","NOT_FOUND","VALIDATION","CONFLICT","IDEMPOTENCY_MISMATCH","CREDIT_LIMIT","INFLIGHT_LIMIT","RATE_LIMITED","KEY_LIMIT","UPSTREAM","STORE_BUSY","STORE_UNAVAILABLE","MAINTENANCE","BAD_REQUEST","INTERNAL"]},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}},"headers":{"X-Request-Id":{"description":"Request identifier. Include this value when contacting support.","schema":{"type":"string"}}}},"503":{"description":"Service temporarily unavailable: MAINTENANCE, STORE_BUSY, STORE_UNAVAILABLE or UPSTREAM.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["UNAUTHENTICATED","FORBIDDEN","NETWORK_RESTRICTED","FROZEN","PARTNER_SUSPENDED","QUOTA","NOT_FOUND","VALIDATION","CONFLICT","IDEMPOTENCY_MISMATCH","CREDIT_LIMIT","INFLIGHT_LIMIT","RATE_LIMITED","KEY_LIMIT","UPSTREAM","STORE_BUSY","STORE_UNAVAILABLE","MAINTENANCE","BAD_REQUEST","INTERNAL"]},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}},"headers":{"X-Request-Id":{"description":"Request identifier. Include this value when contacting support.","schema":{"type":"string"}},"Retry-After":{"description":"Minimum delay in seconds before retrying, when present. Some dependency failures omit this header; use exponential backoff with jitter.","schema":{"type":"integer"}}}},"default":{"description":"Other API error. Inspect the HTTP status and error envelope; request parsing can return 400, 413 or 415.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["UNAUTHENTICATED","FORBIDDEN","NETWORK_RESTRICTED","FROZEN","PARTNER_SUSPENDED","QUOTA","NOT_FOUND","VALIDATION","CONFLICT","IDEMPOTENCY_MISMATCH","CREDIT_LIMIT","INFLIGHT_LIMIT","RATE_LIMITED","KEY_LIMIT","UPSTREAM","STORE_BUSY","STORE_UNAVAILABLE","MAINTENANCE","BAD_REQUEST","INTERNAL"]},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}},"headers":{"X-Request-Id":{"description":"Request identifier. Include this value when contacting support.","schema":{"type":"string"}}}}},"operationId":"get_servers"},"post":{"tags":["Servers"],"summary":"Create a server","description":"Creates a server asynchronously. Set dry_run to true to validate the configuration and retrieve pricing without creating a server. If neither a password nor SSH keys are supplied, the generated root password is returned once. A 202 response confirms acceptance, not completion. Poll the returned server until its status changes; reuse the same idempotency key after a timeout. Billing start depends on the account's discount basis; see Billing.","parameters":[{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","minLength":1,"maxLength":128},"example":"create-web-01-20260910","description":"Required when dry_run is false or omitted. Use one unique value per intended server and reuse it for retries with the same request body. Retained for 24 hours. An unfinished request returns 409 CONFLICT with details.reason=request_in_progress and Retry-After. A different body returns 409 IDEMPOTENCY_MISMATCH."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":253,"pattern":"^(?=.{1,253}$)([a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?)(\\.[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?)*$","description":"Server hostname. Lowercase DNS labels separated by dots; unique among live servers in this account."},"plan":{"type":"string","minLength":1,"maxLength":32,"description":"Plan code returned by GET /v1/plans."},"region":{"type":"string","minLength":1,"maxLength":32,"description":"Region code returned by GET /v1/regions."},"image":{"type":"string","minLength":1,"maxLength":32,"description":"Operating system image code returned by GET /v1/images."},"ssh_keys":{"type":"array","items":{"type":"integer","exclusiveMinimum":0},"maxItems":20,"description":"IDs of registered SSH public keys owned by this account. Maximum 20 keys."},"password":{"type":"string","minLength":8,"maxLength":20,"description":"Root password, 8–20 characters. If omitted with no SSH keys, a password is generated and returned once."},"user_data":{"type":"string","description":"Cloud-init configuration or shell script. Must begin with #cloud-config or #! and be at most 65,536 UTF-8 bytes after CRLF normalization. Requires an image with cloud_init enabled."},"external_id":{"type":"string","minLength":1,"maxLength":64,"description":"Identifier from your system. Must be unique across this account, including deleted server records."},"batch":{"type":"string","minLength":1,"maxLength":64,"description":"Optional group label for filtering related servers."},"dry_run":{"type":"boolean","description":"When true, validate and return pricing without creating a server. Does not require Idempotency-Key."}},"required":["name","plan","region","image"],"additionalProperties":false},"examples":{"ssh":{"summary":"Create a server with an SSH key","value":{"name":"web-01","plan":"standard-2","region":"chicago","image":"ubuntu-24.04","ssh_keys":[123],"external_id":"customer-4711"}},"dryRun":{"summary":"Validate a server configuration","value":{"name":"web-01","plan":"standard-2","region":"chicago","image":"ubuntu-24.04","ssh_keys":[123],"dry_run":true}}}}}},"responses":{"200":{"description":"Configuration validated. Returned only for dry_run.","content":{"application/json":{"schema":{"type":"object","properties":{"valid":{"type":"boolean","const":true},"plan":{"type":"object","properties":{"code":{"type":"string"},"hourly_price":{"type":"string"},"monthly_cap_hours":{"type":"integer"}},"required":["code","hourly_price","monthly_cap_hours"],"additionalProperties":false},"price":{"type":"object","properties":{"discount_basis":{"type":"string","enum":["vm_months_per_plan","allocated_per_plan","allocated_combined"]},"current_tier":{"type":"object","properties":{"qualifying_count":{"type":"integer","description":"Allocated server count used to select this rate."},"monthly_price":{"type":"string","description":"Monthly price at this allocation count."},"hourly_price":{"type":"string","description":"Displayed hourly rate at this allocation count; use returned charges for billing totals."},"next_from_count":{"anyOf":[{"type":"integer"},{"type":"null"}],"description":"Next discount threshold, or null when there is no higher tier."}},"required":["qualifying_count","monthly_price","hourly_price","next_from_count"],"additionalProperties":false},"hourly":{"type":"string","description":"Current hourly rate (monthly price / 672). Allocated-count books rate each started hour at the qualifying count then; existing charges stay fixed"},"monthly_max":{"type":"string","description":"Base-rate monthly ceiling; current discounts may change during the month"},"monthly_price":{"type":"string","description":"Price per VM-month at the tier in force"},"tier":{"anyOf":[{"type":"object","properties":{"hours":{"type":"number"},"vm_months":{"type":"number"},"from_vm_months":{"type":"number"},"monthly_price":{"type":"string"},"next":{"anyOf":[{"type":"object","properties":{"from_vm_months":{"type":"number"},"monthly_price":{"type":"string"}},"required":["from_vm_months","monthly_price"],"additionalProperties":false},{"type":"null"}]}},"required":["hours","vm_months","from_vm_months","monthly_price","next"],"additionalProperties":false},{"type":"null"}]}},"required":["hourly","monthly_max"],"additionalProperties":false}},"required":["valid","plan","price"],"additionalProperties":false},"example":{"valid":true,"plan":{"code":"standard-2","hourly_price":"0.1000","monthly_cap_hours":672},"price":{"hourly":"0.1000","monthly_max":"67.20","monthly_price":"67.20"}}}},"headers":{"X-Request-Id":{"description":"Request identifier. Include this value when contacting support.","schema":{"type":"string"}}}},"202":{"description":"Server creation accepted.","content":{"application/json":{"schema":{"type":"object","properties":{"server":{"type":"object","properties":{"id":{"type":"string","description":"Server identifier in srv_<ulid> format."},"name":{"type":"string","description":"Server hostname."},"status":{"type":"string","enum":["requested","provisioning","active","rebuilding","suspended","destroying","destroyed","failed"],"description":"Provisioning or lifecycle state; does not indicate application health."},"failure":{"anyOf":[{"type":"string","enum":["create_call","ambiguous_create","task_failed","timeout","vanished","destroy_timeout"]},{"type":"null"}],"description":"Failure classification, or null when no failure has been recorded."},"plan":{"type":"string","description":"Plan code."},"region":{"type":"string","description":"Region code."},"image":{"type":"string","description":"Operating system image code."},"ipv4":{"type":["string","null"],"description":"Assigned IPv4 address, or null before allocation."},"ipv6":{"type":["string","null"],"description":"Reserved for IPv6. Null in this API version."},"locked":{"type":"boolean","description":"Whether deletion through the API is blocked."},"external_id":{"type":["string","null"],"description":"Identifier supplied by the integration, or null."},"batch":{"type":["string","null"],"description":"Group label supplied by the integration, or null."},"backups":{"type":"object","properties":{"enabled":{"type":"boolean"}},"required":["enabled"],"additionalProperties":false},"created_at":{"type":"string","format":"date-time","description":"Creation acceptance timestamp. Billing starts here for vm_months_per_plan, and at active_at for allocation-based pricing."},"active_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"description":"Timestamp when provisioning completed, or null while pending."},"ssh_reachable_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"description":"First successful TCP connection to port 22. Does not verify SSH authentication."},"destroy_requested_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"description":"Deletion acceptance timestamp and end of billing, or null."},"version":{"type":"integer","description":"Resource revision, incremented when the record changes."},"updated_at":{"type":"string","format":"date-time","description":"Timestamp of the most recent record update."},"cost":{"type":"object","properties":{"hourly":{"type":"string","description":"Current hourly rate as a decimal string."},"month_to_date":{"type":"string","description":"Accrued charges for the current billing month."},"projected":{"type":"string","description":"Projected charge through month end if the server remains allocated."}},"required":["hourly","month_to_date","projected"],"additionalProperties":false}},"required":["id","name","status","failure","plan","region","image","ipv4","ipv6","locked","external_id","batch","backups","created_at","active_at","ssh_reachable_at","destroy_requested_at","version","updated_at","cost"],"additionalProperties":false},"price":{"type":"object","properties":{"discount_basis":{"type":"string","enum":["vm_months_per_plan","allocated_per_plan","allocated_combined"]},"current_tier":{"type":"object","properties":{"qualifying_count":{"type":"integer","description":"Allocated server count used to select this rate."},"monthly_price":{"type":"string","description":"Monthly price at this allocation count."},"hourly_price":{"type":"string","description":"Displayed hourly rate at this allocation count; use returned charges for billing totals."},"next_from_count":{"anyOf":[{"type":"integer"},{"type":"null"}],"description":"Next discount threshold, or null when there is no higher tier."}},"required":["qualifying_count","monthly_price","hourly_price","next_from_count"],"additionalProperties":false},"hourly":{"type":"string","description":"Current hourly rate (monthly price / 672). Allocated-count books rate each started hour at the qualifying count then; existing charges stay fixed"},"monthly_max":{"type":"string","description":"Base-rate monthly ceiling; current discounts may change during the month"},"monthly_price":{"type":"string","description":"Price per VM-month at the tier in force"},"tier":{"anyOf":[{"type":"object","properties":{"hours":{"type":"number"},"vm_months":{"type":"number"},"from_vm_months":{"type":"number"},"monthly_price":{"type":"string"},"next":{"anyOf":[{"type":"object","properties":{"from_vm_months":{"type":"number"},"monthly_price":{"type":"string"}},"required":["from_vm_months","monthly_price"],"additionalProperties":false},{"type":"null"}]}},"required":["hours","vm_months","from_vm_months","monthly_price","next"],"additionalProperties":false},{"type":"null"}]}},"required":["hourly","monthly_max"],"additionalProperties":false},"password":{"type":["string","null"],"description":"Generated root password, returned once. Null with password_redacted on an idempotent replay."},"password_generated":{"type":"boolean","description":"Whether the API generated a root password for this request."},"password_redacted":{"type":"boolean","description":"True when a generated password is omitted from an idempotent replay."}},"required":["server","price","password_generated"],"additionalProperties":false},"example":{"server":{"id":"srv_01J8Z3M4N5P6Q7R8S9T0V1W2X3","name":"web-01","status":"provisioning","failure":null,"plan":"standard-2","region":"chicago","image":"ubuntu-24.04","ipv4":null,"ipv6":null,"locked":false,"external_id":"customer-4711","batch":null,"backups":{"enabled":true},"created_at":"2026-09-10T00:00:00.000Z","active_at":null,"ssh_reachable_at":null,"destroy_requested_at":null,"version":1,"updated_at":"2026-09-10T00:00:00.000Z","cost":{"hourly":"0.1000","month_to_date":"0.00","projected":"50.40"}},"price":{"hourly":"0.1000","monthly_max":"67.20","monthly_price":"67.20"},"password_generated":false}}},"headers":{"X-Request-Id":{"description":"Request identifier. Include this value when contacting support.","schema":{"type":"string"}},"Location":{"description":"Relative URL of the created server.","schema":{"type":"string"}},"Idempotent-Replayed":{"description":"true when this is a replay of a stored response.","schema":{"type":"boolean"}}}},"400":{"description":"Idempotency-Key is missing or invalid.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["UNAUTHENTICATED","FORBIDDEN","NETWORK_RESTRICTED","FROZEN","PARTNER_SUSPENDED","QUOTA","NOT_FOUND","VALIDATION","CONFLICT","IDEMPOTENCY_MISMATCH","CREDIT_LIMIT","INFLIGHT_LIMIT","RATE_LIMITED","KEY_LIMIT","UPSTREAM","STORE_BUSY","STORE_UNAVAILABLE","MAINTENANCE","BAD_REQUEST","INTERNAL"]},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}},"headers":{"X-Request-Id":{"description":"Request identifier. Include this value when contacting support.","schema":{"type":"string"}}}},"401":{"description":"Authentication failed. The API key is missing, invalid or revoked, or API access is not approved.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["UNAUTHENTICATED","FORBIDDEN","NETWORK_RESTRICTED","FROZEN","PARTNER_SUSPENDED","QUOTA","NOT_FOUND","VALIDATION","CONFLICT","IDEMPOTENCY_MISMATCH","CREDIT_LIMIT","INFLIGHT_LIMIT","RATE_LIMITED","KEY_LIMIT","UPSTREAM","STORE_BUSY","STORE_UNAVAILABLE","MAINTENANCE","BAD_REQUEST","INTERNAL"]},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}},"headers":{"X-Request-Id":{"description":"Request identifier. Include this value when contacting support.","schema":{"type":"string"}},"WWW-Authenticate":{"description":"Bearer authentication challenge.","schema":{"type":"string"}}}},"402":{"description":"CREDIT_LIMIT: account credit limit reached.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["UNAUTHENTICATED","FORBIDDEN","NETWORK_RESTRICTED","FROZEN","PARTNER_SUSPENDED","QUOTA","NOT_FOUND","VALIDATION","CONFLICT","IDEMPOTENCY_MISMATCH","CREDIT_LIMIT","INFLIGHT_LIMIT","RATE_LIMITED","KEY_LIMIT","UPSTREAM","STORE_BUSY","STORE_UNAVAILABLE","MAINTENANCE","BAD_REQUEST","INTERNAL"]},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}},"headers":{"X-Request-Id":{"description":"Request identifier. Include this value when contacting support.","schema":{"type":"string"}}}},"403":{"description":"FROZEN, PARTNER_SUSPENDED or QUOTA: account state or server quota prevents creation. NETWORK_RESTRICTED: the request source is outside this deployment's approved IP networks.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["UNAUTHENTICATED","FORBIDDEN","NETWORK_RESTRICTED","FROZEN","PARTNER_SUSPENDED","QUOTA","NOT_FOUND","VALIDATION","CONFLICT","IDEMPOTENCY_MISMATCH","CREDIT_LIMIT","INFLIGHT_LIMIT","RATE_LIMITED","KEY_LIMIT","UPSTREAM","STORE_BUSY","STORE_UNAVAILABLE","MAINTENANCE","BAD_REQUEST","INTERNAL"]},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}},"headers":{"X-Request-Id":{"description":"Request identifier. Include this value when contacting support.","schema":{"type":"string"}}}},"409":{"description":"CONFLICT or IDEMPOTENCY_MISMATCH: duplicate name or external_id, unfinished or expired idempotency key, or key used with a different body. For request_in_progress, wait for Retry-After and retry with the same key. A persistent conflict requires reconciling details.server_id with support.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["UNAUTHENTICATED","FORBIDDEN","NETWORK_RESTRICTED","FROZEN","PARTNER_SUSPENDED","QUOTA","NOT_FOUND","VALIDATION","CONFLICT","IDEMPOTENCY_MISMATCH","CREDIT_LIMIT","INFLIGHT_LIMIT","RATE_LIMITED","KEY_LIMIT","UPSTREAM","STORE_BUSY","STORE_UNAVAILABLE","MAINTENANCE","BAD_REQUEST","INTERNAL"]},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}},"headers":{"X-Request-Id":{"description":"Request identifier. Include this value when contacting support.","schema":{"type":"string"}},"Retry-After":{"description":"Minimum delay in seconds before retrying, when present. Some dependency failures omit this header; use exponential backoff with jitter.","schema":{"type":"integer"}}}},"422":{"description":"VALIDATION: invalid configuration or rejected provisioning. A rejected provisioning attempt also returns a failed server record.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["UNAUTHENTICATED","FORBIDDEN","NETWORK_RESTRICTED","FROZEN","PARTNER_SUSPENDED","QUOTA","NOT_FOUND","VALIDATION","CONFLICT","IDEMPOTENCY_MISMATCH","CREDIT_LIMIT","INFLIGHT_LIMIT","RATE_LIMITED","KEY_LIMIT","UPSTREAM","STORE_BUSY","STORE_UNAVAILABLE","MAINTENANCE","BAD_REQUEST","INTERNAL"]},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}}},"required":["code","message"],"additionalProperties":false},"server":{"type":"object","properties":{"id":{"type":"string","description":"Server identifier in srv_<ulid> format."},"name":{"type":"string","description":"Server hostname."},"status":{"type":"string","enum":["requested","provisioning","active","rebuilding","suspended","destroying","destroyed","failed"],"description":"Provisioning or lifecycle state; does not indicate application health."},"failure":{"anyOf":[{"type":"string","enum":["create_call","ambiguous_create","task_failed","timeout","vanished","destroy_timeout"]},{"type":"null"}],"description":"Failure classification, or null when no failure has been recorded."},"plan":{"type":"string","description":"Plan code."},"region":{"type":"string","description":"Region code."},"image":{"type":"string","description":"Operating system image code."},"ipv4":{"type":["string","null"],"description":"Assigned IPv4 address, or null before allocation."},"ipv6":{"type":["string","null"],"description":"Reserved for IPv6. Null in this API version."},"locked":{"type":"boolean","description":"Whether deletion through the API is blocked."},"external_id":{"type":["string","null"],"description":"Identifier supplied by the integration, or null."},"batch":{"type":["string","null"],"description":"Group label supplied by the integration, or null."},"backups":{"type":"object","properties":{"enabled":{"type":"boolean"}},"required":["enabled"],"additionalProperties":false},"created_at":{"type":"string","format":"date-time","description":"Creation acceptance timestamp. Billing starts here for vm_months_per_plan, and at active_at for allocation-based pricing."},"active_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"description":"Timestamp when provisioning completed, or null while pending."},"ssh_reachable_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"description":"First successful TCP connection to port 22. Does not verify SSH authentication."},"destroy_requested_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"description":"Deletion acceptance timestamp and end of billing, or null."},"version":{"type":"integer","description":"Resource revision, incremented when the record changes."},"updated_at":{"type":"string","format":"date-time","description":"Timestamp of the most recent record update."},"cost":{"type":"object","properties":{"hourly":{"type":"string","description":"Current hourly rate as a decimal string."},"month_to_date":{"type":"string","description":"Accrued charges for the current billing month."},"projected":{"type":"string","description":"Projected charge through month end if the server remains allocated."}},"required":["hourly","month_to_date","projected"],"additionalProperties":false}},"required":["id","name","status","failure","plan","region","image","ipv4","ipv6","locked","external_id","batch","backups","created_at","active_at","ssh_reachable_at","destroy_requested_at","version","updated_at","cost"],"additionalProperties":false,"description":"Failed server record when the compute platform rejected a provisioning attempt. Omitted for validation failures before creation."}},"required":["error"],"additionalProperties":false}}},"headers":{"X-Request-Id":{"description":"Request identifier. Include this value when contacting support.","schema":{"type":"string"}}}},"429":{"description":"INFLIGHT_LIMIT or RATE_LIMITED: provisioning concurrency or request rate exceeded.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["UNAUTHENTICATED","FORBIDDEN","NETWORK_RESTRICTED","FROZEN","PARTNER_SUSPENDED","QUOTA","NOT_FOUND","VALIDATION","CONFLICT","IDEMPOTENCY_MISMATCH","CREDIT_LIMIT","INFLIGHT_LIMIT","RATE_LIMITED","KEY_LIMIT","UPSTREAM","STORE_BUSY","STORE_UNAVAILABLE","MAINTENANCE","BAD_REQUEST","INTERNAL"]},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}},"headers":{"X-Request-Id":{"description":"Request identifier. Include this value when contacting support.","schema":{"type":"string"}},"Retry-After":{"description":"Minimum delay in seconds before retrying, when present. Some dependency failures omit this header; use exponential backoff with jitter.","schema":{"type":"integer"}}}},"500":{"description":"INTERNAL: unexpected server error. Retain X-Request-Id for support; resolve the outcome before repeating a write.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["UNAUTHENTICATED","FORBIDDEN","NETWORK_RESTRICTED","FROZEN","PARTNER_SUSPENDED","QUOTA","NOT_FOUND","VALIDATION","CONFLICT","IDEMPOTENCY_MISMATCH","CREDIT_LIMIT","INFLIGHT_LIMIT","RATE_LIMITED","KEY_LIMIT","UPSTREAM","STORE_BUSY","STORE_UNAVAILABLE","MAINTENANCE","BAD_REQUEST","INTERNAL"]},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}},"headers":{"X-Request-Id":{"description":"Request identifier. Include this value when contacting support.","schema":{"type":"string"}}}},"503":{"description":"Service temporarily unavailable: MAINTENANCE, STORE_BUSY, STORE_UNAVAILABLE or UPSTREAM.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["UNAUTHENTICATED","FORBIDDEN","NETWORK_RESTRICTED","FROZEN","PARTNER_SUSPENDED","QUOTA","NOT_FOUND","VALIDATION","CONFLICT","IDEMPOTENCY_MISMATCH","CREDIT_LIMIT","INFLIGHT_LIMIT","RATE_LIMITED","KEY_LIMIT","UPSTREAM","STORE_BUSY","STORE_UNAVAILABLE","MAINTENANCE","BAD_REQUEST","INTERNAL"]},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}},"headers":{"X-Request-Id":{"description":"Request identifier. Include this value when contacting support.","schema":{"type":"string"}},"Retry-After":{"description":"Minimum delay in seconds before retrying, when present. Some dependency failures omit this header; use exponential backoff with jitter.","schema":{"type":"integer"}}}},"default":{"description":"Other API error. Inspect the HTTP status and error envelope; request parsing can return 400, 413 or 415.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["UNAUTHENTICATED","FORBIDDEN","NETWORK_RESTRICTED","FROZEN","PARTNER_SUSPENDED","QUOTA","NOT_FOUND","VALIDATION","CONFLICT","IDEMPOTENCY_MISMATCH","CREDIT_LIMIT","INFLIGHT_LIMIT","RATE_LIMITED","KEY_LIMIT","UPSTREAM","STORE_BUSY","STORE_UNAVAILABLE","MAINTENANCE","BAD_REQUEST","INTERNAL"]},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}},"headers":{"X-Request-Id":{"description":"Request identifier. Include this value when contacting support.","schema":{"type":"string"}}}}},"operationId":"post_servers"}},"/servers/{id}":{"get":{"tags":["Servers"],"summary":"Retrieve a server","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"example":"srv_01J8Z3M4N5P6Q7R8S9T0V1W2X3","description":"Server identifier returned by the API."},{"name":"If-None-Match","in":"header","required":false,"schema":{"type":"string"},"description":"ETag from a previous response. A matching representation returns 304 with no response body."}],"responses":{"200":{"description":"Server details.","content":{"application/json":{"schema":{"type":"object","properties":{"server":{"type":"object","properties":{"id":{"type":"string","description":"Server identifier in srv_<ulid> format."},"name":{"type":"string","description":"Server hostname."},"status":{"type":"string","enum":["requested","provisioning","active","rebuilding","suspended","destroying","destroyed","failed"],"description":"Provisioning or lifecycle state; does not indicate application health."},"failure":{"anyOf":[{"type":"string","enum":["create_call","ambiguous_create","task_failed","timeout","vanished","destroy_timeout"]},{"type":"null"}],"description":"Failure classification, or null when no failure has been recorded."},"plan":{"type":"string","description":"Plan code."},"region":{"type":"string","description":"Region code."},"image":{"type":"string","description":"Operating system image code."},"ipv4":{"type":["string","null"],"description":"Assigned IPv4 address, or null before allocation."},"ipv6":{"type":["string","null"],"description":"Reserved for IPv6. Null in this API version."},"locked":{"type":"boolean","description":"Whether deletion through the API is blocked."},"external_id":{"type":["string","null"],"description":"Identifier supplied by the integration, or null."},"batch":{"type":["string","null"],"description":"Group label supplied by the integration, or null."},"backups":{"type":"object","properties":{"enabled":{"type":"boolean"}},"required":["enabled"],"additionalProperties":false},"created_at":{"type":"string","format":"date-time","description":"Creation acceptance timestamp. Billing starts here for vm_months_per_plan, and at active_at for allocation-based pricing."},"active_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"description":"Timestamp when provisioning completed, or null while pending."},"ssh_reachable_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"description":"First successful TCP connection to port 22. Does not verify SSH authentication."},"destroy_requested_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"description":"Deletion acceptance timestamp and end of billing, or null."},"version":{"type":"integer","description":"Resource revision, incremented when the record changes."},"updated_at":{"type":"string","format":"date-time","description":"Timestamp of the most recent record update."},"cost":{"type":"object","properties":{"hourly":{"type":"string","description":"Current hourly rate as a decimal string."},"month_to_date":{"type":"string","description":"Accrued charges for the current billing month."},"projected":{"type":"string","description":"Projected charge through month end if the server remains allocated."}},"required":["hourly","month_to_date","projected"],"additionalProperties":false}},"required":["id","name","status","failure","plan","region","image","ipv4","ipv6","locked","external_id","batch","backups","created_at","active_at","ssh_reachable_at","destroy_requested_at","version","updated_at","cost"],"additionalProperties":false}},"required":["server"],"additionalProperties":false},"example":{"server":{"id":"srv_01J8Z3M4N5P6Q7R8S9T0V1W2X3","name":"web-01","status":"active","failure":null,"plan":"standard-2","region":"chicago","image":"ubuntu-24.04","ipv4":"203.0.113.10","ipv6":null,"locked":false,"external_id":"customer-4711","batch":null,"backups":{"enabled":true},"created_at":"2026-09-09T00:00:00.000Z","active_at":"2026-09-09T00:00:30.000Z","ssh_reachable_at":"2026-09-09T00:01:00.000Z","destroy_requested_at":null,"version":3,"updated_at":"2026-09-09T00:01:00.000Z","cost":{"hourly":"0.1000","month_to_date":"2.40","projected":"52.80"}}}}},"headers":{"X-Request-Id":{"description":"Request identifier. Include this value when contacting support.","schema":{"type":"string"}},"ETag":{"description":"Identifier for the current representation.","schema":{"type":"string"}},"Cache-Control":{"description":"Private response cache policy; max-age is 5 seconds.","schema":{"type":"string"}}}},"304":{"description":"Not Modified. The representation matches If-None-Match; no response body.","headers":{"X-Request-Id":{"description":"Request identifier. Include this value when contacting support.","schema":{"type":"string"}},"ETag":{"description":"Identifier for the current representation.","schema":{"type":"string"}},"Cache-Control":{"description":"Private response cache policy; max-age is 5 seconds.","schema":{"type":"string"}}}},"401":{"description":"Authentication failed. The API key is missing, invalid or revoked, or API access is not approved.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["UNAUTHENTICATED","FORBIDDEN","NETWORK_RESTRICTED","FROZEN","PARTNER_SUSPENDED","QUOTA","NOT_FOUND","VALIDATION","CONFLICT","IDEMPOTENCY_MISMATCH","CREDIT_LIMIT","INFLIGHT_LIMIT","RATE_LIMITED","KEY_LIMIT","UPSTREAM","STORE_BUSY","STORE_UNAVAILABLE","MAINTENANCE","BAD_REQUEST","INTERNAL"]},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}},"headers":{"X-Request-Id":{"description":"Request identifier. Include this value when contacting support.","schema":{"type":"string"}},"WWW-Authenticate":{"description":"Bearer authentication challenge.","schema":{"type":"string"}}}},"403":{"description":"NETWORK_RESTRICTED: the request source is outside this deployment's approved IP networks.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["UNAUTHENTICATED","FORBIDDEN","NETWORK_RESTRICTED","FROZEN","PARTNER_SUSPENDED","QUOTA","NOT_FOUND","VALIDATION","CONFLICT","IDEMPOTENCY_MISMATCH","CREDIT_LIMIT","INFLIGHT_LIMIT","RATE_LIMITED","KEY_LIMIT","UPSTREAM","STORE_BUSY","STORE_UNAVAILABLE","MAINTENANCE","BAD_REQUEST","INTERNAL"]},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}},"headers":{"X-Request-Id":{"description":"Request identifier. Include this value when contacting support.","schema":{"type":"string"}}}},"404":{"description":"Server not found in this account.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["UNAUTHENTICATED","FORBIDDEN","NETWORK_RESTRICTED","FROZEN","PARTNER_SUSPENDED","QUOTA","NOT_FOUND","VALIDATION","CONFLICT","IDEMPOTENCY_MISMATCH","CREDIT_LIMIT","INFLIGHT_LIMIT","RATE_LIMITED","KEY_LIMIT","UPSTREAM","STORE_BUSY","STORE_UNAVAILABLE","MAINTENANCE","BAD_REQUEST","INTERNAL"]},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}},"headers":{"X-Request-Id":{"description":"Request identifier. Include this value when contacting support.","schema":{"type":"string"}}}},"429":{"description":"Rate limit exceeded. See Retry-After before retrying.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["UNAUTHENTICATED","FORBIDDEN","NETWORK_RESTRICTED","FROZEN","PARTNER_SUSPENDED","QUOTA","NOT_FOUND","VALIDATION","CONFLICT","IDEMPOTENCY_MISMATCH","CREDIT_LIMIT","INFLIGHT_LIMIT","RATE_LIMITED","KEY_LIMIT","UPSTREAM","STORE_BUSY","STORE_UNAVAILABLE","MAINTENANCE","BAD_REQUEST","INTERNAL"]},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}},"headers":{"X-Request-Id":{"description":"Request identifier. Include this value when contacting support.","schema":{"type":"string"}},"Retry-After":{"description":"Minimum delay in seconds before retrying, when present. Some dependency failures omit this header; use exponential backoff with jitter.","schema":{"type":"integer"}}}},"500":{"description":"INTERNAL: unexpected server error. Retain X-Request-Id for support; resolve the outcome before repeating a write.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["UNAUTHENTICATED","FORBIDDEN","NETWORK_RESTRICTED","FROZEN","PARTNER_SUSPENDED","QUOTA","NOT_FOUND","VALIDATION","CONFLICT","IDEMPOTENCY_MISMATCH","CREDIT_LIMIT","INFLIGHT_LIMIT","RATE_LIMITED","KEY_LIMIT","UPSTREAM","STORE_BUSY","STORE_UNAVAILABLE","MAINTENANCE","BAD_REQUEST","INTERNAL"]},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}},"headers":{"X-Request-Id":{"description":"Request identifier. Include this value when contacting support.","schema":{"type":"string"}}}},"503":{"description":"Service temporarily unavailable: MAINTENANCE, STORE_BUSY, STORE_UNAVAILABLE or UPSTREAM.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["UNAUTHENTICATED","FORBIDDEN","NETWORK_RESTRICTED","FROZEN","PARTNER_SUSPENDED","QUOTA","NOT_FOUND","VALIDATION","CONFLICT","IDEMPOTENCY_MISMATCH","CREDIT_LIMIT","INFLIGHT_LIMIT","RATE_LIMITED","KEY_LIMIT","UPSTREAM","STORE_BUSY","STORE_UNAVAILABLE","MAINTENANCE","BAD_REQUEST","INTERNAL"]},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}},"headers":{"X-Request-Id":{"description":"Request identifier. Include this value when contacting support.","schema":{"type":"string"}},"Retry-After":{"description":"Minimum delay in seconds before retrying, when present. Some dependency failures omit this header; use exponential backoff with jitter.","schema":{"type":"integer"}}}},"default":{"description":"Other API error. Inspect the HTTP status and error envelope; request parsing can return 400, 413 or 415.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["UNAUTHENTICATED","FORBIDDEN","NETWORK_RESTRICTED","FROZEN","PARTNER_SUSPENDED","QUOTA","NOT_FOUND","VALIDATION","CONFLICT","IDEMPOTENCY_MISMATCH","CREDIT_LIMIT","INFLIGHT_LIMIT","RATE_LIMITED","KEY_LIMIT","UPSTREAM","STORE_BUSY","STORE_UNAVAILABLE","MAINTENANCE","BAD_REQUEST","INTERNAL"]},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}},"headers":{"X-Request-Id":{"description":"Request identifier. Include this value when contacting support.","schema":{"type":"string"}}}}},"operationId":"get_servers_id"},"patch":{"tags":["Servers"],"summary":"Update deletion protection","description":"Set locked to true to prevent deletion through the API, or false to allow deletion. This setting does not prevent a rebuild or backup restore.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"example":"srv_01J8Z3M4N5P6Q7R8S9T0V1W2X3","description":"Server identifier returned by the API."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"locked":{"type":"boolean","description":"Enable or disable deletion protection. Does not prevent rebuilds or backup restores."}},"required":["locked"],"additionalProperties":false},"examples":{"lock":{"summary":"Enable deletion protection","value":{"locked":true}}}}}},"responses":{"200":{"description":"Updated server.","content":{"application/json":{"schema":{"type":"object","properties":{"server":{"type":"object","properties":{"id":{"type":"string","description":"Server identifier in srv_<ulid> format."},"name":{"type":"string","description":"Server hostname."},"status":{"type":"string","enum":["requested","provisioning","active","rebuilding","suspended","destroying","destroyed","failed"],"description":"Provisioning or lifecycle state; does not indicate application health."},"failure":{"anyOf":[{"type":"string","enum":["create_call","ambiguous_create","task_failed","timeout","vanished","destroy_timeout"]},{"type":"null"}],"description":"Failure classification, or null when no failure has been recorded."},"plan":{"type":"string","description":"Plan code."},"region":{"type":"string","description":"Region code."},"image":{"type":"string","description":"Operating system image code."},"ipv4":{"type":["string","null"],"description":"Assigned IPv4 address, or null before allocation."},"ipv6":{"type":["string","null"],"description":"Reserved for IPv6. Null in this API version."},"locked":{"type":"boolean","description":"Whether deletion through the API is blocked."},"external_id":{"type":["string","null"],"description":"Identifier supplied by the integration, or null."},"batch":{"type":["string","null"],"description":"Group label supplied by the integration, or null."},"backups":{"type":"object","properties":{"enabled":{"type":"boolean"}},"required":["enabled"],"additionalProperties":false},"created_at":{"type":"string","format":"date-time","description":"Creation acceptance timestamp. Billing starts here for vm_months_per_plan, and at active_at for allocation-based pricing."},"active_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"description":"Timestamp when provisioning completed, or null while pending."},"ssh_reachable_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"description":"First successful TCP connection to port 22. Does not verify SSH authentication."},"destroy_requested_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"description":"Deletion acceptance timestamp and end of billing, or null."},"version":{"type":"integer","description":"Resource revision, incremented when the record changes."},"updated_at":{"type":"string","format":"date-time","description":"Timestamp of the most recent record update."},"cost":{"type":"object","properties":{"hourly":{"type":"string","description":"Current hourly rate as a decimal string."},"month_to_date":{"type":"string","description":"Accrued charges for the current billing month."},"projected":{"type":"string","description":"Projected charge through month end if the server remains allocated."}},"required":["hourly","month_to_date","projected"],"additionalProperties":false}},"required":["id","name","status","failure","plan","region","image","ipv4","ipv6","locked","external_id","batch","backups","created_at","active_at","ssh_reachable_at","destroy_requested_at","version","updated_at","cost"],"additionalProperties":false}},"required":["server"],"additionalProperties":false},"example":{"server":{"id":"srv_01J8Z3M4N5P6Q7R8S9T0V1W2X3","name":"web-01","status":"active","failure":null,"plan":"standard-2","region":"chicago","image":"ubuntu-24.04","ipv4":"203.0.113.10","ipv6":null,"locked":true,"external_id":"customer-4711","batch":null,"backups":{"enabled":true},"created_at":"2026-09-09T00:00:00.000Z","active_at":"2026-09-09T00:00:30.000Z","ssh_reachable_at":"2026-09-09T00:01:00.000Z","destroy_requested_at":null,"version":4,"updated_at":"2026-09-10T00:00:00.000Z","cost":{"hourly":"0.1000","month_to_date":"2.40","projected":"52.80"}}}}},"headers":{"X-Request-Id":{"description":"Request identifier. Include this value when contacting support.","schema":{"type":"string"}}}},"401":{"description":"Authentication failed. The API key is missing, invalid or revoked, or API access is not approved.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["UNAUTHENTICATED","FORBIDDEN","NETWORK_RESTRICTED","FROZEN","PARTNER_SUSPENDED","QUOTA","NOT_FOUND","VALIDATION","CONFLICT","IDEMPOTENCY_MISMATCH","CREDIT_LIMIT","INFLIGHT_LIMIT","RATE_LIMITED","KEY_LIMIT","UPSTREAM","STORE_BUSY","STORE_UNAVAILABLE","MAINTENANCE","BAD_REQUEST","INTERNAL"]},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}},"headers":{"X-Request-Id":{"description":"Request identifier. Include this value when contacting support.","schema":{"type":"string"}},"WWW-Authenticate":{"description":"Bearer authentication challenge.","schema":{"type":"string"}}}},"403":{"description":"NETWORK_RESTRICTED: the request source is outside this deployment's approved IP networks.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["UNAUTHENTICATED","FORBIDDEN","NETWORK_RESTRICTED","FROZEN","PARTNER_SUSPENDED","QUOTA","NOT_FOUND","VALIDATION","CONFLICT","IDEMPOTENCY_MISMATCH","CREDIT_LIMIT","INFLIGHT_LIMIT","RATE_LIMITED","KEY_LIMIT","UPSTREAM","STORE_BUSY","STORE_UNAVAILABLE","MAINTENANCE","BAD_REQUEST","INTERNAL"]},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}},"headers":{"X-Request-Id":{"description":"Request identifier. Include this value when contacting support.","schema":{"type":"string"}}}},"404":{"description":"Server not found.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["UNAUTHENTICATED","FORBIDDEN","NETWORK_RESTRICTED","FROZEN","PARTNER_SUSPENDED","QUOTA","NOT_FOUND","VALIDATION","CONFLICT","IDEMPOTENCY_MISMATCH","CREDIT_LIMIT","INFLIGHT_LIMIT","RATE_LIMITED","KEY_LIMIT","UPSTREAM","STORE_BUSY","STORE_UNAVAILABLE","MAINTENANCE","BAD_REQUEST","INTERNAL"]},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}},"headers":{"X-Request-Id":{"description":"Request identifier. Include this value when contacting support.","schema":{"type":"string"}}}},"409":{"description":"CONFLICT: the server changed concurrently.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["UNAUTHENTICATED","FORBIDDEN","NETWORK_RESTRICTED","FROZEN","PARTNER_SUSPENDED","QUOTA","NOT_FOUND","VALIDATION","CONFLICT","IDEMPOTENCY_MISMATCH","CREDIT_LIMIT","INFLIGHT_LIMIT","RATE_LIMITED","KEY_LIMIT","UPSTREAM","STORE_BUSY","STORE_UNAVAILABLE","MAINTENANCE","BAD_REQUEST","INTERNAL"]},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}},"headers":{"X-Request-Id":{"description":"Request identifier. Include this value when contacting support.","schema":{"type":"string"}}}},"422":{"description":"Invalid request body.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["UNAUTHENTICATED","FORBIDDEN","NETWORK_RESTRICTED","FROZEN","PARTNER_SUSPENDED","QUOTA","NOT_FOUND","VALIDATION","CONFLICT","IDEMPOTENCY_MISMATCH","CREDIT_LIMIT","INFLIGHT_LIMIT","RATE_LIMITED","KEY_LIMIT","UPSTREAM","STORE_BUSY","STORE_UNAVAILABLE","MAINTENANCE","BAD_REQUEST","INTERNAL"]},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}},"headers":{"X-Request-Id":{"description":"Request identifier. Include this value when contacting support.","schema":{"type":"string"}}}},"429":{"description":"Rate limit exceeded. See Retry-After before retrying.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["UNAUTHENTICATED","FORBIDDEN","NETWORK_RESTRICTED","FROZEN","PARTNER_SUSPENDED","QUOTA","NOT_FOUND","VALIDATION","CONFLICT","IDEMPOTENCY_MISMATCH","CREDIT_LIMIT","INFLIGHT_LIMIT","RATE_LIMITED","KEY_LIMIT","UPSTREAM","STORE_BUSY","STORE_UNAVAILABLE","MAINTENANCE","BAD_REQUEST","INTERNAL"]},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}},"headers":{"X-Request-Id":{"description":"Request identifier. Include this value when contacting support.","schema":{"type":"string"}},"Retry-After":{"description":"Minimum delay in seconds before retrying, when present. Some dependency failures omit this header; use exponential backoff with jitter.","schema":{"type":"integer"}}}},"500":{"description":"INTERNAL: unexpected server error. Retain X-Request-Id for support; resolve the outcome before repeating a write.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["UNAUTHENTICATED","FORBIDDEN","NETWORK_RESTRICTED","FROZEN","PARTNER_SUSPENDED","QUOTA","NOT_FOUND","VALIDATION","CONFLICT","IDEMPOTENCY_MISMATCH","CREDIT_LIMIT","INFLIGHT_LIMIT","RATE_LIMITED","KEY_LIMIT","UPSTREAM","STORE_BUSY","STORE_UNAVAILABLE","MAINTENANCE","BAD_REQUEST","INTERNAL"]},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}},"headers":{"X-Request-Id":{"description":"Request identifier. Include this value when contacting support.","schema":{"type":"string"}}}},"503":{"description":"Service temporarily unavailable: MAINTENANCE, STORE_BUSY, STORE_UNAVAILABLE or UPSTREAM.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["UNAUTHENTICATED","FORBIDDEN","NETWORK_RESTRICTED","FROZEN","PARTNER_SUSPENDED","QUOTA","NOT_FOUND","VALIDATION","CONFLICT","IDEMPOTENCY_MISMATCH","CREDIT_LIMIT","INFLIGHT_LIMIT","RATE_LIMITED","KEY_LIMIT","UPSTREAM","STORE_BUSY","STORE_UNAVAILABLE","MAINTENANCE","BAD_REQUEST","INTERNAL"]},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}},"headers":{"X-Request-Id":{"description":"Request identifier. Include this value when contacting support.","schema":{"type":"string"}},"Retry-After":{"description":"Minimum delay in seconds before retrying, when present. Some dependency failures omit this header; use exponential backoff with jitter.","schema":{"type":"integer"}}}},"default":{"description":"Other API error. Inspect the HTTP status and error envelope; request parsing can return 400, 413 or 415.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["UNAUTHENTICATED","FORBIDDEN","NETWORK_RESTRICTED","FROZEN","PARTNER_SUSPENDED","QUOTA","NOT_FOUND","VALIDATION","CONFLICT","IDEMPOTENCY_MISMATCH","CREDIT_LIMIT","INFLIGHT_LIMIT","RATE_LIMITED","KEY_LIMIT","UPSTREAM","STORE_BUSY","STORE_UNAVAILABLE","MAINTENANCE","BAD_REQUEST","INTERNAL"]},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}},"headers":{"X-Request-Id":{"description":"Request identifier. Include this value when contacting support.","schema":{"type":"string"}}}}},"operationId":"patch_servers_id"},"delete":{"tags":["Servers"],"summary":"Delete a server","description":"Permanently deletes the server. Active or suspended servers transition to destroying; billing ends when deletion is accepted. Returns 204 if the server is already destroying, destroyed or failed. Locked servers and servers in requested, provisioning or rebuilding state return 409.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"example":"srv_01J8Z3M4N5P6Q7R8S9T0V1W2X3","description":"Server identifier returned by the API."}],"responses":{"202":{"description":"Deletion accepted; server status is destroying.","content":{"application/json":{"schema":{"type":"object","properties":{"server":{"type":"object","properties":{"id":{"type":"string","description":"Server identifier in srv_<ulid> format."},"name":{"type":"string","description":"Server hostname."},"status":{"type":"string","enum":["requested","provisioning","active","rebuilding","suspended","destroying","destroyed","failed"],"description":"Provisioning or lifecycle state; does not indicate application health."},"failure":{"anyOf":[{"type":"string","enum":["create_call","ambiguous_create","task_failed","timeout","vanished","destroy_timeout"]},{"type":"null"}],"description":"Failure classification, or null when no failure has been recorded."},"plan":{"type":"string","description":"Plan code."},"region":{"type":"string","description":"Region code."},"image":{"type":"string","description":"Operating system image code."},"ipv4":{"type":["string","null"],"description":"Assigned IPv4 address, or null before allocation."},"ipv6":{"type":["string","null"],"description":"Reserved for IPv6. Null in this API version."},"locked":{"type":"boolean","description":"Whether deletion through the API is blocked."},"external_id":{"type":["string","null"],"description":"Identifier supplied by the integration, or null."},"batch":{"type":["string","null"],"description":"Group label supplied by the integration, or null."},"backups":{"type":"object","properties":{"enabled":{"type":"boolean"}},"required":["enabled"],"additionalProperties":false},"created_at":{"type":"string","format":"date-time","description":"Creation acceptance timestamp. Billing starts here for vm_months_per_plan, and at active_at for allocation-based pricing."},"active_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"description":"Timestamp when provisioning completed, or null while pending."},"ssh_reachable_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"description":"First successful TCP connection to port 22. Does not verify SSH authentication."},"destroy_requested_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"description":"Deletion acceptance timestamp and end of billing, or null."},"version":{"type":"integer","description":"Resource revision, incremented when the record changes."},"updated_at":{"type":"string","format":"date-time","description":"Timestamp of the most recent record update."},"cost":{"type":"object","properties":{"hourly":{"type":"string","description":"Current hourly rate as a decimal string."},"month_to_date":{"type":"string","description":"Accrued charges for the current billing month."},"projected":{"type":"string","description":"Projected charge through month end if the server remains allocated."}},"required":["hourly","month_to_date","projected"],"additionalProperties":false}},"required":["id","name","status","failure","plan","region","image","ipv4","ipv6","locked","external_id","batch","backups","created_at","active_at","ssh_reachable_at","destroy_requested_at","version","updated_at","cost"],"additionalProperties":false}},"required":["server"],"additionalProperties":false},"example":{"server":{"id":"srv_01J8Z3M4N5P6Q7R8S9T0V1W2X3","name":"web-01","status":"destroying","failure":null,"plan":"standard-2","region":"chicago","image":"ubuntu-24.04","ipv4":"203.0.113.10","ipv6":null,"locked":false,"external_id":"customer-4711","batch":null,"backups":{"enabled":true},"created_at":"2026-09-09T00:00:00.000Z","active_at":"2026-09-09T00:00:30.000Z","ssh_reachable_at":"2026-09-09T00:01:00.000Z","destroy_requested_at":"2026-09-10T00:00:00.000Z","version":4,"updated_at":"2026-09-10T00:00:00.000Z","cost":{"hourly":"0.1000","month_to_date":"2.40","projected":"2.40"}}}}},"headers":{"X-Request-Id":{"description":"Request identifier. Include this value when contacting support.","schema":{"type":"string"}}}},"204":{"description":"Server is already destroying, destroyed or failed. No response body.","headers":{"X-Request-Id":{"description":"Request identifier. Include this value when contacting support.","schema":{"type":"string"}}}},"401":{"description":"Authentication failed. The API key is missing, invalid or revoked, or API access is not approved.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["UNAUTHENTICATED","FORBIDDEN","NETWORK_RESTRICTED","FROZEN","PARTNER_SUSPENDED","QUOTA","NOT_FOUND","VALIDATION","CONFLICT","IDEMPOTENCY_MISMATCH","CREDIT_LIMIT","INFLIGHT_LIMIT","RATE_LIMITED","KEY_LIMIT","UPSTREAM","STORE_BUSY","STORE_UNAVAILABLE","MAINTENANCE","BAD_REQUEST","INTERNAL"]},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}},"headers":{"X-Request-Id":{"description":"Request identifier. Include this value when contacting support.","schema":{"type":"string"}},"WWW-Authenticate":{"description":"Bearer authentication challenge.","schema":{"type":"string"}}}},"403":{"description":"NETWORK_RESTRICTED: the request source is outside this deployment's approved IP networks.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["UNAUTHENTICATED","FORBIDDEN","NETWORK_RESTRICTED","FROZEN","PARTNER_SUSPENDED","QUOTA","NOT_FOUND","VALIDATION","CONFLICT","IDEMPOTENCY_MISMATCH","CREDIT_LIMIT","INFLIGHT_LIMIT","RATE_LIMITED","KEY_LIMIT","UPSTREAM","STORE_BUSY","STORE_UNAVAILABLE","MAINTENANCE","BAD_REQUEST","INTERNAL"]},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}},"headers":{"X-Request-Id":{"description":"Request identifier. Include this value when contacting support.","schema":{"type":"string"}}}},"404":{"description":"Server not found.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["UNAUTHENTICATED","FORBIDDEN","NETWORK_RESTRICTED","FROZEN","PARTNER_SUSPENDED","QUOTA","NOT_FOUND","VALIDATION","CONFLICT","IDEMPOTENCY_MISMATCH","CREDIT_LIMIT","INFLIGHT_LIMIT","RATE_LIMITED","KEY_LIMIT","UPSTREAM","STORE_BUSY","STORE_UNAVAILABLE","MAINTENANCE","BAD_REQUEST","INTERNAL"]},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}},"headers":{"X-Request-Id":{"description":"Request identifier. Include this value when contacting support.","schema":{"type":"string"}}}},"409":{"description":"CONFLICT: deletion protection, server state or a concurrent update prevents deletion.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["UNAUTHENTICATED","FORBIDDEN","NETWORK_RESTRICTED","FROZEN","PARTNER_SUSPENDED","QUOTA","NOT_FOUND","VALIDATION","CONFLICT","IDEMPOTENCY_MISMATCH","CREDIT_LIMIT","INFLIGHT_LIMIT","RATE_LIMITED","KEY_LIMIT","UPSTREAM","STORE_BUSY","STORE_UNAVAILABLE","MAINTENANCE","BAD_REQUEST","INTERNAL"]},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}},"headers":{"X-Request-Id":{"description":"Request identifier. Include this value when contacting support.","schema":{"type":"string"}}}},"429":{"description":"Rate limit exceeded. See Retry-After before retrying.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["UNAUTHENTICATED","FORBIDDEN","NETWORK_RESTRICTED","FROZEN","PARTNER_SUSPENDED","QUOTA","NOT_FOUND","VALIDATION","CONFLICT","IDEMPOTENCY_MISMATCH","CREDIT_LIMIT","INFLIGHT_LIMIT","RATE_LIMITED","KEY_LIMIT","UPSTREAM","STORE_BUSY","STORE_UNAVAILABLE","MAINTENANCE","BAD_REQUEST","INTERNAL"]},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}},"headers":{"X-Request-Id":{"description":"Request identifier. Include this value when contacting support.","schema":{"type":"string"}},"Retry-After":{"description":"Minimum delay in seconds before retrying, when present. Some dependency failures omit this header; use exponential backoff with jitter.","schema":{"type":"integer"}}}},"500":{"description":"INTERNAL: unexpected server error. Retain X-Request-Id for support; resolve the outcome before repeating a write.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["UNAUTHENTICATED","FORBIDDEN","NETWORK_RESTRICTED","FROZEN","PARTNER_SUSPENDED","QUOTA","NOT_FOUND","VALIDATION","CONFLICT","IDEMPOTENCY_MISMATCH","CREDIT_LIMIT","INFLIGHT_LIMIT","RATE_LIMITED","KEY_LIMIT","UPSTREAM","STORE_BUSY","STORE_UNAVAILABLE","MAINTENANCE","BAD_REQUEST","INTERNAL"]},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}},"headers":{"X-Request-Id":{"description":"Request identifier. Include this value when contacting support.","schema":{"type":"string"}}}},"503":{"description":"Service temporarily unavailable: MAINTENANCE, STORE_BUSY, STORE_UNAVAILABLE or UPSTREAM.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["UNAUTHENTICATED","FORBIDDEN","NETWORK_RESTRICTED","FROZEN","PARTNER_SUSPENDED","QUOTA","NOT_FOUND","VALIDATION","CONFLICT","IDEMPOTENCY_MISMATCH","CREDIT_LIMIT","INFLIGHT_LIMIT","RATE_LIMITED","KEY_LIMIT","UPSTREAM","STORE_BUSY","STORE_UNAVAILABLE","MAINTENANCE","BAD_REQUEST","INTERNAL"]},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}},"headers":{"X-Request-Id":{"description":"Request identifier. Include this value when contacting support.","schema":{"type":"string"}},"Retry-After":{"description":"Minimum delay in seconds before retrying, when present. Some dependency failures omit this header; use exponential backoff with jitter.","schema":{"type":"integer"}}}},"default":{"description":"Other API error. Inspect the HTTP status and error envelope; request parsing can return 400, 413 or 415.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["UNAUTHENTICATED","FORBIDDEN","NETWORK_RESTRICTED","FROZEN","PARTNER_SUSPENDED","QUOTA","NOT_FOUND","VALIDATION","CONFLICT","IDEMPOTENCY_MISMATCH","CREDIT_LIMIT","INFLIGHT_LIMIT","RATE_LIMITED","KEY_LIMIT","UPSTREAM","STORE_BUSY","STORE_UNAVAILABLE","MAINTENANCE","BAD_REQUEST","INTERNAL"]},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}},"headers":{"X-Request-Id":{"description":"Request identifier. Include this value when contacting support.","schema":{"type":"string"}}}}},"operationId":"delete_servers_id"}},"/servers/{id}/actions":{"post":{"tags":["Servers"],"summary":"Perform a server action","description":"Supports reboot, start, stop, reset_password and rebuild on active servers. reset_password returns the password generated by the compute platform once; its task ID can be null. Rebuild overwrites the server disk with the selected image while preserving the server ID, IP address and billing interval. Supply SSH keys or a password, or receive a generated password once. Rebuild can return a null task ID; monitor the returned server and events. Rebuild failure requires checking task and event details; a return to active does not confirm a successful reinstall.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"example":"srv_01J8Z3M4N5P6Q7R8S9T0V1W2X3","description":"Server identifier returned by the API."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"anyOf":[{"type":"object","properties":{"action":{"type":"string","enum":["reboot","start","stop","reset_password"]}},"required":["action"],"additionalProperties":false},{"type":"object","properties":{"action":{"type":"string","const":"rebuild"},"image":{"type":"string","minLength":1,"maxLength":32,"description":"Operating system image code returned by GET /v1/images."},"ssh_keys":{"type":"array","items":{"type":"integer","exclusiveMinimum":0},"maxItems":20,"description":"IDs of registered SSH public keys owned by this account. Maximum 20 keys."},"password":{"type":"string","minLength":8,"maxLength":20,"description":"Root password, 8–20 characters. If omitted with no SSH keys, a password is generated and returned once."},"user_data":{"type":"string","description":"Cloud-init configuration or shell script. Must begin with #cloud-config or #! and be at most 65,536 UTF-8 bytes after CRLF normalization. Requires an image with cloud_init enabled."}},"required":["action","image"],"additionalProperties":false}]},"examples":{"reboot":{"summary":"Reboot a server","value":{"action":"reboot"}},"rebuild":{"summary":"Reinstall the operating system","value":{"action":"rebuild","image":"ubuntu-24.04","ssh_keys":[123]}},"resetPassword":{"summary":"Reset the root password","value":{"action":"reset_password"}}}}}},"responses":{"202":{"description":"Action accepted. Poll task.id when present.","content":{"application/json":{"schema":{"type":"object","properties":{"task":{"type":"object","properties":{"id":{"anyOf":[{"type":"integer"},{"type":"null"}],"description":"Task identifier for polling, or null when the operation returned no task."},"action":{"type":"string","description":"Operation performed by this task."},"status":{"type":"string","description":"Task status: pending or running is incomplete; done is success; failed or canceled is unsuccessful. Treat unknown values as unresolved."},"server_id":{"type":"string","description":"Associated server ID, included when retrieving a task."}},"required":["id","action","status"],"additionalProperties":false},"password":{"type":"string","description":"Generated root password, shown once for reset_password or a rebuild with neither password nor non-empty ssh_keys. A supplied password is not echoed."},"server":{"type":"object","properties":{"id":{"type":"string","description":"Server identifier in srv_<ulid> format."},"name":{"type":"string","description":"Server hostname."},"status":{"type":"string","enum":["requested","provisioning","active","rebuilding","suspended","destroying","destroyed","failed"],"description":"Provisioning or lifecycle state; does not indicate application health."},"failure":{"anyOf":[{"type":"string","enum":["create_call","ambiguous_create","task_failed","timeout","vanished","destroy_timeout"]},{"type":"null"}],"description":"Failure classification, or null when no failure has been recorded."},"plan":{"type":"string","description":"Plan code."},"region":{"type":"string","description":"Region code."},"image":{"type":"string","description":"Operating system image code."},"ipv4":{"type":["string","null"],"description":"Assigned IPv4 address, or null before allocation."},"ipv6":{"type":["string","null"],"description":"Reserved for IPv6. Null in this API version."},"locked":{"type":"boolean","description":"Whether deletion through the API is blocked."},"external_id":{"type":["string","null"],"description":"Identifier supplied by the integration, or null."},"batch":{"type":["string","null"],"description":"Group label supplied by the integration, or null."},"backups":{"type":"object","properties":{"enabled":{"type":"boolean"}},"required":["enabled"],"additionalProperties":false},"created_at":{"type":"string","format":"date-time","description":"Creation acceptance timestamp. Billing starts here for vm_months_per_plan, and at active_at for allocation-based pricing."},"active_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"description":"Timestamp when provisioning completed, or null while pending."},"ssh_reachable_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"description":"First successful TCP connection to port 22. Does not verify SSH authentication."},"destroy_requested_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"description":"Deletion acceptance timestamp and end of billing, or null."},"version":{"type":"integer","description":"Resource revision, incremented when the record changes."},"updated_at":{"type":"string","format":"date-time","description":"Timestamp of the most recent record update."},"cost":{"type":"object","properties":{"hourly":{"type":"string","description":"Current hourly rate as a decimal string."},"month_to_date":{"type":"string","description":"Accrued charges for the current billing month."},"projected":{"type":"string","description":"Projected charge through month end if the server remains allocated."}},"required":["hourly","month_to_date","projected"],"additionalProperties":false}},"required":["id","name","status","failure","plan","region","image","ipv4","ipv6","locked","external_id","batch","backups","created_at","active_at","ssh_reachable_at","destroy_requested_at","version","updated_at","cost"],"additionalProperties":false,"description":"Only for rebuild: the server in `rebuilding`"}},"required":["task"],"additionalProperties":false},"example":{"task":{"id":90210,"action":"reboot","status":"pending"}}}},"headers":{"X-Request-Id":{"description":"Request identifier. Include this value when contacting support.","schema":{"type":"string"}}}},"401":{"description":"Authentication failed. The API key is missing, invalid or revoked, or API access is not approved.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["UNAUTHENTICATED","FORBIDDEN","NETWORK_RESTRICTED","FROZEN","PARTNER_SUSPENDED","QUOTA","NOT_FOUND","VALIDATION","CONFLICT","IDEMPOTENCY_MISMATCH","CREDIT_LIMIT","INFLIGHT_LIMIT","RATE_LIMITED","KEY_LIMIT","UPSTREAM","STORE_BUSY","STORE_UNAVAILABLE","MAINTENANCE","BAD_REQUEST","INTERNAL"]},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}},"headers":{"X-Request-Id":{"description":"Request identifier. Include this value when contacting support.","schema":{"type":"string"}},"WWW-Authenticate":{"description":"Bearer authentication challenge.","schema":{"type":"string"}}}},"403":{"description":"NETWORK_RESTRICTED: the request source is outside this deployment's approved IP networks.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["UNAUTHENTICATED","FORBIDDEN","NETWORK_RESTRICTED","FROZEN","PARTNER_SUSPENDED","QUOTA","NOT_FOUND","VALIDATION","CONFLICT","IDEMPOTENCY_MISMATCH","CREDIT_LIMIT","INFLIGHT_LIMIT","RATE_LIMITED","KEY_LIMIT","UPSTREAM","STORE_BUSY","STORE_UNAVAILABLE","MAINTENANCE","BAD_REQUEST","INTERNAL"]},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}},"headers":{"X-Request-Id":{"description":"Request identifier. Include this value when contacting support.","schema":{"type":"string"}}}},"404":{"description":"Server not found.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["UNAUTHENTICATED","FORBIDDEN","NETWORK_RESTRICTED","FROZEN","PARTNER_SUSPENDED","QUOTA","NOT_FOUND","VALIDATION","CONFLICT","IDEMPOTENCY_MISMATCH","CREDIT_LIMIT","INFLIGHT_LIMIT","RATE_LIMITED","KEY_LIMIT","UPSTREAM","STORE_BUSY","STORE_UNAVAILABLE","MAINTENANCE","BAD_REQUEST","INTERNAL"]},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}},"headers":{"X-Request-Id":{"description":"Request identifier. Include this value when contacting support.","schema":{"type":"string"}}}},"409":{"description":"CONFLICT: server must be active; concurrent operations can also prevent an action.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["UNAUTHENTICATED","FORBIDDEN","NETWORK_RESTRICTED","FROZEN","PARTNER_SUSPENDED","QUOTA","NOT_FOUND","VALIDATION","CONFLICT","IDEMPOTENCY_MISMATCH","CREDIT_LIMIT","INFLIGHT_LIMIT","RATE_LIMITED","KEY_LIMIT","UPSTREAM","STORE_BUSY","STORE_UNAVAILABLE","MAINTENANCE","BAD_REQUEST","INTERNAL"]},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}},"headers":{"X-Request-Id":{"description":"Request identifier. Include this value when contacting support.","schema":{"type":"string"}}}},"422":{"description":"Invalid action or rebuild configuration.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["UNAUTHENTICATED","FORBIDDEN","NETWORK_RESTRICTED","FROZEN","PARTNER_SUSPENDED","QUOTA","NOT_FOUND","VALIDATION","CONFLICT","IDEMPOTENCY_MISMATCH","CREDIT_LIMIT","INFLIGHT_LIMIT","RATE_LIMITED","KEY_LIMIT","UPSTREAM","STORE_BUSY","STORE_UNAVAILABLE","MAINTENANCE","BAD_REQUEST","INTERNAL"]},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}},"headers":{"X-Request-Id":{"description":"Request identifier. Include this value when contacting support.","schema":{"type":"string"}}}},"429":{"description":"Rate limit exceeded. See Retry-After before retrying.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["UNAUTHENTICATED","FORBIDDEN","NETWORK_RESTRICTED","FROZEN","PARTNER_SUSPENDED","QUOTA","NOT_FOUND","VALIDATION","CONFLICT","IDEMPOTENCY_MISMATCH","CREDIT_LIMIT","INFLIGHT_LIMIT","RATE_LIMITED","KEY_LIMIT","UPSTREAM","STORE_BUSY","STORE_UNAVAILABLE","MAINTENANCE","BAD_REQUEST","INTERNAL"]},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}},"headers":{"X-Request-Id":{"description":"Request identifier. Include this value when contacting support.","schema":{"type":"string"}},"Retry-After":{"description":"Minimum delay in seconds before retrying, when present. Some dependency failures omit this header; use exponential backoff with jitter.","schema":{"type":"integer"}}}},"500":{"description":"INTERNAL: unexpected server error. Retain X-Request-Id for support; resolve the outcome before repeating a write.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["UNAUTHENTICATED","FORBIDDEN","NETWORK_RESTRICTED","FROZEN","PARTNER_SUSPENDED","QUOTA","NOT_FOUND","VALIDATION","CONFLICT","IDEMPOTENCY_MISMATCH","CREDIT_LIMIT","INFLIGHT_LIMIT","RATE_LIMITED","KEY_LIMIT","UPSTREAM","STORE_BUSY","STORE_UNAVAILABLE","MAINTENANCE","BAD_REQUEST","INTERNAL"]},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}},"headers":{"X-Request-Id":{"description":"Request identifier. Include this value when contacting support.","schema":{"type":"string"}}}},"503":{"description":"Service temporarily unavailable: MAINTENANCE, STORE_BUSY, STORE_UNAVAILABLE or UPSTREAM.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["UNAUTHENTICATED","FORBIDDEN","NETWORK_RESTRICTED","FROZEN","PARTNER_SUSPENDED","QUOTA","NOT_FOUND","VALIDATION","CONFLICT","IDEMPOTENCY_MISMATCH","CREDIT_LIMIT","INFLIGHT_LIMIT","RATE_LIMITED","KEY_LIMIT","UPSTREAM","STORE_BUSY","STORE_UNAVAILABLE","MAINTENANCE","BAD_REQUEST","INTERNAL"]},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}},"headers":{"X-Request-Id":{"description":"Request identifier. Include this value when contacting support.","schema":{"type":"string"}},"Retry-After":{"description":"Minimum delay in seconds before retrying, when present. Some dependency failures omit this header; use exponential backoff with jitter.","schema":{"type":"integer"}}}},"default":{"description":"Other API error. Inspect the HTTP status and error envelope; request parsing can return 400, 413 or 415.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["UNAUTHENTICATED","FORBIDDEN","NETWORK_RESTRICTED","FROZEN","PARTNER_SUSPENDED","QUOTA","NOT_FOUND","VALIDATION","CONFLICT","IDEMPOTENCY_MISMATCH","CREDIT_LIMIT","INFLIGHT_LIMIT","RATE_LIMITED","KEY_LIMIT","UPSTREAM","STORE_BUSY","STORE_UNAVAILABLE","MAINTENANCE","BAD_REQUEST","INTERNAL"]},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}},"headers":{"X-Request-Id":{"description":"Request identifier. Include this value when contacting support.","schema":{"type":"string"}}}}},"operationId":"post_servers_id_actions"}},"/servers/{id}/backups":{"get":{"tags":["Backups"],"summary":"List server backups","description":"Requires an active or suspended server. Existing backups remain visible when backups.enabled is false. Deleting the server also removes its backups.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"example":"srv_01J8Z3M4N5P6Q7R8S9T0V1W2X3","description":"Server identifier returned by the API."}],"responses":{"200":{"description":"Server backups.","content":{"application/json":{"schema":{"type":"object","properties":{"backups":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer"},"status":{"type":"string"},"created_at":{"type":"string"},"size":{"type":["number","null"]}},"required":["id","status","created_at","size"],"additionalProperties":false}}},"required":["backups"],"additionalProperties":false},"example":{"backups":[{"id":7,"status":"created","created_at":"2026-09-09T06:00:00.000Z","size":1073741824}]}}},"headers":{"X-Request-Id":{"description":"Request identifier. Include this value when contacting support.","schema":{"type":"string"}}}},"401":{"description":"Authentication failed. The API key is missing, invalid or revoked, or API access is not approved.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["UNAUTHENTICATED","FORBIDDEN","NETWORK_RESTRICTED","FROZEN","PARTNER_SUSPENDED","QUOTA","NOT_FOUND","VALIDATION","CONFLICT","IDEMPOTENCY_MISMATCH","CREDIT_LIMIT","INFLIGHT_LIMIT","RATE_LIMITED","KEY_LIMIT","UPSTREAM","STORE_BUSY","STORE_UNAVAILABLE","MAINTENANCE","BAD_REQUEST","INTERNAL"]},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}},"headers":{"X-Request-Id":{"description":"Request identifier. Include this value when contacting support.","schema":{"type":"string"}},"WWW-Authenticate":{"description":"Bearer authentication challenge.","schema":{"type":"string"}}}},"403":{"description":"NETWORK_RESTRICTED: the request source is outside this deployment's approved IP networks.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["UNAUTHENTICATED","FORBIDDEN","NETWORK_RESTRICTED","FROZEN","PARTNER_SUSPENDED","QUOTA","NOT_FOUND","VALIDATION","CONFLICT","IDEMPOTENCY_MISMATCH","CREDIT_LIMIT","INFLIGHT_LIMIT","RATE_LIMITED","KEY_LIMIT","UPSTREAM","STORE_BUSY","STORE_UNAVAILABLE","MAINTENANCE","BAD_REQUEST","INTERNAL"]},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}},"headers":{"X-Request-Id":{"description":"Request identifier. Include this value when contacting support.","schema":{"type":"string"}}}},"404":{"description":"Server not found.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["UNAUTHENTICATED","FORBIDDEN","NETWORK_RESTRICTED","FROZEN","PARTNER_SUSPENDED","QUOTA","NOT_FOUND","VALIDATION","CONFLICT","IDEMPOTENCY_MISMATCH","CREDIT_LIMIT","INFLIGHT_LIMIT","RATE_LIMITED","KEY_LIMIT","UPSTREAM","STORE_BUSY","STORE_UNAVAILABLE","MAINTENANCE","BAD_REQUEST","INTERNAL"]},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}},"headers":{"X-Request-Id":{"description":"Request identifier. Include this value when contacting support.","schema":{"type":"string"}}}},"409":{"description":"CONFLICT: server is not active or suspended.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["UNAUTHENTICATED","FORBIDDEN","NETWORK_RESTRICTED","FROZEN","PARTNER_SUSPENDED","QUOTA","NOT_FOUND","VALIDATION","CONFLICT","IDEMPOTENCY_MISMATCH","CREDIT_LIMIT","INFLIGHT_LIMIT","RATE_LIMITED","KEY_LIMIT","UPSTREAM","STORE_BUSY","STORE_UNAVAILABLE","MAINTENANCE","BAD_REQUEST","INTERNAL"]},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}},"headers":{"X-Request-Id":{"description":"Request identifier. Include this value when contacting support.","schema":{"type":"string"}}}},"429":{"description":"Rate limit exceeded. See Retry-After before retrying.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["UNAUTHENTICATED","FORBIDDEN","NETWORK_RESTRICTED","FROZEN","PARTNER_SUSPENDED","QUOTA","NOT_FOUND","VALIDATION","CONFLICT","IDEMPOTENCY_MISMATCH","CREDIT_LIMIT","INFLIGHT_LIMIT","RATE_LIMITED","KEY_LIMIT","UPSTREAM","STORE_BUSY","STORE_UNAVAILABLE","MAINTENANCE","BAD_REQUEST","INTERNAL"]},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}},"headers":{"X-Request-Id":{"description":"Request identifier. Include this value when contacting support.","schema":{"type":"string"}},"Retry-After":{"description":"Minimum delay in seconds before retrying, when present. Some dependency failures omit this header; use exponential backoff with jitter.","schema":{"type":"integer"}}}},"500":{"description":"INTERNAL: unexpected server error. Retain X-Request-Id for support; resolve the outcome before repeating a write.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["UNAUTHENTICATED","FORBIDDEN","NETWORK_RESTRICTED","FROZEN","PARTNER_SUSPENDED","QUOTA","NOT_FOUND","VALIDATION","CONFLICT","IDEMPOTENCY_MISMATCH","CREDIT_LIMIT","INFLIGHT_LIMIT","RATE_LIMITED","KEY_LIMIT","UPSTREAM","STORE_BUSY","STORE_UNAVAILABLE","MAINTENANCE","BAD_REQUEST","INTERNAL"]},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}},"headers":{"X-Request-Id":{"description":"Request identifier. Include this value when contacting support.","schema":{"type":"string"}}}},"503":{"description":"Service temporarily unavailable: MAINTENANCE, STORE_BUSY, STORE_UNAVAILABLE or UPSTREAM.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["UNAUTHENTICATED","FORBIDDEN","NETWORK_RESTRICTED","FROZEN","PARTNER_SUSPENDED","QUOTA","NOT_FOUND","VALIDATION","CONFLICT","IDEMPOTENCY_MISMATCH","CREDIT_LIMIT","INFLIGHT_LIMIT","RATE_LIMITED","KEY_LIMIT","UPSTREAM","STORE_BUSY","STORE_UNAVAILABLE","MAINTENANCE","BAD_REQUEST","INTERNAL"]},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}},"headers":{"X-Request-Id":{"description":"Request identifier. Include this value when contacting support.","schema":{"type":"string"}},"Retry-After":{"description":"Minimum delay in seconds before retrying, when present. Some dependency failures omit this header; use exponential backoff with jitter.","schema":{"type":"integer"}}}},"default":{"description":"Other API error. Inspect the HTTP status and error envelope; request parsing can return 400, 413 or 415.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["UNAUTHENTICATED","FORBIDDEN","NETWORK_RESTRICTED","FROZEN","PARTNER_SUSPENDED","QUOTA","NOT_FOUND","VALIDATION","CONFLICT","IDEMPOTENCY_MISMATCH","CREDIT_LIMIT","INFLIGHT_LIMIT","RATE_LIMITED","KEY_LIMIT","UPSTREAM","STORE_BUSY","STORE_UNAVAILABLE","MAINTENANCE","BAD_REQUEST","INTERNAL"]},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}},"headers":{"X-Request-Id":{"description":"Request identifier. Include this value when contacting support.","schema":{"type":"string"}}}}},"operationId":"get_servers_id_backups"},"post":{"tags":["Backups"],"summary":"Create a backup","description":"Creates a backup of the server disk. Requires an active or suspended server and backups.enabled=true for its plan. The current plan setting is enforced on every request. When task.id is null, poll the server backup list to track completion.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"example":"srv_01J8Z3M4N5P6Q7R8S9T0V1W2X3","description":"Server identifier returned by the API."}],"responses":{"202":{"description":"Backup task accepted.","content":{"application/json":{"schema":{"type":"object","properties":{"task":{"type":"object","properties":{"id":{"anyOf":[{"type":"integer"},{"type":"null"}],"description":"Task identifier for polling, or null when the operation returned no task."},"action":{"type":"string","description":"Operation performed by this task."},"status":{"type":"string","description":"Task status: pending or running is incomplete; done is success; failed or canceled is unsuccessful. Treat unknown values as unresolved."},"server_id":{"type":"string","description":"Associated server ID, included when retrieving a task."}},"required":["id","action","status"],"additionalProperties":false}},"required":["task"],"additionalProperties":false},"example":{"task":{"id":null,"action":"vm-backup","status":"pending"}}}},"headers":{"X-Request-Id":{"description":"Request identifier. Include this value when contacting support.","schema":{"type":"string"}}}},"401":{"description":"Authentication failed. The API key is missing, invalid or revoked, or API access is not approved.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["UNAUTHENTICATED","FORBIDDEN","NETWORK_RESTRICTED","FROZEN","PARTNER_SUSPENDED","QUOTA","NOT_FOUND","VALIDATION","CONFLICT","IDEMPOTENCY_MISMATCH","CREDIT_LIMIT","INFLIGHT_LIMIT","RATE_LIMITED","KEY_LIMIT","UPSTREAM","STORE_BUSY","STORE_UNAVAILABLE","MAINTENANCE","BAD_REQUEST","INTERNAL"]},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}},"headers":{"X-Request-Id":{"description":"Request identifier. Include this value when contacting support.","schema":{"type":"string"}},"WWW-Authenticate":{"description":"Bearer authentication challenge.","schema":{"type":"string"}}}},"403":{"description":"FORBIDDEN with details.reason=backups_disabled: the plan disables backups or its configuration is missing. NETWORK_RESTRICTED: the request source is outside this deployment's approved IP networks.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["UNAUTHENTICATED","FORBIDDEN","NETWORK_RESTRICTED","FROZEN","PARTNER_SUSPENDED","QUOTA","NOT_FOUND","VALIDATION","CONFLICT","IDEMPOTENCY_MISMATCH","CREDIT_LIMIT","INFLIGHT_LIMIT","RATE_LIMITED","KEY_LIMIT","UPSTREAM","STORE_BUSY","STORE_UNAVAILABLE","MAINTENANCE","BAD_REQUEST","INTERNAL"]},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}},"headers":{"X-Request-Id":{"description":"Request identifier. Include this value when contacting support.","schema":{"type":"string"}}}},"404":{"description":"Server not found.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["UNAUTHENTICATED","FORBIDDEN","NETWORK_RESTRICTED","FROZEN","PARTNER_SUSPENDED","QUOTA","NOT_FOUND","VALIDATION","CONFLICT","IDEMPOTENCY_MISMATCH","CREDIT_LIMIT","INFLIGHT_LIMIT","RATE_LIMITED","KEY_LIMIT","UPSTREAM","STORE_BUSY","STORE_UNAVAILABLE","MAINTENANCE","BAD_REQUEST","INTERNAL"]},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}},"headers":{"X-Request-Id":{"description":"Request identifier. Include this value when contacting support.","schema":{"type":"string"}}}},"409":{"description":"CONFLICT: server is not active or suspended.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["UNAUTHENTICATED","FORBIDDEN","NETWORK_RESTRICTED","FROZEN","PARTNER_SUSPENDED","QUOTA","NOT_FOUND","VALIDATION","CONFLICT","IDEMPOTENCY_MISMATCH","CREDIT_LIMIT","INFLIGHT_LIMIT","RATE_LIMITED","KEY_LIMIT","UPSTREAM","STORE_BUSY","STORE_UNAVAILABLE","MAINTENANCE","BAD_REQUEST","INTERNAL"]},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}},"headers":{"X-Request-Id":{"description":"Request identifier. Include this value when contacting support.","schema":{"type":"string"}}}},"429":{"description":"Rate limit exceeded. See Retry-After before retrying.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["UNAUTHENTICATED","FORBIDDEN","NETWORK_RESTRICTED","FROZEN","PARTNER_SUSPENDED","QUOTA","NOT_FOUND","VALIDATION","CONFLICT","IDEMPOTENCY_MISMATCH","CREDIT_LIMIT","INFLIGHT_LIMIT","RATE_LIMITED","KEY_LIMIT","UPSTREAM","STORE_BUSY","STORE_UNAVAILABLE","MAINTENANCE","BAD_REQUEST","INTERNAL"]},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}},"headers":{"X-Request-Id":{"description":"Request identifier. Include this value when contacting support.","schema":{"type":"string"}},"Retry-After":{"description":"Minimum delay in seconds before retrying, when present. Some dependency failures omit this header; use exponential backoff with jitter.","schema":{"type":"integer"}}}},"500":{"description":"INTERNAL: unexpected server error. Retain X-Request-Id for support; resolve the outcome before repeating a write.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["UNAUTHENTICATED","FORBIDDEN","NETWORK_RESTRICTED","FROZEN","PARTNER_SUSPENDED","QUOTA","NOT_FOUND","VALIDATION","CONFLICT","IDEMPOTENCY_MISMATCH","CREDIT_LIMIT","INFLIGHT_LIMIT","RATE_LIMITED","KEY_LIMIT","UPSTREAM","STORE_BUSY","STORE_UNAVAILABLE","MAINTENANCE","BAD_REQUEST","INTERNAL"]},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}},"headers":{"X-Request-Id":{"description":"Request identifier. Include this value when contacting support.","schema":{"type":"string"}}}},"503":{"description":"Service temporarily unavailable: MAINTENANCE, STORE_BUSY, STORE_UNAVAILABLE or UPSTREAM.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["UNAUTHENTICATED","FORBIDDEN","NETWORK_RESTRICTED","FROZEN","PARTNER_SUSPENDED","QUOTA","NOT_FOUND","VALIDATION","CONFLICT","IDEMPOTENCY_MISMATCH","CREDIT_LIMIT","INFLIGHT_LIMIT","RATE_LIMITED","KEY_LIMIT","UPSTREAM","STORE_BUSY","STORE_UNAVAILABLE","MAINTENANCE","BAD_REQUEST","INTERNAL"]},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}},"headers":{"X-Request-Id":{"description":"Request identifier. Include this value when contacting support.","schema":{"type":"string"}},"Retry-After":{"description":"Minimum delay in seconds before retrying, when present. Some dependency failures omit this header; use exponential backoff with jitter.","schema":{"type":"integer"}}}},"default":{"description":"Other API error. Inspect the HTTP status and error envelope; request parsing can return 400, 413 or 415.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["UNAUTHENTICATED","FORBIDDEN","NETWORK_RESTRICTED","FROZEN","PARTNER_SUSPENDED","QUOTA","NOT_FOUND","VALIDATION","CONFLICT","IDEMPOTENCY_MISMATCH","CREDIT_LIMIT","INFLIGHT_LIMIT","RATE_LIMITED","KEY_LIMIT","UPSTREAM","STORE_BUSY","STORE_UNAVAILABLE","MAINTENANCE","BAD_REQUEST","INTERNAL"]},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}},"headers":{"X-Request-Id":{"description":"Request identifier. Include this value when contacting support.","schema":{"type":"string"}}}}},"operationId":"post_servers_id_backups"}},"/servers/{id}/backups/{bid}/restore":{"post":{"tags":["Backups"],"summary":"Restore a backup","description":"Overwrites the server disk with this backup. The backup must belong to the server. Requires an active or suspended server and backups.enabled=true for its plan, enforced on every request. This operation does not create a new server.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"example":"srv_01J8Z3M4N5P6Q7R8S9T0V1W2X3","description":"Server identifier returned by the API."},{"name":"bid","in":"path","required":true,"schema":{"type":"integer","minimum":1},"example":7,"description":"Backup identifier returned by the server's backup list."}],"responses":{"202":{"description":"Restore task accepted.","content":{"application/json":{"schema":{"type":"object","properties":{"task":{"type":"object","properties":{"id":{"anyOf":[{"type":"integer"},{"type":"null"}],"description":"Task identifier for polling, or null when the operation returned no task."},"action":{"type":"string","description":"Operation performed by this task."},"status":{"type":"string","description":"Task status: pending or running is incomplete; done is success; failed or canceled is unsuccessful. Treat unknown values as unresolved."},"server_id":{"type":"string","description":"Associated server ID, included when retrieving a task."}},"required":["id","action","status"],"additionalProperties":false}},"required":["task"],"additionalProperties":false},"example":{"task":{"id":90212,"action":"vm-restore","status":"pending"}}}},"headers":{"X-Request-Id":{"description":"Request identifier. Include this value when contacting support.","schema":{"type":"string"}}}},"401":{"description":"Authentication failed. The API key is missing, invalid or revoked, or API access is not approved.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["UNAUTHENTICATED","FORBIDDEN","NETWORK_RESTRICTED","FROZEN","PARTNER_SUSPENDED","QUOTA","NOT_FOUND","VALIDATION","CONFLICT","IDEMPOTENCY_MISMATCH","CREDIT_LIMIT","INFLIGHT_LIMIT","RATE_LIMITED","KEY_LIMIT","UPSTREAM","STORE_BUSY","STORE_UNAVAILABLE","MAINTENANCE","BAD_REQUEST","INTERNAL"]},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}},"headers":{"X-Request-Id":{"description":"Request identifier. Include this value when contacting support.","schema":{"type":"string"}},"WWW-Authenticate":{"description":"Bearer authentication challenge.","schema":{"type":"string"}}}},"403":{"description":"FORBIDDEN with details.reason=backups_disabled: the plan disables backups or its configuration is missing. NETWORK_RESTRICTED: the request source is outside this deployment's approved IP networks.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["UNAUTHENTICATED","FORBIDDEN","NETWORK_RESTRICTED","FROZEN","PARTNER_SUSPENDED","QUOTA","NOT_FOUND","VALIDATION","CONFLICT","IDEMPOTENCY_MISMATCH","CREDIT_LIMIT","INFLIGHT_LIMIT","RATE_LIMITED","KEY_LIMIT","UPSTREAM","STORE_BUSY","STORE_UNAVAILABLE","MAINTENANCE","BAD_REQUEST","INTERNAL"]},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}},"headers":{"X-Request-Id":{"description":"Request identifier. Include this value when contacting support.","schema":{"type":"string"}}}},"404":{"description":"Server or backup not found.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["UNAUTHENTICATED","FORBIDDEN","NETWORK_RESTRICTED","FROZEN","PARTNER_SUSPENDED","QUOTA","NOT_FOUND","VALIDATION","CONFLICT","IDEMPOTENCY_MISMATCH","CREDIT_LIMIT","INFLIGHT_LIMIT","RATE_LIMITED","KEY_LIMIT","UPSTREAM","STORE_BUSY","STORE_UNAVAILABLE","MAINTENANCE","BAD_REQUEST","INTERNAL"]},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}},"headers":{"X-Request-Id":{"description":"Request identifier. Include this value when contacting support.","schema":{"type":"string"}}}},"409":{"description":"CONFLICT: server is not active or suspended.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["UNAUTHENTICATED","FORBIDDEN","NETWORK_RESTRICTED","FROZEN","PARTNER_SUSPENDED","QUOTA","NOT_FOUND","VALIDATION","CONFLICT","IDEMPOTENCY_MISMATCH","CREDIT_LIMIT","INFLIGHT_LIMIT","RATE_LIMITED","KEY_LIMIT","UPSTREAM","STORE_BUSY","STORE_UNAVAILABLE","MAINTENANCE","BAD_REQUEST","INTERNAL"]},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}},"headers":{"X-Request-Id":{"description":"Request identifier. Include this value when contacting support.","schema":{"type":"string"}}}},"429":{"description":"Rate limit exceeded. See Retry-After before retrying.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["UNAUTHENTICATED","FORBIDDEN","NETWORK_RESTRICTED","FROZEN","PARTNER_SUSPENDED","QUOTA","NOT_FOUND","VALIDATION","CONFLICT","IDEMPOTENCY_MISMATCH","CREDIT_LIMIT","INFLIGHT_LIMIT","RATE_LIMITED","KEY_LIMIT","UPSTREAM","STORE_BUSY","STORE_UNAVAILABLE","MAINTENANCE","BAD_REQUEST","INTERNAL"]},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}},"headers":{"X-Request-Id":{"description":"Request identifier. Include this value when contacting support.","schema":{"type":"string"}},"Retry-After":{"description":"Minimum delay in seconds before retrying, when present. Some dependency failures omit this header; use exponential backoff with jitter.","schema":{"type":"integer"}}}},"500":{"description":"INTERNAL: unexpected server error. Retain X-Request-Id for support; resolve the outcome before repeating a write.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["UNAUTHENTICATED","FORBIDDEN","NETWORK_RESTRICTED","FROZEN","PARTNER_SUSPENDED","QUOTA","NOT_FOUND","VALIDATION","CONFLICT","IDEMPOTENCY_MISMATCH","CREDIT_LIMIT","INFLIGHT_LIMIT","RATE_LIMITED","KEY_LIMIT","UPSTREAM","STORE_BUSY","STORE_UNAVAILABLE","MAINTENANCE","BAD_REQUEST","INTERNAL"]},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}},"headers":{"X-Request-Id":{"description":"Request identifier. Include this value when contacting support.","schema":{"type":"string"}}}},"503":{"description":"Service temporarily unavailable: MAINTENANCE, STORE_BUSY, STORE_UNAVAILABLE or UPSTREAM.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["UNAUTHENTICATED","FORBIDDEN","NETWORK_RESTRICTED","FROZEN","PARTNER_SUSPENDED","QUOTA","NOT_FOUND","VALIDATION","CONFLICT","IDEMPOTENCY_MISMATCH","CREDIT_LIMIT","INFLIGHT_LIMIT","RATE_LIMITED","KEY_LIMIT","UPSTREAM","STORE_BUSY","STORE_UNAVAILABLE","MAINTENANCE","BAD_REQUEST","INTERNAL"]},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}},"headers":{"X-Request-Id":{"description":"Request identifier. Include this value when contacting support.","schema":{"type":"string"}},"Retry-After":{"description":"Minimum delay in seconds before retrying, when present. Some dependency failures omit this header; use exponential backoff with jitter.","schema":{"type":"integer"}}}},"default":{"description":"Other API error. Inspect the HTTP status and error envelope; request parsing can return 400, 413 or 415.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["UNAUTHENTICATED","FORBIDDEN","NETWORK_RESTRICTED","FROZEN","PARTNER_SUSPENDED","QUOTA","NOT_FOUND","VALIDATION","CONFLICT","IDEMPOTENCY_MISMATCH","CREDIT_LIMIT","INFLIGHT_LIMIT","RATE_LIMITED","KEY_LIMIT","UPSTREAM","STORE_BUSY","STORE_UNAVAILABLE","MAINTENANCE","BAD_REQUEST","INTERNAL"]},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}},"headers":{"X-Request-Id":{"description":"Request identifier. Include this value when contacting support.","schema":{"type":"string"}}}}},"operationId":"post_servers_id_backups_bid_restore"}},"/tasks/{id}":{"get":{"tags":["Tasks"],"summary":"Retrieve a task","description":"Returns a task associated with a server in the authenticated account. Task IDs are integers; server IDs are strings. done indicates success, failed or canceled is unsuccessful, and pending or running is incomplete. Poll at intervals of five seconds or longer. action is the platform task name and can differ from the submitted action, for example vm-restart for reboot.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer","minimum":1},"example":90210,"description":"Task identifier returned by an asynchronous operation."}],"responses":{"200":{"description":"Task details.","content":{"application/json":{"schema":{"type":"object","properties":{"task":{"type":"object","properties":{"id":{"anyOf":[{"type":"integer"},{"type":"null"}],"description":"Task identifier for polling, or null when the operation returned no task."},"action":{"type":"string","description":"Operation performed by this task."},"status":{"type":"string","description":"Task status: pending or running is incomplete; done is success; failed or canceled is unsuccessful. Treat unknown values as unresolved."},"server_id":{"type":"string","description":"Associated server ID, included when retrieving a task."}},"required":["id","action","status"],"additionalProperties":false}},"required":["task"],"additionalProperties":false},"example":{"task":{"id":90210,"action":"vm-restart","status":"done","server_id":"srv_01J8Z3M4N5P6Q7R8S9T0V1W2X3"}}}},"headers":{"X-Request-Id":{"description":"Request identifier. Include this value when contacting support.","schema":{"type":"string"}}}},"401":{"description":"Authentication failed. The API key is missing, invalid or revoked, or API access is not approved.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["UNAUTHENTICATED","FORBIDDEN","NETWORK_RESTRICTED","FROZEN","PARTNER_SUSPENDED","QUOTA","NOT_FOUND","VALIDATION","CONFLICT","IDEMPOTENCY_MISMATCH","CREDIT_LIMIT","INFLIGHT_LIMIT","RATE_LIMITED","KEY_LIMIT","UPSTREAM","STORE_BUSY","STORE_UNAVAILABLE","MAINTENANCE","BAD_REQUEST","INTERNAL"]},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}},"headers":{"X-Request-Id":{"description":"Request identifier. Include this value when contacting support.","schema":{"type":"string"}},"WWW-Authenticate":{"description":"Bearer authentication challenge.","schema":{"type":"string"}}}},"403":{"description":"NETWORK_RESTRICTED: the request source is outside this deployment's approved IP networks.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["UNAUTHENTICATED","FORBIDDEN","NETWORK_RESTRICTED","FROZEN","PARTNER_SUSPENDED","QUOTA","NOT_FOUND","VALIDATION","CONFLICT","IDEMPOTENCY_MISMATCH","CREDIT_LIMIT","INFLIGHT_LIMIT","RATE_LIMITED","KEY_LIMIT","UPSTREAM","STORE_BUSY","STORE_UNAVAILABLE","MAINTENANCE","BAD_REQUEST","INTERNAL"]},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}},"headers":{"X-Request-Id":{"description":"Request identifier. Include this value when contacting support.","schema":{"type":"string"}}}},"404":{"description":"Task not found in this account.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["UNAUTHENTICATED","FORBIDDEN","NETWORK_RESTRICTED","FROZEN","PARTNER_SUSPENDED","QUOTA","NOT_FOUND","VALIDATION","CONFLICT","IDEMPOTENCY_MISMATCH","CREDIT_LIMIT","INFLIGHT_LIMIT","RATE_LIMITED","KEY_LIMIT","UPSTREAM","STORE_BUSY","STORE_UNAVAILABLE","MAINTENANCE","BAD_REQUEST","INTERNAL"]},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}},"headers":{"X-Request-Id":{"description":"Request identifier. Include this value when contacting support.","schema":{"type":"string"}}}},"429":{"description":"Rate limit exceeded. See Retry-After before retrying.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["UNAUTHENTICATED","FORBIDDEN","NETWORK_RESTRICTED","FROZEN","PARTNER_SUSPENDED","QUOTA","NOT_FOUND","VALIDATION","CONFLICT","IDEMPOTENCY_MISMATCH","CREDIT_LIMIT","INFLIGHT_LIMIT","RATE_LIMITED","KEY_LIMIT","UPSTREAM","STORE_BUSY","STORE_UNAVAILABLE","MAINTENANCE","BAD_REQUEST","INTERNAL"]},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}},"headers":{"X-Request-Id":{"description":"Request identifier. Include this value when contacting support.","schema":{"type":"string"}},"Retry-After":{"description":"Minimum delay in seconds before retrying, when present. Some dependency failures omit this header; use exponential backoff with jitter.","schema":{"type":"integer"}}}},"500":{"description":"INTERNAL: unexpected server error. Retain X-Request-Id for support; resolve the outcome before repeating a write.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["UNAUTHENTICATED","FORBIDDEN","NETWORK_RESTRICTED","FROZEN","PARTNER_SUSPENDED","QUOTA","NOT_FOUND","VALIDATION","CONFLICT","IDEMPOTENCY_MISMATCH","CREDIT_LIMIT","INFLIGHT_LIMIT","RATE_LIMITED","KEY_LIMIT","UPSTREAM","STORE_BUSY","STORE_UNAVAILABLE","MAINTENANCE","BAD_REQUEST","INTERNAL"]},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}},"headers":{"X-Request-Id":{"description":"Request identifier. Include this value when contacting support.","schema":{"type":"string"}}}},"503":{"description":"Service temporarily unavailable: MAINTENANCE, STORE_BUSY, STORE_UNAVAILABLE or UPSTREAM.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["UNAUTHENTICATED","FORBIDDEN","NETWORK_RESTRICTED","FROZEN","PARTNER_SUSPENDED","QUOTA","NOT_FOUND","VALIDATION","CONFLICT","IDEMPOTENCY_MISMATCH","CREDIT_LIMIT","INFLIGHT_LIMIT","RATE_LIMITED","KEY_LIMIT","UPSTREAM","STORE_BUSY","STORE_UNAVAILABLE","MAINTENANCE","BAD_REQUEST","INTERNAL"]},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}},"headers":{"X-Request-Id":{"description":"Request identifier. Include this value when contacting support.","schema":{"type":"string"}},"Retry-After":{"description":"Minimum delay in seconds before retrying, when present. Some dependency failures omit this header; use exponential backoff with jitter.","schema":{"type":"integer"}}}},"default":{"description":"Other API error. Inspect the HTTP status and error envelope; request parsing can return 400, 413 or 415.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["UNAUTHENTICATED","FORBIDDEN","NETWORK_RESTRICTED","FROZEN","PARTNER_SUSPENDED","QUOTA","NOT_FOUND","VALIDATION","CONFLICT","IDEMPOTENCY_MISMATCH","CREDIT_LIMIT","INFLIGHT_LIMIT","RATE_LIMITED","KEY_LIMIT","UPSTREAM","STORE_BUSY","STORE_UNAVAILABLE","MAINTENANCE","BAD_REQUEST","INTERNAL"]},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}},"headers":{"X-Request-Id":{"description":"Request identifier. Include this value when contacting support.","schema":{"type":"string"}}}}},"operationId":"get_tasks_id"}},"/ssh-keys":{"get":{"tags":["SSH keys"],"summary":"List SSH keys","responses":{"200":{"description":"Registered SSH public keys.","content":{"application/json":{"schema":{"type":"object","properties":{"ssh_keys":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer"},"name":{"type":"string"},"body":{"type":"string"}},"required":["id","name","body"],"additionalProperties":false}}},"required":["ssh_keys"],"additionalProperties":false},"example":{"ssh_keys":[{"id":123,"name":"deploy","body":"ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIAEBAQEBAQEBAQEBAQEBAQEBAQEBAQEBAQEBAQEBAQEB deploy@example.com"}]}}},"headers":{"X-Request-Id":{"description":"Request identifier. Include this value when contacting support.","schema":{"type":"string"}}}},"401":{"description":"Authentication failed. The API key is missing, invalid or revoked, or API access is not approved.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["UNAUTHENTICATED","FORBIDDEN","NETWORK_RESTRICTED","FROZEN","PARTNER_SUSPENDED","QUOTA","NOT_FOUND","VALIDATION","CONFLICT","IDEMPOTENCY_MISMATCH","CREDIT_LIMIT","INFLIGHT_LIMIT","RATE_LIMITED","KEY_LIMIT","UPSTREAM","STORE_BUSY","STORE_UNAVAILABLE","MAINTENANCE","BAD_REQUEST","INTERNAL"]},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}},"headers":{"X-Request-Id":{"description":"Request identifier. Include this value when contacting support.","schema":{"type":"string"}},"WWW-Authenticate":{"description":"Bearer authentication challenge.","schema":{"type":"string"}}}},"403":{"description":"NETWORK_RESTRICTED: the request source is outside this deployment's approved IP networks.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["UNAUTHENTICATED","FORBIDDEN","NETWORK_RESTRICTED","FROZEN","PARTNER_SUSPENDED","QUOTA","NOT_FOUND","VALIDATION","CONFLICT","IDEMPOTENCY_MISMATCH","CREDIT_LIMIT","INFLIGHT_LIMIT","RATE_LIMITED","KEY_LIMIT","UPSTREAM","STORE_BUSY","STORE_UNAVAILABLE","MAINTENANCE","BAD_REQUEST","INTERNAL"]},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}},"headers":{"X-Request-Id":{"description":"Request identifier. Include this value when contacting support.","schema":{"type":"string"}}}},"429":{"description":"Rate limit exceeded. See Retry-After before retrying.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["UNAUTHENTICATED","FORBIDDEN","NETWORK_RESTRICTED","FROZEN","PARTNER_SUSPENDED","QUOTA","NOT_FOUND","VALIDATION","CONFLICT","IDEMPOTENCY_MISMATCH","CREDIT_LIMIT","INFLIGHT_LIMIT","RATE_LIMITED","KEY_LIMIT","UPSTREAM","STORE_BUSY","STORE_UNAVAILABLE","MAINTENANCE","BAD_REQUEST","INTERNAL"]},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}},"headers":{"X-Request-Id":{"description":"Request identifier. Include this value when contacting support.","schema":{"type":"string"}},"Retry-After":{"description":"Minimum delay in seconds before retrying, when present. Some dependency failures omit this header; use exponential backoff with jitter.","schema":{"type":"integer"}}}},"500":{"description":"INTERNAL: unexpected server error. Retain X-Request-Id for support; resolve the outcome before repeating a write.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["UNAUTHENTICATED","FORBIDDEN","NETWORK_RESTRICTED","FROZEN","PARTNER_SUSPENDED","QUOTA","NOT_FOUND","VALIDATION","CONFLICT","IDEMPOTENCY_MISMATCH","CREDIT_LIMIT","INFLIGHT_LIMIT","RATE_LIMITED","KEY_LIMIT","UPSTREAM","STORE_BUSY","STORE_UNAVAILABLE","MAINTENANCE","BAD_REQUEST","INTERNAL"]},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}},"headers":{"X-Request-Id":{"description":"Request identifier. Include this value when contacting support.","schema":{"type":"string"}}}},"503":{"description":"Service temporarily unavailable: MAINTENANCE, STORE_BUSY, STORE_UNAVAILABLE or UPSTREAM.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["UNAUTHENTICATED","FORBIDDEN","NETWORK_RESTRICTED","FROZEN","PARTNER_SUSPENDED","QUOTA","NOT_FOUND","VALIDATION","CONFLICT","IDEMPOTENCY_MISMATCH","CREDIT_LIMIT","INFLIGHT_LIMIT","RATE_LIMITED","KEY_LIMIT","UPSTREAM","STORE_BUSY","STORE_UNAVAILABLE","MAINTENANCE","BAD_REQUEST","INTERNAL"]},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}},"headers":{"X-Request-Id":{"description":"Request identifier. Include this value when contacting support.","schema":{"type":"string"}},"Retry-After":{"description":"Minimum delay in seconds before retrying, when present. Some dependency failures omit this header; use exponential backoff with jitter.","schema":{"type":"integer"}}}},"default":{"description":"Other API error. Inspect the HTTP status and error envelope; request parsing can return 400, 413 or 415.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["UNAUTHENTICATED","FORBIDDEN","NETWORK_RESTRICTED","FROZEN","PARTNER_SUSPENDED","QUOTA","NOT_FOUND","VALIDATION","CONFLICT","IDEMPOTENCY_MISMATCH","CREDIT_LIMIT","INFLIGHT_LIMIT","RATE_LIMITED","KEY_LIMIT","UPSTREAM","STORE_BUSY","STORE_UNAVAILABLE","MAINTENANCE","BAD_REQUEST","INTERNAL"]},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}},"headers":{"X-Request-Id":{"description":"Request identifier. Include this value when contacting support.","schema":{"type":"string"}}}}},"operationId":"get_ssh_keys"},"post":{"tags":["SSH keys"],"summary":"Register an SSH key","description":"Registers an OpenSSH public key for use in create and rebuild requests. Supports Ed25519, RSA and ECDSA public keys. Submit the complete public key, never its private key.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":64,"description":"Display name for the SSH public key."},"body":{"type":"string","minLength":20,"maxLength":8192,"pattern":"^(ssh-(rsa|ed25519)|ecdsa-sha2-nistp\\d+) ","description":"Complete OpenSSH public key, including its key type and base64-encoded key data."}},"required":["name","body"],"additionalProperties":false},"examples":{"register":{"summary":"Register an SSH public key","value":{"name":"deploy","body":"ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIAEBAQEBAQEBAQEBAQEBAQEBAQEBAQEBAQEBAQEBAQEB deploy@example.com"}}}}}},"responses":{"201":{"description":"SSH public key registered.","content":{"application/json":{"schema":{"type":"object","properties":{"ssh_key":{"type":"object","properties":{"id":{"type":"integer"},"name":{"type":"string"},"body":{"type":"string"}},"required":["id","name","body"],"additionalProperties":false}},"required":["ssh_key"],"additionalProperties":false},"example":{"ssh_key":{"id":123,"name":"deploy","body":"ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIAEBAQEBAQEBAQEBAQEBAQEBAQEBAQEBAQEBAQEBAQEB deploy@example.com"}}}},"headers":{"X-Request-Id":{"description":"Request identifier. Include this value when contacting support.","schema":{"type":"string"}}}},"401":{"description":"Authentication failed. The API key is missing, invalid or revoked, or API access is not approved.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["UNAUTHENTICATED","FORBIDDEN","NETWORK_RESTRICTED","FROZEN","PARTNER_SUSPENDED","QUOTA","NOT_FOUND","VALIDATION","CONFLICT","IDEMPOTENCY_MISMATCH","CREDIT_LIMIT","INFLIGHT_LIMIT","RATE_LIMITED","KEY_LIMIT","UPSTREAM","STORE_BUSY","STORE_UNAVAILABLE","MAINTENANCE","BAD_REQUEST","INTERNAL"]},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}},"headers":{"X-Request-Id":{"description":"Request identifier. Include this value when contacting support.","schema":{"type":"string"}},"WWW-Authenticate":{"description":"Bearer authentication challenge.","schema":{"type":"string"}}}},"403":{"description":"NETWORK_RESTRICTED: the request source is outside this deployment's approved IP networks.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["UNAUTHENTICATED","FORBIDDEN","NETWORK_RESTRICTED","FROZEN","PARTNER_SUSPENDED","QUOTA","NOT_FOUND","VALIDATION","CONFLICT","IDEMPOTENCY_MISMATCH","CREDIT_LIMIT","INFLIGHT_LIMIT","RATE_LIMITED","KEY_LIMIT","UPSTREAM","STORE_BUSY","STORE_UNAVAILABLE","MAINTENANCE","BAD_REQUEST","INTERNAL"]},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}},"headers":{"X-Request-Id":{"description":"Request identifier. Include this value when contacting support.","schema":{"type":"string"}}}},"422":{"description":"Invalid SSH public key or name.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["UNAUTHENTICATED","FORBIDDEN","NETWORK_RESTRICTED","FROZEN","PARTNER_SUSPENDED","QUOTA","NOT_FOUND","VALIDATION","CONFLICT","IDEMPOTENCY_MISMATCH","CREDIT_LIMIT","INFLIGHT_LIMIT","RATE_LIMITED","KEY_LIMIT","UPSTREAM","STORE_BUSY","STORE_UNAVAILABLE","MAINTENANCE","BAD_REQUEST","INTERNAL"]},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}},"headers":{"X-Request-Id":{"description":"Request identifier. Include this value when contacting support.","schema":{"type":"string"}}}},"429":{"description":"Rate limit exceeded. See Retry-After before retrying.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["UNAUTHENTICATED","FORBIDDEN","NETWORK_RESTRICTED","FROZEN","PARTNER_SUSPENDED","QUOTA","NOT_FOUND","VALIDATION","CONFLICT","IDEMPOTENCY_MISMATCH","CREDIT_LIMIT","INFLIGHT_LIMIT","RATE_LIMITED","KEY_LIMIT","UPSTREAM","STORE_BUSY","STORE_UNAVAILABLE","MAINTENANCE","BAD_REQUEST","INTERNAL"]},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}},"headers":{"X-Request-Id":{"description":"Request identifier. Include this value when contacting support.","schema":{"type":"string"}},"Retry-After":{"description":"Minimum delay in seconds before retrying, when present. Some dependency failures omit this header; use exponential backoff with jitter.","schema":{"type":"integer"}}}},"500":{"description":"INTERNAL: unexpected server error. Retain X-Request-Id for support; resolve the outcome before repeating a write.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["UNAUTHENTICATED","FORBIDDEN","NETWORK_RESTRICTED","FROZEN","PARTNER_SUSPENDED","QUOTA","NOT_FOUND","VALIDATION","CONFLICT","IDEMPOTENCY_MISMATCH","CREDIT_LIMIT","INFLIGHT_LIMIT","RATE_LIMITED","KEY_LIMIT","UPSTREAM","STORE_BUSY","STORE_UNAVAILABLE","MAINTENANCE","BAD_REQUEST","INTERNAL"]},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}},"headers":{"X-Request-Id":{"description":"Request identifier. Include this value when contacting support.","schema":{"type":"string"}}}},"503":{"description":"Service temporarily unavailable: MAINTENANCE, STORE_BUSY, STORE_UNAVAILABLE or UPSTREAM.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["UNAUTHENTICATED","FORBIDDEN","NETWORK_RESTRICTED","FROZEN","PARTNER_SUSPENDED","QUOTA","NOT_FOUND","VALIDATION","CONFLICT","IDEMPOTENCY_MISMATCH","CREDIT_LIMIT","INFLIGHT_LIMIT","RATE_LIMITED","KEY_LIMIT","UPSTREAM","STORE_BUSY","STORE_UNAVAILABLE","MAINTENANCE","BAD_REQUEST","INTERNAL"]},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}},"headers":{"X-Request-Id":{"description":"Request identifier. Include this value when contacting support.","schema":{"type":"string"}},"Retry-After":{"description":"Minimum delay in seconds before retrying, when present. Some dependency failures omit this header; use exponential backoff with jitter.","schema":{"type":"integer"}}}},"default":{"description":"Other API error. Inspect the HTTP status and error envelope; request parsing can return 400, 413 or 415.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["UNAUTHENTICATED","FORBIDDEN","NETWORK_RESTRICTED","FROZEN","PARTNER_SUSPENDED","QUOTA","NOT_FOUND","VALIDATION","CONFLICT","IDEMPOTENCY_MISMATCH","CREDIT_LIMIT","INFLIGHT_LIMIT","RATE_LIMITED","KEY_LIMIT","UPSTREAM","STORE_BUSY","STORE_UNAVAILABLE","MAINTENANCE","BAD_REQUEST","INTERNAL"]},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}},"headers":{"X-Request-Id":{"description":"Request identifier. Include this value when contacting support.","schema":{"type":"string"}}}}},"operationId":"post_ssh_keys"}},"/ssh-keys/{id}":{"delete":{"tags":["SSH keys"],"summary":"Delete an SSH key","description":"Removes the key from the account's registered keys. It does not remove keys already installed in existing servers.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer","minimum":1},"example":123,"description":"SSH key identifier."}],"responses":{"204":{"description":"SSH key deleted. No response body.","headers":{"X-Request-Id":{"description":"Request identifier. Include this value when contacting support.","schema":{"type":"string"}}}},"401":{"description":"Authentication failed. The API key is missing, invalid or revoked, or API access is not approved.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["UNAUTHENTICATED","FORBIDDEN","NETWORK_RESTRICTED","FROZEN","PARTNER_SUSPENDED","QUOTA","NOT_FOUND","VALIDATION","CONFLICT","IDEMPOTENCY_MISMATCH","CREDIT_LIMIT","INFLIGHT_LIMIT","RATE_LIMITED","KEY_LIMIT","UPSTREAM","STORE_BUSY","STORE_UNAVAILABLE","MAINTENANCE","BAD_REQUEST","INTERNAL"]},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}},"headers":{"X-Request-Id":{"description":"Request identifier. Include this value when contacting support.","schema":{"type":"string"}},"WWW-Authenticate":{"description":"Bearer authentication challenge.","schema":{"type":"string"}}}},"403":{"description":"NETWORK_RESTRICTED: the request source is outside this deployment's approved IP networks.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["UNAUTHENTICATED","FORBIDDEN","NETWORK_RESTRICTED","FROZEN","PARTNER_SUSPENDED","QUOTA","NOT_FOUND","VALIDATION","CONFLICT","IDEMPOTENCY_MISMATCH","CREDIT_LIMIT","INFLIGHT_LIMIT","RATE_LIMITED","KEY_LIMIT","UPSTREAM","STORE_BUSY","STORE_UNAVAILABLE","MAINTENANCE","BAD_REQUEST","INTERNAL"]},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}},"headers":{"X-Request-Id":{"description":"Request identifier. Include this value when contacting support.","schema":{"type":"string"}}}},"404":{"description":"SSH key not found.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["UNAUTHENTICATED","FORBIDDEN","NETWORK_RESTRICTED","FROZEN","PARTNER_SUSPENDED","QUOTA","NOT_FOUND","VALIDATION","CONFLICT","IDEMPOTENCY_MISMATCH","CREDIT_LIMIT","INFLIGHT_LIMIT","RATE_LIMITED","KEY_LIMIT","UPSTREAM","STORE_BUSY","STORE_UNAVAILABLE","MAINTENANCE","BAD_REQUEST","INTERNAL"]},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}},"headers":{"X-Request-Id":{"description":"Request identifier. Include this value when contacting support.","schema":{"type":"string"}}}},"429":{"description":"Rate limit exceeded. See Retry-After before retrying.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["UNAUTHENTICATED","FORBIDDEN","NETWORK_RESTRICTED","FROZEN","PARTNER_SUSPENDED","QUOTA","NOT_FOUND","VALIDATION","CONFLICT","IDEMPOTENCY_MISMATCH","CREDIT_LIMIT","INFLIGHT_LIMIT","RATE_LIMITED","KEY_LIMIT","UPSTREAM","STORE_BUSY","STORE_UNAVAILABLE","MAINTENANCE","BAD_REQUEST","INTERNAL"]},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}},"headers":{"X-Request-Id":{"description":"Request identifier. Include this value when contacting support.","schema":{"type":"string"}},"Retry-After":{"description":"Minimum delay in seconds before retrying, when present. Some dependency failures omit this header; use exponential backoff with jitter.","schema":{"type":"integer"}}}},"500":{"description":"INTERNAL: unexpected server error. Retain X-Request-Id for support; resolve the outcome before repeating a write.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["UNAUTHENTICATED","FORBIDDEN","NETWORK_RESTRICTED","FROZEN","PARTNER_SUSPENDED","QUOTA","NOT_FOUND","VALIDATION","CONFLICT","IDEMPOTENCY_MISMATCH","CREDIT_LIMIT","INFLIGHT_LIMIT","RATE_LIMITED","KEY_LIMIT","UPSTREAM","STORE_BUSY","STORE_UNAVAILABLE","MAINTENANCE","BAD_REQUEST","INTERNAL"]},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}},"headers":{"X-Request-Id":{"description":"Request identifier. Include this value when contacting support.","schema":{"type":"string"}}}},"503":{"description":"Service temporarily unavailable: MAINTENANCE, STORE_BUSY, STORE_UNAVAILABLE or UPSTREAM.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["UNAUTHENTICATED","FORBIDDEN","NETWORK_RESTRICTED","FROZEN","PARTNER_SUSPENDED","QUOTA","NOT_FOUND","VALIDATION","CONFLICT","IDEMPOTENCY_MISMATCH","CREDIT_LIMIT","INFLIGHT_LIMIT","RATE_LIMITED","KEY_LIMIT","UPSTREAM","STORE_BUSY","STORE_UNAVAILABLE","MAINTENANCE","BAD_REQUEST","INTERNAL"]},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}},"headers":{"X-Request-Id":{"description":"Request identifier. Include this value when contacting support.","schema":{"type":"string"}},"Retry-After":{"description":"Minimum delay in seconds before retrying, when present. Some dependency failures omit this header; use exponential backoff with jitter.","schema":{"type":"integer"}}}},"default":{"description":"Other API error. Inspect the HTTP status and error envelope; request parsing can return 400, 413 or 415.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["UNAUTHENTICATED","FORBIDDEN","NETWORK_RESTRICTED","FROZEN","PARTNER_SUSPENDED","QUOTA","NOT_FOUND","VALIDATION","CONFLICT","IDEMPOTENCY_MISMATCH","CREDIT_LIMIT","INFLIGHT_LIMIT","RATE_LIMITED","KEY_LIMIT","UPSTREAM","STORE_BUSY","STORE_UNAVAILABLE","MAINTENANCE","BAD_REQUEST","INTERNAL"]},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}},"headers":{"X-Request-Id":{"description":"Request identifier. Include this value when contacting support.","schema":{"type":"string"}}}}},"operationId":"delete_ssh_keys_id"}},"/events":{"get":{"tags":["Events"],"summary":"List events","description":"Returns account events in ascending ID order. Use after to resume from the last processed event. Webhook test events are excluded. Poll at intervals of 10 seconds or longer, or use webhooks for delivery and this endpoint for recovery.","parameters":[{"name":"after","in":"query","required":false,"schema":{"type":"integer","minimum":0,"description":"Return events with an ID greater than this cursor."},"description":"Return events with an ID greater than this cursor."},{"name":"type","in":"query","required":false,"schema":{"type":"string","enum":["api_access.requested","api_access.reviewed","api_access.migrated","api_key.issued","api_key.revoked","server.requested","server.provisioning","server.active","server.ssh_ready","server.provision_failed","server.create_ambiguous","server.destroy_requested","server.destroyed","server.destroy_failed","server.action","server.rebuild_requested","server.rebuilt","server.rebuild_failed","server.updated","server.suspended","server.unsuspended","server.orphaned","server.adopted","backup.requested","backup.restore_requested","backup.deleted","partner.suspended","partner.unsuspended","partner.frozen","partner.unfrozen","partner.billed","webhook.test"],"description":"Filter by event type."},"description":"Filter by event type."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":100,"default":50,"description":"Maximum number of events to return."},"description":"Maximum number of events to return."}],"responses":{"200":{"description":"Event list.","content":{"application/json":{"schema":{"type":"object","properties":{"events":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer","description":"Event identifier. Use for deduplication and pagination."},"type":{"type":"string","enum":["api_access.requested","api_access.reviewed","api_access.migrated","api_key.issued","api_key.revoked","server.requested","server.provisioning","server.active","server.ssh_ready","server.provision_failed","server.create_ambiguous","server.destroy_requested","server.destroyed","server.destroy_failed","server.action","server.rebuild_requested","server.rebuilt","server.rebuild_failed","server.updated","server.suspended","server.unsuspended","server.orphaned","server.adopted","backup.requested","backup.restore_requested","backup.deleted","partner.suspended","partner.unsuspended","partner.frozen","partner.unfrozen","partner.billed","webhook.test"]},"at":{"type":"string","format":"date-time"},"server_id":{"type":["string","null"]},"data":{"type":"object","additionalProperties":{}}},"required":["id","type","at","server_id","data"],"additionalProperties":false}},"next_after":{"anyOf":[{"type":"integer"},{"type":"null"}]}},"required":["events","next_after"],"additionalProperties":false},"example":{"events":[{"id":1042,"type":"server.active","at":"2026-09-09T00:00:30.000Z","server_id":"srv_01J8Z3M4N5P6Q7R8S9T0V1W2X3","data":{"ipv4":"203.0.113.10","seconds_since_request":30}}],"next_after":null}}},"headers":{"X-Request-Id":{"description":"Request identifier. Include this value when contacting support.","schema":{"type":"string"}}}},"401":{"description":"Authentication failed. The API key is missing, invalid or revoked, or API access is not approved.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["UNAUTHENTICATED","FORBIDDEN","NETWORK_RESTRICTED","FROZEN","PARTNER_SUSPENDED","QUOTA","NOT_FOUND","VALIDATION","CONFLICT","IDEMPOTENCY_MISMATCH","CREDIT_LIMIT","INFLIGHT_LIMIT","RATE_LIMITED","KEY_LIMIT","UPSTREAM","STORE_BUSY","STORE_UNAVAILABLE","MAINTENANCE","BAD_REQUEST","INTERNAL"]},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}},"headers":{"X-Request-Id":{"description":"Request identifier. Include this value when contacting support.","schema":{"type":"string"}},"WWW-Authenticate":{"description":"Bearer authentication challenge.","schema":{"type":"string"}}}},"403":{"description":"NETWORK_RESTRICTED: the request source is outside this deployment's approved IP networks.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["UNAUTHENTICATED","FORBIDDEN","NETWORK_RESTRICTED","FROZEN","PARTNER_SUSPENDED","QUOTA","NOT_FOUND","VALIDATION","CONFLICT","IDEMPOTENCY_MISMATCH","CREDIT_LIMIT","INFLIGHT_LIMIT","RATE_LIMITED","KEY_LIMIT","UPSTREAM","STORE_BUSY","STORE_UNAVAILABLE","MAINTENANCE","BAD_REQUEST","INTERNAL"]},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}},"headers":{"X-Request-Id":{"description":"Request identifier. Include this value when contacting support.","schema":{"type":"string"}}}},"422":{"description":"Invalid query or unknown event type.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["UNAUTHENTICATED","FORBIDDEN","NETWORK_RESTRICTED","FROZEN","PARTNER_SUSPENDED","QUOTA","NOT_FOUND","VALIDATION","CONFLICT","IDEMPOTENCY_MISMATCH","CREDIT_LIMIT","INFLIGHT_LIMIT","RATE_LIMITED","KEY_LIMIT","UPSTREAM","STORE_BUSY","STORE_UNAVAILABLE","MAINTENANCE","BAD_REQUEST","INTERNAL"]},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}},"headers":{"X-Request-Id":{"description":"Request identifier. Include this value when contacting support.","schema":{"type":"string"}}}},"429":{"description":"Rate limit exceeded. See Retry-After before retrying.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["UNAUTHENTICATED","FORBIDDEN","NETWORK_RESTRICTED","FROZEN","PARTNER_SUSPENDED","QUOTA","NOT_FOUND","VALIDATION","CONFLICT","IDEMPOTENCY_MISMATCH","CREDIT_LIMIT","INFLIGHT_LIMIT","RATE_LIMITED","KEY_LIMIT","UPSTREAM","STORE_BUSY","STORE_UNAVAILABLE","MAINTENANCE","BAD_REQUEST","INTERNAL"]},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}},"headers":{"X-Request-Id":{"description":"Request identifier. Include this value when contacting support.","schema":{"type":"string"}},"Retry-After":{"description":"Minimum delay in seconds before retrying, when present. Some dependency failures omit this header; use exponential backoff with jitter.","schema":{"type":"integer"}}}},"500":{"description":"INTERNAL: unexpected server error. Retain X-Request-Id for support; resolve the outcome before repeating a write.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["UNAUTHENTICATED","FORBIDDEN","NETWORK_RESTRICTED","FROZEN","PARTNER_SUSPENDED","QUOTA","NOT_FOUND","VALIDATION","CONFLICT","IDEMPOTENCY_MISMATCH","CREDIT_LIMIT","INFLIGHT_LIMIT","RATE_LIMITED","KEY_LIMIT","UPSTREAM","STORE_BUSY","STORE_UNAVAILABLE","MAINTENANCE","BAD_REQUEST","INTERNAL"]},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}},"headers":{"X-Request-Id":{"description":"Request identifier. Include this value when contacting support.","schema":{"type":"string"}}}},"503":{"description":"Service temporarily unavailable: MAINTENANCE, STORE_BUSY, STORE_UNAVAILABLE or UPSTREAM.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["UNAUTHENTICATED","FORBIDDEN","NETWORK_RESTRICTED","FROZEN","PARTNER_SUSPENDED","QUOTA","NOT_FOUND","VALIDATION","CONFLICT","IDEMPOTENCY_MISMATCH","CREDIT_LIMIT","INFLIGHT_LIMIT","RATE_LIMITED","KEY_LIMIT","UPSTREAM","STORE_BUSY","STORE_UNAVAILABLE","MAINTENANCE","BAD_REQUEST","INTERNAL"]},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}},"headers":{"X-Request-Id":{"description":"Request identifier. Include this value when contacting support.","schema":{"type":"string"}},"Retry-After":{"description":"Minimum delay in seconds before retrying, when present. Some dependency failures omit this header; use exponential backoff with jitter.","schema":{"type":"integer"}}}},"default":{"description":"Other API error. Inspect the HTTP status and error envelope; request parsing can return 400, 413 or 415.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["UNAUTHENTICATED","FORBIDDEN","NETWORK_RESTRICTED","FROZEN","PARTNER_SUSPENDED","QUOTA","NOT_FOUND","VALIDATION","CONFLICT","IDEMPOTENCY_MISMATCH","CREDIT_LIMIT","INFLIGHT_LIMIT","RATE_LIMITED","KEY_LIMIT","UPSTREAM","STORE_BUSY","STORE_UNAVAILABLE","MAINTENANCE","BAD_REQUEST","INTERNAL"]},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}},"headers":{"X-Request-Id":{"description":"Request identifier. Include this value when contacting support.","schema":{"type":"string"}}}}},"operationId":"get_events"}},"/webhook":{"get":{"tags":["Webhooks"],"summary":"Retrieve webhook configuration","description":"Returns the destination URL and configuration timestamp, or null when delivery is disabled. The signing secret is not returned.","responses":{"200":{"description":"Webhook configuration.","content":{"application/json":{"schema":{"type":"object","properties":{"webhook":{"anyOf":[{"type":"object","properties":{"url":{"type":"string"},"configured_at":{"type":"string","format":"date-time"}},"required":["url","configured_at"],"additionalProperties":false},{"type":"null"}]}},"required":["webhook"],"additionalProperties":false},"example":{"webhook":{"url":"https://hooks.example.com/infra","configured_at":"2026-09-10T00:00:00.000Z"}}}},"headers":{"X-Request-Id":{"description":"Request identifier. Include this value when contacting support.","schema":{"type":"string"}}}},"401":{"description":"Authentication failed. The API key is missing, invalid or revoked, or API access is not approved.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["UNAUTHENTICATED","FORBIDDEN","NETWORK_RESTRICTED","FROZEN","PARTNER_SUSPENDED","QUOTA","NOT_FOUND","VALIDATION","CONFLICT","IDEMPOTENCY_MISMATCH","CREDIT_LIMIT","INFLIGHT_LIMIT","RATE_LIMITED","KEY_LIMIT","UPSTREAM","STORE_BUSY","STORE_UNAVAILABLE","MAINTENANCE","BAD_REQUEST","INTERNAL"]},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}},"headers":{"X-Request-Id":{"description":"Request identifier. Include this value when contacting support.","schema":{"type":"string"}},"WWW-Authenticate":{"description":"Bearer authentication challenge.","schema":{"type":"string"}}}},"403":{"description":"NETWORK_RESTRICTED: the request source is outside this deployment's approved IP networks.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["UNAUTHENTICATED","FORBIDDEN","NETWORK_RESTRICTED","FROZEN","PARTNER_SUSPENDED","QUOTA","NOT_FOUND","VALIDATION","CONFLICT","IDEMPOTENCY_MISMATCH","CREDIT_LIMIT","INFLIGHT_LIMIT","RATE_LIMITED","KEY_LIMIT","UPSTREAM","STORE_BUSY","STORE_UNAVAILABLE","MAINTENANCE","BAD_REQUEST","INTERNAL"]},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}},"headers":{"X-Request-Id":{"description":"Request identifier. Include this value when contacting support.","schema":{"type":"string"}}}},"429":{"description":"Rate limit exceeded. See Retry-After before retrying.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["UNAUTHENTICATED","FORBIDDEN","NETWORK_RESTRICTED","FROZEN","PARTNER_SUSPENDED","QUOTA","NOT_FOUND","VALIDATION","CONFLICT","IDEMPOTENCY_MISMATCH","CREDIT_LIMIT","INFLIGHT_LIMIT","RATE_LIMITED","KEY_LIMIT","UPSTREAM","STORE_BUSY","STORE_UNAVAILABLE","MAINTENANCE","BAD_REQUEST","INTERNAL"]},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}},"headers":{"X-Request-Id":{"description":"Request identifier. Include this value when contacting support.","schema":{"type":"string"}},"Retry-After":{"description":"Minimum delay in seconds before retrying, when present. Some dependency failures omit this header; use exponential backoff with jitter.","schema":{"type":"integer"}}}},"500":{"description":"INTERNAL: unexpected server error. Retain X-Request-Id for support; resolve the outcome before repeating a write.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["UNAUTHENTICATED","FORBIDDEN","NETWORK_RESTRICTED","FROZEN","PARTNER_SUSPENDED","QUOTA","NOT_FOUND","VALIDATION","CONFLICT","IDEMPOTENCY_MISMATCH","CREDIT_LIMIT","INFLIGHT_LIMIT","RATE_LIMITED","KEY_LIMIT","UPSTREAM","STORE_BUSY","STORE_UNAVAILABLE","MAINTENANCE","BAD_REQUEST","INTERNAL"]},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}},"headers":{"X-Request-Id":{"description":"Request identifier. Include this value when contacting support.","schema":{"type":"string"}}}},"503":{"description":"Service temporarily unavailable: MAINTENANCE, STORE_BUSY, STORE_UNAVAILABLE or UPSTREAM.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["UNAUTHENTICATED","FORBIDDEN","NETWORK_RESTRICTED","FROZEN","PARTNER_SUSPENDED","QUOTA","NOT_FOUND","VALIDATION","CONFLICT","IDEMPOTENCY_MISMATCH","CREDIT_LIMIT","INFLIGHT_LIMIT","RATE_LIMITED","KEY_LIMIT","UPSTREAM","STORE_BUSY","STORE_UNAVAILABLE","MAINTENANCE","BAD_REQUEST","INTERNAL"]},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}},"headers":{"X-Request-Id":{"description":"Request identifier. Include this value when contacting support.","schema":{"type":"string"}},"Retry-After":{"description":"Minimum delay in seconds before retrying, when present. Some dependency failures omit this header; use exponential backoff with jitter.","schema":{"type":"integer"}}}},"default":{"description":"Other API error. Inspect the HTTP status and error envelope; request parsing can return 400, 413 or 415.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["UNAUTHENTICATED","FORBIDDEN","NETWORK_RESTRICTED","FROZEN","PARTNER_SUSPENDED","QUOTA","NOT_FOUND","VALIDATION","CONFLICT","IDEMPOTENCY_MISMATCH","CREDIT_LIMIT","INFLIGHT_LIMIT","RATE_LIMITED","KEY_LIMIT","UPSTREAM","STORE_BUSY","STORE_UNAVAILABLE","MAINTENANCE","BAD_REQUEST","INTERNAL"]},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}},"headers":{"X-Request-Id":{"description":"Request identifier. Include this value when contacting support.","schema":{"type":"string"}}}}},"operationId":"get_webhook"},"put":{"tags":["Webhooks"],"summary":"Update webhook configuration","description":"Sets or disables the destination URL. Every request with a non-null URL rotates the signing secret, including requests that repeat the existing URL. The new secret is returned once. Pending deliveries are cancelled; recover missed events through GET /v1/events. This operation is not safe to retry automatically.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"url":{"anyOf":[{"type":"string","minLength":12,"maxLength":512},{"type":"null"}],"description":"HTTPS URL with a public hostname. IP addresses, embedded credentials and private destinations are rejected. Set to null to disable delivery."}},"required":["url"],"additionalProperties":false},"examples":{"configure":{"summary":"Configure an event destination","value":{"url":"https://hooks.example.com/infra"}},"disable":{"summary":"Disable webhook delivery","value":{"url":null}}}}}},"responses":{"200":{"description":"Webhook configuration updated.","content":{"application/json":{"schema":{"type":"object","properties":{"webhook":{"anyOf":[{"type":"object","properties":{"url":{"type":"string"},"secret":{"type":"string","description":"Shown once"},"note":{"type":"string"}},"required":["url","secret","note"],"additionalProperties":false},{"type":"null"}]},"dead_lettered":{"type":"integer"}},"required":["webhook","dead_lettered"],"additionalProperties":false},"example":{"webhook":{"url":"https://hooks.example.com/infra","secret":"whsec_example_not_a_valid_secret","note":"secret shown once; queued deliveries were dead-lettered, replay via /v1/events"},"dead_lettered":0}}},"headers":{"X-Request-Id":{"description":"Request identifier. Include this value when contacting support.","schema":{"type":"string"}}}},"401":{"description":"Authentication failed. The API key is missing, invalid or revoked, or API access is not approved.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["UNAUTHENTICATED","FORBIDDEN","NETWORK_RESTRICTED","FROZEN","PARTNER_SUSPENDED","QUOTA","NOT_FOUND","VALIDATION","CONFLICT","IDEMPOTENCY_MISMATCH","CREDIT_LIMIT","INFLIGHT_LIMIT","RATE_LIMITED","KEY_LIMIT","UPSTREAM","STORE_BUSY","STORE_UNAVAILABLE","MAINTENANCE","BAD_REQUEST","INTERNAL"]},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}},"headers":{"X-Request-Id":{"description":"Request identifier. Include this value when contacting support.","schema":{"type":"string"}},"WWW-Authenticate":{"description":"Bearer authentication challenge.","schema":{"type":"string"}}}},"403":{"description":"NETWORK_RESTRICTED: the request source is outside this deployment's approved IP networks.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["UNAUTHENTICATED","FORBIDDEN","NETWORK_RESTRICTED","FROZEN","PARTNER_SUSPENDED","QUOTA","NOT_FOUND","VALIDATION","CONFLICT","IDEMPOTENCY_MISMATCH","CREDIT_LIMIT","INFLIGHT_LIMIT","RATE_LIMITED","KEY_LIMIT","UPSTREAM","STORE_BUSY","STORE_UNAVAILABLE","MAINTENANCE","BAD_REQUEST","INTERNAL"]},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}},"headers":{"X-Request-Id":{"description":"Request identifier. Include this value when contacting support.","schema":{"type":"string"}}}},"409":{"description":"CONFLICT: the account changed concurrently.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["UNAUTHENTICATED","FORBIDDEN","NETWORK_RESTRICTED","FROZEN","PARTNER_SUSPENDED","QUOTA","NOT_FOUND","VALIDATION","CONFLICT","IDEMPOTENCY_MISMATCH","CREDIT_LIMIT","INFLIGHT_LIMIT","RATE_LIMITED","KEY_LIMIT","UPSTREAM","STORE_BUSY","STORE_UNAVAILABLE","MAINTENANCE","BAD_REQUEST","INTERNAL"]},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}},"headers":{"X-Request-Id":{"description":"Request identifier. Include this value when contacting support.","schema":{"type":"string"}}}},"422":{"description":"Destination URL rejected.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["UNAUTHENTICATED","FORBIDDEN","NETWORK_RESTRICTED","FROZEN","PARTNER_SUSPENDED","QUOTA","NOT_FOUND","VALIDATION","CONFLICT","IDEMPOTENCY_MISMATCH","CREDIT_LIMIT","INFLIGHT_LIMIT","RATE_LIMITED","KEY_LIMIT","UPSTREAM","STORE_BUSY","STORE_UNAVAILABLE","MAINTENANCE","BAD_REQUEST","INTERNAL"]},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}},"headers":{"X-Request-Id":{"description":"Request identifier. Include this value when contacting support.","schema":{"type":"string"}}}},"429":{"description":"Rate limit exceeded. See Retry-After before retrying.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["UNAUTHENTICATED","FORBIDDEN","NETWORK_RESTRICTED","FROZEN","PARTNER_SUSPENDED","QUOTA","NOT_FOUND","VALIDATION","CONFLICT","IDEMPOTENCY_MISMATCH","CREDIT_LIMIT","INFLIGHT_LIMIT","RATE_LIMITED","KEY_LIMIT","UPSTREAM","STORE_BUSY","STORE_UNAVAILABLE","MAINTENANCE","BAD_REQUEST","INTERNAL"]},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}},"headers":{"X-Request-Id":{"description":"Request identifier. Include this value when contacting support.","schema":{"type":"string"}},"Retry-After":{"description":"Minimum delay in seconds before retrying, when present. Some dependency failures omit this header; use exponential backoff with jitter.","schema":{"type":"integer"}}}},"500":{"description":"INTERNAL: unexpected server error. Retain X-Request-Id for support; resolve the outcome before repeating a write.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["UNAUTHENTICATED","FORBIDDEN","NETWORK_RESTRICTED","FROZEN","PARTNER_SUSPENDED","QUOTA","NOT_FOUND","VALIDATION","CONFLICT","IDEMPOTENCY_MISMATCH","CREDIT_LIMIT","INFLIGHT_LIMIT","RATE_LIMITED","KEY_LIMIT","UPSTREAM","STORE_BUSY","STORE_UNAVAILABLE","MAINTENANCE","BAD_REQUEST","INTERNAL"]},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}},"headers":{"X-Request-Id":{"description":"Request identifier. Include this value when contacting support.","schema":{"type":"string"}}}},"503":{"description":"Service temporarily unavailable: MAINTENANCE, STORE_BUSY, STORE_UNAVAILABLE or UPSTREAM.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["UNAUTHENTICATED","FORBIDDEN","NETWORK_RESTRICTED","FROZEN","PARTNER_SUSPENDED","QUOTA","NOT_FOUND","VALIDATION","CONFLICT","IDEMPOTENCY_MISMATCH","CREDIT_LIMIT","INFLIGHT_LIMIT","RATE_LIMITED","KEY_LIMIT","UPSTREAM","STORE_BUSY","STORE_UNAVAILABLE","MAINTENANCE","BAD_REQUEST","INTERNAL"]},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}},"headers":{"X-Request-Id":{"description":"Request identifier. Include this value when contacting support.","schema":{"type":"string"}},"Retry-After":{"description":"Minimum delay in seconds before retrying, when present. Some dependency failures omit this header; use exponential backoff with jitter.","schema":{"type":"integer"}}}},"default":{"description":"Other API error. Inspect the HTTP status and error envelope; request parsing can return 400, 413 or 415.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["UNAUTHENTICATED","FORBIDDEN","NETWORK_RESTRICTED","FROZEN","PARTNER_SUSPENDED","QUOTA","NOT_FOUND","VALIDATION","CONFLICT","IDEMPOTENCY_MISMATCH","CREDIT_LIMIT","INFLIGHT_LIMIT","RATE_LIMITED","KEY_LIMIT","UPSTREAM","STORE_BUSY","STORE_UNAVAILABLE","MAINTENANCE","BAD_REQUEST","INTERNAL"]},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}},"headers":{"X-Request-Id":{"description":"Request identifier. Include this value when contacting support.","schema":{"type":"string"}}}}},"operationId":"put_webhook"}},"/webhook/test":{"post":{"tags":["Webhooks"],"summary":"Send a test webhook","description":"Attempts one synchronous delivery of a signed webhook.test event. HTTP 200 indicates the test ran; inspect ok and status for the delivery result. Response bodies from the destination are not returned.","responses":{"200":{"description":"Delivery result. status is the destination's HTTP status, or 0 for a connection failure.","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"integer"},"latency_ms":{"type":"integer"},"ok":{"type":"boolean"},"error":{"type":"string"}},"required":["status","latency_ms","ok"],"additionalProperties":false},"example":{"status":204,"latency_ms":82,"ok":true}}},"headers":{"X-Request-Id":{"description":"Request identifier. Include this value when contacting support.","schema":{"type":"string"}}}},"401":{"description":"Authentication failed. The API key is missing, invalid or revoked, or API access is not approved.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["UNAUTHENTICATED","FORBIDDEN","NETWORK_RESTRICTED","FROZEN","PARTNER_SUSPENDED","QUOTA","NOT_FOUND","VALIDATION","CONFLICT","IDEMPOTENCY_MISMATCH","CREDIT_LIMIT","INFLIGHT_LIMIT","RATE_LIMITED","KEY_LIMIT","UPSTREAM","STORE_BUSY","STORE_UNAVAILABLE","MAINTENANCE","BAD_REQUEST","INTERNAL"]},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}},"headers":{"X-Request-Id":{"description":"Request identifier. Include this value when contacting support.","schema":{"type":"string"}},"WWW-Authenticate":{"description":"Bearer authentication challenge.","schema":{"type":"string"}}}},"403":{"description":"NETWORK_RESTRICTED: the request source is outside this deployment's approved IP networks.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["UNAUTHENTICATED","FORBIDDEN","NETWORK_RESTRICTED","FROZEN","PARTNER_SUSPENDED","QUOTA","NOT_FOUND","VALIDATION","CONFLICT","IDEMPOTENCY_MISMATCH","CREDIT_LIMIT","INFLIGHT_LIMIT","RATE_LIMITED","KEY_LIMIT","UPSTREAM","STORE_BUSY","STORE_UNAVAILABLE","MAINTENANCE","BAD_REQUEST","INTERNAL"]},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}},"headers":{"X-Request-Id":{"description":"Request identifier. Include this value when contacting support.","schema":{"type":"string"}}}},"409":{"description":"CONFLICT: no webhook configured.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["UNAUTHENTICATED","FORBIDDEN","NETWORK_RESTRICTED","FROZEN","PARTNER_SUSPENDED","QUOTA","NOT_FOUND","VALIDATION","CONFLICT","IDEMPOTENCY_MISMATCH","CREDIT_LIMIT","INFLIGHT_LIMIT","RATE_LIMITED","KEY_LIMIT","UPSTREAM","STORE_BUSY","STORE_UNAVAILABLE","MAINTENANCE","BAD_REQUEST","INTERNAL"]},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}},"headers":{"X-Request-Id":{"description":"Request identifier. Include this value when contacting support.","schema":{"type":"string"}}}},"429":{"description":"Rate limit exceeded. See Retry-After before retrying.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["UNAUTHENTICATED","FORBIDDEN","NETWORK_RESTRICTED","FROZEN","PARTNER_SUSPENDED","QUOTA","NOT_FOUND","VALIDATION","CONFLICT","IDEMPOTENCY_MISMATCH","CREDIT_LIMIT","INFLIGHT_LIMIT","RATE_LIMITED","KEY_LIMIT","UPSTREAM","STORE_BUSY","STORE_UNAVAILABLE","MAINTENANCE","BAD_REQUEST","INTERNAL"]},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}},"headers":{"X-Request-Id":{"description":"Request identifier. Include this value when contacting support.","schema":{"type":"string"}},"Retry-After":{"description":"Minimum delay in seconds before retrying, when present. Some dependency failures omit this header; use exponential backoff with jitter.","schema":{"type":"integer"}}}},"500":{"description":"INTERNAL: unexpected server error. Retain X-Request-Id for support; resolve the outcome before repeating a write.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["UNAUTHENTICATED","FORBIDDEN","NETWORK_RESTRICTED","FROZEN","PARTNER_SUSPENDED","QUOTA","NOT_FOUND","VALIDATION","CONFLICT","IDEMPOTENCY_MISMATCH","CREDIT_LIMIT","INFLIGHT_LIMIT","RATE_LIMITED","KEY_LIMIT","UPSTREAM","STORE_BUSY","STORE_UNAVAILABLE","MAINTENANCE","BAD_REQUEST","INTERNAL"]},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}},"headers":{"X-Request-Id":{"description":"Request identifier. Include this value when contacting support.","schema":{"type":"string"}}}},"503":{"description":"Service temporarily unavailable: MAINTENANCE, STORE_BUSY, STORE_UNAVAILABLE or UPSTREAM.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["UNAUTHENTICATED","FORBIDDEN","NETWORK_RESTRICTED","FROZEN","PARTNER_SUSPENDED","QUOTA","NOT_FOUND","VALIDATION","CONFLICT","IDEMPOTENCY_MISMATCH","CREDIT_LIMIT","INFLIGHT_LIMIT","RATE_LIMITED","KEY_LIMIT","UPSTREAM","STORE_BUSY","STORE_UNAVAILABLE","MAINTENANCE","BAD_REQUEST","INTERNAL"]},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}},"headers":{"X-Request-Id":{"description":"Request identifier. Include this value when contacting support.","schema":{"type":"string"}},"Retry-After":{"description":"Minimum delay in seconds before retrying, when present. Some dependency failures omit this header; use exponential backoff with jitter.","schema":{"type":"integer"}}}},"default":{"description":"Other API error. Inspect the HTTP status and error envelope; request parsing can return 400, 413 or 415.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["UNAUTHENTICATED","FORBIDDEN","NETWORK_RESTRICTED","FROZEN","PARTNER_SUSPENDED","QUOTA","NOT_FOUND","VALIDATION","CONFLICT","IDEMPOTENCY_MISMATCH","CREDIT_LIMIT","INFLIGHT_LIMIT","RATE_LIMITED","KEY_LIMIT","UPSTREAM","STORE_BUSY","STORE_UNAVAILABLE","MAINTENANCE","BAD_REQUEST","INTERNAL"]},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}},"headers":{"X-Request-Id":{"description":"Request identifier. Include this value when contacting support.","schema":{"type":"string"}}}}},"operationId":"post_webhook_test"}},"/usage":{"get":{"tags":["Billing"],"summary":"Retrieve monthly usage","description":"Returns billable hours and charges by plan for a billing month. Rates, caps and discount calculations follow the account's price book.","parameters":[{"name":"month","in":"query","required":false,"schema":{"type":"string","pattern":"^\\d{4}-(0[1-9]|1[0-2])$"},"example":"2026-09","description":"Billing month in YYYY-MM format. Defaults to the current month in the billing timezone."}],"responses":{"200":{"description":"Monthly usage.","content":{"application/json":{"schema":{"type":"object","properties":{"month":{"type":"string"},"as_of":{"type":"string","format":"date-time"},"plans":{"type":"array","items":{"type":"object","properties":{"discount_basis":{"type":"string","enum":["vm_months_per_plan","allocated_per_plan","allocated_combined"]},"current_tier":{"type":"object","properties":{"qualifying_count":{"type":"integer","description":"Allocated server count used to select this rate."},"monthly_price":{"type":"string","description":"Monthly price at this allocation count."},"hourly_price":{"type":"string","description":"Displayed hourly rate at this allocation count; use returned charges for billing totals."},"next_from_count":{"anyOf":[{"type":"integer"},{"type":"null"}],"description":"Next discount threshold, or null when there is no higher tier."}},"required":["qualifying_count","monthly_price","hourly_price","next_from_count"],"additionalProperties":false},"period_segments":{"type":"array","items":{"type":"object","properties":{"from":{"type":"string","format":"date-time"},"to":{"type":"string","format":"date-time"},"qualifying_count":{"type":"integer"},"monthly_price":{"type":"string"},"hourly_price":{"type":"string"},"hours":{"type":"integer"},"charge_numerator":{"type":"string","description":"Exact charge numerator: monthly price in cents multiplied by billed hours. Divide by 672 for cents. Sum numerators before rounding the plan total."},"subtotal":{"type":"string","description":"Rounded display amount for this segment; independently rounded segments may not sum to the final plan amount."}},"required":["from","to","qualifying_count","monthly_price","hourly_price","hours","charge_numerator","subtotal"],"additionalProperties":false}},"code":{"type":"string"},"hours":{"type":"number"},"capped_hours":{"type":"number"},"vm_months":{"type":"number","description":"Capped hours divided by 672, to four decimals. Used for tier selection with vm_months_per_plan; allocation-based pricing uses charges recorded for each hour."},"monthly_price":{"type":"string","description":"Monthly price at the selected VM-month tier, or current allocation-count tier. It does not reprice historical allocated usage."},"hourly_price":{"type":"string","description":"Displayed hourly rate at the same tier. Use amount for the period's charge."},"amount":{"type":"string"},"tier":{"anyOf":[{"type":"object","properties":{"hours":{"type":"number"},"vm_months":{"type":"number"},"from_vm_months":{"type":"number"},"monthly_price":{"type":"string"},"next":{"anyOf":[{"type":"object","properties":{"from_vm_months":{"type":"number"},"monthly_price":{"type":"string"}},"required":["from_vm_months","monthly_price"],"additionalProperties":false},{"type":"null"}]}},"required":["hours","vm_months","from_vm_months","monthly_price","next"],"additionalProperties":false},{"type":"null"}]}},"required":["code","hours","capped_hours","vm_months","monthly_price","hourly_price","amount"],"additionalProperties":false}},"total":{"type":"string"}},"required":["month","as_of","plans","total"],"additionalProperties":false},"example":{"month":"2026-09","as_of":"2026-09-10T00:00:00.000Z","plans":[{"code":"standard-2","hours":24,"capped_hours":24,"vm_months":0.0357,"monthly_price":"67.20","hourly_price":"0.1000","amount":"2.40"}],"total":"2.40"}}},"headers":{"X-Request-Id":{"description":"Request identifier. Include this value when contacting support.","schema":{"type":"string"}}}},"401":{"description":"Authentication failed. The API key is missing, invalid or revoked, or API access is not approved.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["UNAUTHENTICATED","FORBIDDEN","NETWORK_RESTRICTED","FROZEN","PARTNER_SUSPENDED","QUOTA","NOT_FOUND","VALIDATION","CONFLICT","IDEMPOTENCY_MISMATCH","CREDIT_LIMIT","INFLIGHT_LIMIT","RATE_LIMITED","KEY_LIMIT","UPSTREAM","STORE_BUSY","STORE_UNAVAILABLE","MAINTENANCE","BAD_REQUEST","INTERNAL"]},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}},"headers":{"X-Request-Id":{"description":"Request identifier. Include this value when contacting support.","schema":{"type":"string"}},"WWW-Authenticate":{"description":"Bearer authentication challenge.","schema":{"type":"string"}}}},"403":{"description":"NETWORK_RESTRICTED: the request source is outside this deployment's approved IP networks.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["UNAUTHENTICATED","FORBIDDEN","NETWORK_RESTRICTED","FROZEN","PARTNER_SUSPENDED","QUOTA","NOT_FOUND","VALIDATION","CONFLICT","IDEMPOTENCY_MISMATCH","CREDIT_LIMIT","INFLIGHT_LIMIT","RATE_LIMITED","KEY_LIMIT","UPSTREAM","STORE_BUSY","STORE_UNAVAILABLE","MAINTENANCE","BAD_REQUEST","INTERNAL"]},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}},"headers":{"X-Request-Id":{"description":"Request identifier. Include this value when contacting support.","schema":{"type":"string"}}}},"422":{"description":"Invalid month parameter.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["UNAUTHENTICATED","FORBIDDEN","NETWORK_RESTRICTED","FROZEN","PARTNER_SUSPENDED","QUOTA","NOT_FOUND","VALIDATION","CONFLICT","IDEMPOTENCY_MISMATCH","CREDIT_LIMIT","INFLIGHT_LIMIT","RATE_LIMITED","KEY_LIMIT","UPSTREAM","STORE_BUSY","STORE_UNAVAILABLE","MAINTENANCE","BAD_REQUEST","INTERNAL"]},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}},"headers":{"X-Request-Id":{"description":"Request identifier. Include this value when contacting support.","schema":{"type":"string"}}}},"429":{"description":"Rate limit exceeded. See Retry-After before retrying.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["UNAUTHENTICATED","FORBIDDEN","NETWORK_RESTRICTED","FROZEN","PARTNER_SUSPENDED","QUOTA","NOT_FOUND","VALIDATION","CONFLICT","IDEMPOTENCY_MISMATCH","CREDIT_LIMIT","INFLIGHT_LIMIT","RATE_LIMITED","KEY_LIMIT","UPSTREAM","STORE_BUSY","STORE_UNAVAILABLE","MAINTENANCE","BAD_REQUEST","INTERNAL"]},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}},"headers":{"X-Request-Id":{"description":"Request identifier. Include this value when contacting support.","schema":{"type":"string"}},"Retry-After":{"description":"Minimum delay in seconds before retrying, when present. Some dependency failures omit this header; use exponential backoff with jitter.","schema":{"type":"integer"}}}},"500":{"description":"INTERNAL: unexpected server error. Retain X-Request-Id for support; resolve the outcome before repeating a write.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["UNAUTHENTICATED","FORBIDDEN","NETWORK_RESTRICTED","FROZEN","PARTNER_SUSPENDED","QUOTA","NOT_FOUND","VALIDATION","CONFLICT","IDEMPOTENCY_MISMATCH","CREDIT_LIMIT","INFLIGHT_LIMIT","RATE_LIMITED","KEY_LIMIT","UPSTREAM","STORE_BUSY","STORE_UNAVAILABLE","MAINTENANCE","BAD_REQUEST","INTERNAL"]},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}},"headers":{"X-Request-Id":{"description":"Request identifier. Include this value when contacting support.","schema":{"type":"string"}}}},"503":{"description":"Service temporarily unavailable: MAINTENANCE, STORE_BUSY, STORE_UNAVAILABLE or UPSTREAM.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["UNAUTHENTICATED","FORBIDDEN","NETWORK_RESTRICTED","FROZEN","PARTNER_SUSPENDED","QUOTA","NOT_FOUND","VALIDATION","CONFLICT","IDEMPOTENCY_MISMATCH","CREDIT_LIMIT","INFLIGHT_LIMIT","RATE_LIMITED","KEY_LIMIT","UPSTREAM","STORE_BUSY","STORE_UNAVAILABLE","MAINTENANCE","BAD_REQUEST","INTERNAL"]},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}},"headers":{"X-Request-Id":{"description":"Request identifier. Include this value when contacting support.","schema":{"type":"string"}},"Retry-After":{"description":"Minimum delay in seconds before retrying, when present. Some dependency failures omit this header; use exponential backoff with jitter.","schema":{"type":"integer"}}}},"default":{"description":"Other API error. Inspect the HTTP status and error envelope; request parsing can return 400, 413 or 415.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["UNAUTHENTICATED","FORBIDDEN","NETWORK_RESTRICTED","FROZEN","PARTNER_SUSPENDED","QUOTA","NOT_FOUND","VALIDATION","CONFLICT","IDEMPOTENCY_MISMATCH","CREDIT_LIMIT","INFLIGHT_LIMIT","RATE_LIMITED","KEY_LIMIT","UPSTREAM","STORE_BUSY","STORE_UNAVAILABLE","MAINTENANCE","BAD_REQUEST","INTERNAL"]},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}},"headers":{"X-Request-Id":{"description":"Request identifier. Include this value when contacting support.","schema":{"type":"string"}}}}},"operationId":"get_usage"}},"/servers/{id}/usage":{"get":{"tags":["Billing"],"summary":"Retrieve server usage","description":"Returns daily billable hours and the monthly charge for one server. closed indicates that a daily usage record is finalized.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"example":"srv_01J8Z3M4N5P6Q7R8S9T0V1W2X3","description":"Server identifier returned by the API."},{"name":"month","in":"query","required":false,"schema":{"type":"string","pattern":"^\\d{4}-(0[1-9]|1[0-2])$"},"example":"2026-09","description":"Billing month in YYYY-MM format. Defaults to the current month in the billing timezone."}],"responses":{"200":{"description":"Server usage.","content":{"application/json":{"schema":{"type":"object","properties":{"usage":{"type":"object","properties":{"discount_basis":{"type":"string","enum":["vm_months_per_plan","allocated_per_plan","allocated_combined"]},"current_tier":{"type":"object","properties":{"qualifying_count":{"type":"integer","description":"Allocated server count used to select this rate."},"monthly_price":{"type":"string","description":"Monthly price at this allocation count."},"hourly_price":{"type":"string","description":"Displayed hourly rate at this allocation count; use returned charges for billing totals."},"next_from_count":{"anyOf":[{"type":"integer"},{"type":"null"}],"description":"Next discount threshold, or null when there is no higher tier."}},"required":["qualifying_count","monthly_price","hourly_price","next_from_count"],"additionalProperties":false},"server_id":{"type":"string"},"month":{"type":"string"},"plan":{"type":"string"},"days":{"type":"array","items":{"type":"object","properties":{"day":{"type":"string"},"hours":{"type":"number"},"closed":{"type":"boolean"},"amount":{"type":"string"},"period_segments":{"type":"array","items":{"type":"object","properties":{"from":{"type":"string","format":"date-time"},"to":{"type":"string","format":"date-time"},"qualifying_count":{"type":"integer"},"monthly_price":{"type":"string"},"hourly_price":{"type":"string"},"hours":{"type":"integer"},"charge_numerator":{"type":"string","description":"Exact charge numerator: monthly price in cents multiplied by billed hours. Divide by 672 for cents. Sum numerators before rounding the plan total."},"subtotal":{"type":"string","description":"Rounded display amount for this segment; independently rounded segments may not sum to the final plan amount."}},"required":["from","to","qualifying_count","monthly_price","hourly_price","hours","charge_numerator","subtotal"],"additionalProperties":false}}},"required":["day","hours","closed"],"additionalProperties":false}},"hours":{"type":"number"},"capped_hours":{"type":"number"},"hourly_price":{"type":"string"},"monthly_price":{"type":"string","description":"Monthly price at the current allocation-count tier; present for allocation-based pricing."},"amount":{"type":"string"}},"required":["server_id","month","plan","days","hours","capped_hours","hourly_price","amount"],"additionalProperties":false}},"required":["usage"],"additionalProperties":false},"example":{"usage":{"server_id":"srv_01J8Z3M4N5P6Q7R8S9T0V1W2X3","month":"2026-09","plan":"standard-2","days":[{"day":"2026-09-09","hours":24,"closed":true}],"hours":24,"capped_hours":24,"hourly_price":"0.1000","amount":"2.40"}}}},"headers":{"X-Request-Id":{"description":"Request identifier. Include this value when contacting support.","schema":{"type":"string"}}}},"401":{"description":"Authentication failed. The API key is missing, invalid or revoked, or API access is not approved.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["UNAUTHENTICATED","FORBIDDEN","NETWORK_RESTRICTED","FROZEN","PARTNER_SUSPENDED","QUOTA","NOT_FOUND","VALIDATION","CONFLICT","IDEMPOTENCY_MISMATCH","CREDIT_LIMIT","INFLIGHT_LIMIT","RATE_LIMITED","KEY_LIMIT","UPSTREAM","STORE_BUSY","STORE_UNAVAILABLE","MAINTENANCE","BAD_REQUEST","INTERNAL"]},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}},"headers":{"X-Request-Id":{"description":"Request identifier. Include this value when contacting support.","schema":{"type":"string"}},"WWW-Authenticate":{"description":"Bearer authentication challenge.","schema":{"type":"string"}}}},"403":{"description":"NETWORK_RESTRICTED: the request source is outside this deployment's approved IP networks.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["UNAUTHENTICATED","FORBIDDEN","NETWORK_RESTRICTED","FROZEN","PARTNER_SUSPENDED","QUOTA","NOT_FOUND","VALIDATION","CONFLICT","IDEMPOTENCY_MISMATCH","CREDIT_LIMIT","INFLIGHT_LIMIT","RATE_LIMITED","KEY_LIMIT","UPSTREAM","STORE_BUSY","STORE_UNAVAILABLE","MAINTENANCE","BAD_REQUEST","INTERNAL"]},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}},"headers":{"X-Request-Id":{"description":"Request identifier. Include this value when contacting support.","schema":{"type":"string"}}}},"404":{"description":"Server not found.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["UNAUTHENTICATED","FORBIDDEN","NETWORK_RESTRICTED","FROZEN","PARTNER_SUSPENDED","QUOTA","NOT_FOUND","VALIDATION","CONFLICT","IDEMPOTENCY_MISMATCH","CREDIT_LIMIT","INFLIGHT_LIMIT","RATE_LIMITED","KEY_LIMIT","UPSTREAM","STORE_BUSY","STORE_UNAVAILABLE","MAINTENANCE","BAD_REQUEST","INTERNAL"]},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}},"headers":{"X-Request-Id":{"description":"Request identifier. Include this value when contacting support.","schema":{"type":"string"}}}},"422":{"description":"Invalid month parameter.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["UNAUTHENTICATED","FORBIDDEN","NETWORK_RESTRICTED","FROZEN","PARTNER_SUSPENDED","QUOTA","NOT_FOUND","VALIDATION","CONFLICT","IDEMPOTENCY_MISMATCH","CREDIT_LIMIT","INFLIGHT_LIMIT","RATE_LIMITED","KEY_LIMIT","UPSTREAM","STORE_BUSY","STORE_UNAVAILABLE","MAINTENANCE","BAD_REQUEST","INTERNAL"]},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}},"headers":{"X-Request-Id":{"description":"Request identifier. Include this value when contacting support.","schema":{"type":"string"}}}},"429":{"description":"Rate limit exceeded. See Retry-After before retrying.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["UNAUTHENTICATED","FORBIDDEN","NETWORK_RESTRICTED","FROZEN","PARTNER_SUSPENDED","QUOTA","NOT_FOUND","VALIDATION","CONFLICT","IDEMPOTENCY_MISMATCH","CREDIT_LIMIT","INFLIGHT_LIMIT","RATE_LIMITED","KEY_LIMIT","UPSTREAM","STORE_BUSY","STORE_UNAVAILABLE","MAINTENANCE","BAD_REQUEST","INTERNAL"]},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}},"headers":{"X-Request-Id":{"description":"Request identifier. Include this value when contacting support.","schema":{"type":"string"}},"Retry-After":{"description":"Minimum delay in seconds before retrying, when present. Some dependency failures omit this header; use exponential backoff with jitter.","schema":{"type":"integer"}}}},"500":{"description":"INTERNAL: unexpected server error. Retain X-Request-Id for support; resolve the outcome before repeating a write.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["UNAUTHENTICATED","FORBIDDEN","NETWORK_RESTRICTED","FROZEN","PARTNER_SUSPENDED","QUOTA","NOT_FOUND","VALIDATION","CONFLICT","IDEMPOTENCY_MISMATCH","CREDIT_LIMIT","INFLIGHT_LIMIT","RATE_LIMITED","KEY_LIMIT","UPSTREAM","STORE_BUSY","STORE_UNAVAILABLE","MAINTENANCE","BAD_REQUEST","INTERNAL"]},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}},"headers":{"X-Request-Id":{"description":"Request identifier. Include this value when contacting support.","schema":{"type":"string"}}}},"503":{"description":"Service temporarily unavailable: MAINTENANCE, STORE_BUSY, STORE_UNAVAILABLE or UPSTREAM.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["UNAUTHENTICATED","FORBIDDEN","NETWORK_RESTRICTED","FROZEN","PARTNER_SUSPENDED","QUOTA","NOT_FOUND","VALIDATION","CONFLICT","IDEMPOTENCY_MISMATCH","CREDIT_LIMIT","INFLIGHT_LIMIT","RATE_LIMITED","KEY_LIMIT","UPSTREAM","STORE_BUSY","STORE_UNAVAILABLE","MAINTENANCE","BAD_REQUEST","INTERNAL"]},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}},"headers":{"X-Request-Id":{"description":"Request identifier. Include this value when contacting support.","schema":{"type":"string"}},"Retry-After":{"description":"Minimum delay in seconds before retrying, when present. Some dependency failures omit this header; use exponential backoff with jitter.","schema":{"type":"integer"}}}},"default":{"description":"Other API error. Inspect the HTTP status and error envelope; request parsing can return 400, 413 or 415.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["UNAUTHENTICATED","FORBIDDEN","NETWORK_RESTRICTED","FROZEN","PARTNER_SUSPENDED","QUOTA","NOT_FOUND","VALIDATION","CONFLICT","IDEMPOTENCY_MISMATCH","CREDIT_LIMIT","INFLIGHT_LIMIT","RATE_LIMITED","KEY_LIMIT","UPSTREAM","STORE_BUSY","STORE_UNAVAILABLE","MAINTENANCE","BAD_REQUEST","INTERNAL"]},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}},"headers":{"X-Request-Id":{"description":"Request identifier. Include this value when contacting support.","schema":{"type":"string"}}}}},"operationId":"get_servers_id_usage"}},"/billing/estimate":{"get":{"tags":["Billing"],"summary":"Retrieve a billing estimate","description":"Returns month-to-date charges, a month-end projection and the next invoice estimate. The projection assumes the current fleet remains allocated until month end with no server creations or deletions. Use next_invoice.issued_on and due_on for the invoice dates.","responses":{"200":{"description":"Billing estimate.","content":{"application/json":{"schema":{"type":"object","properties":{"estimate":{"type":"object","properties":{"discount_basis":{"type":"string","enum":["vm_months_per_plan","allocated_per_plan","allocated_combined"]},"period":{"type":"string"},"as_of":{"type":"string","format":"date-time"},"month_to_date":{"type":"object","properties":{"hours":{"type":"number"},"amount":{"type":"string"}},"required":["hours","amount"],"additionalProperties":false},"projected_month_end":{"type":"object","properties":{"amount":{"type":"string"},"assumes":{"type":"string"}},"required":["amount","assumes"],"additionalProperties":false},"next_invoice":{"type":"object","properties":{"month":{"type":"string"},"amount":{"type":"string"},"issued_on":{"type":"string"},"due_on":{"type":"string"}},"required":["month","amount","issued_on","due_on"],"additionalProperties":false},"per_plan":{"type":"array","items":{"type":"object","properties":{"discount_basis":{"type":"string","enum":["vm_months_per_plan","allocated_per_plan","allocated_combined"]},"current_tier":{"type":"object","properties":{"qualifying_count":{"type":"integer","description":"Allocated server count used to select this rate."},"monthly_price":{"type":"string","description":"Monthly price at this allocation count."},"hourly_price":{"type":"string","description":"Displayed hourly rate at this allocation count; use returned charges for billing totals."},"next_from_count":{"anyOf":[{"type":"integer"},{"type":"null"}],"description":"Next discount threshold, or null when there is no higher tier."}},"required":["qualifying_count","monthly_price","hourly_price","next_from_count"],"additionalProperties":false},"period_segments":{"type":"array","items":{"type":"object","properties":{"from":{"type":"string","format":"date-time"},"to":{"type":"string","format":"date-time"},"qualifying_count":{"type":"integer"},"monthly_price":{"type":"string"},"hourly_price":{"type":"string"},"hours":{"type":"integer"},"charge_numerator":{"type":"string","description":"Exact charge numerator: monthly price in cents multiplied by billed hours. Divide by 672 for cents. Sum numerators before rounding the plan total."},"subtotal":{"type":"string","description":"Rounded display amount for this segment; independently rounded segments may not sum to the final plan amount."}},"required":["from","to","qualifying_count","monthly_price","hourly_price","hours","charge_numerator","subtotal"],"additionalProperties":false}},"code":{"type":"string"},"hours":{"type":"number"},"capped_hours":{"type":"number"},"vm_months":{"type":"number"},"month_to_date":{"type":"string"},"amount":{"type":"string","description":"Accrued amount for allocation-based pricing; equal to month_to_date. Use month_to_date consistently across pricing modes."},"projected":{"type":"string"},"hourly_price":{"type":"string"},"monthly_price":{"type":"string"},"tier":{"anyOf":[{"type":"object","properties":{"hours":{"type":"number"},"vm_months":{"type":"number"},"from_vm_months":{"type":"number"},"monthly_price":{"type":"string"},"next":{"anyOf":[{"type":"object","properties":{"from_vm_months":{"type":"number"},"monthly_price":{"type":"string"}},"required":["from_vm_months","monthly_price"],"additionalProperties":false},{"type":"null"}]}},"required":["hours","vm_months","from_vm_months","monthly_price","next"],"additionalProperties":false},{"type":"null"}]}},"required":["code","hours","capped_hours","vm_months","month_to_date","projected","hourly_price","monthly_price"],"additionalProperties":false}},"per_server":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":["string","null"]},"plan":{"type":"string"},"hourly_price":{"type":"string"},"hours":{"type":"number"},"month_to_date":{"type":"string"},"projected":{"type":"string"}},"required":["id","name","plan","hourly_price","hours","month_to_date","projected"],"additionalProperties":false}}},"required":["period","as_of","month_to_date","projected_month_end","next_invoice","per_plan","per_server"],"additionalProperties":false}},"required":["estimate"],"additionalProperties":false},"example":{"estimate":{"period":"2026-09","as_of":"2026-09-10T00:00:00.000Z","month_to_date":{"hours":24,"amount":"2.40"},"projected_month_end":{"amount":"52.80","assumes":"current servers run to month end, no creates or destroys"},"next_invoice":{"month":"2026-09","amount":"52.80","issued_on":"2026-10-01","due_on":"2026-10-01"},"per_plan":[{"code":"standard-2","hours":24,"capped_hours":24,"vm_months":0.0357,"monthly_price":"67.20","hourly_price":"0.1000","month_to_date":"2.40","projected":"52.80"}],"per_server":[{"id":"srv_01J8Z3M4N5P6Q7R8S9T0V1W2X3","name":"web-01","plan":"standard-2","hourly_price":"0.1000","hours":24,"month_to_date":"2.40","projected":"52.80"}]}}}},"headers":{"X-Request-Id":{"description":"Request identifier. Include this value when contacting support.","schema":{"type":"string"}}}},"401":{"description":"Authentication failed. The API key is missing, invalid or revoked, or API access is not approved.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["UNAUTHENTICATED","FORBIDDEN","NETWORK_RESTRICTED","FROZEN","PARTNER_SUSPENDED","QUOTA","NOT_FOUND","VALIDATION","CONFLICT","IDEMPOTENCY_MISMATCH","CREDIT_LIMIT","INFLIGHT_LIMIT","RATE_LIMITED","KEY_LIMIT","UPSTREAM","STORE_BUSY","STORE_UNAVAILABLE","MAINTENANCE","BAD_REQUEST","INTERNAL"]},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}},"headers":{"X-Request-Id":{"description":"Request identifier. Include this value when contacting support.","schema":{"type":"string"}},"WWW-Authenticate":{"description":"Bearer authentication challenge.","schema":{"type":"string"}}}},"403":{"description":"NETWORK_RESTRICTED: the request source is outside this deployment's approved IP networks.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["UNAUTHENTICATED","FORBIDDEN","NETWORK_RESTRICTED","FROZEN","PARTNER_SUSPENDED","QUOTA","NOT_FOUND","VALIDATION","CONFLICT","IDEMPOTENCY_MISMATCH","CREDIT_LIMIT","INFLIGHT_LIMIT","RATE_LIMITED","KEY_LIMIT","UPSTREAM","STORE_BUSY","STORE_UNAVAILABLE","MAINTENANCE","BAD_REQUEST","INTERNAL"]},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}},"headers":{"X-Request-Id":{"description":"Request identifier. Include this value when contacting support.","schema":{"type":"string"}}}},"429":{"description":"Rate limit exceeded. See Retry-After before retrying.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["UNAUTHENTICATED","FORBIDDEN","NETWORK_RESTRICTED","FROZEN","PARTNER_SUSPENDED","QUOTA","NOT_FOUND","VALIDATION","CONFLICT","IDEMPOTENCY_MISMATCH","CREDIT_LIMIT","INFLIGHT_LIMIT","RATE_LIMITED","KEY_LIMIT","UPSTREAM","STORE_BUSY","STORE_UNAVAILABLE","MAINTENANCE","BAD_REQUEST","INTERNAL"]},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}},"headers":{"X-Request-Id":{"description":"Request identifier. Include this value when contacting support.","schema":{"type":"string"}},"Retry-After":{"description":"Minimum delay in seconds before retrying, when present. Some dependency failures omit this header; use exponential backoff with jitter.","schema":{"type":"integer"}}}},"500":{"description":"INTERNAL: unexpected server error. Retain X-Request-Id for support; resolve the outcome before repeating a write.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["UNAUTHENTICATED","FORBIDDEN","NETWORK_RESTRICTED","FROZEN","PARTNER_SUSPENDED","QUOTA","NOT_FOUND","VALIDATION","CONFLICT","IDEMPOTENCY_MISMATCH","CREDIT_LIMIT","INFLIGHT_LIMIT","RATE_LIMITED","KEY_LIMIT","UPSTREAM","STORE_BUSY","STORE_UNAVAILABLE","MAINTENANCE","BAD_REQUEST","INTERNAL"]},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}},"headers":{"X-Request-Id":{"description":"Request identifier. Include this value when contacting support.","schema":{"type":"string"}}}},"503":{"description":"Service temporarily unavailable: MAINTENANCE, STORE_BUSY, STORE_UNAVAILABLE or UPSTREAM.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["UNAUTHENTICATED","FORBIDDEN","NETWORK_RESTRICTED","FROZEN","PARTNER_SUSPENDED","QUOTA","NOT_FOUND","VALIDATION","CONFLICT","IDEMPOTENCY_MISMATCH","CREDIT_LIMIT","INFLIGHT_LIMIT","RATE_LIMITED","KEY_LIMIT","UPSTREAM","STORE_BUSY","STORE_UNAVAILABLE","MAINTENANCE","BAD_REQUEST","INTERNAL"]},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}},"headers":{"X-Request-Id":{"description":"Request identifier. Include this value when contacting support.","schema":{"type":"string"}},"Retry-After":{"description":"Minimum delay in seconds before retrying, when present. Some dependency failures omit this header; use exponential backoff with jitter.","schema":{"type":"integer"}}}},"default":{"description":"Other API error. Inspect the HTTP status and error envelope; request parsing can return 400, 413 or 415.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["UNAUTHENTICATED","FORBIDDEN","NETWORK_RESTRICTED","FROZEN","PARTNER_SUSPENDED","QUOTA","NOT_FOUND","VALIDATION","CONFLICT","IDEMPOTENCY_MISMATCH","CREDIT_LIMIT","INFLIGHT_LIMIT","RATE_LIMITED","KEY_LIMIT","UPSTREAM","STORE_BUSY","STORE_UNAVAILABLE","MAINTENANCE","BAD_REQUEST","INTERNAL"]},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}},"headers":{"X-Request-Id":{"description":"Request identifier. Include this value when contacting support.","schema":{"type":"string"}}}}},"operationId":"get_billing_estimate"}}},"components":{"securitySchemes":{"bearer":{"type":"http","scheme":"bearer","bearerFormat":"pk_live_<keyId>_<secret>","description":"API key issued for an approved partner account."}},"schemas":{"Server":{"type":"object","properties":{"id":{"type":"string","description":"Server identifier in srv_<ulid> format."},"name":{"type":"string","description":"Server hostname."},"status":{"type":"string","enum":["requested","provisioning","active","rebuilding","suspended","destroying","destroyed","failed"],"description":"Provisioning or lifecycle state; does not indicate application health."},"failure":{"anyOf":[{"type":"string","enum":["create_call","ambiguous_create","task_failed","timeout","vanished","destroy_timeout"]},{"type":"null"}],"description":"Failure classification, or null when no failure has been recorded."},"plan":{"type":"string","description":"Plan code."},"region":{"type":"string","description":"Region code."},"image":{"type":"string","description":"Operating system image code."},"ipv4":{"type":["string","null"],"description":"Assigned IPv4 address, or null before allocation."},"ipv6":{"type":["string","null"],"description":"Reserved for IPv6. Null in this API version."},"locked":{"type":"boolean","description":"Whether deletion through the API is blocked."},"external_id":{"type":["string","null"],"description":"Identifier supplied by the integration, or null."},"batch":{"type":["string","null"],"description":"Group label supplied by the integration, or null."},"backups":{"type":"object","properties":{"enabled":{"type":"boolean"}},"required":["enabled"],"additionalProperties":false},"created_at":{"type":"string","format":"date-time","description":"Creation acceptance timestamp. Billing starts here for vm_months_per_plan, and at active_at for allocation-based pricing."},"active_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"description":"Timestamp when provisioning completed, or null while pending."},"ssh_reachable_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"description":"First successful TCP connection to port 22. Does not verify SSH authentication."},"destroy_requested_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"description":"Deletion acceptance timestamp and end of billing, or null."},"version":{"type":"integer","description":"Resource revision, incremented when the record changes."},"updated_at":{"type":"string","format":"date-time","description":"Timestamp of the most recent record update."}},"required":["id","name","status","failure","plan","region","image","ipv4","ipv6","locked","external_id","batch","backups","created_at","active_at","ssh_reachable_at","destroy_requested_at","version","updated_at"],"additionalProperties":false},"Event":{"type":"object","properties":{"id":{"type":"integer","description":"Event identifier. Use for deduplication and pagination."},"type":{"type":"string","enum":["api_access.requested","api_access.reviewed","api_access.migrated","api_key.issued","api_key.revoked","server.requested","server.provisioning","server.active","server.ssh_ready","server.provision_failed","server.create_ambiguous","server.destroy_requested","server.destroyed","server.destroy_failed","server.action","server.rebuild_requested","server.rebuilt","server.rebuild_failed","server.updated","server.suspended","server.unsuspended","server.orphaned","server.adopted","backup.requested","backup.restore_requested","backup.deleted","partner.suspended","partner.unsuspended","partner.frozen","partner.unfrozen","partner.billed","webhook.test"]},"at":{"type":"string","format":"date-time"},"server_id":{"type":["string","null"]},"data":{"type":"object","additionalProperties":{}}},"required":["id","type","at","server_id","data"],"additionalProperties":false},"Error":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["UNAUTHENTICATED","FORBIDDEN","NETWORK_RESTRICTED","FROZEN","PARTNER_SUSPENDED","QUOTA","NOT_FOUND","VALIDATION","CONFLICT","IDEMPOTENCY_MISMATCH","CREDIT_LIMIT","INFLIGHT_LIMIT","RATE_LIMITED","KEY_LIMIT","UPSTREAM","STORE_BUSY","STORE_UNAVAILABLE","MAINTENANCE","BAD_REQUEST","INTERNAL"]},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}