{ "openapi": "3.1.0", "info": { "title": "Fiberax API", "version": "v1", "description": "The Fiberax API lets your own programs manage a Virtual Data Center project: servers, private\nnetworks, public addresses, backups, images and firewalls. It is built for automation - a\nTerraform provider, a deployment script, an SDK - rather than for a person clicking through a\nconsole. Everything the console does with a project's resources is available here, and the two\nstay in step because both drive the same platform.\n\n## Getting started\n\n1. Open **API tokens** in your client area and issue a token for the project you want to manage.\n The secret is shown once; we store only its fingerprint.\n2. Send it in the `Authorization` header on every request.\n\n```\ncurl -H \"Authorization: Bearer fbx_YOUR_TOKEN\" \\\n https://api.fiberax.com/v1/servers\n```\n\nA token belongs to **one project** and carries a fixed access level - read, or read and write.\nTo manage several projects, issue a token for each. The project is never named in a path: it\ncomes from the token, so there is nothing to guess and nothing to forge.\n\n## Authentication\n\nBearer token, no session, no expiry unless you chose one when issuing it. Tokens can be revoked\nfrom the same page at any time; revocation takes effect immediately.\n\nAccess levels:\n\n- **read** - every `GET` in this reference.\n- **read and write** - everything, including creating, changing and deleting resources.\n\nA request that exceeds the token's level is refused with `403 insufficient_scope`.\n\nIf the token was issued to a team member rather than to the account owner, each operation is\nadditionally checked against the permissions that member has in the client area. An operation\nthe member cannot perform in the console is refused here too, with `403 insufficient_privileges`.\n\n## Response envelope\n\nEvery successful response carries the payload under `data`:\n\n```json\n{ \"data\": { \"id\": 10657, \"name\": \"web-01\", \"status\": \"running\" } }\n```\n\nCollections are always a JSON array under `data`, including when empty. No field changes its\ntype depending on how much data there is.\n\nEvery response carries an `X-Request-Id` header. Quote it when you contact support - it is how\nwe find your exact call.\n\n## Errors\n\nErrors follow [RFC 9457 Problem Details](https://www.rfc-editor.org/rfc/rfc9457.html) and are\nserved as `application/problem+json`:\n\n```json\n{\n \"type\": \"https://docs.fiberax.com/errors/server_not_found\",\n \"title\": \"Server not found\",\n \"status\": 404,\n \"code\": \"server_not_found\",\n \"request_id\": \"a277dcd1ca652c65\"\n}\n```\n\nBranch your code on `code` - it is machine-readable, stable, and independent of language. The\n`type` member links to a page explaining that specific code and what to do about it. When a\nrequest fails validation, `invalid_params` names the offending fields:\n\n```json\n{\n \"code\": \"invalid_request\",\n \"status\": 422,\n \"invalid_params\": [ { \"name\": \"memory_mb\", \"reason\": \"must be between 1024 and 4194304\" } ]\n}\n```\n\n**The set of codes grows.** New codes appear as the platform gains operations, so treat a code you\ndo not recognise by its HTTP status and carry on - a client that refuses to parse an unknown code\nbreaks on an ordinary release. For that reason the specification publishes the codes as examples\nrather than as a closed list; the full list is at\n[docs.fiberax.com/errors](https://docs.fiberax.com/errors/).\n\nTwo codes are not declared per operation, because they cannot reach a generated client:\n\n- **405** arrives when the path exists but the method does not. The response carries an `Allow`\n header naming the methods that path accepts. A generated library calls a declared method, so it\n will not see this one - you will, if you build requests by hand.\n- **415** arrives when the body was sent form-encoded instead of JSON. It is declared on every\n write operation, since that is where it can happen.\n\nThree classes are worth distinguishing in code:\n\n- **422** - the request is wrong. Fix the body or the query and send it again.\n- **409** - the request is right but the current state blocks it. Change the state, then repeat\n the same request.\n- **503** - the request is right and our side could not complete it. Repeat later.\n\n## Request bodies\n\nJSON only. Every operation declares the fields it accepts, and an unknown field is refused with\n`422` rather than ignored - a typo in your configuration should fail loudly instead of quietly\napplying something you did not mean. Types are checked strictly: a boolean field accepts `true`\nand `false`, not `\"true\"` or `1`.\n\nString fields are trimmed before they are checked, so `\" web-01 \"` is stored as `web-01`. The\npatterns published in the specification describe the trimmed value, which is why a generated\nclient that validates locally may refuse a value this API would have accepted. Send values\nwithout leading or trailing whitespace and the two agree exactly. Secrets are the exception:\npasswords are never trimmed - a silently altered secret would leave you with one string and the\nserver with another - so they are refused instead.\n\n## Asynchronous operations\n\nWork that outlives a request returns `202` with a task next to the data:\n\n```json\n{\n \"data\": null,\n \"task\": { \"id\": \"8f3c...\", \"status\": \"pending\", \"is_terminal\": false,\n \"poll\": \"/v1/tasks/8f3c...\", \"created_at\": \"2026-08-19T14:03:11+02:00\" }\n}\n```\n\nPoll `GET /v1/tasks/{id}` until `is_terminal` is true, then read the resource itself. There are\nexactly four states - `pending`, `running`, `succeeded`, `failed` - and the set is closed, so\nyour code can branch on it without a catch-all.\n\nTwo details worth coding for:\n\n- **`task` is `null` and the status is 200.** The work was already done inside the request;\n there is nothing to wait for. The field is always present, so test its value, not its presence.\n- **Taking a backup is the one operation without a task.** Its response points at the created\n backup, and you wait by polling that backup until its status becomes `available`.\n\n## Repeating a request safely\n\nSend an `Idempotency-Key` header on write operations. A dropped connection should not cost you a\nsecond server or a second billable address.\n\n- The key is yours to choose, 8 to 255 printable characters, one per logical operation.\n- Repeating the same key with the same body replays the stored response, with\n `Idempotency-Replayed: true`.\n- Repeating the same key with a different body is refused - a key promises one operation.\n- Keys are remembered for 24 hours, per project.\n- Failures on our side (`5xx`) and state conflicts (`409`) are **not** stored: you are meant to\n retry those. After a `409`, retry with the same key. After a `5xx`, read the resource first and\n then retry with a **new** key - the work may already have been started.\n\n## Rate limit\n\nTwo separate budgets, both counted per token, per minute:\n\n- **60 reads** per minute\n- **20 writes** per minute\n\nThey do not share a bucket, so polling a task does not consume your budget for creating servers.\nExceeding either returns `429` with a `Retry-After` header telling you how many seconds are left\nin the current minute. There is no header reporting your remaining allowance - handle `429` and\nback off.\n\nThe limit is per token, not per project: several tokens do not share one budget. Worth knowing if\nyou run a large plan in parallel - a provider that reads many resources at once can reach 60 reads\nper minute on its own.\n\n## Query parameters, dates and numbers\n\nDeclared per operation, and an unknown parameter is refused with `422` - the same rule as for\nrequest bodies, for the same reason.\n\nTimestamps are RFC 3339. Parameters take UTC (`2026-08-16T00:00:00Z`); ranges are half-open, with\n`start` included and `end` excluded, and both bounds are given together. Human forms like `now` or\n`+1 day` are not accepted, and an impossible date is refused rather than rolled forward.\n\nTimestamps inside resources carry a real offset (`2026-08-19T14:03:11+02:00`).\n\nMoney and quantities in the costs endpoint are **strings**, not numbers, so no precision is lost\non the way to your code.\n\n## Versioning\n\nThe base path carries the version: `https://api.fiberax.com/v1`. Breaking changes ship as a new\nversion; the previous one keeps working while it is deprecated. Adding a field to a response is\nnot a breaking change - ignore fields you do not know.\n\n## What this API does not cover\n\nOrdering and closing the project itself, the server console, GPU server types and snapshots are\ndeliberately outside the API and stay in the client area. SSH keys are worth one note: they\nbelong to your **account**, not to a single project, so a token issued for one project can list\nand delete keys used by all of them.\n", "contact": { "name": "Fiberax support", "url": "https://fiberax.com/clientarea/" } }, "servers": [ { "url": "https://api.fiberax.com/v1", "description": "Production" } ], "tags": [ { "name": "Project", "description": "The project this token belongs to: its name, its backup default, and what it has run up so far." }, { "name": "Servers", "description": "Create, inspect, resize and remove servers, and act on the ones you have." }, { "name": "Tags", "description": "Your own labels on a server. They are yours to structure - the platform does not read them." }, { "name": "Disks", "description": "Data disks attached to a server. The system disk is sized through the server itself." }, { "name": "Network interfaces", "description": "Network cards on a server. A card's network is a field on the card, not a separate resource." }, { "name": "Networks", "description": "Private networks inside the project, and the router that serves them." }, { "name": "Router", "description": "A router is a server, with operations of its own: the networks it serves and address handout, its public address, and its configuration - access rules, port forwards, WireGuard and OpenVPN." }, { "name": "IP addresses", "description": "Public IPv4 addresses held by the project. An address is billed from the moment you take it, attached or not." }, { "name": "SSH keys", "description": "Keys in your account pool. They belong to the account, so every project of yours sees the same pool." }, { "name": "Server types", "description": "What kinds of server you can create, which images each offers, and what they cost." }, { "name": "Backups", "description": "Backups of a server and the policy that schedules them." }, { "name": "Images", "description": "Images you own: ISO files you added by URL, and images taken from your own servers. Also what is in a server's drive." }, { "name": "Firewall", "description": "The firewall of a server, rules included. One resource, replaced as a whole." }, { "name": "Tasks", "description": "Background work. Every asynchronous operation hands you one of these to poll." } ], "security": [ { "bearerAuth": [] } ], "paths": { "/ips": { "get": { "operationId": "ip_list", "tags": [ "IP addresses" ], "summary": "List addresses", "description": "Public addresses held by the project, attached or free. A free address is still billed.", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "description": "Identifier of this call." } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Ip" } } } } } } }, "400": { "$ref": "#/components/responses/Problem400" }, "401": { "$ref": "#/components/responses/Problem401" }, "402": { "$ref": "#/components/responses/Problem402" }, "403": { "$ref": "#/components/responses/Problem403" }, "404": { "$ref": "#/components/responses/Problem404" }, "409": { "$ref": "#/components/responses/Problem409" }, "422": { "$ref": "#/components/responses/Problem422" }, "429": { "$ref": "#/components/responses/Problem429" }, "500": { "$ref": "#/components/responses/Problem500" }, "503": { "$ref": "#/components/responses/Problem503" } } }, "post": { "operationId": "ip_allocate", "tags": [ "IP addresses" ], "summary": "Take a public address", "description": "Takes a new address for the project. Billing starts immediately, whether or not you attach it to a server.", "security": [ { "bearerAuth": [] } ], "responses": { "201": { "description": "Created.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "description": "Identifier of this call." }, "Location": { "schema": { "type": "string" }, "description": "Path of the created resource." }, "Idempotency-Replayed": { "schema": { "type": "string", "examples": [ "true" ] }, "description": "Present and set to true when this is a stored response replayed for a repeated Idempotency-Key. The work was done by the first call." } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Ip" } } } } } }, "400": { "$ref": "#/components/responses/Problem400" }, "401": { "$ref": "#/components/responses/Problem401" }, "402": { "$ref": "#/components/responses/Problem402" }, "403": { "$ref": "#/components/responses/Problem403" }, "404": { "$ref": "#/components/responses/Problem404" }, "409": { "$ref": "#/components/responses/Problem409" }, "422": { "$ref": "#/components/responses/Problem422" }, "429": { "$ref": "#/components/responses/Problem429" }, "500": { "$ref": "#/components/responses/Problem500" }, "503": { "$ref": "#/components/responses/Problem503" }, "415": { "$ref": "#/components/responses/Problem415" } }, "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "server_type_id": { "type": "integer", "minimum": 1, "description": "Take the address from the pool serving this server type. Omit and the project's own location is used." } }, "additionalProperties": false } } } }, "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Repeat-safety key. Repeating the same key with the same body replays the stored response.", "schema": { "type": "string", "minLength": 8, "maxLength": 255 } } ] } }, "/ips/{id}": { "get": { "operationId": "ip_get", "tags": [ "IP addresses" ], "summary": "Read an address", "description": "One public address and the server it is attached to, if any.", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "description": "Identifier of this call." } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Ip" } } } } } }, "400": { "$ref": "#/components/responses/Problem400" }, "401": { "$ref": "#/components/responses/Problem401" }, "402": { "$ref": "#/components/responses/Problem402" }, "403": { "$ref": "#/components/responses/Problem403" }, "404": { "$ref": "#/components/responses/Problem404" }, "409": { "$ref": "#/components/responses/Problem409" }, "422": { "$ref": "#/components/responses/Problem422" }, "429": { "$ref": "#/components/responses/Problem429" }, "500": { "$ref": "#/components/responses/Problem500" }, "503": { "$ref": "#/components/responses/Problem503" } }, "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Identifier of the resource.", "schema": { "type": "integer" } } ] }, "delete": { "operationId": "ip_release", "tags": [ "IP addresses" ], "summary": "Release an address", "description": "Gives the address back and stops the charge. An address attached to a server cannot be released - detach it first and wait for the detaching task to finish: the address leaves the server inside that task, so an earlier release answers 409 ip_in_use.", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "description": "Identifier of this call." }, "Idempotency-Replayed": { "schema": { "type": "string", "examples": [ "true" ] }, "description": "Present and set to true when this is a stored response replayed for a repeated Idempotency-Key. The work was done by the first call." } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Deleted" } } } } } }, "400": { "$ref": "#/components/responses/Problem400" }, "401": { "$ref": "#/components/responses/Problem401" }, "402": { "$ref": "#/components/responses/Problem402" }, "403": { "$ref": "#/components/responses/Problem403" }, "404": { "$ref": "#/components/responses/Problem404" }, "409": { "$ref": "#/components/responses/Problem409" }, "422": { "$ref": "#/components/responses/Problem422" }, "429": { "$ref": "#/components/responses/Problem429" }, "500": { "$ref": "#/components/responses/Problem500" }, "503": { "$ref": "#/components/responses/Problem503" }, "415": { "$ref": "#/components/responses/Problem415" } }, "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Identifier of the resource.", "schema": { "type": "integer" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Repeat-safety key. Repeating the same key with the same body replays the stored response.", "schema": { "type": "string", "minLength": 8, "maxLength": 255 } } ] } }, "/isos": { "get": { "operationId": "iso_list", "tags": [ "Images" ], "summary": "List ISO images", "description": "ISO files you added to this project.", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "description": "Identifier of this call." } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Iso" } } } } } } }, "400": { "$ref": "#/components/responses/Problem400" }, "401": { "$ref": "#/components/responses/Problem401" }, "402": { "$ref": "#/components/responses/Problem402" }, "403": { "$ref": "#/components/responses/Problem403" }, "404": { "$ref": "#/components/responses/Problem404" }, "409": { "$ref": "#/components/responses/Problem409" }, "422": { "$ref": "#/components/responses/Problem422" }, "429": { "$ref": "#/components/responses/Problem429" }, "500": { "$ref": "#/components/responses/Problem500" }, "503": { "$ref": "#/components/responses/Problem503" } } }, "post": { "operationId": "iso_create", "tags": [ "Images" ], "summary": "Add an ISO image", "description": "We fetch the file from the URL you give. Watch the status: the response comes back long before the download finishes. The project image library is handled one request at a time, so a parallel image operation of the same project makes this one wait up to three seconds and then answer 409 server_busy with Retry-After.", "security": [ { "bearerAuth": [] } ], "responses": { "202": { "description": "Accepted. The work continues in the background - poll the task.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "description": "Identifier of this call." }, "Location": { "schema": { "type": "string" }, "description": "Path of the created resource." }, "Idempotency-Replayed": { "schema": { "type": "string", "examples": [ "true" ] }, "description": "Present and set to true when this is a stored response replayed for a repeated Idempotency-Key. The work was done by the first call." } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Iso" }, "task": { "oneOf": [ { "$ref": "#/components/schemas/Task" }, { "type": "null" } ], "description": "Null when the work was already finished inside the request." } } } } } }, "200": { "description": "Done inside the request: the task field is null, there is nothing to wait for.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "description": "Identifier of this call." }, "Location": { "schema": { "type": "string" }, "description": "Path of the created resource." }, "Idempotency-Replayed": { "schema": { "type": "string", "examples": [ "true" ] }, "description": "Present and set to true when this is a stored response replayed for a repeated Idempotency-Key. The work was done by the first call." } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Iso" }, "task": { "oneOf": [ { "$ref": "#/components/schemas/Task" }, { "type": "null" } ], "description": "Null when the work was already finished inside the request." } } } } } }, "400": { "$ref": "#/components/responses/Problem400" }, "401": { "$ref": "#/components/responses/Problem401" }, "402": { "$ref": "#/components/responses/Problem402" }, "403": { "$ref": "#/components/responses/Problem403" }, "404": { "$ref": "#/components/responses/Problem404" }, "409": { "$ref": "#/components/responses/Problem409" }, "422": { "$ref": "#/components/responses/Problem422" }, "429": { "$ref": "#/components/responses/Problem429" }, "500": { "$ref": "#/components/responses/Problem500" }, "503": { "$ref": "#/components/responses/Problem503" }, "415": { "$ref": "#/components/responses/Problem415" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string", "minLength": 8, "maxLength": 2048, "description": "Where to fetch the ISO from. Must be reachable from the internet." }, "name": { "type": "string", "minLength": 1, "maxLength": 50, "description": "Your name for the image. Omit and it is taken from the file name." } }, "additionalProperties": false, "required": [ "url" ] } } } }, "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Repeat-safety key. Repeating the same key with the same body replays the stored response.", "schema": { "type": "string", "minLength": 8, "maxLength": 255 } } ] } }, "/isos/{id}": { "get": { "operationId": "iso_get", "tags": [ "Images" ], "summary": "Read an ISO image", "description": "One ISO, its download status and, if the download failed, why.", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "description": "Identifier of this call." } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Iso" } } } } } }, "400": { "$ref": "#/components/responses/Problem400" }, "401": { "$ref": "#/components/responses/Problem401" }, "402": { "$ref": "#/components/responses/Problem402" }, "403": { "$ref": "#/components/responses/Problem403" }, "404": { "$ref": "#/components/responses/Problem404" }, "409": { "$ref": "#/components/responses/Problem409" }, "422": { "$ref": "#/components/responses/Problem422" }, "429": { "$ref": "#/components/responses/Problem429" }, "500": { "$ref": "#/components/responses/Problem500" }, "503": { "$ref": "#/components/responses/Problem503" } }, "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Identifier of the resource.", "schema": { "type": "string", "pattern": "^(?:uiso-\\d{1,10})$" } } ] }, "delete": { "operationId": "iso_delete", "tags": [ "Images" ], "summary": "Delete an ISO image", "description": "Removes the file. An ISO currently in a server's drive cannot be deleted. Deleting waits its turn in the project image library and answers 409 server_busy with Retry-After if another image operation of the project is being submitted: without that wait an image could be inserted into a server between the check and the delete, leaving that drive pointing at nothing.", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "description": "Identifier of this call." }, "Idempotency-Replayed": { "schema": { "type": "string", "examples": [ "true" ] }, "description": "Present and set to true when this is a stored response replayed for a repeated Idempotency-Key. The work was done by the first call." } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/IsoDeleted" } } } } } }, "400": { "$ref": "#/components/responses/Problem400" }, "401": { "$ref": "#/components/responses/Problem401" }, "402": { "$ref": "#/components/responses/Problem402" }, "403": { "$ref": "#/components/responses/Problem403" }, "404": { "$ref": "#/components/responses/Problem404" }, "409": { "$ref": "#/components/responses/Problem409" }, "422": { "$ref": "#/components/responses/Problem422" }, "429": { "$ref": "#/components/responses/Problem429" }, "500": { "$ref": "#/components/responses/Problem500" }, "503": { "$ref": "#/components/responses/Problem503" }, "415": { "$ref": "#/components/responses/Problem415" } }, "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Identifier of the resource.", "schema": { "type": "string", "pattern": "^(?:uiso-\\d{1,10})$" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Repeat-safety key. Repeating the same key with the same body replays the stored response.", "schema": { "type": "string", "minLength": 8, "maxLength": 255 } } ] } }, "/networks": { "get": { "operationId": "network_list", "tags": [ "Networks" ], "summary": "List networks", "description": "Private networks in the project. Ask to skip the server count when you only need names and ranges - counting is the slow part.", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "description": "Identifier of this call." } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Network" } } } } } } }, "400": { "$ref": "#/components/responses/Problem400" }, "401": { "$ref": "#/components/responses/Problem401" }, "402": { "$ref": "#/components/responses/Problem402" }, "403": { "$ref": "#/components/responses/Problem403" }, "404": { "$ref": "#/components/responses/Problem404" }, "409": { "$ref": "#/components/responses/Problem409" }, "422": { "$ref": "#/components/responses/Problem422" }, "429": { "$ref": "#/components/responses/Problem429" }, "500": { "$ref": "#/components/responses/Problem500" }, "503": { "$ref": "#/components/responses/Problem503" } }, "parameters": [ { "name": "skip_vm_count", "in": "query", "required": false, "description": "Pass any value to skip counting attached servers - the slow part of this call.", "schema": { "type": "string" } } ] }, "post": { "operationId": "network_create", "tags": [ "Networks" ], "summary": "Create a network", "description": "Creates a private network across the project. Servers of different types can share it.", "security": [ { "bearerAuth": [] } ], "responses": { "202": { "description": "Accepted. The work continues in the background - poll the task.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "description": "Identifier of this call." }, "Idempotency-Replayed": { "schema": { "type": "string", "examples": [ "true" ] }, "description": "Present and set to true when this is a stored response replayed for a repeated Idempotency-Key. The work was done by the first call." } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "null" }, "task": { "oneOf": [ { "$ref": "#/components/schemas/Task" }, { "type": "null" } ], "description": "Null when the work was already finished inside the request." } } } } } }, "201": { "description": "Created inside the request: the network object is returned and Location points at it.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "description": "Identifier of this call." }, "Location": { "schema": { "type": "string" }, "description": "Path of the created resource." }, "Idempotency-Replayed": { "schema": { "type": "string", "examples": [ "true" ] }, "description": "Present and set to true when this is a stored response replayed for a repeated Idempotency-Key. The work was done by the first call." } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Network" }, "task": { "oneOf": [ { "$ref": "#/components/schemas/Task" }, { "type": "null" } ], "description": "Null when the work was already finished inside the request." } } } } } }, "400": { "$ref": "#/components/responses/Problem400" }, "401": { "$ref": "#/components/responses/Problem401" }, "402": { "$ref": "#/components/responses/Problem402" }, "403": { "$ref": "#/components/responses/Problem403" }, "404": { "$ref": "#/components/responses/Problem404" }, "409": { "$ref": "#/components/responses/Problem409" }, "422": { "$ref": "#/components/responses/Problem422" }, "429": { "$ref": "#/components/responses/Problem429" }, "500": { "$ref": "#/components/responses/Problem500" }, "503": { "$ref": "#/components/responses/Problem503" }, "415": { "$ref": "#/components/responses/Problem415" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 30, "pattern": "^[a-zA-Z0-9 _.\\-]+$", "description": "Your name for the network." }, "cidr": { "type": "string", "minLength": 9, "maxLength": 18, "pattern": "^(\\d{1,3}\\.){3}\\d{1,3}/\\d{1,2}$", "description": "Subnet in CIDR form, for example 10.0.0.0/24." } }, "additionalProperties": false, "required": [ "name", "cidr" ] } } } }, "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Repeat-safety key. Repeating the same key with the same body replays the stored response.", "schema": { "type": "string", "minLength": 8, "maxLength": 255 } } ] } }, "/networks/{id}": { "get": { "operationId": "network_get", "tags": [ "Networks" ], "summary": "Read a network", "description": "One private network and the router serving it, if any.", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "description": "Identifier of this call." } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Network" } } } } } }, "400": { "$ref": "#/components/responses/Problem400" }, "401": { "$ref": "#/components/responses/Problem401" }, "402": { "$ref": "#/components/responses/Problem402" }, "403": { "$ref": "#/components/responses/Problem403" }, "404": { "$ref": "#/components/responses/Problem404" }, "409": { "$ref": "#/components/responses/Problem409" }, "422": { "$ref": "#/components/responses/Problem422" }, "429": { "$ref": "#/components/responses/Problem429" }, "500": { "$ref": "#/components/responses/Problem500" }, "503": { "$ref": "#/components/responses/Problem503" } }, "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Identifier of the resource.", "schema": { "type": "integer" } }, { "name": "skip_vm_count", "in": "query", "required": false, "description": "Pass any value to skip counting attached servers.", "schema": { "type": "string" } } ] }, "patch": { "operationId": "network_update", "tags": [ "Networks" ], "summary": "Change a network", "description": "Renames the network or moves it to another subnet. Changing the subnet while servers or a router are attached is refused.", "security": [ { "bearerAuth": [] } ], "responses": { "202": { "description": "Accepted. The work continues in the background - poll the task.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "description": "Identifier of this call." }, "Idempotency-Replayed": { "schema": { "type": "string", "examples": [ "true" ] }, "description": "Present and set to true when this is a stored response replayed for a repeated Idempotency-Key. The work was done by the first call." } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Network" }, "task": { "oneOf": [ { "$ref": "#/components/schemas/Task" }, { "type": "null" } ], "description": "Null when the work was already finished inside the request." } } } } } }, "200": { "description": "Done inside the request: the task field is null, there is nothing to wait for.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "description": "Identifier of this call." }, "Idempotency-Replayed": { "schema": { "type": "string", "examples": [ "true" ] }, "description": "Present and set to true when this is a stored response replayed for a repeated Idempotency-Key. The work was done by the first call." } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Network" }, "task": { "oneOf": [ { "$ref": "#/components/schemas/Task" }, { "type": "null" } ], "description": "Null when the work was already finished inside the request." } } } } } }, "400": { "$ref": "#/components/responses/Problem400" }, "401": { "$ref": "#/components/responses/Problem401" }, "402": { "$ref": "#/components/responses/Problem402" }, "403": { "$ref": "#/components/responses/Problem403" }, "404": { "$ref": "#/components/responses/Problem404" }, "409": { "$ref": "#/components/responses/Problem409" }, "422": { "$ref": "#/components/responses/Problem422" }, "429": { "$ref": "#/components/responses/Problem429" }, "500": { "$ref": "#/components/responses/Problem500" }, "503": { "$ref": "#/components/responses/Problem503" }, "415": { "$ref": "#/components/responses/Problem415" } }, "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Identifier of the resource.", "schema": { "type": "integer" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Repeat-safety key. Repeating the same key with the same body replays the stored response.", "schema": { "type": "string", "minLength": 8, "maxLength": 255 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 30, "pattern": "^[a-zA-Z0-9 _.\\-]+$", "description": "New name for the network." }, "cidr": { "type": "string", "minLength": 9, "maxLength": 18, "pattern": "^(\\d{1,3}\\.){3}\\d{1,3}/\\d{1,2}$", "description": "New subnet. Refused while servers or a router are attached." } }, "additionalProperties": false, "anyOf": [ { "required": [ "name" ] }, { "required": [ "cidr" ] } ], "description": "At least one of these fields must be present." } } } } }, "delete": { "operationId": "network_delete", "tags": [ "Networks" ], "summary": "Delete a network", "description": "Removes the network. The project's default network cannot be deleted, and neither can one that still has servers or a router attached.", "security": [ { "bearerAuth": [] } ], "responses": { "202": { "description": "Accepted. The work continues in the background - poll the task.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "description": "Identifier of this call." }, "Idempotency-Replayed": { "schema": { "type": "string", "examples": [ "true" ] }, "description": "Present and set to true when this is a stored response replayed for a repeated Idempotency-Key. The work was done by the first call." } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Network" }, "task": { "oneOf": [ { "$ref": "#/components/schemas/Task" }, { "type": "null" } ], "description": "Null when the work was already finished inside the request." } } } } } }, "200": { "description": "Done inside the request: the task field is null, there is nothing to wait for.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "description": "Identifier of this call." }, "Idempotency-Replayed": { "schema": { "type": "string", "examples": [ "true" ] }, "description": "Present and set to true when this is a stored response replayed for a repeated Idempotency-Key. The work was done by the first call." } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Network" }, "task": { "oneOf": [ { "$ref": "#/components/schemas/Task" }, { "type": "null" } ], "description": "Null when the work was already finished inside the request." } } } } } }, "400": { "$ref": "#/components/responses/Problem400" }, "401": { "$ref": "#/components/responses/Problem401" }, "402": { "$ref": "#/components/responses/Problem402" }, "403": { "$ref": "#/components/responses/Problem403" }, "404": { "$ref": "#/components/responses/Problem404" }, "409": { "$ref": "#/components/responses/Problem409" }, "422": { "$ref": "#/components/responses/Problem422" }, "429": { "$ref": "#/components/responses/Problem429" }, "500": { "$ref": "#/components/responses/Problem500" }, "503": { "$ref": "#/components/responses/Problem503" }, "415": { "$ref": "#/components/responses/Problem415" } }, "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Identifier of the resource.", "schema": { "type": "integer" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Repeat-safety key. Repeating the same key with the same body replays the stored response.", "schema": { "type": "string", "minLength": 8, "maxLength": 255 } } ] } }, "/networks/{id}/router": { "put": { "operationId": "network_link_router", "tags": [ "Networks" ], "summary": "Attach a router", "description": "Puts a router on this network so it can hand out addresses and route traffic. A network takes one router.", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "description": "Identifier of this call." }, "Idempotency-Replayed": { "schema": { "type": "string", "examples": [ "true" ] }, "description": "Present and set to true when this is a stored response replayed for a repeated Idempotency-Key. The work was done by the first call." } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Network" } } } } } }, "400": { "$ref": "#/components/responses/Problem400" }, "401": { "$ref": "#/components/responses/Problem401" }, "402": { "$ref": "#/components/responses/Problem402" }, "403": { "$ref": "#/components/responses/Problem403" }, "404": { "$ref": "#/components/responses/Problem404" }, "409": { "$ref": "#/components/responses/Problem409" }, "422": { "$ref": "#/components/responses/Problem422" }, "429": { "$ref": "#/components/responses/Problem429" }, "500": { "$ref": "#/components/responses/Problem500" }, "503": { "$ref": "#/components/responses/Problem503" }, "415": { "$ref": "#/components/responses/Problem415" } }, "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Identifier of the resource.", "schema": { "type": "integer" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Repeat-safety key. Repeating the same key with the same body replays the stored response.", "schema": { "type": "string", "minLength": 8, "maxLength": 255 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "server_id": { "type": "integer", "minimum": 1, "description": "The router to put on this network." } }, "additionalProperties": false, "required": [ "server_id" ] } } } } }, "delete": { "operationId": "network_unlink_router", "tags": [ "Networks" ], "summary": "Detach the router", "description": "Takes the router off this network. The router's own base network cannot be detached.", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "description": "Identifier of this call." }, "Idempotency-Replayed": { "schema": { "type": "string", "examples": [ "true" ] }, "description": "Present and set to true when this is a stored response replayed for a repeated Idempotency-Key. The work was done by the first call." } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Network" } } } } } }, "400": { "$ref": "#/components/responses/Problem400" }, "401": { "$ref": "#/components/responses/Problem401" }, "402": { "$ref": "#/components/responses/Problem402" }, "403": { "$ref": "#/components/responses/Problem403" }, "404": { "$ref": "#/components/responses/Problem404" }, "409": { "$ref": "#/components/responses/Problem409" }, "422": { "$ref": "#/components/responses/Problem422" }, "429": { "$ref": "#/components/responses/Problem429" }, "500": { "$ref": "#/components/responses/Problem500" }, "503": { "$ref": "#/components/responses/Problem503" }, "415": { "$ref": "#/components/responses/Problem415" } }, "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Identifier of the resource.", "schema": { "type": "integer" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Repeat-safety key. Repeating the same key with the same body replays the stored response.", "schema": { "type": "string", "minLength": 8, "maxLength": 255 } } ] } }, "/project": { "get": { "operationId": "project_get", "tags": [ "Project" ], "summary": "Read the project", "description": "Name, identifier and status of the project this token was issued for. A suspended project still answers reads.", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "description": "Identifier of this call." } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Project" } } } } } }, "400": { "$ref": "#/components/responses/Problem400" }, "401": { "$ref": "#/components/responses/Problem401" }, "402": { "$ref": "#/components/responses/Problem402" }, "403": { "$ref": "#/components/responses/Problem403" }, "404": { "$ref": "#/components/responses/Problem404" }, "409": { "$ref": "#/components/responses/Problem409" }, "422": { "$ref": "#/components/responses/Problem422" }, "429": { "$ref": "#/components/responses/Problem429" }, "500": { "$ref": "#/components/responses/Problem500" }, "503": { "$ref": "#/components/responses/Problem503" } } }, "patch": { "operationId": "project_update", "tags": [ "Project" ], "summary": "Rename the project", "description": "Changes the name you see in the client area. Does not touch anything inside the project.", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "description": "Identifier of this call." }, "Idempotency-Replayed": { "schema": { "type": "string", "examples": [ "true" ] }, "description": "Present and set to true when this is a stored response replayed for a repeated Idempotency-Key. The work was done by the first call." } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Project" } } } } } }, "400": { "$ref": "#/components/responses/Problem400" }, "401": { "$ref": "#/components/responses/Problem401" }, "402": { "$ref": "#/components/responses/Problem402" }, "403": { "$ref": "#/components/responses/Problem403" }, "404": { "$ref": "#/components/responses/Problem404" }, "409": { "$ref": "#/components/responses/Problem409" }, "422": { "$ref": "#/components/responses/Problem422" }, "429": { "$ref": "#/components/responses/Problem429" }, "500": { "$ref": "#/components/responses/Problem500" }, "503": { "$ref": "#/components/responses/Problem503" }, "415": { "$ref": "#/components/responses/Problem415" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 64, "pattern": "^[a-zA-Z0-9 _.\\-]+$", "description": "New name for the project." } }, "additionalProperties": false, "required": [ "name" ] } } } }, "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Repeat-safety key. Repeating the same key with the same body replays the stored response.", "schema": { "type": "string", "minLength": 8, "maxLength": 255 } } ] } }, "/project/backup-policy": { "get": { "operationId": "project_backup_policy_get", "tags": [ "Project" ], "summary": "Read the project backup default", "description": "Whether servers created from now on get backups switched on. Servers that already set their own policy keep it.", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "description": "Identifier of this call." } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/ProjectBackupPolicy" } } } } } }, "400": { "$ref": "#/components/responses/Problem400" }, "401": { "$ref": "#/components/responses/Problem401" }, "402": { "$ref": "#/components/responses/Problem402" }, "403": { "$ref": "#/components/responses/Problem403" }, "404": { "$ref": "#/components/responses/Problem404" }, "409": { "$ref": "#/components/responses/Problem409" }, "422": { "$ref": "#/components/responses/Problem422" }, "429": { "$ref": "#/components/responses/Problem429" }, "500": { "$ref": "#/components/responses/Problem500" }, "503": { "$ref": "#/components/responses/Problem503" } } }, "put": { "operationId": "project_backup_policy_set", "tags": [ "Project" ], "summary": "Set the project backup default", "description": "Applies to servers created afterwards, and to existing servers that never set a policy of their own. A server with its own policy is left alone.", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "description": "Identifier of this call." }, "Idempotency-Replayed": { "schema": { "type": "string", "examples": [ "true" ] }, "description": "Present and set to true when this is a stored response replayed for a repeated Idempotency-Key. The work was done by the first call." } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/ProjectBackupPolicy" } } } } } }, "400": { "$ref": "#/components/responses/Problem400" }, "401": { "$ref": "#/components/responses/Problem401" }, "402": { "$ref": "#/components/responses/Problem402" }, "403": { "$ref": "#/components/responses/Problem403" }, "404": { "$ref": "#/components/responses/Problem404" }, "409": { "$ref": "#/components/responses/Problem409" }, "422": { "$ref": "#/components/responses/Problem422" }, "429": { "$ref": "#/components/responses/Problem429" }, "500": { "$ref": "#/components/responses/Problem500" }, "503": { "$ref": "#/components/responses/Problem503" }, "415": { "$ref": "#/components/responses/Problem415" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "enabled": { "type": "boolean", "description": "Whether servers created from now on get backups." } }, "additionalProperties": false, "required": [ "enabled" ] } } } }, "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Repeat-safety key. Repeating the same key with the same body replays the stored response.", "schema": { "type": "string", "minLength": 8, "maxLength": 255 } } ] } }, "/project/costs": { "get": { "operationId": "project_costs_get", "tags": [ "Project" ], "summary": "Read charges", "description": "What the project has run up over a period, optionally broken into daily or hourly buckets. Figures are an estimate of usage, not an invoice: amounts are strings so nothing is rounded on the way to you.", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "description": "Identifier of this call." } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Costs" } } } } } }, "400": { "$ref": "#/components/responses/Problem400" }, "401": { "$ref": "#/components/responses/Problem401" }, "402": { "$ref": "#/components/responses/Problem402" }, "403": { "$ref": "#/components/responses/Problem403" }, "404": { "$ref": "#/components/responses/Problem404" }, "409": { "$ref": "#/components/responses/Problem409" }, "422": { "$ref": "#/components/responses/Problem422" }, "429": { "$ref": "#/components/responses/Problem429" }, "500": { "$ref": "#/components/responses/Problem500" }, "503": { "$ref": "#/components/responses/Problem503" } }, "parameters": [ { "name": "start", "in": "query", "required": false, "description": "Start of the window, RFC 3339 in UTC. Included. Give it together with end.", "schema": { "type": "string", "format": "date-time" } }, { "name": "end", "in": "query", "required": false, "description": "End of the window, RFC 3339 in UTC. Excluded. Give it together with start.", "schema": { "type": "string", "format": "date-time" } }, { "name": "granularity", "in": "query", "required": false, "description": "none returns one total; daily and hourly split the window into buckets.", "schema": { "type": "string", "enum": [ "none", "daily", "hourly" ], "default": "none" } } ] } }, "/server-images": { "get": { "operationId": "server_image_list", "tags": [ "Images" ], "summary": "List server images", "description": "Images taken from your own servers.", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "description": "Identifier of this call." } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/ServerImage" } } } } } } }, "400": { "$ref": "#/components/responses/Problem400" }, "401": { "$ref": "#/components/responses/Problem401" }, "402": { "$ref": "#/components/responses/Problem402" }, "403": { "$ref": "#/components/responses/Problem403" }, "404": { "$ref": "#/components/responses/Problem404" }, "409": { "$ref": "#/components/responses/Problem409" }, "422": { "$ref": "#/components/responses/Problem422" }, "429": { "$ref": "#/components/responses/Problem429" }, "500": { "$ref": "#/components/responses/Problem500" }, "503": { "$ref": "#/components/responses/Problem503" } } }, "post": { "operationId": "server_image_create", "tags": [ "Images" ], "summary": "Take an image of a server", "description": "Captures a server as a reusable image. The image can only build servers of the same type. Taking an image waits its turn in the project image library and answers 409 server_busy with Retry-After if another image operation of the project is being submitted.", "security": [ { "bearerAuth": [] } ], "responses": { "202": { "description": "Accepted. The work continues in the background - poll the task.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "description": "Identifier of this call." }, "Location": { "schema": { "type": "string" }, "description": "Path of the created resource." }, "Idempotency-Replayed": { "schema": { "type": "string", "examples": [ "true" ] }, "description": "Present and set to true when this is a stored response replayed for a repeated Idempotency-Key. The work was done by the first call." } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/ServerImage" }, "task": { "oneOf": [ { "$ref": "#/components/schemas/Task" }, { "type": "null" } ], "description": "Null when the work was already finished inside the request." } } } } } }, "200": { "description": "Done inside the request: the task field is null, there is nothing to wait for.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "description": "Identifier of this call." }, "Location": { "schema": { "type": "string" }, "description": "Path of the created resource." }, "Idempotency-Replayed": { "schema": { "type": "string", "examples": [ "true" ] }, "description": "Present and set to true when this is a stored response replayed for a repeated Idempotency-Key. The work was done by the first call." } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/ServerImage" }, "task": { "oneOf": [ { "$ref": "#/components/schemas/Task" }, { "type": "null" } ], "description": "Null when the work was already finished inside the request." } } } } } }, "400": { "$ref": "#/components/responses/Problem400" }, "401": { "$ref": "#/components/responses/Problem401" }, "402": { "$ref": "#/components/responses/Problem402" }, "403": { "$ref": "#/components/responses/Problem403" }, "404": { "$ref": "#/components/responses/Problem404" }, "409": { "$ref": "#/components/responses/Problem409" }, "422": { "$ref": "#/components/responses/Problem422" }, "429": { "$ref": "#/components/responses/Problem429" }, "500": { "$ref": "#/components/responses/Problem500" }, "503": { "$ref": "#/components/responses/Problem503" }, "415": { "$ref": "#/components/responses/Problem415" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "source_server_id": { "type": "integer", "minimum": 1, "description": "The server to capture." }, "name": { "type": "string", "minLength": 1, "maxLength": 50, "description": "Your name for the image." }, "description": { "type": "string", "maxLength": 1000, "description": "Free text for your own reference." } }, "additionalProperties": false, "required": [ "source_server_id", "name" ] } } } }, "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Repeat-safety key. Repeating the same key with the same body replays the stored response.", "schema": { "type": "string", "minLength": 8, "maxLength": 255 } } ] } }, "/server-images/{id}": { "get": { "operationId": "server_image_get", "tags": [ "Images" ], "summary": "Read a server image", "description": "One image and the server it was taken from.", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "description": "Identifier of this call." } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/ServerImage" } } } } } }, "400": { "$ref": "#/components/responses/Problem400" }, "401": { "$ref": "#/components/responses/Problem401" }, "402": { "$ref": "#/components/responses/Problem402" }, "403": { "$ref": "#/components/responses/Problem403" }, "404": { "$ref": "#/components/responses/Problem404" }, "409": { "$ref": "#/components/responses/Problem409" }, "422": { "$ref": "#/components/responses/Problem422" }, "429": { "$ref": "#/components/responses/Problem429" }, "500": { "$ref": "#/components/responses/Problem500" }, "503": { "$ref": "#/components/responses/Problem503" } }, "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Identifier of the resource.", "schema": { "type": "string", "pattern": "^(?:utpl-\\d{1,10})$" } } ] }, "delete": { "operationId": "server_image_delete", "tags": [ "Images" ], "summary": "Delete a server image", "description": "Removes the image. Servers already built from it are unaffected, but they can no longer be reinstalled from it. Deleting waits its turn in the project image library and answers 409 server_busy with Retry-After if another image operation of the project is being submitted.", "security": [ { "bearerAuth": [] } ], "responses": { "202": { "description": "Accepted. The work continues in the background - poll the task.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "description": "Identifier of this call." }, "Idempotency-Replayed": { "schema": { "type": "string", "examples": [ "true" ] }, "description": "Present and set to true when this is a stored response replayed for a repeated Idempotency-Key. The work was done by the first call." } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/ServerImageDeleted" }, "task": { "oneOf": [ { "$ref": "#/components/schemas/Task" }, { "type": "null" } ], "description": "Null when the work was already finished inside the request." } } } } } }, "200": { "description": "Done inside the request: the task field is null, there is nothing to wait for.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "description": "Identifier of this call." }, "Idempotency-Replayed": { "schema": { "type": "string", "examples": [ "true" ] }, "description": "Present and set to true when this is a stored response replayed for a repeated Idempotency-Key. The work was done by the first call." } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/ServerImageDeleted" }, "task": { "oneOf": [ { "$ref": "#/components/schemas/Task" }, { "type": "null" } ], "description": "Null when the work was already finished inside the request." } } } } } }, "400": { "$ref": "#/components/responses/Problem400" }, "401": { "$ref": "#/components/responses/Problem401" }, "402": { "$ref": "#/components/responses/Problem402" }, "403": { "$ref": "#/components/responses/Problem403" }, "404": { "$ref": "#/components/responses/Problem404" }, "409": { "$ref": "#/components/responses/Problem409" }, "422": { "$ref": "#/components/responses/Problem422" }, "429": { "$ref": "#/components/responses/Problem429" }, "500": { "$ref": "#/components/responses/Problem500" }, "503": { "$ref": "#/components/responses/Problem503" }, "415": { "$ref": "#/components/responses/Problem415" } }, "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Identifier of the resource.", "schema": { "type": "string", "pattern": "^(?:utpl-\\d{1,10})$" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Repeat-safety key. Repeating the same key with the same body replays the stored response.", "schema": { "type": "string", "minLength": 8, "maxLength": 255 } } ] } }, "/server-types": { "get": { "operationId": "server_type_list", "tags": [ "Server types" ], "summary": "List server types", "description": "Kinds of server you can create. The pricing mode tells you how a type is sized: by plan, by sliders, or fixed with the GPU package that comes with it. The gpu flag marks types sold with graphics cards - read the pricing of such a type to see the packages or the card models it offers.", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "description": "Identifier of this call." } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/ServerType" } } } } } } }, "400": { "$ref": "#/components/responses/Problem400" }, "401": { "$ref": "#/components/responses/Problem401" }, "402": { "$ref": "#/components/responses/Problem402" }, "403": { "$ref": "#/components/responses/Problem403" }, "404": { "$ref": "#/components/responses/Problem404" }, "409": { "$ref": "#/components/responses/Problem409" }, "422": { "$ref": "#/components/responses/Problem422" }, "429": { "$ref": "#/components/responses/Problem429" }, "500": { "$ref": "#/components/responses/Problem500" }, "503": { "$ref": "#/components/responses/Problem503" } } } }, "/server-types/{id}/images": { "get": { "operationId": "server_type_image_list", "tags": [ "Server types" ], "summary": "List images for a type", "description": "Images this server type can build from, with the minimum size each needs and whether it carries a paid licence.", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "description": "Identifier of this call." } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Image" } } } } } } }, "400": { "$ref": "#/components/responses/Problem400" }, "401": { "$ref": "#/components/responses/Problem401" }, "402": { "$ref": "#/components/responses/Problem402" }, "403": { "$ref": "#/components/responses/Problem403" }, "404": { "$ref": "#/components/responses/Problem404" }, "409": { "$ref": "#/components/responses/Problem409" }, "422": { "$ref": "#/components/responses/Problem422" }, "429": { "$ref": "#/components/responses/Problem429" }, "500": { "$ref": "#/components/responses/Problem500" }, "503": { "$ref": "#/components/responses/Problem503" } }, "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Identifier of the resource.", "schema": { "type": "integer" } } ] } }, "/server-types/{id}/pricing": { "get": { "operationId": "server_type_pricing_get", "tags": [ "Server types" ], "summary": "Read prices for a type", "description": "Hourly rates for what this type bills, the plans it sells, the upper bounds of its sliders and, on types with graphics cards, the GPU packages or the card models on offer. Monthly figures are the hourly rate over 720 hours, for comparison.", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "description": "Identifier of this call." } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Pricing" } } } } } }, "400": { "$ref": "#/components/responses/Problem400" }, "401": { "$ref": "#/components/responses/Problem401" }, "402": { "$ref": "#/components/responses/Problem402" }, "403": { "$ref": "#/components/responses/Problem403" }, "404": { "$ref": "#/components/responses/Problem404" }, "409": { "$ref": "#/components/responses/Problem409" }, "422": { "$ref": "#/components/responses/Problem422" }, "429": { "$ref": "#/components/responses/Problem429" }, "500": { "$ref": "#/components/responses/Problem500" }, "503": { "$ref": "#/components/responses/Problem503" } }, "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Identifier of the resource.", "schema": { "type": "integer" } } ] } }, "/servers": { "get": { "operationId": "server_list", "tags": [ "Servers" ], "summary": "List servers", "description": "Every server in the project, routers included. Sizes here come from our own records and can lag the hypervisor by up to a minute after a change; read one server for the fresher figure.", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "description": "Identifier of this call." } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Server" } } } } } } }, "400": { "$ref": "#/components/responses/Problem400" }, "401": { "$ref": "#/components/responses/Problem401" }, "402": { "$ref": "#/components/responses/Problem402" }, "403": { "$ref": "#/components/responses/Problem403" }, "404": { "$ref": "#/components/responses/Problem404" }, "409": { "$ref": "#/components/responses/Problem409" }, "422": { "$ref": "#/components/responses/Problem422" }, "429": { "$ref": "#/components/responses/Problem429" }, "500": { "$ref": "#/components/responses/Problem500" }, "503": { "$ref": "#/components/responses/Problem503" } } }, "post": { "operationId": "server_create", "tags": [ "Servers" ], "summary": "Create a server", "description": "What the body must carry depends on the server type: types sold as plans take plan_id and refuse cores, memory and disk; types sized by sliders take those three and refuse plan_id. Read the type first if you do not know which it is. The response carries the new server's identifier immediately, and a task to wait on.", "security": [ { "bearerAuth": [] } ], "responses": { "202": { "description": "Accepted. The work continues in the background - poll the task.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "description": "Identifier of this call." }, "Location": { "schema": { "type": "string" }, "description": "Path of the created resource." }, "Idempotency-Replayed": { "schema": { "type": "string", "examples": [ "true" ] }, "description": "Present and set to true when this is a stored response replayed for a repeated Idempotency-Key. The work was done by the first call." } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Server" }, "task": { "oneOf": [ { "$ref": "#/components/schemas/Task" }, { "type": "null" } ], "description": "Null when the work was already finished inside the request." } } } } } }, "400": { "$ref": "#/components/responses/Problem400" }, "401": { "$ref": "#/components/responses/Problem401" }, "402": { "$ref": "#/components/responses/Problem402" }, "403": { "$ref": "#/components/responses/Problem403" }, "404": { "$ref": "#/components/responses/Problem404" }, "409": { "$ref": "#/components/responses/Problem409" }, "422": { "$ref": "#/components/responses/Problem422" }, "429": { "$ref": "#/components/responses/Problem429" }, "500": { "$ref": "#/components/responses/Problem500" }, "503": { "$ref": "#/components/responses/Problem503" }, "415": { "$ref": "#/components/responses/Problem415" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 64, "pattern": "^[A-Za-z0-9]([A-Za-z0-9.-]{0,62}[A-Za-z0-9])?$", "description": "Hostname for the server. Required for every image except a router, which the platform names itself." }, "server_type_id": { "type": "integer", "minimum": 1, "description": "Which kind of server to create. List the types to see what is available." }, "image": { "type": "string", "minLength": 4, "maxLength": 64, "pattern": "^[A-Za-z0-9_-]+$", "description": "Identifier of the image to build from, exactly as the type's image listing reports it. That listing also contains your own uploaded ISO images (type useriso, identified as uiso-N), and a server cannot be CREATED from one of those - such a request is refused with image_not_supported. An ISO installs a machine rather than builds one: create from an operating system image and insert the ISO into the drive afterwards." }, "cores": { "type": "integer", "minimum": 1, "maximum": 1024, "description": "Virtual cores. Only for types sized by sliders - a type sold as plans refuses this field." }, "memory_mb": { "type": "integer", "minimum": 1024, "maximum": 4194304, "multipleOf": 1024, "description": "Memory in megabytes. Slider types only." }, "disk_gb": { "type": "integer", "minimum": 1, "maximum": 65536, "description": "System disk in gigabytes. Slider types only." }, "plan_id": { "type": "integer", "minimum": 1, "description": "The plan to buy. Required on types sold as plans, refused on slider types." }, "public_ipv4": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 1 }, "new": { "type": "boolean" }, "reuse": { "type": "boolean" } }, "additionalProperties": false, "description": "Give {\"id\": N} to attach an address you already hold, {\"new\": true} to take a fresh one, or {\"reuse\": true} to take one of YOUR unused addresses - if none is free, a new one is allocated and billed. Reuse picks the free address with the lowest id, from the pools of the server type you are creating on. The three are mutually exclusive; a body that carries more than one is rejected. Omit the field for a server with no public address." }, "networks": { "type": "array", "items": { "type": "integer", "minimum": 1 }, "maxItems": 8, "description": "Private networks to attach the server to, by identifier." }, "ssh_keys": { "type": "array", "items": { "type": "integer", "minimum": 1 }, "maxItems": 20, "description": "Keys from your account pool to install in the guest. Either this field or password must be present - a server with neither is refused as credentials_required. Neither belongs on a router image: both are refused as router_field_not_supported." }, "password": { "type": "string", "minLength": 12, "maxLength": 64, "description": "Administrator password inside the guest. Latin letters and digits only, 12 to 64 characters, with at least one uppercase letter, one lowercase letter and one digit; any other character is refused as invalid_password. Omit and one is generated, but then send ssh_keys: a server with neither is refused as credentials_required, because this API never returns a generated password. A router image takes neither field: both are refused as router_field_not_supported, because a router is entered through its own management key." }, "accept_license": { "type": "boolean", "description": "Required for images that carry a paid licence, and refused for images that do not." }, "setup": { "type": "object", "additionalProperties": { "type": "string" }, "maxProperties": 20, "propertyNames": { "pattern": "^[a-z0-9_]{1,40}$" }, "description": "Application settings for images that ask for them. Which keys an image expects is listed with the image." }, "gpu_package": { "type": [ "string", "null" ], "maxLength": 40, "pattern": "^[A-Za-z0-9_-]*$", "description": "The GPU package to buy on a type sold as one: it defines the card, the cores, the memory and the system disk together. Required on such a type, refused on the others, and the size fields are refused with it. Take the value from the key field of gpu_packages in the type's pricing. A server of this kind never changes size afterwards." }, "gpus": { "type": "array", "items": { "type": "object", "properties": { "model": { "type": "string", "minLength": 1, "maxLength": 40, "pattern": "^[A-Za-z0-9_-]+$" }, "count": { "type": "integer", "minimum": 1, "maximum": 16 } }, "additionalProperties": false, "required": [ "model", "count" ] }, "maxItems": 16, "description": "Graphics cards for a type sold with cards you pick yourself: one entry per model, with how many of that model you want. Required on such a type, refused on the others. Take model from the key field of gpu_models in the type's pricing; naming the same model twice adds the counts up. The set cannot be changed afterwards - a different set of cards means a different server." }, "disk_type": { "oneOf": [ { "type": "string", "enum": [ "local", "ceph" ], "maxLength": 8, "pattern": "^(local|ceph)?$" }, { "type": "null" } ], "description": "Storage class of the system disk on a type with graphics cards: local for the disk of the host itself, ceph for shared storage. Defaults to local, and is refused on types where the class is part of the type. The disk limit of each class is in the type's pricing, but the limits do NOT tell you whether a class is available: a type can carry a Ceph limit and still refuse ceph. Availability is a property of the type itself, and it is not published - a type that only ever has a local system disk answers disk_type_not_available." } }, "additionalProperties": false, "required": [ "server_type_id", "image" ] } } } }, "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Repeat-safety key. Repeating the same key with the same body replays the stored response.", "schema": { "type": "string", "minLength": 8, "maxLength": 255 } } ] } }, "/servers/{id}": { "get": { "operationId": "server_get", "tags": [ "Servers" ], "summary": "Read a server", "description": "Full state of one server, its public addresses and its labels.", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "description": "Identifier of this call." } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Server" } } } } } }, "400": { "$ref": "#/components/responses/Problem400" }, "401": { "$ref": "#/components/responses/Problem401" }, "402": { "$ref": "#/components/responses/Problem402" }, "403": { "$ref": "#/components/responses/Problem403" }, "404": { "$ref": "#/components/responses/Problem404" }, "409": { "$ref": "#/components/responses/Problem409" }, "422": { "$ref": "#/components/responses/Problem422" }, "429": { "$ref": "#/components/responses/Problem429" }, "500": { "$ref": "#/components/responses/Problem500" }, "503": { "$ref": "#/components/responses/Problem503" } }, "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Identifier of the resource.", "schema": { "type": "integer" } } ] }, "patch": { "operationId": "server_update", "tags": [ "Servers" ], "summary": "Change a server", "description": "Renames the server, changes its cores and memory, moves it to another plan, or grows its system disk - one kind of change per request. Growing a disk and resizing memory in one call is refused, so that a partial failure cannot leave you guessing which half applied.", "security": [ { "bearerAuth": [] } ], "responses": { "202": { "description": "Accepted. The work continues in the background - poll the task.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "description": "Identifier of this call." }, "Idempotency-Replayed": { "schema": { "type": "string", "examples": [ "true" ] }, "description": "Present and set to true when this is a stored response replayed for a repeated Idempotency-Key. The work was done by the first call." } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Server" }, "task": { "oneOf": [ { "$ref": "#/components/schemas/Task" }, { "type": "null" } ], "description": "Null when the work was already finished inside the request." } } } } } }, "200": { "description": "Done inside the request: the task field is null, there is nothing to wait for.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "description": "Identifier of this call." }, "Idempotency-Replayed": { "schema": { "type": "string", "examples": [ "true" ] }, "description": "Present and set to true when this is a stored response replayed for a repeated Idempotency-Key. The work was done by the first call." } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Server" }, "task": { "oneOf": [ { "$ref": "#/components/schemas/Task" }, { "type": "null" } ], "description": "Null when the work was already finished inside the request." } } } } } }, "400": { "$ref": "#/components/responses/Problem400" }, "401": { "$ref": "#/components/responses/Problem401" }, "402": { "$ref": "#/components/responses/Problem402" }, "403": { "$ref": "#/components/responses/Problem403" }, "404": { "$ref": "#/components/responses/Problem404" }, "409": { "$ref": "#/components/responses/Problem409" }, "422": { "$ref": "#/components/responses/Problem422" }, "429": { "$ref": "#/components/responses/Problem429" }, "500": { "$ref": "#/components/responses/Problem500" }, "503": { "$ref": "#/components/responses/Problem503" }, "415": { "$ref": "#/components/responses/Problem415" } }, "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Identifier of the resource.", "schema": { "type": "integer" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Repeat-safety key. Repeating the same key with the same body replays the stored response.", "schema": { "type": "string", "minLength": 8, "maxLength": 255 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 64, "description": "New hostname. Routers cannot be renamed." }, "cores": { "type": "integer", "minimum": 1, "maximum": 1024, "description": "New core count. Slider types only." }, "memory_mb": { "type": "integer", "minimum": 1024, "maximum": 4194304, "multipleOf": 1024, "description": "New memory in megabytes. Slider types only." }, "disk_gb": { "type": "integer", "minimum": 1, "maximum": 65536, "description": "New system disk size. It can only grow." }, "plan_id": { "type": "integer", "minimum": 1, "description": "Move the server to this plan. Plan types only." } }, "additionalProperties": false, "anyOf": [ { "required": [ "name" ] }, { "required": [ "cores" ] }, { "required": [ "memory_mb" ] }, { "required": [ "disk_gb" ] }, { "required": [ "plan_id" ] } ], "description": "At least one of these fields must be present." } } } } }, "delete": { "operationId": "server_delete", "tags": [ "Servers" ], "summary": "Delete a server", "description": "Destroys the server and its disks. Public addresses are not released: they stay with the project and keep being billed, and the response lists them so you can release them deliberately.", "security": [ { "bearerAuth": [] } ], "responses": { "202": { "description": "Accepted. The work continues in the background - poll the task.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "description": "Identifier of this call." }, "Idempotency-Replayed": { "schema": { "type": "string", "examples": [ "true" ] }, "description": "Present and set to true when this is a stored response replayed for a repeated Idempotency-Key. The work was done by the first call." } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/ServerDeleted" }, "task": { "oneOf": [ { "$ref": "#/components/schemas/Task" }, { "type": "null" } ], "description": "Null when the work was already finished inside the request." } } } } } }, "400": { "$ref": "#/components/responses/Problem400" }, "401": { "$ref": "#/components/responses/Problem401" }, "402": { "$ref": "#/components/responses/Problem402" }, "403": { "$ref": "#/components/responses/Problem403" }, "404": { "$ref": "#/components/responses/Problem404" }, "409": { "$ref": "#/components/responses/Problem409" }, "422": { "$ref": "#/components/responses/Problem422" }, "429": { "$ref": "#/components/responses/Problem429" }, "500": { "$ref": "#/components/responses/Problem500" }, "503": { "$ref": "#/components/responses/Problem503" }, "415": { "$ref": "#/components/responses/Problem415" } }, "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Identifier of the resource.", "schema": { "type": "integer" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Repeat-safety key. Repeating the same key with the same body replays the stored response.", "schema": { "type": "string", "minLength": 8, "maxLength": 255 } } ] } }, "/servers/{id}/actions/add-ssh-keys": { "post": { "operationId": "server_add_ssh_keys", "tags": [ "Servers" ], "summary": "Add SSH keys to a server", "description": "Adds keys from your account pool to the server's authorized keys. It adds - it never removes, and keys already installed by hand inside the guest are left alone. Send every key you want the server to keep: the recorded set becomes exactly what you send, and that recorded set is what a reinstall restores.", "security": [ { "bearerAuth": [] } ], "responses": { "202": { "description": "Accepted. The work continues in the background - poll the task.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "description": "Identifier of this call." }, "Idempotency-Replayed": { "schema": { "type": "string", "examples": [ "true" ] }, "description": "Present and set to true when this is a stored response replayed for a repeated Idempotency-Key. The work was done by the first call." } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "null" }, "task": { "oneOf": [ { "$ref": "#/components/schemas/Task" }, { "type": "null" } ], "description": "Null when the work was already finished inside the request." } } } } } }, "200": { "description": "Done inside the request: the task field is null, there is nothing to wait for.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "description": "Identifier of this call." }, "Idempotency-Replayed": { "schema": { "type": "string", "examples": [ "true" ] }, "description": "Present and set to true when this is a stored response replayed for a repeated Idempotency-Key. The work was done by the first call." } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "null" }, "task": { "oneOf": [ { "$ref": "#/components/schemas/Task" }, { "type": "null" } ], "description": "Null when the work was already finished inside the request." } } } } } }, "400": { "$ref": "#/components/responses/Problem400" }, "401": { "$ref": "#/components/responses/Problem401" }, "402": { "$ref": "#/components/responses/Problem402" }, "403": { "$ref": "#/components/responses/Problem403" }, "404": { "$ref": "#/components/responses/Problem404" }, "409": { "$ref": "#/components/responses/Problem409" }, "422": { "$ref": "#/components/responses/Problem422" }, "429": { "$ref": "#/components/responses/Problem429" }, "500": { "$ref": "#/components/responses/Problem500" }, "503": { "$ref": "#/components/responses/Problem503" }, "415": { "$ref": "#/components/responses/Problem415" } }, "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Identifier of the resource.", "schema": { "type": "integer" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Repeat-safety key. Repeating the same key with the same body replays the stored response.", "schema": { "type": "string", "minLength": 8, "maxLength": 255 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "ssh_keys": { "type": "array", "items": { "type": "integer", "minimum": 1 }, "maxItems": 20, "description": "Keys from your account pool. Send every key the server should keep, not just the new ones." } }, "additionalProperties": false, "required": [ "ssh_keys" ] } } } } } }, "/servers/{id}/actions/power-off": { "post": { "operationId": "server_power_off", "tags": [ "Servers" ], "summary": "Power off", "description": "Cuts the power without telling the guest - the equivalent of pulling the plug. Use shutdown when the guest holds data in memory.", "security": [ { "bearerAuth": [] } ], "responses": { "202": { "description": "Accepted. The work continues in the background - poll the task.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "description": "Identifier of this call." }, "Idempotency-Replayed": { "schema": { "type": "string", "examples": [ "true" ] }, "description": "Present and set to true when this is a stored response replayed for a repeated Idempotency-Key. The work was done by the first call." } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "null" }, "task": { "oneOf": [ { "$ref": "#/components/schemas/Task" }, { "type": "null" } ], "description": "Null when the work was already finished inside the request." } } } } } }, "200": { "description": "Done inside the request: the task field is null, there is nothing to wait for.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "description": "Identifier of this call." }, "Idempotency-Replayed": { "schema": { "type": "string", "examples": [ "true" ] }, "description": "Present and set to true when this is a stored response replayed for a repeated Idempotency-Key. The work was done by the first call." } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "null" }, "task": { "oneOf": [ { "$ref": "#/components/schemas/Task" }, { "type": "null" } ], "description": "Null when the work was already finished inside the request." } } } } } }, "400": { "$ref": "#/components/responses/Problem400" }, "401": { "$ref": "#/components/responses/Problem401" }, "402": { "$ref": "#/components/responses/Problem402" }, "403": { "$ref": "#/components/responses/Problem403" }, "404": { "$ref": "#/components/responses/Problem404" }, "409": { "$ref": "#/components/responses/Problem409" }, "422": { "$ref": "#/components/responses/Problem422" }, "429": { "$ref": "#/components/responses/Problem429" }, "500": { "$ref": "#/components/responses/Problem500" }, "503": { "$ref": "#/components/responses/Problem503" }, "415": { "$ref": "#/components/responses/Problem415" } }, "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Identifier of the resource.", "schema": { "type": "integer" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Repeat-safety key. Repeating the same key with the same body replays the stored response.", "schema": { "type": "string", "minLength": 8, "maxLength": 255 } } ] } }, "/servers/{id}/actions/power-on": { "post": { "operationId": "server_power_on", "tags": [ "Servers" ], "summary": "Power on", "description": "Starts a stopped server. Starting a running server is accepted and changes nothing.", "security": [ { "bearerAuth": [] } ], "responses": { "202": { "description": "Accepted. The work continues in the background - poll the task.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "description": "Identifier of this call." }, "Idempotency-Replayed": { "schema": { "type": "string", "examples": [ "true" ] }, "description": "Present and set to true when this is a stored response replayed for a repeated Idempotency-Key. The work was done by the first call." } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "null" }, "task": { "oneOf": [ { "$ref": "#/components/schemas/Task" }, { "type": "null" } ], "description": "Null when the work was already finished inside the request." } } } } } }, "200": { "description": "Done inside the request: the task field is null, there is nothing to wait for.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "description": "Identifier of this call." }, "Idempotency-Replayed": { "schema": { "type": "string", "examples": [ "true" ] }, "description": "Present and set to true when this is a stored response replayed for a repeated Idempotency-Key. The work was done by the first call." } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "null" }, "task": { "oneOf": [ { "$ref": "#/components/schemas/Task" }, { "type": "null" } ], "description": "Null when the work was already finished inside the request." } } } } } }, "400": { "$ref": "#/components/responses/Problem400" }, "401": { "$ref": "#/components/responses/Problem401" }, "402": { "$ref": "#/components/responses/Problem402" }, "403": { "$ref": "#/components/responses/Problem403" }, "404": { "$ref": "#/components/responses/Problem404" }, "409": { "$ref": "#/components/responses/Problem409" }, "422": { "$ref": "#/components/responses/Problem422" }, "429": { "$ref": "#/components/responses/Problem429" }, "500": { "$ref": "#/components/responses/Problem500" }, "503": { "$ref": "#/components/responses/Problem503" }, "415": { "$ref": "#/components/responses/Problem415" } }, "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Identifier of the resource.", "schema": { "type": "integer" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Repeat-safety key. Repeating the same key with the same body replays the stored response.", "schema": { "type": "string", "minLength": 8, "maxLength": 255 } } ] } }, "/servers/{id}/actions/reboot": { "post": { "operationId": "server_reboot", "tags": [ "Servers" ], "summary": "Reboot", "description": "Asks the guest to restart cleanly.", "security": [ { "bearerAuth": [] } ], "responses": { "202": { "description": "Accepted. The work continues in the background - poll the task.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "description": "Identifier of this call." }, "Idempotency-Replayed": { "schema": { "type": "string", "examples": [ "true" ] }, "description": "Present and set to true when this is a stored response replayed for a repeated Idempotency-Key. The work was done by the first call." } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "null" }, "task": { "oneOf": [ { "$ref": "#/components/schemas/Task" }, { "type": "null" } ], "description": "Null when the work was already finished inside the request." } } } } } }, "200": { "description": "Done inside the request: the task field is null, there is nothing to wait for.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "description": "Identifier of this call." }, "Idempotency-Replayed": { "schema": { "type": "string", "examples": [ "true" ] }, "description": "Present and set to true when this is a stored response replayed for a repeated Idempotency-Key. The work was done by the first call." } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "null" }, "task": { "oneOf": [ { "$ref": "#/components/schemas/Task" }, { "type": "null" } ], "description": "Null when the work was already finished inside the request." } } } } } }, "400": { "$ref": "#/components/responses/Problem400" }, "401": { "$ref": "#/components/responses/Problem401" }, "402": { "$ref": "#/components/responses/Problem402" }, "403": { "$ref": "#/components/responses/Problem403" }, "404": { "$ref": "#/components/responses/Problem404" }, "409": { "$ref": "#/components/responses/Problem409" }, "422": { "$ref": "#/components/responses/Problem422" }, "429": { "$ref": "#/components/responses/Problem429" }, "500": { "$ref": "#/components/responses/Problem500" }, "503": { "$ref": "#/components/responses/Problem503" }, "415": { "$ref": "#/components/responses/Problem415" } }, "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Identifier of the resource.", "schema": { "type": "integer" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Repeat-safety key. Repeating the same key with the same body replays the stored response.", "schema": { "type": "string", "minLength": 8, "maxLength": 255 } } ] } }, "/servers/{id}/actions/rebuild": { "post": { "operationId": "server_rebuild", "tags": [ "Servers" ], "summary": "Reinstall the system", "description": "Reinstalls the same image the server already runs - the image is not a parameter, because you have no choice of a different one here. Everything on the system disk is lost. A Windows image needs accept_license, as when creating.", "security": [ { "bearerAuth": [] } ], "responses": { "202": { "description": "Accepted. The work continues in the background - poll the task.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "description": "Identifier of this call." }, "Idempotency-Replayed": { "schema": { "type": "string", "examples": [ "true" ] }, "description": "Present and set to true when this is a stored response replayed for a repeated Idempotency-Key. The work was done by the first call." } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "null" }, "task": { "oneOf": [ { "$ref": "#/components/schemas/Task" }, { "type": "null" } ], "description": "Null when the work was already finished inside the request." } } } } } }, "200": { "description": "Done inside the request: the task field is null, there is nothing to wait for.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "description": "Identifier of this call." }, "Idempotency-Replayed": { "schema": { "type": "string", "examples": [ "true" ] }, "description": "Present and set to true when this is a stored response replayed for a repeated Idempotency-Key. The work was done by the first call." } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "null" }, "task": { "oneOf": [ { "$ref": "#/components/schemas/Task" }, { "type": "null" } ], "description": "Null when the work was already finished inside the request." } } } } } }, "400": { "$ref": "#/components/responses/Problem400" }, "401": { "$ref": "#/components/responses/Problem401" }, "402": { "$ref": "#/components/responses/Problem402" }, "403": { "$ref": "#/components/responses/Problem403" }, "404": { "$ref": "#/components/responses/Problem404" }, "409": { "$ref": "#/components/responses/Problem409" }, "422": { "$ref": "#/components/responses/Problem422" }, "429": { "$ref": "#/components/responses/Problem429" }, "500": { "$ref": "#/components/responses/Problem500" }, "503": { "$ref": "#/components/responses/Problem503" }, "415": { "$ref": "#/components/responses/Problem415" } }, "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Identifier of the resource.", "schema": { "type": "integer" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Repeat-safety key. Repeating the same key with the same body replays the stored response.", "schema": { "type": "string", "minLength": 8, "maxLength": 255 } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "password": { "type": "string", "minLength": 12, "maxLength": 64, "description": "Administrator password for the reinstalled system. Latin letters and digits only, 12 to 64 characters, with at least one uppercase letter, one lowercase letter and one digit; any other character is refused as invalid_password. Omit to have one generated." }, "accept_license": { "type": "boolean", "description": "Required when the image carries a paid licence." } }, "additionalProperties": false } } } } } }, "/servers/{id}/actions/reset": { "post": { "operationId": "server_reset", "tags": [ "Servers" ], "summary": "Reset", "description": "Restarts the server without asking the guest. Same caveat as power off.", "security": [ { "bearerAuth": [] } ], "responses": { "202": { "description": "Accepted. The work continues in the background - poll the task.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "description": "Identifier of this call." }, "Idempotency-Replayed": { "schema": { "type": "string", "examples": [ "true" ] }, "description": "Present and set to true when this is a stored response replayed for a repeated Idempotency-Key. The work was done by the first call." } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "null" }, "task": { "oneOf": [ { "$ref": "#/components/schemas/Task" }, { "type": "null" } ], "description": "Null when the work was already finished inside the request." } } } } } }, "200": { "description": "Done inside the request: the task field is null, there is nothing to wait for.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "description": "Identifier of this call." }, "Idempotency-Replayed": { "schema": { "type": "string", "examples": [ "true" ] }, "description": "Present and set to true when this is a stored response replayed for a repeated Idempotency-Key. The work was done by the first call." } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "null" }, "task": { "oneOf": [ { "$ref": "#/components/schemas/Task" }, { "type": "null" } ], "description": "Null when the work was already finished inside the request." } } } } } }, "400": { "$ref": "#/components/responses/Problem400" }, "401": { "$ref": "#/components/responses/Problem401" }, "402": { "$ref": "#/components/responses/Problem402" }, "403": { "$ref": "#/components/responses/Problem403" }, "404": { "$ref": "#/components/responses/Problem404" }, "409": { "$ref": "#/components/responses/Problem409" }, "422": { "$ref": "#/components/responses/Problem422" }, "429": { "$ref": "#/components/responses/Problem429" }, "500": { "$ref": "#/components/responses/Problem500" }, "503": { "$ref": "#/components/responses/Problem503" }, "415": { "$ref": "#/components/responses/Problem415" } }, "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Identifier of the resource.", "schema": { "type": "integer" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Repeat-safety key. Repeating the same key with the same body replays the stored response.", "schema": { "type": "string", "minLength": 8, "maxLength": 255 } } ] } }, "/servers/{id}/actions/reset-password": { "post": { "operationId": "server_reset_password", "tags": [ "Servers" ], "summary": "Change the administrator password", "description": "Sets a new password for the administrator account inside the guest. Passwords are never readable through the API, so this operation is the only way to know one.", "security": [ { "bearerAuth": [] } ], "responses": { "202": { "description": "Accepted. The work continues in the background - poll the task.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "description": "Identifier of this call." }, "Idempotency-Replayed": { "schema": { "type": "string", "examples": [ "true" ] }, "description": "Present and set to true when this is a stored response replayed for a repeated Idempotency-Key. The work was done by the first call." } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "null" }, "task": { "oneOf": [ { "$ref": "#/components/schemas/Task" }, { "type": "null" } ], "description": "Null when the work was already finished inside the request." } } } } } }, "200": { "description": "Done inside the request: the task field is null, there is nothing to wait for.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "description": "Identifier of this call." }, "Idempotency-Replayed": { "schema": { "type": "string", "examples": [ "true" ] }, "description": "Present and set to true when this is a stored response replayed for a repeated Idempotency-Key. The work was done by the first call." } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "null" }, "task": { "oneOf": [ { "$ref": "#/components/schemas/Task" }, { "type": "null" } ], "description": "Null when the work was already finished inside the request." } } } } } }, "400": { "$ref": "#/components/responses/Problem400" }, "401": { "$ref": "#/components/responses/Problem401" }, "402": { "$ref": "#/components/responses/Problem402" }, "403": { "$ref": "#/components/responses/Problem403" }, "404": { "$ref": "#/components/responses/Problem404" }, "409": { "$ref": "#/components/responses/Problem409" }, "422": { "$ref": "#/components/responses/Problem422" }, "429": { "$ref": "#/components/responses/Problem429" }, "500": { "$ref": "#/components/responses/Problem500" }, "503": { "$ref": "#/components/responses/Problem503" }, "415": { "$ref": "#/components/responses/Problem415" } }, "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Identifier of the resource.", "schema": { "type": "integer" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Repeat-safety key. Repeating the same key with the same body replays the stored response.", "schema": { "type": "string", "minLength": 8, "maxLength": 255 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "password": { "type": "string", "minLength": 12, "maxLength": 64, "description": "New administrator password. Latin letters and digits only, 12 to 64 characters, with at least one uppercase letter, one lowercase letter and one digit; any other character is refused as invalid_password." } }, "additionalProperties": false, "required": [ "password" ] } } } } } }, "/servers/{id}/actions/shutdown": { "post": { "operationId": "server_shutdown", "tags": [ "Servers" ], "summary": "Shut down", "description": "Asks the guest to shut down cleanly. A guest that ignores the request stays running; power off is the fallback.", "security": [ { "bearerAuth": [] } ], "responses": { "202": { "description": "Accepted. The work continues in the background - poll the task.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "description": "Identifier of this call." }, "Idempotency-Replayed": { "schema": { "type": "string", "examples": [ "true" ] }, "description": "Present and set to true when this is a stored response replayed for a repeated Idempotency-Key. The work was done by the first call." } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "null" }, "task": { "oneOf": [ { "$ref": "#/components/schemas/Task" }, { "type": "null" } ], "description": "Null when the work was already finished inside the request." } } } } } }, "200": { "description": "Done inside the request: the task field is null, there is nothing to wait for.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "description": "Identifier of this call." }, "Idempotency-Replayed": { "schema": { "type": "string", "examples": [ "true" ] }, "description": "Present and set to true when this is a stored response replayed for a repeated Idempotency-Key. The work was done by the first call." } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "null" }, "task": { "oneOf": [ { "$ref": "#/components/schemas/Task" }, { "type": "null" } ], "description": "Null when the work was already finished inside the request." } } } } } }, "400": { "$ref": "#/components/responses/Problem400" }, "401": { "$ref": "#/components/responses/Problem401" }, "402": { "$ref": "#/components/responses/Problem402" }, "403": { "$ref": "#/components/responses/Problem403" }, "404": { "$ref": "#/components/responses/Problem404" }, "409": { "$ref": "#/components/responses/Problem409" }, "422": { "$ref": "#/components/responses/Problem422" }, "429": { "$ref": "#/components/responses/Problem429" }, "500": { "$ref": "#/components/responses/Problem500" }, "503": { "$ref": "#/components/responses/Problem503" }, "415": { "$ref": "#/components/responses/Problem415" } }, "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Identifier of the resource.", "schema": { "type": "integer" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Repeat-safety key. Repeating the same key with the same body replays the stored response.", "schema": { "type": "string", "minLength": 8, "maxLength": 255 } } ] } }, "/servers/{id}/backup-policy": { "get": { "operationId": "server_backup_policy_get", "tags": [ "Backups" ], "summary": "Read the backup policy", "description": "Whether scheduled backups run for this server, on what days and at what time, and how the last run went.", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "description": "Identifier of this call." } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/BackupPolicy" } } } } } }, "400": { "$ref": "#/components/responses/Problem400" }, "401": { "$ref": "#/components/responses/Problem401" }, "402": { "$ref": "#/components/responses/Problem402" }, "403": { "$ref": "#/components/responses/Problem403" }, "404": { "$ref": "#/components/responses/Problem404" }, "409": { "$ref": "#/components/responses/Problem409" }, "422": { "$ref": "#/components/responses/Problem422" }, "429": { "$ref": "#/components/responses/Problem429" }, "500": { "$ref": "#/components/responses/Problem500" }, "503": { "$ref": "#/components/responses/Problem503" } }, "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Identifier of the resource.", "schema": { "type": "integer" } } ] }, "put": { "operationId": "server_backup_policy_set", "tags": [ "Backups" ], "summary": "Set the backup policy", "description": "Turns scheduled backups on or off and sets the schedule. Switching off keeps your days and times, so switching back on does not lose them. Fields you leave out keep their current value.", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "description": "Identifier of this call." }, "Idempotency-Replayed": { "schema": { "type": "string", "examples": [ "true" ] }, "description": "Present and set to true when this is a stored response replayed for a repeated Idempotency-Key. The work was done by the first call." } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/BackupPolicy" } } } } } }, "400": { "$ref": "#/components/responses/Problem400" }, "401": { "$ref": "#/components/responses/Problem401" }, "402": { "$ref": "#/components/responses/Problem402" }, "403": { "$ref": "#/components/responses/Problem403" }, "404": { "$ref": "#/components/responses/Problem404" }, "409": { "$ref": "#/components/responses/Problem409" }, "422": { "$ref": "#/components/responses/Problem422" }, "429": { "$ref": "#/components/responses/Problem429" }, "500": { "$ref": "#/components/responses/Problem500" }, "503": { "$ref": "#/components/responses/Problem503" }, "415": { "$ref": "#/components/responses/Problem415" } }, "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Identifier of the resource.", "schema": { "type": "integer" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Repeat-safety key. Repeating the same key with the same body replays the stored response.", "schema": { "type": "string", "minLength": 8, "maxLength": 255 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "enabled": { "type": "boolean", "description": "Whether scheduled backups run for this server." }, "days": { "type": "array", "items": { "type": "string", "enum": [ "mon", "tue", "wed", "thu", "fri", "sat", "sun" ] }, "minItems": 1, "maxItems": 7, "description": "Days the backup runs. Omit to keep the current days." }, "hour": { "type": "integer", "minimum": 0, "maximum": 23, "description": "Hour of the run, 0 to 23, in the platform's time zone." }, "minute": { "type": "integer", "minimum": 0, "maximum": 59, "description": "Minute of the run, 0 to 59." } }, "additionalProperties": false, "required": [ "enabled" ] } } } } } }, "/servers/{id}/backups": { "get": { "operationId": "server_backup_list", "tags": [ "Backups" ], "summary": "List backups", "description": "Backups of this server, newest first.", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "description": "Identifier of this call." } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Backup" } } } } } } }, "400": { "$ref": "#/components/responses/Problem400" }, "401": { "$ref": "#/components/responses/Problem401" }, "402": { "$ref": "#/components/responses/Problem402" }, "403": { "$ref": "#/components/responses/Problem403" }, "404": { "$ref": "#/components/responses/Problem404" }, "409": { "$ref": "#/components/responses/Problem409" }, "422": { "$ref": "#/components/responses/Problem422" }, "429": { "$ref": "#/components/responses/Problem429" }, "500": { "$ref": "#/components/responses/Problem500" }, "503": { "$ref": "#/components/responses/Problem503" } }, "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Identifier of the resource.", "schema": { "type": "integer" } } ] }, "post": { "operationId": "server_backup_create", "tags": [ "Backups" ], "summary": "Take a backup", "description": "Starts a backup now. This is the one operation that hands you no task: the response points at the backup, and you wait by reading that backup until it becomes available.", "security": [ { "bearerAuth": [] } ], "responses": { "202": { "description": "Accepted. The work continues in the background - poll the task.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "description": "Identifier of this call." }, "Location": { "schema": { "type": "string" }, "description": "Path of the created resource." }, "Idempotency-Replayed": { "schema": { "type": "string", "examples": [ "true" ] }, "description": "Present and set to true when this is a stored response replayed for a repeated Idempotency-Key. The work was done by the first call." } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Backup" } } } } } }, "400": { "$ref": "#/components/responses/Problem400" }, "401": { "$ref": "#/components/responses/Problem401" }, "402": { "$ref": "#/components/responses/Problem402" }, "403": { "$ref": "#/components/responses/Problem403" }, "404": { "$ref": "#/components/responses/Problem404" }, "409": { "$ref": "#/components/responses/Problem409" }, "422": { "$ref": "#/components/responses/Problem422" }, "429": { "$ref": "#/components/responses/Problem429" }, "500": { "$ref": "#/components/responses/Problem500" }, "503": { "$ref": "#/components/responses/Problem503" }, "415": { "$ref": "#/components/responses/Problem415" } }, "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Identifier of the resource.", "schema": { "type": "integer" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Repeat-safety key. Repeating the same key with the same body replays the stored response.", "schema": { "type": "string", "minLength": 8, "maxLength": 255 } } ] } }, "/servers/{id}/backups/{backup}": { "get": { "operationId": "server_backup_get", "tags": [ "Backups" ], "summary": "Read a backup", "description": "One backup. Wait for status available before restoring from it.", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "description": "Identifier of this call." } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Backup" } } } } } }, "400": { "$ref": "#/components/responses/Problem400" }, "401": { "$ref": "#/components/responses/Problem401" }, "402": { "$ref": "#/components/responses/Problem402" }, "403": { "$ref": "#/components/responses/Problem403" }, "404": { "$ref": "#/components/responses/Problem404" }, "409": { "$ref": "#/components/responses/Problem409" }, "422": { "$ref": "#/components/responses/Problem422" }, "429": { "$ref": "#/components/responses/Problem429" }, "500": { "$ref": "#/components/responses/Problem500" }, "503": { "$ref": "#/components/responses/Problem503" } }, "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Identifier of the resource.", "schema": { "type": "integer" } }, { "name": "backup", "in": "path", "required": true, "description": "Backup identifier - the moment it was taken, in UTC.", "schema": { "type": "string", "pattern": "^(?:[^/]{1,64})$" } } ] }, "delete": { "operationId": "server_backup_delete", "tags": [ "Backups" ], "summary": "Delete a backup", "description": "Removes the archive. Restoring from it afterwards is impossible.", "security": [ { "bearerAuth": [] } ], "responses": { "202": { "description": "Accepted. The work continues in the background - poll the task.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "description": "Identifier of this call." }, "Idempotency-Replayed": { "schema": { "type": "string", "examples": [ "true" ] }, "description": "Present and set to true when this is a stored response replayed for a repeated Idempotency-Key. The work was done by the first call." } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/BackupDeleted" }, "task": { "oneOf": [ { "$ref": "#/components/schemas/Task" }, { "type": "null" } ], "description": "Null when the work was already finished inside the request." } } } } } }, "200": { "description": "Done inside the request: the task field is null, there is nothing to wait for.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "description": "Identifier of this call." }, "Idempotency-Replayed": { "schema": { "type": "string", "examples": [ "true" ] }, "description": "Present and set to true when this is a stored response replayed for a repeated Idempotency-Key. The work was done by the first call." } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/BackupDeleted" }, "task": { "oneOf": [ { "$ref": "#/components/schemas/Task" }, { "type": "null" } ], "description": "Null when the work was already finished inside the request." } } } } } }, "400": { "$ref": "#/components/responses/Problem400" }, "401": { "$ref": "#/components/responses/Problem401" }, "402": { "$ref": "#/components/responses/Problem402" }, "403": { "$ref": "#/components/responses/Problem403" }, "404": { "$ref": "#/components/responses/Problem404" }, "409": { "$ref": "#/components/responses/Problem409" }, "422": { "$ref": "#/components/responses/Problem422" }, "429": { "$ref": "#/components/responses/Problem429" }, "500": { "$ref": "#/components/responses/Problem500" }, "503": { "$ref": "#/components/responses/Problem503" }, "415": { "$ref": "#/components/responses/Problem415" } }, "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Identifier of the resource.", "schema": { "type": "integer" } }, { "name": "backup", "in": "path", "required": true, "description": "Backup identifier - the moment it was taken, in UTC.", "schema": { "type": "string", "pattern": "^(?:[^/]{1,64})$" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Repeat-safety key. Repeating the same key with the same body replays the stored response.", "schema": { "type": "string", "minLength": 8, "maxLength": 255 } } ] } }, "/servers/{id}/backups/{backup}/restore": { "post": { "operationId": "server_backup_restore", "tags": [ "Backups" ], "summary": "Restore from a backup", "description": "Overwrites the server's disks with the contents of the backup. Everything written since the backup was taken is lost, and the operation cannot be undone.", "security": [ { "bearerAuth": [] } ], "responses": { "202": { "description": "Accepted. The work continues in the background - poll the task.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "description": "Identifier of this call." }, "Idempotency-Replayed": { "schema": { "type": "string", "examples": [ "true" ] }, "description": "Present and set to true when this is a stored response replayed for a repeated Idempotency-Key. The work was done by the first call." } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "null" }, "task": { "oneOf": [ { "$ref": "#/components/schemas/Task" }, { "type": "null" } ], "description": "Null when the work was already finished inside the request." } } } } } }, "200": { "description": "Done inside the request: the task field is null, there is nothing to wait for.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "description": "Identifier of this call." }, "Idempotency-Replayed": { "schema": { "type": "string", "examples": [ "true" ] }, "description": "Present and set to true when this is a stored response replayed for a repeated Idempotency-Key. The work was done by the first call." } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "null" }, "task": { "oneOf": [ { "$ref": "#/components/schemas/Task" }, { "type": "null" } ], "description": "Null when the work was already finished inside the request." } } } } } }, "400": { "$ref": "#/components/responses/Problem400" }, "401": { "$ref": "#/components/responses/Problem401" }, "402": { "$ref": "#/components/responses/Problem402" }, "403": { "$ref": "#/components/responses/Problem403" }, "404": { "$ref": "#/components/responses/Problem404" }, "409": { "$ref": "#/components/responses/Problem409" }, "422": { "$ref": "#/components/responses/Problem422" }, "429": { "$ref": "#/components/responses/Problem429" }, "500": { "$ref": "#/components/responses/Problem500" }, "503": { "$ref": "#/components/responses/Problem503" }, "415": { "$ref": "#/components/responses/Problem415" } }, "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Identifier of the resource.", "schema": { "type": "integer" } }, { "name": "backup", "in": "path", "required": true, "description": "Backup identifier - the moment it was taken, in UTC.", "schema": { "type": "string", "pattern": "^(?:[^/]{1,64})$" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Repeat-safety key. Repeating the same key with the same body replays the stored response.", "schema": { "type": "string", "minLength": 8, "maxLength": 255 } } ] } }, "/servers/{id}/disks": { "get": { "operationId": "server_disk_list", "tags": [ "Disks" ], "summary": "List disks", "description": "Disks attached to the server, the system disk included. Data disks are their own resource; the system disk is sized through the server.", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "description": "Identifier of this call." } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Disk" } } } } } } }, "400": { "$ref": "#/components/responses/Problem400" }, "401": { "$ref": "#/components/responses/Problem401" }, "402": { "$ref": "#/components/responses/Problem402" }, "403": { "$ref": "#/components/responses/Problem403" }, "404": { "$ref": "#/components/responses/Problem404" }, "409": { "$ref": "#/components/responses/Problem409" }, "422": { "$ref": "#/components/responses/Problem422" }, "429": { "$ref": "#/components/responses/Problem429" }, "500": { "$ref": "#/components/responses/Problem500" }, "503": { "$ref": "#/components/responses/Problem503" } }, "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Identifier of the resource.", "schema": { "type": "integer" } } ] }, "post": { "operationId": "server_disk_create", "tags": [ "Disks" ], "summary": "Add a data disk", "description": "Attaches a new disk. The server restarts to pick it up, so plan for the interruption.", "security": [ { "bearerAuth": [] } ], "responses": { "202": { "description": "Accepted. The work continues in the background - poll the task.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "description": "Identifier of this call." }, "Idempotency-Replayed": { "schema": { "type": "string", "examples": [ "true" ] }, "description": "Present and set to true when this is a stored response replayed for a repeated Idempotency-Key. The work was done by the first call." } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "null" }, "task": { "oneOf": [ { "$ref": "#/components/schemas/Task" }, { "type": "null" } ], "description": "Null when the work was already finished inside the request." } } } } } }, "200": { "description": "Done inside the request: the task field is null, there is nothing to wait for.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "description": "Identifier of this call." }, "Idempotency-Replayed": { "schema": { "type": "string", "examples": [ "true" ] }, "description": "Present and set to true when this is a stored response replayed for a repeated Idempotency-Key. The work was done by the first call." } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "null" }, "task": { "oneOf": [ { "$ref": "#/components/schemas/Task" }, { "type": "null" } ], "description": "Null when the work was already finished inside the request." } } } } } }, "400": { "$ref": "#/components/responses/Problem400" }, "401": { "$ref": "#/components/responses/Problem401" }, "402": { "$ref": "#/components/responses/Problem402" }, "403": { "$ref": "#/components/responses/Problem403" }, "404": { "$ref": "#/components/responses/Problem404" }, "409": { "$ref": "#/components/responses/Problem409" }, "422": { "$ref": "#/components/responses/Problem422" }, "429": { "$ref": "#/components/responses/Problem429" }, "500": { "$ref": "#/components/responses/Problem500" }, "503": { "$ref": "#/components/responses/Problem503" }, "415": { "$ref": "#/components/responses/Problem415" } }, "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Identifier of the resource.", "schema": { "type": "integer" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Repeat-safety key. Repeating the same key with the same body replays the stored response.", "schema": { "type": "string", "minLength": 8, "maxLength": 255 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "size_gb": { "type": "integer", "minimum": 1, "maximum": 65536, "description": "Size of the new data disk in gigabytes." } }, "additionalProperties": false, "required": [ "size_gb" ] } } } } } }, "/servers/{id}/disks/{disk}": { "get": { "operationId": "server_disk_get", "tags": [ "Disks" ], "summary": "Get a disk", "description": "One disk of the server by its slot name. The slot is the identifier: it survives resizing, reboots and the removal of a neighbouring disk, so it is what you keep in your configuration. The system disk is readable here too, but it is sized through the server, not through this resource.", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "description": "Identifier of this call." } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Disk" } } } } } }, "400": { "$ref": "#/components/responses/Problem400" }, "401": { "$ref": "#/components/responses/Problem401" }, "402": { "$ref": "#/components/responses/Problem402" }, "403": { "$ref": "#/components/responses/Problem403" }, "404": { "$ref": "#/components/responses/Problem404" }, "409": { "$ref": "#/components/responses/Problem409" }, "422": { "$ref": "#/components/responses/Problem422" }, "429": { "$ref": "#/components/responses/Problem429" }, "500": { "$ref": "#/components/responses/Problem500" }, "503": { "$ref": "#/components/responses/Problem503" } }, "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Identifier of the resource.", "schema": { "type": "integer" } }, { "name": "disk", "in": "path", "required": true, "description": "Disk slot name, as returned by the disks listing.", "schema": { "type": "string", "pattern": "^(?:[a-z]{3,6}\\d{1,2})$" } } ] }, "patch": { "operationId": "server_disk_update", "tags": [ "Disks" ], "summary": "Grow a data disk", "description": "Disks only grow - shrinking is impossible and is refused. The server restarts.", "security": [ { "bearerAuth": [] } ], "responses": { "202": { "description": "Accepted. The work continues in the background - poll the task.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "description": "Identifier of this call." }, "Idempotency-Replayed": { "schema": { "type": "string", "examples": [ "true" ] }, "description": "Present and set to true when this is a stored response replayed for a repeated Idempotency-Key. The work was done by the first call." } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Disk" }, "task": { "oneOf": [ { "$ref": "#/components/schemas/Task" }, { "type": "null" } ], "description": "Null when the work was already finished inside the request." } } } } } }, "200": { "description": "Done inside the request: the task field is null, there is nothing to wait for.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "description": "Identifier of this call." }, "Idempotency-Replayed": { "schema": { "type": "string", "examples": [ "true" ] }, "description": "Present and set to true when this is a stored response replayed for a repeated Idempotency-Key. The work was done by the first call." } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Disk" }, "task": { "oneOf": [ { "$ref": "#/components/schemas/Task" }, { "type": "null" } ], "description": "Null when the work was already finished inside the request." } } } } } }, "400": { "$ref": "#/components/responses/Problem400" }, "401": { "$ref": "#/components/responses/Problem401" }, "402": { "$ref": "#/components/responses/Problem402" }, "403": { "$ref": "#/components/responses/Problem403" }, "404": { "$ref": "#/components/responses/Problem404" }, "409": { "$ref": "#/components/responses/Problem409" }, "422": { "$ref": "#/components/responses/Problem422" }, "429": { "$ref": "#/components/responses/Problem429" }, "500": { "$ref": "#/components/responses/Problem500" }, "503": { "$ref": "#/components/responses/Problem503" }, "415": { "$ref": "#/components/responses/Problem415" } }, "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Identifier of the resource.", "schema": { "type": "integer" } }, { "name": "disk", "in": "path", "required": true, "description": "Disk slot name, as returned by the disks listing.", "schema": { "type": "string", "pattern": "^(?:[a-z]{3,6}\\d{1,2})$" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Repeat-safety key. Repeating the same key with the same body replays the stored response.", "schema": { "type": "string", "minLength": 8, "maxLength": 255 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "size_gb": { "type": "integer", "minimum": 1, "maximum": 65536, "description": "New size in gigabytes. Larger than the current one - disks do not shrink." } }, "additionalProperties": false, "required": [ "size_gb" ] } } } } }, "delete": { "operationId": "server_disk_delete", "tags": [ "Disks" ], "summary": "Delete a data disk", "description": "Destroys the disk and everything on it. The system disk cannot be deleted this way.", "security": [ { "bearerAuth": [] } ], "responses": { "202": { "description": "Accepted. The work continues in the background - poll the task.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "description": "Identifier of this call." }, "Idempotency-Replayed": { "schema": { "type": "string", "examples": [ "true" ] }, "description": "Present and set to true when this is a stored response replayed for a repeated Idempotency-Key. The work was done by the first call." } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/DiskDeleted" }, "task": { "oneOf": [ { "$ref": "#/components/schemas/Task" }, { "type": "null" } ], "description": "Null when the work was already finished inside the request." } } } } } }, "200": { "description": "Done inside the request: the task field is null, there is nothing to wait for.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "description": "Identifier of this call." }, "Idempotency-Replayed": { "schema": { "type": "string", "examples": [ "true" ] }, "description": "Present and set to true when this is a stored response replayed for a repeated Idempotency-Key. The work was done by the first call." } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/DiskDeleted" }, "task": { "oneOf": [ { "$ref": "#/components/schemas/Task" }, { "type": "null" } ], "description": "Null when the work was already finished inside the request." } } } } } }, "400": { "$ref": "#/components/responses/Problem400" }, "401": { "$ref": "#/components/responses/Problem401" }, "402": { "$ref": "#/components/responses/Problem402" }, "403": { "$ref": "#/components/responses/Problem403" }, "404": { "$ref": "#/components/responses/Problem404" }, "409": { "$ref": "#/components/responses/Problem409" }, "422": { "$ref": "#/components/responses/Problem422" }, "429": { "$ref": "#/components/responses/Problem429" }, "500": { "$ref": "#/components/responses/Problem500" }, "503": { "$ref": "#/components/responses/Problem503" }, "415": { "$ref": "#/components/responses/Problem415" } }, "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Identifier of the resource.", "schema": { "type": "integer" } }, { "name": "disk", "in": "path", "required": true, "description": "Disk slot name, as returned by the disks listing.", "schema": { "type": "string", "pattern": "^(?:[a-z]{3,6}\\d{1,2})$" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Repeat-safety key. Repeating the same key with the same body replays the stored response.", "schema": { "type": "string", "minLength": 8, "maxLength": 255 } } ] } }, "/servers/{id}/events": { "get": { "operationId": "server_event_list", "tags": [ "Servers" ], "summary": "Read server events", "description": "What the platform did with this server and whether it succeeded. This is our own record of operations, not the guest's system log.", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "description": "Identifier of this call." } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Event" } } } } } } }, "400": { "$ref": "#/components/responses/Problem400" }, "401": { "$ref": "#/components/responses/Problem401" }, "402": { "$ref": "#/components/responses/Problem402" }, "403": { "$ref": "#/components/responses/Problem403" }, "404": { "$ref": "#/components/responses/Problem404" }, "409": { "$ref": "#/components/responses/Problem409" }, "422": { "$ref": "#/components/responses/Problem422" }, "429": { "$ref": "#/components/responses/Problem429" }, "500": { "$ref": "#/components/responses/Problem500" }, "503": { "$ref": "#/components/responses/Problem503" } }, "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Identifier of the resource.", "schema": { "type": "integer" } }, { "name": "start", "in": "query", "required": false, "description": "Start of the window, RFC 3339 in UTC. Included.", "schema": { "type": "string", "format": "date-time" } }, { "name": "end", "in": "query", "required": false, "description": "End of the window, RFC 3339 in UTC. Excluded.", "schema": { "type": "string", "format": "date-time" } }, { "name": "limit", "in": "query", "required": false, "description": "How many events to return, newest first.", "schema": { "type": "integer", "minimum": 1, "maximum": 500 } } ] } }, "/servers/{id}/firewall": { "get": { "operationId": "server_firewall_get", "tags": [ "Firewall" ], "summary": "Read the firewall", "description": "The firewall of the server together with its rules, in order. Filtering applies to the server's public card.", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "description": "Identifier of this call." } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Firewall" } } } } } }, "400": { "$ref": "#/components/responses/Problem400" }, "401": { "$ref": "#/components/responses/Problem401" }, "402": { "$ref": "#/components/responses/Problem402" }, "403": { "$ref": "#/components/responses/Problem403" }, "404": { "$ref": "#/components/responses/Problem404" }, "409": { "$ref": "#/components/responses/Problem409" }, "422": { "$ref": "#/components/responses/Problem422" }, "429": { "$ref": "#/components/responses/Problem429" }, "500": { "$ref": "#/components/responses/Problem500" }, "503": { "$ref": "#/components/responses/Problem503" } }, "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Identifier of the resource.", "schema": { "type": "integer" } } ] }, "put": { "operationId": "server_firewall_set", "tags": [ "Firewall" ], "summary": "Set the firewall", "description": "Replaces the whole firewall, rules included - send the complete set you want. Rules are evaluated in order and the first match wins. A server with no public card cannot enable filtering.", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "description": "Identifier of this call." }, "Idempotency-Replayed": { "schema": { "type": "string", "examples": [ "true" ] }, "description": "Present and set to true when this is a stored response replayed for a repeated Idempotency-Key. The work was done by the first call." } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Firewall" } } } } } }, "400": { "$ref": "#/components/responses/Problem400" }, "401": { "$ref": "#/components/responses/Problem401" }, "402": { "$ref": "#/components/responses/Problem402" }, "403": { "$ref": "#/components/responses/Problem403" }, "404": { "$ref": "#/components/responses/Problem404" }, "409": { "$ref": "#/components/responses/Problem409" }, "422": { "$ref": "#/components/responses/Problem422" }, "429": { "$ref": "#/components/responses/Problem429" }, "500": { "$ref": "#/components/responses/Problem500" }, "503": { "$ref": "#/components/responses/Problem503" }, "415": { "$ref": "#/components/responses/Problem415" } }, "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Identifier of the resource.", "schema": { "type": "integer" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Repeat-safety key. Repeating the same key with the same body replays the stored response.", "schema": { "type": "string", "minLength": 8, "maxLength": 255 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "enabled": { "type": "boolean", "description": "Whether filtering applies to the server's public card." }, "policy_in": { "type": "string", "minLength": 4, "maxLength": 6, "pattern": "^(accept|drop|reject)$", "description": "What happens to inbound traffic no rule matched." }, "policy_out": { "type": "string", "minLength": 4, "maxLength": 6, "pattern": "^(accept|drop|reject)$", "description": "What happens to outbound traffic no rule matched." }, "log_level_in": { "type": "string", "minLength": 3, "maxLength": 7, "pattern": "^(nolog|emerg|alert|crit|err|warning|notice|info|debug)$", "description": "How much inbound filtering is logged." }, "log_level_out": { "type": "string", "minLength": 3, "maxLength": 7, "pattern": "^(nolog|emerg|alert|crit|err|warning|notice|info|debug)$", "description": "How much outbound filtering is logged." }, "rules": { "type": "array", "items": { "type": "object", "properties": { "direction": { "type": "string", "minLength": 2, "maxLength": 3, "pattern": "^(in|out)$" }, "action": { "type": "string", "minLength": 4, "maxLength": 6, "pattern": "^(accept|drop|reject)$" }, "protocol": { "type": "string", "minLength": 1, "maxLength": 16, "pattern": "^[a-zA-Z0-9\\-]+$" }, "source": { "type": "string", "minLength": 1, "maxLength": 512 }, "destination": { "type": "string", "minLength": 1, "maxLength": 512 }, "source_port": { "type": "string", "minLength": 1, "maxLength": 64, "pattern": "^[0-9,:\\-]+$" }, "destination_port": { "type": "string", "minLength": 1, "maxLength": 64, "pattern": "^[0-9,:\\-]+$" }, "macro": { "type": "string", "minLength": 2, "maxLength": 32, "pattern": "^[A-Za-z0-9_\\-]+$" }, "enabled": { "type": "boolean" }, "description": { "type": "string", "minLength": 1, "maxLength": 255, "pattern": "^[^#\\x00-\\x1F\\x7F][^\\x00-\\x1F\\x7F]*$" } }, "additionalProperties": false, "required": [ "direction", "action" ] }, "maxItems": 50, "description": "The complete rule set, in order. The first matching rule wins." } }, "additionalProperties": false, "required": [ "enabled", "rules" ] } } } } } }, "/servers/{id}/iso": { "get": { "operationId": "server_iso_get", "tags": [ "Images" ], "summary": "Read the server's drive", "description": "What is in the server's optical drive and whether it is set to boot from it.", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "description": "Identifier of this call." } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/ServerIso" } } } } } }, "400": { "$ref": "#/components/responses/Problem400" }, "401": { "$ref": "#/components/responses/Problem401" }, "402": { "$ref": "#/components/responses/Problem402" }, "403": { "$ref": "#/components/responses/Problem403" }, "404": { "$ref": "#/components/responses/Problem404" }, "409": { "$ref": "#/components/responses/Problem409" }, "422": { "$ref": "#/components/responses/Problem422" }, "429": { "$ref": "#/components/responses/Problem429" }, "500": { "$ref": "#/components/responses/Problem500" }, "503": { "$ref": "#/components/responses/Problem503" } }, "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Identifier of the resource.", "schema": { "type": "integer" } } ] }, "put": { "operationId": "server_iso_set", "tags": [ "Images" ], "summary": "Insert an image into the drive", "description": "Puts one of your ISO images in the drive, optionally making the server boot from it. Booting from the drive restarts the server. Inserting takes the project image library too, so inserts into DIFFERENT servers of one project run one after another rather than in parallel, and a request that does not get its turn answers 409 server_busy with Retry-After. Ejecting is not held back this way.", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "description": "Identifier of this call." }, "Idempotency-Replayed": { "schema": { "type": "string", "examples": [ "true" ] }, "description": "Present and set to true when this is a stored response replayed for a repeated Idempotency-Key. The work was done by the first call." } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/ServerIso" } } } } } }, "400": { "$ref": "#/components/responses/Problem400" }, "401": { "$ref": "#/components/responses/Problem401" }, "402": { "$ref": "#/components/responses/Problem402" }, "403": { "$ref": "#/components/responses/Problem403" }, "404": { "$ref": "#/components/responses/Problem404" }, "409": { "$ref": "#/components/responses/Problem409" }, "422": { "$ref": "#/components/responses/Problem422" }, "429": { "$ref": "#/components/responses/Problem429" }, "500": { "$ref": "#/components/responses/Problem500" }, "503": { "$ref": "#/components/responses/Problem503" }, "415": { "$ref": "#/components/responses/Problem415" } }, "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Identifier of the resource.", "schema": { "type": "integer" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Repeat-safety key. Repeating the same key with the same body replays the stored response.", "schema": { "type": "string", "minLength": 8, "maxLength": 255 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "image": { "type": "string", "minLength": 4, "maxLength": 64, "description": "Identifier of the ISO image to insert." }, "boot": { "type": "boolean", "description": "Set true to boot the server from the drive. The server restarts." } }, "additionalProperties": false, "required": [ "image" ] } } } } }, "delete": { "operationId": "server_iso_eject", "tags": [ "Images" ], "summary": "Eject the drive", "description": "Empties the drive. A stopped server stays stopped: ejecting never powers a server on.", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "description": "Identifier of this call." }, "Idempotency-Replayed": { "schema": { "type": "string", "examples": [ "true" ] }, "description": "Present and set to true when this is a stored response replayed for a repeated Idempotency-Key. The work was done by the first call." } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/ServerIso" } } } } } }, "400": { "$ref": "#/components/responses/Problem400" }, "401": { "$ref": "#/components/responses/Problem401" }, "402": { "$ref": "#/components/responses/Problem402" }, "403": { "$ref": "#/components/responses/Problem403" }, "404": { "$ref": "#/components/responses/Problem404" }, "409": { "$ref": "#/components/responses/Problem409" }, "422": { "$ref": "#/components/responses/Problem422" }, "429": { "$ref": "#/components/responses/Problem429" }, "500": { "$ref": "#/components/responses/Problem500" }, "503": { "$ref": "#/components/responses/Problem503" }, "415": { "$ref": "#/components/responses/Problem415" } }, "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Identifier of the resource.", "schema": { "type": "integer" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Repeat-safety key. Repeating the same key with the same body replays the stored response.", "schema": { "type": "string", "minLength": 8, "maxLength": 255 } } ] } }, "/servers/{id}/metrics": { "get": { "operationId": "server_metrics_get", "tags": [ "Servers" ], "summary": "Read server metrics", "description": "Processor, memory, disk and network measurements over a window. The step you get back can be coarser than the one you asked for; a null value means no data for that moment, not zero.", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "description": "Identifier of this call." } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Metrics" } } } } } }, "400": { "$ref": "#/components/responses/Problem400" }, "401": { "$ref": "#/components/responses/Problem401" }, "402": { "$ref": "#/components/responses/Problem402" }, "403": { "$ref": "#/components/responses/Problem403" }, "404": { "$ref": "#/components/responses/Problem404" }, "409": { "$ref": "#/components/responses/Problem409" }, "422": { "$ref": "#/components/responses/Problem422" }, "429": { "$ref": "#/components/responses/Problem429" }, "500": { "$ref": "#/components/responses/Problem500" }, "503": { "$ref": "#/components/responses/Problem503" } }, "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Identifier of the resource.", "schema": { "type": "integer" } }, { "name": "start", "in": "query", "required": false, "description": "Start of the window, RFC 3339 in UTC. Included.", "schema": { "type": "string", "format": "date-time" } }, { "name": "end", "in": "query", "required": false, "description": "End of the window, RFC 3339 in UTC. Excluded.", "schema": { "type": "string", "format": "date-time" } }, { "name": "step", "in": "query", "required": false, "description": "Requested spacing between points, in seconds. What you get back can be coarser.", "schema": { "type": "integer", "minimum": 60, "maximum": 86400 } }, { "name": "type", "in": "query", "required": false, "description": "Which measurements to return - comma-separated. Omit for all of them.", "schema": { "type": "string", "description": "Comma-separated subset of: cpu, memory, disk, network" } }, { "name": "aggregation", "in": "query", "required": false, "description": "How values inside one step are combined.", "schema": { "type": "string", "enum": [ "average", "max" ], "default": "average" } } ] } }, "/servers/{id}/network-interfaces": { "get": { "operationId": "server_nic_list", "tags": [ "Network interfaces" ], "summary": "List network cards", "description": "Cards on the server, with the network or public addresses each carries.", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "description": "Identifier of this call." } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/NetworkInterface" } } } } } } }, "400": { "$ref": "#/components/responses/Problem400" }, "401": { "$ref": "#/components/responses/Problem401" }, "402": { "$ref": "#/components/responses/Problem402" }, "403": { "$ref": "#/components/responses/Problem403" }, "404": { "$ref": "#/components/responses/Problem404" }, "409": { "$ref": "#/components/responses/Problem409" }, "422": { "$ref": "#/components/responses/Problem422" }, "429": { "$ref": "#/components/responses/Problem429" }, "500": { "$ref": "#/components/responses/Problem500" }, "503": { "$ref": "#/components/responses/Problem503" } }, "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Identifier of the resource.", "schema": { "type": "integer" } } ] }, "post": { "operationId": "server_nic_create", "tags": [ "Network interfaces" ], "summary": "Add a network card", "description": "Attaches a card either to a private network or to the internet. A router's cards are managed through its networks instead.", "security": [ { "bearerAuth": [] } ], "responses": { "202": { "description": "Accepted. The work continues in the background - poll the task.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "description": "Identifier of this call." }, "Location": { "schema": { "type": "string" }, "description": "Path of the created resource." }, "Idempotency-Replayed": { "schema": { "type": "string", "examples": [ "true" ] }, "description": "Present and set to true when this is a stored response replayed for a repeated Idempotency-Key. The work was done by the first call." } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/NetworkInterface" }, "task": { "oneOf": [ { "$ref": "#/components/schemas/Task" }, { "type": "null" } ], "description": "Null when the work was already finished inside the request." } } } } } }, "200": { "description": "Done inside the request: the task field is null, there is nothing to wait for.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "description": "Identifier of this call." }, "Location": { "schema": { "type": "string" }, "description": "Path of the created resource." }, "Idempotency-Replayed": { "schema": { "type": "string", "examples": [ "true" ] }, "description": "Present and set to true when this is a stored response replayed for a repeated Idempotency-Key. The work was done by the first call." } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/NetworkInterface" }, "task": { "oneOf": [ { "$ref": "#/components/schemas/Task" }, { "type": "null" } ], "description": "Null when the work was already finished inside the request." } } } } } }, "400": { "$ref": "#/components/responses/Problem400" }, "401": { "$ref": "#/components/responses/Problem401" }, "402": { "$ref": "#/components/responses/Problem402" }, "403": { "$ref": "#/components/responses/Problem403" }, "404": { "$ref": "#/components/responses/Problem404" }, "409": { "$ref": "#/components/responses/Problem409" }, "422": { "$ref": "#/components/responses/Problem422" }, "429": { "$ref": "#/components/responses/Problem429" }, "500": { "$ref": "#/components/responses/Problem500" }, "503": { "$ref": "#/components/responses/Problem503" }, "415": { "$ref": "#/components/responses/Problem415" } }, "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Identifier of the resource.", "schema": { "type": "integer" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Repeat-safety key. Repeating the same key with the same body replays the stored response.", "schema": { "type": "string", "minLength": 8, "maxLength": 255 } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "network_id": { "type": "integer", "minimum": 1, "description": "Private network to attach the card to." }, "public": { "type": "boolean", "description": "Set true for a card facing the internet, instead of a network." }, "ips": { "type": "array", "items": { "type": "integer", "minimum": 1 }, "maxItems": 8, "description": "Public addresses to put on the card. Only for a public card. NOT ACCEPTED WHILE THE CARD IS BEING CREATED - the platform would drop the address and create the card without it, so such a request is refused with nic_ips_on_create_not_supported. Create the card, wait for the task to finish, then attach the addresses with a PATCH of the card. The field stays here: it will start working once the create path of the platform validates addresses the way its update path does." }, "firewall": { "type": "boolean", "description": "Whether the firewall filters this card." } }, "additionalProperties": false } } } } } }, "/servers/{id}/network-interfaces/{interface}": { "get": { "operationId": "server_nic_get", "tags": [ "Network interfaces" ], "summary": "Read a network card", "description": "One card by its slot name.", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "description": "Identifier of this call." } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/NetworkInterface" } } } } } }, "400": { "$ref": "#/components/responses/Problem400" }, "401": { "$ref": "#/components/responses/Problem401" }, "402": { "$ref": "#/components/responses/Problem402" }, "403": { "$ref": "#/components/responses/Problem403" }, "404": { "$ref": "#/components/responses/Problem404" }, "409": { "$ref": "#/components/responses/Problem409" }, "422": { "$ref": "#/components/responses/Problem422" }, "429": { "$ref": "#/components/responses/Problem429" }, "500": { "$ref": "#/components/responses/Problem500" }, "503": { "$ref": "#/components/responses/Problem503" } }, "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Identifier of the resource.", "schema": { "type": "integer" } }, { "name": "interface", "in": "path", "required": true, "description": "Network card slot name.", "schema": { "type": "string", "pattern": "^(?:net\\d{1,2})$" } } ] }, "patch": { "operationId": "server_nic_update", "tags": [ "Network interfaces" ], "summary": "Change a network card", "description": "Moves the card to another network, changes its addresses, turns filtering on, or disconnects it. Send only what changes: fields you leave out are read back from the current card and kept. When the change takes the card out of the public network, the response also lists the addresses it frees - they stay with the project and keep being billed until you release them, which the task of this call makes possible.", "security": [ { "bearerAuth": [] } ], "responses": { "202": { "description": "Accepted. The work continues in the background - poll the task.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "description": "Identifier of this call." }, "Idempotency-Replayed": { "schema": { "type": "string", "examples": [ "true" ] }, "description": "Present and set to true when this is a stored response replayed for a repeated Idempotency-Key. The work was done by the first call." } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/NetworkInterface" }, "task": { "oneOf": [ { "$ref": "#/components/schemas/Task" }, { "type": "null" } ], "description": "Null when the work was already finished inside the request." }, "billable_ips": { "type": "array", "items": { "$ref": "#/components/schemas/Ip" }, "description": "Public addresses released by this change. They stay with the project and keep being billed until released with DELETE /v1/ips/{id}. Present whenever the card leaves the public network, empty when it carried no addresses; absent from every other change of the card." } } } } } }, "200": { "description": "Done inside the request: the task field is null, there is nothing to wait for.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "description": "Identifier of this call." }, "Idempotency-Replayed": { "schema": { "type": "string", "examples": [ "true" ] }, "description": "Present and set to true when this is a stored response replayed for a repeated Idempotency-Key. The work was done by the first call." } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/NetworkInterface" }, "task": { "oneOf": [ { "$ref": "#/components/schemas/Task" }, { "type": "null" } ], "description": "Null when the work was already finished inside the request." }, "billable_ips": { "type": "array", "items": { "$ref": "#/components/schemas/Ip" }, "description": "Public addresses released by this change. They stay with the project and keep being billed until released with DELETE /v1/ips/{id}. Present whenever the card leaves the public network, empty when it carried no addresses; absent from every other change of the card." } } } } } }, "400": { "$ref": "#/components/responses/Problem400" }, "401": { "$ref": "#/components/responses/Problem401" }, "402": { "$ref": "#/components/responses/Problem402" }, "403": { "$ref": "#/components/responses/Problem403" }, "404": { "$ref": "#/components/responses/Problem404" }, "409": { "$ref": "#/components/responses/Problem409" }, "422": { "$ref": "#/components/responses/Problem422" }, "429": { "$ref": "#/components/responses/Problem429" }, "500": { "$ref": "#/components/responses/Problem500" }, "503": { "$ref": "#/components/responses/Problem503" }, "415": { "$ref": "#/components/responses/Problem415" } }, "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Identifier of the resource.", "schema": { "type": "integer" } }, { "name": "interface", "in": "path", "required": true, "description": "Network card slot name.", "schema": { "type": "string", "pattern": "^(?:net\\d{1,2})$" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Repeat-safety key. Repeating the same key with the same body replays the stored response.", "schema": { "type": "string", "minLength": 8, "maxLength": 255 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "network_id": { "type": "integer", "minimum": 1, "description": "Move the card to this private network." }, "public": { "type": "boolean", "description": "Turn the card into a public one." }, "ips": { "type": "array", "items": { "type": "integer", "minimum": 1 }, "maxItems": 8, "description": "Public addresses the card should carry." }, "firewall": { "type": "boolean", "description": "Whether the firewall filters this card." }, "link_down": { "type": "boolean", "description": "Set true to disconnect the card without removing it." } }, "additionalProperties": false, "anyOf": [ { "required": [ "network_id" ] }, { "required": [ "public" ] }, { "required": [ "ips" ] }, { "required": [ "firewall" ] }, { "required": [ "link_down" ] } ], "description": "At least one of these fields must be present." } } } } }, "delete": { "operationId": "server_nic_delete", "tags": [ "Network interfaces" ], "summary": "Remove a network card", "description": "Removes the card. Addresses that were on it stay with the project and keep being billed - they are listed in the response and can be released once this task has finished.", "security": [ { "bearerAuth": [] } ], "responses": { "202": { "description": "Accepted. The work continues in the background - poll the task.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "description": "Identifier of this call." }, "Idempotency-Replayed": { "schema": { "type": "string", "examples": [ "true" ] }, "description": "Present and set to true when this is a stored response replayed for a repeated Idempotency-Key. The work was done by the first call." } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/NicDeleted" }, "task": { "oneOf": [ { "$ref": "#/components/schemas/Task" }, { "type": "null" } ], "description": "Null when the work was already finished inside the request." } } } } } }, "200": { "description": "Done inside the request: the task field is null, there is nothing to wait for.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "description": "Identifier of this call." }, "Idempotency-Replayed": { "schema": { "type": "string", "examples": [ "true" ] }, "description": "Present and set to true when this is a stored response replayed for a repeated Idempotency-Key. The work was done by the first call." } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/NicDeleted" }, "task": { "oneOf": [ { "$ref": "#/components/schemas/Task" }, { "type": "null" } ], "description": "Null when the work was already finished inside the request." } } } } } }, "400": { "$ref": "#/components/responses/Problem400" }, "401": { "$ref": "#/components/responses/Problem401" }, "402": { "$ref": "#/components/responses/Problem402" }, "403": { "$ref": "#/components/responses/Problem403" }, "404": { "$ref": "#/components/responses/Problem404" }, "409": { "$ref": "#/components/responses/Problem409" }, "422": { "$ref": "#/components/responses/Problem422" }, "429": { "$ref": "#/components/responses/Problem429" }, "500": { "$ref": "#/components/responses/Problem500" }, "503": { "$ref": "#/components/responses/Problem503" }, "415": { "$ref": "#/components/responses/Problem415" } }, "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Identifier of the resource.", "schema": { "type": "integer" } }, { "name": "interface", "in": "path", "required": true, "description": "Network card slot name.", "schema": { "type": "string", "pattern": "^(?:net\\d{1,2})$" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Repeat-safety key. Repeating the same key with the same body replays the stored response.", "schema": { "type": "string", "minLength": 8, "maxLength": 255 } } ] } }, "/servers/{id}/private-ips": { "get": { "operationId": "server_private_ips_get", "tags": [ "Servers" ], "summary": "Read private addresses", "description": "Addresses the guest agent reports from inside the server. Requires a running guest agent; when it does not answer, available is false rather than an error.", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "description": "Identifier of this call." } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/PrivateIps" } } } } } }, "400": { "$ref": "#/components/responses/Problem400" }, "401": { "$ref": "#/components/responses/Problem401" }, "402": { "$ref": "#/components/responses/Problem402" }, "403": { "$ref": "#/components/responses/Problem403" }, "404": { "$ref": "#/components/responses/Problem404" }, "409": { "$ref": "#/components/responses/Problem409" }, "422": { "$ref": "#/components/responses/Problem422" }, "429": { "$ref": "#/components/responses/Problem429" }, "500": { "$ref": "#/components/responses/Problem500" }, "503": { "$ref": "#/components/responses/Problem503" } }, "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Identifier of the resource.", "schema": { "type": "integer" } } ] } }, "/servers/{id}/router/dhcp": { "put": { "operationId": "router_dhcp", "tags": [ "Router" ], "summary": "Set address handout", "description": "Turns address handout on or off for one router interface, and sets the range it hands out. The range must sit inside the network's own subnet.", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "description": "Identifier of this call." }, "Idempotency-Replayed": { "schema": { "type": "string", "examples": [ "true" ] }, "description": "Present and set to true when this is a stored response replayed for a repeated Idempotency-Key. The work was done by the first call." } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/RouterNetworks" } } } } } }, "400": { "$ref": "#/components/responses/Problem400" }, "401": { "$ref": "#/components/responses/Problem401" }, "402": { "$ref": "#/components/responses/Problem402" }, "403": { "$ref": "#/components/responses/Problem403" }, "404": { "$ref": "#/components/responses/Problem404" }, "409": { "$ref": "#/components/responses/Problem409" }, "422": { "$ref": "#/components/responses/Problem422" }, "429": { "$ref": "#/components/responses/Problem429" }, "500": { "$ref": "#/components/responses/Problem500" }, "503": { "$ref": "#/components/responses/Problem503" }, "415": { "$ref": "#/components/responses/Problem415" } }, "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Identifier of the resource.", "schema": { "type": "integer" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Repeat-safety key. Repeating the same key with the same body replays the stored response.", "schema": { "type": "string", "minLength": 8, "maxLength": 255 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "interface": { "type": "string", "minLength": 4, "maxLength": 8, "pattern": "^eth[1-9]\\d*$", "description": "Router interface to configure, for example eth1." }, "enabled": { "type": "boolean", "description": "Whether the router hands out addresses on this interface." }, "range_start": { "type": "string", "minLength": 7, "maxLength": 15, "pattern": "^(\\d{1,3}\\.){3}\\d{1,3}$", "description": "First address to hand out. Must sit inside the network's subnet." }, "range_end": { "type": "string", "minLength": 7, "maxLength": 15, "pattern": "^(\\d{1,3}\\.){3}\\d{1,3}$", "description": "Last address to hand out." } }, "additionalProperties": false, "required": [ "interface", "enabled" ] } } } } } }, "/servers/{id}/router/firewall-rules": { "get": { "operationId": "router_firewall_rule_list", "tags": [ "Router" ], "summary": "List router firewall rules", "description": "Access rules of the router, in priority order. Rules created by hand inside the router are listed too; those with conditions outside this API are marked non-editable.", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "description": "Identifier of this call." } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/RouterFirewallRule" } } } } } } }, "400": { "$ref": "#/components/responses/Problem400" }, "401": { "$ref": "#/components/responses/Problem401" }, "402": { "$ref": "#/components/responses/Problem402" }, "403": { "$ref": "#/components/responses/Problem403" }, "404": { "$ref": "#/components/responses/Problem404" }, "409": { "$ref": "#/components/responses/Problem409" }, "422": { "$ref": "#/components/responses/Problem422" }, "429": { "$ref": "#/components/responses/Problem429" }, "500": { "$ref": "#/components/responses/Problem500" }, "503": { "$ref": "#/components/responses/Problem503" } }, "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Identifier of the resource.", "schema": { "type": "integer" } } ] }, "post": { "operationId": "router_firewall_rule_create", "tags": [ "Router" ], "summary": "Create a router firewall rule", "description": "Adds one access rule to the router. The platform picks the next free priority unless you set one; a priority already in use is refused with router_rule_taken. The first drop or reject rule also switches on the router's stateful policy (established and related traffic is accepted), so replies to allowed connections keep flowing. The operation is synchronous, a few seconds at most. Send an Idempotency-Key: repeating a create without one adds a second identical rule under a new number. The saved flag in the envelope tells whether the router wrote its boot configuration.", "security": [ { "bearerAuth": [] } ], "responses": { "201": { "description": "Created.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "description": "Identifier of this call." }, "Location": { "schema": { "type": "string" }, "description": "Path of the created resource." }, "Idempotency-Replayed": { "schema": { "type": "string", "examples": [ "true" ] }, "description": "Present and set to true when this is a stored response replayed for a repeated Idempotency-Key. The work was done by the first call." } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "saved" ], "properties": { "data": { "$ref": "#/components/schemas/RouterFirewallRule" }, "saved": { "type": "boolean", "description": "Whether the router wrote the change to its boot configuration. False means the change is applied but will not survive a router reboot: repeat a PATCH of the same rule or port forward with the same body - that saves the whole router configuration." } } } } } }, "400": { "$ref": "#/components/responses/Problem400" }, "401": { "$ref": "#/components/responses/Problem401" }, "402": { "$ref": "#/components/responses/Problem402" }, "403": { "$ref": "#/components/responses/Problem403" }, "404": { "$ref": "#/components/responses/Problem404" }, "409": { "$ref": "#/components/responses/Problem409" }, "422": { "$ref": "#/components/responses/Problem422" }, "429": { "$ref": "#/components/responses/Problem429" }, "500": { "$ref": "#/components/responses/Problem500" }, "503": { "$ref": "#/components/responses/Problem503" }, "415": { "$ref": "#/components/responses/Problem415" } }, "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Identifier of the resource.", "schema": { "type": "integer" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Repeat-safety key. Repeating the same key with the same body replays the stored response.", "schema": { "type": "string", "minLength": 8, "maxLength": 255 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "action": { "type": "string", "minLength": 4, "maxLength": 6, "pattern": "^(accept|drop|reject)$", "enum": [ "accept", "drop", "reject" ], "description": "What to do with matching traffic." }, "priority": { "type": "integer", "minimum": 2000, "maximum": 999000, "description": "Rule number, 2000 to 999000. Lower numbers are checked first. Omit it and the platform takes the next free number in steps of ten." }, "protocol": { "oneOf": [ { "type": "string", "enum": [ "tcp", "udp", "tcp_udp", "icmp" ], "minLength": 3, "maxLength": 7, "pattern": "^(tcp|udp|tcp_udp|icmp)$" }, { "type": "null" } ], "description": "Protocol to match. Omit or send null for any protocol. Required (tcp, udp or tcp_udp) when a port is given." }, "interface": { "type": [ "string", "null" ], "minLength": 4, "maxLength": 8, "pattern": "^eth\\d+$", "description": "Router interface the traffic arrives on, as the router names it (eth0 is the public side). Null means any interface." }, "source": { "type": [ "string", "null" ], "minLength": 7, "maxLength": 18, "pattern": "^(\\d{1,3}\\.){3}\\d{1,3}(/\\d{1,2})?$", "description": "IPv4 address or IPv4/prefix the traffic comes from. Null means any." }, "destination": { "type": [ "string", "null" ], "minLength": 7, "maxLength": 18, "pattern": "^(\\d{1,3}\\.){3}\\d{1,3}(/\\d{1,2})?$", "description": "IPv4 address or IPv4/prefix the traffic goes to. Null means any." }, "source_port": { "type": [ "string", "null" ], "minLength": 1, "maxLength": 200, "pattern": "^\\d{1,5}(-\\d{1,5})?(,\\d{1,5}(-\\d{1,5})?)*$", "description": "A port, a comma-separated list or a dash range (10000-20000), up to 200 characters." }, "destination_port": { "type": [ "string", "null" ], "minLength": 1, "maxLength": 200, "pattern": "^\\d{1,5}(-\\d{1,5})?(,\\d{1,5}(-\\d{1,5})?)*$", "description": "A port, a comma-separated list or a dash range (10000-20000), up to 200 characters." }, "enabled": { "type": "boolean", "description": "Whether the rule is active. Defaults to true." }, "description": { "type": [ "string", "null" ], "minLength": 1, "maxLength": 120, "pattern": "^[^\\x00-\\x1F\\x7F]+$", "description": "Free text, up to 120 characters, no control characters." } }, "additionalProperties": false, "required": [ "action" ] } } } } } }, "/servers/{id}/router/firewall-rules/{rule}": { "get": { "operationId": "router_firewall_rule_get", "tags": [ "Router" ], "summary": "Get a router firewall rule", "description": "One access rule by its number.", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "description": "Identifier of this call." } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/RouterFirewallRule" } } } } } }, "400": { "$ref": "#/components/responses/Problem400" }, "401": { "$ref": "#/components/responses/Problem401" }, "402": { "$ref": "#/components/responses/Problem402" }, "403": { "$ref": "#/components/responses/Problem403" }, "404": { "$ref": "#/components/responses/Problem404" }, "409": { "$ref": "#/components/responses/Problem409" }, "422": { "$ref": "#/components/responses/Problem422" }, "429": { "$ref": "#/components/responses/Problem429" }, "500": { "$ref": "#/components/responses/Problem500" }, "503": { "$ref": "#/components/responses/Problem503" } }, "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Identifier of the resource.", "schema": { "type": "integer" } }, { "name": "rule", "in": "path", "required": true, "description": "Rule number on the router - the id (and priority) returned by the listing.", "schema": { "type": "integer" } } ] }, "patch": { "operationId": "router_firewall_rule_update", "tags": [ "Router" ], "summary": "Change a router firewall rule", "description": "Partial update: fields you omit keep their value, a field set to null is cleared. The priority cannot be changed - delete and recreate instead. A rule marked non-editable is refused with router_rule_not_editable. Repeating a PATCH with the same body is harmless and saves the router configuration again, which is the way to recover from saved: false.", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "description": "Identifier of this call." }, "Idempotency-Replayed": { "schema": { "type": "string", "examples": [ "true" ] }, "description": "Present and set to true when this is a stored response replayed for a repeated Idempotency-Key. The work was done by the first call." } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "saved" ], "properties": { "data": { "$ref": "#/components/schemas/RouterFirewallRule" }, "saved": { "type": "boolean", "description": "Whether the router wrote the change to its boot configuration. False means the change is applied but will not survive a router reboot: repeat a PATCH of the same rule or port forward with the same body - that saves the whole router configuration." } } } } } }, "400": { "$ref": "#/components/responses/Problem400" }, "401": { "$ref": "#/components/responses/Problem401" }, "402": { "$ref": "#/components/responses/Problem402" }, "403": { "$ref": "#/components/responses/Problem403" }, "404": { "$ref": "#/components/responses/Problem404" }, "409": { "$ref": "#/components/responses/Problem409" }, "422": { "$ref": "#/components/responses/Problem422" }, "429": { "$ref": "#/components/responses/Problem429" }, "500": { "$ref": "#/components/responses/Problem500" }, "503": { "$ref": "#/components/responses/Problem503" }, "415": { "$ref": "#/components/responses/Problem415" } }, "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Identifier of the resource.", "schema": { "type": "integer" } }, { "name": "rule", "in": "path", "required": true, "description": "Rule number on the router - the id (and priority) returned by the listing.", "schema": { "type": "integer" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Repeat-safety key. Repeating the same key with the same body replays the stored response.", "schema": { "type": "string", "minLength": 8, "maxLength": 255 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "action": { "type": "string", "minLength": 4, "maxLength": 6, "pattern": "^(accept|drop|reject)$", "enum": [ "accept", "drop", "reject" ], "description": "What to do with matching traffic." }, "protocol": { "oneOf": [ { "type": "string", "enum": [ "tcp", "udp", "tcp_udp", "icmp" ], "minLength": 3, "maxLength": 7, "pattern": "^(tcp|udp|tcp_udp|icmp)$" }, { "type": "null" } ], "description": "Protocol to match. Null clears it (any protocol)." }, "interface": { "type": [ "string", "null" ], "minLength": 4, "maxLength": 8, "pattern": "^eth\\d+$", "description": "Router interface the traffic arrives on. Null clears it (any interface)." }, "source": { "type": [ "string", "null" ], "minLength": 7, "maxLength": 18, "pattern": "^(\\d{1,3}\\.){3}\\d{1,3}(/\\d{1,2})?$", "description": "IPv4 address or IPv4/prefix. Null clears it." }, "destination": { "type": [ "string", "null" ], "minLength": 7, "maxLength": 18, "pattern": "^(\\d{1,3}\\.){3}\\d{1,3}(/\\d{1,2})?$", "description": "IPv4 address or IPv4/prefix. Null clears it." }, "source_port": { "type": [ "string", "null" ], "minLength": 1, "maxLength": 200, "pattern": "^\\d{1,5}(-\\d{1,5})?(,\\d{1,5}(-\\d{1,5})?)*$", "description": "A port, a list or a dash range. Null clears it." }, "destination_port": { "type": [ "string", "null" ], "minLength": 1, "maxLength": 200, "pattern": "^\\d{1,5}(-\\d{1,5})?(,\\d{1,5}(-\\d{1,5})?)*$", "description": "A port, a list or a dash range. Null clears it." }, "enabled": { "type": "boolean", "description": "Whether the rule is active." }, "description": { "type": [ "string", "null" ], "minLength": 1, "maxLength": 120, "pattern": "^[^\\x00-\\x1F\\x7F]+$", "description": "Free text, up to 120 characters. Null clears it." } }, "additionalProperties": false, "anyOf": [ { "required": [ "action" ] }, { "required": [ "protocol" ] }, { "required": [ "interface" ] }, { "required": [ "source" ] }, { "required": [ "destination" ] }, { "required": [ "source_port" ] }, { "required": [ "destination_port" ] }, { "required": [ "enabled" ] }, { "required": [ "description" ] } ], "description": "At least one of these fields must be present." } } } } }, "delete": { "operationId": "router_firewall_rule_delete", "tags": [ "Router" ], "summary": "Delete a router firewall rule", "description": "Removes the rule, editable or not. Allowed on a suspended project and with an overdue invoice: you must always be able to take down a rule you put up. Deleting a rule that is already gone answers 404.", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "description": "Identifier of this call." }, "Idempotency-Replayed": { "schema": { "type": "string", "examples": [ "true" ] }, "description": "Present and set to true when this is a stored response replayed for a repeated Idempotency-Key. The work was done by the first call." } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "saved" ], "properties": { "data": { "$ref": "#/components/schemas/Deleted" }, "saved": { "type": "boolean", "description": "Whether the router wrote the change to its boot configuration. False means the change is applied but will not survive a router reboot: repeat a PATCH of the same rule or port forward with the same body - that saves the whole router configuration." } } } } } }, "400": { "$ref": "#/components/responses/Problem400" }, "401": { "$ref": "#/components/responses/Problem401" }, "402": { "$ref": "#/components/responses/Problem402" }, "403": { "$ref": "#/components/responses/Problem403" }, "404": { "$ref": "#/components/responses/Problem404" }, "409": { "$ref": "#/components/responses/Problem409" }, "422": { "$ref": "#/components/responses/Problem422" }, "429": { "$ref": "#/components/responses/Problem429" }, "500": { "$ref": "#/components/responses/Problem500" }, "503": { "$ref": "#/components/responses/Problem503" }, "415": { "$ref": "#/components/responses/Problem415" } }, "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Identifier of the resource.", "schema": { "type": "integer" } }, { "name": "rule", "in": "path", "required": true, "description": "Rule number on the router - the id (and priority) returned by the listing.", "schema": { "type": "integer" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Repeat-safety key. Repeating the same key with the same body replays the stored response.", "schema": { "type": "string", "minLength": 8, "maxLength": 255 } } ] } }, "/servers/{id}/router/networks": { "get": { "operationId": "router_networks_get", "tags": [ "Router" ], "summary": "List router networks", "description": "Networks this router serves, with the address range it hands out on each.", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "description": "Identifier of this call." } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/RouterNetworks" } } } } } }, "400": { "$ref": "#/components/responses/Problem400" }, "401": { "$ref": "#/components/responses/Problem401" }, "402": { "$ref": "#/components/responses/Problem402" }, "403": { "$ref": "#/components/responses/Problem403" }, "404": { "$ref": "#/components/responses/Problem404" }, "409": { "$ref": "#/components/responses/Problem409" }, "422": { "$ref": "#/components/responses/Problem422" }, "429": { "$ref": "#/components/responses/Problem429" }, "500": { "$ref": "#/components/responses/Problem500" }, "503": { "$ref": "#/components/responses/Problem503" } }, "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Identifier of the resource.", "schema": { "type": "integer" } } ] } }, "/servers/{id}/router/openvpn": { "get": { "operationId": "router_openvpn_get", "tags": [ "Router" ], "summary": "Get the OpenVPN tunnel", "description": "State of the router's OpenVPN tunnel: whether it is on, its interface, subnet, port and endpoint, and which private networks it pushes to devices.", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "description": "Identifier of this call." } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/OpenVpnTunnel" } } } } } }, "400": { "$ref": "#/components/responses/Problem400" }, "401": { "$ref": "#/components/responses/Problem401" }, "402": { "$ref": "#/components/responses/Problem402" }, "403": { "$ref": "#/components/responses/Problem403" }, "404": { "$ref": "#/components/responses/Problem404" }, "409": { "$ref": "#/components/responses/Problem409" }, "422": { "$ref": "#/components/responses/Problem422" }, "429": { "$ref": "#/components/responses/Problem429" }, "500": { "$ref": "#/components/responses/Problem500" }, "503": { "$ref": "#/components/responses/Problem503" } }, "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Identifier of the resource.", "schema": { "type": "integer" } } ] }, "put": { "operationId": "router_openvpn_set", "tags": [ "Router" ], "summary": "Switch the OpenVPN tunnel on or off", "description": "Enabling creates the tunnel on first use - the platform issues a certificate authority for this router, which takes a few seconds - or brings it back after it was switched off, keeping the devices. Enabling an already enabled tunnel is harmless and pushes routes for networks attached since (see networks_missing) and the current certificate revocation list. Disabling is allowed on a suspended project and with an overdue invoice.", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "description": "Identifier of this call." }, "Idempotency-Replayed": { "schema": { "type": "string", "examples": [ "true" ] }, "description": "Present and set to true when this is a stored response replayed for a repeated Idempotency-Key. The work was done by the first call." } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "saved" ], "properties": { "data": { "$ref": "#/components/schemas/OpenVpnTunnel" }, "saved": { "type": "boolean", "description": "Whether the router wrote the change to its boot configuration. False means the change is applied but will not survive a router reboot: repeat a PATCH of the same rule or port forward with the same body - that saves the whole router configuration." } } } } } }, "400": { "$ref": "#/components/responses/Problem400" }, "401": { "$ref": "#/components/responses/Problem401" }, "402": { "$ref": "#/components/responses/Problem402" }, "403": { "$ref": "#/components/responses/Problem403" }, "404": { "$ref": "#/components/responses/Problem404" }, "409": { "$ref": "#/components/responses/Problem409" }, "422": { "$ref": "#/components/responses/Problem422" }, "429": { "$ref": "#/components/responses/Problem429" }, "500": { "$ref": "#/components/responses/Problem500" }, "503": { "$ref": "#/components/responses/Problem503" }, "415": { "$ref": "#/components/responses/Problem415" } }, "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Identifier of the resource.", "schema": { "type": "integer" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Repeat-safety key. Repeating the same key with the same body replays the stored response.", "schema": { "type": "string", "minLength": 8, "maxLength": 255 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "enabled": { "type": "boolean", "description": "true switches the tunnel on (issuing the certificate authority on first use) and pushes current routes, false switches it off and keeps the devices." } }, "additionalProperties": false, "required": [ "enabled" ] } } } } } }, "/servers/{id}/router/openvpn/devices": { "get": { "operationId": "router_openvpn_device_list", "tags": [ "Router" ], "summary": "List OpenVPN devices", "description": "Devices of the tunnel. Profiles are never included.", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "description": "Identifier of this call." } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/OpenVpnDevice" } } } } } } }, "400": { "$ref": "#/components/responses/Problem400" }, "401": { "$ref": "#/components/responses/Problem401" }, "402": { "$ref": "#/components/responses/Problem402" }, "403": { "$ref": "#/components/responses/Problem403" }, "404": { "$ref": "#/components/responses/Problem404" }, "409": { "$ref": "#/components/responses/Problem409" }, "422": { "$ref": "#/components/responses/Problem422" }, "429": { "$ref": "#/components/responses/Problem429" }, "500": { "$ref": "#/components/responses/Problem500" }, "503": { "$ref": "#/components/responses/Problem503" } }, "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Identifier of the resource.", "schema": { "type": "integer" } } ] }, "post": { "operationId": "router_openvpn_device_create", "tags": [ "Router" ], "summary": "Create an OpenVPN device", "description": "Issues a certificate for a new device and returns the complete .ovpn profile, private key included, EXACTLY ONCE: store it immediately, it cannot be read again. A lost profile means delete the device (which revokes its certificate) and create a new one. The tunnel must be enabled first. Up to ten devices per tunnel. Send an Idempotency-Key: a repeat with the same key within a day replays the same response, profile included, so a dropped connection does not cost you the device.", "security": [ { "bearerAuth": [] } ], "responses": { "201": { "description": "Created.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "description": "Identifier of this call." }, "Location": { "schema": { "type": "string" }, "description": "Path of the created resource." }, "Idempotency-Replayed": { "schema": { "type": "string", "examples": [ "true" ] }, "description": "Present and set to true when this is a stored response replayed for a repeated Idempotency-Key. The work was done by the first call." } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "saved" ], "properties": { "data": { "$ref": "#/components/schemas/OpenVpnDeviceCreated" }, "saved": { "type": "boolean", "description": "Whether the router wrote the change to its boot configuration. False means the change is applied but will not survive a router reboot: repeat a PATCH of the same rule or port forward with the same body - that saves the whole router configuration." } } } } } }, "400": { "$ref": "#/components/responses/Problem400" }, "401": { "$ref": "#/components/responses/Problem401" }, "402": { "$ref": "#/components/responses/Problem402" }, "403": { "$ref": "#/components/responses/Problem403" }, "404": { "$ref": "#/components/responses/Problem404" }, "409": { "$ref": "#/components/responses/Problem409" }, "422": { "$ref": "#/components/responses/Problem422" }, "429": { "$ref": "#/components/responses/Problem429" }, "500": { "$ref": "#/components/responses/Problem500" }, "503": { "$ref": "#/components/responses/Problem503" }, "415": { "$ref": "#/components/responses/Problem415" } }, "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Identifier of the resource.", "schema": { "type": "integer" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Repeat-safety key. Repeating the same key with the same body replays the stored response.", "schema": { "type": "string", "minLength": 8, "maxLength": 255 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 64, "pattern": "^[^\\x00-\\x1F\\x7F]+$", "description": "Name of the device, up to 64 characters." } }, "additionalProperties": false, "required": [ "name" ] } } } } } }, "/servers/{id}/router/openvpn/devices/{device}": { "get": { "operationId": "router_openvpn_device_get", "tags": [ "Router" ], "summary": "Get an OpenVPN device", "description": "One device by its identifier. The profile is not part of it - it was returned once, on create.", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "description": "Identifier of this call." } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/OpenVpnDevice" } } } } } }, "400": { "$ref": "#/components/responses/Problem400" }, "401": { "$ref": "#/components/responses/Problem401" }, "402": { "$ref": "#/components/responses/Problem402" }, "403": { "$ref": "#/components/responses/Problem403" }, "404": { "$ref": "#/components/responses/Problem404" }, "409": { "$ref": "#/components/responses/Problem409" }, "422": { "$ref": "#/components/responses/Problem422" }, "429": { "$ref": "#/components/responses/Problem429" }, "500": { "$ref": "#/components/responses/Problem500" }, "503": { "$ref": "#/components/responses/Problem503" } }, "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Identifier of the resource.", "schema": { "type": "integer" } }, { "name": "device", "in": "path", "required": true, "description": "Device identifier (dev1, dev2, ...), as returned by the devices listing.", "schema": { "type": "string", "pattern": "^(?:dev\\d+)$" } } ] }, "patch": { "operationId": "router_openvpn_device_update", "tags": [ "Router" ], "summary": "Rename an OpenVPN device", "description": "Changes the name on the platform only; the router is not touched, although it must be reachable.", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "description": "Identifier of this call." }, "Idempotency-Replayed": { "schema": { "type": "string", "examples": [ "true" ] }, "description": "Present and set to true when this is a stored response replayed for a repeated Idempotency-Key. The work was done by the first call." } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "saved" ], "properties": { "data": { "$ref": "#/components/schemas/OpenVpnDevice" }, "saved": { "type": "boolean", "description": "Whether the router wrote the change to its boot configuration. False means the change is applied but will not survive a router reboot: repeat a PATCH of the same rule or port forward with the same body - that saves the whole router configuration." } } } } } }, "400": { "$ref": "#/components/responses/Problem400" }, "401": { "$ref": "#/components/responses/Problem401" }, "402": { "$ref": "#/components/responses/Problem402" }, "403": { "$ref": "#/components/responses/Problem403" }, "404": { "$ref": "#/components/responses/Problem404" }, "409": { "$ref": "#/components/responses/Problem409" }, "422": { "$ref": "#/components/responses/Problem422" }, "429": { "$ref": "#/components/responses/Problem429" }, "500": { "$ref": "#/components/responses/Problem500" }, "503": { "$ref": "#/components/responses/Problem503" }, "415": { "$ref": "#/components/responses/Problem415" } }, "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Identifier of the resource.", "schema": { "type": "integer" } }, { "name": "device", "in": "path", "required": true, "description": "Device identifier (dev1, dev2, ...), as returned by the devices listing.", "schema": { "type": "string", "pattern": "^(?:dev\\d+)$" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Repeat-safety key. Repeating the same key with the same body replays the stored response.", "schema": { "type": "string", "minLength": 8, "maxLength": 255 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 64, "pattern": "^[^\\x00-\\x1F\\x7F]+$", "description": "New name of the device." } }, "additionalProperties": false, "required": [ "name" ] } } } } }, "delete": { "operationId": "router_openvpn_device_delete", "tags": [ "Router" ], "summary": "Delete an OpenVPN device", "description": "Revokes the device certificate and pushes the revocation list to the router. If the router does not accept the push, the device is still removed and revocation_pending is true: the router keeps accepting that certificate until you send PUT /v1/servers/{id}/router/openvpn with enabled: true, which pushes the list again. Allowed on a suspended project and with an overdue invoice.", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "description": "Identifier of this call." }, "Idempotency-Replayed": { "schema": { "type": "string", "examples": [ "true" ] }, "description": "Present and set to true when this is a stored response replayed for a repeated Idempotency-Key. The work was done by the first call." } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "saved" ], "properties": { "data": { "$ref": "#/components/schemas/DeletedDevice" }, "saved": { "type": "boolean", "description": "Whether the router wrote the change to its boot configuration. False means the change is applied but will not survive a router reboot: repeat a PATCH of the same rule or port forward with the same body - that saves the whole router configuration." } } } } } }, "400": { "$ref": "#/components/responses/Problem400" }, "401": { "$ref": "#/components/responses/Problem401" }, "402": { "$ref": "#/components/responses/Problem402" }, "403": { "$ref": "#/components/responses/Problem403" }, "404": { "$ref": "#/components/responses/Problem404" }, "409": { "$ref": "#/components/responses/Problem409" }, "422": { "$ref": "#/components/responses/Problem422" }, "429": { "$ref": "#/components/responses/Problem429" }, "500": { "$ref": "#/components/responses/Problem500" }, "503": { "$ref": "#/components/responses/Problem503" }, "415": { "$ref": "#/components/responses/Problem415" } }, "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Identifier of the resource.", "schema": { "type": "integer" } }, { "name": "device", "in": "path", "required": true, "description": "Device identifier (dev1, dev2, ...), as returned by the devices listing.", "schema": { "type": "string", "pattern": "^(?:dev\\d+)$" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Repeat-safety key. Repeating the same key with the same body replays the stored response.", "schema": { "type": "string", "minLength": 8, "maxLength": 255 } } ] } }, "/servers/{id}/router/port-forwards": { "get": { "operationId": "router_port_forward_list", "tags": [ "Router" ], "summary": "List router port forwards", "description": "Port forwards of the router, in priority order. Forwards created by hand inside the router are listed too; those with conditions outside this API are marked non-editable.", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "description": "Identifier of this call." } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/RouterPortForward" } } } } } } }, "400": { "$ref": "#/components/responses/Problem400" }, "401": { "$ref": "#/components/responses/Problem401" }, "402": { "$ref": "#/components/responses/Problem402" }, "403": { "$ref": "#/components/responses/Problem403" }, "404": { "$ref": "#/components/responses/Problem404" }, "409": { "$ref": "#/components/responses/Problem409" }, "422": { "$ref": "#/components/responses/Problem422" }, "429": { "$ref": "#/components/responses/Problem429" }, "500": { "$ref": "#/components/responses/Problem500" }, "503": { "$ref": "#/components/responses/Problem503" } }, "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Identifier of the resource.", "schema": { "type": "integer" } } ] }, "post": { "operationId": "router_port_forward_create", "tags": [ "Router" ], "summary": "Create a router port forward", "description": "Sends traffic arriving on a public port of the router to a server inside one of its private networks. The target must be a server address, not the router itself, and must lie inside a network attached to this router; a public port that covers the router's management port or its VPN port is refused. Two forwards may overlap on public ports - the lower priority wins, and the API does not check for overlaps. Synchronous, a few seconds at most. Send an Idempotency-Key: repeating a create without one adds a second identical forward. The saved flag in the envelope tells whether the router wrote its boot configuration.", "security": [ { "bearerAuth": [] } ], "responses": { "201": { "description": "Created.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "description": "Identifier of this call." }, "Location": { "schema": { "type": "string" }, "description": "Path of the created resource." }, "Idempotency-Replayed": { "schema": { "type": "string", "examples": [ "true" ] }, "description": "Present and set to true when this is a stored response replayed for a repeated Idempotency-Key. The work was done by the first call." } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "saved" ], "properties": { "data": { "$ref": "#/components/schemas/RouterPortForward" }, "saved": { "type": "boolean", "description": "Whether the router wrote the change to its boot configuration. False means the change is applied but will not survive a router reboot: repeat a PATCH of the same rule or port forward with the same body - that saves the whole router configuration." } } } } } }, "400": { "$ref": "#/components/responses/Problem400" }, "401": { "$ref": "#/components/responses/Problem401" }, "402": { "$ref": "#/components/responses/Problem402" }, "403": { "$ref": "#/components/responses/Problem403" }, "404": { "$ref": "#/components/responses/Problem404" }, "409": { "$ref": "#/components/responses/Problem409" }, "422": { "$ref": "#/components/responses/Problem422" }, "429": { "$ref": "#/components/responses/Problem429" }, "500": { "$ref": "#/components/responses/Problem500" }, "503": { "$ref": "#/components/responses/Problem503" }, "415": { "$ref": "#/components/responses/Problem415" } }, "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Identifier of the resource.", "schema": { "type": "integer" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Repeat-safety key. Repeating the same key with the same body replays the stored response.", "schema": { "type": "string", "minLength": 8, "maxLength": 255 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "public_port": { "type": "string", "minLength": 1, "maxLength": 200, "pattern": "^\\d{1,5}(-\\d{1,5})?(,\\d{1,5}(-\\d{1,5})?)*$", "description": "Port on the router's public address: a number, a comma-separated list or a dash range (10000-20000), up to 200 characters. Must not cover the router's management port or its VPN port." }, "target": { "type": "string", "minLength": 7, "maxLength": 15, "pattern": "^(\\d{1,3}\\.){3}\\d{1,3}$", "description": "IPv4 address of the server to send the traffic to. Must lie inside a private network attached to this router and must not be the router itself." }, "target_port": { "type": [ "string", "null" ], "minLength": 1, "maxLength": 5, "pattern": "^\\d{1,5}$", "description": "Port on the target. Omit or send null to keep the port the traffic arrived on." }, "priority": { "type": "integer", "minimum": 2000, "maximum": 999000, "description": "Forward number, 2000 to 999000. Lower numbers are checked first. Omit it and the platform takes the next free number in steps of ten." }, "protocol": { "type": "string", "minLength": 3, "maxLength": 7, "pattern": "^(tcp|udp|tcp_udp)$", "enum": [ "tcp", "udp", "tcp_udp" ], "default": "tcp", "description": "tcp, udp or tcp_udp. Defaults to tcp." }, "source": { "type": [ "string", "null" ], "minLength": 7, "maxLength": 18, "pattern": "^(\\d{1,3}\\.){3}\\d{1,3}(/\\d{1,2})?$", "description": "IPv4 address or IPv4/prefix allowed to use the forward. Null means anyone." }, "enabled": { "type": "boolean", "description": "Whether the forward is active. Defaults to true." }, "description": { "type": [ "string", "null" ], "minLength": 1, "maxLength": 120, "pattern": "^[^\\x00-\\x1F\\x7F]+$", "description": "Free text, up to 120 characters, no control characters." } }, "additionalProperties": false, "required": [ "public_port", "target" ] } } } } } }, "/servers/{id}/router/port-forwards/{rule}": { "get": { "operationId": "router_port_forward_get", "tags": [ "Router" ], "summary": "Get a router port forward", "description": "One port forward by its number.", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "description": "Identifier of this call." } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/RouterPortForward" } } } } } }, "400": { "$ref": "#/components/responses/Problem400" }, "401": { "$ref": "#/components/responses/Problem401" }, "402": { "$ref": "#/components/responses/Problem402" }, "403": { "$ref": "#/components/responses/Problem403" }, "404": { "$ref": "#/components/responses/Problem404" }, "409": { "$ref": "#/components/responses/Problem409" }, "422": { "$ref": "#/components/responses/Problem422" }, "429": { "$ref": "#/components/responses/Problem429" }, "500": { "$ref": "#/components/responses/Problem500" }, "503": { "$ref": "#/components/responses/Problem503" } }, "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Identifier of the resource.", "schema": { "type": "integer" } }, { "name": "rule", "in": "path", "required": true, "description": "Rule number on the router - the id (and priority) returned by the listing.", "schema": { "type": "integer" } } ] }, "patch": { "operationId": "router_port_forward_update", "tags": [ "Router" ], "summary": "Change a router port forward", "description": "Partial update: fields you omit keep their value, a field set to null is cleared. The priority cannot be changed - delete and recreate instead. A forward marked non-editable is refused with router_rule_not_editable. Repeating a PATCH with the same body saves the router configuration again, which is the way to recover from saved: false.", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "description": "Identifier of this call." }, "Idempotency-Replayed": { "schema": { "type": "string", "examples": [ "true" ] }, "description": "Present and set to true when this is a stored response replayed for a repeated Idempotency-Key. The work was done by the first call." } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "saved" ], "properties": { "data": { "$ref": "#/components/schemas/RouterPortForward" }, "saved": { "type": "boolean", "description": "Whether the router wrote the change to its boot configuration. False means the change is applied but will not survive a router reboot: repeat a PATCH of the same rule or port forward with the same body - that saves the whole router configuration." } } } } } }, "400": { "$ref": "#/components/responses/Problem400" }, "401": { "$ref": "#/components/responses/Problem401" }, "402": { "$ref": "#/components/responses/Problem402" }, "403": { "$ref": "#/components/responses/Problem403" }, "404": { "$ref": "#/components/responses/Problem404" }, "409": { "$ref": "#/components/responses/Problem409" }, "422": { "$ref": "#/components/responses/Problem422" }, "429": { "$ref": "#/components/responses/Problem429" }, "500": { "$ref": "#/components/responses/Problem500" }, "503": { "$ref": "#/components/responses/Problem503" }, "415": { "$ref": "#/components/responses/Problem415" } }, "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Identifier of the resource.", "schema": { "type": "integer" } }, { "name": "rule", "in": "path", "required": true, "description": "Rule number on the router - the id (and priority) returned by the listing.", "schema": { "type": "integer" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Repeat-safety key. Repeating the same key with the same body replays the stored response.", "schema": { "type": "string", "minLength": 8, "maxLength": 255 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "public_port": { "type": "string", "minLength": 1, "maxLength": 200, "pattern": "^\\d{1,5}(-\\d{1,5})?(,\\d{1,5}(-\\d{1,5})?)*$", "description": "Port, list or dash range on the router's public address." }, "target": { "type": "string", "minLength": 7, "maxLength": 15, "pattern": "^(\\d{1,3}\\.){3}\\d{1,3}$", "description": "IPv4 address of the server inside a private network of this router." }, "target_port": { "type": [ "string", "null" ], "minLength": 1, "maxLength": 5, "pattern": "^\\d{1,5}$", "description": "Port on the target. Null clears it (same port as arrived)." }, "protocol": { "type": "string", "minLength": 3, "maxLength": 7, "pattern": "^(tcp|udp|tcp_udp)$", "enum": [ "tcp", "udp", "tcp_udp" ], "description": "tcp, udp or tcp_udp." }, "source": { "type": [ "string", "null" ], "minLength": 7, "maxLength": 18, "pattern": "^(\\d{1,3}\\.){3}\\d{1,3}(/\\d{1,2})?$", "description": "IPv4 address or IPv4/prefix. Null clears it (anyone)." }, "enabled": { "type": "boolean", "description": "Whether the forward is active." }, "description": { "type": [ "string", "null" ], "minLength": 1, "maxLength": 120, "pattern": "^[^\\x00-\\x1F\\x7F]+$", "description": "Free text, up to 120 characters. Null clears it." } }, "additionalProperties": false, "anyOf": [ { "required": [ "public_port" ] }, { "required": [ "target" ] }, { "required": [ "target_port" ] }, { "required": [ "protocol" ] }, { "required": [ "source" ] }, { "required": [ "enabled" ] }, { "required": [ "description" ] } ], "description": "At least one of these fields must be present." } } } } }, "delete": { "operationId": "router_port_forward_delete", "tags": [ "Router" ], "summary": "Delete a router port forward", "description": "Removes the forward, editable or not. Allowed on a suspended project and with an overdue invoice. Deleting a forward that is already gone answers 404.", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "description": "Identifier of this call." }, "Idempotency-Replayed": { "schema": { "type": "string", "examples": [ "true" ] }, "description": "Present and set to true when this is a stored response replayed for a repeated Idempotency-Key. The work was done by the first call." } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "saved" ], "properties": { "data": { "$ref": "#/components/schemas/Deleted" }, "saved": { "type": "boolean", "description": "Whether the router wrote the change to its boot configuration. False means the change is applied but will not survive a router reboot: repeat a PATCH of the same rule or port forward with the same body - that saves the whole router configuration." } } } } } }, "400": { "$ref": "#/components/responses/Problem400" }, "401": { "$ref": "#/components/responses/Problem401" }, "402": { "$ref": "#/components/responses/Problem402" }, "403": { "$ref": "#/components/responses/Problem403" }, "404": { "$ref": "#/components/responses/Problem404" }, "409": { "$ref": "#/components/responses/Problem409" }, "422": { "$ref": "#/components/responses/Problem422" }, "429": { "$ref": "#/components/responses/Problem429" }, "500": { "$ref": "#/components/responses/Problem500" }, "503": { "$ref": "#/components/responses/Problem503" }, "415": { "$ref": "#/components/responses/Problem415" } }, "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Identifier of the resource.", "schema": { "type": "integer" } }, { "name": "rule", "in": "path", "required": true, "description": "Rule number on the router - the id (and priority) returned by the listing.", "schema": { "type": "integer" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Repeat-safety key. Repeating the same key with the same body replays the stored response.", "schema": { "type": "string", "minLength": 8, "maxLength": 255 } } ] } }, "/servers/{id}/router/wan-ip": { "put": { "operationId": "router_wan_ip", "tags": [ "Router" ], "summary": "Move the router's public address", "description": "Puts a different public address on the router. If this call fails midway, read the router before retrying - the address may already have moved.", "security": [ { "bearerAuth": [] } ], "responses": { "202": { "description": "Accepted. The work continues in the background - poll the task.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "description": "Identifier of this call." }, "Idempotency-Replayed": { "schema": { "type": "string", "examples": [ "true" ] }, "description": "Present and set to true when this is a stored response replayed for a repeated Idempotency-Key. The work was done by the first call." } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/RouterWanIp" }, "task": { "oneOf": [ { "$ref": "#/components/schemas/Task" }, { "type": "null" } ], "description": "Null when the work was already finished inside the request." } } } } } }, "200": { "description": "Done inside the request: the task field is null, there is nothing to wait for.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "description": "Identifier of this call." }, "Idempotency-Replayed": { "schema": { "type": "string", "examples": [ "true" ] }, "description": "Present and set to true when this is a stored response replayed for a repeated Idempotency-Key. The work was done by the first call." } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/RouterWanIp" }, "task": { "oneOf": [ { "$ref": "#/components/schemas/Task" }, { "type": "null" } ], "description": "Null when the work was already finished inside the request." } } } } } }, "400": { "$ref": "#/components/responses/Problem400" }, "401": { "$ref": "#/components/responses/Problem401" }, "402": { "$ref": "#/components/responses/Problem402" }, "403": { "$ref": "#/components/responses/Problem403" }, "404": { "$ref": "#/components/responses/Problem404" }, "409": { "$ref": "#/components/responses/Problem409" }, "422": { "$ref": "#/components/responses/Problem422" }, "429": { "$ref": "#/components/responses/Problem429" }, "500": { "$ref": "#/components/responses/Problem500" }, "503": { "$ref": "#/components/responses/Problem503" }, "415": { "$ref": "#/components/responses/Problem415" } }, "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Identifier of the resource.", "schema": { "type": "integer" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Repeat-safety key. Repeating the same key with the same body replays the stored response.", "schema": { "type": "string", "minLength": 8, "maxLength": 255 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "ip_id": { "type": "integer", "minimum": 1, "description": "The public address to move onto the router. It must already belong to the project." } }, "additionalProperties": false, "required": [ "ip_id" ] } } } } } }, "/servers/{id}/router/wireguard": { "get": { "operationId": "router_wireguard_get", "tags": [ "Router" ], "summary": "Get the WireGuard tunnel", "description": "State of the router's WireGuard tunnel: whether it is on, its interface, subnet, port, public key and endpoint, and what a device should route through it.", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "description": "Identifier of this call." } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/WireGuardTunnel" } } } } } }, "400": { "$ref": "#/components/responses/Problem400" }, "401": { "$ref": "#/components/responses/Problem401" }, "402": { "$ref": "#/components/responses/Problem402" }, "403": { "$ref": "#/components/responses/Problem403" }, "404": { "$ref": "#/components/responses/Problem404" }, "409": { "$ref": "#/components/responses/Problem409" }, "422": { "$ref": "#/components/responses/Problem422" }, "429": { "$ref": "#/components/responses/Problem429" }, "500": { "$ref": "#/components/responses/Problem500" }, "503": { "$ref": "#/components/responses/Problem503" } }, "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Identifier of the resource.", "schema": { "type": "integer" } } ] }, "put": { "operationId": "router_wireguard_set", "tags": [ "Router" ], "summary": "Switch the WireGuard tunnel on or off", "description": "Enabling creates the tunnel on first use (the platform picks the port, the subnet and the key) or brings it back after it was switched off, keeping the devices. Disabling stops the router listening; the key and the devices stay recorded. Both directions are idempotent. Disabling is allowed on a suspended project and with an overdue invoice.", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "description": "Identifier of this call." }, "Idempotency-Replayed": { "schema": { "type": "string", "examples": [ "true" ] }, "description": "Present and set to true when this is a stored response replayed for a repeated Idempotency-Key. The work was done by the first call." } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "saved" ], "properties": { "data": { "$ref": "#/components/schemas/WireGuardTunnel" }, "saved": { "type": "boolean", "description": "Whether the router wrote the change to its boot configuration. False means the change is applied but will not survive a router reboot: repeat a PATCH of the same rule or port forward with the same body - that saves the whole router configuration." } } } } } }, "400": { "$ref": "#/components/responses/Problem400" }, "401": { "$ref": "#/components/responses/Problem401" }, "402": { "$ref": "#/components/responses/Problem402" }, "403": { "$ref": "#/components/responses/Problem403" }, "404": { "$ref": "#/components/responses/Problem404" }, "409": { "$ref": "#/components/responses/Problem409" }, "422": { "$ref": "#/components/responses/Problem422" }, "429": { "$ref": "#/components/responses/Problem429" }, "500": { "$ref": "#/components/responses/Problem500" }, "503": { "$ref": "#/components/responses/Problem503" }, "415": { "$ref": "#/components/responses/Problem415" } }, "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Identifier of the resource.", "schema": { "type": "integer" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Repeat-safety key. Repeating the same key with the same body replays the stored response.", "schema": { "type": "string", "minLength": 8, "maxLength": 255 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "enabled": { "type": "boolean", "description": "true switches the tunnel on (creating it on first use), false switches it off and keeps the devices." } }, "additionalProperties": false, "required": [ "enabled" ] } } } } } }, "/servers/{id}/router/wireguard/devices": { "get": { "operationId": "router_wireguard_device_list", "tags": [ "Router" ], "summary": "List WireGuard devices", "description": "Devices (peers) of the tunnel, including peers added inside the router by hand (foreign) and devices whose peer is currently absent from the router (present: false).", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "description": "Identifier of this call." } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/WireGuardDevice" } } } } } } }, "400": { "$ref": "#/components/responses/Problem400" }, "401": { "$ref": "#/components/responses/Problem401" }, "402": { "$ref": "#/components/responses/Problem402" }, "403": { "$ref": "#/components/responses/Problem403" }, "404": { "$ref": "#/components/responses/Problem404" }, "409": { "$ref": "#/components/responses/Problem409" }, "422": { "$ref": "#/components/responses/Problem422" }, "429": { "$ref": "#/components/responses/Problem429" }, "500": { "$ref": "#/components/responses/Problem500" }, "503": { "$ref": "#/components/responses/Problem503" } }, "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Identifier of the resource.", "schema": { "type": "integer" } } ] }, "post": { "operationId": "router_wireguard_device_create", "tags": [ "Router" ], "summary": "Create a WireGuard device", "description": "Registers a device by its public key; generate the key pair on the device and keep the private key there - the platform never sees it. The tunnel must be enabled first. The response carries the device plus a config block with everything the device needs for its [Interface] and [Peer] sections; all of it can be read again from the tunnel and the device, so nothing is lost if the response is missed. Up to ten devices per tunnel.", "security": [ { "bearerAuth": [] } ], "responses": { "201": { "description": "Created.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "description": "Identifier of this call." }, "Location": { "schema": { "type": "string" }, "description": "Path of the created resource." }, "Idempotency-Replayed": { "schema": { "type": "string", "examples": [ "true" ] }, "description": "Present and set to true when this is a stored response replayed for a repeated Idempotency-Key. The work was done by the first call." } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "saved" ], "properties": { "data": { "$ref": "#/components/schemas/WireGuardDeviceCreated" }, "saved": { "type": "boolean", "description": "Whether the router wrote the change to its boot configuration. False means the change is applied but will not survive a router reboot: repeat a PATCH of the same rule or port forward with the same body - that saves the whole router configuration." } } } } } }, "400": { "$ref": "#/components/responses/Problem400" }, "401": { "$ref": "#/components/responses/Problem401" }, "402": { "$ref": "#/components/responses/Problem402" }, "403": { "$ref": "#/components/responses/Problem403" }, "404": { "$ref": "#/components/responses/Problem404" }, "409": { "$ref": "#/components/responses/Problem409" }, "422": { "$ref": "#/components/responses/Problem422" }, "429": { "$ref": "#/components/responses/Problem429" }, "500": { "$ref": "#/components/responses/Problem500" }, "503": { "$ref": "#/components/responses/Problem503" }, "415": { "$ref": "#/components/responses/Problem415" } }, "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Identifier of the resource.", "schema": { "type": "integer" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Repeat-safety key. Repeating the same key with the same body replays the stored response.", "schema": { "type": "string", "minLength": 8, "maxLength": 255 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 64, "pattern": "^[^\\x00-\\x1F\\x7F]+$", "description": "Name of the device, up to 64 characters." }, "public_key": { "type": "string", "minLength": 44, "maxLength": 44, "pattern": "^[A-Za-z0-9+/]{43}=$", "description": "Public key generated on the device, 44 characters base64. Keep the private key on the device." } }, "additionalProperties": false, "required": [ "name", "public_key" ] } } } } } }, "/servers/{id}/router/wireguard/devices/{device}": { "get": { "operationId": "router_wireguard_device_get", "tags": [ "Router" ], "summary": "Get a WireGuard device", "description": "One device by its identifier.", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "description": "Identifier of this call." } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/WireGuardDevice" } } } } } }, "400": { "$ref": "#/components/responses/Problem400" }, "401": { "$ref": "#/components/responses/Problem401" }, "402": { "$ref": "#/components/responses/Problem402" }, "403": { "$ref": "#/components/responses/Problem403" }, "404": { "$ref": "#/components/responses/Problem404" }, "409": { "$ref": "#/components/responses/Problem409" }, "422": { "$ref": "#/components/responses/Problem422" }, "429": { "$ref": "#/components/responses/Problem429" }, "500": { "$ref": "#/components/responses/Problem500" }, "503": { "$ref": "#/components/responses/Problem503" } }, "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Identifier of the resource.", "schema": { "type": "integer" } }, { "name": "device", "in": "path", "required": true, "description": "Device identifier (dev1, dev2, ...), as returned by the devices listing.", "schema": { "type": "string", "pattern": "^(?:dev\\d+)$" } } ] }, "patch": { "operationId": "router_wireguard_device_update", "tags": [ "Router" ], "summary": "Rename a WireGuard device", "description": "Changes the name. The key and the address cannot change: to replace a key, delete the device and create a new one. A peer added inside the router by hand cannot be renamed.", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "description": "Identifier of this call." }, "Idempotency-Replayed": { "schema": { "type": "string", "examples": [ "true" ] }, "description": "Present and set to true when this is a stored response replayed for a repeated Idempotency-Key. The work was done by the first call." } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "saved" ], "properties": { "data": { "$ref": "#/components/schemas/WireGuardDevice" }, "saved": { "type": "boolean", "description": "Whether the router wrote the change to its boot configuration. False means the change is applied but will not survive a router reboot: repeat a PATCH of the same rule or port forward with the same body - that saves the whole router configuration." } } } } } }, "400": { "$ref": "#/components/responses/Problem400" }, "401": { "$ref": "#/components/responses/Problem401" }, "402": { "$ref": "#/components/responses/Problem402" }, "403": { "$ref": "#/components/responses/Problem403" }, "404": { "$ref": "#/components/responses/Problem404" }, "409": { "$ref": "#/components/responses/Problem409" }, "422": { "$ref": "#/components/responses/Problem422" }, "429": { "$ref": "#/components/responses/Problem429" }, "500": { "$ref": "#/components/responses/Problem500" }, "503": { "$ref": "#/components/responses/Problem503" }, "415": { "$ref": "#/components/responses/Problem415" } }, "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Identifier of the resource.", "schema": { "type": "integer" } }, { "name": "device", "in": "path", "required": true, "description": "Device identifier (dev1, dev2, ...), as returned by the devices listing.", "schema": { "type": "string", "pattern": "^(?:dev\\d+)$" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Repeat-safety key. Repeating the same key with the same body replays the stored response.", "schema": { "type": "string", "minLength": 8, "maxLength": 255 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 64, "pattern": "^[^\\x00-\\x1F\\x7F]+$", "description": "New name of the device." } }, "additionalProperties": false, "required": [ "name" ] } } } } }, "delete": { "operationId": "router_wireguard_device_delete", "tags": [ "Router" ], "summary": "Delete a WireGuard device", "description": "Removes the peer from the router and the device from the platform; a peer added by hand can be removed too. Allowed on a suspended project and with an overdue invoice: removing a device is how you cut access. revocation_pending is always false for WireGuard.", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "description": "Identifier of this call." }, "Idempotency-Replayed": { "schema": { "type": "string", "examples": [ "true" ] }, "description": "Present and set to true when this is a stored response replayed for a repeated Idempotency-Key. The work was done by the first call." } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "saved" ], "properties": { "data": { "$ref": "#/components/schemas/DeletedDevice" }, "saved": { "type": "boolean", "description": "Whether the router wrote the change to its boot configuration. False means the change is applied but will not survive a router reboot: repeat a PATCH of the same rule or port forward with the same body - that saves the whole router configuration." } } } } } }, "400": { "$ref": "#/components/responses/Problem400" }, "401": { "$ref": "#/components/responses/Problem401" }, "402": { "$ref": "#/components/responses/Problem402" }, "403": { "$ref": "#/components/responses/Problem403" }, "404": { "$ref": "#/components/responses/Problem404" }, "409": { "$ref": "#/components/responses/Problem409" }, "422": { "$ref": "#/components/responses/Problem422" }, "429": { "$ref": "#/components/responses/Problem429" }, "500": { "$ref": "#/components/responses/Problem500" }, "503": { "$ref": "#/components/responses/Problem503" }, "415": { "$ref": "#/components/responses/Problem415" } }, "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Identifier of the resource.", "schema": { "type": "integer" } }, { "name": "device", "in": "path", "required": true, "description": "Device identifier (dev1, dev2, ...), as returned by the devices listing.", "schema": { "type": "string", "pattern": "^(?:dev\\d+)$" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Repeat-safety key. Repeating the same key with the same body replays the stored response.", "schema": { "type": "string", "minLength": 8, "maxLength": 255 } } ] } }, "/servers/{id}/tags": { "get": { "operationId": "server_tag_list", "tags": [ "Tags" ], "summary": "List tags", "description": "Your labels on this server.", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "description": "Identifier of this call." } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "type": "string" } } } } } } }, "400": { "$ref": "#/components/responses/Problem400" }, "401": { "$ref": "#/components/responses/Problem401" }, "402": { "$ref": "#/components/responses/Problem402" }, "403": { "$ref": "#/components/responses/Problem403" }, "404": { "$ref": "#/components/responses/Problem404" }, "409": { "$ref": "#/components/responses/Problem409" }, "422": { "$ref": "#/components/responses/Problem422" }, "429": { "$ref": "#/components/responses/Problem429" }, "500": { "$ref": "#/components/responses/Problem500" }, "503": { "$ref": "#/components/responses/Problem503" } }, "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Identifier of the resource.", "schema": { "type": "integer" } } ] }, "post": { "operationId": "server_tag_add", "tags": [ "Tags" ], "summary": "Add a tag", "description": "Adds one label. Use plain Latin letters, digits, dot, dash and underscore - other characters are stored damaged by the platform underneath and are refused here.", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "description": "Identifier of this call." }, "Idempotency-Replayed": { "schema": { "type": "string", "examples": [ "true" ] }, "description": "Present and set to true when this is a stored response replayed for a repeated Idempotency-Key. The work was done by the first call." } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "type": "string" } } } } } } }, "400": { "$ref": "#/components/responses/Problem400" }, "401": { "$ref": "#/components/responses/Problem401" }, "402": { "$ref": "#/components/responses/Problem402" }, "403": { "$ref": "#/components/responses/Problem403" }, "404": { "$ref": "#/components/responses/Problem404" }, "409": { "$ref": "#/components/responses/Problem409" }, "422": { "$ref": "#/components/responses/Problem422" }, "429": { "$ref": "#/components/responses/Problem429" }, "500": { "$ref": "#/components/responses/Problem500" }, "503": { "$ref": "#/components/responses/Problem503" }, "415": { "$ref": "#/components/responses/Problem415" } }, "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Identifier of the resource.", "schema": { "type": "integer" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Repeat-safety key. Repeating the same key with the same body replays the stored response.", "schema": { "type": "string", "minLength": 8, "maxLength": 255 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "tag": { "type": "string", "minLength": 1, "maxLength": 50, "pattern": "^[A-Za-z0-9._-]+$", "description": "The label to add. Latin letters, digits, dot, dash and underscore." } }, "additionalProperties": false, "required": [ "tag" ] } } } } } }, "/servers/{id}/tags/{tag}": { "delete": { "operationId": "server_tag_remove", "tags": [ "Tags" ], "summary": "Remove a tag", "description": "Removes one label from the server.", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "description": "Identifier of this call." }, "Idempotency-Replayed": { "schema": { "type": "string", "examples": [ "true" ] }, "description": "Present and set to true when this is a stored response replayed for a repeated Idempotency-Key. The work was done by the first call." } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "type": "string" } } } } } } }, "400": { "$ref": "#/components/responses/Problem400" }, "401": { "$ref": "#/components/responses/Problem401" }, "402": { "$ref": "#/components/responses/Problem402" }, "403": { "$ref": "#/components/responses/Problem403" }, "404": { "$ref": "#/components/responses/Problem404" }, "409": { "$ref": "#/components/responses/Problem409" }, "422": { "$ref": "#/components/responses/Problem422" }, "429": { "$ref": "#/components/responses/Problem429" }, "500": { "$ref": "#/components/responses/Problem500" }, "503": { "$ref": "#/components/responses/Problem503" }, "415": { "$ref": "#/components/responses/Problem415" } }, "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Identifier of the resource.", "schema": { "type": "integer" } }, { "name": "tag", "in": "path", "required": true, "description": "The tag to remove.", "schema": { "type": "string", "pattern": "^(?:[^/]+)$" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Repeat-safety key. Repeating the same key with the same body replays the stored response.", "schema": { "type": "string", "minLength": 8, "maxLength": 255 } } ] } }, "/ssh-keys": { "get": { "operationId": "ssh_key_list", "tags": [ "SSH keys" ], "summary": "List SSH keys", "description": "Keys in your account pool. Every project of yours sees the same list.", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "description": "Identifier of this call." } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/SshKey" } } } } } } }, "400": { "$ref": "#/components/responses/Problem400" }, "401": { "$ref": "#/components/responses/Problem401" }, "402": { "$ref": "#/components/responses/Problem402" }, "403": { "$ref": "#/components/responses/Problem403" }, "404": { "$ref": "#/components/responses/Problem404" }, "409": { "$ref": "#/components/responses/Problem409" }, "422": { "$ref": "#/components/responses/Problem422" }, "429": { "$ref": "#/components/responses/Problem429" }, "500": { "$ref": "#/components/responses/Problem500" }, "503": { "$ref": "#/components/responses/Problem503" } } }, "post": { "operationId": "ssh_key_add", "tags": [ "SSH keys" ], "summary": "Add an SSH key", "description": "Adds a key to your account pool so servers can be built with it. Names are unique within the pool.", "security": [ { "bearerAuth": [] } ], "responses": { "201": { "description": "Created.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "description": "Identifier of this call." }, "Location": { "schema": { "type": "string" }, "description": "Path of the created resource." }, "Idempotency-Replayed": { "schema": { "type": "string", "examples": [ "true" ] }, "description": "Present and set to true when this is a stored response replayed for a repeated Idempotency-Key. The work was done by the first call." } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/SshKey" } } } } } }, "200": { "description": "The key already existed with the same material: the existing key is returned.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "description": "Identifier of this call." }, "Idempotency-Replayed": { "schema": { "type": "string", "examples": [ "true" ] }, "description": "Present and set to true when this is a stored response replayed for a repeated Idempotency-Key. The work was done by the first call." } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/SshKey" } } } } } }, "400": { "$ref": "#/components/responses/Problem400" }, "401": { "$ref": "#/components/responses/Problem401" }, "402": { "$ref": "#/components/responses/Problem402" }, "403": { "$ref": "#/components/responses/Problem403" }, "404": { "$ref": "#/components/responses/Problem404" }, "409": { "$ref": "#/components/responses/Problem409" }, "422": { "$ref": "#/components/responses/Problem422" }, "429": { "$ref": "#/components/responses/Problem429" }, "500": { "$ref": "#/components/responses/Problem500" }, "503": { "$ref": "#/components/responses/Problem503" }, "415": { "$ref": "#/components/responses/Problem415" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 50, "pattern": "^[\\x00-\\uD7FF\\uE000-\\uFFFF]+$", "description": "Your name for the key, unique within your pool." }, "public_key": { "type": "string", "minLength": 32, "maxLength": 8192, "description": "The public key material, as it appears in your .pub file." } }, "additionalProperties": false, "required": [ "name", "public_key" ] } } } }, "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Repeat-safety key. Repeating the same key with the same body replays the stored response.", "schema": { "type": "string", "minLength": 8, "maxLength": 255 } } ] } }, "/ssh-keys/{id}": { "get": { "operationId": "ssh_key_get", "tags": [ "SSH keys" ], "summary": "Read an SSH key", "description": "One key, with its material.", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "description": "Identifier of this call." } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/SshKey" } } } } } }, "400": { "$ref": "#/components/responses/Problem400" }, "401": { "$ref": "#/components/responses/Problem401" }, "402": { "$ref": "#/components/responses/Problem402" }, "403": { "$ref": "#/components/responses/Problem403" }, "404": { "$ref": "#/components/responses/Problem404" }, "409": { "$ref": "#/components/responses/Problem409" }, "422": { "$ref": "#/components/responses/Problem422" }, "429": { "$ref": "#/components/responses/Problem429" }, "500": { "$ref": "#/components/responses/Problem500" }, "503": { "$ref": "#/components/responses/Problem503" } }, "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Identifier of the resource.", "schema": { "type": "integer" } } ] }, "delete": { "operationId": "ssh_key_delete", "tags": [ "SSH keys" ], "summary": "Delete an SSH key", "description": "Removes the key from the pool. Servers already carrying it are not touched - the key stays inside their guests.", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "description": "Identifier of this call." }, "Idempotency-Replayed": { "schema": { "type": "string", "examples": [ "true" ] }, "description": "Present and set to true when this is a stored response replayed for a repeated Idempotency-Key. The work was done by the first call." } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Deleted" } } } } } }, "400": { "$ref": "#/components/responses/Problem400" }, "401": { "$ref": "#/components/responses/Problem401" }, "402": { "$ref": "#/components/responses/Problem402" }, "403": { "$ref": "#/components/responses/Problem403" }, "404": { "$ref": "#/components/responses/Problem404" }, "409": { "$ref": "#/components/responses/Problem409" }, "422": { "$ref": "#/components/responses/Problem422" }, "429": { "$ref": "#/components/responses/Problem429" }, "500": { "$ref": "#/components/responses/Problem500" }, "503": { "$ref": "#/components/responses/Problem503" }, "415": { "$ref": "#/components/responses/Problem415" } }, "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Identifier of the resource.", "schema": { "type": "integer" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Repeat-safety key. Repeating the same key with the same body replays the stored response.", "schema": { "type": "string", "minLength": 8, "maxLength": 255 } } ] } }, "/tasks/{id}": { "get": { "operationId": "task_get", "tags": [ "Tasks" ], "summary": "Read a task", "description": "State of one background operation. Poll until is_terminal, then read the resource itself to see the result.", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "description": "Identifier of this call." } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Task" } } } } } }, "400": { "$ref": "#/components/responses/Problem400" }, "401": { "$ref": "#/components/responses/Problem401" }, "402": { "$ref": "#/components/responses/Problem402" }, "403": { "$ref": "#/components/responses/Problem403" }, "404": { "$ref": "#/components/responses/Problem404" }, "409": { "$ref": "#/components/responses/Problem409" }, "422": { "$ref": "#/components/responses/Problem422" }, "429": { "$ref": "#/components/responses/Problem429" }, "500": { "$ref": "#/components/responses/Problem500" }, "503": { "$ref": "#/components/responses/Problem503" } }, "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Identifier of the resource.", "schema": { "type": "string", "pattern": "^(?:[a-fA-F0-9]{32})$" } } ] } } }, "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "description": "API token issued in the client area. Send it as: Authorization: Bearer fbx_..." } }, "schemas": { "Problem": { "type": "object", "description": "Error response, RFC 9457 Problem Details. Served as application/problem+json.", "required": [ "type", "title", "status", "code", "request_id" ], "properties": { "type": { "type": "string", "format": "uri", "description": "Link to the page describing this code.", "examples": [ "https://docs.fiberax.com/errors/server_not_found" ] }, "title": { "type": "string", "description": "Short, human-readable summary. Stable for a given code." }, "status": { "type": "integer", "description": "HTTP status, repeated here for logs that keep only the body." }, "code": { "type": "string", "description": "Machine-readable code. Branch on this, not on the text.\n\nTHE SET GROWS OVER TIME. Treat a code you do not know by its HTTP status and do not fail on it: new codes are added as the platform gains operations, and a client that refuses to parse an unknown one breaks on an ordinary release. The examples below are one per class, not the whole set - the full list lives at https://docs.fiberax.com/errors/ .", "examples": [ "server_not_found", "service_suspended", "server_busy", "invalid_request", "resource_limit_exceeded", "rate_limited", "server_unavailable" ] }, "request_id": { "type": "string", "description": "Same value as the X-Request-Id header. Quote it in support requests." }, "detail": { "type": "string", "description": "What went wrong in this particular case." }, "invalid_params": { "type": "array", "description": "Present when a body or query field failed validation.", "items": { "type": "object", "required": [ "name", "reason" ], "properties": { "name": { "type": "string", "description": "Field that was rejected." }, "reason": { "type": "string", "description": "Why it was rejected." } } } } } }, "Task": { "type": "object", "description": "A unit of work that outlives the request. Poll it until is_terminal is true, then read the resource.", "required": [ "id", "status", "is_terminal" ], "properties": { "id": { "type": "string", "description": "Task identifier, 32 hexadecimal characters." }, "status": { "type": "string", "enum": [ "pending", "running", "succeeded", "failed" ], "description": "Closed set - safe to branch on without a catch-all." }, "is_terminal": { "type": "boolean", "description": "True once the task will not change again." }, "poll": { "type": [ "string", "null" ], "description": "Path to poll for this task." }, "error": { "type": [ "object", "null" ], "description": "Present only when the task failed.", "properties": { "code": { "type": "string", "examples": [ "operation_failed" ] } } }, "created_at": { "type": [ "string", "null" ], "format": "date-time", "description": "RFC 3339 with a real offset." }, "updated_at": { "type": [ "string", "null" ], "format": "date-time", "description": "When the task last changed state." } } }, "Project": { "type": "object", "description": "The Virtual Data Center project this token belongs to.", "required": [ "id", "name", "status" ], "properties": { "id": { "type": "integer", "description": "Identifier of the project. Every path in this API acts inside it." }, "name": { "type": "string", "description": "The name you see in the client area." }, "status": { "type": "string", "enum": [ "Active", "Suspended", "Terminated" ], "description": "Capitalised - this is the one enumeration in the API that is not lower case." } } }, "Ip": { "type": "object", "description": "A public IPv4 address held by the project.", "required": [ "id", "address", "netmask", "prefix", "gateway", "primary" ], "properties": { "id": { "type": "integer", "description": "Identifier of the address. This is what you pass wherever an address is referenced, including public_ipv4 when creating a server." }, "address": { "type": "string", "examples": [ "77.88.234.15" ], "description": "The address itself." }, "netmask": { "type": "string", "description": "Dotted form.", "examples": [ "255.255.255.128" ] }, "prefix": { "type": "string", "description": "Prefix length with a leading slash.", "examples": [ "/25" ] }, "gateway": { "type": "string", "description": "Default gateway for the address." }, "server_id": { "type": [ "integer", "null" ], "description": "Server this address is attached to; null when the address is free but still billed." }, "primary": { "type": "boolean", "description": "True for the address the server presents as its own." } } }, "Server": { "type": "object", "description": "A server in the project. Sizes are always the ordered ones: cores in units, memory in MB, disk in GB.", "required": [ "id", "name", "status", "power", "is_router" ], "properties": { "id": { "type": "integer", "description": "Stable identifier. Use it in paths." }, "name": { "type": "string", "description": "Hostname you gave the server. Routers are named by the platform and cannot be renamed." }, "status": { "type": "string", "description": "Lifecycle state. Closed set - branch on it directly. Two sources feed the field: the state of the machine on the hypervisor, and, while the machine is briefly absent from it (creation, rebuild), the work being done on it. Anything unexpected arrives as unknown.", "enum": [ "running", "stopped", "paused", "suspended", "starting", "stopping", "shutdown", "rebooting", "resetting", "reset", "creating", "rebuild", "removing", "resize", "updating", "backup", "templating", "migrated", "rollback", "pending_reboot", "recovery", "error", "unknown" ] }, "power": { "type": "boolean", "description": "True when the server is powered on." }, "cores": { "type": [ "integer", "null" ], "description": "Virtual cores in total." }, "memory_mb": { "type": [ "integer", "null" ], "description": "Memory in megabytes." }, "disk_gb": { "type": [ "integer", "null" ], "description": "System disk in gigabytes. Never the sum of all disks - data disks are their own resource." }, "uptime_seconds": { "type": [ "integer", "null" ], "description": "Seconds the server has been running. Null when the platform does not report it." }, "ipv4": { "type": "string", "description": "Primary public address, empty when the server has none." }, "ipv6": { "type": "string", "description": "IPv6 address of the server. Empty when it has none." }, "image": { "type": [ "string", "null" ], "description": "Identifier of the image the server was built from - exactly the value accepted when creating a server." }, "image_name": { "type": "string", "description": "Human-readable name of that image." }, "server_type_id": { "type": [ "integer", "null" ], "description": "Server type the machine was built on. It also decides which images and sizes the machine can take." }, "server_type": { "type": "string", "description": "Product name of the server type, for example Solo Server." }, "plan_id": { "type": [ "integer", "null" ], "description": "Set only on server types sold as ready-made plans, and null when the configuration matches no plan." }, "gpus": { "type": "array", "description": "Graphics cards attached to this server, grouped by model. Empty on a server without cards. The model is named the way the catalogue of its type names it: the model key on a slider type with cards, the package card model on a package type.", "items": { "type": "object", "properties": { "model": { "type": "string", "examples": [ "l40s" ] }, "count": { "type": "integer" } } } }, "gpu_package": { "type": [ "string", "null" ], "description": "Package the server was built from, on types sold as GPU packages. Null elsewhere. The package fixes cores, memory and disk, and cannot be changed on an existing server." }, "disk_type": { "oneOf": [ { "type": "string", "enum": [ "local", "ceph" ] }, { "type": "null" } ], "description": "Storage class of the system disk, chosen at creation on types with graphics cards. Null on types where the storage class is part of the type." }, "is_router": { "type": "boolean", "description": "Routers are servers, but several operations are refused on them." }, "pending_reboot": { "type": "boolean", "description": "A change has been applied that the server needs a restart to pick up." }, "admin_user": { "type": "string", "description": "Administrator account name inside the guest, for example root or Administrator." }, "tags": { "type": "array", "items": { "type": "string" }, "description": "Your own labels. Platform labels are not shown." }, "ips": { "type": "array", "items": { "$ref": "#/components/schemas/Ip" }, "description": "Public addresses attached to this server." } } }, "NetworkRouter": { "type": "object", "description": "The router serving a private network.", "required": [ "server_id", "name", "status", "interface" ], "properties": { "server_id": { "type": [ "integer", "null" ], "description": "The router is an ordinary server: this is its id, and it is read, powered and deleted like any other." }, "name": { "type": "string", "description": "Name of the router server. The platform sets it and does not let it be changed." }, "status": { "type": "string", "description": "State of the router server, in the same words as any other server." }, "interface": { "type": "string", "description": "Router interface facing this network.", "examples": [ "eth2" ] } } }, "Network": { "type": "object", "description": "A private network inside the project. Servers on it talk to each other regardless of which server type they run on.", "required": [ "id", "name", "cidr", "is_default" ], "properties": { "id": { "type": "integer", "description": "Identifier of the network. Pass it in networks when creating a server, or as network_id on a card." }, "name": { "type": "string", "description": "Name of the network. Unique within the project, and compared without regard to case." }, "cidr": { "type": "string", "examples": [ "10.0.0.0/24" ], "description": "Subnet handed out inside the network. Empty until one is set - a network without a subnet exists but hands out nothing." }, "is_default": { "type": "boolean", "description": "The network created with the project. It cannot be deleted." }, "server_count": { "type": [ "integer", "null" ], "description": "Servers attached. Omitted from the count when you ask to skip it." }, "router": { "oneOf": [ { "$ref": "#/components/schemas/NetworkRouter" }, { "type": "null" } ], "description": "Null when no router serves this network." } } }, "SshKey": { "type": "object", "description": "An SSH key in your account pool. Keys belong to the account, not to one project.", "required": [ "id", "name" ], "properties": { "id": { "type": "integer", "description": "Identifier of the key." }, "name": { "type": "string", "description": "Name of the key. It belongs to the client, not to one project, so the name is unique across all of them." }, "public_key": { "type": [ "string", "null" ], "description": "The key material as you supplied it." } } }, "Disk": { "type": "object", "description": "A disk attached to a server. The system disk is reported here too but is sized through the server itself.", "required": [ "id", "is_system" ], "properties": { "id": { "type": "string", "description": "Slot name, the same one shown in the client area.", "examples": [ "scsi1" ] }, "size_gb": { "type": [ "integer", "null" ], "description": "Size in gigabytes. Disks grow only: a smaller value is refused." }, "is_system": { "type": "boolean", "description": "True for the disk the operating system boots from. It cannot be deleted separately." }, "server_id": { "type": [ "integer", "null" ], "description": "Server the disk is attached to." } } }, "NetworkInterface": { "type": "object", "description": "A network card on a server. Its network is a field, not a separate resource.", "required": [ "id", "public", "firewall", "link_down" ], "properties": { "id": { "type": "string", "description": "Slot name.", "examples": [ "net0" ] }, "mac": { "type": "string", "description": "Hardware address of the card." }, "public": { "type": "boolean", "description": "True when the card faces the internet." }, "network_id": { "type": [ "integer", "null" ], "description": "Private network this card is attached to; null for a public card." }, "firewall": { "type": "boolean", "description": "Whether the firewall filters this card." }, "link_down": { "type": "boolean", "description": "True when the card is administratively disconnected." }, "ips": { "type": "array", "items": { "$ref": "#/components/schemas/Ip" }, "description": "Public addresses attached to this card. Empty on a card in a private network." } } }, "BackupPolicy": { "type": "object", "description": "Backup policy of a server. The switch and the schedule are one thing: turning backups off keeps your days and times, so switching back on does not lose them.", "required": [ "enabled", "keep" ], "properties": { "enabled": { "type": "boolean", "description": "Whether scheduled backups run. This is what you are billed for." }, "days": { "type": [ "array", "null" ], "items": { "type": "string", "enum": [ "mon", "tue", "wed", "thu", "fri", "sat", "sun" ] }, "description": "Days the backup runs. Null when the server has no schedule yet." }, "hour": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 23, "description": "Hour of the daily run, in the project timezone. Null when the schedule is off." }, "minute": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 59, "description": "Minute of the daily run. Null when the schedule is off." }, "keep": { "type": "integer", "description": "How many backups are kept. Set by the product, read-only here." }, "next_run": { "type": [ "string", "null" ], "format": "date-time", "description": "When the schedule fires next. Null when it is off." }, "last_run": { "type": [ "string", "null" ], "format": "date-time", "description": "When the schedule last fired. Null until it has run once." }, "last_run_status": { "oneOf": [ { "type": "string", "enum": [ "succeeded", "failed" ] }, { "type": "null" } ], "description": "How the last run ended. Null until the schedule has run once." } } }, "Backup": { "type": "object", "description": "One backup of a server. Its identifier is the moment it was taken, in UTC.", "required": [ "id", "status" ], "properties": { "id": { "type": "string", "description": "Timestamp the backup was taken, UTC.", "examples": [ "2026-08-16T01:12:00Z" ] }, "server_id": { "type": [ "integer", "null" ], "description": "Server the backup was taken from." }, "status": { "type": "string", "enum": [ "available", "creating", "deleting", "failed", "unavailable" ], "description": "Wait for available before restoring - a backup still being written is not a usable archive." }, "size_bytes": { "type": [ "integer", "null" ], "description": "Null while the backup is still being written." }, "created_at": { "type": [ "string", "null" ], "format": "date-time", "description": "When the archive was written. Null while the copy is still being taken." } } }, "Image": { "type": "object", "description": "An image a server can be built from: an operating system, a prepared application, a router, or one of your own.", "required": [ "id", "name", "type" ], "properties": { "id": { "type": "string", "description": "Pass this value as image when creating a server." }, "name": { "type": "string", "description": "Name shown in the catalogue." }, "type": { "type": "string", "enum": [ "os", "marketplace", "router", "iso", "usertemplate", "useriso" ], "description": "What kind of image this is. The first four come from the platform catalogue - an operating system, a prepared application, a router, an installation ISO; usertemplate and useriso are your own, taken from one of your servers or uploaded by you." }, "category": { "type": "string", "description": "Grouping for application images; empty for your own images." }, "min_cores": { "type": [ "integer", "null" ], "description": "Below this the image is refused." }, "min_memory_gb": { "type": [ "integer", "null" ], "description": "Least memory the image will run on. Null when the image does not state one." }, "min_disk_gb": { "type": [ "integer", "null" ], "description": "Least system disk the image will run on. Null when the image does not state one." }, "recommended": { "type": "object", "description": "What we suggest for this image.", "properties": { "cores": { "type": [ "integer", "null" ] }, "memory_gb": { "type": [ "integer", "null" ] }, "disk_gb": { "type": [ "integer", "null" ] } } }, "admin_user": { "type": "string", "description": "Administrator account inside the guest." }, "licensed": { "type": "boolean", "description": "True when the image carries a paid licence billed per core. Creating from it requires accept_license." } } }, "Iso": { "type": "object", "description": "An ISO image you added to the project by URL.", "required": [ "id", "name", "status" ], "properties": { "id": { "type": "string", "examples": [ "uiso-50" ], "description": "Identifier of the image. Pass it wherever an image is named, including the drive of a server." }, "name": { "type": "string", "description": "Name you gave the image." }, "status": { "type": "string", "enum": [ "pending", "downloading", "available", "unavailable", "failed" ], "description": "Where the download has got to. Closed set: pending and downloading mean the platform is still fetching the file, available means it can be used, failed means the download did not finish, unavailable means the record is intact but the file is no longer on the storage." }, "size_bytes": { "type": [ "integer", "null" ], "description": "Size of the file. Empty above four gigabytes: the platform counts size in a field that stops there, and an empty value is honester than a wrong one." }, "error": { "oneOf": [ { "type": "string", "enum": [ "invalid_content_type", "empty_file", "unreachable", "timeout", "url_not_allowed", "upload_failed", "storage_not_writable", "download_failed" ] }, { "type": "null" } ], "description": "Why the download failed, when it did." }, "created_at": { "type": [ "string", "null" ], "format": "date-time", "description": "When the image was added." }, "last_deployed_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Last time a server was built from it." } } }, "ServerImage": { "type": "object", "description": "An image taken from one of your servers, ready to build new ones from.", "required": [ "id", "name", "status" ], "properties": { "id": { "type": "string", "examples": [ "utpl-12" ], "description": "Identifier of the image. Pass it as image when creating a server." }, "name": { "type": "string", "description": "Name you gave the image." }, "description": { "type": "string", "description": "Free text you attached to the image." }, "status": { "type": "string", "enum": [ "pending", "creating", "available", "deleting", "deleted", "failed" ], "description": "Where the image has got to. It can only be used for a new server while it is available." }, "server_type_id": { "type": [ "integer", "null" ], "description": "The image can only build servers of this type." }, "source_server_id": { "type": [ "integer", "null" ], "description": "Server the image was taken from. The image runs only on that server type." }, "created_at": { "type": [ "string", "null" ], "format": "date-time", "description": "When the image was taken." }, "last_deployed_at": { "type": [ "string", "null" ], "format": "date-time", "description": "When a server was last created from this image. Null while none has been." } } }, "ServerType": { "type": "object", "description": "A kind of server you can create. Types differ in how they are sized and priced.", "required": [ "id", "name", "pricing_mode" ], "properties": { "id": { "type": "integer", "description": "Identifier of the server type. Everything else - prices, images, limits - is read per type with this id." }, "name": { "type": "string", "examples": [ "Solo Server" ], "description": "Name of the type as it is sold." }, "description": { "type": "string", "description": "What the type is for, in the words of the catalogue." }, "pricing_mode": { "type": "string", "enum": [ "sliders", "plans", "fixed" ], "description": "sliders - you choose cores, memory and disk; plans - you choose a ready-made plan; fixed - the size comes with the GPU package you pick." }, "gpu": { "type": "boolean", "description": "True when this type is sold with graphics cards. Two shapes exist: a fixed type comes as a GPU package (cards, cores, memory and disk in one item), a slider type with gpu true lets you pick the cards and size the rest yourself. See the type pricing for what it offers." } } }, "Plan": { "type": "object", "description": "A ready-made configuration sold as one item.", "properties": { "id": { "type": [ "integer", "null" ], "description": "Identifier of the plan. Pass it as plan_id when creating a server on a plan type." }, "name": { "type": "string", "description": "Name of the plan as it is sold." }, "cores": { "type": [ "integer", "null" ], "description": "Cores the plan contains." }, "memory_gb": { "type": [ "integer", "null" ], "description": "Memory the plan contains." }, "disk_gb": { "type": [ "integer", "null" ], "description": "System disk the plan contains." }, "price": { "type": [ "number", "null" ], "format": "double", "description": "Price per month." } } }, "Pricing": { "type": "object", "description": "What a server type costs. Rates are per hour; the monthly figure is the hourly rate over 720 hours, for comparison only.", "required": [ "server_type_id", "pricing_mode" ], "properties": { "server_type_id": { "type": [ "integer", "null" ], "description": "Server type these prices belong to." }, "pricing_mode": { "type": "string", "enum": [ "sliders", "plans", "fixed" ], "description": "How the type is sized and billed: sliders means you choose cores, memory and disk yourself; plans means you pick a ready-made plan; fixed means the type itself decides." }, "metered": { "type": "object", "description": "Rate per billed item. Keys depend on the type: resource rates on slider types, plan rates on plan types.", "additionalProperties": { "type": "object", "properties": { "hourly": { "type": "number", "format": "double" }, "monthly": { "type": "number", "format": "double" } } } }, "limits": { "type": [ "object", "null" ], "description": "Upper bounds for slider types. Null where the type is not sized by sliders.", "properties": { "cpu": { "type": "integer" }, "ram_gb": { "type": "integer" }, "disk_gb_local": { "type": "integer" }, "disk_gb_ceph": { "type": "integer" }, "gpus": { "type": "integer", "description": "Most graphics cards one server of this type may hold. Present on types sold with cards you pick yourself." } } }, "plans": { "type": "array", "items": { "$ref": "#/components/schemas/Plan" }, "description": "Ready-made plans of this type. Empty on a type that is not sold in plans." }, "gpu_packages": { "type": "array", "items": { "$ref": "#/components/schemas/GpuPackage" }, "description": "GPU packages this type sells. Filled on fixed types with graphics cards, empty everywhere else." }, "gpu_models": { "type": "array", "items": { "$ref": "#/components/schemas/GpuModel" }, "description": "Card models you can combine on this type. Filled on slider types with graphics cards, empty everywhere else." } } }, "GpuPackage": { "type": "object", "description": "A whole GPU host sold as one item: the card, the cores, the memory and the system disk. Name it as gpu_package when creating a server; cores, memory, disk and plan_id are not accepted on such a type.", "properties": { "key": { "type": "string", "examples": [ "gpu-l4-24" ], "description": "Identifier of the package. This is the value you pass as gpu_package." }, "name": { "type": "string", "examples": [ "GPU L4 24-core" ], "description": "Name of the package as it is sold." }, "gpu_model": { "type": "string", "examples": [ "L4" ], "description": "Card model in the package." }, "gpu_count": { "type": "integer", "description": "Cards in the package. One: the host and its card are not shared between servers." }, "cores": { "type": [ "integer", "null" ], "description": "Cores the package contains." }, "memory_gb": { "type": [ "integer", "null" ], "description": "Memory the package contains." }, "disk_gb": { "type": [ "integer", "null" ], "description": "System disk the package contains." }, "price": { "type": [ "number", "null" ], "format": "double", "description": "Price per month." }, "backup_price": { "type": [ "number", "null" ], "format": "double", "description": "Price per month for automatic backups of a server on this package - a flat figure per server, not per gigabyte." } } }, "GpuModel": { "type": "object", "description": "A card model available on a slider type with graphics cards. Combine models in the gpus list when creating a server.", "properties": { "key": { "type": "string", "examples": [ "l40s" ], "description": "Identifier of the model. This is the value you pass as model inside gpus." }, "name": { "type": "string", "examples": [ "L40S" ], "description": "Name of the card model as it is sold." }, "memory_gb": { "type": [ "integer", "null" ], "description": "Memory on the card itself." }, "price": { "type": [ "number", "null" ], "format": "double", "description": "Price per month per card. Zero means the card is included in the price of the type." } } }, "FirewallRule": { "type": "object", "description": "One rule. Order matters: the first matching rule wins.", "required": [ "direction", "action", "enabled" ], "properties": { "direction": { "type": "string", "enum": [ "in", "out" ], "description": "Which way the traffic goes: in means towards the server, out means away from it." }, "action": { "type": "string", "enum": [ "accept", "drop", "reject" ], "description": "What happens to matching traffic. drop says nothing back, reject answers with a refusal." }, "protocol": { "type": [ "string", "null" ], "examples": [ "tcp" ], "description": "Protocol the rule matches. Empty means any. Compared in lower case." }, "source": { "type": [ "string", "null" ], "description": "Address or range the traffic comes from. Empty means any." }, "destination": { "type": [ "string", "null" ], "description": "Where the traffic goes, as an address or a subnet. Empty means anywhere." }, "source_port": { "type": [ "string", "null" ], "description": "A port, a list or a range, as text.", "examples": [ "80,443", "1000:2000" ] }, "destination_port": { "type": [ "string", "null" ], "description": "Port or ports at the destination. A list or a range is allowed, for example 80,443 or 1000:2000. A port without a protocol is refused." }, "macro": { "type": [ "string", "null" ], "description": "Named service shorthand supplied by the platform." }, "enabled": { "type": "boolean", "description": "A disabled rule stays in the set and does nothing." }, "description": { "type": [ "string", "null" ], "description": "Your own note on the rule. Control characters are refused and it cannot start with a hash: the note goes into the firewall configuration as text, where a line break would become a rule of its own and a leading hash would hide the rule." } } }, "Firewall": { "type": "object", "description": "The firewall of a server, rules included. It is one resource: sending it replaces the whole rule set.", "required": [ "enabled", "rules" ], "properties": { "enabled": { "type": "boolean", "description": "Filtering applies to the server's public card. A server with no public card cannot enable it." }, "policy_in": { "type": "string", "enum": [ "accept", "drop", "reject" ], "description": "What happens to inbound traffic no rule matched." }, "policy_out": { "type": "string", "enum": [ "accept", "drop", "reject" ], "description": "What happens to outgoing traffic no rule matched." }, "log_level_in": { "type": "string", "enum": [ "nolog", "emerg", "alert", "crit", "err", "warning", "notice", "info", "debug" ], "description": "How much of the incoming traffic the platform writes down. nolog writes nothing." }, "log_level_out": { "type": "string", "enum": [ "nolog", "emerg", "alert", "crit", "err", "warning", "notice", "info", "debug" ], "description": "How much of the outgoing traffic the platform writes down. nolog writes nothing." }, "rules": { "type": "array", "maxItems": 50, "items": { "$ref": "#/components/schemas/FirewallRule" }, "description": "Rules in the order they are checked: top to bottom, first match wins. Writing the firewall replaces the whole set." } } }, "ServerIso": { "type": "object", "description": "What is in the server's optical drive.", "required": [ "boot", "occupied" ], "properties": { "image": { "type": [ "string", "null" ], "description": "Identifier of the mounted image, null when the drive is empty." }, "image_name": { "type": [ "string", "null" ], "description": "Name of the image in the drive. Empty when the image has been deleted or withdrawn from sale since it was inserted - the drive is still occupied, there is just nothing left to name it by." }, "boot": { "type": "boolean", "description": "True when the server is set to boot from the drive." }, "occupied": { "type": "boolean", "description": "Something is in the drive. Read only: to free it, eject the image." } } }, "RouterNetwork": { "type": "object", "description": "A private network as the router sees it, with its address handout range.", "properties": { "network_id": { "type": [ "integer", "null" ], "description": "The private network this entry describes." }, "interface": { "type": "string", "description": "Router interface name.", "examples": [ "eth1" ] }, "name": { "type": "string", "description": "Name of the network." }, "cidr": { "type": "string", "description": "Subnet the router hands out inside this network." }, "gateway": { "type": "string", "description": "Address of the router inside this network." }, "dhcp": { "type": "object", "description": "What the router hands out to machines on this network.", "properties": { "enabled": { "type": "boolean", "description": "The router hands out addresses here." }, "range_start": { "type": "string", "description": "First address of the pool." }, "range_end": { "type": "string", "description": "Last address of the pool." } } } } }, "RouterNetworks": { "type": "object", "description": "Private networks attached to a router, with what it hands out on each.", "required": [ "router_ip", "networks" ], "properties": { "router_ip": { "type": "string", "description": "Public address of the router." }, "networks": { "type": "array", "items": { "$ref": "#/components/schemas/RouterNetwork" }, "description": "One entry per private network the router serves." } } }, "RouterFirewallRule": { "type": "object", "description": "One access rule of the router firewall. Rules are checked in ascending priority order and the first matching rule wins. The rule is a resource of its own: it keeps its number when neighbours are deleted, and a number freed by a delete is reused by the next create.", "required": [ "id", "priority", "action", "enabled", "editable", "extra" ], "properties": { "id": { "type": "integer", "description": "Rule number on the router. Same value as priority." }, "priority": { "type": "integer", "minimum": 2000, "maximum": 999000, "description": "Position in the rule order: lower is checked first. Chosen by the platform unless given on create; cannot be changed afterwards." }, "action": { "type": "string", "enum": [ "accept", "drop", "reject" ], "description": "What happens to matching traffic. drop says nothing back, reject answers with a refusal." }, "protocol": { "oneOf": [ { "type": "string", "enum": [ "tcp", "udp", "tcp_udp", "icmp" ] }, { "type": "null" } ], "description": "Null means any protocol." }, "interface": { "type": [ "string", "null" ], "description": "Router interface the traffic arrives on (eth0 is the public side), as listed by GET /v1/servers/{id}/router/networks. Null means any interface.", "examples": [ "eth0" ] }, "source": { "type": [ "string", "null" ], "description": "IPv4 address or IPv4/prefix the traffic comes from. Null means any." }, "source_port": { "type": [ "string", "null" ], "description": "A port, a comma-separated list or a dash range, as text. Requires a tcp, udp or tcp_udp protocol.", "examples": [ "22", "80,443", "10000-20000" ] }, "destination": { "type": [ "string", "null" ], "description": "IPv4 address or IPv4/prefix the traffic goes to. Null means any." }, "destination_port": { "type": [ "string", "null" ], "examples": [ "22", "80,443", "10000-20000" ], "description": "Port or ports at the destination. A list or a range is allowed." }, "enabled": { "type": "boolean", "description": "A disabled rule stays on the router and does nothing." }, "description": { "type": [ "string", "null" ], "description": "Free text, up to 120 characters." }, "editable": { "type": "boolean", "description": "False when the rule carries conditions this API cannot express (extra is non-empty): such a rule can be read and deleted, but not changed." }, "extra": { "type": "array", "items": { "type": "string" }, "description": "Conditions of the rule that lie outside this API's model, in the router's own words. Empty for rules created through the API." } } }, "RouterPortForward": { "type": "object", "description": "One port forward of the router: traffic arriving on a public port is sent to a server inside a private network of the router. Forwards are checked in ascending priority order and the first matching one wins; a freed number is reused by the next create.", "required": [ "id", "priority", "protocol", "public_port", "target", "enabled", "editable", "extra" ], "properties": { "id": { "type": "integer", "description": "Forward number on the router. Same value as priority." }, "priority": { "type": "integer", "minimum": 2000, "maximum": 999000, "description": "Position in the order: lower is checked first. Chosen by the platform unless given on create; cannot be changed afterwards." }, "protocol": { "type": "string", "enum": [ "tcp", "udp", "tcp_udp" ], "description": "Protocol that is forwarded." }, "public_port": { "type": "string", "description": "Port, comma-separated list or dash range on the router's public address.", "examples": [ "2222", "8080,8443", "10000-20000" ] }, "source": { "type": [ "string", "null" ], "description": "IPv4 address or IPv4/prefix allowed to use the forward. Null means anyone." }, "target": { "type": "string", "description": "IPv4 address of the server inside a private network of this router." }, "target_port": { "type": [ "string", "null" ], "description": "Port on the target. Null means the same port the traffic arrived on." }, "interface": { "type": [ "string", "null" ], "description": "Router interface the forward listens on. Read-only: new forwards always listen on the public interface; null on older forwards means any." }, "enabled": { "type": "boolean", "description": "A disabled forward stays on the router and does nothing." }, "description": { "type": [ "string", "null" ], "description": "Free text, up to 120 characters." }, "editable": { "type": "boolean", "description": "False when the forward carries conditions this API cannot express (extra is non-empty): it can be read and deleted, but not changed." }, "extra": { "type": "array", "items": { "type": "string" }, "description": "Conditions outside this API's model, in the router's own words." } } }, "WireGuardTunnel": { "type": "object", "description": "The WireGuard tunnel of the router: one per router, switched on and off with enabled. Everything else is chosen by the platform. When the tunnel is switched off and its interface is gone from the router, the tunnel fields are null; configured tells whether the platform keeps the key and the devices, so switching it back on restores them.", "required": [ "enabled", "configured", "managed", "interface", "subnet", "router_address", "port", "public_key", "endpoint", "allowed_ips", "dns", "keepalive", "device_limit", "device_count", "networks" ], "properties": { "enabled": { "type": "boolean", "description": "Whether the tunnel accepts connections. The only field you set." }, "configured": { "type": "boolean", "description": "The platform holds a key and device records for this router. Enabling brings them back." }, "managed": { "type": "boolean", "description": "The interface on the router matches the platform records. False means someone changed the tunnel inside the router by hand; devices cannot be managed until that is resolved." }, "interface": { "type": [ "string", "null" ], "description": "Interface name inside the router.", "examples": [ "wg90" ] }, "subnet": { "type": [ "string", "null" ], "description": "Address range of the tunnel, devices get addresses from it.", "examples": [ "172.16.1.0/24" ] }, "router_address": { "type": [ "string", "null" ], "description": "Address of the router inside the tunnel." }, "port": { "type": [ "integer", "null" ], "description": "UDP port the router listens on." }, "public_key": { "type": [ "string", "null" ], "description": "Public key of the router - the peer key for device configurations." }, "endpoint": { "type": [ "string", "null" ], "description": "Public address and port devices connect to.", "examples": [ "203.0.113.10:51820" ] }, "allowed_ips": { "type": "array", "items": { "type": "string" }, "description": "Ranges a device should route into the tunnel: the router's private networks plus the tunnel subnet." }, "dns": { "type": [ "string", "null" ], "description": "DNS server to use inside the tunnel (the router)." }, "keepalive": { "type": [ "integer", "null" ], "description": "Recommended persistent keepalive, seconds." }, "device_limit": { "type": "integer", "description": "Maximum devices on this tunnel." }, "device_count": { "type": "integer", "description": "Devices issued on this tunnel." }, "networks": { "type": "array", "items": { "type": "string" }, "description": "Private networks of the router reachable through the tunnel." } } }, "WireGuardDevice": { "type": "object", "description": "One WireGuard device (peer). The device generates its own key pair and sends only the public half: the private key never reaches the platform, so the client configuration is assembled on the device from the tunnel and device fields.", "required": [ "id", "name", "public_key", "address", "allowed_ips", "present", "online", "foreign", "custom_allowed" ], "properties": { "id": { "type": "string", "description": "Device identifier on the router.", "examples": [ "dev1" ] }, "name": { "type": "string", "description": "Name you gave the device." }, "public_key": { "type": "string", "description": "Public key of the device, 44 characters base64." }, "address": { "type": [ "string", "null" ], "description": "Address of the device inside the tunnel, assigned by the platform." }, "allowed_ips": { "type": "array", "items": { "type": "string" }, "description": "Ranges the router routes to this device; normally the device's own address as /32." }, "present": { "type": "boolean", "description": "The peer exists on the router. False when the tunnel is switched off or the peer was removed inside the router by hand: delete and create the device again to restore it." }, "online": { "type": [ "boolean", "null" ], "description": "A handshake happened within the last three minutes. Null when unknown." }, "foreign": { "type": "boolean", "description": "The peer was added inside the router, not through the platform: it can be deleted but not renamed." }, "custom_allowed": { "type": "boolean", "description": "allowed_ips were changed inside the router by hand; the platform shows them as they are." } } }, "WireGuardDeviceCreated": { "description": "A newly issued WireGuard device, together with its configuration. The configuration is returned once and cannot be read again.", "allOf": [ { "$ref": "#/components/schemas/WireGuardDevice" }, { "type": "object", "required": [ "config" ], "properties": { "config": { "type": "object", "description": "What the device needs for its [Interface] and [Peer] sections. Nothing here is secret: every value can be read again from the tunnel and the device.", "required": [ "address", "dns", "server_public_key", "endpoint", "allowed_ips", "keepalive" ], "properties": { "address": { "type": [ "string", "null" ], "description": "Device address with prefix, for the Interface section.", "examples": [ "172.16.1.2/24" ] }, "dns": { "type": [ "string", "null" ] }, "server_public_key": { "type": [ "string", "null" ], "description": "Public key of the router, for the Peer section." }, "endpoint": { "type": [ "string", "null" ], "examples": [ "203.0.113.10:51820" ] }, "allowed_ips": { "type": "array", "items": { "type": "string" } }, "keepalive": { "type": [ "integer", "null" ] } } } } } ] }, "OpenVpnTunnel": { "type": "object", "description": "The OpenVPN tunnel of the router: one per router, switched on and off with enabled. Certificates are issued by a certificate authority the platform keeps for this router. When the tunnel is switched off and its interface is gone from the router, the tunnel fields are null.", "required": [ "enabled", "configured", "managed", "interface", "subnet", "router_address", "port", "endpoint", "dns", "push_routes", "networks_missing", "device_limit", "device_count", "networks" ], "properties": { "enabled": { "type": "boolean", "description": "Whether the tunnel accepts connections. The only field you set. Enabling an already enabled tunnel is harmless and pushes routes for networks attached since." }, "configured": { "type": "boolean", "description": "The platform holds the certificate authority and device records for this router." }, "managed": { "type": "boolean", "description": "The interface on the router matches the platform records." }, "interface": { "type": [ "string", "null" ], "examples": [ "vtun90" ], "description": "Name of the tunnel interface on the router. Null while the tunnel is off." }, "subnet": { "type": [ "string", "null" ], "examples": [ "172.17.1.0/24" ], "description": "Subnet the tunnel hands out to connected devices. Null while the tunnel is off." }, "router_address": { "type": [ "string", "null" ], "description": "Address of the router inside the tunnel. Null while the tunnel is off." }, "port": { "type": [ "integer", "null" ], "description": "UDP port the router listens on." }, "endpoint": { "type": [ "string", "null" ], "examples": [ "203.0.113.10:1194" ], "description": "Address and port clients connect to. Null while the tunnel is off." }, "dns": { "type": [ "string", "null" ], "description": "Resolver handed to connected devices. Null when none is handed out." }, "push_routes": { "type": "array", "items": { "type": "string" }, "description": "Private networks the router currently pushes to connecting devices." }, "networks_missing": { "type": "array", "items": { "type": "string" }, "description": "Networks attached to the router after the tunnel was configured and not pushed yet. Non-empty means: send PUT with enabled: true again to push them." }, "device_limit": { "type": "integer", "description": "How many devices the tunnel accepts." }, "device_count": { "type": "integer", "description": "Devices issued on this tunnel." }, "networks": { "type": "array", "items": { "type": "string" }, "description": "Private networks reachable through the tunnel." } } }, "OpenVpnDevice": { "type": "object", "description": "One OpenVPN device. Its certificate and key are issued by the platform and handed out exactly once, inside the profile returned by the create call; there is no way to read them again. A lost profile means delete the device (which revokes the certificate) and create a new one.", "required": [ "id", "name", "address", "serial", "online" ], "properties": { "id": { "type": "string", "examples": [ "dev1" ], "description": "Identifier of the device. Pass it when renaming or revoking." }, "name": { "type": "string", "description": "Name you gave the device." }, "address": { "type": [ "string", "null" ], "description": "Address of the device inside the tunnel, fixed by the platform." }, "serial": { "type": [ "string", "null" ], "description": "Serial number of the device certificate." }, "online": { "type": [ "boolean", "null" ], "description": "The device is connected right now. Null when the router status could not be read." } } }, "OpenVpnDeviceCreated": { "description": "A newly issued OpenVPN device, together with its profile. The profile is returned once and cannot be read again.", "allOf": [ { "$ref": "#/components/schemas/OpenVpnDevice" }, { "type": "object", "required": [ "profile" ], "properties": { "profile": { "type": "string", "description": "The complete .ovpn profile: certificate authority, device certificate and the device PRIVATE KEY. Returned once, never readable again - store it now. A repeat of the same request with the same Idempotency-Key within a day replays this response, profile included." } } } ] }, "PrivateIps": { "type": "object", "description": "Addresses the guest agent reports from inside the server. Available only while the server runs an agent.", "required": [ "available" ], "properties": { "available": { "type": "boolean", "description": "False when the agent did not answer; the interface map is then empty." }, "interfaces": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } }, "description": "Interface name to the addresses seen on it." } } }, "Event": { "type": "object", "description": "Something the platform did with the server.", "required": [ "time", "type", "status" ], "properties": { "time": { "type": "string", "format": "date-time", "description": "UTC." }, "type": { "type": "string", "enum": [ "server_created", "server_deleted", "power_on", "power_off", "shutdown", "reboot", "resources_changed", "network_interface_changed", "firewall_changed", "password_reset", "backup_started", "backup_deleted", "tag_added", "tag_removed", "router_dhcp_changed" ], "description": "What happened, for example power_on, resources_changed, backup_started. The set grows as the platform learns to name new events, so treat a value you do not know as a valid event and ignore it rather than failing." }, "status": { "type": "string", "enum": [ "succeeded", "failed" ], "description": "How it ended." } } }, "CostItem": { "type": "object", "description": "One billed line. Amounts and quantities are strings so no precision is lost.", "properties": { "sku": { "type": "string", "description": "What is billed, for example cpu, memory, storage, ipv4, backup." }, "name": { "type": "string", "description": "What is billed, in words." }, "server_type_id": { "type": [ "integer", "null" ], "description": "Server type the charge belongs to. Null on charges that belong to no type." }, "quantity": { "type": [ "string", "null" ], "description": "How much was used, as a string so no precision is lost. Null where a count makes no sense." }, "unit": { "type": [ "string", "null" ], "description": "Unit of the quantity, for example Core-Hours. Null together with quantity." }, "amount": { "type": "string", "description": "What it costs, as a string so no precision is lost." } } }, "CostBucket": { "type": "object", "description": "One slice of the period, with what was billed inside it.", "properties": { "start_time": { "type": "string", "format": "date-time", "description": "Start of this slice of the period." }, "end_time": { "type": "string", "format": "date-time", "description": "End of this slice." }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/CostItem" }, "description": "What was billed inside this slice. Empty when nothing was." }, "total": { "type": "string", "description": "Sum over this slice, as a string so no precision is lost." } } }, "Costs": { "type": "object", "description": "What the project has run up. Figures are an estimate of usage so far, not an invoice.", "required": [ "period_start", "period_end", "currency", "total" ], "properties": { "period_start": { "type": "string", "format": "date-time", "description": "Start of the period the answer covers." }, "period_end": { "type": "string", "format": "date-time", "description": "End of the period the answer covers." }, "currency": { "type": "string", "description": "ISO currency code of your account." }, "granularity": { "type": "string", "enum": [ "none", "daily", "hourly" ], "description": "How the period is split into buckets. none means one bucket for the whole period." }, "estimated": { "type": "boolean", "description": "True while the invoice for the period has not been issued. Today every answer carries true, so do not read it as a way to tell a closed period from an open one." }, "generated_at": { "type": "string", "format": "date-time", "description": "The moment the figures were calculated." }, "buckets": { "type": "array", "items": { "$ref": "#/components/schemas/CostBucket" }, "description": "The period split by granularity. Every bucket is present, including the empty ones: a missing bucket would read as \"nothing was spent\"." }, "total": { "type": "string", "description": "Sum over the whole period, as a string so no precision is lost." } } }, "MetricPoint": { "type": "object", "description": "One measurement in time.", "properties": { "time": { "type": "string", "format": "date-time", "description": "The moment this value belongs to." }, "value": { "type": [ "number", "null" ], "format": "double", "description": "Null means no data for that moment - not zero." } } }, "MetricSeries": { "type": "object", "description": "One measurement over the whole window.", "properties": { "name": { "type": "string", "enum": [ "cpu_usage", "memory_used", "disk_read", "disk_write", "network_in", "network_out" ], "description": "What is measured." }, "unit": { "type": "string", "enum": [ "Percent", "Bytes", "Bytes/Second" ], "description": "Unit of the values in this series." }, "points": { "type": "array", "items": { "$ref": "#/components/schemas/MetricPoint" }, "description": "Values in time order, one per step of the window." } } }, "Metrics": { "type": "object", "description": "Server measurements over a window.", "required": [ "start_time", "end_time", "step_seconds", "series" ], "properties": { "start_time": { "type": "string", "format": "date-time", "description": "Start of the window the answer covers." }, "end_time": { "type": "string", "format": "date-time", "description": "End of the window the answer covers." }, "step_seconds": { "type": "integer", "description": "Actual spacing between points. It can be coarser than you asked for." }, "series": { "type": "array", "items": { "$ref": "#/components/schemas/MetricSeries" }, "description": "One entry per measurement asked for." } } }, "ProjectBackupPolicy": { "type": "object", "description": "Whether new servers in this project get backups by default. Servers that set their own policy are not affected.", "required": [ "enabled" ], "properties": { "enabled": { "type": "boolean", "description": "Automatic backups are on for every server of the project that does not set its own policy." } } }, "Deleted": { "type": "object", "description": "Confirmation that the resource is gone.", "properties": { "deleted": { "type": "integer", "description": "Identifier of what was removed." } } }, "ServerDeleted": { "type": "object", "description": "The server is being destroyed. Addresses that stay billable are listed so you can release them yourself.", "properties": { "server_id": { "type": "integer", "description": "The server being destroyed." }, "billable_ips": { "type": "array", "items": { "$ref": "#/components/schemas/Ip" }, "description": "Public addresses the project keeps - and keeps paying for - after the server is gone." } } }, "DiskDeleted": { "type": "object", "description": "The data disk has been removed from the server.", "properties": { "deleted": { "type": "string", "description": "Slot name of the removed disk." }, "server_id": { "type": "integer", "description": "Server the disk was removed from." } } }, "NicDeleted": { "type": "object", "description": "The network card has been removed from the server. Addresses that stay billable are listed so you can release them yourself.", "properties": { "server_id": { "type": "integer", "description": "Server the card was removed from." }, "id": { "type": "string", "description": "Slot name of the removed card." }, "deleted": { "type": "boolean", "description": "The card is gone." }, "billable_ips": { "type": "array", "items": { "$ref": "#/components/schemas/Ip" }, "description": "Addresses released from the card that the project still holds and pays for." } } }, "DeletedDevice": { "type": "object", "description": "Confirmation that a VPN device is gone. Its identifier is a string (dev1, dev2, ...), unlike the numeric Deleted.", "required": [ "deleted", "revocation_pending" ], "properties": { "deleted": { "type": "string", "description": "Identifier of the removed device.", "examples": [ "dev1" ] }, "revocation_pending": { "type": "boolean", "description": "OpenVPN only, normally false. True means the device is removed from the platform but the router has not received the certificate revocation yet: the router still accepts that certificate until you send PUT /v1/servers/{id}/router/openvpn with enabled: true, which pushes the revocation list. Always false for WireGuard." } } }, "RouterWanIp": { "type": "object", "description": "Result of moving the router's public address.", "properties": { "server_id": { "type": "integer", "description": "The router this address belongs to." }, "ip_id": { "type": "integer", "description": "Identifier of the address, the same one GET /v1/ips uses." }, "address": { "type": "string", "description": "The address itself." }, "previous": { "type": "string", "description": "Address the router had before." }, "gateway": { "type": "string", "description": "Default gateway for the address." }, "prefix": { "type": "string", "description": "Network prefix of the address." } } }, "BackupDeleted": { "type": "object", "description": "The backup has been deleted.", "properties": { "deleted": { "type": "string", "description": "Identifier of the deleted backup - the moment it was taken." }, "server_id": { "type": "integer", "description": "Server the backup belonged to." } } }, "IsoDeleted": { "type": "object", "description": "The ISO image has been deleted, together with its file.", "properties": { "deleted": { "type": "string", "examples": [ "uiso-50" ], "description": "Identifier of the deleted image." } } }, "ServerImageDeleted": { "type": "object", "description": "The server image has been deleted, together with its file. Servers built from it can no longer be reinstalled from it.", "properties": { "deleted": { "type": "string", "examples": [ "utpl-12" ], "description": "Identifier of the deleted image." } } } }, "responses": { "Problem400": { "description": "Malformed request.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "description": "Identifier of this call - quote it when you contact support." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "Problem401": { "description": "No token, or the token is not valid.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "description": "Identifier of this call - quote it when you contact support." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "Problem402": { "description": "Payment required - the project is suspended, or its owner has an overdue invoice.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "description": "Identifier of this call - quote it when you contact support." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "Problem403": { "description": "The token or the team grant does not allow this operation.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "description": "Identifier of this call - quote it when you contact support." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "Problem404": { "description": "No such resource in this project.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "description": "Identifier of this call - quote it when you contact support." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "Problem409": { "description": "The request is valid but the current state blocks it. Change the state and repeat.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "description": "Identifier of this call - quote it when you contact support." }, "Retry-After": { "schema": { "type": "integer" }, "description": "Seconds to wait before repeating the request." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "Problem422": { "description": "The request did not pass validation. See invalid_params.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "description": "Identifier of this call - quote it when you contact support." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "Problem429": { "description": "Rate limit exceeded.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "description": "Identifier of this call - quote it when you contact support." }, "Retry-After": { "schema": { "type": "integer" }, "description": "Seconds to wait before repeating the request." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "Problem500": { "description": "Unexpected failure on our side.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "description": "Identifier of this call - quote it when you contact support." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "Problem503": { "description": "The request is valid, our side could not complete it. Repeat later.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "description": "Identifier of this call - quote it when you contact support." }, "Retry-After": { "schema": { "type": "integer" }, "description": "Seconds to wait before repeating the request." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "Problem415": { "description": "The body was not sent as JSON - a form-encoded body arrives here.", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "description": "Identifier of this call - quote it when you contact support." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }