{ "openapi": "3.0.3", "info": { "title": "Solume reseller API", "version": "1.0.0", "description": "Resell VPS and VDS servers from your own systems: browse the catalog, quote and buy, operate servers, pay renewals and receive events. Using the API has no cost: you pay the price of each service (minus the discount agreed for your key, plus the card fee agreed for your key; both 0 by default).\n\nAuthenticate with `Authorization: Bearer `. Every error has the same JSON shape. Money is in integer cents. See the full guide, quickstart and code examples at https://solumecore.com/docs/reseller-api.\nThe test environment is documented in reseller-sandbox-v1.json (https://api.solumecore.com/sandbox/v1).", "contact": { "name": "Solume support", "url": "https://solumecore.com/contact" } }, "externalDocs": { "description": "Full guide, quickstart and best practices", "url": "https://solumecore.com/docs/reseller-api" }, "servers": [ { "url": "https://api.solumecore.com/v1", "description": "Production" } ], "security": [ { "bearerAuth": [] } ], "tags": [ { "name": "Account", "description": "Who the key is, balance, payment method, top-ups and events." }, { "name": "Catalog", "description": "Plans, locations, OS templates, purchase options and quotes." }, { "name": "Orders", "description": "Buy a VPS/VDS and follow the order." }, { "name": "Services", "description": "Read and operate the services: power, credentials, network, SSH keys, cancellation and tasks." }, { "name": "Firewall", "description": "Firewall of the service. The engine depends on the node: shield, gsk or none." }, { "name": "Billing", "description": "Renewals, auto-renew mode and invoices." } ], "paths": { "/balance": { "get": { "summary": "Account balance", "tags": ["Account"], "description": "Credit available in the account, in its currency. Orders and renewals paid with `payment: \"balance\"` (or \"auto\") draw from it. Requires the \"billing\" scope.\n\n**Permission:** `billing`.", "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "balance": { "type": "object", "properties": { "amount_cents": { "type": "integer", "description": "Amount in minor units (cents). Never a float." }, "currency": { "type": "string", "minLength": 3, "maxLength": 3, "description": "ISO 4217 currency code, e.g. \"USD\"." } }, "required": ["amount_cents", "currency"], "additionalProperties": false } }, "required": ["balance"], "additionalProperties": false }, "example": { "balance": { "amount_cents": 2500, "currency": "USD" } } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "400": { "description": "Error response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable, documented error code." }, "message": { "type": "string", "description": "Human-readable text; may change." }, "request_id": { "type": "string", "description": "Same value as the X-Request-Id response header." }, "details": { "type": "object", "additionalProperties": {} } }, "required": ["code", "message", "request_id"], "additionalProperties": false } }, "required": ["error"], "additionalProperties": false, "description": "Error response." } } } }, "401": { "description": "Missing, unknown or revoked API key (code `unauthorized`).", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Forbidden: `ip_not_allowed`, `insufficient_scope`, `wrong_environment`, spending cap or rejected order.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable, documented error code." }, "message": { "type": "string", "description": "Human-readable text; may change." }, "request_id": { "type": "string", "description": "Same value as the X-Request-Id response header." }, "details": { "type": "object", "additionalProperties": {} } }, "required": ["code", "message", "request_id"], "additionalProperties": false } }, "required": ["error"], "additionalProperties": false, "description": "Error response." } } } }, "429": { "description": "Rate limit reached. Read `Retry-After`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal error. Quote `request_id` to support.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Temporarily unavailable. `internal_error`: A platform dependency does not answer; retry after Retry-After seconds.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "operationId": "getBalance", "x-required-scope": "billing", "parameters": [] } }, "/balance/top-ups": { "post": { "summary": "Start a balance top-up", "tags": ["Account"], "description": "Creates a top-up invoice and returns the URL of the hosted checkout where the account owner pays it (card, PayPal or crypto). Nothing is charged by this call; the balance is credited when the payment is confirmed. The page asks the owner to sign in. Requires the \"billing\" scope and the `Idempotency-Key` header (8-64 characters: letters, digits, \"_\" or \"-\").\n\n**Permission:** `billing`. **Requires** the `Idempotency-Key` header.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "amount_cents": { "type": "integer", "exclusiveMinimum": true, "minimum": 0, "description": "Amount to add, in cents." }, "method": { "type": "string", "enum": ["card", "paypal", "crypto"], "description": "Payment method to offer." } }, "required": ["amount_cents", "method"], "additionalProperties": false }, "example": { "amount_cents": 5000, "method": "paypal" } } } }, "responses": { "201": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "checkout_url": { "type": "string", "format": "uri" }, "expires_at": { "type": "string" }, "amount": { "type": "object", "properties": { "amount_cents": { "type": "integer", "description": "Amount in minor units (cents). Never a float." }, "currency": { "type": "string", "minLength": 3, "maxLength": 3, "description": "ISO 4217 currency code, e.g. \"USD\"." } }, "required": ["amount_cents", "currency"], "additionalProperties": false }, "method": { "type": "string", "enum": ["card", "paypal", "crypto"] } }, "required": ["checkout_url", "expires_at", "amount", "method"], "additionalProperties": false }, "example": { "checkout_url": "https://solumecore.com/pay/top-up/chk_example", "expires_at": "2026-11-05T13:00:00.000Z", "amount": { "amount_cents": 5000, "currency": "USD" }, "method": "paypal" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "400": { "description": "Invalid request (code `invalid_request`, or a missing/malformed `Idempotency-Key`).", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, unknown or revoked API key (code `unauthorized`).", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Forbidden: `ip_not_allowed`, `insufficient_scope`, `wrong_environment`, spending cap or rejected order.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable, documented error code." }, "message": { "type": "string", "description": "Human-readable text; may change." }, "request_id": { "type": "string", "description": "Same value as the X-Request-Id response header." }, "details": { "type": "object", "additionalProperties": {} } }, "required": ["code", "message", "request_id"], "additionalProperties": false } }, "required": ["error"], "additionalProperties": false, "description": "Error response." } } } }, "409": { "description": "Conflict with the current state. `conflict`: That payment method or top-ups are not available right now. `request_in_progress`: The same Idempotency-Key is still running.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Unprocessable request. `idempotency_key_reused`: The Idempotency-Key was used with a different request.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit reached. Read `Retry-After`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal error. Quote `request_id` to support.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Temporarily unavailable. `internal_error`: A platform dependency does not answer; retry after Retry-After seconds.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "operationId": "postBalanceTopUps", "x-required-scope": "billing", "x-idempotent": true, "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "description": "8-64 characters: letters, digits, `_` or `-`. Same key + same body within 24 h replays the stored response (`Idempotent-Replay: true`).", "schema": { "type": "string", "minLength": 8, "maxLength": 64, "pattern": "^[A-Za-z0-9_-]{8,64}$", "example": "order-acme-42-001" } } ] } }, "/catalog/locations": { "get": { "summary": "List the locations that sell VPS/VDS, with a stock flag", "tags": ["Catalog"], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Location code: use it as `location_id`." }, "name": { "type": "string" }, "country": { "type": "string" }, "city": { "type": "string", "nullable": true }, "in_stock": { "type": "boolean" }, "coming_soon": { "type": "boolean" } }, "required": ["id", "name", "country", "city", "in_stock", "coming_soon"], "additionalProperties": false } }, "next_cursor": { "type": "string", "nullable": true } }, "required": ["data", "next_cursor"], "additionalProperties": false }, "example": { "data": [ { "id": "us-mia-1", "name": "Miami", "country": "US", "city": null, "in_stock": true, "coming_soon": false } ], "next_cursor": null } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "401": { "description": "Missing, unknown or revoked API key (code `unauthorized`).", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Forbidden: `ip_not_allowed`, `insufficient_scope`, `wrong_environment`, spending cap or rejected order.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit reached. Read `Retry-After`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal error. Quote `request_id` to support.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Temporarily unavailable. `internal_error`: A platform dependency does not answer; retry after Retry-After seconds.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "operationId": "getCatalogLocations", "description": "**Permission:** `read`.", "x-required-scope": "read", "parameters": [] } }, "/catalog/options": { "get": { "summary": "List the purchase options (e.g. Anti-DDoS) available for a plan, with prices per cycle", "tags": ["Catalog"], "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 40 }, "in": "query", "name": "plan", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "slug": { "type": "string", "description": "Use it as `options[].slug`." }, "title": { "type": "string" }, "description": { "type": "string" }, "default_answer": { "type": "string", "enum": ["yes", "no"] }, "currency": { "type": "string" }, "prices": { "type": "object", "properties": { "monthly": { "type": "object", "properties": { "recurring": { "type": "object", "properties": { "list_price": { "type": "object", "properties": { "amount_cents": { "type": "integer", "description": "Amount in minor units (cents). Never a float." }, "currency": { "type": "string", "description": "ISO 4217 currency code, e.g. \"USD\"." } }, "required": ["amount_cents", "currency"], "additionalProperties": false, "description": "Website price for the cycle." }, "your_price": { "type": "object", "properties": { "amount_cents": { "type": "integer", "description": "Amount in minor units (cents). Never a float." }, "currency": { "type": "string", "description": "ISO 4217 currency code, e.g. \"USD\"." } }, "required": ["amount_cents", "currency"], "additionalProperties": false, "description": "List price minus the discount agreed for your key." } }, "required": ["list_price", "your_price"], "additionalProperties": false, "nullable": true, "description": "Charged every cycle." }, "one_time": { "type": "object", "properties": { "list_price": { "type": "object", "properties": { "amount_cents": { "type": "integer", "description": "Amount in minor units (cents). Never a float." }, "currency": { "type": "string", "description": "ISO 4217 currency code, e.g. \"USD\"." } }, "required": ["amount_cents", "currency"], "additionalProperties": false, "description": "Website price for the cycle." }, "your_price": { "type": "object", "properties": { "amount_cents": { "type": "integer", "description": "Amount in minor units (cents). Never a float." }, "currency": { "type": "string", "description": "ISO 4217 currency code, e.g. \"USD\"." } }, "required": ["amount_cents", "currency"], "additionalProperties": false, "description": "List price minus the discount agreed for your key." } }, "required": ["list_price", "your_price"], "additionalProperties": false, "nullable": true, "description": "Charged once." }, "first_invoice": { "type": "object", "properties": { "list_price": { "type": "object", "properties": { "amount_cents": { "type": "integer", "description": "Amount in minor units (cents). Never a float." }, "currency": { "type": "string", "description": "ISO 4217 currency code, e.g. \"USD\"." } }, "required": ["amount_cents", "currency"], "additionalProperties": false, "description": "Website price for the cycle." }, "your_price": { "type": "object", "properties": { "amount_cents": { "type": "integer", "description": "Amount in minor units (cents). Never a float." }, "currency": { "type": "string", "description": "ISO 4217 currency code, e.g. \"USD\"." } }, "required": ["amount_cents", "currency"], "additionalProperties": false, "description": "List price minus the discount agreed for your key." } }, "required": ["list_price", "your_price"], "additionalProperties": false, "description": "What the first invoice adds for this option." } }, "required": ["recurring", "one_time", "first_invoice"], "additionalProperties": false, "nullable": true, "description": "null when the option has no price for that cycle (it cannot be chosen)." }, "quarterly": { "type": "object", "properties": { "recurring": { "type": "object", "properties": { "list_price": { "type": "object", "properties": { "amount_cents": { "type": "integer", "description": "Amount in minor units (cents). Never a float." }, "currency": { "type": "string", "description": "ISO 4217 currency code, e.g. \"USD\"." } }, "required": ["amount_cents", "currency"], "additionalProperties": false, "description": "Website price for the cycle." }, "your_price": { "type": "object", "properties": { "amount_cents": { "type": "integer", "description": "Amount in minor units (cents). Never a float." }, "currency": { "type": "string", "description": "ISO 4217 currency code, e.g. \"USD\"." } }, "required": ["amount_cents", "currency"], "additionalProperties": false, "description": "List price minus the discount agreed for your key." } }, "required": ["list_price", "your_price"], "additionalProperties": false, "nullable": true, "description": "Charged every cycle." }, "one_time": { "type": "object", "properties": { "list_price": { "type": "object", "properties": { "amount_cents": { "type": "integer", "description": "Amount in minor units (cents). Never a float." }, "currency": { "type": "string", "description": "ISO 4217 currency code, e.g. \"USD\"." } }, "required": ["amount_cents", "currency"], "additionalProperties": false, "description": "Website price for the cycle." }, "your_price": { "type": "object", "properties": { "amount_cents": { "type": "integer", "description": "Amount in minor units (cents). Never a float." }, "currency": { "type": "string", "description": "ISO 4217 currency code, e.g. \"USD\"." } }, "required": ["amount_cents", "currency"], "additionalProperties": false, "description": "List price minus the discount agreed for your key." } }, "required": ["list_price", "your_price"], "additionalProperties": false, "nullable": true, "description": "Charged once." }, "first_invoice": { "type": "object", "properties": { "list_price": { "type": "object", "properties": { "amount_cents": { "type": "integer", "description": "Amount in minor units (cents). Never a float." }, "currency": { "type": "string", "description": "ISO 4217 currency code, e.g. \"USD\"." } }, "required": ["amount_cents", "currency"], "additionalProperties": false, "description": "Website price for the cycle." }, "your_price": { "type": "object", "properties": { "amount_cents": { "type": "integer", "description": "Amount in minor units (cents). Never a float." }, "currency": { "type": "string", "description": "ISO 4217 currency code, e.g. \"USD\"." } }, "required": ["amount_cents", "currency"], "additionalProperties": false, "description": "List price minus the discount agreed for your key." } }, "required": ["list_price", "your_price"], "additionalProperties": false, "description": "What the first invoice adds for this option." } }, "required": ["recurring", "one_time", "first_invoice"], "additionalProperties": false, "nullable": true, "description": "null when the option has no price for that cycle (it cannot be chosen)." }, "semiannual": { "type": "object", "properties": { "recurring": { "type": "object", "properties": { "list_price": { "type": "object", "properties": { "amount_cents": { "type": "integer", "description": "Amount in minor units (cents). Never a float." }, "currency": { "type": "string", "description": "ISO 4217 currency code, e.g. \"USD\"." } }, "required": ["amount_cents", "currency"], "additionalProperties": false, "description": "Website price for the cycle." }, "your_price": { "type": "object", "properties": { "amount_cents": { "type": "integer", "description": "Amount in minor units (cents). Never a float." }, "currency": { "type": "string", "description": "ISO 4217 currency code, e.g. \"USD\"." } }, "required": ["amount_cents", "currency"], "additionalProperties": false, "description": "List price minus the discount agreed for your key." } }, "required": ["list_price", "your_price"], "additionalProperties": false, "nullable": true, "description": "Charged every cycle." }, "one_time": { "type": "object", "properties": { "list_price": { "type": "object", "properties": { "amount_cents": { "type": "integer", "description": "Amount in minor units (cents). Never a float." }, "currency": { "type": "string", "description": "ISO 4217 currency code, e.g. \"USD\"." } }, "required": ["amount_cents", "currency"], "additionalProperties": false, "description": "Website price for the cycle." }, "your_price": { "type": "object", "properties": { "amount_cents": { "type": "integer", "description": "Amount in minor units (cents). Never a float." }, "currency": { "type": "string", "description": "ISO 4217 currency code, e.g. \"USD\"." } }, "required": ["amount_cents", "currency"], "additionalProperties": false, "description": "List price minus the discount agreed for your key." } }, "required": ["list_price", "your_price"], "additionalProperties": false, "nullable": true, "description": "Charged once." }, "first_invoice": { "type": "object", "properties": { "list_price": { "type": "object", "properties": { "amount_cents": { "type": "integer", "description": "Amount in minor units (cents). Never a float." }, "currency": { "type": "string", "description": "ISO 4217 currency code, e.g. \"USD\"." } }, "required": ["amount_cents", "currency"], "additionalProperties": false, "description": "Website price for the cycle." }, "your_price": { "type": "object", "properties": { "amount_cents": { "type": "integer", "description": "Amount in minor units (cents). Never a float." }, "currency": { "type": "string", "description": "ISO 4217 currency code, e.g. \"USD\"." } }, "required": ["amount_cents", "currency"], "additionalProperties": false, "description": "List price minus the discount agreed for your key." } }, "required": ["list_price", "your_price"], "additionalProperties": false, "description": "What the first invoice adds for this option." } }, "required": ["recurring", "one_time", "first_invoice"], "additionalProperties": false, "nullable": true, "description": "null when the option has no price for that cycle (it cannot be chosen)." }, "annual": { "type": "object", "properties": { "recurring": { "type": "object", "properties": { "list_price": { "type": "object", "properties": { "amount_cents": { "type": "integer", "description": "Amount in minor units (cents). Never a float." }, "currency": { "type": "string", "description": "ISO 4217 currency code, e.g. \"USD\"." } }, "required": ["amount_cents", "currency"], "additionalProperties": false, "description": "Website price for the cycle." }, "your_price": { "type": "object", "properties": { "amount_cents": { "type": "integer", "description": "Amount in minor units (cents). Never a float." }, "currency": { "type": "string", "description": "ISO 4217 currency code, e.g. \"USD\"." } }, "required": ["amount_cents", "currency"], "additionalProperties": false, "description": "List price minus the discount agreed for your key." } }, "required": ["list_price", "your_price"], "additionalProperties": false, "nullable": true, "description": "Charged every cycle." }, "one_time": { "type": "object", "properties": { "list_price": { "type": "object", "properties": { "amount_cents": { "type": "integer", "description": "Amount in minor units (cents). Never a float." }, "currency": { "type": "string", "description": "ISO 4217 currency code, e.g. \"USD\"." } }, "required": ["amount_cents", "currency"], "additionalProperties": false, "description": "Website price for the cycle." }, "your_price": { "type": "object", "properties": { "amount_cents": { "type": "integer", "description": "Amount in minor units (cents). Never a float." }, "currency": { "type": "string", "description": "ISO 4217 currency code, e.g. \"USD\"." } }, "required": ["amount_cents", "currency"], "additionalProperties": false, "description": "List price minus the discount agreed for your key." } }, "required": ["list_price", "your_price"], "additionalProperties": false, "nullable": true, "description": "Charged once." }, "first_invoice": { "type": "object", "properties": { "list_price": { "type": "object", "properties": { "amount_cents": { "type": "integer", "description": "Amount in minor units (cents). Never a float." }, "currency": { "type": "string", "description": "ISO 4217 currency code, e.g. \"USD\"." } }, "required": ["amount_cents", "currency"], "additionalProperties": false, "description": "Website price for the cycle." }, "your_price": { "type": "object", "properties": { "amount_cents": { "type": "integer", "description": "Amount in minor units (cents). Never a float." }, "currency": { "type": "string", "description": "ISO 4217 currency code, e.g. \"USD\"." } }, "required": ["amount_cents", "currency"], "additionalProperties": false, "description": "List price minus the discount agreed for your key." } }, "required": ["list_price", "your_price"], "additionalProperties": false, "description": "What the first invoice adds for this option." } }, "required": ["recurring", "one_time", "first_invoice"], "additionalProperties": false, "nullable": true, "description": "null when the option has no price for that cycle (it cannot be chosen)." } }, "required": ["monthly", "quarterly", "semiannual", "annual"], "additionalProperties": false } }, "required": [ "slug", "title", "description", "default_answer", "currency", "prices" ], "additionalProperties": false } }, "next_cursor": { "type": "string", "nullable": true } }, "required": ["data", "next_cursor"], "additionalProperties": false }, "example": { "data": [ { "slug": "anti-ddos", "title": "Anti-DDoS", "description": "Extra DDoS protection", "default_answer": "no", "currency": "USD", "prices": { "monthly": { "recurring": { "list_price": { "amount_cents": 300, "currency": "USD" }, "your_price": { "amount_cents": 270, "currency": "USD" } }, "one_time": null, "first_invoice": { "list_price": { "amount_cents": 300, "currency": "USD" }, "your_price": { "amount_cents": 270, "currency": "USD" } } }, "quarterly": null, "semiannual": null, "annual": null } } ], "next_cursor": null } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "400": { "description": "Invalid request (code `invalid_request`, or a missing/malformed `Idempotency-Key`).", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, unknown or revoked API key (code `unauthorized`).", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Forbidden: `ip_not_allowed`, `insufficient_scope`, `wrong_environment`, spending cap or rejected order.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit reached. Read `Retry-After`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal error. Quote `request_id` to support.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Temporarily unavailable. `internal_error`: A platform dependency does not answer; retry after Retry-After seconds.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "operationId": "getCatalogOptions", "description": "**Permission:** `read`.", "x-required-scope": "read" } }, "/catalog/os-templates": { "get": { "summary": "List the OS templates valid for a plan", "tags": ["Catalog"], "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 40 }, "in": "query", "name": "plan", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Template id: use it as `os_template_id`." }, "name": { "type": "string" }, "family": { "type": "string", "enum": ["linux", "windows"] }, "distro": { "type": "string" }, "version": { "type": "string", "nullable": true }, "min_disk_gb": { "type": "number", "nullable": true }, "min_ram_mb": { "type": "number", "nullable": true }, "default_user": { "type": "string", "description": "\"root\" on Linux, \"Administrator\" on Windows." } }, "required": [ "id", "name", "family", "distro", "version", "min_disk_gb", "min_ram_mb", "default_user" ], "additionalProperties": false } }, "next_cursor": { "type": "string", "nullable": true } }, "required": ["data", "next_cursor"], "additionalProperties": false }, "example": { "data": [ { "id": "cm3x7k2p00002ubuntu2404", "name": "Ubuntu 24.04 LTS", "family": "linux", "distro": "ubuntu", "version": "24.04", "min_disk_gb": null, "min_ram_mb": 512, "default_user": "root" } ], "next_cursor": null } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "400": { "description": "Invalid request (code `invalid_request`, or a missing/malformed `Idempotency-Key`).", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, unknown or revoked API key (code `unauthorized`).", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Forbidden: `ip_not_allowed`, `insufficient_scope`, `wrong_environment`, spending cap or rejected order.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit reached. Read `Retry-After`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal error. Quote `request_id` to support.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Temporarily unavailable. `internal_error`: A platform dependency does not answer; retry after Retry-After seconds.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "operationId": "getCatalogOsTemplates", "description": "**Permission:** `read`.", "x-required-scope": "read" } }, "/catalog/plans": { "get": { "summary": "List the VPS/VDS plans you can resell, with list price and your price per cycle", "tags": ["Catalog"], "parameters": [ { "schema": { "type": "string", "enum": ["vps", "vds"] }, "in": "query", "name": "type", "required": false }, { "schema": { "type": "string", "minLength": 1, "maxLength": 60 }, "in": "query", "name": "location", "required": false } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Plan id: use it as `plan_id` when quoting and ordering." }, "name": { "type": "string" }, "type": { "type": "string", "enum": ["vps", "vds"] }, "location": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "country": { "type": "string" } }, "required": ["id", "name", "country"], "additionalProperties": false }, "specs": { "type": "object", "properties": { "cores": { "type": "integer" }, "ram_mb": { "type": "integer" }, "disk_gb": { "type": "integer" }, "bandwidth_mbps": { "type": "number", "nullable": true }, "bandwidth_label": { "type": "string", "nullable": true }, "transfer_gb": { "type": "number", "nullable": true, "description": "Included monthly transfer; null means unlimited." }, "ipv4": { "type": "integer" }, "cpu_model": { "type": "string", "nullable": true }, "disk_type": { "type": "string", "nullable": true }, "ram_type": { "type": "string", "nullable": true } }, "required": [ "cores", "ram_mb", "disk_gb", "bandwidth_mbps", "bandwidth_label", "transfer_gb", "ipv4", "cpu_model", "disk_type", "ram_type" ], "additionalProperties": false }, "currency": { "type": "string" }, "prices": { "type": "object", "properties": { "monthly": { "type": "object", "properties": { "list_price": { "type": "object", "properties": { "amount_cents": { "type": "integer", "description": "Amount in minor units (cents). Never a float." }, "currency": { "type": "string", "description": "ISO 4217 currency code, e.g. \"USD\"." } }, "required": ["amount_cents", "currency"], "additionalProperties": false, "description": "Website price for the cycle." }, "your_price": { "type": "object", "properties": { "amount_cents": { "type": "integer", "description": "Amount in minor units (cents). Never a float." }, "currency": { "type": "string", "description": "ISO 4217 currency code, e.g. \"USD\"." } }, "required": ["amount_cents", "currency"], "additionalProperties": false, "description": "List price minus the discount agreed for your key." } }, "required": ["list_price", "your_price"], "additionalProperties": false }, "quarterly": { "type": "object", "properties": { "list_price": { "type": "object", "properties": { "amount_cents": { "type": "integer", "description": "Amount in minor units (cents). Never a float." }, "currency": { "type": "string", "description": "ISO 4217 currency code, e.g. \"USD\"." } }, "required": ["amount_cents", "currency"], "additionalProperties": false, "description": "Website price for the cycle." }, "your_price": { "type": "object", "properties": { "amount_cents": { "type": "integer", "description": "Amount in minor units (cents). Never a float." }, "currency": { "type": "string", "description": "ISO 4217 currency code, e.g. \"USD\"." } }, "required": ["amount_cents", "currency"], "additionalProperties": false, "description": "List price minus the discount agreed for your key." } }, "required": ["list_price", "your_price"], "additionalProperties": false }, "semiannual": { "type": "object", "properties": { "list_price": { "type": "object", "properties": { "amount_cents": { "type": "integer", "description": "Amount in minor units (cents). Never a float." }, "currency": { "type": "string", "description": "ISO 4217 currency code, e.g. \"USD\"." } }, "required": ["amount_cents", "currency"], "additionalProperties": false, "description": "Website price for the cycle." }, "your_price": { "type": "object", "properties": { "amount_cents": { "type": "integer", "description": "Amount in minor units (cents). Never a float." }, "currency": { "type": "string", "description": "ISO 4217 currency code, e.g. \"USD\"." } }, "required": ["amount_cents", "currency"], "additionalProperties": false, "description": "List price minus the discount agreed for your key." } }, "required": ["list_price", "your_price"], "additionalProperties": false }, "annual": { "type": "object", "properties": { "list_price": { "type": "object", "properties": { "amount_cents": { "type": "integer", "description": "Amount in minor units (cents). Never a float." }, "currency": { "type": "string", "description": "ISO 4217 currency code, e.g. \"USD\"." } }, "required": ["amount_cents", "currency"], "additionalProperties": false, "description": "Website price for the cycle." }, "your_price": { "type": "object", "properties": { "amount_cents": { "type": "integer", "description": "Amount in minor units (cents). Never a float." }, "currency": { "type": "string", "description": "ISO 4217 currency code, e.g. \"USD\"." } }, "required": ["amount_cents", "currency"], "additionalProperties": false, "description": "List price minus the discount agreed for your key." } }, "required": ["list_price", "your_price"], "additionalProperties": false } }, "required": ["monthly", "quarterly", "semiannual", "annual"], "additionalProperties": false }, "available": { "type": "boolean", "description": "In stock and not \"coming soon\"." }, "availability": { "type": "string", "enum": ["in_stock", "out_of_stock", "coming_soon"] } }, "required": [ "id", "name", "type", "location", "specs", "currency", "prices", "available", "availability" ], "additionalProperties": false } }, "next_cursor": { "type": "string", "nullable": true } }, "required": ["data", "next_cursor"], "additionalProperties": false }, "example": { "data": [ { "id": "cm3x7k2p00001vps2gb", "name": "VPS Small", "type": "vps", "location": { "id": "us-mia-1", "name": "Miami", "country": "US" }, "specs": { "cores": 2, "ram_mb": 2048, "disk_gb": 40, "bandwidth_mbps": 1000, "bandwidth_label": "1 Gbps", "transfer_gb": null, "ipv4": 1, "cpu_model": "AMD EPYC", "disk_type": "NVME", "ram_type": "DDR5" }, "currency": "USD", "prices": { "monthly": { "list_price": { "amount_cents": 800, "currency": "USD" }, "your_price": { "amount_cents": 720, "currency": "USD" } }, "quarterly": { "list_price": { "amount_cents": 2280, "currency": "USD" }, "your_price": { "amount_cents": 2052, "currency": "USD" } }, "semiannual": { "list_price": { "amount_cents": 4320, "currency": "USD" }, "your_price": { "amount_cents": 3888, "currency": "USD" } }, "annual": { "list_price": { "amount_cents": 8160, "currency": "USD" }, "your_price": { "amount_cents": 7344, "currency": "USD" } } }, "available": true, "availability": "in_stock" } ], "next_cursor": null } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "400": { "description": "Invalid request (code `invalid_request`, or a missing/malformed `Idempotency-Key`).", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, unknown or revoked API key (code `unauthorized`).", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Forbidden: `ip_not_allowed`, `insufficient_scope`, `wrong_environment`, spending cap or rejected order.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit reached. Read `Retry-After`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal error. Quote `request_id` to support.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Temporarily unavailable. `internal_error`: A platform dependency does not answer; retry after Retry-After seconds.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "operationId": "getCatalogPlans", "description": "**Permission:** `read`.", "x-required-scope": "read" } }, "/events": { "get": { "summary": "List account events (pull alternative to webhooks)", "tags": ["Account"], "description": "Events of the last 30 days, oldest first, in the same shape the account webhooks deliver. Use `since` (ISO-8601) or the returned `next_cursor` to continue where you left off. Requires the \"read\" scope.\n\n**Permission:** `read`.", "parameters": [ { "schema": { "type": "string", "format": "date-time" }, "in": "query", "name": "since", "required": false, "description": "Only events created after this instant (ISO-8601)." }, { "schema": { "type": "string", "minLength": 1, "maxLength": 80 }, "in": "query", "name": "type", "required": false, "description": "Only this event type." }, { "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25 }, "in": "query", "name": "limit", "required": false }, { "schema": { "type": "string", "minLength": 1, "maxLength": 200 }, "in": "query", "name": "cursor", "required": false } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique, stable event id (dedupe on this)." }, "event": { "type": "string", "description": "Event type, e.g. \"servicio.activo\"." }, "created_at": { "type": "string" }, "service": { "type": "object", "properties": { "id": { "type": "string", "description": "Service id (the public code used everywhere in this API)." }, "name": { "type": "string" }, "type": { "type": "string" } }, "required": ["id", "name", "type"], "additionalProperties": false, "nullable": true }, "actor": { "type": "object", "properties": { "type": { "type": "string" }, "name": { "type": "string", "nullable": true } }, "required": ["type", "name"], "additionalProperties": false, "nullable": true, "description": "Who did it, seen by the account owner. Never carries ids." }, "data": { "type": "object", "additionalProperties": {}, "description": "Event data; never contains credentials." } }, "required": ["id", "event", "created_at", "service", "actor", "data"], "additionalProperties": false } }, "next_cursor": { "type": "string", "nullable": true } }, "required": ["data", "next_cursor"], "additionalProperties": false }, "example": { "data": [ { "id": "evt_cm3z0a1b20001xyz", "event": "invoice.paid", "created_at": "2026-12-02T06:01:12.000Z", "service": null, "actor": null, "data": { "invoice_id": "inv_cm3z4c9s00007renew02", "number": "INV-2026-000412", "status": "paid", "total": { "amount_cents": 720, "currency": "USD" }, "due_at": "2026-12-05T06:00:00.000Z", "paid_at": "2026-12-02T06:01:12.000Z", "service_ids": ["K3F8QX2P"] } } ], "next_cursor": null } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "400": { "description": "Invalid request (code `invalid_request`, or a missing/malformed `Idempotency-Key`).", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, unknown or revoked API key (code `unauthorized`).", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Forbidden: `ip_not_allowed`, `insufficient_scope`, `wrong_environment`, spending cap or rejected order.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable, documented error code." }, "message": { "type": "string", "description": "Human-readable text; may change." }, "request_id": { "type": "string", "description": "Same value as the X-Request-Id response header." }, "details": { "type": "object", "additionalProperties": {} } }, "required": ["code", "message", "request_id"], "additionalProperties": false } }, "required": ["error"], "additionalProperties": false, "description": "Error response." } } } }, "429": { "description": "Rate limit reached. Read `Retry-After`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal error. Quote `request_id` to support.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Temporarily unavailable. `internal_error`: A platform dependency does not answer; retry after Retry-After seconds.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "operationId": "getEvents", "x-required-scope": "read" } }, "/invoices": { "get": { "summary": "List invoices", "tags": ["Billing"], "parameters": [ { "schema": { "type": "string", "enum": ["open", "overdue", "paid", "cancelled", "disputed"] }, "in": "query", "name": "status", "required": false }, { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "in": "query", "name": "service_id", "required": false }, { "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25 }, "in": "query", "name": "limit", "required": false }, { "schema": { "type": "string", "maxLength": 200 }, "in": "query", "name": "cursor", "required": false } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "number": { "type": "string" }, "status": { "type": "string", "enum": ["open", "overdue", "paid", "cancelled", "disputed"] }, "total": { "type": "object", "properties": { "amount_cents": { "type": "integer" }, "currency": { "type": "string" } }, "required": ["amount_cents", "currency"], "additionalProperties": false }, "created_at": { "type": "string" }, "due_at": { "type": "string" }, "paid_at": { "type": "string", "nullable": true }, "lines": { "type": "array", "items": { "type": "object", "properties": { "description": { "type": "string" }, "type": { "type": "string" }, "service_id": { "type": "string", "nullable": true }, "quantity": { "type": "integer" }, "unit_price": { "type": "object", "properties": { "amount_cents": { "type": "integer" }, "currency": { "type": "string" } }, "required": ["amount_cents", "currency"], "additionalProperties": false }, "total": { "type": "object", "properties": { "amount_cents": { "type": "integer" }, "currency": { "type": "string" } }, "required": ["amount_cents", "currency"], "additionalProperties": false } }, "required": [ "description", "type", "service_id", "quantity", "unit_price", "total" ], "additionalProperties": false } } }, "required": [ "id", "number", "status", "total", "created_at", "due_at", "paid_at", "lines" ], "additionalProperties": false } }, "next_cursor": { "type": "string", "nullable": true } }, "required": ["data", "next_cursor"], "additionalProperties": false }, "example": { "data": [ { "id": "inv_cm3z4c9s00007renew02", "number": "INV-2026-000412", "status": "paid", "total": { "amount_cents": 720, "currency": "USD" }, "created_at": "2026-12-02T06:00:00.000Z", "due_at": "2026-12-05T06:00:00.000Z", "paid_at": "2026-12-02T06:01:12.000Z", "lines": [ { "description": "Service renewal - VPS Small (monthly) - web-1", "type": "plan", "service_id": "K3F8QX2P", "quantity": 1, "unit_price": { "amount_cents": 800, "currency": "USD" }, "total": { "amount_cents": 800, "currency": "USD" } }, { "description": "Reseller discount (10%)", "type": "discount", "service_id": "K3F8QX2P", "quantity": 1, "unit_price": { "amount_cents": -80, "currency": "USD" }, "total": { "amount_cents": -80, "currency": "USD" } } ] } ], "next_cursor": null } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "400": { "description": "Invalid request (code `invalid_request`, or a missing/malformed `Idempotency-Key`).", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, unknown or revoked API key (code `unauthorized`).", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Forbidden: `ip_not_allowed`, `insufficient_scope`, `wrong_environment`, spending cap or rejected order.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit reached. Read `Retry-After`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal error. Quote `request_id` to support.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Temporarily unavailable. `internal_error`: A platform dependency does not answer; retry after Retry-After seconds.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "operationId": "getInvoices", "description": "**Permission:** `read`.", "x-required-scope": "read" } }, "/invoices/{id}": { "get": { "summary": "Get an invoice", "tags": ["Billing"], "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "number": { "type": "string" }, "status": { "type": "string", "enum": ["open", "overdue", "paid", "cancelled", "disputed"] }, "total": { "type": "object", "properties": { "amount_cents": { "type": "integer" }, "currency": { "type": "string" } }, "required": ["amount_cents", "currency"], "additionalProperties": false }, "created_at": { "type": "string" }, "due_at": { "type": "string" }, "paid_at": { "type": "string", "nullable": true }, "lines": { "type": "array", "items": { "type": "object", "properties": { "description": { "type": "string" }, "type": { "type": "string" }, "service_id": { "type": "string", "nullable": true }, "quantity": { "type": "integer" }, "unit_price": { "type": "object", "properties": { "amount_cents": { "type": "integer" }, "currency": { "type": "string" } }, "required": ["amount_cents", "currency"], "additionalProperties": false }, "total": { "type": "object", "properties": { "amount_cents": { "type": "integer" }, "currency": { "type": "string" } }, "required": ["amount_cents", "currency"], "additionalProperties": false } }, "required": [ "description", "type", "service_id", "quantity", "unit_price", "total" ], "additionalProperties": false } } }, "required": [ "id", "number", "status", "total", "created_at", "due_at", "paid_at", "lines" ], "additionalProperties": false }, "example": { "id": "inv_cm3z4c9s00007renew02", "number": "INV-2026-000412", "status": "paid", "total": { "amount_cents": 720, "currency": "USD" }, "created_at": "2026-12-02T06:00:00.000Z", "due_at": "2026-12-05T06:00:00.000Z", "paid_at": "2026-12-02T06:01:12.000Z", "lines": [ { "description": "Service renewal - VPS Small (monthly) - web-1", "type": "plan", "service_id": "K3F8QX2P", "quantity": 1, "unit_price": { "amount_cents": 800, "currency": "USD" }, "total": { "amount_cents": 800, "currency": "USD" } }, { "description": "Reseller discount (10%)", "type": "discount", "service_id": "K3F8QX2P", "quantity": 1, "unit_price": { "amount_cents": -80, "currency": "USD" }, "total": { "amount_cents": -80, "currency": "USD" } } ] } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "401": { "description": "Missing, unknown or revoked API key (code `unauthorized`).", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Forbidden: `ip_not_allowed`, `insufficient_scope`, `wrong_environment`, spending cap or rejected order.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found (also for resources that belong to someone else).", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit reached. Read `Retry-After`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal error. Quote `request_id` to support.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Temporarily unavailable. `internal_error`: A platform dependency does not answer; retry after Retry-After seconds.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "operationId": "getInvoicesById", "description": "**Permission:** `read`.", "x-required-scope": "read" } }, "/invoices/{id}/pay": { "post": { "summary": "Pay an invoice", "tags": ["Billing"], "description": "Pays an open invoice of VPS/VDS services with the same caps, reservation and payment order as renewals. Requires Idempotency-Key.\n\n**Permission:** `purchase`. **Rate-limit bucket:** `renew` (besides the general one). **Requires** the `Idempotency-Key` header.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "anyOf": [ { "not": {} }, { "type": "object", "properties": { "payment": { "type": "string", "enum": ["auto", "balance", "card"], "default": "auto" } }, "additionalProperties": false, "nullable": true } ] }, "example": { "payment": "balance" } } } }, "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "in": "path", "name": "id", "required": true }, { "name": "Idempotency-Key", "in": "header", "required": true, "description": "8-64 characters: letters, digits, `_` or `-`. Same key + same body within 24 h replays the stored response (`Idempotent-Replay: true`).", "schema": { "type": "string", "minLength": 8, "maxLength": 64, "pattern": "^[A-Za-z0-9_-]{8,64}$", "example": "order-acme-42-001" } } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "invoice": { "type": "object", "properties": { "id": { "type": "string" }, "number": { "type": "string" }, "status": { "type": "string", "enum": ["open", "overdue", "paid", "cancelled", "disputed"] }, "total": { "type": "object", "properties": { "amount_cents": { "type": "integer" }, "currency": { "type": "string" } }, "required": ["amount_cents", "currency"], "additionalProperties": false }, "created_at": { "type": "string" }, "due_at": { "type": "string" }, "paid_at": { "type": "string", "nullable": true }, "lines": { "type": "array", "items": { "type": "object", "properties": { "description": { "type": "string" }, "type": { "type": "string" }, "service_id": { "type": "string", "nullable": true }, "quantity": { "type": "integer" }, "unit_price": { "type": "object", "properties": { "amount_cents": { "type": "integer" }, "currency": { "type": "string" } }, "required": ["amount_cents", "currency"], "additionalProperties": false }, "total": { "type": "object", "properties": { "amount_cents": { "type": "integer" }, "currency": { "type": "string" } }, "required": ["amount_cents", "currency"], "additionalProperties": false } }, "required": [ "description", "type", "service_id", "quantity", "unit_price", "total" ], "additionalProperties": false } } }, "required": [ "id", "number", "status", "total", "created_at", "due_at", "paid_at", "lines" ], "additionalProperties": false }, "already_paid": { "type": "boolean" } }, "required": ["invoice", "already_paid"], "additionalProperties": false }, "example": { "invoice": { "id": "inv_cm3z4c9s00007renew02", "number": "INV-2026-000412", "status": "paid", "total": { "amount_cents": 720, "currency": "USD" }, "created_at": "2026-12-02T06:00:00.000Z", "due_at": "2026-12-05T06:00:00.000Z", "paid_at": "2026-12-02T06:01:12.000Z", "lines": [ { "description": "Service renewal - VPS Small (monthly) - web-1", "type": "plan", "service_id": "K3F8QX2P", "quantity": 1, "unit_price": { "amount_cents": 800, "currency": "USD" }, "total": { "amount_cents": 800, "currency": "USD" } }, { "description": "Reseller discount (10%)", "type": "discount", "service_id": "K3F8QX2P", "quantity": 1, "unit_price": { "amount_cents": -80, "currency": "USD" }, "total": { "amount_cents": -80, "currency": "USD" } } ] }, "already_paid": false } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "400": { "description": "Invalid request (code `invalid_request`, or a missing/malformed `Idempotency-Key`).", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, unknown or revoked API key (code `unauthorized`).", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Payment needs the customer or failed. `requires_action`: The card needs the customer: details.reason is authentication_required (3-D Secure), no_card (no saved default card) or no_mandate (the automatic-charge mandate version 2026-11-v2 is not accepted for the card). Nothing was charged. `card_declined`: The card was declined (details.reason: declined, insufficient_funds) or card payments are switched off (stripe_disabled). Nothing was charged. `insufficient_balance`: The balance does not cover the total (details.required_cents), and with payment \"auto\" no card can be used either (details.card).", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Forbidden: `ip_not_allowed`, `insufficient_scope`, `wrong_environment`, spending cap or rejected order. `spending_cap_exceeded`: The amount, the daily total or the hourly purchase count goes over a cap of the key. `spending_caps_not_set`: The key has \"purchase\" but no spending caps loaded.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found (also for resources that belong to someone else).", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict with the current state. `conflict`: details.reason says why (invoice_not_payable, grouped_invoice, payment_in_progress, no_default_card, mandate_not_accepted...). `request_in_progress`: The same Idempotency-Key is still running.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Unprocessable request. `idempotency_key_reused`: The Idempotency-Key was used with a different request.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit reached. Read `Retry-After`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal error. Quote `request_id` to support.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Temporarily unavailable. `internal_error`: A platform dependency does not answer; retry after Retry-After seconds.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "operationId": "postInvoicesByIdPay", "x-required-scope": "purchase", "x-rate-limit-bucket": "renew", "x-idempotent": true } }, "/me": { "get": { "summary": "Current API key", "tags": ["Account"], "description": "Returns the authenticated key: its scopes, spending caps, usage of the rolling day and hour, commercial conditions (discount and card fee), currency and every rate-limit tier. Works with any scope.\n\n**Permission:** any valid key.", "responses": { "200": { "description": "The authenticated API key and its limits.", "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "The name the account owner gave to this key." }, "key_prefix": { "type": "string", "description": "First characters of the key, to recognise it. Not the secret." }, "tag": { "type": "string", "nullable": true, "description": "Label set by Solume staff (e.g. the reseller brand)." }, "created_at": { "type": "string" }, "last_used_at": { "type": "string", "nullable": true }, "scopes": { "type": "array", "items": { "type": "string", "enum": ["read", "manage", "purchase", "billing"] }, "description": "Permissions granted by Solume staff." }, "can_purchase": { "type": "boolean", "description": "True when the key has the \"purchase\" scope AND its spending caps are loaded." }, "caps": { "type": "object", "properties": { "per_order_cents": { "type": "integer", "nullable": true }, "daily_cents": { "type": "integer", "nullable": true }, "orders_per_hour": { "type": "integer", "nullable": true, "description": "Orders per rolling hour; 10 by default when \"purchase\" is granted." } }, "required": ["per_order_cents", "daily_cents", "orders_per_hour"], "additionalProperties": false }, "usage": { "type": "object", "properties": { "spent_today_cents": { "type": "integer", "description": "Spent in the last 24 hours (rolling)." }, "orders_last_hour": { "type": "integer" } }, "required": ["spent_today_cents", "orders_last_hour"], "additionalProperties": false }, "discount_percent": { "type": "number" }, "card_fee_percent": { "type": "number" }, "currency": { "type": "string" }, "allowed_ips_count": { "type": "integer" }, "rate_limits": { "type": "array", "items": { "type": "object", "properties": { "bucket": { "type": "string" }, "scope": { "type": "string", "enum": ["key_ip", "key", "service"] }, "max": { "type": "integer" }, "window_seconds": { "type": "integer" } }, "required": ["bucket", "scope", "max", "window_seconds"], "additionalProperties": false } } }, "required": [ "name", "key_prefix", "tag", "created_at", "last_used_at", "scopes", "can_purchase", "caps", "usage", "discount_percent", "card_fee_percent", "currency", "allowed_ips_count", "rate_limits" ], "additionalProperties": false, "description": "The authenticated API key and its limits." }, "example": { "name": "Production backend", "key_prefix": "sk_live_8f3a", "tag": "acme", "created_at": "2026-10-20T15:04:00.000Z", "last_used_at": "2026-11-05T12:00:00.000Z", "scopes": ["read", "manage", "purchase", "billing"], "can_purchase": true, "caps": { "per_order_cents": 20000, "daily_cents": 100000, "orders_per_hour": 10 }, "usage": { "spent_today_cents": 720, "orders_last_hour": 1 }, "discount_percent": 10, "card_fee_percent": 3, "currency": "USD", "allowed_ips_count": 2, "rate_limits": [ { "bucket": "general", "scope": "key_ip", "max": 120, "window_seconds": 60 }, { "bucket": "quotes", "scope": "key", "max": 30, "window_seconds": 60 }, { "bucket": "orders", "scope": "key", "max": 30, "window_seconds": 3600 }, { "bucket": "power", "scope": "service", "max": 6, "window_seconds": 60 }, { "bucket": "power", "scope": "service", "max": 40, "window_seconds": 3600 }, { "bucket": "power", "scope": "key", "max": 60, "window_seconds": 60 }, { "bucket": "reinstall", "scope": "service", "max": 1, "window_seconds": 600 }, { "bucket": "reinstall", "scope": "service", "max": 5, "window_seconds": 86400 }, { "bucket": "reinstall", "scope": "key", "max": 20, "window_seconds": 86400 }, { "bucket": "reset-password", "scope": "service", "max": 3, "window_seconds": 3600 }, { "bucket": "reset-password", "scope": "key", "max": 20, "window_seconds": 3600 }, { "bucket": "renew", "scope": "service", "max": 5, "window_seconds": 3600 }, { "bucket": "service-settings", "scope": "service", "max": 10, "window_seconds": 3600 }, { "bucket": "cancel", "scope": "service", "max": 3, "window_seconds": 86400 }, { "bucket": "credentials", "scope": "service", "max": 10, "window_seconds": 3600 } ] } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "400": { "description": "Error response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable, documented error code." }, "message": { "type": "string", "description": "Human-readable text; may change." }, "request_id": { "type": "string", "description": "Same value as the X-Request-Id response header." }, "details": { "type": "object", "additionalProperties": {} } }, "required": ["code", "message", "request_id"], "additionalProperties": false } }, "required": ["error"], "additionalProperties": false, "description": "Error response." } } } }, "401": { "description": "Missing, unknown or revoked API key (code `unauthorized`).", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Forbidden: `ip_not_allowed`, `insufficient_scope`, `wrong_environment`, spending cap or rejected order.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable, documented error code." }, "message": { "type": "string", "description": "Human-readable text; may change." }, "request_id": { "type": "string", "description": "Same value as the X-Request-Id response header." }, "details": { "type": "object", "additionalProperties": {} } }, "required": ["code", "message", "request_id"], "additionalProperties": false } }, "required": ["error"], "additionalProperties": false, "description": "Error response." } } } }, "429": { "description": "Rate limit reached. Read `Retry-After`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal error. Quote `request_id` to support.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Temporarily unavailable. `internal_error`: A platform dependency does not answer; retry after Retry-After seconds.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "operationId": "getMe", "x-required-scope": "any", "parameters": [] } }, "/orders": { "post": { "summary": "Buy a VPS/VDS (requires Idempotency-Key). Provisioning is asynchronous", "tags": ["Orders"], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "plan_id": { "type": "string", "minLength": 1, "maxLength": 40 }, "location_id": { "type": "string", "minLength": 1, "maxLength": 60 }, "billing_cycle": { "type": "string", "enum": ["monthly", "quarterly", "semiannual", "annual"] }, "os_template_id": { "type": "string", "minLength": 1, "maxLength": 40 }, "hostname": { "type": "string", "minLength": 3, "maxLength": 63, "pattern": "^[a-z0-9-]+$" }, "ssh_public_key": { "type": "string", "minLength": 1, "maxLength": 4096 }, "ssh_key_ids": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 40 }, "minItems": 1, "maxItems": 5 }, "options": { "type": "array", "items": { "type": "object", "properties": { "slug": { "type": "string", "minLength": 1, "maxLength": 60 }, "answer": { "type": "string", "enum": ["yes", "no"] } }, "required": ["slug", "answer"], "additionalProperties": false }, "maxItems": 20 }, "payment": { "type": "string", "enum": ["auto", "balance", "card"], "default": "auto" }, "auto_renew": { "type": "string", "enum": ["off", "balance", "balance_and_card", "card"], "default": "off" }, "metadata": { "type": "object", "additionalProperties": { "type": "string", "maxLength": 200 } } }, "required": [ "plan_id", "location_id", "billing_cycle", "os_template_id", "hostname" ], "additionalProperties": false }, "example": { "plan_id": "cm3x7k2p00001vps2gb", "location_id": "us-mia-1", "billing_cycle": "monthly", "os_template_id": "cm3x7k2p00002ubuntu2404", "hostname": "web-1", "ssh_public_key": "ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIOMqqnkVzrm0SdG6UOoqKLsabgH5C9okWi0dh2l9GKJl me@laptop", "options": [ { "slug": "anti-ddos", "answer": "yes" } ], "payment": "auto", "auto_renew": "off", "metadata": { "customer": "acme-42" } } } } }, "responses": { "201": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "order": { "type": "object", "properties": { "id": { "type": "string", "description": "Public order id (`ord_...`)." }, "status": { "type": "string", "enum": [ "pending", "paid", "provisioning", "completed", "failed", "refunded" ] }, "created_at": { "type": "string" }, "currency": { "type": "string" }, "billing_cycle": { "type": "string", "enum": ["monthly", "quarterly", "semiannual", "annual"], "nullable": true }, "lines": { "type": "array", "items": { "type": "object", "properties": { "description": { "type": "string" }, "amount": { "type": "object", "properties": { "amount_cents": { "type": "integer", "description": "Amount in minor units (cents). Never a float." }, "currency": { "type": "string", "description": "ISO 4217 currency code, e.g. \"USD\"." } }, "required": ["amount_cents", "currency"], "additionalProperties": false } }, "required": ["description", "amount"], "additionalProperties": false } }, "subtotal": { "type": "object", "properties": { "amount_cents": { "type": "integer", "description": "Amount in minor units (cents). Never a float." }, "currency": { "type": "string", "description": "ISO 4217 currency code, e.g. \"USD\"." } }, "required": ["amount_cents", "currency"], "additionalProperties": false }, "tax": { "type": "object", "properties": { "amount_cents": { "type": "integer", "description": "Amount in minor units (cents). Never a float." }, "currency": { "type": "string", "description": "ISO 4217 currency code, e.g. \"USD\"." } }, "required": ["amount_cents", "currency"], "additionalProperties": false }, "total": { "type": "object", "properties": { "amount_cents": { "type": "integer", "description": "Amount in minor units (cents). Never a float." }, "currency": { "type": "string", "description": "ISO 4217 currency code, e.g. \"USD\"." } }, "required": ["amount_cents", "currency"], "additionalProperties": false }, "payment_method": { "type": "string", "enum": ["balance", "card"], "nullable": true }, "invoice_number": { "type": "string", "nullable": true }, "invoice_id": { "type": "string", "nullable": true, "description": "Public id (inv_…) of the order invoice: the same id GET /invoices/:id and POST /invoices/:id/pay use." }, "service_id": { "type": "string", "nullable": true, "description": "Public code of the service created by the order." }, "auto_renew": { "type": "string", "enum": ["off", "balance", "balance_and_card", "card"] }, "metadata": { "type": "object", "additionalProperties": { "type": "string" } } }, "required": [ "id", "status", "created_at", "currency", "billing_cycle", "lines", "subtotal", "tax", "total", "payment_method", "invoice_number", "invoice_id", "service_id", "auto_renew", "metadata" ], "additionalProperties": false }, "service": { "type": "object", "properties": { "id": { "type": "string" }, "hostname": { "type": "string" }, "status": { "type": "string", "enum": [ "provisioning", "active", "suspended", "paused", "cancelled", "error" ] }, "power_state": { "type": "string", "nullable": true }, "plan": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "cores": { "type": "integer" }, "ram_mb": { "type": "integer" }, "disk_gb": { "type": "integer" } }, "required": ["id", "name", "cores", "ram_mb", "disk_gb"], "additionalProperties": false }, "location": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "country": { "type": "string" } }, "required": ["id", "name", "country"], "additionalProperties": false }, "os": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" } }, "required": ["id", "name"], "additionalProperties": false, "nullable": true }, "ips": { "type": "array", "items": {}, "description": "Empty until the service is provisioned; read GET /services/{id}." }, "created_at": { "type": "string" }, "origin": { "type": "string", "enum": ["api"] }, "metadata": { "type": "object", "additionalProperties": { "type": "string" } }, "billing": { "type": "object", "additionalProperties": {}, "description": "Same object as `billing` in GET /services/{id}." } }, "required": [ "id", "hostname", "status", "power_state", "plan", "location", "os", "ips", "created_at", "origin", "metadata", "billing" ], "additionalProperties": false, "nullable": true } }, "required": ["order", "service"], "additionalProperties": false }, "example": { "order": { "id": "ord_9173eb967115608b2f", "status": "provisioning", "created_at": "2026-11-05T12:00:00.000Z", "currency": "USD", "billing_cycle": "monthly", "lines": [ { "description": "VPS Small - monthly", "amount": { "amount_cents": 800, "currency": "USD" } }, { "description": "Reseller discount (10%)", "amount": { "amount_cents": -80, "currency": "USD" } } ], "subtotal": { "amount_cents": 720, "currency": "USD" }, "tax": { "amount_cents": 0, "currency": "USD" }, "total": { "amount_cents": 720, "currency": "USD" }, "payment_method": "balance", "invoice_number": "INV-2026-000398", "invoice_id": "inv_cm3f0x8s20009abcd1234", "service_id": "K3F8QX2P", "auto_renew": "off", "metadata": { "customer": "acme-42" } }, "service": { "id": "K3F8QX2P", "hostname": "web-1", "status": "provisioning", "power_state": null, "plan": { "id": "cm3x7k2p00001vps2gb", "name": "VPS Small", "cores": 2, "ram_mb": 2048, "disk_gb": 40 }, "location": { "id": "us-mia-1", "name": "Miami", "country": "US" }, "os": { "id": "cm3x7k2p00002ubuntu2404", "name": "Ubuntu 24.04 LTS" }, "ips": [], "created_at": "2026-11-05T12:00:00.000Z", "origin": "api", "metadata": { "customer": "acme-42" }, "billing": { "cycle": "monthly", "price": { "amount_cents": 720, "currency": "USD" }, "current_period_end": null, "next_invoice_at": null, "open_invoice_id": null, "due_at": null, "grace_ends_at": null, "suspends_at": null, "terminates_at": null, "auto_renew": "off", "cancel_at_period_end": false, "renewable": false } } } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "400": { "description": "Invalid request (code `invalid_request`, or a missing/malformed `Idempotency-Key`).", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, unknown or revoked API key (code `unauthorized`).", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Payment needs the customer or failed. `requires_action`: The card needs the customer: details.reason is authentication_required (3-D Secure), no_card (no saved default card) or no_mandate (the automatic-charge mandate version 2026-11-v2 is not accepted for the card). Nothing was charged. `card_declined`: The card was declined (details.reason: declined, insufficient_funds) or card payments are switched off (stripe_disabled). Nothing was charged. `insufficient_balance`: The balance does not cover the total (details.required_cents), and with payment \"auto\" no card can be used either (details.card).", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Forbidden: `ip_not_allowed`, `insufficient_scope`, `wrong_environment`, spending cap or rejected order. `spending_cap_exceeded`: The amount, the daily total or the hourly purchase count goes over a cap of the key. `spending_caps_not_set`: The key has \"purchase\" but no spending caps loaded. `order_rejected`: The trust and anti-fraud checks of the website also apply (generic message). `product_not_resellable`: The plan is not a VPS/VDS plan.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict with the current state. `out_of_stock`: No stock in that location, or the order was paid but could not be delivered (refunded). `request_in_progress`: An order with this Idempotency-Key is still being processed. `request_in_progress`: The same Idempotency-Key is still running.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Unprocessable request. `invalid_option`: Unknown option, repeated option or no price for that cycle. `idempotency_key_reused`: The Idempotency-Key was used with a different request.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit reached. Read `Retry-After`. `too_many_in_flight`: The key already has 3 orders in flight.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal error. Quote `request_id` to support.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Temporarily unavailable. `internal_error`: A platform dependency does not answer; retry after Retry-After seconds.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "operationId": "postOrders", "description": "**Permission:** `purchase`. **Rate-limit bucket:** `orders` (besides the general one). **Requires** the `Idempotency-Key` header.", "x-required-scope": "purchase", "x-rate-limit-bucket": "orders", "x-idempotent": true, "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "description": "8-64 characters: letters, digits, `_` or `-`. Same key + same body within 24 h replays the stored response (`Idempotent-Replay: true`).", "schema": { "type": "string", "minLength": 8, "maxLength": 64, "pattern": "^[A-Za-z0-9_-]{8,64}$", "example": "order-acme-42-001" } } ] }, "get": { "summary": "List your API orders, newest first", "tags": ["Orders"], "parameters": [ { "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25 }, "in": "query", "name": "limit", "required": false }, { "schema": { "type": "string", "minLength": 1, "maxLength": 60 }, "in": "query", "name": "cursor", "required": false } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Public order id (`ord_...`)." }, "status": { "type": "string", "enum": [ "pending", "paid", "provisioning", "completed", "failed", "refunded" ] }, "created_at": { "type": "string" }, "currency": { "type": "string" }, "billing_cycle": { "type": "string", "enum": ["monthly", "quarterly", "semiannual", "annual"], "nullable": true }, "lines": { "type": "array", "items": { "type": "object", "properties": { "description": { "type": "string" }, "amount": { "type": "object", "properties": { "amount_cents": { "type": "integer", "description": "Amount in minor units (cents). Never a float." }, "currency": { "type": "string", "description": "ISO 4217 currency code, e.g. \"USD\"." } }, "required": ["amount_cents", "currency"], "additionalProperties": false } }, "required": ["description", "amount"], "additionalProperties": false } }, "subtotal": { "type": "object", "properties": { "amount_cents": { "type": "integer", "description": "Amount in minor units (cents). Never a float." }, "currency": { "type": "string", "description": "ISO 4217 currency code, e.g. \"USD\"." } }, "required": ["amount_cents", "currency"], "additionalProperties": false }, "tax": { "type": "object", "properties": { "amount_cents": { "type": "integer", "description": "Amount in minor units (cents). Never a float." }, "currency": { "type": "string", "description": "ISO 4217 currency code, e.g. \"USD\"." } }, "required": ["amount_cents", "currency"], "additionalProperties": false }, "total": { "type": "object", "properties": { "amount_cents": { "type": "integer", "description": "Amount in minor units (cents). Never a float." }, "currency": { "type": "string", "description": "ISO 4217 currency code, e.g. \"USD\"." } }, "required": ["amount_cents", "currency"], "additionalProperties": false }, "payment_method": { "type": "string", "enum": ["balance", "card"], "nullable": true }, "invoice_number": { "type": "string", "nullable": true }, "invoice_id": { "type": "string", "nullable": true, "description": "Public id (inv_…) of the order invoice: the same id GET /invoices/:id and POST /invoices/:id/pay use." }, "service_id": { "type": "string", "nullable": true, "description": "Public code of the service created by the order." }, "auto_renew": { "type": "string", "enum": ["off", "balance", "balance_and_card", "card"] }, "metadata": { "type": "object", "additionalProperties": { "type": "string" } } }, "required": [ "id", "status", "created_at", "currency", "billing_cycle", "lines", "subtotal", "tax", "total", "payment_method", "invoice_number", "invoice_id", "service_id", "auto_renew", "metadata" ], "additionalProperties": false } }, "next_cursor": { "type": "string", "nullable": true } }, "required": ["data", "next_cursor"], "additionalProperties": false }, "example": { "data": [ { "id": "ord_9173eb967115608b2f", "status": "provisioning", "created_at": "2026-11-05T12:00:00.000Z", "currency": "USD", "billing_cycle": "monthly", "lines": [ { "description": "VPS Small - monthly", "amount": { "amount_cents": 800, "currency": "USD" } }, { "description": "Reseller discount (10%)", "amount": { "amount_cents": -80, "currency": "USD" } } ], "subtotal": { "amount_cents": 720, "currency": "USD" }, "tax": { "amount_cents": 0, "currency": "USD" }, "total": { "amount_cents": 720, "currency": "USD" }, "payment_method": "balance", "invoice_number": "INV-2026-000398", "invoice_id": "inv_cm3f0x8s20009abcd1234", "service_id": "K3F8QX2P", "auto_renew": "off", "metadata": { "customer": "acme-42" } } ], "next_cursor": null } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "400": { "description": "Invalid request (code `invalid_request`, or a missing/malformed `Idempotency-Key`).", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, unknown or revoked API key (code `unauthorized`).", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Forbidden: `ip_not_allowed`, `insufficient_scope`, `wrong_environment`, spending cap or rejected order.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit reached. Read `Retry-After`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal error. Quote `request_id` to support.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Temporarily unavailable. `internal_error`: A platform dependency does not answer; retry after Retry-After seconds.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "operationId": "getOrders", "description": "**Permission:** `read`.", "x-required-scope": "read" } }, "/orders/{id}": { "get": { "summary": "Get one of your orders", "tags": ["Orders"], "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 60 }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "order": { "type": "object", "properties": { "id": { "type": "string", "description": "Public order id (`ord_...`)." }, "status": { "type": "string", "enum": [ "pending", "paid", "provisioning", "completed", "failed", "refunded" ] }, "created_at": { "type": "string" }, "currency": { "type": "string" }, "billing_cycle": { "type": "string", "enum": ["monthly", "quarterly", "semiannual", "annual"], "nullable": true }, "lines": { "type": "array", "items": { "type": "object", "properties": { "description": { "type": "string" }, "amount": { "type": "object", "properties": { "amount_cents": { "type": "integer", "description": "Amount in minor units (cents). Never a float." }, "currency": { "type": "string", "description": "ISO 4217 currency code, e.g. \"USD\"." } }, "required": ["amount_cents", "currency"], "additionalProperties": false } }, "required": ["description", "amount"], "additionalProperties": false } }, "subtotal": { "type": "object", "properties": { "amount_cents": { "type": "integer", "description": "Amount in minor units (cents). Never a float." }, "currency": { "type": "string", "description": "ISO 4217 currency code, e.g. \"USD\"." } }, "required": ["amount_cents", "currency"], "additionalProperties": false }, "tax": { "type": "object", "properties": { "amount_cents": { "type": "integer", "description": "Amount in minor units (cents). Never a float." }, "currency": { "type": "string", "description": "ISO 4217 currency code, e.g. \"USD\"." } }, "required": ["amount_cents", "currency"], "additionalProperties": false }, "total": { "type": "object", "properties": { "amount_cents": { "type": "integer", "description": "Amount in minor units (cents). Never a float." }, "currency": { "type": "string", "description": "ISO 4217 currency code, e.g. \"USD\"." } }, "required": ["amount_cents", "currency"], "additionalProperties": false }, "payment_method": { "type": "string", "enum": ["balance", "card"], "nullable": true }, "invoice_number": { "type": "string", "nullable": true }, "invoice_id": { "type": "string", "nullable": true, "description": "Public id (inv_…) of the order invoice: the same id GET /invoices/:id and POST /invoices/:id/pay use." }, "service_id": { "type": "string", "nullable": true, "description": "Public code of the service created by the order." }, "auto_renew": { "type": "string", "enum": ["off", "balance", "balance_and_card", "card"] }, "metadata": { "type": "object", "additionalProperties": { "type": "string" } } }, "required": [ "id", "status", "created_at", "currency", "billing_cycle", "lines", "subtotal", "tax", "total", "payment_method", "invoice_number", "invoice_id", "service_id", "auto_renew", "metadata" ], "additionalProperties": false }, "service": { "type": "object", "properties": { "id": { "type": "string" }, "hostname": { "type": "string" }, "status": { "type": "string", "enum": [ "provisioning", "active", "suspended", "paused", "cancelled", "error" ] }, "power_state": { "type": "string", "nullable": true }, "plan": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "cores": { "type": "integer" }, "ram_mb": { "type": "integer" }, "disk_gb": { "type": "integer" } }, "required": ["id", "name", "cores", "ram_mb", "disk_gb"], "additionalProperties": false }, "location": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "country": { "type": "string" } }, "required": ["id", "name", "country"], "additionalProperties": false }, "os": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" } }, "required": ["id", "name"], "additionalProperties": false, "nullable": true }, "ips": { "type": "array", "items": {}, "description": "Empty until the service is provisioned; read GET /services/{id}." }, "created_at": { "type": "string" }, "origin": { "type": "string", "enum": ["api"] }, "metadata": { "type": "object", "additionalProperties": { "type": "string" } }, "billing": { "type": "object", "additionalProperties": {}, "description": "Same object as `billing` in GET /services/{id}." } }, "required": [ "id", "hostname", "status", "power_state", "plan", "location", "os", "ips", "created_at", "origin", "metadata", "billing" ], "additionalProperties": false, "nullable": true } }, "required": ["order", "service"], "additionalProperties": false }, "example": { "order": { "id": "ord_9173eb967115608b2f", "status": "completed", "created_at": "2026-11-05T12:00:00.000Z", "currency": "USD", "billing_cycle": "monthly", "lines": [ { "description": "VPS Small - monthly", "amount": { "amount_cents": 800, "currency": "USD" } }, { "description": "Reseller discount (10%)", "amount": { "amount_cents": -80, "currency": "USD" } } ], "subtotal": { "amount_cents": 720, "currency": "USD" }, "tax": { "amount_cents": 0, "currency": "USD" }, "total": { "amount_cents": 720, "currency": "USD" }, "payment_method": "balance", "invoice_number": "INV-2026-000398", "invoice_id": "inv_cm3f0x8s20009abcd1234", "service_id": "K3F8QX2P", "auto_renew": "off", "metadata": { "customer": "acme-42" } }, "service": { "id": "K3F8QX2P", "hostname": "web-1", "status": "active", "plan": { "id": "cm3x7k2p00001vps2gb", "name": "VPS Small", "cores": 2, "ram_mb": 2048, "disk_gb": 40 }, "location": { "id": "us-mia-1", "name": "Miami", "country": "US" }, "os": { "id": "cm3x7k2p00002ubuntu2404", "name": "Ubuntu 24.04 LTS" }, "ips": [ { "address": "203.0.113.10", "version": 4, "primary": true, "rdns": null }, { "address": "2001:db8:396::b8a9", "version": 6, "primary": false, "rdns": null } ], "created_at": "2026-11-05T12:00:00.000Z", "origin": "api", "metadata": { "customer": "acme-42" }, "power_state": "running", "billing": { "cycle": "monthly", "price": { "amount_cents": 720, "currency": "USD" }, "current_period_end": "2026-12-05T12:00:00.000Z", "next_invoice_at": "2026-12-02T12:00:00.000Z", "open_invoice_id": null, "due_at": null, "grace_ends_at": null, "suspends_at": null, "terminates_at": null, "auto_renew": "off", "cancel_at_period_end": false, "renewable": true } } } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "401": { "description": "Missing, unknown or revoked API key (code `unauthorized`).", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Forbidden: `ip_not_allowed`, `insufficient_scope`, `wrong_environment`, spending cap or rejected order.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found (also for resources that belong to someone else).", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit reached. Read `Retry-After`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal error. Quote `request_id` to support.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Temporarily unavailable. `internal_error`: A platform dependency does not answer; retry after Retry-After seconds.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "operationId": "getOrdersById", "description": "**Permission:** `read`.", "x-required-scope": "read" } }, "/payment-method": { "get": { "summary": "Default card (read-only)", "tags": ["Account"], "description": "The default saved card and whether the owner accepted the off-session charge mandate for it. The card and the mandate are set up on the website (dashboard, API, Payment method), never through the API. `payment_method` is `null` when there is none. Requires the \"billing\" scope.\n\n**Permission:** `billing`.", "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "payment_method": { "type": "object", "properties": { "brand": { "type": "string", "nullable": true }, "last4": { "type": "string", "nullable": true }, "exp_month": { "type": "integer", "nullable": true }, "exp_year": { "type": "integer", "nullable": true }, "mandate_accepted": { "type": "boolean", "description": "The owner accepted, for this card, an automatic-charge mandate whose version covers API purchases." }, "chargeable_off_session": { "type": "boolean", "description": "Orders and renewals paid with \"card\" or \"auto\" can use it now." } }, "required": [ "brand", "last4", "exp_month", "exp_year", "mandate_accepted", "chargeable_off_session" ], "additionalProperties": false, "nullable": true } }, "required": ["payment_method"], "additionalProperties": false }, "example": { "payment_method": { "brand": "visa", "last4": "4242", "exp_month": 12, "exp_year": 2029, "mandate_accepted": true, "chargeable_off_session": true } } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "400": { "description": "Error response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable, documented error code." }, "message": { "type": "string", "description": "Human-readable text; may change." }, "request_id": { "type": "string", "description": "Same value as the X-Request-Id response header." }, "details": { "type": "object", "additionalProperties": {} } }, "required": ["code", "message", "request_id"], "additionalProperties": false } }, "required": ["error"], "additionalProperties": false, "description": "Error response." } } } }, "401": { "description": "Missing, unknown or revoked API key (code `unauthorized`).", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Forbidden: `ip_not_allowed`, `insufficient_scope`, `wrong_environment`, spending cap or rejected order.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable, documented error code." }, "message": { "type": "string", "description": "Human-readable text; may change." }, "request_id": { "type": "string", "description": "Same value as the X-Request-Id response header." }, "details": { "type": "object", "additionalProperties": {} } }, "required": ["code", "message", "request_id"], "additionalProperties": false } }, "required": ["error"], "additionalProperties": false, "description": "Error response." } } } }, "429": { "description": "Rate limit reached. Read `Retry-After`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal error. Quote `request_id` to support.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Temporarily unavailable. `internal_error`: A platform dependency does not answer; retry after Retry-After seconds.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "operationId": "getPaymentMethod", "x-required-scope": "billing", "parameters": [] } }, "/quotes": { "post": { "summary": "Quote an order: full price breakdown, no side effects", "tags": ["Catalog"], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "plan_id": { "type": "string", "minLength": 1, "maxLength": 40 }, "location_id": { "type": "string", "minLength": 1, "maxLength": 60 }, "billing_cycle": { "type": "string", "enum": ["monthly", "quarterly", "semiannual", "annual"] }, "os_template_id": { "type": "string", "minLength": 1, "maxLength": 40 }, "hostname": { "type": "string", "minLength": 3, "maxLength": 63, "pattern": "^[a-z0-9-]+$" }, "ssh_public_key": { "type": "string", "minLength": 1, "maxLength": 4096 }, "ssh_key_ids": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 40 }, "minItems": 1, "maxItems": 5 }, "options": { "type": "array", "items": { "type": "object", "properties": { "slug": { "type": "string", "minLength": 1, "maxLength": 60 }, "answer": { "type": "string", "enum": ["yes", "no"] } }, "required": ["slug", "answer"], "additionalProperties": false }, "maxItems": 20 }, "payment": { "type": "string", "enum": ["auto", "balance", "card"], "default": "auto" }, "auto_renew": { "type": "string", "enum": ["off", "balance", "balance_and_card", "card"], "default": "off" }, "metadata": { "type": "object", "additionalProperties": { "type": "string", "maxLength": 200 } } }, "required": [ "plan_id", "location_id", "billing_cycle", "os_template_id", "hostname" ], "additionalProperties": false }, "example": { "plan_id": "cm3x7k2p00001vps2gb", "location_id": "us-mia-1", "billing_cycle": "monthly", "os_template_id": "cm3x7k2p00002ubuntu2404", "hostname": "web-1", "ssh_public_key": "ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIOMqqnkVzrm0SdG6UOoqKLsabgH5C9okWi0dh2l9GKJl me@laptop", "options": [ { "slug": "anti-ddos", "answer": "yes" } ], "payment": "auto", "auto_renew": "off", "metadata": { "customer": "acme-42" } } } } }, "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "quote": { "type": "object", "properties": { "plan": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "type": { "type": "string" } }, "required": ["id", "name", "type"], "additionalProperties": false }, "location": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "country": { "type": "string" } }, "required": ["id", "name", "country"], "additionalProperties": false }, "hostname": { "type": "string" }, "billing_cycle": { "type": "string", "enum": ["monthly", "quarterly", "semiannual", "annual"] }, "currency": { "type": "string" }, "lines": { "type": "array", "items": { "type": "object", "properties": { "kind": { "type": "string", "enum": ["plan", "option", "option_one_time", "reseller_discount"] }, "slug": { "type": "string" }, "description": { "type": "string" }, "amount": { "type": "object", "properties": { "amount_cents": { "type": "integer", "description": "Amount in minor units (cents). Never a float." }, "currency": { "type": "string", "description": "ISO 4217 currency code, e.g. \"USD\"." } }, "required": ["amount_cents", "currency"], "additionalProperties": false, "description": "Negative for the `reseller_discount` line." } }, "required": ["kind", "description", "amount"], "additionalProperties": false } }, "list_total": { "type": "object", "properties": { "amount_cents": { "type": "integer", "description": "Amount in minor units (cents). Never a float." }, "currency": { "type": "string", "description": "ISO 4217 currency code, e.g. \"USD\"." } }, "required": ["amount_cents", "currency"], "additionalProperties": false }, "reseller_discount": { "type": "object", "properties": { "percent": { "type": "number" }, "amount": { "type": "object", "properties": { "amount_cents": { "type": "integer", "description": "Amount in minor units (cents). Never a float." }, "currency": { "type": "string", "description": "ISO 4217 currency code, e.g. \"USD\"." } }, "required": ["amount_cents", "currency"], "additionalProperties": false } }, "required": ["percent", "amount"], "additionalProperties": false }, "subtotal": { "type": "object", "properties": { "amount_cents": { "type": "integer", "description": "Amount in minor units (cents). Never a float." }, "currency": { "type": "string", "description": "ISO 4217 currency code, e.g. \"USD\"." } }, "required": ["amount_cents", "currency"], "additionalProperties": false }, "tax": { "type": "object", "properties": { "amount_cents": { "type": "integer", "description": "Amount in minor units (cents). Never a float." }, "currency": { "type": "string", "description": "ISO 4217 currency code, e.g. \"USD\"." } }, "required": ["amount_cents", "currency"], "additionalProperties": false }, "total": { "type": "object", "properties": { "amount_cents": { "type": "integer", "description": "Amount in minor units (cents). Never a float." }, "currency": { "type": "string", "description": "ISO 4217 currency code, e.g. \"USD\"." } }, "required": ["amount_cents", "currency"], "additionalProperties": false, "description": "What it costs paying with the balance." }, "card_fee": { "type": "object", "properties": { "percent": { "type": "number" }, "amount": { "type": "object", "properties": { "amount_cents": { "type": "integer", "description": "Amount in minor units (cents). Never a float." }, "currency": { "type": "string", "description": "ISO 4217 currency code, e.g. \"USD\"." } }, "required": ["amount_cents", "currency"], "additionalProperties": false } }, "required": ["percent", "amount"], "additionalProperties": false }, "total_with_card": { "type": "object", "properties": { "amount_cents": { "type": "integer", "description": "Amount in minor units (cents). Never a float." }, "currency": { "type": "string", "description": "ISO 4217 currency code, e.g. \"USD\"." } }, "required": ["amount_cents", "currency"], "additionalProperties": false, "description": "`total` plus the card fee: what a card payment charges." }, "payable_with": { "type": "array", "items": { "type": "string", "enum": ["balance", "card"] } }, "would_exceed_cap": { "type": "boolean" }, "cap": { "type": "string", "enum": ["not_set", "per_order", "daily", "hourly"], "nullable": true }, "cap_remaining_cents": { "type": "integer", "nullable": true } }, "required": [ "plan", "location", "hostname", "billing_cycle", "currency", "lines", "list_total", "reseller_discount", "subtotal", "tax", "total", "card_fee", "total_with_card", "payable_with", "would_exceed_cap", "cap", "cap_remaining_cents" ], "additionalProperties": false } }, "required": ["quote"], "additionalProperties": false }, "example": { "quote": { "plan": { "id": "cm3x7k2p00001vps2gb", "name": "VPS Small", "type": "vps" }, "location": { "id": "us-mia-1", "name": "Miami", "country": "US" }, "hostname": "web-1", "billing_cycle": "monthly", "currency": "USD", "lines": [ { "kind": "plan", "description": "VPS Small - monthly", "amount": { "amount_cents": 800, "currency": "USD" } }, { "kind": "option", "slug": "anti-ddos", "description": "Anti-DDoS", "amount": { "amount_cents": 300, "currency": "USD" } }, { "kind": "reseller_discount", "description": "Reseller discount (10%)", "amount": { "amount_cents": -110, "currency": "USD" } } ], "list_total": { "amount_cents": 1100, "currency": "USD" }, "reseller_discount": { "percent": 10, "amount": { "amount_cents": 110, "currency": "USD" } }, "subtotal": { "amount_cents": 990, "currency": "USD" }, "tax": { "amount_cents": 0, "currency": "USD" }, "total": { "amount_cents": 990, "currency": "USD" }, "card_fee": { "percent": 3, "amount": { "amount_cents": 30, "currency": "USD" } }, "total_with_card": { "amount_cents": 1020, "currency": "USD" }, "payable_with": ["balance", "card"], "would_exceed_cap": false, "cap": null, "cap_remaining_cents": null } } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "400": { "description": "Invalid request (code `invalid_request`, or a missing/malformed `Idempotency-Key`).", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, unknown or revoked API key (code `unauthorized`).", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Forbidden: `ip_not_allowed`, `insufficient_scope`, `wrong_environment`, spending cap or rejected order. `product_not_resellable`: The plan is not a VPS/VDS plan.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Unprocessable request. `invalid_option`: Unknown option, repeated option or no price for that cycle.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit reached. Read `Retry-After`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal error. Quote `request_id` to support.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Temporarily unavailable. `internal_error`: A platform dependency does not answer; retry after Retry-After seconds.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "operationId": "postQuotes", "description": "**Permission:** `read`. **Rate-limit bucket:** `quotes` (besides the general one).", "x-required-scope": "read", "x-rate-limit-bucket": "quotes", "parameters": [] } }, "/services": { "get": { "summary": "List services", "tags": ["Services"], "description": "Lists the VPS/VDS services of the key owner, newest first. Keyset pagination with `limit` (1-100, default 25) and `cursor`; filter by `status`.\n\n**Permission:** `read`.", "parameters": [ { "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25 }, "in": "query", "name": "limit", "required": false }, { "schema": { "type": "string", "maxLength": 200 }, "in": "query", "name": "cursor", "required": false }, { "schema": { "type": "string", "enum": ["provisioning", "active", "suspended", "paused", "cancelled", "error"] }, "in": "query", "name": "status", "required": false } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "hostname": { "type": "string" }, "status": { "type": "string", "enum": [ "provisioning", "active", "suspended", "paused", "cancelled", "error" ] }, "plan": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "cores": { "type": "integer" }, "ram_mb": { "type": "integer" }, "disk_gb": { "type": "integer" } }, "required": ["id", "name", "cores", "ram_mb", "disk_gb"], "additionalProperties": false }, "location": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "country": { "type": "string" } }, "required": ["id", "name", "country"], "additionalProperties": false }, "os": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" } }, "required": ["id", "name"], "additionalProperties": false, "nullable": true }, "ips": { "type": "array", "items": { "type": "object", "properties": { "address": { "type": "string" }, "version": { "anyOf": [ { "type": "number", "enum": [4] }, { "type": "number", "enum": [6] } ] }, "primary": { "type": "boolean" }, "rdns": { "type": "string", "nullable": true } }, "required": ["address", "version", "primary", "rdns"], "additionalProperties": false } }, "created_at": { "type": "string" }, "origin": { "type": "string", "enum": ["api", "web"] }, "metadata": { "type": "object", "additionalProperties": { "type": "string" } } }, "required": [ "id", "hostname", "status", "plan", "location", "os", "ips", "created_at", "origin", "metadata" ], "additionalProperties": false } }, "next_cursor": { "type": "string", "nullable": true } }, "required": ["data", "next_cursor"], "additionalProperties": false }, "example": { "data": [ { "id": "K3F8QX2P", "hostname": "web-1", "status": "active", "plan": { "id": "cm3x7k2p00001vps2gb", "name": "VPS Small", "cores": 2, "ram_mb": 2048, "disk_gb": 40 }, "location": { "id": "us-mia-1", "name": "Miami", "country": "US" }, "os": { "id": "cm3x7k2p00002ubuntu2404", "name": "Ubuntu 24.04 LTS" }, "ips": [ { "address": "203.0.113.10", "version": 4, "primary": true, "rdns": null }, { "address": "2001:db8:396::b8a9", "version": 6, "primary": false, "rdns": null } ], "created_at": "2026-11-05T12:00:00.000Z", "origin": "api", "metadata": { "customer": "acme-42" } } ], "next_cursor": null } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "400": { "description": "Invalid request (code `invalid_request`, or a missing/malformed `Idempotency-Key`).", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, unknown or revoked API key (code `unauthorized`).", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Forbidden: `ip_not_allowed`, `insufficient_scope`, `wrong_environment`, spending cap or rejected order.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit reached. Read `Retry-After`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal error. Quote `request_id` to support.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Temporarily unavailable. `internal_error`: A platform dependency does not answer; retry after Retry-After seconds.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "operationId": "getServices", "x-required-scope": "read" } }, "/services/{id}": { "get": { "summary": "Get a service", "tags": ["Services"], "description": "Returns one service with its live power state and the billing object (with your price).\n\n**Permission:** `read`. **Rate-limit bucket:** `service-reads` (besides the general one).", "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "hostname": { "type": "string" }, "status": { "type": "string", "enum": [ "provisioning", "active", "suspended", "paused", "cancelled", "error" ] }, "plan": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "cores": { "type": "integer" }, "ram_mb": { "type": "integer" }, "disk_gb": { "type": "integer" } }, "required": ["id", "name", "cores", "ram_mb", "disk_gb"], "additionalProperties": false }, "location": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "country": { "type": "string" } }, "required": ["id", "name", "country"], "additionalProperties": false }, "os": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" } }, "required": ["id", "name"], "additionalProperties": false, "nullable": true }, "ips": { "type": "array", "items": { "type": "object", "properties": { "address": { "type": "string" }, "version": { "anyOf": [ { "type": "number", "enum": [4] }, { "type": "number", "enum": [6] } ] }, "primary": { "type": "boolean" }, "rdns": { "type": "string", "nullable": true } }, "required": ["address", "version", "primary", "rdns"], "additionalProperties": false } }, "created_at": { "type": "string" }, "origin": { "type": "string", "enum": ["api", "web"] }, "metadata": { "type": "object", "additionalProperties": { "type": "string" } }, "power_state": { "type": "string", "enum": ["running", "stopped", "paused", "unknown"], "nullable": true }, "billing": { "type": "object", "properties": { "cycle": { "type": "string", "enum": ["monthly", "quarterly", "semiannual", "annual"] }, "price": { "type": "object", "properties": { "amount_cents": { "type": "integer" }, "currency": { "type": "string" } }, "required": ["amount_cents", "currency"], "additionalProperties": false }, "current_period_end": { "type": "string", "nullable": true }, "next_invoice_at": { "type": "string", "nullable": true }, "open_invoice_id": { "type": "string", "nullable": true }, "due_at": { "type": "string", "nullable": true }, "grace_ends_at": { "type": "string", "nullable": true }, "suspends_at": { "type": "string", "nullable": true }, "terminates_at": { "type": "string", "nullable": true }, "auto_renew": { "type": "string", "enum": ["off", "balance", "balance_and_card", "card"] }, "cancel_at_period_end": { "type": "boolean" }, "renewable": { "type": "boolean" } }, "required": [ "cycle", "price", "current_period_end", "next_invoice_at", "open_invoice_id", "due_at", "grace_ends_at", "suspends_at", "terminates_at", "auto_renew", "cancel_at_period_end", "renewable" ], "additionalProperties": false } }, "required": [ "id", "hostname", "status", "plan", "location", "os", "ips", "created_at", "origin", "metadata", "power_state", "billing" ], "additionalProperties": false }, "example": { "id": "K3F8QX2P", "hostname": "web-1", "status": "active", "plan": { "id": "cm3x7k2p00001vps2gb", "name": "VPS Small", "cores": 2, "ram_mb": 2048, "disk_gb": 40 }, "location": { "id": "us-mia-1", "name": "Miami", "country": "US" }, "os": { "id": "cm3x7k2p00002ubuntu2404", "name": "Ubuntu 24.04 LTS" }, "ips": [ { "address": "203.0.113.10", "version": 4, "primary": true, "rdns": null }, { "address": "2001:db8:396::b8a9", "version": 6, "primary": false, "rdns": null } ], "created_at": "2026-11-05T12:00:00.000Z", "origin": "api", "metadata": { "customer": "acme-42" }, "power_state": "running", "billing": { "cycle": "monthly", "price": { "amount_cents": 720, "currency": "USD" }, "current_period_end": "2026-12-05T12:00:00.000Z", "next_invoice_at": "2026-12-02T12:00:00.000Z", "open_invoice_id": null, "due_at": null, "grace_ends_at": null, "suspends_at": null, "terminates_at": null, "auto_renew": "off", "cancel_at_period_end": false, "renewable": true } } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "401": { "description": "Missing, unknown or revoked API key (code `unauthorized`).", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Forbidden: `ip_not_allowed`, `insufficient_scope`, `wrong_environment`, spending cap or rejected order.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found (also for resources that belong to someone else).", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit reached. Read `Retry-After`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal error. Quote `request_id` to support.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Temporarily unavailable. `internal_error`: A platform dependency does not answer; retry after Retry-After seconds.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "operationId": "getServicesById", "x-required-scope": "read", "x-rate-limit-bucket": "service-reads" } }, "/services/{id}/auto-renew": { "put": { "summary": "Set the auto-renew mode of a service", "tags": ["Billing"], "description": "off: nothing is charged automatically (invoices, reminders, suspension and termination still follow the usual schedule). balance: paid from the account balance when it covers the invoice. balance_and_card: balance first, then the default card. card: the default card. Card modes need a default card with the auto-charge mandate accepted on the website.\n\n**Permission:** `billing`. **Rate-limit bucket:** `service-settings` (besides the general one).", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "mode": { "type": "string", "enum": ["off", "balance", "balance_and_card", "card"] } }, "required": ["mode"], "additionalProperties": false }, "example": { "mode": "balance" } } } }, "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "service": { "type": "object", "properties": { "id": { "type": "string" }, "hostname": { "type": "string" }, "status": { "type": "string", "enum": [ "provisioning", "active", "suspended", "paused", "cancelled", "error" ] }, "billing": { "type": "object", "properties": { "cycle": { "type": "string", "enum": ["monthly", "quarterly", "semiannual", "annual"] }, "price": { "type": "object", "properties": { "amount_cents": { "type": "integer" }, "currency": { "type": "string" } }, "required": ["amount_cents", "currency"], "additionalProperties": false }, "current_period_end": { "type": "string", "nullable": true }, "next_invoice_at": { "type": "string", "nullable": true }, "open_invoice_id": { "type": "string", "nullable": true }, "due_at": { "type": "string", "nullable": true }, "grace_ends_at": { "type": "string", "nullable": true }, "suspends_at": { "type": "string", "nullable": true }, "terminates_at": { "type": "string", "nullable": true }, "auto_renew": { "type": "string", "enum": ["off", "balance", "balance_and_card", "card"] }, "cancel_at_period_end": { "type": "boolean" }, "renewable": { "type": "boolean" } }, "required": [ "cycle", "price", "current_period_end", "next_invoice_at", "open_invoice_id", "due_at", "grace_ends_at", "suspends_at", "terminates_at", "auto_renew", "cancel_at_period_end", "renewable" ], "additionalProperties": false } }, "required": ["id", "hostname", "status", "billing"], "additionalProperties": false } }, "required": ["service"], "additionalProperties": false }, "example": { "service": { "id": "K3F8QX2P", "hostname": "web-1", "status": "active", "billing": { "cycle": "monthly", "price": { "amount_cents": 720, "currency": "USD" }, "current_period_end": "2026-12-05T12:00:00.000Z", "next_invoice_at": "2026-12-02T12:00:00.000Z", "open_invoice_id": null, "due_at": null, "grace_ends_at": null, "suspends_at": null, "terminates_at": null, "auto_renew": "balance", "cancel_at_period_end": false, "renewable": true } } } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "400": { "description": "Invalid request (code `invalid_request`, or a missing/malformed `Idempotency-Key`).", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, unknown or revoked API key (code `unauthorized`).", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Forbidden: `ip_not_allowed`, `insufficient_scope`, `wrong_environment`, spending cap or rejected order.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found (also for resources that belong to someone else).", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict with the current state. `conflict`: details.reason says why (for example no_default_card or mandate_not_accepted for the card modes).", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit reached. Read `Retry-After`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal error. Quote `request_id` to support.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Temporarily unavailable. `internal_error`: A platform dependency does not answer; retry after Retry-After seconds.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "operationId": "putServicesByIdAutoRenew", "x-required-scope": "billing", "x-rate-limit-bucket": "service-settings" } }, "/services/{id}/cancel": { "post": { "summary": "Cancel a service", "tags": ["Services"], "description": "`at: \"period_end\"` schedules the cancellation for the end of the paid period (reversible with `cancel/withdraw`). `at: \"now\"` powers the VPS off, releases its IPs and cannot be undone. `confirm: true` is required. Requires `Idempotency-Key`.\n\n**Permission:** `manage`. **Rate-limit bucket:** `cancel` (besides the general one). **Requires** the `Idempotency-Key` header.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "at": { "type": "string", "enum": ["period_end", "now"] }, "confirm": { "type": "boolean", "enum": [true] } }, "required": ["at", "confirm"], "additionalProperties": false }, "example": { "at": "period_end", "confirm": true } } } }, "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "in": "path", "name": "id", "required": true }, { "name": "Idempotency-Key", "in": "header", "required": true, "description": "8-64 characters: letters, digits, `_` or `-`. Same key + same body within 24 h replays the stored response (`Idempotent-Replay: true`).", "schema": { "type": "string", "minLength": 8, "maxLength": 64, "pattern": "^[A-Za-z0-9_-]{8,64}$", "example": "order-acme-42-001" } } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": ["scheduled", "requested", "cancelled"] }, "cancel_at": { "type": "string", "nullable": true }, "cancel_at_period_end": { "type": "boolean" } }, "required": ["status", "cancel_at", "cancel_at_period_end"], "additionalProperties": false }, "example": { "status": "scheduled", "cancel_at": "2026-12-05T12:00:00.000Z", "cancel_at_period_end": true } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "400": { "description": "Invalid request (code `invalid_request`, or a missing/malformed `Idempotency-Key`).", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, unknown or revoked API key (code `unauthorized`).", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Forbidden: `ip_not_allowed`, `insufficient_scope`, `wrong_environment`, spending cap or rejected order.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found (also for resources that belong to someone else).", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict with the current state. `conflict`: Already cancelled, a sub-server, or a permanent/courtesy service (at \"now\"). `service_not_ready`: at \"now\" while the service is provisioning or being reinstalled. `service_suspended`: at \"now\" on a suspended, paused or errored service (use at \"period_end\" or contact support). `request_in_progress`: The same Idempotency-Key is still running.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Unprocessable request. `idempotency_key_reused`: The Idempotency-Key was used with a different request.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit reached. Read `Retry-After`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal error. Quote `request_id` to support.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Temporarily unavailable. `internal_error`: A platform dependency does not answer; retry after Retry-After seconds.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "operationId": "postServicesByIdCancel", "x-required-scope": "manage", "x-rate-limit-bucket": "cancel", "x-idempotent": true } }, "/services/{id}/cancel/withdraw": { "post": { "summary": "Withdraw a scheduled cancellation", "tags": ["Services"], "description": "Undoes a cancellation scheduled with `at: \"period_end\"`. An immediate cancellation that already ran cannot be withdrawn.\n\n**Permission:** `manage`. **Rate-limit bucket:** `cancel` (besides the general one).", "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "cancel_at_period_end": { "type": "boolean", "enum": [false] } }, "required": ["cancel_at_period_end"], "additionalProperties": false }, "example": { "cancel_at_period_end": false } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "401": { "description": "Missing, unknown or revoked API key (code `unauthorized`).", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Forbidden: `ip_not_allowed`, `insufficient_scope`, `wrong_environment`, spending cap or rejected order.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found (also for resources that belong to someone else).", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict with the current state. `conflict`: Nothing to withdraw, or an immediate cancellation that already ran.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit reached. Read `Retry-After`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal error. Quote `request_id` to support.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Temporarily unavailable. `internal_error`: A platform dependency does not answer; retry after Retry-After seconds.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "operationId": "postServicesByIdCancelWithdraw", "x-required-scope": "manage", "x-rate-limit-bucket": "cancel" } }, "/services/{id}/credentials": { "get": { "summary": "Read the one-time credentials", "tags": ["Services"], "description": "Returns the initial root/Administrator password (or the one produced by `reset-password` / `reinstall`) of a service this key bought or reset. Available for 24 h and consumed on the first successful read: afterwards `410 credentials_consumed`. Always audited, never cached.\n\nThe one-time password needs the `manage` permission (a `read`-only key gets `403 insufficient_scope`). There is no HEAD version of this route.\n\n**Permission:** `manage`. **Rate-limit bucket:** `credentials` (besides the general one).", "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "username": { "type": "string" }, "password": { "type": "string" }, "expires_at": { "type": "string" } }, "required": ["username", "password", "expires_at"], "additionalProperties": false }, "example": { "username": "root", "password": "wm^j&Xt&=L!bkZEK&M2A", "expires_at": "2026-11-06T12:00:11.000Z" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "401": { "description": "Missing, unknown or revoked API key (code `unauthorized`).", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Forbidden: `ip_not_allowed`, `insufficient_scope`, `wrong_environment`, spending cap or rejected order.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found (also for resources that belong to someone else). `credentials_not_available`: This key did not buy or reset the service, or the 24 h window passed.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict with the current state. `service_not_ready`: The service is still provisioning or a reinstall has not finished.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "410": { "description": "The one-time credentials were already read. `credentials_consumed`: The password was already read once. Use reset-password.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit reached. Read `Retry-After`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal error. Quote `request_id` to support.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Temporarily unavailable. `internal_error`: A platform dependency does not answer; retry after Retry-After seconds.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "operationId": "getServicesByIdCredentials", "x-required-scope": "manage", "x-rate-limit-bucket": "credentials" } }, "/services/{id}/firewall": { "get": { "summary": "Get the firewall of a service", "tags": ["Firewall"], "description": "The firewall engine depends on the node of the service. `engine: \"shield\"` (own firewall) exposes per-IP features (`geoblock`, `srcwl`, `asn-block`, port gates…): `state` has `ip`, `geoblock`, `geo_policy`, `srcwl`, `asn_block` and `blacklist`; manage them with `POST/DELETE /firewall/{feature}`. `engine: \"gsk\"` exposes mitigation profiles and rules, attacks, metrics and cache ports: `state` has `ip`, `rules` and `profiles`; use `/firewall/rules`, `/profiles`, `/attacks`, `/metrics` and `/cache-ports`. `engine: \"none\"` means the node has no firewall: `capabilities` is empty and `state` is null. `capabilities` lists what the engine supports. The IP is always the primary IP of the service. `409 firewall_unavailable` when the service has no real firewall behind it; `503 firewall_unavailable` when the provider is down.\n\n**Permission:** `read`. **Rate-limit bucket:** `service-reads` (besides the general one).", "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "engine": { "type": "string", "enum": ["shield", "gsk", "none"] }, "capabilities": { "type": "array", "items": { "type": "string" } }, "state": { "type": "object", "additionalProperties": {}, "nullable": true } }, "required": ["engine", "capabilities", "state"], "additionalProperties": false }, "example": { "engine": "shield", "capabilities": [ "geoblock", "srcwl", "asn-block", "tcp-allow-perdst", "udp-allow-perdst", "ports-fivem", "ports-rdp", "ports-ssh", "syn-gate", "fivem-cache", "rdp-filter", "ssh-filter", "udp-strict", "geo-rate", "geoblock-policy", "filter-mode", "blacklist" ], "state": { "ip": "203.0.113.10", "geoblock": ["CN"], "geo_policy": "blacklist", "srcwl": [], "asn_block": [], "blacklist": [] } } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "401": { "description": "Missing, unknown or revoked API key (code `unauthorized`).", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Forbidden: `ip_not_allowed`, `insufficient_scope`, `wrong_environment`, spending cap or rejected order.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found (also for resources that belong to someone else).", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict with the current state. `firewall_unavailable`: The service has no firewall (engine \"none\"), no IP, or a fake delivery.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Unprocessable request. `feature_not_supported`: The route belongs to another firewall engine (details.engine).", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit reached. Read `Retry-After`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal error. Quote `request_id` to support.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Temporarily unavailable. `firewall_unavailable`: The firewall provider failed (a failed read is never an empty list), is not configured or is down. `internal_error`: A platform dependency does not answer; retry after Retry-After seconds.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "operationId": "getServicesByIdFirewall", "x-required-scope": "read", "x-rate-limit-bucket": "service-reads" } }, "/services/{id}/firewall/attacks": { "get": { "summary": "List the recent attacks (gsk engine)", "tags": ["Firewall"], "description": "Attacks mitigated on the primary IP, paginated with `page`. Only for the `gsk` engine.\n\n**Permission:** `read`. **Rate-limit bucket:** `service-reads` (besides the general one).", "parameters": [ { "schema": { "type": "integer", "minimum": 1, "maximum": 1000 }, "in": "query", "name": "page", "required": false }, { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "attacks": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "address": { "type": "string" }, "date": { "type": "string" }, "peak_pps": { "type": "number" }, "peak_bps": { "type": "number" }, "duration_seconds": { "type": "number" } }, "required": [ "id", "address", "date", "peak_pps", "peak_bps", "duration_seconds" ], "additionalProperties": false } } }, "required": ["attacks"], "additionalProperties": false } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "400": { "description": "Invalid request (code `invalid_request`, or a missing/malformed `Idempotency-Key`).", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, unknown or revoked API key (code `unauthorized`).", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Forbidden: `ip_not_allowed`, `insufficient_scope`, `wrong_environment`, spending cap or rejected order.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found (also for resources that belong to someone else).", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict with the current state. `firewall_unavailable`: The service has no firewall (engine \"none\"), no IP, or a fake delivery.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Unprocessable request. `feature_not_supported`: The route belongs to another firewall engine (details.engine).", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit reached. Read `Retry-After`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal error. Quote `request_id` to support.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Temporarily unavailable. `firewall_unavailable`: The firewall provider failed (a failed read is never an empty list), is not configured or is down. `internal_error`: A platform dependency does not answer; retry after Retry-After seconds.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "operationId": "getServicesByIdFirewallAttacks", "x-required-scope": "read", "x-rate-limit-bucket": "service-reads" } }, "/services/{id}/firewall/cache-ports": { "get": { "summary": "List the cache ports (gsk engine)", "tags": ["Firewall"], "description": "Cache ports per protocol type (steam-a2s, raknet, sampp, fivem, minecraft-java, source, teamspeak); types without ports are omitted. Only for the `gsk` engine.\n\n**Permission:** `read`. **Rate-limit bucket:** `service-reads` (besides the general one).", "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "cache": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string" }, "ports": { "type": "array", "items": { "type": "number" } } }, "required": ["type", "ports"], "additionalProperties": false } } }, "required": ["cache"], "additionalProperties": false } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "401": { "description": "Missing, unknown or revoked API key (code `unauthorized`).", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Forbidden: `ip_not_allowed`, `insufficient_scope`, `wrong_environment`, spending cap or rejected order.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found (also for resources that belong to someone else).", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict with the current state. `firewall_unavailable`: The service has no firewall (engine \"none\"), no IP, or a fake delivery.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Unprocessable request. `feature_not_supported`: The route belongs to another firewall engine (details.engine).", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit reached. Read `Retry-After`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal error. Quote `request_id` to support.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Temporarily unavailable. `firewall_unavailable`: The firewall provider failed (a failed read is never an empty list), is not configured or is down. `internal_error`: A platform dependency does not answer; retry after Retry-After seconds.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "operationId": "getServicesByIdFirewallCachePorts", "x-required-scope": "read", "x-rate-limit-bucket": "service-reads" }, "delete": { "summary": "Clear the whole cache (gsk engine)", "tags": ["Firewall"], "description": "Removes every cache port of every type of the primary IP. Only for the `gsk` engine.\n\n**Permission:** `manage`. **Rate-limit bucket:** `service-settings` (besides the general one).", "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "enum": [true] } }, "required": ["ok"], "additionalProperties": false } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "401": { "description": "Missing, unknown or revoked API key (code `unauthorized`).", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Forbidden: `ip_not_allowed`, `insufficient_scope`, `wrong_environment`, spending cap or rejected order.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found (also for resources that belong to someone else).", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict with the current state. `firewall_unavailable`: The service has no firewall (engine \"none\"), no IP, or a fake delivery.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Unprocessable request. `feature_not_supported`: The route belongs to another firewall engine (details.engine).", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit reached. Read `Retry-After`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal error. Quote `request_id` to support.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Temporarily unavailable. `firewall_unavailable`: The firewall provider failed (a failed read is never an empty list), is not configured or is down. `internal_error`: A platform dependency does not answer; retry after Retry-After seconds.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "operationId": "deleteServicesByIdFirewallCachePorts", "x-required-scope": "manage", "x-rate-limit-bucket": "service-settings" } }, "/services/{id}/firewall/cache-ports/{type}": { "post": { "summary": "Add cache ports (gsk engine)", "tags": ["Firewall"], "description": "Adds 1-50 ports to the cache of one protocol type. Only for the `gsk` engine.\n\n**Permission:** `manage`. **Rate-limit bucket:** `service-settings` (besides the general one).", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "ports": { "type": "array", "items": { "type": "integer", "minimum": 1, "maximum": 65535 }, "minItems": 1, "maxItems": 50 } }, "required": ["ports"], "additionalProperties": false } } } }, "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "in": "path", "name": "id", "required": true }, { "schema": { "type": "string", "enum": [ "steam-a2s", "raknet", "sampp", "fivem", "minecraft-java", "source", "teamspeak" ] }, "in": "path", "name": "type", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "ports": { "type": "array", "items": { "type": "number" } } }, "required": ["ports"], "additionalProperties": false } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "400": { "description": "Invalid request (code `invalid_request`, or a missing/malformed `Idempotency-Key`).", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, unknown or revoked API key (code `unauthorized`).", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Forbidden: `ip_not_allowed`, `insufficient_scope`, `wrong_environment`, spending cap or rejected order.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found (also for resources that belong to someone else).", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict with the current state. `firewall_unavailable`: The service has no firewall (engine \"none\"), no IP, or a fake delivery.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Unprocessable request. `feature_not_supported`: The route belongs to another firewall engine (details.engine).", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit reached. Read `Retry-After`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal error. Quote `request_id` to support.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Temporarily unavailable. `firewall_unavailable`: The firewall provider failed (a failed read is never an empty list), is not configured or is down. `internal_error`: A platform dependency does not answer; retry after Retry-After seconds.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "operationId": "postServicesByIdFirewallCachePortsByType", "x-required-scope": "manage", "x-rate-limit-bucket": "service-settings" }, "delete": { "summary": "Clear the cache of one type (gsk engine)", "tags": ["Firewall"], "description": "Removes every cache port of one protocol type. Only for the `gsk` engine.\n\n**Permission:** `manage`. **Rate-limit bucket:** `service-settings` (besides the general one).", "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "in": "path", "name": "id", "required": true }, { "schema": { "type": "string", "enum": [ "steam-a2s", "raknet", "sampp", "fivem", "minecraft-java", "source", "teamspeak" ] }, "in": "path", "name": "type", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "enum": [true] } }, "required": ["ok"], "additionalProperties": false } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "401": { "description": "Missing, unknown or revoked API key (code `unauthorized`).", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Forbidden: `ip_not_allowed`, `insufficient_scope`, `wrong_environment`, spending cap or rejected order.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found (also for resources that belong to someone else).", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict with the current state. `firewall_unavailable`: The service has no firewall (engine \"none\"), no IP, or a fake delivery.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Unprocessable request. `feature_not_supported`: The route belongs to another firewall engine (details.engine).", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit reached. Read `Retry-After`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal error. Quote `request_id` to support.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Temporarily unavailable. `firewall_unavailable`: The firewall provider failed (a failed read is never an empty list), is not configured or is down. `internal_error`: A platform dependency does not answer; retry after Retry-After seconds.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "operationId": "deleteServicesByIdFirewallCachePortsByType", "x-required-scope": "manage", "x-rate-limit-bucket": "service-settings" } }, "/services/{id}/firewall/cache-ports/{type}/ports": { "delete": { "summary": "Remove some cache ports (gsk engine)", "tags": ["Firewall"], "description": "Removes the given ports from the cache of one protocol type. Only for the `gsk` engine.\n\n**Permission:** `manage`. **Rate-limit bucket:** `service-settings` (besides the general one).", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "ports": { "type": "array", "items": { "type": "integer", "minimum": 1, "maximum": 65535 }, "minItems": 1, "maxItems": 50 } }, "required": ["ports"], "additionalProperties": false } } } }, "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "in": "path", "name": "id", "required": true }, { "schema": { "type": "string", "enum": [ "steam-a2s", "raknet", "sampp", "fivem", "minecraft-java", "source", "teamspeak" ] }, "in": "path", "name": "type", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "enum": [true] } }, "required": ["ok"], "additionalProperties": false } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "400": { "description": "Invalid request (code `invalid_request`, or a missing/malformed `Idempotency-Key`).", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, unknown or revoked API key (code `unauthorized`).", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Forbidden: `ip_not_allowed`, `insufficient_scope`, `wrong_environment`, spending cap or rejected order.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found (also for resources that belong to someone else).", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict with the current state. `firewall_unavailable`: The service has no firewall (engine \"none\"), no IP, or a fake delivery.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Unprocessable request. `feature_not_supported`: The route belongs to another firewall engine (details.engine).", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit reached. Read `Retry-After`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal error. Quote `request_id` to support.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Temporarily unavailable. `firewall_unavailable`: The firewall provider failed (a failed read is never an empty list), is not configured or is down. `internal_error`: A platform dependency does not answer; retry after Retry-After seconds.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "operationId": "deleteServicesByIdFirewallCachePortsByTypePorts", "x-required-scope": "manage", "x-rate-limit-bucket": "service-settings" } }, "/services/{id}/firewall/metrics": { "get": { "summary": "Get the traffic metrics (gsk engine)", "tags": ["Firewall"], "description": "Passed and dropped traffic samples of the primary IP. Only for the `gsk` engine.\n\n**Permission:** `read`. **Rate-limit bucket:** `service-reads` (besides the general one).", "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "samples": { "type": "array", "items": { "type": "object", "properties": { "time": { "type": "number" }, "pass_bps": { "type": "number" }, "drop_bps": { "type": "number" }, "pass_pps": { "type": "number" }, "drop_pps": { "type": "number" } }, "required": ["time", "pass_bps", "drop_bps", "pass_pps", "drop_pps"], "additionalProperties": false } } }, "required": ["samples"], "additionalProperties": false } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "401": { "description": "Missing, unknown or revoked API key (code `unauthorized`).", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Forbidden: `ip_not_allowed`, `insufficient_scope`, `wrong_environment`, spending cap or rejected order.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found (also for resources that belong to someone else).", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict with the current state. `firewall_unavailable`: The service has no firewall (engine \"none\"), no IP, or a fake delivery.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Unprocessable request. `feature_not_supported`: The route belongs to another firewall engine (details.engine).", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit reached. Read `Retry-After`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal error. Quote `request_id` to support.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Temporarily unavailable. `firewall_unavailable`: The firewall provider failed (a failed read is never an empty list), is not configured or is down. `internal_error`: A platform dependency does not answer; retry after Retry-After seconds.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "operationId": "getServicesByIdFirewallMetrics", "x-required-scope": "read", "x-rate-limit-bucket": "service-reads" } }, "/services/{id}/firewall/profiles": { "get": { "summary": "List the mitigation profiles (gsk engine)", "tags": ["Firewall"], "description": "Profiles that can be used in a rule. Only for the `gsk` engine.\n\n**Permission:** `read`. **Rate-limit bucket:** `service-reads` (besides the general one).", "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "profiles": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "description": { "type": "string" } }, "required": ["id", "name", "description"], "additionalProperties": false } } }, "required": ["profiles"], "additionalProperties": false } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "401": { "description": "Missing, unknown or revoked API key (code `unauthorized`).", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Forbidden: `ip_not_allowed`, `insufficient_scope`, `wrong_environment`, spending cap or rejected order.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found (also for resources that belong to someone else).", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict with the current state. `firewall_unavailable`: The service has no firewall (engine \"none\"), no IP, or a fake delivery.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Unprocessable request. `feature_not_supported`: The route belongs to another firewall engine (details.engine).", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit reached. Read `Retry-After`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal error. Quote `request_id` to support.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Temporarily unavailable. `firewall_unavailable`: The firewall provider failed (a failed read is never an empty list), is not configured or is down. `internal_error`: A platform dependency does not answer; retry after Retry-After seconds.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "operationId": "getServicesByIdFirewallProfiles", "x-required-scope": "read", "x-rate-limit-bucket": "service-reads" } }, "/services/{id}/firewall/rules": { "get": { "summary": "List the firewall rules (gsk engine)", "tags": ["Firewall"], "description": "Rules of the primary IP. Only for the `gsk` engine, else `422 feature_not_supported`.\n\n**Permission:** `read`. **Rate-limit bucket:** `service-reads` (besides the general one).", "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "rules": { "type": "array", "items": { "type": "object", "properties": { "profile": { "type": "string" }, "source": { "type": "string" }, "port": { "type": "string" }, "protocol": { "type": "string", "enum": ["tcp", "udp"] } }, "required": ["profile", "source", "port", "protocol"], "additionalProperties": false } } }, "required": ["rules"], "additionalProperties": false }, "example": { "rules": [ { "profile": "minecraft", "source": "0.0.0.0/0", "port": "25565", "protocol": "tcp" } ] } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "401": { "description": "Missing, unknown or revoked API key (code `unauthorized`).", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Forbidden: `ip_not_allowed`, `insufficient_scope`, `wrong_environment`, spending cap or rejected order.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found (also for resources that belong to someone else).", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict with the current state. `firewall_unavailable`: The service has no firewall (engine \"none\"), no IP, or a fake delivery.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Unprocessable request. `feature_not_supported`: The route belongs to another firewall engine (details.engine).", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit reached. Read `Retry-After`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal error. Quote `request_id` to support.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Temporarily unavailable. `firewall_unavailable`: The firewall provider failed (a failed read is never an empty list), is not configured or is down. `internal_error`: A platform dependency does not answer; retry after Retry-After seconds.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "operationId": "getServicesByIdFirewallRules", "x-required-scope": "read", "x-rate-limit-bucket": "service-reads" }, "put": { "summary": "Replace the firewall rules (gsk engine)", "tags": ["Firewall"], "description": "Replaces ALL rules of the primary IP with the given list (an empty list removes them all). Up to 200 rules; `profile` should be one of `GET /firewall/profiles`.\n\n**Permission:** `manage`. **Rate-limit bucket:** `service-settings` (besides the general one).", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "rules": { "type": "array", "items": { "type": "object", "properties": { "profile": { "type": "string", "minLength": 1, "maxLength": 64 }, "source": { "type": "string", "minLength": 1, "maxLength": 64 }, "port": { "type": "string", "minLength": 1, "maxLength": 16 }, "protocol": { "type": "string", "enum": ["tcp", "udp"] } }, "required": ["profile", "source", "port", "protocol"], "additionalProperties": false }, "maxItems": 200 } }, "required": ["rules"], "additionalProperties": false } } } }, "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "rules": { "type": "array", "items": { "type": "object", "properties": { "profile": { "type": "string" }, "source": { "type": "string" }, "port": { "type": "string" }, "protocol": { "type": "string", "enum": ["tcp", "udp"] } }, "required": ["profile", "source", "port", "protocol"], "additionalProperties": false } } }, "required": ["rules"], "additionalProperties": false } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "400": { "description": "Invalid request (code `invalid_request`, or a missing/malformed `Idempotency-Key`).", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, unknown or revoked API key (code `unauthorized`).", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Forbidden: `ip_not_allowed`, `insufficient_scope`, `wrong_environment`, spending cap or rejected order.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found (also for resources that belong to someone else).", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict with the current state. `firewall_unavailable`: The service has no firewall (engine \"none\"), no IP, or a fake delivery.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Unprocessable request. `feature_not_supported`: The route belongs to another firewall engine (details.engine).", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit reached. Read `Retry-After`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal error. Quote `request_id` to support.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Temporarily unavailable. `firewall_unavailable`: The firewall provider failed (a failed read is never an empty list), is not configured or is down. `internal_error`: A platform dependency does not answer; retry after Retry-After seconds.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "operationId": "putServicesByIdFirewallRules", "x-required-scope": "manage", "x-rate-limit-bucket": "service-settings" } }, "/services/{id}/firewall/{feature}": { "post": { "summary": "Add a firewall rule (shield engine)", "tags": ["Firewall"], "description": "Only for services whose engine is `shield`; a `gsk` service answers `422 feature_not_supported`. The body depends on the feature (`geoblock`, `srcwl`, `asn-block`, port gates…).\n\n**Permission:** `manage`. **Rate-limit bucket:** `service-settings` (besides the general one).", "requestBody": { "required": true, "content": { "application/json": { "schema": { "anyOf": [ { "not": {} }, { "type": "object", "additionalProperties": {} } ] }, "example": { "country": "CN" } } } }, "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "in": "path", "name": "id", "required": true }, { "schema": { "type": "string", "minLength": 1, "maxLength": 40 }, "in": "path", "name": "feature", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "enum": [true] } }, "required": ["ok"], "additionalProperties": false }, "example": { "ok": true } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "400": { "description": "Invalid request (code `invalid_request`, or a missing/malformed `Idempotency-Key`).", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, unknown or revoked API key (code `unauthorized`).", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Forbidden: `ip_not_allowed`, `insufficient_scope`, `wrong_environment`, spending cap or rejected order.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found (also for resources that belong to someone else).", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict with the current state. `firewall_unavailable`: The service has no firewall (engine \"none\"), no IP, or a fake delivery.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Unprocessable request. `feature_not_supported`: The route belongs to another firewall engine (details.engine).", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit reached. Read `Retry-After`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal error. Quote `request_id` to support.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Temporarily unavailable. `firewall_unavailable`: The firewall provider failed (a failed read is never an empty list), is not configured or is down. `internal_error`: A platform dependency does not answer; retry after Retry-After seconds.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "operationId": "postServicesByIdFirewallByFeature", "x-required-scope": "manage", "x-rate-limit-bucket": "service-settings" }, "delete": { "summary": "Remove a firewall rule (shield engine)", "tags": ["Firewall"], "description": "Only for services whose engine is `shield`; a `gsk` service answers `422 feature_not_supported`. The body depends on the feature (`geoblock`, `srcwl`, `asn-block`, port gates…).\n\n**Permission:** `manage`. **Rate-limit bucket:** `service-settings` (besides the general one).", "requestBody": { "required": true, "content": { "application/json": { "schema": { "anyOf": [ { "not": {} }, { "type": "object", "additionalProperties": {} } ] } } } }, "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "in": "path", "name": "id", "required": true }, { "schema": { "type": "string", "minLength": 1, "maxLength": 40 }, "in": "path", "name": "feature", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "enum": [true] } }, "required": ["ok"], "additionalProperties": false } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "400": { "description": "Invalid request (code `invalid_request`, or a missing/malformed `Idempotency-Key`).", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, unknown or revoked API key (code `unauthorized`).", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Forbidden: `ip_not_allowed`, `insufficient_scope`, `wrong_environment`, spending cap or rejected order.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found (also for resources that belong to someone else).", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict with the current state. `firewall_unavailable`: The service has no firewall (engine \"none\"), no IP, or a fake delivery.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Unprocessable request. `feature_not_supported`: The route belongs to another firewall engine (details.engine).", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit reached. Read `Retry-After`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal error. Quote `request_id` to support.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Temporarily unavailable. `firewall_unavailable`: The firewall provider failed (a failed read is never an empty list), is not configured or is down. `internal_error`: A platform dependency does not answer; retry after Retry-After seconds.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "operationId": "deleteServicesByIdFirewallByFeature", "x-required-scope": "manage", "x-rate-limit-bucket": "service-settings" } }, "/services/{id}/hostname": { "put": { "summary": "Change the hostname", "tags": ["Services"], "description": "Changes the real hostname inside the VM through the guest agent (Windows applies it on the next reboot).\n\n**Permission:** `manage`. **Rate-limit bucket:** `service-settings` (besides the general one).", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "hostname": { "type": "string", "maxLength": 253, "pattern": "^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?(\\.[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?)*$" } }, "required": ["hostname"], "additionalProperties": false }, "example": { "hostname": "web-prod-1" } } } }, "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "hostname": { "type": "string" }, "requires_reboot": { "type": "boolean" } }, "required": ["hostname", "requires_reboot"], "additionalProperties": false }, "example": { "hostname": "web-prod-1", "requires_reboot": false } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "400": { "description": "Invalid request (code `invalid_request`, or a missing/malformed `Idempotency-Key`).", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, unknown or revoked API key (code `unauthorized`).", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Forbidden: `ip_not_allowed`, `insufficient_scope`, `wrong_environment`, spending cap or rejected order.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found (also for resources that belong to someone else).", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict with the current state. `service_suspended`: The service is suspended. `service_not_ready`: The service is not active yet (still provisioning, or being reinstalled).", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit reached. Read `Retry-After`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal error. Quote `request_id` to support.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Temporarily unavailable. `maintenance`: The node blocks panel actions right now. `internal_error`: A platform dependency does not answer; retry after Retry-After seconds.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "operationId": "putServicesByIdHostname", "x-required-scope": "manage", "x-rate-limit-bucket": "service-settings" } }, "/services/{id}/metrics": { "get": { "summary": "Get service metrics", "tags": ["Services"], "description": "CPU, RAM, disk I/O and network history for `1h`, `24h` or `7d`.\n\n**Permission:** `read`. **Rate-limit bucket:** `service-reads` (besides the general one).", "parameters": [ { "schema": { "type": "string", "enum": ["1h", "24h", "7d"], "default": "1h" }, "in": "query", "name": "range", "required": false }, { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "range": { "type": "string", "enum": ["1h", "24h", "7d"] }, "available": { "type": "boolean" }, "points": { "type": "array", "items": { "type": "object", "properties": { "time": { "type": "string" }, "cpu_percent": { "type": "number", "nullable": true }, "ram_percent": { "type": "number", "nullable": true }, "disk_read_bytes_per_sec": { "type": "number", "nullable": true }, "disk_write_bytes_per_sec": { "type": "number", "nullable": true }, "network_in_bytes_per_sec": { "type": "number", "nullable": true }, "network_out_bytes_per_sec": { "type": "number", "nullable": true } }, "required": [ "time", "cpu_percent", "ram_percent", "disk_read_bytes_per_sec", "disk_write_bytes_per_sec", "network_in_bytes_per_sec", "network_out_bytes_per_sec" ], "additionalProperties": false } } }, "required": ["range", "available", "points"], "additionalProperties": false }, "example": { "range": "1h", "available": true, "points": [ { "time": "2026-11-06T11:59:00.000Z", "cpu_percent": 9.6, "ram_percent": 29.5, "disk_read_bytes_per_sec": 1270790, "disk_write_bytes_per_sec": 1639052, "network_in_bytes_per_sec": 2587202, "network_out_bytes_per_sec": 3586884 } ] } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "400": { "description": "Invalid request (code `invalid_request`, or a missing/malformed `Idempotency-Key`).", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, unknown or revoked API key (code `unauthorized`).", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Forbidden: `ip_not_allowed`, `insufficient_scope`, `wrong_environment`, spending cap or rejected order.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found (also for resources that belong to someone else).", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit reached. Read `Retry-After`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal error. Quote `request_id` to support.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Temporarily unavailable. `internal_error`: A platform dependency does not answer; retry after Retry-After seconds.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "operationId": "getServicesByIdMetrics", "x-required-scope": "read", "x-rate-limit-bucket": "service-reads" } }, "/services/{id}/network": { "get": { "summary": "Get the network of a service", "tags": ["Services"], "description": "IPv4/IPv6 addresses with their reverse DNS (PTR) request, if any.\n\n**Permission:** `read`.", "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "ips": { "type": "array", "items": { "type": "object", "properties": { "address": { "type": "string" }, "version": { "anyOf": [ { "type": "number", "enum": [4] }, { "type": "number", "enum": [6] } ] }, "primary": { "type": "boolean" }, "rdns": { "type": "object", "properties": { "ptr": { "type": "string" }, "status": { "type": "string", "enum": ["pending", "applied", "rejected"] }, "forward_confirmed": { "type": "boolean" } }, "required": ["ptr", "status", "forward_confirmed"], "additionalProperties": false, "nullable": true } }, "required": ["address", "version", "primary", "rdns"], "additionalProperties": false } }, "rdns_available": { "type": "boolean" } }, "required": ["ips", "rdns_available"], "additionalProperties": false }, "example": { "ips": [ { "address": "203.0.113.10", "version": 4, "primary": true, "rdns": { "ptr": "mail.example.com", "status": "applied", "forward_confirmed": true } }, { "address": "2001:db8:396::b8a9", "version": 6, "primary": false, "rdns": null } ], "rdns_available": true } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "401": { "description": "Missing, unknown or revoked API key (code `unauthorized`).", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Forbidden: `ip_not_allowed`, `insufficient_scope`, `wrong_environment`, spending cap or rejected order.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found (also for resources that belong to someone else).", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit reached. Read `Retry-After`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal error. Quote `request_id` to support.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Temporarily unavailable. `internal_error`: A platform dependency does not answer; retry after Retry-After seconds.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "operationId": "getServicesByIdNetwork", "x-required-scope": "read" } }, "/services/{id}/network/ips/{ip}/rdns": { "put": { "summary": "Request a reverse DNS (PTR) record", "tags": ["Services"], "description": "Requests the PTR of one of the service IPs. The name must be a full hostname that already resolves to that IP (forward-confirmed). The record is applied by the staff: status starts as `pending`.\n\n**Permission:** `manage`. **Rate-limit bucket:** `service-settings` (besides the general one).", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "ptr": { "type": "string", "minLength": 1, "maxLength": 253 } }, "required": ["ptr"], "additionalProperties": false }, "example": { "ptr": "mail.example.com" } } } }, "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "in": "path", "name": "id", "required": true }, { "schema": { "type": "string", "anyOf": [ { "format": "ipv4" }, { "format": "ipv6" } ] }, "in": "path", "name": "ip", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "ip": { "type": "string" }, "ptr": { "type": "string" }, "status": { "type": "string", "enum": ["pending"] } }, "required": ["ip", "ptr", "status"], "additionalProperties": false }, "example": { "ip": "203.0.113.10", "ptr": "mail.example.com", "status": "pending" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "400": { "description": "Invalid request (code `invalid_request`, or a missing/malformed `Idempotency-Key`).", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, unknown or revoked API key (code `unauthorized`).", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Forbidden: `ip_not_allowed`, `insufficient_scope`, `wrong_environment`, spending cap or rejected order.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found (also for resources that belong to someone else).", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit reached. Read `Retry-After`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal error. Quote `request_id` to support.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Temporarily unavailable. `internal_error`: A platform dependency does not answer; retry after Retry-After seconds.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "operationId": "putServicesByIdNetworkIpsByIpRdns", "x-required-scope": "manage", "x-rate-limit-bucket": "service-settings" } }, "/services/{id}/power/{action}": { "post": { "summary": "Power action", "tags": ["Services"], "description": "Starts, stops (hard power-off), restarts or gracefully shuts down the VPS. Returns a task. `503 maintenance` while the node blocks panel actions.\n\n**Permission:** `manage`. **Rate-limit bucket:** `power` (besides the general one).", "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "in": "path", "name": "id", "required": true }, { "schema": { "type": "string", "enum": ["start", "stop", "restart", "shutdown"] }, "in": "path", "name": "action", "required": true } ], "responses": { "202": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "task": { "type": "object", "properties": { "id": { "type": "string" }, "status": { "type": "string", "enum": ["queued", "running", "succeeded", "failed"] } }, "required": ["id", "status"], "additionalProperties": false } }, "required": ["task"], "additionalProperties": false }, "example": { "task": { "id": "tsk_883e0ff8c42d09b420", "status": "queued" } } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "401": { "description": "Missing, unknown or revoked API key (code `unauthorized`).", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Forbidden: `ip_not_allowed`, `insufficient_scope`, `wrong_environment`, spending cap or rejected order.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found (also for resources that belong to someone else).", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict with the current state. `service_suspended`: The service is suspended. `service_not_ready`: The service is not active yet (still provisioning, or being reinstalled).", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit reached. Read `Retry-After`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal error. Quote `request_id` to support.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Temporarily unavailable. `maintenance`: The node blocks panel actions right now. `internal_error`: A platform dependency does not answer; retry after Retry-After seconds.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "operationId": "postServicesByIdPowerByAction", "x-required-scope": "manage", "x-rate-limit-bucket": "power" } }, "/services/{id}/reinstall": { "post": { "summary": "Reinstall the operating system", "tags": ["Services"], "description": "WIPES THE DISK and installs the chosen OS template (`confirm: true` is required). `ssh_key_ids` are ids of SSH keys of your account. Returns a task; read the new password once with `GET /services/{id}/credentials` when it succeeds. Requires `Idempotency-Key`.\n\n**Permission:** `manage`. **Rate-limit bucket:** `reinstall` (besides the general one). **Requires** the `Idempotency-Key` header.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "os_template_id": { "type": "string", "minLength": 1, "maxLength": 64 }, "ssh_key_ids": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 64 }, "maxItems": 20 }, "confirm": { "type": "boolean", "enum": [true] } }, "required": ["os_template_id", "confirm"], "additionalProperties": false }, "example": { "os_template_id": "cm3x7k2p00002ubuntu2404", "confirm": true } } } }, "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "in": "path", "name": "id", "required": true }, { "name": "Idempotency-Key", "in": "header", "required": true, "description": "8-64 characters: letters, digits, `_` or `-`. Same key + same body within 24 h replays the stored response (`Idempotent-Replay: true`).", "schema": { "type": "string", "minLength": 8, "maxLength": 64, "pattern": "^[A-Za-z0-9_-]{8,64}$", "example": "order-acme-42-001" } } ], "responses": { "202": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "task": { "type": "object", "properties": { "id": { "type": "string" }, "status": { "type": "string", "enum": ["queued", "running", "succeeded", "failed"] } }, "required": ["id", "status"], "additionalProperties": false } }, "required": ["task"], "additionalProperties": false }, "example": { "task": { "id": "tsk_101d04a2bd37b05dac", "status": "queued" } } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "400": { "description": "Invalid request (code `invalid_request`, or a missing/malformed `Idempotency-Key`).", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, unknown or revoked API key (code `unauthorized`).", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Forbidden: `ip_not_allowed`, `insufficient_scope`, `wrong_environment`, spending cap or rejected order.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found (also for resources that belong to someone else).", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict with the current state. `service_suspended`: The service is suspended. `service_not_ready`: The service is not active yet (still provisioning, or being reinstalled). `request_in_progress`: The same Idempotency-Key is still running.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Unprocessable request. `idempotency_key_reused`: The Idempotency-Key was used with a different request.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit reached. Read `Retry-After`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal error. Quote `request_id` to support.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Temporarily unavailable. `maintenance`: The node blocks panel actions right now. `internal_error`: A platform dependency does not answer; retry after Retry-After seconds.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "operationId": "postServicesByIdReinstall", "x-required-scope": "manage", "x-rate-limit-bucket": "reinstall", "x-idempotent": true } }, "/services/{id}/renew": { "post": { "summary": "Renew a service", "tags": ["Billing"], "description": "Pays the open renewal invoice of a VPS/VDS service (creating it first when the renewal window has opened). Balance first, then the default card. Reactivates a service suspended for non-payment. Requires Idempotency-Key.\n\n**Permission:** `purchase`. **Rate-limit bucket:** `renew` (besides the general one). **Requires** the `Idempotency-Key` header.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "anyOf": [ { "not": {} }, { "type": "object", "properties": { "payment": { "type": "string", "enum": ["auto", "balance", "card"], "default": "auto" }, "cycles": { "type": "number", "enum": [1] } }, "additionalProperties": false, "nullable": true } ] }, "example": { "payment": "auto" } } } }, "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "in": "path", "name": "id", "required": true }, { "name": "Idempotency-Key", "in": "header", "required": true, "description": "8-64 characters: letters, digits, `_` or `-`. Same key + same body within 24 h replays the stored response (`Idempotent-Replay: true`).", "schema": { "type": "string", "minLength": 8, "maxLength": 64, "pattern": "^[A-Za-z0-9_-]{8,64}$", "example": "order-acme-42-001" } } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "invoice": { "type": "object", "properties": { "id": { "type": "string" }, "number": { "type": "string" }, "status": { "type": "string", "enum": ["open", "overdue", "paid", "cancelled", "disputed"] }, "total": { "type": "object", "properties": { "amount_cents": { "type": "integer" }, "currency": { "type": "string" } }, "required": ["amount_cents", "currency"], "additionalProperties": false }, "created_at": { "type": "string" }, "due_at": { "type": "string" }, "paid_at": { "type": "string", "nullable": true }, "lines": { "type": "array", "items": { "type": "object", "properties": { "description": { "type": "string" }, "type": { "type": "string" }, "service_id": { "type": "string", "nullable": true }, "quantity": { "type": "integer" }, "unit_price": { "type": "object", "properties": { "amount_cents": { "type": "integer" }, "currency": { "type": "string" } }, "required": ["amount_cents", "currency"], "additionalProperties": false }, "total": { "type": "object", "properties": { "amount_cents": { "type": "integer" }, "currency": { "type": "string" } }, "required": ["amount_cents", "currency"], "additionalProperties": false } }, "required": [ "description", "type", "service_id", "quantity", "unit_price", "total" ], "additionalProperties": false } } }, "required": [ "id", "number", "status", "total", "created_at", "due_at", "paid_at", "lines" ], "additionalProperties": false, "nullable": true }, "service": { "type": "object", "properties": { "id": { "type": "string" }, "hostname": { "type": "string" }, "status": { "type": "string", "enum": [ "provisioning", "active", "suspended", "paused", "cancelled", "error" ] }, "billing": { "type": "object", "properties": { "cycle": { "type": "string", "enum": ["monthly", "quarterly", "semiannual", "annual"] }, "price": { "type": "object", "properties": { "amount_cents": { "type": "integer" }, "currency": { "type": "string" } }, "required": ["amount_cents", "currency"], "additionalProperties": false }, "current_period_end": { "type": "string", "nullable": true }, "next_invoice_at": { "type": "string", "nullable": true }, "open_invoice_id": { "type": "string", "nullable": true }, "due_at": { "type": "string", "nullable": true }, "grace_ends_at": { "type": "string", "nullable": true }, "suspends_at": { "type": "string", "nullable": true }, "terminates_at": { "type": "string", "nullable": true }, "auto_renew": { "type": "string", "enum": ["off", "balance", "balance_and_card", "card"] }, "cancel_at_period_end": { "type": "boolean" }, "renewable": { "type": "boolean" } }, "required": [ "cycle", "price", "current_period_end", "next_invoice_at", "open_invoice_id", "due_at", "grace_ends_at", "suspends_at", "terminates_at", "auto_renew", "cancel_at_period_end", "renewable" ], "additionalProperties": false } }, "required": ["id", "hostname", "status", "billing"], "additionalProperties": false }, "already_paid": { "type": "boolean" } }, "required": ["invoice", "service", "already_paid"], "additionalProperties": false }, "example": { "invoice": { "id": "inv_cm3z4c9s00007renew02", "number": "INV-2026-000412", "status": "paid", "total": { "amount_cents": 720, "currency": "USD" }, "created_at": "2026-12-02T06:00:00.000Z", "due_at": "2026-12-05T06:00:00.000Z", "paid_at": "2026-12-02T06:01:12.000Z", "lines": [ { "description": "Service renewal - VPS Small (monthly) - web-1", "type": "plan", "service_id": "K3F8QX2P", "quantity": 1, "unit_price": { "amount_cents": 800, "currency": "USD" }, "total": { "amount_cents": 800, "currency": "USD" } }, { "description": "Reseller discount (10%)", "type": "discount", "service_id": "K3F8QX2P", "quantity": 1, "unit_price": { "amount_cents": -80, "currency": "USD" }, "total": { "amount_cents": -80, "currency": "USD" } } ] }, "service": { "id": "K3F8QX2P", "hostname": "web-1", "status": "active", "billing": { "cycle": "monthly", "price": { "amount_cents": 720, "currency": "USD" }, "current_period_end": "2027-01-05T12:00:00.000Z", "next_invoice_at": "2027-01-02T12:00:00.000Z", "open_invoice_id": null, "due_at": null, "grace_ends_at": null, "suspends_at": null, "terminates_at": null, "auto_renew": "off", "cancel_at_period_end": false, "renewable": true } }, "already_paid": false } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "400": { "description": "Invalid request (code `invalid_request`, or a missing/malformed `Idempotency-Key`).", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, unknown or revoked API key (code `unauthorized`).", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Payment needs the customer or failed. `requires_action`: The card needs the customer: details.reason is authentication_required (3-D Secure), no_card (no saved default card) or no_mandate (the automatic-charge mandate version 2026-11-v2 is not accepted for the card). Nothing was charged. `card_declined`: The card was declined (details.reason: declined, insufficient_funds) or card payments are switched off (stripe_disabled). Nothing was charged. `insufficient_balance`: The balance does not cover the total (details.required_cents), and with payment \"auto\" no card can be used either (details.card).", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Forbidden: `ip_not_allowed`, `insufficient_scope`, `wrong_environment`, spending cap or rejected order. `spending_cap_exceeded`: The amount, the daily total or the hourly purchase count goes over a cap of the key. `spending_caps_not_set`: The key has \"purchase\" but no spending caps loaded.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found (also for resources that belong to someone else).", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict with the current state. `conflict`: details.reason says why: service_cancelled, service_error, service_paused, cancellation_scheduled, no_billing_cycle, grouped_invoice, invoice_not_payable, payment_in_progress, no_default_card, mandate_not_accepted. `request_in_progress`: The same Idempotency-Key is still running.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Unprocessable request. `idempotency_key_reused`: The Idempotency-Key was used with a different request.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit reached. Read `Retry-After`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal error. Quote `request_id` to support.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Temporarily unavailable. `internal_error`: A platform dependency does not answer; retry after Retry-After seconds.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "operationId": "postServicesByIdRenew", "x-required-scope": "purchase", "x-rate-limit-bucket": "renew", "x-idempotent": true } }, "/services/{id}/reset-password": { "post": { "summary": "Reset the root/Administrator password", "tags": ["Services"], "description": "Generates a new strong password and applies it through the guest agent. The password is NOT in this response nor in any log: read it once with `GET /services/{id}/credentials` after the task succeeds. Requires `Idempotency-Key`.\n\n**Permission:** `manage`. **Rate-limit bucket:** `reset-password` (besides the general one). **Requires** the `Idempotency-Key` header.", "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "in": "path", "name": "id", "required": true }, { "name": "Idempotency-Key", "in": "header", "required": true, "description": "8-64 characters: letters, digits, `_` or `-`. Same key + same body within 24 h replays the stored response (`Idempotent-Replay: true`).", "schema": { "type": "string", "minLength": 8, "maxLength": 64, "pattern": "^[A-Za-z0-9_-]{8,64}$", "example": "order-acme-42-001" } } ], "responses": { "202": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "task": { "type": "object", "properties": { "id": { "type": "string" }, "status": { "type": "string", "enum": ["queued", "running", "succeeded", "failed"] } }, "required": ["id", "status"], "additionalProperties": false } }, "required": ["task"], "additionalProperties": false }, "example": { "task": { "id": "tsk_027b75d163aafa7be6", "status": "queued" } } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "400": { "description": "Invalid request (code `invalid_request`, or a missing/malformed `Idempotency-Key`).", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, unknown or revoked API key (code `unauthorized`).", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Forbidden: `ip_not_allowed`, `insufficient_scope`, `wrong_environment`, spending cap or rejected order.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found (also for resources that belong to someone else).", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict with the current state. `service_suspended`: The service is suspended. `service_not_ready`: The service is not active yet (still provisioning, or being reinstalled). `request_in_progress`: The same Idempotency-Key is still running.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Unprocessable request. `idempotency_key_reused`: The Idempotency-Key was used with a different request.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit reached. Read `Retry-After`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal error. Quote `request_id` to support.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Temporarily unavailable. `maintenance`: The node blocks panel actions right now. `internal_error`: A platform dependency does not answer; retry after Retry-After seconds.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "operationId": "postServicesByIdResetPassword", "x-required-scope": "manage", "x-rate-limit-bucket": "reset-password", "x-idempotent": true } }, "/services/{id}/ssh-keys": { "get": { "summary": "List the SSH keys of a service", "tags": ["Services"], "description": "Public keys registered on the service (the ones kept across reinstalls). Only public data is ever returned.\n\n**Permission:** `read`.", "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string" }, "fingerprint": { "type": "string" }, "comment": { "type": "string" }, "public_key": { "type": "string" } }, "required": ["id", "type", "fingerprint", "comment", "public_key"], "additionalProperties": false } } }, "required": ["data"], "additionalProperties": false }, "example": { "data": [ { "id": "key_dc959f518826c74c1d", "type": "ssh-ed25519", "fingerprint": "SHA256:+DiY3wvvV6TuJJhbpZisF/zLDA0zPMSvHdkr4UvCOqU", "comment": "me@laptop", "public_key": "ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIOMqqnkVzrm0SdG6UOoqKLsabgH5C9okWi0dh2l9GKJl me@laptop" } ] } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "401": { "description": "Missing, unknown or revoked API key (code `unauthorized`).", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Forbidden: `ip_not_allowed`, `insufficient_scope`, `wrong_environment`, spending cap or rejected order.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found (also for resources that belong to someone else).", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit reached. Read `Retry-After`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal error. Quote `request_id` to support.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Temporarily unavailable. `internal_error`: A platform dependency does not answer; retry after Retry-After seconds.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "operationId": "getServicesByIdSshKeys", "x-required-scope": "read" }, "post": { "summary": "Install an SSH public key", "tags": ["Services"], "description": "Adds a PUBLIC key to the running Linux VM (guest agent) and keeps it for reinstalls. The key is also stored in your account so its id can be used in `ssh_key_ids`.\n\n**Permission:** `manage`. **Rate-limit bucket:** `service-settings` (besides the general one).", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "public_key": { "type": "string", "minLength": 1, "maxLength": 16000 }, "name": { "type": "string", "minLength": 1, "maxLength": 60 } }, "required": ["public_key"], "additionalProperties": false }, "example": { "public_key": "ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIOMqqnkVzrm0SdG6UOoqKLsabgH5C9okWi0dh2l9GKJl me@laptop", "name": "laptop" } } } }, "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "in": "path", "name": "id", "required": true } ], "responses": { "201": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string" }, "fingerprint": { "type": "string" }, "comment": { "type": "string" }, "public_key": { "type": "string" } }, "required": ["id", "type", "fingerprint", "comment", "public_key"], "additionalProperties": false }, "example": { "id": "key_dc959f518826c74c1d", "type": "ssh-ed25519", "fingerprint": "SHA256:+DiY3wvvV6TuJJhbpZisF/zLDA0zPMSvHdkr4UvCOqU", "comment": "me@laptop", "public_key": "ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIOMqqnkVzrm0SdG6UOoqKLsabgH5C9okWi0dh2l9GKJl me@laptop" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "400": { "description": "Invalid request (code `invalid_request`, or a missing/malformed `Idempotency-Key`).", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, unknown or revoked API key (code `unauthorized`).", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Forbidden: `ip_not_allowed`, `insufficient_scope`, `wrong_environment`, spending cap or rejected order.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found (also for resources that belong to someone else).", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict with the current state. `service_suspended`: The service is suspended. `service_not_ready`: The service is not active yet (still provisioning, or being reinstalled).", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit reached. Read `Retry-After`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal error. Quote `request_id` to support.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Temporarily unavailable. `maintenance`: The node blocks panel actions right now. `internal_error`: A platform dependency does not answer; retry after Retry-After seconds.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "operationId": "postServicesByIdSshKeys", "x-required-scope": "manage", "x-rate-limit-bucket": "service-settings" } }, "/services/{id}/ssh-keys/{keyId}": { "delete": { "summary": "Remove an SSH key from a service", "tags": ["Services"], "description": "Removes the key from the VM authorized_keys and from the keys kept for reinstalls.\n\n**Permission:** `manage`. **Rate-limit bucket:** `service-settings` (besides the general one).", "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "in": "path", "name": "id", "required": true }, { "schema": { "type": "string", "pattern": "^key_[A-Za-z0-9_-]{43}$" }, "in": "path", "name": "keyId", "required": true } ], "responses": { "204": { "description": "Default Response", "content": { "application/json": { "schema": {} } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "401": { "description": "Missing, unknown or revoked API key (code `unauthorized`).", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Forbidden: `ip_not_allowed`, `insufficient_scope`, `wrong_environment`, spending cap or rejected order.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found (also for resources that belong to someone else).", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict with the current state. `service_suspended`: The service is suspended. `service_not_ready`: The service is not active yet (still provisioning, or being reinstalled).", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit reached. Read `Retry-After`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal error. Quote `request_id` to support.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Temporarily unavailable. `maintenance`: The node blocks panel actions right now. `internal_error`: A platform dependency does not answer; retry after Retry-After seconds.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "operationId": "deleteServicesByIdSshKeysByKeyId", "x-required-scope": "manage", "x-rate-limit-bucket": "service-settings" } }, "/services/{id}/status": { "get": { "summary": "Get the live status of a service", "tags": ["Services"], "description": "Cheap status read: power state, uptime and a snapshot of CPU, RAM and network counters.\n\n**Permission:** `read`. **Rate-limit bucket:** `service-reads` (besides the general one).", "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "power_state": { "type": "string", "enum": ["running", "stopped", "paused", "unknown"], "nullable": true }, "uptime_seconds": { "type": "number", "nullable": true }, "last_seen": { "type": "string", "nullable": true }, "cpu_percent": { "type": "number", "nullable": true }, "ram": { "type": "object", "properties": { "used_bytes": { "type": "number", "nullable": true }, "total_bytes": { "type": "number", "nullable": true } }, "required": ["used_bytes", "total_bytes"], "additionalProperties": false }, "network": { "type": "object", "properties": { "in_bytes": { "type": "number", "nullable": true }, "out_bytes": { "type": "number", "nullable": true } }, "required": ["in_bytes", "out_bytes"], "additionalProperties": false } }, "required": [ "power_state", "uptime_seconds", "last_seen", "cpu_percent", "ram", "network" ], "additionalProperties": false }, "example": { "power_state": "running", "uptime_seconds": 86400, "last_seen": "2026-11-06T12:00:00.000Z", "cpu_percent": 9.7, "ram": { "used_bytes": 604000000, "total_bytes": 2147483648 }, "network": { "in_bytes": 2601682, "out_bytes": 3606958 } } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "401": { "description": "Missing, unknown or revoked API key (code `unauthorized`).", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Forbidden: `ip_not_allowed`, `insufficient_scope`, `wrong_environment`, spending cap or rejected order.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found (also for resources that belong to someone else).", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit reached. Read `Retry-After`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal error. Quote `request_id` to support.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Temporarily unavailable. `internal_error`: A platform dependency does not answer; retry after Retry-After seconds.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "operationId": "getServicesByIdStatus", "x-required-scope": "read", "x-rate-limit-bucket": "service-reads" } }, "/tasks/{id}": { "get": { "summary": "Get a task", "tags": ["Services"], "description": "Status of an asynchronous operation: `queued`, `running`, `succeeded` or `failed` (with `error.code`). Only the account that created the task can read it.\n\n**Permission:** `read`.", "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "power.start", "power.stop", "power.restart", "power.shutdown", "reinstall", "reset_password" ] }, "status": { "type": "string", "enum": ["queued", "running", "succeeded", "failed"] }, "service_id": { "type": "string" }, "created_at": { "type": "string" }, "started_at": { "type": "string", "nullable": true }, "finished_at": { "type": "string", "nullable": true }, "error": { "type": "object", "properties": { "code": { "type": "string" } }, "required": ["code"], "additionalProperties": false, "nullable": true } }, "required": [ "id", "type", "status", "service_id", "created_at", "started_at", "finished_at", "error" ], "additionalProperties": false }, "example": { "id": "tsk_883e0ff8c42d09b420", "type": "power.restart", "status": "succeeded", "service_id": "K3F8QX2P", "created_at": "2026-11-05T12:30:00.000Z", "started_at": "2026-11-05T12:30:01.000Z", "finished_at": "2026-11-05T12:30:05.000Z", "error": null } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } } }, "401": { "description": "Missing, unknown or revoked API key (code `unauthorized`).", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Forbidden: `ip_not_allowed`, `insufficient_scope`, `wrong_environment`, spending cap or rejected order.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found (also for resources that belong to someone else).", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit reached. Read `Retry-After`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal error. Quote `request_id` to support.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Temporarily unavailable. `internal_error`: A platform dependency does not answer; retry after Retry-After seconds.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "operationId": "getTasksById", "x-required-scope": "read" } } }, "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "description": "A live key (`sk_live_...`) approved by Solume staff. It only works from the IP addresses registered for it (`403 ip_not_allowed` otherwise). A sandbox key here answers `403 wrong_environment`." } }, "schemas": { "Error": { "type": "object", "required": ["error"], "properties": { "error": { "type": "object", "required": ["code", "message", "request_id"], "properties": { "code": { "type": "string", "description": "Stable, documented error code." }, "message": { "type": "string", "description": "Human-readable text; may change. Never branch on it." }, "request_id": { "type": "string", "description": "Same value as the `X-Request-Id` response header.", "example": "req_5b1c0e7d2a9f4c3b8e16" }, "details": { "type": "object", "additionalProperties": true, "description": "Extra data for some codes (for example `cap`, `remaining_cents`, `engine`, `reason`, `retry_after`)." } } } } } }, "headers": { "X-Request-Id": { "description": "Id of this request. Quote it to support.", "schema": { "type": "string", "example": "req_5b1c0e7d2a9f4c3b8e16" } }, "X-RateLimit-Limit": { "description": "Requests allowed in the current window of the general bucket.", "schema": { "type": "integer", "example": 120 } }, "X-RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer", "example": 118 } }, "X-RateLimit-Reset": { "description": "Unix time (seconds) when the window resets.", "schema": { "type": "integer", "example": 1793880060 } }, "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer", "example": 30 } } } } }