{ "openapi": "3.1.0", "info": { "title": "arianet Cloud API", "version": "1.0.0", "description": "The arianet cloud API: servers, volumes, networks, IPs, firewalls, load balancers, images and\nbackups.\n\n**Authentication.** Send an API token as a bearer token (`Authorization: Bearer `). A token's\nscopes are `cloud:servers:read` (every GET) and `cloud:servers:write` (every change). Resources are\nalways the token's account's.\n\n**Asynchronous actions.** A change that takes time answers `202` (or `201` for a create) with an\n`action_id`. Poll `GET /actions/{id}` until `status` is `success` or `error`.\n\n**Lists.** Every resource list takes `label_selector`, `project_id` and opt-in `page`/`per_page`\n(default 25, at most 100), and answers `{\"data\": [...], \"meta\": {\"pagination\": {...}}}`. Without\n`page` and `per_page` the whole list is returned as one page.\n\n**Errors.** Every error is `{\"error\": \"...\", \"code\": \"...\", \"reason\": \"...\"}`; `code` is stable and\n`reason` narrows it when set. A `503` carries `Retry-After`.\n\n**Rate limits.** Each token's account and user may make 3600 requests an hour and 60 a minute. Every\nanswer carries `RateLimit-Limit`, `RateLimit-Remaining` and `RateLimit-Reset` (seconds until the window\nresets); over the limit the answer is `429` `rate_limit_exceeded` with `Retry-After`.\n" }, "servers": [ { "url": "https://api.ariaservice.net/cloud/v1", "description": "Public gateway. Authenticate with an API token as a bearer token; token scopes `cloud:servers:read` / `cloud:servers:write`." } ], "security": [ { "bearerAuth": [] } ], "tags": [ { "name": "Servers", "description": "Virtual servers." }, { "name": "Server actions", "description": "Asynchronous server operations: power, rebuild, rescue, plan, backups, networks." }, { "name": "Volumes", "description": "Block storage volumes." }, { "name": "Networks", "description": "Private networks, subnets and routes." }, { "name": "NAT gateways", "description": "Routers giving private networks outbound internet access." }, { "name": "Floating IPs", "description": "Floating IPs: addresses that move between servers." }, { "name": "Elastic IPs", "description": "Elastic IPs: a server's public address kept beyond the server." }, { "name": "Primary IPs", "description": "A server's own public addresses." }, { "name": "Firewalls", "description": "Firewalls and their rules." }, { "name": "Load balancers", "description": "Load balancers." }, { "name": "Images", "description": "Images servers are created from." }, { "name": "Snapshots", "description": "Snapshots of servers." }, { "name": "Backups", "description": "Daily and on-demand server backups." }, { "name": "Actions", "description": "Asynchronous actions." }, { "name": "Datacenters", "description": "Datacenters and their image catalogs." }, { "name": "Plans & pricing", "description": "Plans and prices." }, { "name": "Limits", "description": "The account's quotas." }, { "name": "Meta", "description": "This API description." } ], "paths": { "/actions": { "get": { "operationId": "listActions", "tags": [ "Actions" ], "summary": "List the account's actions", "description": "The account's activity, newest first. Without `page`/`per_page` at most `limit` (default 100, max 500) actions are returned; with them the list is paged and `meta.pagination` is present.", "parameters": [ { "name": "resource_type", "in": "query", "description": "Only actions on this kind of resource.", "schema": { "type": "string", "maxLength": 32, "pattern": "^[a-z_]*$" } }, { "name": "resource_id", "in": "query", "description": "Only actions on this resource.", "schema": { "type": "integer", "format": "int64", "minimum": 1 } }, { "name": "status", "in": "query", "description": "Only actions in this status.", "schema": { "type": "string", "enum": [ "running", "success", "error" ] } }, { "name": "since", "in": "query", "description": "Only actions started at or after this time (RFC 3339).", "schema": { "type": "string", "format": "date-time" } }, { "name": "limit", "in": "query", "description": "At most this many (unpaged; capped at 500).", "schema": { "type": "integer", "minimum": 1 } }, { "$ref": "#/components/parameters/page" }, { "$ref": "#/components/parameters/per_page" } ], "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ActionList" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/UnprocessableEntity" } } } }, "/actions/{id}": { "parameters": [ { "$ref": "#/components/parameters/id" } ], "get": { "operationId": "getAction", "tags": [ "Actions" ], "summary": "Get an action", "description": "Also open to an account held for identity verification, so its first server's creation can be followed.", "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Action" } }, "required": [ "data" ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/actions/{id}/events": { "parameters": [ { "$ref": "#/components/parameters/id" } ], "get": { "operationId": "listActionEvents", "tags": [ "Actions" ], "summary": "List an action's OpenStack events", "parameters": [ { "name": "after", "in": "query", "description": "Only events after this event id.", "schema": { "type": "integer", "format": "int64", "minimum": 0 } }, { "name": "limit", "in": "query", "description": "At most this many (1-500).", "schema": { "type": "integer", "minimum": 1, "maximum": 500, "default": 100 } } ], "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Event" } } }, "required": [ "data" ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/UnprocessableEntity" } } } }, "/backups": { "get": { "operationId": "listBackups", "tags": [ "Backups" ], "summary": "List backups", "parameters": [ { "$ref": "#/components/parameters/label_selector" }, { "$ref": "#/components/parameters/page" }, { "$ref": "#/components/parameters/per_page" }, { "$ref": "#/components/parameters/project_id" } ], "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BackupList" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/UnprocessableEntity" } } } }, "/backups/{id}": { "parameters": [ { "$ref": "#/components/parameters/id" } ], "get": { "operationId": "getBackup", "tags": [ "Backups" ], "summary": "Get a backup", "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Backup" } }, "required": [ "data" ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } }, "delete": { "operationId": "deleteBackup", "tags": [ "Backups" ], "summary": "Delete a backup", "responses": { "202": { "description": "Accepted; follow the action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ActionAccepted" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } } }, "/backups/{id}/actions/convert": { "parameters": [ { "$ref": "#/components/parameters/id" } ], "post": { "operationId": "convertBackup", "tags": [ "Backups" ], "summary": "Convert a backup to a snapshot", "description": "The copy is kept as a snapshot instead of rotating out with the backups.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "Snapshot name; the backup's when empty." } } } } } }, "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Snapshot" } }, "required": [ "data" ] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/UnprocessableEntity" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } } }, "/datacenters": { "get": { "operationId": "listDatacenters", "tags": [ "Datacenters" ], "summary": "List datacenters", "description": "Datacenters customers can see. A `closed` one is listed with `orderable: false`.", "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Datacenter" } } }, "required": [ "data" ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } } } }, "/datacenters/{code}/images": { "parameters": [ { "name": "code", "in": "path", "required": true, "description": "Datacenter code.", "schema": { "type": "string" } } ], "get": { "operationId": "listDatacenterImages", "tags": [ "Datacenters" ], "summary": "List a datacenter's image catalog", "description": "Platform images grouped and described for the create form, then the account's snapshots and backups there.", "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/CatalogImage" } } }, "required": [ "data" ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } } }, "/elastic-ips": { "get": { "operationId": "listElasticIPs", "tags": [ "Elastic IPs" ], "summary": "List elastic IPs", "parameters": [ { "$ref": "#/components/parameters/label_selector" }, { "$ref": "#/components/parameters/page" }, { "$ref": "#/components/parameters/per_page" }, { "$ref": "#/components/parameters/project_id" } ], "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ElasticIPList" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/UnprocessableEntity" } } }, "post": { "operationId": "createElasticIP", "tags": [ "Elastic IPs" ], "summary": "Create an elastic IP", "description": "`datacenter` may be left out when `server_id` is given.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "datacenter": { "type": "string", "description": "Datacenter code, e.g. `ovh`.", "examples": [ "ovh" ] }, "name": { "type": "string", "description": "A name is generated when empty." }, "server_id": { "type": "integer", "format": "int64", "description": "Assign it to this server." }, "labels": { "$ref": "#/components/schemas/Labels" }, "project_id": { "type": "integer", "format": "int64", "description": "Project to create it in; the account's Default project when absent.", "minimum": 1 } } } } } }, "responses": { "201": { "description": "Created.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/ElasticIP" }, "action_id": { "type": "integer", "format": "int64", "description": "The action creating it." } }, "required": [ "data", "action_id" ] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/UnprocessableEntity" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } } }, "/elastic-ips/{id}": { "parameters": [ { "$ref": "#/components/parameters/id" } ], "get": { "operationId": "getElasticIP", "tags": [ "Elastic IPs" ], "summary": "Get an elastic IP", "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/ElasticIP" } }, "required": [ "data" ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } }, "patch": { "operationId": "updateElasticIP", "tags": [ "Elastic IPs" ], "summary": "Update an elastic IP", "description": "Every field is optional: what is sent is changed, the rest stays.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "pattern": "^[a-zA-Z0-9]([a-zA-Z0-9.-]{0,61}[a-zA-Z0-9])?$" }, "labels": { "$ref": "#/components/schemas/Labels" }, "protection_delete": { "type": "boolean" }, "project_id": { "type": "integer", "format": "int64", "description": "Move it to this project of the account.", "minimum": 1 } } } } } }, "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/ElasticIP" } }, "required": [ "data" ] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/UnprocessableEntity" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } }, "delete": { "operationId": "deleteElasticIP", "tags": [ "Elastic IPs" ], "summary": "Delete an elastic IP", "responses": { "202": { "description": "Accepted; follow the action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ActionAccepted" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } } }, "/elastic-ips/{id}/actions": { "parameters": [ { "$ref": "#/components/parameters/id" } ], "get": { "operationId": "listElasticIPActions", "tags": [ "Elastic IPs" ], "summary": "List an elastic IP's actions", "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Action" } } }, "required": [ "data" ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/elastic-ips/{id}/actions/{op}": { "parameters": [ { "$ref": "#/components/parameters/id" }, { "name": "op", "in": "path", "required": true, "description": "The action.", "schema": { "type": "string", "enum": [ "assign", "unassign" ] } } ], "post": { "operationId": "elasticIPAction", "tags": [ "Elastic IPs" ], "summary": "Run an elastic IP action", "description": "`assign` to a server (`server_id`, else 422 `server_required`) or `unassign`.", "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "server_id": { "type": "integer", "format": "int64", "description": "With `assign`.", "minimum": 1 } } } } } }, "responses": { "202": { "description": "Accepted; follow the action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ActionAccepted" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/UnprocessableEntity" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } } }, "/firewalls": { "get": { "operationId": "listFirewalls", "tags": [ "Firewalls" ], "summary": "List firewalls", "parameters": [ { "$ref": "#/components/parameters/label_selector" }, { "$ref": "#/components/parameters/page" }, { "$ref": "#/components/parameters/per_page" }, { "$ref": "#/components/parameters/project_id" } ], "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FirewallList" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/UnprocessableEntity" } } }, "post": { "operationId": "createFirewall", "tags": [ "Firewalls" ], "summary": "Create a firewall", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "pattern": "^[a-zA-Z0-9]([a-zA-Z0-9.-]{0,61}[a-zA-Z0-9])?$" }, "rules": { "type": "array", "items": { "$ref": "#/components/schemas/FirewallRule" }, "maxItems": 50 }, "server_ids": { "type": "array", "items": { "type": "integer", "format": "int64" }, "description": "Servers to apply it to." }, "labels": { "$ref": "#/components/schemas/Labels" }, "project_id": { "type": "integer", "format": "int64", "description": "Project to create it in; the account's Default project when absent.", "minimum": 1 } }, "required": [ "name" ] } } } }, "responses": { "201": { "description": "Created; applying it is an action.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Firewall" }, "action_id": { "type": "integer", "format": "int64", "description": "The action creating it." } }, "required": [ "data", "action_id" ] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/UnprocessableEntity" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } } }, "/firewalls/{id}": { "parameters": [ { "$ref": "#/components/parameters/id" } ], "get": { "operationId": "getFirewall", "tags": [ "Firewalls" ], "summary": "Get a firewall", "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Firewall" } }, "required": [ "data" ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } }, "put": { "operationId": "replaceFirewall", "tags": [ "Firewalls" ], "summary": "Replace a firewall's name and rules", "description": "The rules replace every rule; the servers it is applied to are updated by the action.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "pattern": "^[a-zA-Z0-9]([a-zA-Z0-9.-]{0,61}[a-zA-Z0-9])?$" }, "rules": { "type": "array", "items": { "$ref": "#/components/schemas/FirewallRule" }, "maxItems": 50 } }, "required": [ "name", "rules" ] } } } }, "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Firewall" }, "action_id": { "type": "integer", "format": "int64", "description": "The action creating it." } }, "required": [ "data", "action_id" ] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/UnprocessableEntity" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } }, "patch": { "operationId": "updateFirewall", "tags": [ "Firewalls" ], "summary": "Update a firewall", "description": "Name, labels, delete protection or project. Every field is optional: what is sent is changed, the rest stays.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "pattern": "^[a-zA-Z0-9]([a-zA-Z0-9.-]{0,61}[a-zA-Z0-9])?$" }, "labels": { "$ref": "#/components/schemas/Labels" }, "protection_delete": { "type": "boolean" }, "project_id": { "type": "integer", "format": "int64", "description": "Move it to this project of the account.", "minimum": 1 } } } } } }, "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Firewall" } }, "required": [ "data" ] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/UnprocessableEntity" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } }, "delete": { "operationId": "deleteFirewall", "tags": [ "Firewalls" ], "summary": "Delete a firewall", "responses": { "202": { "description": "Accepted; follow the action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ActionAccepted" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } } }, "/firewalls/{id}/actions": { "parameters": [ { "$ref": "#/components/parameters/id" } ], "get": { "operationId": "listFirewallActions", "tags": [ "Firewalls" ], "summary": "List a firewall's actions", "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Action" } } }, "required": [ "data" ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/firewalls/{id}/actions/{op}": { "parameters": [ { "$ref": "#/components/parameters/id" }, { "name": "op", "in": "path", "required": true, "description": "The action.", "schema": { "type": "string", "enum": [ "apply_to_resources", "remove_from_resources" ] } } ], "post": { "operationId": "firewallAction", "tags": [ "Firewalls" ], "summary": "Apply a firewall to, or remove it from, resources", "description": "Takes `server_ids`, or targets in `apply_to` / `remove_from` (servers or label selectors).", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "server_ids": { "type": "array", "items": { "type": "integer", "format": "int64" } }, "apply_to": { "type": "array", "items": { "$ref": "#/components/schemas/FirewallTarget" }, "description": "With `apply_to_resources`." }, "remove_from": { "type": "array", "items": { "$ref": "#/components/schemas/FirewallTarget" }, "description": "With `remove_from_resources`." } } } } } }, "responses": { "202": { "description": "Accepted; follow the action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ActionAccepted" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/UnprocessableEntity" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } } }, "/firewalls/{id}/servers": { "parameters": [ { "$ref": "#/components/parameters/id" } ], "put": { "operationId": "setFirewallServers", "tags": [ "Firewalls" ], "summary": "Set the servers a firewall is applied to", "description": "Replaces the directly applied servers.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "server_ids": { "type": "array", "items": { "type": "integer", "format": "int64" } } }, "required": [ "server_ids" ] } } } }, "responses": { "202": { "description": "Accepted; follow the action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ActionAccepted" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/UnprocessableEntity" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } } }, "/floating-ips": { "get": { "operationId": "listFloatingIPs", "tags": [ "Floating IPs" ], "summary": "List floating IPs", "parameters": [ { "$ref": "#/components/parameters/label_selector" }, { "$ref": "#/components/parameters/page" }, { "$ref": "#/components/parameters/per_page" }, { "$ref": "#/components/parameters/project_id" } ], "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FloatingIPList" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/UnprocessableEntity" } } }, "post": { "operationId": "createFloatingIP", "tags": [ "Floating IPs" ], "summary": "Create a floating IP", "description": "`datacenter` may be left out when `server_id` is given.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "datacenter": { "type": "string", "description": "Datacenter code, e.g. `ovh`.", "examples": [ "ovh" ] }, "type": { "type": "string", "enum": [ "ipv4", "ipv6" ] }, "name": { "type": "string" }, "description": { "type": "string" }, "server_id": { "type": "integer", "format": "int64", "description": "Assign it to this server." }, "labels": { "$ref": "#/components/schemas/Labels" }, "project_id": { "type": "integer", "format": "int64", "description": "Project to create it in; the account's Default project when absent.", "minimum": 1 } }, "required": [ "type" ] } } } }, "responses": { "201": { "description": "Created.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/FloatingIP" }, "action_id": { "type": "integer", "format": "int64", "description": "The action creating it." } }, "required": [ "data", "action_id" ] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/UnprocessableEntity" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } } }, "/floating-ips/{id}": { "parameters": [ { "$ref": "#/components/parameters/id" } ], "get": { "operationId": "getFloatingIP", "tags": [ "Floating IPs" ], "summary": "Get a floating IP", "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/FloatingIP" } }, "required": [ "data" ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } }, "patch": { "operationId": "updateFloatingIP", "tags": [ "Floating IPs" ], "summary": "Update a floating IP", "description": "Every field is optional: what is sent is changed, the rest stays.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "pattern": "^[a-zA-Z0-9]([a-zA-Z0-9.-]{0,61}[a-zA-Z0-9])?$" }, "labels": { "$ref": "#/components/schemas/Labels" }, "protection_delete": { "type": "boolean" }, "project_id": { "type": "integer", "format": "int64", "description": "Move it to this project of the account.", "minimum": 1 }, "description": { "type": "string" } } } } } }, "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/FloatingIP" } }, "required": [ "data" ] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/UnprocessableEntity" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } }, "delete": { "operationId": "deleteFloatingIP", "tags": [ "Floating IPs" ], "summary": "Delete a floating IP", "responses": { "202": { "description": "Accepted; follow the action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ActionAccepted" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } } }, "/floating-ips/{id}/actions": { "parameters": [ { "$ref": "#/components/parameters/id" } ], "get": { "operationId": "listFloatingIPActions", "tags": [ "Floating IPs" ], "summary": "List a floating IP's actions", "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Action" } } }, "required": [ "data" ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/floating-ips/{id}/actions/{op}": { "parameters": [ { "$ref": "#/components/parameters/id" }, { "name": "op", "in": "path", "required": true, "description": "The action.", "schema": { "type": "string", "enum": [ "assign", "unassign", "change_dns_ptr" ] } } ], "post": { "operationId": "floatingIPAction", "tags": [ "Floating IPs" ], "summary": "Run a floating IP action", "description": "`assign` to a server (`server_id`, else 422 `server_required`), `unassign`, or `change_dns_ptr`.", "requestBody": { "required": false, "content": { "application/json": { "schema": { "description": "`assign` takes `server_id`, `change_dns_ptr` takes `dns_ptr`; `unassign` takes no body.", "anyOf": [ { "type": "object", "properties": { "server_id": { "type": "integer", "format": "int64", "minimum": 1 } }, "required": [ "server_id" ], "title": "assign" }, { "type": "object", "properties": { "dns_ptr": { "type": [ "string", "null" ], "description": "Hostname; null or empty resets it." } }, "required": [ "dns_ptr" ], "title": "change_dns_ptr" } ] } } } }, "responses": { "202": { "description": "Accepted; follow the action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ActionAccepted" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/UnprocessableEntity" }, "501": { "$ref": "#/components/responses/NotImplemented" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } } }, "/images": { "get": { "operationId": "listImages", "tags": [ "Images" ], "summary": "List images", "description": "Every image a server can be created from: platform system and app images (one row per image, with the datacenters that have it) and the account's snapshots and backups.", "parameters": [ { "name": "type", "in": "query", "description": "Only this type.", "schema": { "type": "string", "enum": [ "system", "app", "snapshot", "backup" ] } }, { "name": "datacenter", "in": "query", "description": "Only images in this datacenter.", "schema": { "type": "string" } }, { "$ref": "#/components/parameters/label_selector" }, { "$ref": "#/components/parameters/page" }, { "$ref": "#/components/parameters/per_page" }, { "$ref": "#/components/parameters/project_id" } ], "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ImageList" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/UnprocessableEntity" } } } }, "/images/custom": { "get": { "operationId": "listCustomImages", "tags": [ "Images" ], "summary": "List the account's snapshots and backups as catalog images", "parameters": [ { "name": "datacenter", "in": "query", "description": "Only this datacenter.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/CatalogImage" } } }, "required": [ "data" ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } } } }, "/limits": { "get": { "operationId": "listLimits", "tags": [ "Limits" ], "summary": "List the account's limits", "description": "The account's limits and what it uses of them, per datacenter. A create past a limit is refused with 422 `quota_exceeded` and the resource as `reason`.", "parameters": [ { "name": "datacenter", "in": "query", "description": "Only this datacenter.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/DatacenterLimits" } } }, "required": [ "data" ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/load-balancer-types": { "get": { "operationId": "listLoadBalancerTypes", "tags": [ "Load balancers" ], "summary": "List load balancer types", "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/LoadBalancerType" } } }, "required": [ "data" ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } } } }, "/load-balancers": { "get": { "operationId": "listLoadBalancers", "tags": [ "Load balancers" ], "summary": "List load balancers", "parameters": [ { "$ref": "#/components/parameters/label_selector" }, { "$ref": "#/components/parameters/page" }, { "$ref": "#/components/parameters/per_page" }, { "$ref": "#/components/parameters/project_id" } ], "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LoadBalancerList" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/UnprocessableEntity" } } }, "post": { "operationId": "createLoadBalancer", "tags": [ "Load balancers" ], "summary": "Create a load balancer", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "datacenter": { "type": "string", "description": "Datacenter code, e.g. `ovh`.", "examples": [ "ovh" ] }, "name": { "type": "string", "pattern": "^[a-zA-Z0-9]([a-zA-Z0-9.-]{0,61}[a-zA-Z0-9])?$" }, "type": { "type": "string", "description": "Type code, e.g. `lb11`." }, "algorithm": { "type": "string", "description": "Default `round_robin`.", "enum": [ "round_robin", "least_connections" ] }, "public_interface": { "type": "boolean", "description": "Default true." }, "network_id": { "description": "An id, as a JSON number or a numeric string.", "oneOf": [ { "type": "integer", "format": "int64", "minimum": 1 }, { "type": "string", "pattern": "^[0-9]+$" } ] }, "services": { "type": "array", "items": { "$ref": "#/components/schemas/LBService" } }, "targets": { "type": "array", "items": { "$ref": "#/components/schemas/LBTargetInput" } }, "labels": { "$ref": "#/components/schemas/Labels" }, "project_id": { "type": "integer", "format": "int64", "description": "Project to create it in; the account's Default project when absent.", "minimum": 1 } }, "required": [ "datacenter", "name", "type" ] } } } }, "responses": { "201": { "description": "Created.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/LoadBalancer" }, "action_id": { "type": "integer", "format": "int64", "description": "The action creating it." } }, "required": [ "data", "action_id" ] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/UnprocessableEntity" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } } }, "/load-balancers/{id}": { "parameters": [ { "$ref": "#/components/parameters/id" } ], "get": { "operationId": "getLoadBalancer", "tags": [ "Load balancers" ], "summary": "Get a load balancer", "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/LoadBalancer" } }, "required": [ "data" ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } }, "patch": { "operationId": "updateLoadBalancer", "tags": [ "Load balancers" ], "summary": "Update a load balancer", "description": "Every field is optional: what is sent is changed, the rest stays.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "pattern": "^[a-zA-Z0-9]([a-zA-Z0-9.-]{0,61}[a-zA-Z0-9])?$" }, "labels": { "$ref": "#/components/schemas/Labels" }, "protection_delete": { "type": "boolean" }, "project_id": { "type": "integer", "format": "int64", "description": "Move it to this project of the account.", "minimum": 1 } } } } } }, "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/LoadBalancer" } }, "required": [ "data" ] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/UnprocessableEntity" }, "423": { "$ref": "#/components/responses/Locked" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } }, "delete": { "operationId": "deleteLoadBalancer", "tags": [ "Load balancers" ], "summary": "Delete a load balancer", "responses": { "202": { "description": "Accepted; follow the action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ActionAccepted" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "423": { "$ref": "#/components/responses/Locked" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } } }, "/load-balancers/{id}/actions": { "parameters": [ { "$ref": "#/components/parameters/id" } ], "get": { "operationId": "listLoadBalancerActions", "tags": [ "Load balancers" ], "summary": "List a load balancer's actions", "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Action" } } }, "required": [ "data" ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/load-balancers/{id}/actions/{op}": { "parameters": [ { "$ref": "#/components/parameters/id" }, { "name": "op", "in": "path", "required": true, "description": "The action.", "schema": { "type": "string", "enum": [ "update_services", "add_service", "update_service", "delete_service", "add_target", "remove_target", "change_type", "change_algorithm", "attach_to_network", "detach_from_network" ] } } ], "post": { "operationId": "loadBalancerAction", "tags": [ "Load balancers" ], "summary": "Run a load balancer action", "description": "Change services (listeners), targets, type, algorithm or private network.", "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LoadBalancerOperationRequest" } } } }, "responses": { "202": { "description": "Accepted; follow the action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ActionAccepted" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/UnprocessableEntity" }, "423": { "$ref": "#/components/responses/Locked" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } } }, "/load-balancers/{id}/health": { "parameters": [ { "$ref": "#/components/parameters/id" } ], "get": { "operationId": "getLoadBalancerHealth", "tags": [ "Load balancers" ], "summary": "Refresh a load balancer's target health", "description": "Reads the targets' health now and returns the load balancer.", "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/LoadBalancer" } }, "required": [ "data" ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } } }, "/nat-gateways": { "get": { "operationId": "listNATGateways", "tags": [ "NAT gateways" ], "summary": "List NAT gateways", "parameters": [ { "$ref": "#/components/parameters/label_selector" }, { "$ref": "#/components/parameters/page" }, { "$ref": "#/components/parameters/per_page" }, { "$ref": "#/components/parameters/project_id" } ], "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NATGatewayList" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/UnprocessableEntity" } } }, "post": { "operationId": "createNATGateway", "tags": [ "NAT gateways" ], "summary": "Create a NAT gateway", "description": "A router giving a private network's servers outbound internet access through one public address.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "A name is generated when empty." }, "network_id": { "type": "integer", "format": "int64", "minimum": 1 }, "labels": { "$ref": "#/components/schemas/Labels" }, "project_id": { "type": "integer", "format": "int64", "description": "Project to create it in; the account's Default project when absent.", "minimum": 1 } }, "required": [ "network_id" ] } } } }, "responses": { "201": { "description": "Created.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/NATGateway" }, "action_id": { "type": "integer", "format": "int64", "description": "The action creating it." } }, "required": [ "data", "action_id" ] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/UnprocessableEntity" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } } }, "/nat-gateways/{id}": { "parameters": [ { "$ref": "#/components/parameters/id" } ], "get": { "operationId": "getNATGateway", "tags": [ "NAT gateways" ], "summary": "Get a NAT gateway", "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/NATGateway" } }, "required": [ "data" ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } }, "patch": { "operationId": "updateNATGateway", "tags": [ "NAT gateways" ], "summary": "Update a NAT gateway", "description": "Every field is optional: what is sent is changed, the rest stays.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "pattern": "^[a-zA-Z0-9]([a-zA-Z0-9.-]{0,61}[a-zA-Z0-9])?$" }, "labels": { "$ref": "#/components/schemas/Labels" }, "protection_delete": { "type": "boolean" }, "project_id": { "type": "integer", "format": "int64", "description": "Move it to this project of the account.", "minimum": 1 } } } } } }, "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/NATGateway" } }, "required": [ "data" ] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/UnprocessableEntity" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } }, "delete": { "operationId": "deleteNATGateway", "tags": [ "NAT gateways" ], "summary": "Delete a NAT gateway", "responses": { "202": { "description": "Accepted; follow the action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ActionAccepted" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } } }, "/nat-gateways/{id}/actions": { "parameters": [ { "$ref": "#/components/parameters/id" } ], "get": { "operationId": "listNATGatewayActions", "tags": [ "NAT gateways" ], "summary": "List a NAT gateway's actions", "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Action" } } }, "required": [ "data" ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/networks": { "get": { "operationId": "listNetworks", "tags": [ "Networks" ], "summary": "List private networks", "parameters": [ { "$ref": "#/components/parameters/label_selector" }, { "$ref": "#/components/parameters/page" }, { "$ref": "#/components/parameters/per_page" }, { "$ref": "#/components/parameters/project_id" } ], "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NetworkList" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/UnprocessableEntity" } } }, "post": { "operationId": "createNetwork", "tags": [ "Networks" ], "summary": "Create a private network", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "pattern": "^[a-zA-Z0-9]([a-zA-Z0-9.-]{0,61}[a-zA-Z0-9])?$" }, "datacenter": { "type": "string", "description": "Datacenter code, e.g. `ovh`.", "examples": [ "ovh" ] }, "ip_range": { "type": "string", "description": "Private CIDR of the network, e.g. `10.0.0.0/16`." }, "subnet_ip_range": { "type": "string", "description": "First subnet, inside `ip_range`; one is made from it when absent." }, "labels": { "$ref": "#/components/schemas/Labels" }, "project_id": { "type": "integer", "format": "int64", "description": "Project to create it in; the account's Default project when absent.", "minimum": 1 } }, "required": [ "name", "datacenter", "ip_range" ] } } } }, "responses": { "201": { "description": "Created.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Network" }, "action_id": { "type": "integer", "format": "int64", "description": "The action creating it." } }, "required": [ "data", "action_id" ] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/UnprocessableEntity" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } } }, "/networks/{id}": { "parameters": [ { "$ref": "#/components/parameters/id" } ], "get": { "operationId": "getNetwork", "tags": [ "Networks" ], "summary": "Get a private network", "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Network" } }, "required": [ "data" ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } }, "patch": { "operationId": "updateNetwork", "tags": [ "Networks" ], "summary": "Update a private network", "description": "Every field is optional: what is sent is changed, the rest stays.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "pattern": "^[a-zA-Z0-9]([a-zA-Z0-9.-]{0,61}[a-zA-Z0-9])?$" }, "labels": { "$ref": "#/components/schemas/Labels" }, "protection_delete": { "type": "boolean" }, "project_id": { "type": "integer", "format": "int64", "description": "Move it to this project of the account.", "minimum": 1 } } } } } }, "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Network" } }, "required": [ "data" ] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/UnprocessableEntity" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } }, "delete": { "operationId": "deleteNetwork", "tags": [ "Networks" ], "summary": "Delete a private network", "responses": { "202": { "description": "Accepted; follow the action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ActionAccepted" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } } }, "/networks/{id}/actions": { "parameters": [ { "$ref": "#/components/parameters/id" } ], "get": { "operationId": "listNetworkActions", "tags": [ "Networks" ], "summary": "List a network's actions", "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Action" } } }, "required": [ "data" ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/networks/{id}/routes": { "parameters": [ { "$ref": "#/components/parameters/id" } ], "put": { "operationId": "setNetworkRoutes", "tags": [ "Networks" ], "summary": "Replace a network's routes", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "routes": { "type": "array", "items": { "$ref": "#/components/schemas/Route" } } }, "required": [ "routes" ] } } } }, "responses": { "202": { "description": "Accepted; follow the action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ActionAccepted" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/UnprocessableEntity" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } } }, "/networks/{id}/subnets": { "parameters": [ { "$ref": "#/components/parameters/id" } ], "post": { "operationId": "addSubnet", "tags": [ "Networks" ], "summary": "Add a subnet", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "ip_range": { "type": "string", "description": "CIDR inside the network's range." } }, "required": [ "ip_range" ] } } } }, "responses": { "202": { "description": "Accepted; the subnet is being made.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Subnet" }, "action_id": { "type": "integer", "format": "int64", "description": "The action creating it." } }, "required": [ "data", "action_id" ] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/UnprocessableEntity" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } } }, "/networks/{id}/subnets/{subnet}": { "parameters": [ { "$ref": "#/components/parameters/id" }, { "name": "subnet", "in": "path", "required": true, "description": "Subnet id.", "schema": { "type": "integer", "format": "int64", "minimum": 1 } } ], "delete": { "operationId": "deleteSubnet", "tags": [ "Networks" ], "summary": "Delete a subnet", "responses": { "202": { "description": "Accepted; follow the action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ActionAccepted" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } } }, "/openapi.json": { "get": { "operationId": "getOpenAPIDocument", "tags": [ "Meta" ], "summary": "This API description", "description": "The OpenAPI document of this API. Public: no token needed.", "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "description": "An OpenAPI 3.1 document." } } } } }, "security": [] } }, "/plans": { "get": { "operationId": "listPlans", "tags": [ "Plans & pricing" ], "summary": "List server plans", "description": "Active plans, cheapest first within their group, each with whether it can be ordered right now.", "parameters": [ { "name": "datacenter", "in": "query", "description": "Only this datacenter's plans.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Plan" } } }, "required": [ "data" ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } } }, "/pricing": { "get": { "operationId": "listPricing", "tags": [ "Plans & pricing" ], "summary": "List prices", "description": "Every active SKU price (snapshots, backups, block storage, IPs...).", "parameters": [ { "name": "datacenter", "in": "query", "description": "Only this datacenter's prices.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Pricing" } } }, "required": [ "data" ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } } }, "/primary-ips": { "get": { "operationId": "listPrimaryIPs", "tags": [ "Primary IPs" ], "summary": "List primary IPs", "description": "Primary IPs have no labels: a `label_selector` only matches with `!key` terms.", "parameters": [ { "$ref": "#/components/parameters/label_selector" }, { "$ref": "#/components/parameters/page" }, { "$ref": "#/components/parameters/per_page" }, { "$ref": "#/components/parameters/project_id" } ], "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PrimaryIPList" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/UnprocessableEntity" } } } }, "/primary-ips/{id}": { "parameters": [ { "$ref": "#/components/parameters/id" } ], "get": { "operationId": "getPrimaryIP", "tags": [ "Primary IPs" ], "summary": "Get a primary IP", "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/PrimaryIP" } }, "required": [ "data" ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } }, "patch": { "operationId": "updatePrimaryIP", "tags": [ "Primary IPs" ], "summary": "Move a primary IP to another project", "description": "Only `project_id` can be changed (anything else is 422 `invalid_request`).", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "project_id": { "type": "integer", "format": "int64", "minimum": 1 } }, "required": [ "project_id" ] } } } }, "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/PrimaryIP" } }, "required": [ "data" ] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/UnprocessableEntity" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } } }, "/primary-ips/{id}/actions": { "parameters": [ { "$ref": "#/components/parameters/id" } ], "get": { "operationId": "listPrimaryIPActions", "tags": [ "Primary IPs" ], "summary": "List a primary IP's actions", "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Action" } } }, "required": [ "data" ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/primary-ips/{id}/actions/change_dns_ptr": { "parameters": [ { "$ref": "#/components/parameters/id" } ], "post": { "operationId": "changePrimaryIPDNSPtr", "tags": [ "Primary IPs" ], "summary": "Change a primary IP's reverse DNS", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "dns_ptr": { "type": [ "string", "null" ], "description": "Hostname; null or empty resets it." } }, "required": [ "dns_ptr" ] } } } }, "responses": { "202": { "description": "Accepted; follow the action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ActionAccepted" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/UnprocessableEntity" }, "501": { "$ref": "#/components/responses/NotImplemented" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } } }, "/public/pricing": { "get": { "operationId": "getPublicPricing", "tags": [ "Plans & pricing" ], "summary": "Public price list", "description": "Every listed plan per location and every other price on sale (IPs, volumes, snapshots, backups, load balancers, NAT gateways), VAT excluded, from the same rows billing uses. Public: no token needed, any origin, cached for a minute.", "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "properties": { "pricing": { "$ref": "#/components/schemas/PublicPricing" } }, "required": [ "pricing" ] } } } } }, "security": [] } }, "/servers": { "get": { "operationId": "listServers", "tags": [ "Servers" ], "summary": "List servers", "parameters": [ { "$ref": "#/components/parameters/label_selector" }, { "$ref": "#/components/parameters/page" }, { "$ref": "#/components/parameters/per_page" }, { "$ref": "#/components/parameters/project_id" } ], "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ServerList" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/UnprocessableEntity" } } }, "post": { "operationId": "createServer", "tags": [ "Servers" ], "summary": "Create servers", "description": "Creates one server, or up to 10 with `count`. The root password is in the response only.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ServerCreateRequest" } } } }, "responses": { "201": { "description": "Created; the servers are being built.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ServerCreateResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/UnprocessableEntity" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } } }, "/servers/{id}": { "parameters": [ { "$ref": "#/components/parameters/id" } ], "get": { "operationId": "getServer", "tags": [ "Servers" ], "summary": "Get a server", "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Server" } }, "required": [ "data" ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } }, "patch": { "operationId": "updateServer", "tags": [ "Servers" ], "summary": "Update a server", "description": "Rename, change protection or labels, or move to another project (`project_id`).", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ServerUpdateRequest" } } } }, "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Server" } }, "required": [ "data" ] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/UnprocessableEntity" }, "423": { "$ref": "#/components/responses/Locked" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } }, "delete": { "operationId": "deleteServer", "tags": [ "Servers" ], "summary": "Delete a server", "parameters": [ { "name": "reason", "in": "query", "description": "Why it is deleted (optional).", "schema": { "type": "string", "enum": [ "price", "performance", "ip_filtered", "no_longer_needed", "migrating", "support", "other" ] } }, { "name": "note", "in": "query", "description": "A few words why; required with reason `other`.", "schema": { "type": "string", "maxLength": 500 } }, { "name": "keep_backups", "in": "query", "description": "Keep the finished backups as snapshots, billed per GB until deleted (402 when the balance does not cover them).", "schema": { "type": "boolean", "default": false } }, { "name": "delete_snapshots", "in": "query", "description": "Delete the server's snapshots too; protected ones stay. By default snapshots survive the server.", "schema": { "type": "boolean", "default": false } } ], "responses": { "202": { "description": "Accepted; follow the action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ActionAccepted" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/UnprocessableEntity" }, "423": { "$ref": "#/components/responses/Locked" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } } }, "/servers/{id}/actions": { "parameters": [ { "$ref": "#/components/parameters/id" } ], "get": { "operationId": "listServerActions", "tags": [ "Servers" ], "summary": "List a server's actions", "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Action" } } }, "required": [ "data" ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/servers/{id}/actions/attach_to_network": { "parameters": [ { "$ref": "#/components/parameters/id" } ], "post": { "operationId": "attachServerToNetwork", "tags": [ "Server actions" ], "summary": "Attach a server to a private network", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "network_id": { "type": "integer", "format": "int64", "minimum": 1 }, "subnet_id": { "type": "integer", "format": "int64", "description": "Subnet; the first one when absent." }, "ip": { "type": "string", "description": "Address to take; one is picked when absent." } }, "required": [ "network_id" ] } } } }, "responses": { "202": { "description": "Accepted; follow the action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ActionAccepted" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/UnprocessableEntity" }, "423": { "$ref": "#/components/responses/Locked" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } } }, "/servers/{id}/actions/change_backup_window": { "parameters": [ { "$ref": "#/components/parameters/id" } ], "post": { "operationId": "changeServerBackupWindow", "tags": [ "Server actions" ], "summary": "Change the backup window", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "window_hour": { "type": "integer", "description": "UTC hour, 0-23.", "minimum": 0, "maximum": 23 } }, "required": [ "window_hour" ] } } } }, "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "properties": { "plan": { "$ref": "#/components/schemas/BackupPlan" }, "action_id": { "type": "integer", "format": "int64" } }, "required": [ "plan", "action_id" ] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/UnprocessableEntity" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } } }, "/servers/{id}/actions/create_backup": { "parameters": [ { "$ref": "#/components/parameters/id" } ], "post": { "operationId": "createServerBackup", "tags": [ "Server actions" ], "summary": "Take a backup now", "responses": { "202": { "description": "Accepted; the backup is being taken.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Backup" }, "action_id": { "type": "integer", "format": "int64", "description": "The action creating it." } }, "required": [ "data", "action_id" ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/UnprocessableEntity" }, "423": { "$ref": "#/components/responses/Locked" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } } }, "/servers/{id}/actions/create_image": { "parameters": [ { "$ref": "#/components/parameters/id" } ], "post": { "operationId": "createServerSnapshot", "tags": [ "Server actions" ], "summary": "Snapshot a server", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "pattern": "^[a-zA-Z0-9]([a-zA-Z0-9.-]{0,61}[a-zA-Z0-9])?$" }, "description": { "type": "string" }, "labels": { "$ref": "#/components/schemas/Labels" } } } } } }, "responses": { "201": { "description": "Created; the snapshot is being taken.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Snapshot" }, "action_id": { "type": "integer", "format": "int64", "description": "The action creating it." } }, "required": [ "data", "action_id" ] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/UnprocessableEntity" }, "423": { "$ref": "#/components/responses/Locked" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } } }, "/servers/{id}/actions/detach_from_network": { "parameters": [ { "$ref": "#/components/parameters/id" } ], "post": { "operationId": "detachServerFromNetwork", "tags": [ "Server actions" ], "summary": "Detach a server from a private network", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "network_id": { "type": "integer", "format": "int64", "minimum": 1 } }, "required": [ "network_id" ] } } } }, "responses": { "202": { "description": "Accepted; follow the action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ActionAccepted" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/UnprocessableEntity" }, "423": { "$ref": "#/components/responses/Locked" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } } }, "/servers/{id}/actions/disable_backup": { "parameters": [ { "$ref": "#/components/parameters/id" } ], "post": { "operationId": "disableServerBackup", "tags": [ "Server actions" ], "summary": "Disable daily backups", "description": "Existing backups are kept.", "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ActionAccepted" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/UnprocessableEntity" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } } }, "/servers/{id}/actions/enable_backup": { "parameters": [ { "$ref": "#/components/parameters/id" } ], "post": { "operationId": "enableServerBackup", "tags": [ "Server actions" ], "summary": "Enable daily backups", "description": "The body may be left out; the window is then picked for you.", "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "window_hour": { "type": [ "integer", "null" ], "description": "UTC hour, 0-23.", "minimum": 0, "maximum": 23 } } } } } }, "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "properties": { "plan": { "$ref": "#/components/schemas/BackupPlan" }, "action_id": { "type": "integer", "format": "int64" } }, "required": [ "plan", "action_id" ] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/UnprocessableEntity" }, "423": { "$ref": "#/components/responses/Locked" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } } }, "/servers/{id}/actions/restore_backup": { "parameters": [ { "$ref": "#/components/parameters/id" } ], "post": { "operationId": "restoreServerBackup", "tags": [ "Server actions" ], "summary": "Restore a server from a backup", "description": "Overwrites the server's disk; a new root password is returned once.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "backup_id": { "description": "An id, as a JSON number or a numeric string.", "oneOf": [ { "type": "integer", "format": "int64", "minimum": 1 }, { "type": "string", "pattern": "^[0-9]+$" } ] } }, "required": [ "backup_id" ] } } } }, "responses": { "202": { "description": "Accepted; follow the action.", "content": { "application/json": { "schema": { "type": "object", "properties": { "action_id": { "type": "integer", "format": "int64" }, "root_password": { "type": "string" } }, "required": [ "action_id", "root_password" ] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/UnprocessableEntity" }, "423": { "$ref": "#/components/responses/Locked" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } } }, "/servers/{id}/actions/{op}": { "parameters": [ { "$ref": "#/components/parameters/id" }, { "name": "op", "in": "path", "required": true, "description": "The action.", "schema": { "type": "string", "enum": [ "poweron", "poweroff", "shutdown", "reboot", "reset", "rebuild", "change_plan", "enable_rescue", "disable_rescue", "reset_password", "change_ipv4" ] } } ], "post": { "operationId": "serverAction", "tags": [ "Server actions" ], "summary": "Run a server action", "description": "Power (`poweron`, `poweroff` hard, `shutdown` ACPI, `reboot`, `reset`), `rebuild` from an image (new root password), `change_plan`, `enable_rescue` / `disable_rescue`, `reset_password`, and `change_ipv4` (a paid change needs `confirm_paid: true`, else 409 `ip_change_fee_not_confirmed`). The other server actions have paths of their own.", "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ServerOperationRequest" } } } }, "responses": { "202": { "description": "Accepted; follow the action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ServerOperationResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/UnprocessableEntity" }, "423": { "$ref": "#/components/responses/Locked" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } } }, "/servers/{id}/backups": { "parameters": [ { "$ref": "#/components/parameters/id" } ], "get": { "operationId": "listServerBackups", "tags": [ "Backups" ], "summary": "List a server's backups and backup plan", "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Backup" } }, "plan": { "anyOf": [ { "$ref": "#/components/schemas/BackupPlan" }, { "type": "null" } ] }, "slots": { "type": "integer", "description": "Backups kept." } }, "required": [ "data", "plan", "slots" ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/servers/{id}/console": { "parameters": [ { "$ref": "#/components/parameters/id" } ], "post": { "operationId": "openServerConsole", "tags": [ "Servers" ], "summary": "Open a VNC console", "description": "A single-use console link valid for 60 seconds.", "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConsoleLink" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/UnprocessableEntity" }, "423": { "$ref": "#/components/responses/Locked" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } } }, "/servers/{id}/costs": { "parameters": [ { "$ref": "#/components/parameters/id" } ], "get": { "operationId": "getServerCosts", "tags": [ "Servers" ], "summary": "Get a server's cost", "description": "The server's current hourly and monthly rate per billed piece (plan, primary IPv4, floating and elastic IPs, attached volumes, backup add-on), and what its copies cost after a delete.", "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/ServerCost" } }, "required": [ "data" ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/UnprocessableEntity" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } } }, "/servers/{id}/events": { "parameters": [ { "$ref": "#/components/parameters/id" } ], "get": { "operationId": "listServerEvents", "tags": [ "Servers" ], "summary": "List a server's OpenStack events", "parameters": [ { "name": "after", "in": "query", "description": "Only events after this event id.", "schema": { "type": "integer", "format": "int64", "minimum": 0 } }, { "name": "limit", "in": "query", "description": "At most this many (1-500).", "schema": { "type": "integer", "minimum": 1, "maximum": 500, "default": 100 } } ], "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Event" } } }, "required": [ "data" ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/UnprocessableEntity" } } } }, "/servers/{id}/ip-changes": { "parameters": [ { "$ref": "#/components/parameters/id" } ], "get": { "operationId": "listServerIPChanges", "tags": [ "Servers" ], "summary": "List a server's IPv4 changes", "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/IPChangeRecord" } } }, "required": [ "data" ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/servers/{id}/metrics": { "parameters": [ { "$ref": "#/components/parameters/id" } ], "get": { "operationId": "getServerMetrics", "tags": [ "Servers" ], "summary": "Get server metrics", "description": "CPU, disk or network graphs, at most 31 days at a time.", "parameters": [ { "name": "type", "in": "query", "description": "Which graph.", "schema": { "type": "string", "enum": [ "cpu", "disk", "network" ] }, "required": true }, { "name": "start", "in": "query", "description": "Start (RFC 3339).", "schema": { "type": "string", "format": "date-time" }, "required": true }, { "name": "end", "in": "query", "description": "End (RFC 3339), after start.", "schema": { "type": "string", "format": "date-time" }, "required": true }, { "name": "step", "in": "query", "description": "Seconds between points.", "schema": { "type": "integer", "description": "Seconds between points.", "minimum": 1 } } ], "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/ServerMetrics" } }, "required": [ "data" ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/UnprocessableEntity" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } } }, "/servers/{id}/networking": { "parameters": [ { "$ref": "#/components/parameters/id" } ], "get": { "operationId": "getServerNetworking", "tags": [ "Servers" ], "summary": "Get a server's networking", "description": "Public addresses, private networks, floating and elastic IPs and the IP change state.", "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/ServerNetworking" } }, "required": [ "data" ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } } }, "/servers/{id}/snapshots": { "parameters": [ { "$ref": "#/components/parameters/id" } ], "get": { "operationId": "listServerSnapshots", "tags": [ "Snapshots" ], "summary": "List a server's snapshots", "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Snapshot" } } }, "required": [ "data" ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/servers/{id}/storage": { "parameters": [ { "$ref": "#/components/parameters/id" } ], "get": { "operationId": "getServerStorage", "tags": [ "Servers" ], "summary": "Get a server's boot disk and rescue state", "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/ServerStorage" } }, "required": [ "data" ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } } }, "/snapshots": { "get": { "operationId": "listSnapshots", "tags": [ "Snapshots" ], "summary": "List snapshots", "parameters": [ { "$ref": "#/components/parameters/label_selector" }, { "$ref": "#/components/parameters/page" }, { "$ref": "#/components/parameters/per_page" }, { "$ref": "#/components/parameters/project_id" } ], "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SnapshotList" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/UnprocessableEntity" } } } }, "/snapshots/{id}": { "parameters": [ { "$ref": "#/components/parameters/id" } ], "get": { "operationId": "getSnapshot", "tags": [ "Snapshots" ], "summary": "Get a snapshot", "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Snapshot" } }, "required": [ "data" ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } }, "patch": { "operationId": "updateSnapshot", "tags": [ "Snapshots" ], "summary": "Update a snapshot", "description": "Every field is optional: what is sent is changed, the rest stays.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "pattern": "^[a-zA-Z0-9]([a-zA-Z0-9.-]{0,61}[a-zA-Z0-9])?$" }, "labels": { "$ref": "#/components/schemas/Labels" }, "protection_delete": { "type": "boolean" }, "project_id": { "type": "integer", "format": "int64", "description": "Move it to this project of the account.", "minimum": 1 }, "description": { "type": "string" } } } } } }, "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Snapshot" } }, "required": [ "data" ] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/UnprocessableEntity" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } }, "delete": { "operationId": "deleteSnapshot", "tags": [ "Snapshots" ], "summary": "Delete a snapshot", "responses": { "202": { "description": "Accepted; follow the action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ActionAccepted" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } } }, "/volume-prices": { "get": { "operationId": "listVolumePrices", "tags": [ "Plans & pricing" ], "summary": "List block storage prices", "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/VolumePrice" } } }, "required": [ "data" ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } } }, "/volumes": { "get": { "operationId": "listVolumes", "tags": [ "Volumes" ], "summary": "List volumes", "parameters": [ { "$ref": "#/components/parameters/label_selector" }, { "$ref": "#/components/parameters/page" }, { "$ref": "#/components/parameters/per_page" }, { "$ref": "#/components/parameters/project_id" } ], "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VolumeList" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/UnprocessableEntity" } } }, "post": { "operationId": "createVolume", "tags": [ "Volumes" ], "summary": "Create a volume", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "datacenter": { "type": "string", "description": "Datacenter code, e.g. `ovh`.", "examples": [ "ovh" ] }, "name": { "type": "string", "pattern": "^[a-zA-Z0-9]([a-zA-Z0-9.-]{0,61}[a-zA-Z0-9])?$" }, "size_gb": { "type": "integer", "description": "10-10240 GB.", "minimum": 10, "maximum": 10240 }, "server_id": { "type": "integer", "format": "int64", "description": "Attach it to this server (same datacenter) once created." }, "filesystem": { "type": "string", "enum": [ "ext4", "xfs", "" ] }, "labels": { "$ref": "#/components/schemas/Labels" }, "project_id": { "type": "integer", "format": "int64", "description": "Project to create it in; the account's Default project when absent.", "minimum": 1 } }, "required": [ "datacenter", "name", "size_gb" ] } } } }, "responses": { "201": { "description": "Created; the volume is being made.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Volume" }, "action_id": { "type": "integer", "format": "int64", "description": "The action creating it." } }, "required": [ "data", "action_id" ] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/UnprocessableEntity" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } } }, "/volumes/{id}": { "parameters": [ { "$ref": "#/components/parameters/id" } ], "get": { "operationId": "getVolume", "tags": [ "Volumes" ], "summary": "Get a volume", "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Volume" } }, "required": [ "data" ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } }, "patch": { "operationId": "updateVolume", "tags": [ "Volumes" ], "summary": "Update a volume", "description": "Every field is optional: what is sent is changed, the rest stays.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "pattern": "^[a-zA-Z0-9]([a-zA-Z0-9.-]{0,61}[a-zA-Z0-9])?$" }, "labels": { "$ref": "#/components/schemas/Labels" }, "protection_delete": { "type": "boolean" }, "project_id": { "type": "integer", "format": "int64", "description": "Move it to this project of the account.", "minimum": 1 }, "filesystem": { "type": "string", "enum": [ "ext4", "xfs", "" ] } } } } } }, "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Volume" } }, "required": [ "data" ] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/UnprocessableEntity" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } }, "delete": { "operationId": "deleteVolume", "tags": [ "Volumes" ], "summary": "Delete a volume", "description": "It must be detached.", "responses": { "202": { "description": "Accepted; follow the action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ActionAccepted" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } } }, "/volumes/{id}/actions/{op}": { "parameters": [ { "$ref": "#/components/parameters/id" }, { "name": "op", "in": "path", "required": true, "description": "The action.", "schema": { "type": "string", "enum": [ "attach", "detach", "resize" ] } } ], "post": { "operationId": "volumeAction", "tags": [ "Volumes" ], "summary": "Run a volume action", "description": "`attach` to a server (`server_id`), `detach`, or `resize` (`size_gb`, grow only).", "requestBody": { "required": false, "content": { "application/json": { "schema": { "description": "`attach` takes `server_id`, `resize` takes `size_gb`; `detach` takes no body.", "anyOf": [ { "type": "object", "properties": { "server_id": { "type": "integer", "format": "int64", "minimum": 1 } }, "required": [ "server_id" ], "title": "attach" }, { "type": "object", "properties": { "size_gb": { "type": "integer", "minimum": 10, "maximum": 10240 } }, "required": [ "size_gb" ], "title": "resize" } ] } } } }, "responses": { "202": { "description": "Accepted; follow the action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ActionAccepted" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/UnprocessableEntity" }, "423": { "$ref": "#/components/responses/Locked" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } } } }, "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "description": "An API token with scopes `cloud:servers:read` and/or `cloud:servers:write`." } }, "parameters": { "id": { "name": "id", "in": "path", "required": true, "description": "Resource id.", "schema": { "type": "integer", "format": "int64", "minimum": 1 } }, "page": { "name": "page", "in": "query", "description": "Page to return (1-based). Without `page` and `per_page` the whole list is returned.", "schema": { "type": "integer", "minimum": 1, "default": 1 } }, "per_page": { "name": "per_page", "in": "query", "description": "Items per page (1-100).", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25 } }, "label_selector": { "name": "label_selector", "in": "query", "description": "Comma-separated terms that must all hold: `key=value`, `key!=value`, `key` (has the label) or `!key` (has not). A malformed selector is 422 `invalid_label_selector`.", "schema": { "type": "string" } }, "project_id": { "name": "project_id", "in": "query", "description": "Only resources in this project.", "schema": { "type": "integer", "format": "int64", "minimum": 1 } } }, "responses": { "BadRequest": { "description": "The request body is not valid JSON. Codes: `invalid_input`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "Unauthorized": { "description": "No valid API token. Codes: `unauthorized`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "PaymentRequired": { "description": "The account's balance does not cover the order. Codes: `insufficient_balance`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "Forbidden": { "description": "The token lacks the scope (`cloud:servers:read` for reads, `cloud:servers:write` for changes), or `identity_needed`: the account must verify its identity first (`reason` `identity_hold` when the account is held, `single_server` when an unverified account may order one server at a time). Codes: `forbidden`, `identity_needed`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "NotFound": { "description": "No such resource in this account (or no such action `op`). Codes: `datacenter_not_found`, `not_found`, `service_not_found`, `target_not_found`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "Conflict": { "description": "The resource's state does not allow this now. Codes: `already_assigned`, `already_attached`, `already_exists`, `applied_by_selector`, `backup_already_enabled`, `backup_in_progress`, `backup_not_enabled`, `backup_too_soon`, `conflict`, `elastic_ip_busy`, `firewall_protected`, `floating_ip_busy`, `image_not_ready`, `ip_change_fee_not_confirmed`, `ip_change_in_progress`, `ip_in_use`, `last_subnet`, `lb_busy`, `lb_not_ready`, `metrics_unavailable`, `name_taken`, `nat_gateway_busy`, `nat_gateway_required`, `network_attached`, `network_detached`, `network_in_use`, `network_not_ready`, `network_required`, `not_applied`, `not_assigned`, `not_attached`, `not_ready`, `placement_group_busy`, `placement_group_in_use`, `plan_sold_out`, `primary_network`, `protected`, `rebuild_protected`, `rescue_disabled`, `rescue_enabled`, `resource_in_use`, `server_busy`, `server_in_rescue`, `server_must_be_off`, `server_not_billed_yet`, `server_not_ready`, `server_not_running`, `snapshots_in_progress`, `subnet_exists`, `subnet_in_use`, `subnet_not_ready`, `target_exists`, `type_too_small`, `volume_attached`, `volume_busy`, `volume_detached`, `volume_not_ready`, `volume_protected`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "UnprocessableEntity": { "description": "The request is well-formed but refused. Codes: `datacenter_closed`, `datacenter_mismatch`, `datacenter_not_found`, `delete_note_required`, `delete_note_too_long`, `disk_cannot_shrink`, `dns_ptr_rejected`, `feature_unavailable`, `firewall_not_found`, `image_needs_more_ram`, `image_not_found`, `image_required`, `image_too_large`, `invalid_algorithm`, `invalid_count`, `invalid_cursor`, `invalid_delete_reason`, `invalid_description`, `invalid_dns_ptr`, `invalid_filesystem`, `invalid_filter`, `invalid_input`, `invalid_ip`, `invalid_ip_range`, `invalid_kind`, `invalid_label`, `invalid_label_selector`, `invalid_labels`, `invalid_metrics`, `invalid_name`, `invalid_operation`, `invalid_page`, `invalid_project`, `invalid_request`, `invalid_route`, `invalid_rule`, `invalid_size`, `invalid_ssh_key`, `invalid_state`, `invalid_subnet`, `invalid_target`, `invalid_target_ip`, `invalid_type`, `invalid_user_data`, `invalid_window`, `ip_change_limit_reached`, `ip_change_unavailable`, `ip_outside_network`, `ip_reserved`, `ipv6_unavailable`, `lb_type_not_found`, `network_listed_twice`, `network_not_found`, `network_required`, `no_public_ipv4`, `not_private_range`, `order_unavailable`, `placement_group_datacenter`, `placement_group_full`, `placement_group_not_found`, `plan_not_found`, `plan_unavailable`, `private_ip_required`, `project_not_found`, `quota_exceeded`, `same_algorithm`, `same_plan`, `same_type`, `server_has_public_ip`, `server_not_found`, `server_not_in_network`, `server_private_only`, `server_required`, `sku_unavailable`, `ssh_key_not_found`, `subnet_not_found`, `subnet_outside_range`, `subnet_overlaps`, `too_many_labels`, `too_many_networks`, `too_many_routes`, `too_many_rules`, `too_many_selectors`, `too_many_services`, `too_many_ssh_keys`, `too_many_subnets`, `too_many_targets`, `too_many_volumes`, `user_data_too_large`, `volume_cannot_shrink`, `volume_not_found`, `volumes_need_one_server`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "Locked": { "description": "The server or load balancer is locked. Codes: `lb_locked`, `locked`, `server_locked`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "NotImplemented": { "description": "Not offered for this resource. Codes: `not_implemented`, `rdns_unavailable`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "ServiceUnavailable": { "description": "The datacenter or a dependency is briefly out of reach; try again after `Retry-After`. Codes: `datacenter_unavailable`, `projects_unavailable`, `rdns_temporarily_unavailable`, `ssh_keys_unavailable`, `unavailable`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "description": "Seconds to wait before trying again.", "schema": { "type": "integer", "examples": [ 30 ] } } } } }, "schemas": { "Action": { "type": "object", "description": "An asynchronous operation. Every change that takes time returns an `action_id`; poll `GET /actions/{id}` until `status` is `success` or `error`.", "properties": { "id": { "type": "integer", "format": "int64", "description": "Unique identifier.", "minimum": 1 }, "command": { "type": "string", "description": "What the action does, e.g. `create`, `poweron`, `rebuild`, `attach`, `create_snapshot`, `apply_firewall`." }, "status": { "type": "string", "enum": [ "running", "success", "error" ] }, "progress": { "type": "integer", "description": "Progress in percent (0-100).", "minimum": 0, "maximum": 100 }, "resource": { "$ref": "#/components/schemas/ActionResource" }, "error": { "type": [ "object", "null" ], "description": "Why the action failed; null unless status is `error`.", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] }, "started_at": { "type": "string", "format": "date-time" }, "finished_at": { "type": [ "string", "null" ], "description": "Null while running.", "format": "date-time" }, "resources": { "type": "array", "items": { "$ref": "#/components/schemas/ActionResource" }, "description": "The resources the action touches (the same resource, as a list)." }, "started": { "type": "string", "description": "Same as `started_at`.", "format": "date-time" }, "finished": { "type": [ "string", "null" ], "description": "Same as `finished_at`.", "format": "date-time" } }, "required": [ "id", "command", "status", "progress", "resource", "error", "started_at", "finished_at", "resources", "started", "finished" ] }, "ActionAccepted": { "type": "object", "description": "An asynchronous request was accepted.", "properties": { "action_id": { "type": "integer", "format": "int64", "description": "The action carrying out the request; follow it at `GET /actions/{id}`." } }, "required": [ "action_id" ] }, "ActionList": { "type": "object", "description": "`meta` is present when `page` or `per_page` was given.", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Action" } }, "meta": { "$ref": "#/components/schemas/ListMeta" } }, "required": [ "data" ] }, "ActionResource": { "type": "object", "properties": { "type": { "type": "string", "description": "Resource kind, e.g. `server`, `volume`, `network`, `floating_ip`, `load_balancer`." }, "id": { "type": "integer", "format": "int64", "description": "Resource id." } }, "required": [ "type", "id" ] }, "Availability": { "type": "object", "properties": { "available": { "type": "boolean", "description": "Whether a server of the plan can be placed now." }, "reason": { "type": "string", "description": "Why it is sold out.", "enum": [ "ipv4", "ram", "cpu", "disk", "capacity" ] }, "known": { "type": "boolean", "description": "False while no capacity snapshot has arrived (everything sells)." }, "stale": { "type": "boolean", "description": "The last capacity snapshot is old; the verdict is still its." } }, "required": [ "available", "known" ] }, "Backup": { "type": "object", "properties": { "id": { "type": "integer", "format": "int64", "description": "Unique identifier.", "minimum": 1 }, "kind": { "type": "string", "enum": [ "backup" ] }, "image": { "type": "string", "description": "What `POST /servers` and `rebuild` take: `backup:`." }, "name": { "type": "string" }, "description": { "type": "string" }, "datacenter": { "type": "string", "description": "Datacenter code, e.g. `ovh`.", "examples": [ "ovh" ] }, "status": { "type": "string", "description": "e.g. `creating`, `available`, `error`." }, "size_gb": { "type": [ "number", "null" ], "description": "Stored size; null until available." }, "disk_gb": { "type": "integer", "description": "Minimum disk to create a server from it." }, "server_id": { "type": [ "integer", "null" ], "format": "int64", "description": "Server it was taken from." }, "server_name": { "type": "string" }, "source_image": { "type": "string" }, "protection_delete": { "type": "boolean", "description": "Delete protection: while true the resource cannot be deleted." }, "labels": { "$ref": "#/components/schemas/Labels" }, "created_at": { "type": "string", "description": "When it was created (RFC 3339).", "format": "date-time" }, "project_id": { "type": "integer", "format": "int64", "description": "Project the resource is in." }, "origin": { "type": "string", "description": "How the backup came to be.", "enum": [ "scheduled", "manual" ] } }, "required": [ "id", "kind", "image", "name", "description", "datacenter", "status", "size_gb", "disk_gb", "server_id", "server_name", "source_image", "protection_delete", "labels", "created_at", "project_id", "origin" ] }, "BackupList": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Backup" } }, "meta": { "$ref": "#/components/schemas/ListMeta" }, "plans": { "type": "array", "items": { "$ref": "#/components/schemas/BackupPlan" }, "description": "Backup plans of the account's servers." } }, "required": [ "data", "meta", "plans" ] }, "BackupPlan": { "type": "object", "properties": { "server_id": { "type": "integer", "format": "int64" }, "window_hour": { "type": "integer", "description": "Hour of the day (UTC, 0-23) the daily backup runs.", "minimum": 0, "maximum": 23 }, "enabled_at": { "type": "string", "format": "date-time" }, "next_backup_at": { "type": "string", "format": "date-time" }, "retention": { "type": "integer", "description": "Backups kept; the oldest goes first." } }, "required": [ "server_id", "window_hour", "enabled_at", "next_backup_at", "retention" ] }, "CatalogImage": { "type": "object", "description": "An image of a datacenter's catalog, as the create form shows it.", "properties": { "id": { "type": "string" }, "slug": { "type": "string", "description": "What `image` takes on create and rebuild.", "examples": [ "ubuntu-24.04" ] }, "name": { "type": "string" }, "group": { "type": "string", "enum": [ "os", "app", "snapshot", "backup" ] }, "family": { "type": "string" }, "family_name": { "type": "string" }, "version": { "type": "string" }, "logo": { "type": "string" }, "min_vcpu": { "type": "integer" }, "min_ram_mb": { "type": "integer" }, "min_disk_gb": { "type": "integer" }, "description_fa": { "type": "string", "description": "Description in Persian." } }, "required": [ "id", "slug", "name", "group", "family", "family_name", "version", "logo", "min_vcpu", "min_ram_mb", "min_disk_gb", "description_fa" ] }, "ConsoleLink": { "type": "object", "properties": { "url": { "type": "string", "description": "WebSocket URL of the VNC console; single-use.", "format": "uri" }, "expires_in": { "type": "integer", "description": "Seconds the link is valid.", "examples": [ 60 ] } }, "required": [ "url", "expires_in" ] }, "CostLine": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "server", "primary_ipv4", "floating_ip", "elastic_ip", "volume", "backup" ] }, "id": { "type": "integer", "format": "int64", "description": "Its id in its own list (the server's for `server` and `backup`)." }, "name": { "type": "string" }, "sku": { "type": "string" }, "quantity": { "type": "number", "description": "1, a volume's GB, or the backup's percent of the plan." }, "unit": { "type": "string" }, "hourly_price": { "type": "number" }, "monthly_price": { "type": "number" }, "currency": { "type": "string" } }, "required": [ "type", "id", "name", "sku", "quantity", "unit", "hourly_price", "monthly_price", "currency" ] }, "CostTotal": { "type": "object", "properties": { "currency": { "type": "string" }, "hourly_price": { "type": "number" }, "monthly_price": { "type": "number" } }, "required": [ "currency", "hourly_price", "monthly_price" ] }, "CreatedServer": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Server" }, "action_id": { "type": "integer", "format": "int64" } }, "required": [ "data", "action_id" ] }, "Datacenter": { "type": "object", "properties": { "code": { "type": "string", "description": "Datacenter code; what every `datacenter` field takes.", "examples": [ "ovh" ] }, "name": { "type": "string" }, "name_fa": { "type": "string", "description": "Name in Persian." }, "country": { "type": "string" }, "city": { "type": "string" }, "flag": { "type": "string", "description": "Flag image or emoji." }, "status": { "type": "string", "description": "`closed`: listed, but nothing new can be ordered there.", "enum": [ "active", "closed" ] }, "orderable": { "type": "boolean", "description": "Whether new resources can be ordered here." }, "features": { "type": "array", "items": { "type": "string", "enum": [ "ipv4", "ipv6", "private_networks", "floating_ips", "elastic_ips", "nat_gateways", "load_balancers", "firewalls", "volumes", "snapshots", "backups", "rescue", "graphs", "rdns", "console" ] }, "description": "What the datacenter offers. An operation on a feature it lacks is refused with 422 `feature_unavailable`." }, "sort_order": { "type": "integer" }, "ipv6": { "type": "boolean", "description": "Whether `features` contains `ipv6`." } }, "required": [ "code", "name", "name_fa", "country", "city", "flag", "status", "orderable", "features", "sort_order", "ipv6" ] }, "DatacenterLimits": { "type": "object", "properties": { "datacenter": { "type": "string", "description": "Datacenter code, e.g. `ovh`.", "examples": [ "ovh" ] }, "limits": { "type": "array", "items": { "$ref": "#/components/schemas/QuotaLimit" } } }, "required": [ "datacenter", "limits" ] }, "ElasticIP": { "type": "object", "properties": { "id": { "type": "integer", "format": "int64", "description": "Unique identifier.", "minimum": 1 }, "name": { "type": "string" }, "datacenter": { "type": "string", "description": "Datacenter code, e.g. `ovh`.", "examples": [ "ovh" ] }, "ip": { "type": "string" }, "server_id": { "type": [ "integer", "null" ], "format": "int64", "description": "Server it is assigned to." }, "status": { "type": "string" }, "protection_delete": { "type": "boolean", "description": "Delete protection: while true the resource cannot be deleted." }, "labels": { "$ref": "#/components/schemas/Labels" }, "created_at": { "type": "string", "description": "When it was created (RFC 3339).", "format": "date-time" }, "project_id": { "type": "integer", "format": "int64", "description": "Project the resource is in." } }, "required": [ "id", "name", "datacenter", "ip", "server_id", "status", "protection_delete", "labels", "created_at", "project_id" ] }, "ElasticIPList": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/ElasticIP" } }, "meta": { "$ref": "#/components/schemas/ListMeta" } }, "required": [ "data", "meta" ] }, "Error": { "type": "object", "description": "The error envelope every refusal uses.", "properties": { "error": { "type": "string", "description": "Human-readable message, safe to show to the customer." }, "code": { "type": "string", "description": "Stable machine code to branch on. Every error carries one; the codes each status can carry are listed in `x-error-codes`.", "examples": [ "not_found", "invalid_label_selector" ] }, "reason": { "type": "string", "description": "Narrows `code` when there is more than one way to hit it, e.g. `identity_hold` or `single_server` for `identity_needed`, the resource for `quota_exceeded`, or `ipv4`/`ram`/`cpu`/`disk`/`capacity` for `plan_sold_out`. Present only when set." } }, "required": [ "error", "code" ], "x-error-codes": { "400": [ "invalid_input" ], "401": [ "unauthorized" ], "402": [ "insufficient_balance" ], "403": [ "forbidden", "identity_needed" ], "404": [ "datacenter_not_found", "not_found", "service_not_found", "target_not_found" ], "409": [ "already_assigned", "already_attached", "already_exists", "applied_by_selector", "backup_already_enabled", "backup_in_progress", "backup_not_enabled", "backup_too_soon", "conflict", "elastic_ip_busy", "firewall_protected", "floating_ip_busy", "image_not_ready", "ip_change_fee_not_confirmed", "ip_change_in_progress", "ip_in_use", "last_subnet", "lb_busy", "lb_not_ready", "metrics_unavailable", "name_taken", "nat_gateway_busy", "nat_gateway_required", "network_attached", "network_detached", "network_in_use", "network_not_ready", "network_required", "not_applied", "not_assigned", "not_attached", "not_ready", "placement_group_busy", "placement_group_in_use", "plan_sold_out", "primary_network", "protected", "rebuild_protected", "rescue_disabled", "rescue_enabled", "resource_in_use", "server_busy", "server_in_rescue", "server_must_be_off", "server_not_billed_yet", "server_not_ready", "server_not_running", "snapshots_in_progress", "subnet_exists", "subnet_in_use", "subnet_not_ready", "target_exists", "type_too_small", "volume_attached", "volume_busy", "volume_detached", "volume_not_ready", "volume_protected" ], "422": [ "datacenter_closed", "datacenter_mismatch", "datacenter_not_found", "delete_note_required", "delete_note_too_long", "disk_cannot_shrink", "dns_ptr_rejected", "feature_unavailable", "firewall_not_found", "image_needs_more_ram", "image_not_found", "image_required", "image_too_large", "invalid_algorithm", "invalid_count", "invalid_cursor", "invalid_delete_reason", "invalid_description", "invalid_dns_ptr", "invalid_filesystem", "invalid_filter", "invalid_input", "invalid_ip", "invalid_ip_range", "invalid_kind", "invalid_label", "invalid_label_selector", "invalid_labels", "invalid_metrics", "invalid_name", "invalid_operation", "invalid_page", "invalid_project", "invalid_request", "invalid_route", "invalid_rule", "invalid_size", "invalid_ssh_key", "invalid_state", "invalid_subnet", "invalid_target", "invalid_target_ip", "invalid_type", "invalid_user_data", "invalid_window", "ip_change_limit_reached", "ip_change_unavailable", "ip_outside_network", "ip_reserved", "ipv6_unavailable", "lb_type_not_found", "network_listed_twice", "network_not_found", "network_required", "no_public_ipv4", "not_private_range", "order_unavailable", "placement_group_datacenter", "placement_group_full", "placement_group_not_found", "plan_not_found", "plan_unavailable", "private_ip_required", "project_not_found", "quota_exceeded", "same_algorithm", "same_plan", "same_type", "server_has_public_ip", "server_not_found", "server_not_in_network", "server_private_only", "server_required", "sku_unavailable", "ssh_key_not_found", "subnet_not_found", "subnet_outside_range", "subnet_overlaps", "too_many_labels", "too_many_networks", "too_many_routes", "too_many_rules", "too_many_selectors", "too_many_services", "too_many_ssh_keys", "too_many_subnets", "too_many_targets", "too_many_volumes", "user_data_too_large", "volume_cannot_shrink", "volume_not_found", "volumes_need_one_server" ], "423": [ "lb_locked", "locked", "server_locked" ], "501": [ "not_implemented", "rdns_unavailable" ], "503": [ "datacenter_unavailable", "projects_unavailable", "rdns_temporarily_unavailable", "ssh_keys_unavailable", "unavailable" ] } }, "Event": { "type": "object", "description": "Something OpenStack reported about a resource.", "properties": { "id": { "type": "integer", "format": "int64", "description": "Unique identifier.", "minimum": 1 }, "type": { "type": "string", "description": "OpenStack's event type, e.g. `instance.create.end`, `instance.power_off.end`, `volume.attach.end`." }, "at": { "type": "string", "format": "date-time" }, "source": { "type": "string", "enum": [ "openstack" ] }, "resource": { "type": "object", "properties": { "type": { "type": "string" }, "id": { "type": "integer", "format": "int64" } }, "required": [ "type", "id" ] }, "message": { "type": [ "string", "null" ], "description": "A fixed, customer-safe sentence when the event failed or carried a fault; the raw fault is kept for support only." } }, "required": [ "id", "type", "at", "source", "resource", "message" ] }, "Firewall": { "type": "object", "properties": { "id": { "type": "integer", "format": "int64", "description": "Unique identifier.", "minimum": 1 }, "name": { "type": "string" }, "rules": { "type": "array", "items": { "$ref": "#/components/schemas/FirewallRule" } }, "server_ids": { "type": "array", "items": { "type": "integer", "format": "int64" }, "description": "Every server it is applied to." }, "created_at": { "type": "string", "description": "When it was created (RFC 3339).", "format": "date-time" }, "labels": { "$ref": "#/components/schemas/Labels" }, "protection_delete": { "type": "boolean", "description": "Delete protection: while true the resource cannot be deleted." }, "project_id": { "type": "integer", "format": "int64", "description": "Project the resource is in." }, "applied_to": { "type": "array", "items": { "$ref": "#/components/schemas/FirewallTarget" }, "description": "Servers applied directly and label selectors." }, "selector_server_ids": { "type": "array", "items": { "type": "integer", "format": "int64" }, "description": "Servers it is on only through a label selector." } }, "required": [ "id", "name", "rules", "server_ids", "created_at", "labels", "protection_delete", "project_id", "applied_to", "selector_server_ids" ] }, "FirewallList": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Firewall" } }, "meta": { "$ref": "#/components/schemas/ListMeta" } }, "required": [ "data", "meta" ] }, "FirewallRule": { "type": "object", "properties": { "direction": { "type": "string", "enum": [ "in", "out" ] }, "protocol": { "type": "string", "enum": [ "tcp", "udp", "icmp", "esp", "gre" ] }, "port": { "type": [ "string", "null" ], "description": "Port or range (`80`, `1000-2000`); tcp and udp only." }, "source_ips": { "type": "array", "items": { "type": "string" }, "description": "CIDRs (direction `in`)." }, "destination_ips": { "type": "array", "items": { "type": "string" }, "description": "CIDRs (direction `out`)." }, "description": { "type": [ "string", "null" ] } }, "required": [ "direction", "protocol" ] }, "FirewallTarget": { "type": "object", "description": "A server (`type: server` with `server.id`) or a label selector (`type: label_selector` with `label_selector.selector`).", "properties": { "type": { "type": "string", "enum": [ "server", "label_selector" ] }, "server": { "type": "object", "properties": { "id": { "type": "integer", "format": "int64" } }, "required": [ "id" ] }, "label_selector": { "type": "object", "properties": { "selector": { "type": "string" } }, "required": [ "selector" ] } }, "required": [ "type" ] }, "FloatingIP": { "type": "object", "properties": { "id": { "type": "integer", "format": "int64", "description": "Unique identifier.", "minimum": 1 }, "name": { "type": "string" }, "description": { "type": "string" }, "datacenter": { "type": "string", "description": "Datacenter code, e.g. `ovh`.", "examples": [ "ovh" ] }, "type": { "type": "string", "enum": [ "ipv4", "ipv6" ] }, "ip": { "type": "string" }, "server_id": { "type": [ "integer", "null" ], "format": "int64", "description": "Server it is assigned to." }, "dns_ptr": { "type": "string", "description": "Reverse DNS." }, "status": { "type": "string" }, "protection_delete": { "type": "boolean", "description": "Delete protection: while true the resource cannot be deleted." }, "labels": { "$ref": "#/components/schemas/Labels" }, "created_at": { "type": "string", "description": "When it was created (RFC 3339).", "format": "date-time" }, "project_id": { "type": "integer", "format": "int64", "description": "Project the resource is in." } }, "required": [ "id", "name", "description", "datacenter", "type", "ip", "server_id", "dns_ptr", "status", "protection_delete", "labels", "created_at", "project_id" ] }, "FloatingIPList": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/FloatingIP" } }, "meta": { "$ref": "#/components/schemas/ListMeta" } }, "required": [ "data", "meta" ] }, "IPChange": { "type": "object", "description": "Whether and for what the server's public IPv4 can be changed (`change_ipv4`).", "properties": { "allowed": { "type": "boolean", "description": "Whether the server's public IPv4 can be changed right now." }, "free": { "type": "boolean", "description": "Whether the next change is free." }, "free_left": { "type": "integer" }, "fee": { "type": "number", "description": "Fee of the next change." }, "fee_per_change": { "type": "number" }, "currency": { "type": "string", "examples": [ "IRR" ] }, "pending": { "type": "boolean", "description": "A change is in progress." }, "used": { "type": "integer" }, "max_count": { "type": [ "integer", "null" ] }, "remaining": { "type": [ "integer", "null" ] }, "limit_reached": { "type": "boolean" }, "unavailable_reason": { "type": [ "string", "null" ], "description": "Why it cannot be asked for now; null when it can.", "enum": [ "not_offered", "no_public_ipv4", "limit_reached", "in_progress", "rescue_enabled", "server_locked", "server_busy" ] } }, "required": [ "allowed", "free", "free_left", "fee", "fee_per_change", "currency", "pending", "used", "max_count", "remaining", "limit_reached", "unavailable_reason" ] }, "IPChangeRecord": { "type": "object", "properties": { "id": { "type": "integer", "format": "int64", "description": "Unique identifier.", "minimum": 1 }, "action_id": { "type": "integer", "format": "int64" }, "status": { "type": "string", "enum": [ "running", "completed", "failed" ] }, "old_ip": { "type": "string" }, "new_ip": { "type": [ "string", "null" ] }, "free": { "type": "boolean" }, "fee": { "type": "number" }, "currency": { "type": "string" }, "rebooted": { "type": "boolean" }, "note": { "type": [ "string", "null" ] }, "created_at": { "type": "string", "format": "date-time" }, "completed_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "id", "action_id", "status", "old_ip", "new_ip", "free", "fee", "currency", "rebooted", "note", "created_at", "completed_at" ] }, "Image": { "type": "object", "description": "Any image a server can be created from.", "properties": { "id": { "type": "string", "description": "The image slug for platform images, the numeric id for snapshots and backups." }, "image": { "type": "string", "description": "What `POST /servers` takes as `image`: a slug, or `snapshot:` / `backup:`." }, "type": { "type": "string", "enum": [ "system", "app", "snapshot", "backup" ] }, "name": { "type": "string" }, "description": { "type": "string" }, "datacenters": { "type": "array", "items": { "type": "string" }, "description": "Datacenters that have it." }, "min_disk_gb": { "type": "integer" }, "deprecated": { "type": "boolean" }, "status": { "type": "string", "description": "`available` for platform images; the copy's status for snapshots and backups." }, "labels": { "$ref": "#/components/schemas/Labels" }, "protection": { "type": "object", "properties": { "delete": { "type": "boolean" } }, "required": [ "delete" ] }, "project_id": { "type": "integer", "format": "int64", "description": "Project of a snapshot or backup; 0 for platform images." }, "created_at": { "type": [ "string", "null" ], "description": "Null for platform images.", "format": "date-time" } }, "required": [ "id", "image", "type", "name", "description", "datacenters", "min_disk_gb", "deprecated", "status", "labels", "protection", "project_id", "created_at" ] }, "ImageList": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Image" } }, "meta": { "$ref": "#/components/schemas/ListMeta" } }, "required": [ "data", "meta" ] }, "LBHealthCheck": { "type": "object", "properties": { "protocol": { "type": "string", "enum": [ "tcp", "http" ] }, "port": { "type": "integer" }, "interval": { "type": "integer", "description": "Seconds." }, "timeout": { "type": "integer", "description": "Seconds." }, "retries": { "type": "integer" }, "http": { "type": "object", "properties": { "domain": { "type": "string", "description": "Host header." }, "path": { "type": "string" }, "status_codes": { "type": "array", "items": { "type": "string" }, "description": "e.g. `200`, `2??`." }, "tls": { "type": "boolean", "description": "Check over HTTPS (the certificate is not verified)." } } } } }, "LBService": { "type": "object", "description": "A listener.", "properties": { "protocol": { "type": "string", "description": "`https` is TLS passthrough.", "enum": [ "tcp", "http", "https" ] }, "listen_port": { "type": "integer" }, "destination_port": { "type": "integer" }, "proxyprotocol": { "type": "boolean" }, "health_check": { "$ref": "#/components/schemas/LBHealthCheck" }, "http": { "type": "object", "properties": { "sticky_sessions": { "type": "boolean" }, "cookie_name": { "type": "string", "description": "http: stick on this cookie of your application; empty inserts the load balancer's own." }, "redirect_http": { "type": "boolean", "description": "https: answer plain http on port 80 with a 301 to `redirect_host`." }, "redirect_host": { "type": "string" } } } }, "required": [ "protocol", "listen_port", "destination_port" ] }, "LBTarget": { "type": "object", "properties": { "id": { "type": "integer", "format": "int64", "description": "Unique identifier.", "minimum": 1 }, "type": { "type": "string", "enum": [ "server", "ip", "label_selector" ] }, "server_id": { "type": [ "integer", "null" ], "format": "int64" }, "server_name": { "type": "string" }, "server_deleted": { "type": "boolean" }, "ip": { "type": "string" }, "label_selector": { "type": "string" }, "matched_servers": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "format": "int64" }, "name": { "type": "string" }, "address": { "type": "string" } }, "required": [ "id", "name", "address" ] } }, "use_private_ip": { "type": "boolean" }, "address": { "type": "string" }, "health_status": { "type": "string", "enum": [ "healthy", "unhealthy", "unknown" ] }, "health": { "type": "array", "items": { "type": "object", "properties": { "listen_port": { "type": "integer" }, "status": { "type": "string" } }, "required": [ "listen_port", "status" ] } }, "created_at": { "type": "string", "description": "When it was created (RFC 3339).", "format": "date-time" } }, "required": [ "id", "type", "server_id", "server_deleted", "use_private_ip", "address", "health_status", "health", "created_at" ] }, "LBTargetInput": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "server", "ip", "label_selector" ] }, "server_id": { "type": "integer", "format": "int64" }, "ip": { "type": "string" }, "label_selector": { "type": "string" }, "use_private_ip": { "type": "boolean", "description": "Reach the target on its private network address." } }, "required": [ "type" ] }, "Labels": { "type": "object", "description": "Key/value labels. Keys: 1-63 characters of letters, digits, `.`, `_`, `/`, `-`, starting and ending with a letter or digit; values: empty or up to 63 characters of letters, digits, `.`, `_`, `-`. At most 32 labels.", "properties": {}, "additionalProperties": { "type": "string", "maxLength": 63 }, "maxProperties": 32 }, "ListMeta": { "type": "object", "properties": { "pagination": { "$ref": "#/components/schemas/Pagination" } }, "required": [ "pagination" ] }, "LoadBalancer": { "type": "object", "properties": { "id": { "type": "integer", "format": "int64", "description": "Unique identifier.", "minimum": 1 }, "name": { "type": "string" }, "datacenter": { "type": "string", "description": "Datacenter code, e.g. `ovh`.", "examples": [ "ovh" ] }, "type": { "type": "string", "description": "Load balancer type code (see `GET /load-balancer-types`)." }, "algorithm": { "type": "string", "enum": [ "round_robin", "least_connections" ] }, "status": { "type": "string", "description": "e.g. `creating`, `available`, `updating`, `error`." }, "provisioning_status": { "type": "string" }, "operating_status": { "type": "string" }, "public_interface": { "type": "boolean" }, "ipv4": { "type": [ "string", "null" ] }, "ipv6": { "type": [ "string", "null" ] }, "private_ip": { "type": [ "string", "null" ] }, "network": { "type": [ "object", "null" ], "properties": { "id": { "type": "integer", "format": "int64" }, "name": { "type": "string" }, "ip_range": { "type": "string" } }, "required": [ "id", "name", "ip_range" ] }, "services": { "type": "array", "items": { "$ref": "#/components/schemas/LBService" } }, "targets": { "type": "array", "items": { "$ref": "#/components/schemas/LBTarget" } }, "health_summary": { "type": "object", "properties": { "healthy": { "type": "integer" }, "unhealthy": { "type": "integer" }, "unknown": { "type": "integer" } }, "required": [ "healthy", "unhealthy", "unknown" ] }, "health_checked_at": { "type": [ "string", "null" ], "format": "date-time" }, "protection_delete": { "type": "boolean", "description": "Delete protection: while true the resource cannot be deleted." }, "labels": { "$ref": "#/components/schemas/Labels" }, "locked": { "type": "boolean" }, "created_at": { "type": "string", "description": "When it was created (RFC 3339).", "format": "date-time" }, "project_id": { "type": "integer", "format": "int64", "description": "Project the resource is in." } }, "required": [ "id", "name", "datacenter", "type", "algorithm", "status", "public_interface", "ipv4", "ipv6", "private_ip", "network", "services", "targets", "health_summary", "health_checked_at", "protection_delete", "labels", "locked", "created_at", "project_id" ] }, "LoadBalancerList": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/LoadBalancer" } }, "meta": { "$ref": "#/components/schemas/ListMeta" } }, "required": [ "data", "meta" ] }, "LoadBalancerOperationRequest": { "description": "The body depends on `op`; `detach_from_network` takes none.", "anyOf": [ { "type": "object", "properties": { "services": { "type": "array", "items": { "$ref": "#/components/schemas/LBService" } }, "algorithm": { "type": "string", "enum": [ "round_robin", "least_connections" ] } }, "required": [ "services" ], "title": "update_services" }, { "title": "add_service", "allOf": [ { "$ref": "#/components/schemas/LBService" } ] }, { "type": "object", "properties": { "listen_port": { "type": "integer" }, "service": { "$ref": "#/components/schemas/LBService" } }, "required": [ "listen_port", "service" ], "title": "update_service" }, { "type": "object", "properties": { "listen_port": { "type": "integer" } }, "required": [ "listen_port" ], "title": "delete_service" }, { "title": "add_target", "allOf": [ { "$ref": "#/components/schemas/LBTargetInput" } ] }, { "type": "object", "properties": { "target_id": { "type": "integer", "format": "int64" } }, "required": [ "target_id" ], "title": "remove_target" }, { "type": "object", "properties": { "type": { "type": "string" } }, "required": [ "type" ], "title": "change_type" }, { "type": "object", "properties": { "algorithm": { "type": "string", "enum": [ "round_robin", "least_connections" ] } }, "required": [ "algorithm" ], "title": "change_algorithm" }, { "type": "object", "properties": { "network_id": { "description": "An id, as a JSON number or a numeric string.", "oneOf": [ { "type": "integer", "format": "int64", "minimum": 1 }, { "type": "string", "pattern": "^[0-9]+$" } ] } }, "required": [ "network_id" ], "title": "attach_to_network" } ] }, "LoadBalancerType": { "type": "object", "properties": { "code": { "type": "string", "examples": [ "lb11" ] }, "name": { "type": "string" }, "max_services": { "type": "integer" }, "max_targets": { "type": "integer" }, "max_connections": { "type": "integer" }, "sort": { "type": "integer" } }, "required": [ "code", "name", "max_services", "max_targets", "max_connections", "sort" ] }, "NATGateway": { "type": "object", "properties": { "id": { "type": "integer", "format": "int64", "description": "Unique identifier.", "minimum": 1 }, "name": { "type": "string" }, "datacenter": { "type": "string", "description": "Datacenter code, e.g. `ovh`.", "examples": [ "ovh" ] }, "network_id": { "type": "integer", "format": "int64" }, "network_name": { "type": "string" }, "status": { "type": "string" }, "public_ip": { "type": "string" }, "protection_delete": { "type": "boolean", "description": "Delete protection: while true the resource cannot be deleted." }, "labels": { "$ref": "#/components/schemas/Labels" }, "subnets": { "type": "array", "items": { "$ref": "#/components/schemas/Subnet" } }, "created_at": { "type": "string", "description": "When it was created (RFC 3339).", "format": "date-time" }, "project_id": { "type": "integer", "format": "int64", "description": "Project the resource is in." } }, "required": [ "id", "name", "datacenter", "network_id", "network_name", "status", "public_ip", "protection_delete", "labels", "subnets", "created_at", "project_id" ] }, "NATGatewayList": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/NATGateway" } }, "meta": { "$ref": "#/components/schemas/ListMeta" } }, "required": [ "data", "meta" ] }, "Network": { "type": "object", "properties": { "id": { "type": "integer", "format": "int64", "description": "Unique identifier.", "minimum": 1 }, "name": { "type": "string" }, "datacenter": { "type": "string", "description": "Datacenter code, e.g. `ovh`.", "examples": [ "ovh" ] }, "ip_range": { "type": "string", "description": "CIDR of a private range." }, "status": { "type": "string" }, "protection_delete": { "type": "boolean", "description": "Delete protection: while true the resource cannot be deleted." }, "labels": { "$ref": "#/components/schemas/Labels" }, "subnets": { "type": "array", "items": { "$ref": "#/components/schemas/Subnet" } }, "routes": { "type": "array", "items": { "$ref": "#/components/schemas/Route" } }, "servers": { "type": "array", "items": { "$ref": "#/components/schemas/NetworkServer" } }, "router": { "anyOf": [ { "$ref": "#/components/schemas/RouterRef" }, { "type": "null" } ] }, "created_at": { "type": "string", "description": "When it was created (RFC 3339).", "format": "date-time" }, "project_id": { "type": "integer", "format": "int64", "description": "Project the resource is in." } }, "required": [ "id", "name", "datacenter", "ip_range", "status", "protection_delete", "labels", "subnets", "routes", "servers", "router", "created_at", "project_id" ] }, "NetworkList": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Network" } }, "meta": { "$ref": "#/components/schemas/ListMeta" } }, "required": [ "data", "meta" ] }, "NetworkServer": { "type": "object", "properties": { "server_id": { "type": "integer", "format": "int64" }, "name": { "type": "string" }, "status": { "type": "string" }, "subnet_id": { "type": "integer", "format": "int64" }, "ip": { "type": "string" }, "primary": { "type": "boolean" } }, "required": [ "server_id", "name", "status", "subnet_id", "ip", "primary" ] }, "Pagination": { "type": "object", "properties": { "page": { "type": "integer", "description": "Current page (1-based)." }, "per_page": { "type": "integer", "description": "Items per page. Without `page`/`per_page` the whole list is one page." }, "previous_page": { "type": [ "integer", "null" ], "description": "Previous page, or null on the first." }, "next_page": { "type": [ "integer", "null" ], "description": "Next page, or null on the last." }, "last_page": { "type": "integer", "description": "Last page (at least 1)." }, "total_entries": { "type": "integer", "description": "Matching items across all pages." } }, "required": [ "page", "per_page", "previous_page", "next_page", "last_page", "total_entries" ] }, "Plan": { "type": "object", "description": "A server plan, with whether it can be ordered right now.", "properties": { "id": { "type": "integer", "format": "int64", "description": "Unique identifier.", "minimum": 1 }, "datacenter": { "type": "string", "description": "Datacenter code, e.g. `ovh`.", "examples": [ "ovh" ] }, "name": { "type": "string" }, "flavor": { "type": "string" }, "vcpu": { "type": "integer" }, "ram_mb": { "type": "integer" }, "disk_gb": { "type": "integer" }, "traffic_gb": { "type": [ "integer", "null" ], "description": "Included traffic in GB; null means unmetered." }, "hourly_price": { "type": "number" }, "monthly_price": { "type": "number" }, "currency": { "type": "string", "examples": [ "IRR" ] }, "is_active": { "type": "boolean" }, "minimum_usage_hours": { "type": "integer", "description": "Hours charged up front when a server of the plan is created." }, "group_key": { "type": "string" }, "group_name": { "type": "string" }, "group_name_fa": { "type": "string" }, "group_sort": { "type": "integer" }, "sort_order": { "type": "integer" }, "is_recommended": { "type": "boolean" }, "description_fa": { "type": "string" }, "currency_symbol": { "type": "string" }, "availability": { "$ref": "#/components/schemas/Availability" } }, "required": [ "id", "datacenter", "name", "flavor", "vcpu", "ram_mb", "disk_gb", "traffic_gb", "hourly_price", "monthly_price", "currency", "is_active", "minimum_usage_hours", "group_key", "group_name", "group_name_fa", "group_sort", "sort_order", "is_recommended", "description_fa", "currency_symbol", "availability" ] }, "Pricing": { "type": "object", "description": "An active price.", "properties": { "datacenter": { "type": "string", "description": "Datacenter code, e.g. `ovh`.", "examples": [ "ovh" ] }, "sku": { "type": "string", "description": "What is priced, e.g. `snapshot_gb`, `backup`, `volume_gb`.", "examples": [ "volume_gb" ] }, "unit": { "type": "string", "description": "`hour`: per unit per hour; `gb_hour`: per GB per hour; `percent`: a share of the server's price (backups).", "enum": [ "hour", "gb_hour", "percent" ] }, "hourly_price": { "type": "number" }, "monthly_price": { "type": "number" }, "percent": { "type": "number" }, "currency": { "type": "string" }, "is_active": { "type": "boolean" } }, "required": [ "datacenter", "sku", "unit", "hourly_price", "monthly_price", "percent", "currency", "is_active" ] }, "PrimaryIP": { "type": "object", "description": "A server's own public address.", "properties": { "id": { "type": "integer", "format": "int64", "description": "Unique identifier.", "minimum": 1 }, "name": { "type": "string" }, "datacenter": { "type": "string", "description": "Datacenter code, e.g. `ovh`.", "examples": [ "ovh" ] }, "type": { "type": "string", "enum": [ "ipv4", "ipv6" ] }, "ip": { "type": "string" }, "server_id": { "type": [ "integer", "null" ], "format": "int64" }, "dns_ptr": { "type": "string", "description": "Reverse DNS." }, "auto_delete": { "type": "boolean", "description": "Deleted with its server." }, "created_at": { "type": "string", "description": "When it was created (RFC 3339).", "format": "date-time" }, "project_id": { "type": "integer", "format": "int64", "description": "Project the resource is in." } }, "required": [ "id", "name", "datacenter", "type", "ip", "server_id", "dns_ptr", "auto_delete", "created_at", "project_id" ] }, "PrimaryIPList": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/PrimaryIP" } }, "meta": { "$ref": "#/components/schemas/ListMeta" } }, "required": [ "data", "meta" ] }, "PublicLocationPrice": { "type": "object", "properties": { "location": { "type": "string", "description": "Datacenter code, e.g. `ovh`.", "examples": [ "ovh" ] }, "price_hourly": { "$ref": "#/components/schemas/PublicPrice" }, "price_monthly": { "$ref": "#/components/schemas/PublicPrice" } }, "required": [ "location", "price_hourly", "price_monthly" ] }, "PublicPrice": { "type": "object", "properties": { "net": { "type": "number", "description": "Amount, VAT excluded." }, "currency": { "type": "string", "examples": [ "IRR" ] } }, "required": [ "net", "currency" ] }, "PublicPricing": { "type": "object", "description": "Every plan and price on sale in a listed datacenter, from the rows billing uses.", "properties": { "vat_included": { "type": "boolean", "description": "Always false: prices exclude VAT." }, "hours_per_month": { "type": "integer", "description": "The month monthly prices are quoted over." }, "server_types": { "type": "array", "items": { "$ref": "#/components/schemas/PublicServerType" } }, "resources": { "type": "array", "items": { "$ref": "#/components/schemas/PublicResourcePrice" } } }, "required": [ "vat_included", "hours_per_month", "server_types", "resources" ] }, "PublicResourcePrice": { "type": "object", "properties": { "sku": { "type": "string", "description": "`primary_ipv4`, `floating_ipv4`, `floating_ipv6`, `elastic_ipv4`, `volume_gb`, `snapshot_gb`, `backup`, `nat_gateway`, and one per load balancer type (`lb11`, `lb21`, `lb31`).", "examples": [ "nat_gateway" ] }, "location": { "type": "string", "description": "Datacenter code, e.g. `ovh`.", "examples": [ "ovh" ] }, "unit": { "type": "string", "description": "`hour`: per resource; `gb_hour`: per GB; `percent`: a share of the server's plan (backups), prices 0.", "enum": [ "hour", "gb_hour", "percent" ] }, "price_hourly": { "$ref": "#/components/schemas/PublicPrice" }, "price_monthly": { "$ref": "#/components/schemas/PublicPrice" }, "percent": { "type": [ "number", "null" ], "description": "The share of the server's plan for a `percent` SKU, else null." } }, "required": [ "sku", "location", "unit", "price_hourly", "price_monthly", "percent" ] }, "PublicServerType": { "type": "object", "properties": { "id": { "type": "integer", "format": "int64", "description": "The plan id `POST /servers` takes as `plan_id`." }, "name": { "type": "string", "examples": [ "C2" ] }, "description": { "type": "string" }, "group": { "type": "string", "description": "Plan group key, e.g. `shared`." }, "group_name": { "type": "string" }, "cores": { "type": "integer" }, "memory_mb": { "type": "integer" }, "disk_gb": { "type": "integer" }, "included_traffic_gb": { "type": [ "integer", "null" ], "description": "Included traffic; null when not metered." }, "minimum_usage_hours": { "type": "integer", "description": "Hours charged up front when a server is created." }, "prices": { "type": "array", "items": { "$ref": "#/components/schemas/PublicLocationPrice" } } }, "required": [ "id", "name", "description", "group", "group_name", "cores", "memory_mb", "disk_gb", "included_traffic_gb", "minimum_usage_hours", "prices" ] }, "QuotaLimit": { "type": "object", "properties": { "resource": { "type": "string", "enum": [ "servers", "vcpus", "ram_gb", "disk_gb", "volumes", "floating_ips", "networks", "routers", "load_balancers", "snapshots" ] }, "limit": { "type": "integer", "format": "int64" }, "used": { "type": "integer", "format": "int64" }, "source": { "type": "string", "description": "Where the limit comes from.", "enum": [ "default", "datacenter", "account" ] } }, "required": [ "resource", "limit", "used", "source" ] }, "RetainedCost": { "type": "object", "description": "Copies billed per GB at the snapshot price.", "properties": { "count": { "type": "integer" }, "size_gb": { "type": "number" }, "hourly_price": { "type": "number" }, "monthly_price": { "type": "number" }, "currency": { "type": "string" } }, "required": [ "count", "size_gb", "hourly_price", "monthly_price", "currency" ] }, "Route": { "type": "object", "properties": { "destination": { "type": "string", "description": "CIDR." }, "gateway": { "type": "string", "description": "Next hop, an address in the network." } }, "required": [ "destination", "gateway" ] }, "RouterRef": { "type": "object", "description": "The NAT gateway (router) of a network.", "properties": { "id": { "type": "integer", "format": "int64", "description": "Unique identifier.", "minimum": 1 }, "name": { "type": "string" }, "status": { "type": "string" }, "public_ip": { "type": "string" } }, "required": [ "id", "name", "status", "public_ip" ] }, "Server": { "type": "object", "properties": { "id": { "type": "integer", "format": "int64", "description": "Unique identifier.", "minimum": 1 }, "name": { "type": "string" }, "status": { "type": "string", "description": "`initializing`, `starting`, `running`, `stopping`, `off`, `rebooting`, `rebuilding`, `migrating`, `deleting` or `unknown`." }, "datacenter": { "type": "string", "description": "Datacenter code, e.g. `ovh`.", "examples": [ "ovh" ] }, "plan_id": { "type": "integer", "format": "int64" }, "disk_gb": { "type": "integer" }, "image": { "type": "string", "description": "Image slug it was created or last rebuilt from." }, "ipv4": { "type": "string", "description": "Public IPv4, empty when it has none." }, "ipv6": { "type": "string", "description": "Public IPv6, empty when it has none." }, "rescue_enabled": { "type": "boolean" }, "locked": { "type": "boolean", "description": "Locked servers refuse changes (423 `server_locked`)." }, "locked_reason": { "type": "string" }, "protection_delete": { "type": "boolean", "description": "Delete protection: while true the resource cannot be deleted." }, "labels": { "$ref": "#/components/schemas/Labels" }, "created_at": { "type": "string", "description": "When it was created (RFC 3339).", "format": "date-time" }, "protection_rebuild": { "type": "boolean", "description": "Rebuild protection." }, "project_id": { "type": "integer", "format": "int64", "description": "Project the resource is in." }, "ip_change": { "allOf": [ { "$ref": "#/components/schemas/IPChange" } ], "description": "Present on `GET /servers/{id}` only." } }, "required": [ "id", "name", "status", "datacenter", "plan_id", "disk_gb", "image", "ipv4", "ipv6", "rescue_enabled", "locked", "protection_delete", "labels", "created_at", "protection_rebuild", "project_id" ] }, "ServerCost": { "type": "object", "description": "A server's current rate; `snapshots` stay billed after a delete, `kept_backups` only with `keep_backups`.", "properties": { "server_id": { "type": "integer", "format": "int64" }, "hours_per_month": { "type": "integer" }, "lines": { "type": "array", "items": { "$ref": "#/components/schemas/CostLine" } }, "totals": { "type": "array", "items": { "$ref": "#/components/schemas/CostTotal" }, "description": "Sum of the lines per currency." }, "snapshots": { "$ref": "#/components/schemas/RetainedCost" }, "kept_backups": { "$ref": "#/components/schemas/RetainedCost" } }, "required": [ "server_id", "hours_per_month", "lines", "totals", "snapshots", "kept_backups" ] }, "ServerCreateRequest": { "type": "object", "properties": { "datacenter": { "type": "string", "description": "Datacenter code, e.g. `ovh`.", "examples": [ "ovh" ] }, "name": { "type": "string", "description": "Hostname: letters, digits, dots and dashes, up to 63 characters. With `count` > 1 the servers are numbered from it.", "pattern": "^[a-zA-Z0-9]([a-zA-Z0-9.-]{0,61}[a-zA-Z0-9])?$" }, "plan_id": { "type": "integer", "format": "int64", "minimum": 1 }, "image": { "type": "string", "description": "Image slug, or `snapshot:` / `backup:` (see `GET /images`)." }, "ssh_keys": { "type": "array", "items": { "type": "string" }, "description": "Public keys to install." }, "ssh_key_ids": { "type": "array", "items": { "type": "integer", "format": "int64" }, "description": "Saved SSH keys of the account to install." }, "user_data": { "type": "string", "description": "cloud-init user data, at most 32 KiB." }, "start_after_create": { "type": "boolean", "description": "Default true." }, "firewall_ids": { "type": "array", "items": { "type": "integer", "format": "int64" } }, "backups": { "type": "boolean", "description": "Enable daily backups." }, "networks": { "$ref": "#/components/schemas/ServerNetworksInput" }, "count": { "type": "integer", "description": "How many servers to create, 1-10 (default 1).", "minimum": 1, "maximum": 10 }, "labels": { "$ref": "#/components/schemas/Labels" }, "volume_ids": { "type": "array", "items": { "type": "integer", "format": "int64" }, "description": "Existing volumes to attach once the server runs (at most 16)." }, "project_id": { "type": "integer", "format": "int64", "description": "Project to create it in; the account's Default project when absent.", "minimum": 1 } }, "required": [ "datacenter", "name", "plan_id", "image" ] }, "ServerCreateResponse": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Server" }, "action_id": { "type": "integer", "format": "int64", "description": "The first server's create action." }, "root_password": { "type": "string", "description": "Root password, shown once and never stored in the clear." }, "servers": { "type": "array", "items": { "$ref": "#/components/schemas/CreatedServer" }, "description": "Every server created (several when `count` > 1), each with its action." } }, "required": [ "data", "action_id", "root_password", "servers" ] }, "ServerList": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Server" } }, "meta": { "$ref": "#/components/schemas/ListMeta" } }, "required": [ "data", "meta" ] }, "ServerMetrics": { "type": "object", "properties": { "start": { "type": "string", "format": "date-time" }, "end": { "type": "string", "format": "date-time" }, "step": { "type": "integer", "description": "Seconds between points." }, "time_series": { "type": "object", "description": "Series by name, e.g. `cpu`, `disk.0.iops.read`, `disk.0.bandwidth.write`, `network.0.bandwidth.in`.", "properties": {}, "additionalProperties": { "type": "object", "properties": { "values": { "type": "array", "items": { "type": "array", "prefixItems": [ { "type": "number", "description": "Unix time in seconds." }, { "type": "string", "description": "Value, as a decimal string." } ], "minItems": 2, "maxItems": 2 }, "description": "[unix seconds, value] pairs." } }, "required": [ "values" ] } } }, "required": [ "start", "end", "step", "time_series" ] }, "ServerNetworkAttachment": { "type": "object", "properties": { "network_id": { "type": "integer", "format": "int64" }, "network_name": { "type": "string" }, "ip_range": { "type": "string" }, "subnet_id": { "type": "integer", "format": "int64" }, "subnet": { "type": "string" }, "ip": { "type": "string" }, "ready": { "type": "boolean" }, "primary": { "type": "boolean" }, "router": { "anyOf": [ { "$ref": "#/components/schemas/RouterRef" }, { "type": "null" } ] }, "mac": { "type": "string" }, "gateway": { "type": "string", "description": "The router's address in the subnet, when it has a router." } }, "required": [ "network_id", "network_name", "ip_range", "subnet_id", "subnet", "ip", "ready", "primary", "router", "mac", "gateway" ] }, "ServerNetworking": { "type": "object", "properties": { "server_id": { "type": "integer", "format": "int64" }, "datacenter": { "type": "string", "description": "Datacenter code, e.g. `ovh`.", "examples": [ "ovh" ] }, "ipv4": { "type": "string" }, "ipv6": { "type": "string" }, "private_only": { "type": "boolean" }, "primary_network_id": { "type": [ "integer", "null" ], "format": "int64" }, "primary_ips": { "type": "array", "items": { "$ref": "#/components/schemas/ServerPrimaryIP" } }, "networks": { "type": "array", "items": { "$ref": "#/components/schemas/ServerNetworkAttachment" } }, "floating_ips": { "type": "array", "items": { "$ref": "#/components/schemas/FloatingIP" } }, "elastic_ip": { "anyOf": [ { "$ref": "#/components/schemas/ElasticIP" }, { "type": "null" } ] }, "ipv6_available": { "type": "boolean" }, "public_interface": { "type": [ "object", "null" ], "properties": { "mac": { "type": "string" }, "addresses": { "type": "array", "items": { "type": "object", "properties": { "ip": { "type": "string" }, "cidr": { "type": "string" }, "gateway": { "type": "string" } }, "required": [ "ip", "cidr", "gateway" ] } } }, "required": [ "mac", "addresses" ] }, "ip_change": { "anyOf": [ { "$ref": "#/components/schemas/IPChange" }, { "type": "null" } ] } }, "required": [ "server_id", "datacenter", "ipv4", "ipv6", "private_only", "primary_network_id", "primary_ips", "networks", "floating_ips", "elastic_ip", "ipv6_available", "public_interface", "ip_change" ] }, "ServerNetworksInput": { "type": "object", "properties": { "enable_ipv4": { "type": "boolean", "description": "Give the server a public IPv4 (default true)." }, "enable_ipv6": { "type": "boolean", "description": "Give the server a public IPv6." }, "network_ids": { "type": "array", "items": { "description": "An id, as a JSON number or a numeric string.", "oneOf": [ { "type": "integer", "format": "int64", "minimum": 1 }, { "type": "string", "pattern": "^[0-9]+$" } ] }, "description": "Private networks to attach it to." } } }, "ServerOperationRequest": { "description": "The body depends on `op`: `rebuild` takes `image`, `change_plan` takes `plan_id`, `change_ipv4` optionally takes `confirm_paid`; the others take no body.", "anyOf": [ { "type": "object", "properties": { "image": { "type": "string", "description": "Image slug to reinstall from." } }, "required": [ "image" ], "title": "rebuild" }, { "type": "object", "properties": { "plan_id": { "type": "integer", "format": "int64", "minimum": 1 } }, "required": [ "plan_id" ], "title": "change_plan" }, { "type": "object", "properties": { "confirm_paid": { "type": "boolean", "description": "True once the customer accepted the fee of a paid change." } }, "title": "change_ipv4" } ] }, "ServerOperationResponse": { "type": "object", "properties": { "action_id": { "type": "integer", "format": "int64" }, "root_password": { "type": "string", "description": "The new root password (`rebuild`, `enable_rescue`, `reset_password`), shown once." } }, "required": [ "action_id" ] }, "ServerPrimaryIP": { "type": "object", "description": "A primary IP with its subnet and gateway, for configuring it by hand.", "properties": { "id": { "type": "integer", "format": "int64", "description": "Unique identifier.", "minimum": 1 }, "name": { "type": "string" }, "datacenter": { "type": "string", "description": "Datacenter code, e.g. `ovh`.", "examples": [ "ovh" ] }, "type": { "type": "string", "enum": [ "ipv4", "ipv6" ] }, "ip": { "type": "string" }, "server_id": { "type": [ "integer", "null" ], "format": "int64" }, "dns_ptr": { "type": "string", "description": "Reverse DNS." }, "auto_delete": { "type": "boolean", "description": "Deleted with its server." }, "created_at": { "type": "string", "description": "When it was created (RFC 3339).", "format": "date-time" }, "project_id": { "type": "integer", "format": "int64", "description": "Project the resource is in." }, "cidr": { "type": "string" }, "gateway": { "type": "string" } }, "required": [ "id", "name", "datacenter", "type", "ip", "server_id", "dns_ptr", "auto_delete", "created_at", "project_id", "cidr", "gateway" ] }, "ServerStorage": { "type": "object", "properties": { "root_disk": { "type": "object", "properties": { "size_gb": { "type": "integer" }, "type": { "type": "string", "description": "Volume type, e.g. `nvme`." }, "device": { "type": "string" }, "bus": { "type": "string", "enum": [ "virtio", "scsi" ] } }, "required": [ "size_gb", "type", "device", "bus" ] }, "rescue": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "since": { "type": [ "string", "null" ], "format": "date-time" }, "disk_device": { "type": "string" } }, "required": [ "enabled", "since", "disk_device" ] } }, "required": [ "root_disk", "rescue" ] }, "ServerUpdateRequest": { "type": "object", "description": "Every field is optional: what is sent is changed, the rest stays.", "properties": { "name": { "type": "string", "pattern": "^[a-zA-Z0-9]([a-zA-Z0-9.-]{0,61}[a-zA-Z0-9])?$" }, "protection_delete": { "type": "boolean" }, "protection_rebuild": { "type": "boolean" }, "labels": { "$ref": "#/components/schemas/Labels" }, "project_id": { "type": "integer", "format": "int64", "description": "Move the server to this project of the account.", "minimum": 1 } } }, "Snapshot": { "type": "object", "properties": { "id": { "type": "integer", "format": "int64", "description": "Unique identifier.", "minimum": 1 }, "kind": { "type": "string", "enum": [ "snapshot" ] }, "image": { "type": "string", "description": "What `POST /servers` and `rebuild` take: `snapshot:`." }, "name": { "type": "string" }, "description": { "type": "string" }, "datacenter": { "type": "string", "description": "Datacenter code, e.g. `ovh`.", "examples": [ "ovh" ] }, "status": { "type": "string", "description": "e.g. `creating`, `available`, `error`." }, "size_gb": { "type": [ "number", "null" ], "description": "Stored size; null until available." }, "disk_gb": { "type": "integer", "description": "Minimum disk to create a server from it." }, "server_id": { "type": [ "integer", "null" ], "format": "int64", "description": "Server it was taken from." }, "server_name": { "type": "string" }, "source_image": { "type": "string" }, "protection_delete": { "type": "boolean", "description": "Delete protection: while true the resource cannot be deleted." }, "labels": { "$ref": "#/components/schemas/Labels" }, "created_at": { "type": "string", "description": "When it was created (RFC 3339).", "format": "date-time" }, "project_id": { "type": "integer", "format": "int64", "description": "Project the resource is in." } }, "required": [ "id", "kind", "image", "name", "description", "datacenter", "status", "size_gb", "disk_gb", "server_id", "server_name", "source_image", "protection_delete", "labels", "created_at", "project_id" ] }, "SnapshotList": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Snapshot" } }, "meta": { "$ref": "#/components/schemas/ListMeta" } }, "required": [ "data", "meta" ] }, "Subnet": { "type": "object", "properties": { "id": { "type": "integer", "format": "int64", "description": "Unique identifier.", "minimum": 1 }, "ip_range": { "type": "string", "description": "CIDR." }, "status": { "type": "string" }, "gateway": { "type": "string", "description": "The router's address in the subnet (its first host)." }, "created_at": { "type": "string", "description": "When it was created (RFC 3339).", "format": "date-time" } }, "required": [ "id", "ip_range", "status", "gateway", "created_at" ] }, "Volume": { "type": "object", "properties": { "id": { "type": "integer", "format": "int64", "description": "Unique identifier.", "minimum": 1 }, "name": { "type": "string" }, "datacenter": { "type": "string", "description": "Datacenter code, e.g. `ovh`.", "examples": [ "ovh" ] }, "size_gb": { "type": "integer" }, "status": { "type": "string", "description": "e.g. `creating`, `available`, `attached`, `resizing`, `deleting`." }, "server_id": { "type": [ "integer", "null" ], "format": "int64", "description": "Server it is attached to." }, "device": { "type": "string", "description": "Stable device path in the server; absent when detached or on scsi." }, "created_at": { "type": "string", "description": "When it was created (RFC 3339).", "format": "date-time" }, "disk_bus": { "type": "string", "enum": [ "virtio", "scsi" ] }, "device_id_prefix": { "type": "string", "description": "Part of its id in the disk's serial and by-id name." }, "protection_delete": { "type": "boolean", "description": "Delete protection: while true the resource cannot be deleted." }, "labels": { "$ref": "#/components/schemas/Labels" }, "filesystem": { "type": "string", "description": "Filesystem it is meant for; empty for none.", "enum": [ "ext4", "xfs", "" ] }, "project_id": { "type": "integer", "format": "int64", "description": "Project the resource is in." } }, "required": [ "id", "name", "datacenter", "size_gb", "status", "server_id", "created_at", "disk_bus", "device_id_prefix", "protection_delete", "labels", "filesystem", "project_id" ] }, "VolumeList": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Volume" } }, "meta": { "$ref": "#/components/schemas/ListMeta" } }, "required": [ "data", "meta" ] }, "VolumePrice": { "type": "object", "properties": { "datacenter": { "type": "string", "description": "Datacenter code, e.g. `ovh`.", "examples": [ "ovh" ] }, "gb_hourly_price": { "type": "number" }, "currency": { "type": "string" }, "is_active": { "type": "boolean" } }, "required": [ "datacenter", "gb_hourly_price", "currency", "is_active" ] } } } }