{ "openapi": "3.1.0", "info": { "title": "GalaxyGate API", "description": "Welcome to the GalaxyGate API documentation", "version": "1.0.0" }, "servers": [ { "url": "https://api.galaxygate.net/v1", "description": "Production API" } ], "security": [ { "api": [] }, { "cookie": [] } ], "tags": [ { "name": "Authentication", "description": "Login and session management" }, { "name": "Instance commands", "description": "Operations that interact with an instance" }, { "name": "Dedibox commands", "description": "Operations that interact with a dedibox" }, { "name": "Network commands", "description": "Operations that interact with networking" }, { "name": "Workspaces", "description": "Operations related to workspaces" }, { "name": "Instances", "description": "Operations related to instances" }, { "name": "Dedibox", "description": "Operations related to dediboxes" }, { "name": "User settings", "description": "Operations related to your user account" }, { "name": "Tokens", "description": "Operations related to API tokens" }, { "name": "Templates", "description": "Operations related to templates" }, { "name": "SSH Keys", "description": "Operations related to SSH keys" }, { "name": "Snapshots", "description": "Operations related to instance snapshots" }, { "name": "Firewall", "description": "Operations related to the firewall" }, { "name": "Cloud", "description": "Operations available to cloud accounts" }, { "name": "Metrics", "description": "Operations related to metrics" }, { "name": "ISOs", "description": "Operations related to ISOs" }, { "name": "IPs", "description": "Operations related to IPs" }, { "name": "Disks", "description": "Operations related to disks" }, { "name": "Backups", "description": "Operations related to backups" }, { "name": "VPCs", "description": "Operations related to VPCs" } ], "paths": { "/app-templates": { "get": { "description": "Lists all staff-curated app templates available for deployment.", "operationId": "getAppTemplates", "parameters": [ { "description": "Quick search by name, image, or ID", "in": "query", "name": "q", "required": false, "schema": { "type": "string" } }, { "description": "Filter by template name (partial match)", "in": "query", "name": "name", "required": false, "schema": { "type": "string" } }, { "description": "Filter by docker image (partial match)", "in": "query", "name": "image", "required": false, "schema": { "type": "string" } }, { "description": "Filter by category", "in": "query", "name": "category", "required": false, "schema": { "enum": [ "DEFAULT", "GAMES", "SOFTWARE", "INFRASTRUCTURE", "AI", "MEDIA", "TOOLS", "DATABASES", "MONITORING", "PRODUCTIVITY", "DEVOPS", "AUTOMATION", "NETWORK" ], "type": "string" } }, { "description": "How many items to return", "example": 50, "in": "query", "name": "limit", "required": false, "schema": { "format": "int32", "type": "integer" } }, { "description": "Page number to fetch", "example": 1, "in": "query", "name": "page", "required": false, "schema": { "format": "int32", "type": "integer" } }, { "description": "Field to order by", "example": "id", "in": "query", "name": "sort", "required": false, "schema": { "type": "string" } }, { "description": "Order direction (ASC/DESC)", "example": "asc", "in": "query", "name": "dir", "required": false, "schema": { "type": "string" } }, { "description": "Forward keyset cursor (for keyset pagination)", "in": "query", "name": "after", "required": false, "schema": { "type": "string" } }, { "description": "Backward keyset cursor (for keyset pagination)", "in": "query", "name": "before", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/KeysetResultAppTemplateView" } } }, "description": "OK" }, "default": { "description": "Every failure returns this envelope; the HTTP status carries the category.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "summary": "List app templates", "tags": [ "App Templates" ] }, "post": { "description": "Staff-only. Creates a new globally available app template.", "operationId": "postAppTemplates", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateAppTemplateRequest" } } }, "required": true }, "responses": { "201": { "content": { "*/*": { "schema": { "$ref": "#/components/schemas/AppTemplateDetailView" } } }, "description": "Created" }, "default": { "description": "Every failure returns this envelope; the HTTP status carries the category.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "summary": "Create an app template", "tags": [ "App Templates" ] } }, "/app-templates/{atid}": { "get": { "description": "Returns the full configuration of an app template, including default env, mounts, and ports.", "operationId": "getAppTemplatesByAtid", "parameters": [ { "description": "Template ID", "in": "path", "name": "atid", "required": true, "schema": { "example": "1471181001588760790", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AppTemplateDetailView" } } }, "description": "OK" }, "default": { "description": "Every failure returns this envelope; the HTTP status carries the category.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "summary": "Get an app template", "tags": [ "App Templates" ] }, "delete": { "description": "Staff-only. Deletes an app template.", "operationId": "deleteAppTemplatesByAtid", "parameters": [ { "description": "Template ID", "in": "path", "name": "atid", "required": true, "schema": { "example": "1471181001588760790", "type": "string" } } ], "responses": { "204": { "description": "No Content" }, "default": { "description": "Every failure returns this envelope; the HTTP status carries the category.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "summary": "Delete an app template", "tags": [ "App Templates" ] }, "patch": { "description": "Staff-only. Patches an app template; omitted fields are left unchanged. Setting a non-nullable field to null is rejected; setting category to null clears it.", "operationId": "patchAppTemplatesByAtid", "parameters": [ { "description": "Template ID", "in": "path", "name": "atid", "required": true, "schema": { "example": "1471181001588760790", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateAppTemplateRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AppTemplateDetailView" } } }, "description": "OK" }, "default": { "description": "Every failure returns this envelope; the HTTP status carries the category.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "summary": "Update an app template", "tags": [ "App Templates" ] } }, "/apps/domains": { "get": { "description": "Returns the list of base domains available for custom app subdomains.", "operationId": "getAppsDomains", "responses": { "200": { "content": { "application/json": { "schema": { "items": { "$ref": "#/components/schemas/AppDomainResponse" }, "type": "array" } } }, "description": "OK" }, "default": { "description": "Every failure returns this envelope; the HTTP status carries the category.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "summary": "List available domains", "tags": [ "App Domains" ] }, "post": { "description": "Checks whether a domain name is already in use. Returns 200 if the domain is taken, or 404 if it is available.", "operationId": "postAppsDomains", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DomainCheckRequest" } } }, "required": true }, "responses": { "200": { "description": "Domain is already in use" }, "404": { "description": "Domain is available" }, "default": { "description": "Every failure returns this envelope; the HTTP status carries the category.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "summary": "Check domain availability", "tags": [ "App Domains" ] } }, "/apps/{aid}": { "get": { "description": "Returns full configuration, port mappings, and live container stats of an app.", "operationId": "getAppsByAid", "parameters": [ { "description": "App ID", "in": "path", "name": "aid", "required": true, "schema": { "example": "1483754921000984881", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EnrichedAppDetailViewAppDetailLive" } } }, "description": "OK" }, "default": { "description": "Every failure returns this envelope; the HTTP status carries the category.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "summary": "Get app details", "tags": [ "Apps" ] }, "put": { "description": "Updates an app's configuration and redeploys the container.", "operationId": "putAppsByAid", "parameters": [ { "description": "App ID", "in": "path", "name": "aid", "required": true, "schema": { "example": "1483754921000984881", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateAppRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkflowWithResource" } } }, "description": "OK" }, "default": { "description": "Every failure returns this envelope; the HTTP status carries the category.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "summary": "Update an app", "tags": [ "Apps" ] }, "delete": { "description": "Stops and removes the container, then deletes the app and its port allocations. With delete_data, the app's Docker volumes are removed too; bind-mounted host paths are never touched.", "operationId": "deleteAppsByAid", "parameters": [ { "description": "App ID", "in": "path", "name": "aid", "required": true, "schema": { "example": "1483754921000984881", "type": "string" } }, { "description": "Remove the app's volumes and their data", "example": true, "in": "query", "name": "delete_data", "required": false, "schema": { "default": false, "type": "boolean" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkflowWithResource" } } }, "description": "OK" }, "default": { "description": "Every failure returns this envelope; the HTTP status carries the category.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "summary": "Delete an app", "tags": [ "Apps" ] } }, "/apps/{aid}/logs": { "get": { "description": "Fetches recent container logs for an app. Pass `follow` to receive them as a stream of server-sent events instead, staying open as new lines arrive.", "operationId": "getAppsByAidLogs", "parameters": [ { "description": "App ID", "in": "path", "name": "aid", "required": true, "schema": { "example": "1483754921000984881", "type": "string" } }, { "description": "Number of tail lines to return (default: 100, max: 10000)", "in": "query", "name": "tail", "required": false, "schema": { "description": "Number of tail lines to return (default: 100, max: 10000)", "format": "int32", "maximum": 10000, "minimum": 1, "type": "integer" } }, { "description": "Stream the logs as server-sent events instead of returning them once", "in": "query", "name": "follow", "required": false, "schema": { "description": "Stream the logs as server-sent events instead of returning them once", "type": "boolean" } } ], "responses": { "200": { "content": { "text/event-stream": { "schema": { "type": "string" } }, "text/plain": { "schema": { "type": "string" } } }, "description": "The logs, as text when returned once and as an event stream when followed" }, "default": { "description": "Every failure returns this envelope; the HTTP status carries the category.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "summary": "Get app logs", "tags": [ "App Logs" ] } }, "/apps/{aid}/metrics": { "get": { "description": "Fetches historical CPU, memory, and network metrics for an app container from Prometheus.", "operationId": "getAppsByAidMetrics", "parameters": [ { "description": "App ID", "in": "path", "name": "aid", "required": true, "schema": { "example": "1483754921000984881", "type": "string" } }, { "description": "Start time as Unix epoch seconds", "example": 1784554200, "in": "query", "name": "start", "required": true, "schema": { "format": "int64", "type": "integer" } }, { "description": "End time as Unix epoch seconds", "example": 1784557800, "in": "query", "name": "end", "required": true, "schema": { "format": "int64", "type": "integer" } }, { "description": "Query resolution step in seconds (minimum 15)", "example": 60, "in": "query", "name": "step", "required": true, "schema": { "format": "int64", "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AppMetrics" } } }, "description": "OK" }, "default": { "description": "Every failure returns this envelope; the HTTP status carries the category.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "summary": "Fetch app metrics", "tags": [ "Apps" ] } }, "/apps/{aid}/restart": { "post": { "description": "Stops and starts an app container.", "operationId": "postAppsByAidRestart", "parameters": [ { "description": "App ID", "in": "path", "name": "aid", "required": true, "schema": { "example": "1483754921000984881", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkflowWithResource" } } }, "description": "OK" }, "default": { "description": "Every failure returns this envelope; the HTTP status carries the category.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "summary": "Restart an app", "tags": [ "Apps" ] } }, "/apps/{aid}/start": { "post": { "description": "Starts a stopped app container.", "operationId": "postAppsByAidStart", "parameters": [ { "description": "App ID", "in": "path", "name": "aid", "required": true, "schema": { "example": "1483754921000984881", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkflowWithResource" } } }, "description": "OK" }, "default": { "description": "Every failure returns this envelope; the HTTP status carries the category.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "summary": "Start an app", "tags": [ "Apps" ] } }, "/apps/{aid}/stop": { "post": { "description": "Stops a running app container.", "operationId": "postAppsByAidStop", "parameters": [ { "description": "App ID", "in": "path", "name": "aid", "required": true, "schema": { "example": "1483754921000984881", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkflowWithResource" } } }, "description": "OK" }, "default": { "description": "Every failure returns this envelope; the HTTP status carries the category.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "summary": "Stop an app", "tags": [ "Apps" ] } }, "/auth/callback": { "post": { "description": "Exchanges the provider's authorization code for a SESSION-issued token, identical to the one\n`POST /v1/login` returns. The plaintext code is only returned once, save it securely.\n\nAn address the provider has verified is matched against an existing account on first use; otherwise a\nnew account is created. The provider has already confirmed the address, so no confirmation email is\ninvolved and a session comes back straight away, the same way `POST /v1/register` answers an invite.\nAfterwards the provider account itself identifies the user, so the two email addresses may differ\nfreely.\n\nWhen the account has a second factor, the first call answers 403 `MfaChallenge`. Retry with the same\n`state` and `mfa`, but without `code`: the authorization code is already spent by then and the provider\nwill not accept it twice. Retrying with only `state` answers the challenge again. The sign-in stays\nopen for 10 minutes and five failed attempts; after that the callback fails with `login_expired`.\n", "operationId": "postAuthCallback", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SsoCallbackRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TokenCreateResponse" } } }, "description": "OK" }, "403": { "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ApiError" }, { "$ref": "#/components/schemas/MfaChallenge" } ] } } }, "description": "Forbidden, or `MfaChallenge` when a second factor is needed" }, "default": { "description": "Every failure returns this envelope; the HTTP status carries the category.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "summary": "Complete signing in with an external provider", "tags": [ "Authentication" ], "x-api-modifiers": [ "open" ], "security": [] } }, "/auth/start": { "get": { "description": "Returns the provider URL to send the browser to, together with the `state` value that authorization\nrequest is bound to. Send the browser to `url`, then hand the `code` and `state` the provider returns\nto `POST /v1/auth/callback`.\n\nThe optional `coupon` is stored with the `state`, so the client does not keep it across the provider\nredirect. It applies only when the sign-in creates an account, and a code that cannot be redeemed does\nnot stop the sign-up. A sign-in to an existing account ignores the coupon; redeem it from the wallet.\n\nA provider the deployment has no registered application for answers 404.\n", "operationId": "getAuthStart", "parameters": [ { "description": "Provider to sign in with", "example": "google", "in": "query", "name": "provider", "required": true, "schema": { "enum": [ "google", "github" ], "type": "string" } }, { "description": "Which of the configured redirect URIs the provider should return to. Defaults to the first configured URI.", "in": "query", "name": "redirect_uri", "required": false, "schema": { "type": "string" } }, { "description": "Coupon code to redeem if this sign-in creates a new account.", "example": "LAUNCH2026", "in": "query", "name": "coupon", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SsoStartResponse" } } }, "description": "OK" }, "default": { "description": "Every failure returns this envelope; the HTTP status carries the category.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "summary": "Begin signing in with an external provider", "tags": [ "Authentication" ], "x-api-modifiers": [ "open" ], "security": [] } }, "/commands/apply-upgrades": { "post": { "description": "Applies all pending instance upgrades. Async operation.\nA running instance is powered off for the upgrade and powered back on afterwards.\n", "operationId": "postCommandsApplyUpgrades", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApplyUpgradeRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkflowData" } } }, "description": "OK" }, "default": { "description": "Every failure returns this envelope; the HTTP status carries the category.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "summary": "Applies pending instance upgrades", "tags": [ "Instance commands" ] } }, "/commands/attach-ip": { "post": { "description": "Connects an IP to an instance. Async Operation. Network changes are reflected instantly.\n", "operationId": "postCommandsAttachIp", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AttachIpRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FloatingIpListView" } } }, "description": "OK" }, "default": { "description": "Every failure returns this envelope; the HTTP status carries the category.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "summary": "Attaches an IP to an Instance", "tags": [ "Network commands" ] } }, "/commands/attach-iso": { "post": { "description": "Connects an ISO to an instance. CDROM update is attempted immediately.\n", "operationId": "postCommandsAttachIso", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AttachIsoRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkflowData" } } }, "description": "OK" }, "default": { "description": "Every failure returns this envelope; the HTTP status carries the category.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "summary": "Attaches an ISO to an Instance", "tags": [ "Instance commands" ] } }, "/commands/batch-instance-power": { "post": { "description": "Asynchronous. The instances that cannot do the action are listed in `skipped`.", "operationId": "postCommandsBatchInstancePower", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BatchPowerRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BatchResponse" } } }, "description": "OK" }, "default": { "description": "Every failure returns this envelope; the HTTP status carries the category.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "summary": "Execute a power action on a batch of instances", "tags": [ "Instance commands" ] } }, "/commands/batch-instance-transfer": { "post": { "description": "An instance moves with its included disks and IP addresses, its snapshots and its apps. Its backups stay in the old workspace. If an instance cannot move, for example because it uses other resources of the old workspace, it stays and `skipped` gives the reason. Access tokens bound to a moved resource are revoked.", "operationId": "postCommandsBatchInstanceTransfer", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BatchTransferRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BatchResponse" } } }, "description": "OK" }, "default": { "description": "Every failure returns this envelope; the HTTP status carries the category.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "summary": "Move a batch of instances to another workspace", "tags": [ "Instance commands" ] } }, "/commands/create-snapshot": { "post": { "description": "Queues the creation of a snapshot from an instance. Async operation.\n", "operationId": "postCommandsCreateSnapshot", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateSnapshotRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkflowData" } } }, "description": "OK" }, "default": { "description": "Every failure returns this envelope; the HTTP status carries the category.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "summary": "Creates a snapshot of an instance", "tags": [ "Instance commands" ] } }, "/commands/dedibox-power-cycle": { "post": { "description": "Performs a power operation on a dedibox. Async operation via Temporal.\n", "operationId": "postCommandsDediboxPowerCycle", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PowerCycleRequest" } } }, "required": true }, "responses": { "202": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkflowData" } } }, "description": "Accepted" }, "default": { "description": "Every failure returns this envelope; the HTTP status carries the category.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "summary": "Power controls for dedibox", "tags": [ "Dedibox commands" ] } }, "/commands/dedibox-reset-vnc": { "post": { "description": "Resets the dedibox VNC connection. Potentially fixing connection issues.\n", "operationId": "postCommandsDediboxResetVnc", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DediboxResetVncRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkflowData" } } }, "description": "OK" }, "default": { "description": "Every failure returns this envelope; the HTTP status carries the category.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "summary": "Resets the dedibox VNC connection", "tags": [ "Dedibox commands" ] } }, "/commands/detach-ip": { "post": { "description": "Disconnects an IP address from an instance. Async operation.\nNetwork changes are reflected instantly.\n", "operationId": "postCommandsDetachIp", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DetachIpRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FloatingIpListView" } } }, "description": "OK" }, "default": { "description": "Every failure returns this envelope; the HTTP status carries the category.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "summary": "Detaches an IP address", "tags": [ "Network commands" ] } }, "/commands/detach-iso": { "post": { "description": "Disconnects an ISO from an instance. CDROM update is attempted immediately.\n", "operationId": "postCommandsDetachIso", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DetachIsoRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkflowData" } } }, "description": "OK" }, "default": { "description": "Every failure returns this envelope; the HTTP status carries the category.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "summary": "Detach ISO from Instance", "tags": [ "Instance commands" ] } }, "/commands/install-recipe": { "post": { "description": "Installs a recipe on an instance. Instance must be online. Async operation.\n", "operationId": "postCommandsInstallRecipe", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InstallRecipeRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkflowData" } } }, "description": "OK" }, "default": { "description": "Every failure returns this envelope; the HTTP status carries the category.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "summary": "Installs a recipe on an instance", "tags": [ "Instance commands" ] } }, "/commands/network-auto-attach": { "post": { "description": "Automatically attaches missing IPs to instances. Async operation.\nNetwork changes are reflected instantly if requested.\n", "operationId": "postCommandsNetworkAutoAttach", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NetworkAutoAttachRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkflowWithDataAttachResult" } } }, "description": "OK" }, "default": { "description": "Every failure returns this envelope; the HTTP status carries the category.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "summary": "Automatically attaches IP addresses to an Instance", "tags": [ "Network commands" ] } }, "/commands/reinstall-recommended-firewall": { "post": { "description": "Replaces the instance's firewall with the recommended policy: outbound traffic is allowed, inbound\ntraffic matching no rule is denied, SSH is reachable, and ICMP is admitted under a rate limit. Any\nexisting rules are discarded.\n", "operationId": "postCommandsReinstallRecommendedFirewall", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReinstallRecommendedFirewallRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkflowData" } } }, "description": "OK" }, "default": { "description": "Every failure returns this envelope; the HTTP status carries the category.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "summary": "Reinstall the recommended firewall", "tags": [ "Firewall" ] } }, "/commands/reset-instance-password": { "post": { "description": "Resets an instance's root password. Async operation. Attempts several methods, falling back\nto an offline reset (restart required) in case of failure.\n", "operationId": "postCommandsResetInstancePassword", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResetRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResetResponse" } } }, "description": "OK" }, "default": { "description": "Every failure returns this envelope; the HTTP status carries the category.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "summary": "Resets an instance's root password", "tags": [ "Instance commands" ] } }, "/commands/restore-snapshot": { "post": { "description": "Wipes all data on the instance, replacing with the given snapshot. Async operation.\nInstance must be offline for execution.\n", "operationId": "postCommandsRestoreSnapshot", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestoreSnapshotRequest" } } }, "required": true }, "responses": { "202": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkflowData" } } }, "description": "Accepted" }, "default": { "description": "Every failure returns this envelope; the HTTP status carries the category.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "summary": "Restores a snapshot", "tags": [ "Instance commands" ] } }, "/commands/sync-instance-ssh-keys": { "post": { "description": "Replaces all authorized SSH keys on the instance's root account with the workspace's\ncurrent SSH keys. Requires the instance to be online and running a Linux or BSD operating\nsystem. Async operation.\n", "operationId": "postCommandsSyncInstanceSshKeys", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SyncRequest" } } }, "required": true }, "responses": { "202": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkflowData" } } }, "description": "Accepted" }, "default": { "description": "Every failure returns this envelope; the HTTP status carries the category.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "summary": "Syncs workspace SSH keys to an instance", "tags": [ "Instance commands" ] } }, "/commands/update-instance-hostname": { "post": { "description": "Renames the instance and sets the new name as its hostname through the guest agent. Async operation.\nThe instance must be online with its guest agent running.\n", "operationId": "postCommandsUpdateInstanceHostname", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HostnameRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkflowData" } } }, "description": "OK" }, "default": { "description": "Every failure returns this envelope; the HTTP status carries the category.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "summary": "Updates an instance's hostname", "tags": [ "Instance commands" ] } }, "/credentials/revoke": { "post": { "description": "Revokes exposed GalaxyGate credentials and notifies their owners. Authentication is not necessary. The response is always 202, also when a credential is not valid. Revocation is permanent.\n", "operationId": "postCredentialsRevoke", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CredentialRevokeRequest" } } }, "required": true }, "responses": { "202": { "description": "Accepted" }, "default": { "description": "Every failure returns this envelope; the HTTP status carries the category.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "summary": "Revoke exposed credentials", "tags": [ "Tokens" ], "x-api-modifiers": [ "open" ], "security": [] } }, "/dedibox/{did}": { "get": { "description": "Fetches dedibox details by its ID.\n", "operationId": "getDediboxByDid", "parameters": [ { "description": "Dedibox ID", "in": "path", "name": "did", "required": true, "schema": { "example": "1326819038986244108", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EnrichedDediboxDetailViewDediboxLive" } } }, "description": "OK" }, "default": { "description": "Every failure returns this envelope; the HTTP status carries the category.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "summary": "Fetch dedibox details", "tags": [ "Dedibox" ] }, "patch": { "description": "Updates dedibox details. Omitted fields keep their current value.\n", "operationId": "patchDediboxByDid", "parameters": [ { "description": "Dedibox ID", "in": "path", "name": "did", "required": true, "schema": { "example": "1326819038986244108", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PatchDediboxRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EnrichedDediboxDetailViewDediboxLive" } } }, "description": "OK" }, "default": { "description": "Every failure returns this envelope; the HTTP status carries the category.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "summary": "Update dedibox", "tags": [ "Dedibox" ] } }, "/dedibox/{did}/ips": { "get": { "operationId": "getDediboxByDidIps", "parameters": [ { "in": "path", "name": "did", "required": true, "schema": { "example": "1326819038986244108", "type": "string" } }, { "description": "How many items to return", "example": 50, "in": "query", "name": "limit", "required": false, "schema": { "format": "int32", "type": "integer" } }, { "description": "Page number to fetch", "example": 1, "in": "query", "name": "page", "required": false, "schema": { "format": "int32", "type": "integer" } }, { "description": "Field to order by", "example": "id", "in": "query", "name": "sort", "required": false, "schema": { "type": "string" } }, { "description": "Order direction (ASC/DESC)", "example": "asc", "in": "query", "name": "dir", "required": false, "schema": { "type": "string" } }, { "description": "Forward keyset cursor (for keyset pagination)", "in": "query", "name": "after", "required": false, "schema": { "type": "string" } }, { "description": "Backward keyset cursor (for keyset pagination)", "in": "query", "name": "before", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/KeysetResultDediboxIpListView" } } }, "description": "OK" }, "default": { "description": "Every failure returns this envelope; the HTTP status carries the category.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "tags": [ "dedibox-ip-controller" ] } }, "/dedibox/{did}/ips/{ip}": { "get": { "operationId": "getDediboxByDidIpsByIp", "parameters": [ { "in": "path", "name": "did", "required": true, "schema": { "example": "1326819038986244108", "type": "string" } }, { "in": "path", "name": "ip", "required": true, "schema": { "example": "1464201868476432440", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DediboxIpListView" } } }, "description": "OK" }, "default": { "description": "Every failure returns this envelope; the HTTP status carries the category.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "tags": [ "dedibox-ip-controller" ] } }, "/disks/{did}": { "get": { "description": "Fetches a disk's details by its ID.\n", "operationId": "getDisksByDid", "parameters": [ { "description": "Disk ID", "in": "path", "name": "did", "required": true, "schema": { "example": "1463106081390612571", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OptionallyEnrichedDiskDetailViewDiskLive" } } }, "description": "OK" }, "default": { "description": "Every failure returns this envelope; the HTTP status carries the category.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "summary": "Fetches a disk", "tags": [ "Disks" ] }, "patch": { "description": "Updates a disk's details.\n", "operationId": "patchDisksByDid", "parameters": [ { "description": "Disk ID", "in": "path", "name": "did", "required": true, "schema": { "example": "1463106081390612571", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PatchDiskRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OptionallyEnrichedDiskDetailViewDiskLive" } } }, "description": "OK" }, "default": { "description": "Every failure returns this envelope; the HTTP status carries the category.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "summary": "Updates a disk", "tags": [ "Disks" ] } }, "/disks/{did}/attach": { "post": { "description": "Attaches a disk to an instance.\n", "operationId": "postDisksByDidAttach", "parameters": [ { "description": "Disk ID", "in": "path", "name": "did", "required": true, "schema": { "example": "1463106081390612571", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AttachDiskRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkflowData" } } }, "description": "OK" }, "default": { "description": "Every failure returns this envelope; the HTTP status carries the category.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "summary": "Attaches a disk", "tags": [ "Disks" ] } }, "/disks/{did}/detach": { "post": { "description": "Detaches a disk from its instance.\n", "operationId": "postDisksByDidDetach", "parameters": [ { "description": "Disk ID", "in": "path", "name": "did", "required": true, "schema": { "example": "1463106081390612571", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkflowData" } } }, "description": "OK" }, "default": { "description": "Every failure returns this envelope; the HTTP status carries the category.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "summary": "Detaches a disk", "tags": [ "Disks" ] } }, "/feedback": { "post": { "description": "Submits a feedback message about the platform. The account it was sent from is recorded alongside it.\n", "operationId": "postFeedback", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FeedbackRequest" } } }, "required": true }, "responses": { "204": { "description": "No Content" }, "default": { "description": "Every failure returns this envelope; the HTTP status carries the category.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "summary": "Submit feedback", "tags": [ "Feedback" ] } }, "/images/{imid}": { "get": { "operationId": "getImagesByImid", "parameters": [ { "description": "Image ID", "in": "path", "name": "imid", "required": true, "schema": { "example": "1471181001588760790", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ImageDetailView" } } }, "description": "OK" }, "default": { "description": "Every failure returns this envelope; the HTTP status carries the category.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "summary": "Fetch image by ID", "tags": [ "Images" ] }, "delete": { "operationId": "deleteImagesByImid", "parameters": [ { "description": "Image ID", "in": "path", "name": "imid", "required": true, "schema": { "example": "1471181001588760790", "type": "string" } } ], "responses": { "202": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkflowData" } } }, "description": "Accepted" }, "default": { "description": "Every failure returns this envelope; the HTTP status carries the category.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "summary": "Delete an image", "tags": [ "Images" ] }, "patch": { "operationId": "patchImagesByImid", "parameters": [ { "description": "Image ID", "in": "path", "name": "imid", "required": true, "schema": { "example": "1471181001588760790", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PatchImageRequest" } } }, "required": true }, "responses": { "204": { "description": "No Content" }, "default": { "description": "Every failure returns this envelope; the HTTP status carries the category.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "summary": "Update image", "tags": [ "Images" ] } }, "/images/{imid}/restore": { "post": { "operationId": "postImagesByImidRestore", "parameters": [ { "description": "Image ID", "in": "path", "name": "imid", "required": true, "schema": { "example": "1471181001588760790", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestoreImageRequest" } } }, "required": true }, "responses": { "202": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkflowData" } } }, "description": "Accepted" }, "default": { "description": "Every failure returns this envelope; the HTTP status carries the category.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "summary": "Restore an image onto an instance disk", "tags": [ "Images" ] } }, "/instances/{iid}": { "get": { "description": "Fetch instance details by it's ID.\n", "operationId": "getInstancesByIid", "parameters": [ { "description": "Instance ID", "in": "path", "name": "iid", "required": true, "schema": { "example": "1463106077196308568", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EnrichedInstanceDetailViewInstanceLive" } } }, "description": "OK" }, "default": { "description": "Every failure returns this envelope; the HTTP status carries the category.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "summary": "Fetch instance", "tags": [ "Instances" ] }, "patch": { "description": "Update an instance's details.\n", "operationId": "patchInstancesByIid", "parameters": [ { "description": "Instance ID", "in": "path", "name": "iid", "required": true, "schema": { "example": "1463106077196308568", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PatchInstanceRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EnrichedInstanceDetailViewInstanceLive" } } }, "description": "OK" }, "default": { "description": "Every failure returns this envelope; the HTTP status carries the category.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "summary": "Update instance", "tags": [ "Instances" ] } }, "/instances/{iid}/apps": { "get": { "description": "Lists all apps deployed on the given Instance with keyset pagination.", "operationId": "getInstancesByIidApps", "parameters": [ { "description": "Instance ID", "in": "path", "name": "iid", "required": true, "schema": { "example": "1463106077196308568", "type": "string" } }, { "description": "Quick search by name, image, or ID", "in": "query", "name": "q", "required": false, "schema": { "type": "string" } }, { "description": "Filter by app name (partial match)", "in": "query", "name": "name", "required": false, "schema": { "type": "string" } }, { "description": "Filter by docker image (partial match)", "in": "query", "name": "image", "required": false, "schema": { "type": "string" } }, { "description": "Filter by app state", "in": "query", "name": "state", "required": false, "schema": { "enum": [ "PENDING", "AVAILABLE", "FAILED", "SUSPENDED", "DELETING", "UNPLACED" ], "type": "string" } }, { "description": "Filter by instance ID", "in": "query", "name": "instance", "required": false, "schema": { "example": "1463106077196308568", "type": "string" } }, { "description": "How many items to return", "example": 50, "in": "query", "name": "limit", "required": false, "schema": { "format": "int32", "type": "integer" } }, { "description": "Page number to fetch", "example": 1, "in": "query", "name": "page", "required": false, "schema": { "format": "int32", "type": "integer" } }, { "description": "Field to order by", "example": "id", "in": "query", "name": "sort", "required": false, "schema": { "type": "string" } }, { "description": "Order direction (ASC/DESC)", "example": "asc", "in": "query", "name": "dir", "required": false, "schema": { "type": "string" } }, { "description": "Forward keyset cursor (for keyset pagination)", "in": "query", "name": "after", "required": false, "schema": { "type": "string" } }, { "description": "Backward keyset cursor (for keyset pagination)", "in": "query", "name": "before", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/KeysetResultOptionallyEnrichedAppViewContainerLiveStats" } } }, "description": "OK" }, "default": { "description": "Every failure returns this envelope; the HTTP status carries the category.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "summary": "List apps on an Instance", "tags": [ "Apps" ] }, "post": { "description": "Creates a new Docker container app on the given Instance and starts a deploy workflow.", "operationId": "postInstancesByIidApps", "parameters": [ { "description": "Instance ID", "in": "path", "name": "iid", "required": true, "schema": { "example": "1463106077196308568", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateAppRequest" } } }, "required": true }, "responses": { "201": { "content": { "*/*": { "schema": { "$ref": "#/components/schemas/WorkflowWithResource" } } }, "description": "Created" }, "default": { "description": "Every failure returns this envelope; the HTTP status carries the category.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "summary": "Create an app", "tags": [ "Apps" ] } }, "/instances/{iid}/apps/from-template": { "post": { "description": "Creates a Docker app on the Instance using the given template. Host ports default to the container port when free; otherwise a random port in the 20000-60000 range is allocated.\n\nEnvironment values from the template and user overrides may contain `{{...}}` placeholders that are resolved at deploy time and persisted as the final values on the app. Supported placeholders:\n\n- `{{host_port.}}` \u2014 host port allocated for the template port with the given name\n- `{{container_port.}}` \u2014 container port declared for the template port with the given name\n- `{{instance.ip4}}` \u2014 first IPv4 address assigned to the target Instance\n- `{{instance.ip6}}` \u2014 first IPv6 address assigned to the target Instance\n- `{{random:}}` \u2014 a cryptographically secure random alphanumeric string of the given length (1-128); useful for bootstrapping admin tokens or encryption keys\n\nUnknown placeholders or unresolvable references fail the request.", "operationId": "postInstancesByIidAppsFromTemplate", "parameters": [ { "description": "Instance ID", "in": "path", "name": "iid", "required": true, "schema": { "example": "1463106077196308568", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeployFromTemplateRequest" } } }, "required": true }, "responses": { "201": { "content": { "*/*": { "schema": { "$ref": "#/components/schemas/WorkflowWithResource" } } }, "description": "Created" }, "default": { "description": "Every failure returns this envelope; the HTTP status carries the category.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "summary": "Deploy an app from a template", "tags": [ "App Templates" ] } }, "/instances/{iid}/dhcp": { "get": { "description": "Fetches an instance's DHCP settings.\n", "operationId": "getInstancesByIidDhcp", "parameters": [ { "description": "Instance ID", "in": "path", "name": "iid", "required": true, "schema": { "example": "1463106077196308568", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DHCP" } } }, "description": "OK" }, "default": { "description": "Every failure returns this envelope; the HTTP status carries the category.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "summary": "Fetch DHCP settings", "tags": [ "IPs" ] }, "put": { "description": "Update an instance's DHCP settings.\n", "operationId": "putInstancesByIidDhcp", "parameters": [ { "description": "Instance ID", "in": "path", "name": "iid", "required": true, "schema": { "example": "1463106077196308568", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateDhcpRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkflowData" } } }, "description": "OK" }, "default": { "description": "Every failure returns this envelope; the HTTP status carries the category.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "summary": "Update DHCP settings", "tags": [ "IPs" ] }, "delete": { "description": "Deletes an instance's DHCP settings. Enables auto mode.\n", "operationId": "deleteInstancesByIidDhcp", "parameters": [ { "description": "Instance ID", "in": "path", "name": "iid", "required": true, "schema": { "example": "1463106077196308568", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkflowData" } } }, "description": "OK" }, "default": { "description": "Every failure returns this envelope; the HTTP status carries the category.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "summary": "Delete DHCP settings", "tags": [ "IPs" ] } }, "/instances/{iid}/firewall": { "patch": { "description": "Updates the default policy for each direction. When rules are supplied they replace every rule on\nthe instance; omitting them leaves the existing rules unchanged.\n", "operationId": "patchInstancesByIidFirewall", "parameters": [ { "description": "Instance ID", "in": "path", "name": "iid", "required": true, "schema": { "example": "1463106077196308568", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FirewallPatchRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkflowData" } } }, "description": "OK" }, "default": { "description": "Every failure returns this envelope; the HTTP status carries the category.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "summary": "Update an instance firewall", "tags": [ "Firewall" ] } }, "/instances/{iid}/firewall/rules": { "get": { "description": "Retrieves firewall rules for a specific instance with pagination.", "operationId": "getInstancesByIidFirewallRules", "parameters": [ { "description": "Instance ID", "in": "path", "name": "iid", "required": true, "schema": { "example": "1463106077196308568", "type": "string" } }, { "description": "Filter by IP type", "in": "query", "name": "type", "required": false, "schema": { "enum": [ "IPv4", "IPv6" ], "type": "string" } }, { "description": "Filter by protocol", "in": "query", "name": "protocol", "required": false, "schema": { "enum": [ "TCP", "UDP", "ICMP", "ALL" ], "type": "string" } }, { "description": "Filter by action", "in": "query", "name": "action", "required": false, "schema": { "description": "What happens to traffic a rule matches.\n\n`ACCEPT` admits the traffic, and replies to the connections it admits are allowed back automatically.\n\n`STATELESS` admits the traffic without tracking connections. Replies are not allowed back automatically, so the return direction needs a rule of its own.\n\n`DROP` discards the traffic.\n", "enum": [ "ACCEPT", "STATELESS", "DROP" ], "type": "string" } }, { "description": "How many items to return", "example": 50, "in": "query", "name": "limit", "required": false, "schema": { "format": "int32", "type": "integer" } }, { "description": "Page number to fetch", "example": 1, "in": "query", "name": "page", "required": false, "schema": { "format": "int32", "type": "integer" } }, { "description": "Field to order by", "example": "id", "in": "query", "name": "sort", "required": false, "schema": { "type": "string" } }, { "description": "Order direction (ASC/DESC)", "example": "asc", "in": "query", "name": "dir", "required": false, "schema": { "type": "string" } }, { "description": "Forward keyset cursor (for keyset pagination)", "in": "query", "name": "after", "required": false, "schema": { "type": "string" } }, { "description": "Backward keyset cursor (for keyset pagination)", "in": "query", "name": "before", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/KeysetResultFirewallRuleListView" } } }, "description": "OK" }, "default": { "description": "Every failure returns this envelope; the HTTP status carries the category.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "summary": "List firewall rules for an instance", "tags": [ "Firewall" ] }, "post": { "description": "Creates a firewall rule. Omitting the priority places the rule above the instance's existing rules.\n", "operationId": "postInstancesByIidFirewallRules", "parameters": [ { "description": "Instance ID", "in": "path", "name": "iid", "required": true, "schema": { "example": "1463106077196308568", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FirewallRuleRequest" } } }, "required": true }, "responses": { "201": { "content": { "*/*": { "schema": { "$ref": "#/components/schemas/WorkflowWithResource" } } }, "description": "Created" }, "default": { "description": "Every failure returns this envelope; the HTTP status carries the category.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "summary": "Create a firewall rule", "tags": [ "Firewall" ] } }, "/instances/{iid}/firewall/rules/{rid}": { "delete": { "description": "Deletes a firewall rule.", "operationId": "deleteInstancesByIidFirewallRulesByRid", "parameters": [ { "description": "Instance ID", "in": "path", "name": "iid", "required": true, "schema": { "example": "1463106077196308568", "type": "string" } }, { "description": "Firewall Rule ID", "in": "path", "name": "rid", "required": true, "schema": { "example": "1467950980661264556", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkflowData" } } }, "description": "OK" }, "default": { "description": "Every failure returns this envelope; the HTTP status carries the category.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "summary": "Delete a firewall rule", "tags": [ "Firewall" ] }, "patch": { "description": "Replaces the contents of a single firewall rule.", "operationId": "patchInstancesByIidFirewallRulesByRid", "parameters": [ { "description": "Instance ID", "in": "path", "name": "iid", "required": true, "schema": { "example": "1463106077196308568", "type": "string" } }, { "description": "Firewall Rule ID", "in": "path", "name": "rid", "required": true, "schema": { "example": "1467950980661264556", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FirewallRuleRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkflowWithResource" } } }, "description": "OK" }, "default": { "description": "Every failure returns this envelope; the HTTP status carries the category.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "summary": "Update a firewall rule", "tags": [ "Firewall" ] } }, "/instances/{iid}/firmware": { "put": { "description": "Switches a stopped instance to another firmware. Async operation.\nKEEP leaves the boot disk as is: the installed system may stop booting under the new firmware, and switching back restores it. Turning Secure Boot on enrolls the standard Microsoft and Red Hat keys, replacing keys the installed system enrolled itself. WIPE erases the boot disk and its UEFI variables, and is required to change the sector size. BIOS boots only 512 B sectors.\n", "operationId": "putInstancesByIidFirmware", "parameters": [ { "description": "Instance ID", "in": "path", "name": "iid", "required": true, "schema": { "example": "1463106077196308568", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChangeFirmwareRequest" } } }, "required": true }, "responses": { "202": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkflowData" } } }, "description": "Accepted" }, "default": { "description": "Every failure returns this envelope; the HTTP status carries the category.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "summary": "Change instance firmware", "tags": [ "Instances", "Instance commands" ] } }, "/instances/{iid}/power": { "post": { "description": "Use this to issue power commands to an instance.\n", "operationId": "postInstancesByIidPower", "parameters": [ { "description": "Instance ID", "in": "path", "name": "iid", "required": true, "schema": { "example": "1463106077196308568", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PowerRequest" } } }, "required": true }, "responses": { "202": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkflowData" } } }, "description": "Accepted" }, "default": { "description": "Every failure returns this envelope; the HTTP status carries the category.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "summary": "Instance power operations", "tags": [ "Instances", "Instance commands" ] } }, "/instances/{iid}/vpcs": { "get": { "operationId": "getInstancesByIidVpcs", "parameters": [ { "description": "Instance ID", "in": "path", "name": "iid", "required": true, "schema": { "example": "1463106077196308568", "type": "string" } }, { "description": "Quick search by VPC name or ID", "in": "query", "name": "q", "required": false, "schema": { "type": "string" } }, { "description": "How many items to return", "example": 50, "in": "query", "name": "limit", "required": false, "schema": { "format": "int32", "type": "integer" } }, { "description": "Page number to fetch", "example": 1, "in": "query", "name": "page", "required": false, "schema": { "format": "int32", "type": "integer" } }, { "description": "Field to order by", "example": "id", "in": "query", "name": "sort", "required": false, "schema": { "type": "string" } }, { "description": "Order direction (ASC/DESC)", "example": "asc", "in": "query", "name": "dir", "required": false, "schema": { "type": "string" } }, { "description": "Forward keyset cursor (for keyset pagination)", "in": "query", "name": "after", "required": false, "schema": { "type": "string" } }, { "description": "Backward keyset cursor (for keyset pagination)", "in": "query", "name": "before", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/KeysetResultInstanceVpcListView" } } }, "description": "OK" }, "default": { "description": "Every failure returns this envelope; the HTTP status carries the category.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "summary": "List VPCs attached to an instance", "tags": [ "VPCs" ] }, "post": { "operationId": "postInstancesByIidVpcs", "parameters": [ { "description": "Instance ID", "in": "path", "name": "iid", "required": true, "schema": { "example": "1463106077196308568", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VpcAttachRequest" } } }, "required": true }, "responses": { "201": { "content": { "*/*": { "schema": { "$ref": "#/components/schemas/WorkflowData" } } }, "description": "Created" }, "default": { "description": "Every failure returns this envelope; the HTTP status carries the category.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "summary": "Attach a VPC to an instance", "tags": [ "VPCs" ] } }, "/instances/{iid}/vpcs/{vid}": { "delete": { "operationId": "deleteInstancesByIidVpcsByVid", "parameters": [ { "description": "Instance ID", "in": "path", "name": "iid", "required": true, "schema": { "example": "1463106077196308568", "type": "string" } }, { "description": "VPC ID", "in": "path", "name": "vid", "required": true, "schema": { "example": "1463882832936980610", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkflowData" } } }, "description": "OK" }, "default": { "description": "Every failure returns this envelope; the HTTP status carries the category.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "summary": "Detach a VPC from an instance", "tags": [ "VPCs" ] } }, "/invites": { "post": { "description": "Accepts an invite, joining the workspace it grants.", "operationId": "postInvites", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AcceptInviteRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InviteView" } } }, "description": "OK" }, "default": { "description": "Every failure returns this envelope; the HTTP status carries the category.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "summary": "Accept an invite", "tags": [ "Workspaces" ] } }, "/invites/lookup": { "get": { "description": "Resolves a pending invite so the workspace it grants can be shown before signing up or logging in. Returns\n404 once the invite has been accepted or has expired.\n", "operationId": "getInvitesLookup", "parameters": [ { "in": "query", "name": "code", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InviteView" } } }, "description": "OK" }, "default": { "description": "Every failure returns this envelope; the HTTP status carries the category.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "summary": "Look up a pending invite by code", "tags": [ "Workspaces" ], "x-api-modifiers": [ "open" ], "security": [] } }, "/invites/{iid}": { "get": { "description": "Fetches a pending invitation by id.", "operationId": "getInvitesByIid", "parameters": [ { "in": "path", "name": "iid", "required": true, "schema": { "example": "1489276118237192255", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InviteView" } } }, "description": "OK" }, "default": { "description": "Every failure returns this envelope; the HTTP status carries the category.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "summary": "Fetch an invite", "tags": [ "Workspaces" ] }, "delete": { "description": "Cancels a pending invitation.", "operationId": "deleteInvitesByIid", "parameters": [ { "in": "path", "name": "iid", "required": true, "schema": { "example": "1489276118237192255", "type": "string" } } ], "responses": { "202": { "description": "Accepted" }, "default": { "description": "Every failure returns this envelope; the HTTP status carries the category.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "summary": "Delete an invite", "tags": [ "Workspaces" ] }, "patch": { "description": "Changes a pending invite's role and write kinds.", "operationId": "patchInvitesByIid", "parameters": [ { "in": "path", "name": "iid", "required": true, "schema": { "example": "1489276118237192255", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateInviteRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InviteView" } } }, "description": "OK" }, "default": { "description": "Every failure returns this envelope; the HTTP status carries the category.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "summary": "Update an invite", "tags": [ "Workspaces" ] } }, "/invoices/{invoice_id}": { "get": { "description": "Returns an invoice with its line items.", "operationId": "getInvoicesByInvoiceId", "parameters": [ { "description": "Invoice id", "in": "path", "name": "invoice_id", "required": true, "schema": { "example": "1456074443980800000", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvoiceRenderResponse" } } }, "description": "The invoice with its line items" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "No invoice with that id" }, "default": { "description": "Every failure returns this envelope; the HTTP status carries the category.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "summary": "Get a rendered invoice", "tags": [ "Invoices" ] } }, "/lock-account": { "post": { "operationId": "postLockAccount", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LockAccountRequest" } } }, "required": true }, "responses": { "202": { "description": "Accepted" }, "default": { "description": "Every failure returns this envelope; the HTTP status carries the category.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "tags": [ "lock-controller" ], "x-api-modifiers": [ "open" ], "security": [] } }, "/login": { "post": { "description": "Validates email + password (and MFA if enrolled), sends a login notification email, and returns a\nSESSION-issued USER-scope token with the unrestricted permission map. The plaintext code is only\nreturned once, save it securely. If the account has a second factor and the request has no `mfa` or\n`webauthn`, or has a wrong `mfa` code, the response is 403 `MfaChallenge`. Send the request again with\n`mfa`, or with a `webauthn` response to the challenge options. A password matching the account lock\ncode locks the account and answers 403 `account_locked`.\n", "operationId": "postLogin", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LoginRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TokenCreateResponse" } } }, "description": "OK" }, "403": { "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ApiError" }, { "$ref": "#/components/schemas/MfaChallenge" } ] } } }, "description": "Forbidden, or `MfaChallenge` when a second factor is needed" }, "default": { "description": "Every failure returns this envelope; the HTTP status carries the category.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "summary": "Authenticate a user and mint a SESSION token", "tags": [ "Authentication" ], "x-api-modifiers": [ "open" ], "security": [] } }, "/login/passkey": { "post": { "description": "Signs in without a password and returns a SESSION token, like `POST /v1/login`. Only credentials registered as passkeys are accepted; a security key answers `credential_rejected`.\n", "operationId": "postLoginPasskey", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PasskeyLoginRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TokenCreateResponse" } } }, "description": "OK" }, "default": { "description": "Every failure returns this envelope; the HTTP status carries the category.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "summary": "Sign in with a passkey", "tags": [ "Authentication" ], "x-api-modifiers": [ "open" ], "security": [] } }, "/login/passkey/options": { "post": { "description": "Returns assertion options for any passkey the browser holds for this site, for a modal request or for autofill (`mediation: \"conditional\"`). Send the answer to `POST /v1/login/passkey` within five minutes, else it fails with `challenge_expired`.\n", "operationId": "postLoginPasskeyOptions", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebAuthnOptions" } } }, "description": "OK" }, "default": { "description": "Every failure returns this envelope; the HTTP status carries the category.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "summary": "Start a passkey sign-in", "tags": [ "Authentication" ], "x-api-modifiers": [ "open" ], "security": [] } }, "/metrics": { "get": { "description": "Fetches CPU, memory, disk I/O, and network time-series metrics for an instance in a single request. Values\nare returned in their raw emitted units, see `InstanceMetrics` field descriptions for each unit. Any\nnormalization (percent-to-ratio, MiB-to-GB, etc.) is the frontend's responsibility.\n", "operationId": "getMetrics", "parameters": [ { "description": "Instance ID", "in": "query", "name": "instance", "required": true, "schema": { "example": "1463106077196308568", "type": "string" } }, { "description": "Start time as Unix epoch seconds", "example": 1784808000, "in": "query", "name": "start", "required": true, "schema": { "format": "int64", "minimum": 0, "type": "integer" } }, { "description": "End time as Unix epoch seconds", "example": 1784811600, "in": "query", "name": "end", "required": true, "schema": { "format": "int64", "minimum": 0, "type": "integer" } }, { "description": "Query resolution step (in seconds)", "example": 60, "in": "query", "name": "step", "required": true, "schema": { "format": "int64", "minimum": 15, "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InstanceMetrics" } } }, "description": "OK" }, "default": { "description": "Every failure returns this envelope; the HTTP status carries the category.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "summary": "Fetch instance metrics", "tags": [ "Metrics" ] } }, "/net-lbs/{bid}": { "get": { "operationId": "getNetLbsByBid", "parameters": [ { "in": "path", "name": "bid", "required": true, "schema": { "example": "1467950980661264556", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NetBalancerDetailView" } } }, "description": "OK" }, "default": { "description": "Every failure returns this envelope; the HTTP status carries the category.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "tags": [ "net-balancer-admin-rest" ] }, "patch": { "operationId": "patchNetLbsByBid", "parameters": [ { "in": "path", "name": "bid", "required": true, "schema": { "example": "1467950980661264556", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PatchNetBalancerRequest" } } }, "required": true }, "responses": { "200": { "description": "OK" }, "default": { "description": "Every failure returns this envelope; the HTTP status carries the category.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "tags": [ "net-balancer-admin-rest" ] } }, "/net-lbs/{bid}/instances": { "get": { "operationId": "getNetLbsByBidInstances", "parameters": [ { "in": "path", "name": "bid", "required": true, "schema": { "example": "1467950980661264556", "type": "string" } }, { "description": "Quick search by name, IP address, or ID", "in": "query", "name": "q", "required": false, "schema": { "type": "string" } }, { "description": "Filter by IP address (public or private)", "in": "query", "name": "ip", "required": false, "schema": { "type": "string" } }, { "description": "List of instance IDs to filter", "in": "query", "name": "id", "required": false, "schema": { "items": { "example": "1463106077196308568", "type": "string" }, "type": "array" } }, { "description": "Instance names to filter", "in": "query", "name": "name", "required": false, "schema": { "type": "string" } }, { "description": "List of node IDs to filter", "in": "query", "name": "node", "required": false, "schema": { "items": { "example": "1326819038986244108", "type": "string" }, "type": "array" } }, { "description": "List of products to filter", "in": "query", "name": "sku", "required": false, "schema": { "items": { "example": "lightning-1g", "type": "string" }, "type": "array" } }, { "description": "List of ISO IDs to filter", "in": "query", "name": "iso", "required": false, "schema": { "items": { "example": "1471181001588760790", "type": "string" }, "type": "array" } }, { "description": "Boot target to filter", "in": "query", "name": "boot", "required": false, "schema": { "enum": [ "DISK", "ISO" ], "type": "string" } }, { "description": "Filter for only online/offline instances", "in": "query", "name": "online", "required": false, "schema": { "type": "boolean" } }, { "description": "Filter for instances with a specific state", "in": "query", "name": "state", "required": false, "schema": { "items": { "enum": [ "PENDING", "AVAILABLE", "FAILED", "SUSPENDED", "DELETING", "UNPLACED" ], "type": "string" }, "type": "array" } }, { "description": "Filter for only instances scheduled for termination", "in": "query", "name": "terminating", "required": false, "schema": { "type": "boolean" } }, { "description": "List of backup plan IDs to filter", "in": "query", "name": "backup_plan", "required": false, "schema": { "items": { "example": "1506320201023500406", "type": "string" }, "type": "array" } }, { "description": "Filter for only instances in a specific region", "in": "query", "name": "region", "required": false, "schema": { "enum": [ "NA_01" ], "type": "string" } }, { "description": "List of VPC IDs to filter", "in": "query", "name": "vpc", "required": false, "schema": { "items": { "example": "1463882832936980610", "type": "string" }, "type": "array" } }, { "description": "Filter for instances with a specific OS family", "in": "query", "name": "os", "required": false, "schema": { "enum": [ "WINDOWS", "LINUX", "BSD", "OTHER" ], "type": "string" } }, { "description": "List of workspace IDs to filter", "in": "query", "name": "owner", "required": false, "schema": { "items": { "example": "1405508720263180365", "type": "string" }, "type": "array" } }, { "description": "How many items to return", "example": 50, "in": "query", "name": "limit", "required": false, "schema": { "format": "int32", "type": "integer" } }, { "description": "Page number to fetch", "example": 1, "in": "query", "name": "page", "required": false, "schema": { "format": "int32", "type": "integer" } }, { "description": "Field to order by", "example": "id", "in": "query", "name": "sort", "required": false, "schema": { "type": "string" } }, { "description": "Order direction (ASC/DESC)", "example": "asc", "in": "query", "name": "dir", "required": false, "schema": { "type": "string" } }, { "description": "Forward keyset cursor (for keyset pagination)", "in": "query", "name": "after", "required": false, "schema": { "type": "string" } }, { "description": "Backward keyset cursor (for keyset pagination)", "in": "query", "name": "before", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/KeysetResultInstanceSimple" } } }, "description": "OK" }, "default": { "description": "Every failure returns this envelope; the HTTP status carries the category.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "tags": [ "net-balancer-admin-rest" ] } }, "/net-lbs/{bid}/instances/{iid}": { "put": { "operationId": "putNetLbsByBidInstancesByIid", "parameters": [ { "in": "path", "name": "bid", "required": true, "schema": { "example": "1467950980661264556", "type": "string" } }, { "in": "path", "name": "iid", "required": true, "schema": { "example": "1463106077196308568", "type": "string" } } ], "responses": { "202": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkflowData" } } }, "description": "Accepted" }, "default": { "description": "Every failure returns this envelope; the HTTP status carries the category.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "tags": [ "net-balancer-admin-rest" ] }, "delete": { "operationId": "deleteNetLbsByBidInstancesByIid", "parameters": [ { "in": "path", "name": "bid", "required": true, "schema": { "example": "1467950980661264556", "type": "string" } }, { "in": "path", "name": "iid", "required": true, "schema": { "example": "1463106077196308568", "type": "string" } } ], "responses": { "202": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkflowData" } } }, "description": "Accepted" }, "default": { "description": "Every failure returns this envelope; the HTTP status carries the category.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "tags": [ "net-balancer-admin-rest" ] } }, "/networking/ips/{fid}": { "get": { "description": "Fetches an IP address by it's ID.\n", "operationId": "getNetworkingIpsByFid", "parameters": [ { "description": "IP address ID", "in": "path", "name": "fid", "required": true, "schema": { "example": "1464201868476432440", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FloatingIpListView" } } }, "description": "OK" }, "default": { "description": "Every failure returns this envelope; the HTTP status carries the category.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "summary": "Fetch IP address", "tags": [ "IPs" ] } }, "/networking/ips/{fid}/dns": { "put": { "description": "Updates the rDNS entry for an IP address.\n", "operationId": "putNetworkingIpsByFidDns", "parameters": [ { "description": "IP address ID", "in": "path", "name": "fid", "required": true, "schema": { "example": "1464201868476432440", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EditRdnsRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkflowData" } } }, "description": "OK" }, "default": { "description": "Every failure returns this envelope; the HTTP status carries the category.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "summary": "Update IP reverse DNS", "tags": [ "IPs" ] }, "delete": { "description": "Removes the rDNS entry for an IP address.\n", "operationId": "deleteNetworkingIpsByFidDns", "parameters": [ { "description": "IP address ID", "in": "path", "name": "fid", "required": true, "schema": { "example": "1464201868476432440", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkflowData" } } }, "description": "OK" }, "default": { "description": "Every failure returns this envelope; the HTTP status carries the category.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "summary": "Remove IP reverse DNS", "tags": [ "IPs" ] } }, "/oauth/applications": { "get": { "description": "Lists the registered OAuth applications. Supports a quick search by name or ID and a filter by owner\nuser ID.\n", "operationId": "getOauthApplications", "parameters": [ { "description": "Quick search by name or ID", "in": "query", "name": "q", "required": false, "schema": { "type": "string" } }, { "description": "List of application IDs to filter", "in": "query", "name": "id", "required": false, "schema": { "items": { "example": "1479097389678620681", "type": "string" }, "type": "array" } }, { "description": "Filter by application name", "in": "query", "name": "name", "required": false, "schema": { "type": "string" } }, { "description": "Filter by application description", "in": "query", "name": "description", "required": false, "schema": { "type": "string" } }, { "description": "Filter by active status", "in": "query", "name": "active", "required": false, "schema": { "type": "boolean" } }, { "description": "Filter by redirect URI (contains match)", "in": "query", "name": "redirect_uri", "required": false, "schema": { "type": "string" } }, { "description": "Filter by owner user ID", "in": "query", "name": "owner", "required": false, "schema": { "example": "1405506895740940329", "type": "string" } }, { "description": "How many items to return", "example": 50, "in": "query", "name": "limit", "required": false, "schema": { "format": "int32", "type": "integer" } }, { "description": "Page number to fetch", "example": 1, "in": "query", "name": "page", "required": false, "schema": { "format": "int32", "type": "integer" } }, { "description": "Field to order by", "example": "id", "in": "query", "name": "sort", "required": false, "schema": { "type": "string" } }, { "description": "Order direction (ASC/DESC)", "example": "asc", "in": "query", "name": "dir", "required": false, "schema": { "type": "string" } }, { "description": "Forward keyset cursor (for keyset pagination)", "in": "query", "name": "after", "required": false, "schema": { "type": "string" } }, { "description": "Backward keyset cursor (for keyset pagination)", "in": "query", "name": "before", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/KeysetResultOAuthApplicationListView" } } }, "description": "OK" }, "default": { "description": "Every failure returns this envelope; the HTTP status carries the category.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "summary": "List OAuth applications", "tags": [ "OAuth Applications" ] }, "post": { "description": "Creates an OAuth application. The client secret is returned once, save it securely.\n", "operationId": "postOauthApplications", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateOAuthApplicationRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OAuthApplicationCreatedResponse" } } }, "description": "OK" }, "default": { "description": "Every failure returns this envelope; the HTTP status carries the category.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "summary": "Register a new OAuth application", "tags": [ "OAuth Applications" ] } }, "/oauth/applications/{apid}": { "get": { "description": "Returns the details of a single OAuth application.", "operationId": "getOauthApplicationsByApid", "parameters": [ { "description": "Application ID", "in": "path", "name": "apid", "required": true, "schema": { "example": "1479097389678620681", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OAuthApplicationListView" } } }, "description": "OK" }, "default": { "description": "Every failure returns this envelope; the HTTP status carries the category.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "summary": "Get an OAuth application", "tags": [ "OAuth Applications" ] }, "delete": { "description": "Deletes an OAuth application. The tokens and authorizations it issued stop working immediately.\n", "operationId": "deleteOauthApplicationsByApid", "parameters": [ { "description": "Application ID", "in": "path", "name": "apid", "required": true, "schema": { "example": "1479097389678620681", "type": "string" } } ], "responses": { "202": { "description": "Accepted" }, "default": { "description": "Every failure returns this envelope; the HTTP status carries the category.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "summary": "Delete an OAuth application", "tags": [ "OAuth Applications" ] }, "patch": { "description": "Updates an OAuth application.", "operationId": "patchOauthApplicationsByApid", "parameters": [ { "description": "Application ID", "in": "path", "name": "apid", "required": true, "schema": { "example": "1479097389678620681", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateOAuthApplicationRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OAuthApplicationListView" } } }, "description": "OK" }, "default": { "description": "Every failure returns this envelope; the HTTP status carries the category.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "summary": "Update an OAuth application", "tags": [ "OAuth Applications" ] } }, "/oauth/applications/{apid}/secret": { "post": { "description": "Regenerates the client secret for an OAuth application. The new secret is returned\nonly once, save it securely. The old secret is invalidated immediately.\n", "operationId": "postOauthApplicationsByApidSecret", "parameters": [ { "description": "Application ID", "in": "path", "name": "apid", "required": true, "schema": { "example": "1479097389678620681", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OAuthSecretRegeneratedResponse" } } }, "description": "OK" }, "default": { "description": "Every failure returns this envelope; the HTTP status carries the category.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "summary": "Regenerate client secret", "tags": [ "OAuth Applications" ] } }, "/oauth/authorizations": { "get": { "description": "Lists all OAuth applications the current user has authorized. Each entry shows the\napplication, approved scopes, and when the authorization was granted.\nSupports quick search by application name, and filtering by application ID.\n", "operationId": "getOauthAuthorizations", "parameters": [ { "description": "Quick search by application name or ID", "in": "query", "name": "q", "required": false, "schema": { "type": "string" } }, { "description": "List of authorization IDs to filter", "in": "query", "name": "id", "required": false, "schema": { "items": { "example": "1479097389678620681", "type": "string" }, "type": "array" } }, { "description": "Filter by application name", "in": "query", "name": "name", "required": false, "schema": { "type": "string" } }, { "description": "Filter by application ID", "in": "query", "name": "application", "required": false, "schema": { "example": "1479097389678620681", "type": "string" } }, { "description": "Filter by user ID", "in": "query", "name": "user", "required": false, "schema": { "example": "1405506895740940329", "type": "string" } }, { "description": "Filter by scope (exact match, e.g. instance:read)", "in": "query", "name": "scope", "required": false, "schema": { "enum": [ "app:read", "app:write", "audit:read", "dedibox:read", "dedibox:write", "disk:read", "disk:write", "floating_ip:read", "floating_ip:write", "image:read", "image:write", "instance:read", "instance:write", "net_balancer:read", "net_balancer:write", "workspace:read", "workspace:write" ], "type": "string" } }, { "description": "How many items to return", "example": 50, "in": "query", "name": "limit", "required": false, "schema": { "format": "int32", "type": "integer" } }, { "description": "Page number to fetch", "example": 1, "in": "query", "name": "page", "required": false, "schema": { "format": "int32", "type": "integer" } }, { "description": "Field to order by", "example": "id", "in": "query", "name": "sort", "required": false, "schema": { "type": "string" } }, { "description": "Order direction (ASC/DESC)", "example": "asc", "in": "query", "name": "dir", "required": false, "schema": { "type": "string" } }, { "description": "Forward keyset cursor (for keyset pagination)", "in": "query", "name": "after", "required": false, "schema": { "type": "string" } }, { "description": "Backward keyset cursor (for keyset pagination)", "in": "query", "name": "before", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/KeysetResultOAuthAuthorizationListView" } } }, "description": "OK" }, "default": { "description": "Every failure returns this envelope; the HTTP status carries the category.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "summary": "List authorized apps", "tags": [ "OAuth Authorizations" ] } }, "/oauth/authorizations/{auid}": { "delete": { "description": "Revokes an OAuth authorization, deleting all access and refresh tokens issued\nto the application for this user.\n", "operationId": "deleteOauthAuthorizationsByAuid", "parameters": [ { "description": "Authorization ID", "in": "path", "name": "auid", "required": true, "schema": { "example": "1479097389678620681", "type": "string" } } ], "responses": { "202": { "description": "Accepted" }, "default": { "description": "Every failure returns this envelope; the HTTP status carries the category.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "summary": "Revoke an authorization", "tags": [ "OAuth Authorizations" ] } }, "/oauth/authorize": { "get": { "description": "Returns application details and requested scopes for the frontend consent screen.\nThe user must be logged in.\n", "operationId": "getOauthAuthorize", "parameters": [ { "in": "query", "name": "client_id", "required": true, "schema": { "type": "string" } }, { "in": "query", "name": "redirect_uri", "required": true, "schema": { "type": "string" } }, { "in": "query", "name": "scope", "required": true, "schema": { "type": "string" } }, { "in": "query", "name": "response_type", "required": true, "schema": { "type": "string" } }, { "in": "query", "name": "code_challenge", "required": true, "schema": { "type": "string" } }, { "in": "query", "name": "code_challenge_method", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OAuthAuthorizeInfoResponse" } } }, "description": "OK" }, "default": { "description": "Every failure returns this envelope; the HTTP status carries the category.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "summary": "Get authorization info for consent screen", "tags": [ "OAuth" ] }, "post": { "description": "Called by the frontend after the user makes a consent decision. Returns a redirect URI\nwith an authorization code (if approved) or an error (if denied).\n", "operationId": "postOauthAuthorize", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OAuthAuthorizeRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OAuthAuthorizeResponse" } } }, "description": "OK" }, "default": { "description": "Every failure returns this envelope; the HTTP status carries the category.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "summary": "Approve or deny an authorization request", "tags": [ "OAuth" ] } }, "/oauth/revoke": { "post": { "description": "RFC 7009 token revocation endpoint. Client authenticates via client_id and client_secret.\nAlways returns 200 regardless of whether the token was found.\n", "operationId": "postOauthRevoke", "requestBody": { "content": { "application/x-www-form-urlencoded": { "schema": { "properties": { "client_id": { "type": "string" }, "client_secret": { "type": "string" }, "token": { "type": "string" } }, "required": [ "client_id", "client_secret", "token" ], "type": "object" } } } }, "responses": { "200": { "description": "OK" }, "default": { "description": "Every failure returns this envelope; the HTTP status carries the category.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "summary": "Revoke a token", "tags": [ "OAuth" ], "x-api-modifiers": [ "open" ], "security": [] } }, "/oauth/token": { "post": { "description": "OAuth 2.0 token endpoint. Supports grant_type=authorization_code (with PKCE) and\ngrant_type=refresh_token. Client authenticates via client_id and client_secret.\n", "operationId": "postOauthToken", "requestBody": { "content": { "application/x-www-form-urlencoded": { "schema": { "properties": { "client_id": { "type": "string" }, "client_secret": { "type": "string" }, "code": { "type": "string" }, "code_verifier": { "type": "string" }, "grant_type": { "type": "string" }, "redirect_uri": { "type": "string" }, "refresh_token": { "type": "string" } }, "required": [ "client_id", "client_secret", "grant_type" ], "type": "object" } } } }, "responses": { "200": { "content": { "application/json": { "schema": { "type": "object" } } }, "description": "OK" }, "default": { "description": "Every failure returns this envelope; the HTTP status carries the category.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "summary": "Exchange authorization code or refresh token for tokens", "tags": [ "OAuth" ], "x-api-modifiers": [ "open" ], "security": [] } }, "/orders/{oid}": { "get": { "description": "Returns an order with its items and their part lines.", "operationId": "getOrdersByOid", "parameters": [ { "description": "Order id", "in": "path", "name": "oid", "required": true, "schema": { "example": "1456074443980800000", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrderDetailResponse" } } }, "description": "The order with its items and parts" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Not a member of the order's workspace" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "No order with that id" }, "default": { "description": "Every failure returns this envelope; the HTTP status carries the category.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "summary": "Get an order", "tags": [ "Orders" ] } }, "/orders/{oid}/approve": { "post": { "description": "Approves an order in AWAITING_APPROVAL and collects it from the workspace owner's account. collection tells if a stored payment method is being charged or if a checkout is necessary for the remaining amount.", "operationId": "postOrdersByOidApprove", "parameters": [ { "description": "Order id", "in": "path", "name": "oid", "required": true, "schema": { "example": "1456074443980800000", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateOrderResponse" } } }, "description": "The approved order, whether it greened, and what is owed" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Not the owner of the order's workspace" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "No order with that id" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "The order is not awaiting approval" }, "default": { "description": "Every failure returns this envelope; the HTTP status carries the category.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "summary": "Approve an order", "tags": [ "Orders" ] } }, "/orders/{oid}/cancel": { "post": { "description": "Cancels a DRAFT, AWAITING_APPROVAL or AWAITING_PAYMENT order, voids its invoice and returns the wallet credit paid toward it. Refused while a payment for the invoice waits for confirmation and after the invoice is paid. Cancelling a cancelled order changes nothing.", "operationId": "postOrdersByOidCancel", "parameters": [ { "description": "Order id", "in": "path", "name": "oid", "required": true, "schema": { "example": "1456074443980800000", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrderView" } } }, "description": "The cancelled order" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Not an admin of the order's workspace" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "No order with that id" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "The order cannot be cancelled in its current state" }, "default": { "description": "Every failure returns this envelope; the HTTP status carries the category.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "summary": "Cancel an order", "tags": [ "Orders" ] } }, "/packages": { "get": { "description": "Keyset-paginated listing of the packages on sale, newest first. Each item carries its offers, its rate card and its cheapest price, the same as the package detail.", "operationId": "getPackages", "parameters": [ { "description": "Quick search by package code or name", "in": "query", "name": "q", "required": false, "schema": { "type": "string" } }, { "description": "Kinds to filter", "in": "query", "name": "resource_kind", "required": false, "schema": { "items": { "enum": [ "SERVER", "IP_ADDRESS" ], "type": "string" }, "type": "array" } }, { "description": "Charge bases to filter", "in": "query", "name": "charge_basis", "required": false, "schema": { "items": { "enum": [ "FIXED", "METERED" ], "type": "string" }, "type": "array" } }, { "description": "How many items to return", "example": 50, "in": "query", "name": "limit", "required": false, "schema": { "format": "int32", "type": "integer" } }, { "description": "Page number to fetch", "example": 1, "in": "query", "name": "page", "required": false, "schema": { "format": "int32", "type": "integer" } }, { "description": "Field to order by", "example": "id", "in": "query", "name": "sort", "required": false, "schema": { "type": "string" } }, { "description": "Order direction (ASC/DESC)", "example": "asc", "in": "query", "name": "dir", "required": false, "schema": { "type": "string" } }, { "description": "Forward keyset cursor (for keyset pagination)", "in": "query", "name": "after", "required": false, "schema": { "type": "string" } }, { "description": "Backward keyset cursor (for keyset pagination)", "in": "query", "name": "before", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/KeysetResultPackageDetailResponse" } } }, "description": "OK" }, "default": { "description": "Every failure returns this envelope; the HTTP status carries the category.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "summary": "List packages", "tags": [ "Catalog" ] } }, "/packages/{code}": { "get": { "description": "Returns a package by code with its offers, its rate card and its cheapest price.", "operationId": "getPackagesByCode", "parameters": [ { "description": "Package code", "in": "path", "name": "code", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PackageDetailResponse" } } }, "description": "The package with its spec" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "No package with that code" }, "default": { "description": "Every failure returns this envelope; the HTTP status carries the category.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "summary": "Get a package", "tags": [ "Catalog" ] } }, "/packages/{code}/transitions": { "get": { "description": "Keyset-paginated listing of the packages a subject on this package may upgrade or downgrade to, newest first. Each item carries its direction and the target package in the same shape as a package list item. A package with no offered moves returns an empty page. Moving to the subject's own package, to choose new values for its open fields, is always possible and is not listed.", "operationId": "getPackagesByCodeTransitions", "parameters": [ { "description": "Package code", "in": "path", "name": "code", "required": true, "schema": { "type": "string" } }, { "description": "Directions to filter", "in": "query", "name": "direction", "required": false, "schema": { "items": { "enum": [ "UPGRADE", "DOWNGRADE" ], "type": "string" }, "type": "array" } }, { "description": "How many items to return", "example": 50, "in": "query", "name": "limit", "required": false, "schema": { "format": "int32", "type": "integer" } }, { "description": "Page number to fetch", "example": 1, "in": "query", "name": "page", "required": false, "schema": { "format": "int32", "type": "integer" } }, { "description": "Field to order by", "example": "id", "in": "query", "name": "sort", "required": false, "schema": { "type": "string" } }, { "description": "Order direction (ASC/DESC)", "example": "asc", "in": "query", "name": "dir", "required": false, "schema": { "type": "string" } }, { "description": "Forward keyset cursor (for keyset pagination)", "in": "query", "name": "after", "required": false, "schema": { "type": "string" } }, { "description": "Backward keyset cursor (for keyset pagination)", "in": "query", "name": "before", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/KeysetResultPackageTransitionResponse" } } }, "description": "A page of moves" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "No package with that code" }, "default": { "description": "Every failure returns this envelope; the HTTP status carries the category.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "summary": "List a package's moves", "tags": [ "Catalog" ] } }, "/payment-methods/{pmid}": { "get": { "description": "Returns a stored payment method by id.", "operationId": "getPaymentMethodsByPmid", "parameters": [ { "description": "Payment method id", "in": "path", "name": "pmid", "required": true, "schema": { "example": "1456074443980800000", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentMethodView" } } }, "description": "The stored payment method" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "No payment method with that id" }, "default": { "description": "Every failure returns this envelope; the HTTP status carries the category.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "summary": "Get a payment method", "tags": [ "Payment methods" ] }, "delete": { "description": "Removes a stored payment method and releases it at its gateway. Deleting the default promotes the newest remaining method in its place, so an account with any method left always has one to charge.", "operationId": "deletePaymentMethodsByPmid", "parameters": [ { "description": "Payment method id", "in": "path", "name": "pmid", "required": true, "schema": { "example": "1456074443980800000", "type": "string" } } ], "responses": { "200": { "description": "The payment method was deleted" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "No payment method with that id" }, "default": { "description": "Every failure returns this envelope; the HTTP status carries the category.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "summary": "Delete a payment method", "tags": [ "Payment methods" ] } }, "/payment-methods/{pmid}/default": { "post": { "description": "Makes this method the account's default, unsetting any prior default in the same transaction. A no-op if it is already the default.", "operationId": "postPaymentMethodsByPmidDefault", "parameters": [ { "description": "Payment method id", "in": "path", "name": "pmid", "required": true, "schema": { "example": "1456074443980800000", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentMethodView" } } }, "description": "The payment method, now the account's default" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "No payment method with that id" }, "default": { "description": "Every failure returns this envelope; the HTTP status carries the category.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "summary": "Set a method as default", "tags": [ "Payment methods" ] } }, "/payments/config": { "get": { "description": "Returns the browser configuration of each available gateway, keyed by gateway name, e.g. {\"STRIPE\": {\"publishable_key\": \"pk_live_...\"}}. An unavailable gateway is not in the object. An empty object means that no gateway accepts payments in the browser.", "operationId": "getPaymentsConfig", "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": { "$ref": "#/components/schemas/GatewayClientConfig" }, "type": "object" } } }, "description": "Client configuration per available gateway" }, "default": { "description": "Every failure returns this envelope; the HTTP status carries the category.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "summary": "Get the client payment configuration", "tags": [ "Payments" ] } }, "/payments/{pid}": { "get": { "description": "Returns a payment by id.", "operationId": "getPaymentsByPid", "parameters": [ { "description": "Payment id", "in": "path", "name": "pid", "required": true, "schema": { "example": "1456074443980800000", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentView" } } }, "description": "The payment" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "No payment with that id" }, "default": { "description": "Every failure returns this envelope; the HTTP status carries the category.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "summary": "Get a payment", "tags": [ "Payments" ] } }, "/rate-cards/{code}": { "get": { "description": "Returns a rate card by code with its priced parts.", "operationId": "getRateCardsByCode", "parameters": [ { "description": "Rate card code", "in": "path", "name": "code", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateCardDetailResponse" } } }, "description": "The rate card with its parts" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "No rate card with that code" }, "default": { "description": "Every failure returns this envelope; the HTTP status carries the category.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "summary": "Get a rate card", "tags": [ "Catalog" ] } }, "/recipes/{rid}": { "get": { "description": "Fetches a recipe by ID.\n", "operationId": "getRecipesByRid", "parameters": [ { "description": "Recipe ID", "in": "path", "name": "rid", "required": true, "schema": { "example": "1471181001588760790", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RecipeDetailView" } } }, "description": "OK" }, "default": { "description": "Every failure returns this envelope; the HTTP status carries the category.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "summary": "Fetch recipe details", "tags": [ "Recipes" ] }, "delete": { "description": "Deletes a recipe.\n", "operationId": "deleteRecipesByRid", "parameters": [ { "description": "Recipe ID", "in": "path", "name": "rid", "required": true, "schema": { "example": "1471181001588760790", "type": "string" } } ], "responses": { "204": { "description": "No Content" }, "default": { "description": "Every failure returns this envelope; the HTTP status carries the category.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "summary": "Delete a recipe", "tags": [ "Recipes" ] }, "patch": { "description": "Updates a recipe.\n", "operationId": "patchRecipesByRid", "parameters": [ { "description": "Recipe ID", "in": "path", "name": "rid", "required": true, "schema": { "example": "1471181001588760790", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PatchRecipeRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RecipeDetailView" } } }, "description": "OK" }, "default": { "description": "Every failure returns this envelope; the HTTP status carries the category.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "summary": "Updates a recipe", "tags": [ "Recipes" ] } }, "/register": { "post": { "description": "Creates an account from a name, an email address and a password.\n\nAn `invite_code` that was sent to the same address proves control of that address, so the account is\ncreated already confirmed, joins the workspace it was invited to with the role the invite carries, and\nthe response returns a SESSION-issued token identical to the one `POST /v1/login` returns. Answers\n`200`, and the plaintext code is only returned once, so save it securely.\n\nWithout an invite code the address still has to be confirmed. A confirmation email goes out, signing in\nis refused until the link in it is followed, and no token is returned. Answers `201` with an empty body.\nSigning in through an external provider with `POST /v1/auth/callback` is confirmed by the provider\ninstead, so that route returns a token directly as well.\n\nAn address that already has an account is answered exactly like a new one, and receives a password\nreset email.\n", "operationId": "postRegister", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RegisterRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TokenCreateResponse" } } }, "description": "Registered through an invite. The account is confirmed and the body carries a session token." }, "201": { "description": "Account created and a confirmation email sent. Empty body, and no session until the address is confirmed." }, "default": { "description": "Every failure returns this envelope; the HTTP status carries the category.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "summary": "Register a new account", "tags": [ "Authentication" ], "x-api-modifiers": [ "open" ], "security": [] } }, "/reset-password": { "post": { "operationId": "postResetPassword", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResetPasswordRequest" } } }, "required": true }, "responses": { "202": { "description": "Accepted" }, "default": { "description": "Every failure returns this envelope; the HTTP status carries the category.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "tags": [ "password-reset-controller" ], "x-api-modifiers": [ "open" ], "security": [] } }, "/snapshots/{sid}": { "get": { "description": "Fetches an instance snapshot by it's ID.\n", "operationId": "getSnapshotsBySid", "parameters": [ { "description": "Snapshot ID", "in": "path", "name": "sid", "required": true, "schema": { "example": "1463106081390612571", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SnapshotListView" } } }, "description": "OK" }, "default": { "description": "Every failure returns this envelope; the HTTP status carries the category.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "summary": "Fetch snapshot by ID", "tags": [ "Snapshots" ] }, "delete": { "description": "Deletes a snapshot by it's ID. Async operation.\n", "operationId": "deleteSnapshotsBySid", "parameters": [ { "description": "Snapshot ID", "in": "path", "name": "sid", "required": true, "schema": { "example": "1463106081390612571", "type": "string" } } ], "responses": { "202": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkflowData" } } }, "description": "Accepted" }, "default": { "description": "Every failure returns this envelope; the HTTP status carries the category.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "summary": "Delete a snapshot", "tags": [ "Snapshots" ] } }, "/sse": { "get": { "description": "Opens an SSE stream of resource update/delete events scoped to the authenticated user's accessible workspaces. Admin users receive all events.", "operationId": "getSse", "responses": { "200": { "content": { "text/event-stream": { "schema": { "type": "string" } } }, "description": "An event stream that stays open, carrying one event per resource change" }, "default": { "description": "Every failure returns this envelope; the HTTP status carries the category.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "summary": "Subscribe to real-time events", "tags": [ "Events" ] } }, "/ssh/{kid}": { "get": { "description": "Fetches an ssh key by it's ID.\n", "operationId": "getSshByKid", "parameters": [ { "description": "SSH Key ID", "in": "path", "name": "kid", "required": true, "schema": { "example": "1506320201023500406", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SshKey" } } }, "description": "OK" }, "default": { "description": "Every failure returns this envelope; the HTTP status carries the category.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "summary": "Fetch ssh key by ID", "tags": [ "SSH Keys" ] }, "delete": { "description": "Deletes an SSH key.\n", "operationId": "deleteSshByKid", "parameters": [ { "description": "SSH Key ID", "in": "path", "name": "kid", "required": true, "schema": { "example": "1506320201023500406", "type": "string" } } ], "responses": { "202": { "description": "Accepted" }, "default": { "description": "Every failure returns this envelope; the HTTP status carries the category.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "summary": "Delete an ssh key", "tags": [ "SSH Keys" ] } }, "/subjects/{sid}": { "get": { "description": "Returns a subject with its full spec and the priced fields behind its price.", "operationId": "getSubjectsBySid", "parameters": [ { "description": "Subject id", "in": "path", "name": "sid", "required": true, "schema": { "example": "1456074443980800000", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubjectDetailResponse" } } }, "description": "The subject, its spec and its priced fields" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Not a member of the subject's workspace" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "No subject with that id" }, "default": { "description": "Every failure returns this envelope; the HTTP status carries the category.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "summary": "Get a subject", "tags": [ "Subjects" ] } }, "/subjects/{sid}/cancel": { "post": { "description": "Terminates a delivered subject, stopping its billing. A fixed-prepaid subject refunds the unused part of the cycle to the wallet when the account is set up for it. A cycle paid before it starts is refunded in full, and an unpaid renewal is removed from its invoice. A fixed-postpaid one posts its final partial cycle on the next bill, and a metered one charges accrued usage up to now. A purchase that has not been delivered yet is cancelled on its order instead. Cancelling an already cancelled purchase is a no-op.", "operationId": "postSubjectsBySidCancel", "parameters": [ { "description": "Subject id", "in": "path", "name": "sid", "required": true, "schema": { "example": "1456074443980800000", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubjectView" } } }, "description": "The cancelled subject" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "No subject with that id, or no account or wallet behind it" }, "default": { "description": "Every failure returns this envelope; the HTTP status carries the category.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "summary": "Cancel a purchase", "tags": [ "Subjects" ] } }, "/subjects/{sid}/cancel-quote": { "get": { "description": "Returns the wallet refund that a cancel of the subject gives at this time, and the reason. The refund is prorated by the hour, so a cancel in the same hour gives the same amount.", "operationId": "getSubjectsBySidCancelQuote", "parameters": [ { "description": "Subject id", "in": "path", "name": "sid", "required": true, "schema": { "example": "1456074443980800000", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CancelQuoteResponse" } } }, "description": "The refund a cancel would make now" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Not a member of the subject's workspace" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "No subject with that id" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "The subject is already terminated" }, "default": { "description": "Every failure returns this envelope; the HTTP status carries the category.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "summary": "Quote cancelling a subject", "tags": [ "Subjects" ] } }, "/subjects/{sid}/renewal-day": { "post": { "description": "Moves the renewal of a paid-up prepaid subject forward to a day of the month. The default is the account's monthly date. The renewal only moves later, and the added days are charged at the subject's price. If the wallet cannot pay, an invoice is created and the renewal moves when it is paid.", "operationId": "postSubjectsBySidRenewalDay", "parameters": [ { "description": "Subject id", "in": "path", "name": "sid", "required": true, "schema": { "example": "1456074443980800000", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MoveRenewalDayRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RenewalDayResponse" } } }, "description": "The subject, whether the renewal moved, and what is owed" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Not a prepaid subject, a day outside 1-31, or no day while the account has no monthly date" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Not the subject's owner" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "No subject with that id" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "The subject is not active, not paid up, has a renewal on an unpaid invoice, or already has a move awaiting payment" }, "default": { "description": "Every failure returns this envelope; the HTTP status carries the category.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "summary": "Move a subject's renewal day", "tags": [ "Subjects" ] } }, "/subjects/{sid}/renewal-day-quote": { "get": { "description": "Returns the renewal of a prepaid subject after a move forward to a day of the month, and the current charge for the added days.", "operationId": "getSubjectsBySidRenewalDayQuote", "parameters": [ { "description": "Subject id", "in": "path", "name": "sid", "required": true, "schema": { "example": "1456074443980800000", "type": "string" } }, { "description": "Day of the month to renew on; defaults to the account's monthly date", "in": "query", "name": "day", "required": false, "schema": { "format": "int32", "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RenewalDayQuoteResponse" } } }, "description": "The new renewal and its charge" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Not a prepaid subject, a day outside 1-31, or no day while the account has no monthly date" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Not a member of the subject's workspace" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "No subject with that id" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "The subject is not active, not paid up, or has a renewal on an unpaid invoice" }, "default": { "description": "Every failure returns this envelope; the HTTP status carries the category.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "summary": "Quote moving a subject's renewal day", "tags": [ "Subjects" ] } }, "/subjects/{sid}/transitions": { "get": { "description": "Keyset-paginated listing of the upgrades and downgrades that the subject's current package offers. Each move keeps the subject's current values in the target's open fields and shows the price and prorated amount that an upgrade order bills. A move that the subject cannot make has eligible false and the reason that the order returns. A change to the open fields of the current package is not listed; use an upgrade order to the same package.", "operationId": "getSubjectsBySidTransitions", "parameters": [ { "description": "Subject id", "in": "path", "name": "sid", "required": true, "schema": { "example": "1456074443980800000", "type": "string" } }, { "description": "Directions to filter", "in": "query", "name": "direction", "required": false, "schema": { "items": { "enum": [ "UPGRADE", "DOWNGRADE" ], "type": "string" }, "type": "array" } }, { "description": "How many items to return", "example": 50, "in": "query", "name": "limit", "required": false, "schema": { "format": "int32", "type": "integer" } }, { "description": "Page number to fetch", "example": 1, "in": "query", "name": "page", "required": false, "schema": { "format": "int32", "type": "integer" } }, { "description": "Field to order by", "example": "id", "in": "query", "name": "sort", "required": false, "schema": { "type": "string" } }, { "description": "Order direction (ASC/DESC)", "example": "asc", "in": "query", "name": "dir", "required": false, "schema": { "type": "string" } }, { "description": "Forward keyset cursor (for keyset pagination)", "in": "query", "name": "after", "required": false, "schema": { "type": "string" } }, { "description": "Backward keyset cursor (for keyset pagination)", "in": "query", "name": "before", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/KeysetResultSubjectTransitionResponse" } } }, "description": "A page of priced moves" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Not a member of the subject's workspace" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "No subject with that id" }, "default": { "description": "Every failure returns this envelope; the HTTP status carries the category.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "summary": "List a subject's moves", "tags": [ "Subjects" ] } }, "/subjects/{sid}/usage": { "get": { "description": "Keyset-paginated hourly metered usage for a subject, newest first. Empty for a subject billed a fixed price per cycle.", "operationId": "getSubjectsBySidUsage", "parameters": [ { "description": "Subject id", "in": "path", "name": "sid", "required": true, "schema": { "example": "1456074443980800000", "type": "string" } }, { "description": "How many items to return", "example": 50, "in": "query", "name": "limit", "required": false, "schema": { "format": "int32", "type": "integer" } }, { "description": "Page number to fetch", "example": 1, "in": "query", "name": "page", "required": false, "schema": { "format": "int32", "type": "integer" } }, { "description": "Field to order by", "example": "id", "in": "query", "name": "sort", "required": false, "schema": { "type": "string" } }, { "description": "Order direction (ASC/DESC)", "example": "asc", "in": "query", "name": "dir", "required": false, "schema": { "type": "string" } }, { "description": "Forward keyset cursor (for keyset pagination)", "in": "query", "name": "after", "required": false, "schema": { "type": "string" } }, { "description": "Backward keyset cursor (for keyset pagination)", "in": "query", "name": "before", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/KeysetResultUsageRecordView" } } }, "description": "A page of usage records for the subject" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Not a member of the subject's workspace" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "No subject with that id" }, "default": { "description": "Every failure returns this envelope; the HTTP status carries the category.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "summary": "List a subject's usage", "tags": [ "Subjects" ] } }, "/tokens": { "post": { "description": "Alias for POST /v1/users/@me/tokens. Creates an API token bound to the authenticated user and limited to\nthe supplied permission map. The plaintext code is returned once, save it securely.\n", "operationId": "postTokens", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TokenCreateRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TokenCreateResponse" } } }, "description": "OK" }, "default": { "description": "Every failure returns this envelope; the HTTP status carries the category.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "summary": "Create a USER-scope API token for the authenticated user", "tags": [ "Tokens" ] } }, "/tokens/refresh": { "post": { "description": "Restarts the lifetime of a SESSION token and returns the new expiration. Only a SESSION token in the last\n6 hours of its lifetime can be refreshed.\n", "operationId": "postTokensRefresh", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RefreshTokenRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RefreshTokenResponse" } } }, "description": "OK" }, "default": { "description": "Every failure returns this envelope; the HTTP status carries the category.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "summary": "Refresh a user session token", "tags": [ "Tokens" ] } }, "/tokens/{tid}": { "get": { "description": "Returns the metadata of a single token.", "operationId": "getTokensByTid", "parameters": [ { "description": "Token ID", "in": "path", "name": "tid", "required": true, "schema": { "example": "1479097389678620681", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TokenListView" } } }, "description": "OK" }, "default": { "description": "Every failure returns this envelope; the HTTP status carries the category.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "summary": "Fetch a token by ID", "tags": [ "Tokens" ] }, "delete": { "description": "Deletes a token. The token stops working immediately.", "operationId": "deleteTokensByTid", "parameters": [ { "description": "Token ID", "in": "path", "name": "tid", "required": true, "schema": { "example": "1479097389678620681", "type": "string" } } ], "responses": { "202": { "description": "Accepted" }, "default": { "description": "Every failure returns this envelope; the HTTP status carries the category.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "summary": "Delete a token", "tags": [ "Tokens" ] } }, "/users/{uid}": { "get": { "operationId": "getUsersByUid", "parameters": [ { "description": "User ID, or @me for the current user", "in": "path", "name": "uid", "required": true, "schema": { "example": "@me", "pattern": "^(@me|[0-9]{1,19})$", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EnrichedUserDetailViewUserLive" } } }, "description": "OK" }, "default": { "description": "Every failure returns this envelope; the HTTP status carries the category.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "summary": "Fetch a user profile", "tags": [ "User settings" ] }, "delete": { "description": "Permanently deactivates the account and revokes its active sessions. Transfer or delete the workspaces the\naccount owns first.\n", "operationId": "deleteUsersByUid", "parameters": [ { "description": "User ID, or @me for the current user", "in": "path", "name": "uid", "required": true, "schema": { "example": "@me", "pattern": "^(@me|[0-9]{1,19})$", "type": "string" } } ], "responses": { "202": { "description": "Accepted", "headers": { "X-Sudo-Expires": { "description": "When sudo mode ends, sent when the request starts or extends it", "schema": { "format": "date-time", "type": "string" } } } }, "403": { "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ApiError" }, { "$ref": "#/components/schemas/MfaChallenge" } ] } } }, "description": "Forbidden, or `MfaChallenge` when a second factor is needed" }, "default": { "description": "Every failure returns this envelope; the HTTP status carries the category.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "summary": "Delete a user account", "tags": [ "User settings" ], "x-api-elevation": "required" }, "patch": { "description": "Updates the user profile. A new email address gets a confirmation link first. A change of email address needs sudo mode or a second factor.", "operationId": "patchUsersByUid", "parameters": [ { "description": "User ID, or @me for the current user", "in": "path", "name": "uid", "required": true, "schema": { "example": "@me", "pattern": "^(@me|[0-9]{1,19})$", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateUserRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EnrichedUserDetailViewUserLive" } } }, "description": "OK", "headers": { "X-Sudo-Expires": { "description": "When sudo mode ends, sent when the request starts or extends it", "schema": { "format": "date-time", "type": "string" } } } }, "403": { "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ApiError" }, { "$ref": "#/components/schemas/MfaChallenge" } ] } } }, "description": "Forbidden, or `MfaChallenge` when a second factor is needed" }, "default": { "description": "Every failure returns this envelope; the HTTP status carries the category.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "summary": "Update the account profile", "tags": [ "User settings" ], "x-api-elevation": "conditional" } }, "/users/{uid}/account": { "get": { "description": "Returns the user's billing account and its billing terms.", "operationId": "getUsersByUidAccount", "parameters": [ { "description": "User id, or @me for the current user", "in": "path", "name": "uid", "required": true, "schema": { "example": "@me", "pattern": "^(@me|[0-9]{1,19})$", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccountView" } } }, "description": "The account and its billing terms" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "No account for that user" }, "default": { "description": "Every failure returns this envelope; the HTTP status carries the category.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "summary": "Get a user's billing account", "tags": [ "Accounts" ] } }, "/users/{uid}/account/monthly-date": { "post": { "description": "Sets the day of the month for the monthly invoice and for MONTHLY_DATE renewals. If the account has a monthly invoice, the usage and charges to date are invoiced now, and the next monthly invoice moves to the first date on the new day that is on or after its current date. Prepaid subjects keep their renewal days; move each subject to align it.", "operationId": "postUsersByUidAccountMonthlyDate", "parameters": [ { "description": "User id, or @me for the current user", "in": "path", "name": "uid", "required": true, "schema": { "example": "@me", "pattern": "^(@me|[0-9]{1,19})$", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MoveMonthlyDateRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccountView" } } }, "description": "The account with its new monthly date" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "No day, or a day outside 1-31" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Not the account's user" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "No account for that user" }, "default": { "description": "Every failure returns this envelope; the HTTP status carries the category.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "summary": "Move the account's monthly date", "tags": [ "Accounts" ] } }, "/users/{uid}/audit": { "get": { "description": "Lists the security activity on an account, newest first.", "operationId": "getUsersByUidAudit", "parameters": [ { "description": "User ID, or @me for the current user", "in": "path", "name": "uid", "required": true, "schema": { "example": "@me", "pattern": "^(@me|[0-9]{1,19})$", "type": "string" } }, { "description": "Actions to filter", "in": "query", "name": "action", "required": false, "schema": { "items": { "description": "Action recorded by an audit log entry", "enum": [ "INSTANCE_CREATED", "INSTANCE_TERMINATED", "INSTANCE_TERMINATION_SCHEDULED", "INSTANCE_TERMINATION_CANCELLED", "INSTANCE_POWER_ON", "INSTANCE_POWER_OFF", "INSTANCE_POWER_CYCLE", "INSTANCE_SHUTDOWN", "INSTANCE_POWER", "INSTANCE_SUSPENDED", "INSTANCE_RESUMED", "INSTANCE_NETWORK_SUSPENDED", "INSTANCE_NETWORK_RESUMED", "INSTANCE_BOOT_CHANGED", "INSTANCE_AUTOSTART_CHANGED", "INSTANCE_VIRTIO_CD_CHANGED", "INSTANCE_FIRMWARE_CHANGED", "INSTANCE_OS_CHANGED", "INSTANCE_TIMEZONE_CHANGED", "INSTANCE_CLOUD_INIT_UPDATED", "INSTANCE_HOSTNAME_CHANGED", "INSTANCE_PASSWORD_RESET", "INSTANCE_SSH_KEYS_SYNCED", "INSTANCE_RECIPE_INSTALLED", "INSTANCE_UPGRADED", "INSTANCE_UPGRADES_APPLIED", "INSTANCE_MIGRATION_STARTED", "INSTANCE_TRANSFERRED", "INSTANCE_REINSTALLED", "INSTANCE_PACKET_CAPTURE_STARTED", "SNAPSHOT_CREATED", "SNAPSHOT_DELETED", "SNAPSHOT_RESTORED", "BACKUP_CREATED", "BACKUP_RESTORED", "ISO_ATTACHED", "ISO_DETACHED", "VPC_ATTACHED", "VPC_DETACHED", "FIREWALL_RULE_CREATED", "FIREWALL_RULE_UPDATED", "FIREWALL_RULE_DELETED", "FIREWALL_UPDATED", "FIREWALL_RESET", "IP_ATTACHED", "IP_DETACHED", "IP_AUTO_ASSIGNED", "IP_RELEASED", "IP_ROTATED", "IP_PROTECTION_CHANGED", "ISO_UPLOADED", "ISO_IMPORTED", "TEMPLATE_CREATED", "TEMPLATE_IMPORTED", "IMAGE_DELETED", "VPC_DELETED", "VPC_ROUTER_CHANGED", "RECIPE_CREATED", "RECIPE_UPDATED", "RECIPE_DELETED", "DEDIBOX_POWER_ON", "DEDIBOX_POWER_OFF", "DEDIBOX_POWER_CYCLE", "DEDIBOX_SHUTDOWN", "DEDIBOX_RECONFIGURED", "DEDIBOX_VNC_RESET", "TOKEN_CREATED", "TOKEN_DELETED", "TOKEN_EXPOSED_REVOKED", "ACCOUNT_REGISTERED", "ACCOUNT_LOGIN_PASSWORD", "ACCOUNT_LOGIN_SSO", "ACCOUNT_LOGIN_PASSKEY", "ACCOUNT_LOGIN_PASSWORD_FAILED", "ACCOUNT_LOGIN_SSO_FAILED", "ACCOUNT_LOGIN_PASSKEY_FAILED", "ACCOUNT_LOGOUT", "ACCOUNT_SESSIONS_REVOKED", "ACCOUNT_SESSION_LOCATION_REVOKED", "ACCOUNT_RENAMED", "ACCOUNT_EMAIL_CHANGE_REQUESTED", "ACCOUNT_EMAIL_CHANGED", "ACCOUNT_EMAIL_VERIFIED", "ACCOUNT_EMAIL_UNVERIFIED", "ACCOUNT_PASSWORD_CHANGED", "ACCOUNT_PASSWORD_RESET_REQUESTED", "ACCOUNT_PASSWORD_RESET", "ACCOUNT_PASSWORD_CLEARED", "ACCOUNT_MFA_ENABLED", "ACCOUNT_MFA_DISABLED", "ACCOUNT_RECOVERY_CODE_REGENERATED", "ACCOUNT_CREDENTIAL_ADDED", "ACCOUNT_CREDENTIAL_RENAMED", "ACCOUNT_CREDENTIAL_REMOVED", "ACCOUNT_IDENTITY_LINKED", "ACCOUNT_IDENTITY_UNLINKED", "ACCOUNT_LOCKED", "ACCOUNT_UNLOCKED", "ACCOUNT_BILLING_LINK_CHANGED", "ACCOUNT_DELETED", "OAUTH_APPLICATION_AUTHORIZED", "OAUTH_APPLICATION_DEAUTHORIZED", "OAUTH_TOKEN_ISSUED", "OAUTH_TOKEN_REFRESHED", "OAUTH_TOKEN_REVOKED", "OAUTH_APPLICATION_CREATED", "OAUTH_APPLICATION_UPDATED", "OAUTH_APPLICATION_DELETED", "OAUTH_APPLICATION_SECRET_REGENERATED", "WORKSPACE_CREATED", "WORKSPACE_RENAMED", "WORKSPACE_SETTINGS_CHANGED", "WORKSPACE_DELETED", "MEMBER_INVITED", "MEMBER_INVITE_UPDATED", "MEMBER_INVITE_REVOKED", "MEMBER_JOINED", "MEMBER_ROLE_CHANGED", "MEMBER_PERMISSIONS_CHANGED", "MEMBER_REMOVED", "SSH_KEY_ADDED", "SSH_KEY_DELETED", "REGISTRY_CREDENTIAL_ADDED", "REGISTRY_CREDENTIAL_UPDATED", "REGISTRY_CREDENTIAL_DELETED" ], "type": "string" }, "type": "array" } }, { "description": "Kind of resource the entries are filed under", "in": "query", "name": "target_kind", "required": false, "schema": { "description": "Kind of resource an audit log entry is filed under", "enum": [ "INSTANCE", "DEDIBOX", "IMAGE", "VPC", "RECIPE", "FLOATING_IP", "TOKEN", "USER", "OAUTH_APPLICATION", "WORKSPACE", "SSH_KEY", "REGISTRY_CREDENTIAL" ], "type": "string" } }, { "description": "IDs of the resources the entries are filed under", "in": "query", "name": "target_id", "required": false, "schema": { "items": { "example": "1463106077196308568", "type": "string" }, "type": "array" } }, { "description": "Kind of principal that performed the action", "in": "query", "name": "actor_type", "required": false, "schema": { "description": "Kind of principal that performed an audited action", "enum": [ "USER", "TOKEN", "SYSTEM", "ANONYMOUS", "APPLICATION" ], "type": "string" } }, { "description": "IDs of the users or tokens that performed the action", "in": "query", "name": "actor_id", "required": false, "schema": { "items": { "example": "1053072706808680448", "type": "string" }, "type": "array" } }, { "description": "Only entries for the given workflow", "in": "query", "name": "workflow_id", "required": false, "schema": { "type": "string" } }, { "description": "Only entries at or after this time", "example": "2026-03-01T00:00:00Z", "in": "query", "name": "since", "required": false, "schema": { "format": "date-time", "type": "string" } }, { "description": "Only entries before this time", "example": "2026-04-01T00:00:00Z", "in": "query", "name": "until", "required": false, "schema": { "format": "date-time", "type": "string" } }, { "description": "Only entries from this address, or from any address in this CIDR range", "example": "203.0.113.0/24", "in": "query", "name": "ip", "required": false, "schema": { "type": "string" } }, { "description": "Autonomous system numbers the actor's address belongs to", "in": "query", "name": "asn", "required": false, "schema": { "items": { "example": "3320", "type": "string" }, "type": "array" } }, { "description": "ISO 3166-1 alpha-2 countries of the actor's address", "in": "query", "name": "country", "required": false, "schema": { "items": { "example": "DE", "type": "string" }, "type": "array" } }, { "description": "Kind of network the actor's address belongs to", "in": "query", "name": "network_type", "required": false, "schema": { "enum": [ "PROXY", "DATACENTER", "RESIDENTIAL", "UNKNOWN" ], "type": "string" } }, { "description": "How many items to return", "example": 50, "in": "query", "name": "limit", "required": false, "schema": { "format": "int32", "type": "integer" } }, { "description": "Page number to fetch", "example": 1, "in": "query", "name": "page", "required": false, "schema": { "format": "int32", "type": "integer" } }, { "description": "Field to order by", "example": "id", "in": "query", "name": "sort", "required": false, "schema": { "type": "string" } }, { "description": "Order direction (ASC/DESC)", "example": "asc", "in": "query", "name": "dir", "required": false, "schema": { "type": "string" } }, { "description": "Forward keyset cursor (for keyset pagination)", "in": "query", "name": "after", "required": false, "schema": { "type": "string" } }, { "description": "Backward keyset cursor (for keyset pagination)", "in": "query", "name": "before", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/KeysetResultAuditLogView" } } }, "description": "OK" }, "default": { "description": "Every failure returns this envelope; the HTTP status carries the category.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "summary": "Search an account's audit log", "tags": [ "Audit log" ] } }, "/users/{uid}/audit/{aid}": { "get": { "operationId": "getUsersByUidAuditByAid", "parameters": [ { "description": "User ID, or @me for the current user", "in": "path", "name": "uid", "required": true, "schema": { "example": "@me", "pattern": "^(@me|[0-9]{1,19})$", "type": "string" } }, { "description": "Audit log entry ID", "in": "path", "name": "aid", "required": true, "schema": { "example": "1498223722102817012", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuditLogView" } } }, "description": "OK" }, "default": { "description": "Every failure returns this envelope; the HTTP status carries the category.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "summary": "Fetch an account audit log entry", "tags": [ "Audit log" ] } }, "/users/{uid}/coupons/redeem": { "post": { "description": "Mints the coupon's credit into the user's wallet. A coupon redeems once per user, and a coupon with no uses remaining is rejected.", "operationId": "postUsersByUidCouponsRedeem", "parameters": [ { "description": "User id, or @me for the current user", "in": "path", "name": "uid", "required": true, "schema": { "example": "@me", "pattern": "^(@me|[0-9]{1,19})$", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RedeemCouponRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RedeemCouponResponse" } } }, "description": "The wallet and the ledger entry the redemption wrote" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "No such coupon code, or no account for that user" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Already redeemed by this user, or no uses remaining" }, "default": { "description": "Every failure returns this envelope; the HTTP status carries the category.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "summary": "Redeem a coupon", "tags": [ "Coupons" ] } }, "/users/{uid}/coupons/redemptions": { "get": { "description": "Keyset-paginated coupons the user redeemed, newest first.", "operationId": "getUsersByUidCouponsRedemptions", "parameters": [ { "description": "User id, or @me for the current user", "in": "path", "name": "uid", "required": true, "schema": { "example": "@me", "pattern": "^(@me|[0-9]{1,19})$", "type": "string" } }, { "description": "How many items to return", "example": 50, "in": "query", "name": "limit", "required": false, "schema": { "format": "int32", "type": "integer" } }, { "description": "Page number to fetch", "example": 1, "in": "query", "name": "page", "required": false, "schema": { "format": "int32", "type": "integer" } }, { "description": "Field to order by", "example": "id", "in": "query", "name": "sort", "required": false, "schema": { "type": "string" } }, { "description": "Order direction (ASC/DESC)", "example": "asc", "in": "query", "name": "dir", "required": false, "schema": { "type": "string" } }, { "description": "Forward keyset cursor (for keyset pagination)", "in": "query", "name": "after", "required": false, "schema": { "type": "string" } }, { "description": "Backward keyset cursor (for keyset pagination)", "in": "query", "name": "before", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/KeysetResultCouponRedemptionView" } } }, "description": "A page of the user's redemptions" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "No account for that user" }, "default": { "description": "Every failure returns this envelope; the HTTP status carries the category.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "summary": "List a user's coupon redemptions", "tags": [ "Coupons" ] } }, "/users/{uid}/coupons/validate": { "get": { "description": "Reports whether the user can redeem a code and what redeeming it would grant, without redeeming it. An unknown code is reported as invalid, not as an error.", "operationId": "getUsersByUidCouponsValidate", "parameters": [ { "description": "User id, or @me for the current user", "in": "path", "name": "uid", "required": true, "schema": { "example": "@me", "pattern": "^(@me|[0-9]{1,19})$", "type": "string" } }, { "description": "Coupon code", "example": "WELCOME10", "in": "query", "name": "code", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CouponValidity" } } }, "description": "Whether the coupon can be redeemed" }, "default": { "description": "Every failure returns this envelope; the HTTP status carries the category.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "summary": "Check whether a coupon can be redeemed", "tags": [ "Coupons" ] } }, "/users/{uid}/credentials": { "get": { "operationId": "getUsersByUidCredentials", "parameters": [ { "description": "User ID, or @me for the current user", "in": "path", "name": "uid", "required": true, "schema": { "example": "@me", "pattern": "^(@me|[0-9]{1,19})$", "type": "string" } }, { "description": "Quick search by name or ID", "in": "query", "name": "q", "required": false, "schema": { "type": "string" } }, { "description": "List of credential IDs to filter", "in": "query", "name": "id", "required": false, "schema": { "items": { "example": "1479097389678620681", "type": "string" }, "type": "array" } }, { "description": "Credential name to filter", "in": "query", "name": "name", "required": false, "schema": { "type": "string" } }, { "description": "Credential kind to filter", "in": "query", "name": "kind", "required": false, "schema": { "description": "What a WebAuthn credential is registered as", "enum": [ "SECURITY_KEY", "PASSKEY" ], "type": "string" } }, { "description": "How many items to return", "example": 50, "in": "query", "name": "limit", "required": false, "schema": { "format": "int32", "type": "integer" } }, { "description": "Page number to fetch", "example": 1, "in": "query", "name": "page", "required": false, "schema": { "format": "int32", "type": "integer" } }, { "description": "Field to order by", "example": "id", "in": "query", "name": "sort", "required": false, "schema": { "type": "string" } }, { "description": "Order direction (ASC/DESC)", "example": "asc", "in": "query", "name": "dir", "required": false, "schema": { "type": "string" } }, { "description": "Forward keyset cursor (for keyset pagination)", "in": "query", "name": "after", "required": false, "schema": { "type": "string" } }, { "description": "Backward keyset cursor (for keyset pagination)", "in": "query", "name": "before", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/KeysetResultCredentialView" } } }, "description": "OK" }, "default": { "description": "Every failure returns this envelope; the HTTP status carries the category.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "summary": "List security keys and passkeys", "tags": [ "User settings" ] }, "post": { "description": "Finishes a registration started with `POST /v1/users/{uid}/credentials/options`. When this is the account's first second factor, the response carries the recovery code, shown only once.\n", "operationId": "postUsersByUidCredentials", "parameters": [ { "description": "User ID, or @me for the current user", "in": "path", "name": "uid", "required": true, "schema": { "example": "@me", "pattern": "^(@me|[0-9]{1,19})$", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CredentialRegisterRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CredentialCreated" } } }, "description": "OK", "headers": { "X-Sudo-Expires": { "description": "When sudo mode ends, sent when the request starts or extends it", "schema": { "format": "date-time", "type": "string" } } } }, "403": { "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ApiError" }, { "$ref": "#/components/schemas/MfaChallenge" } ] } } }, "description": "Forbidden, or `MfaChallenge` when a second factor is needed" }, "default": { "description": "Every failure returns this envelope; the HTTP status carries the category.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "summary": "Register a security key or passkey", "tags": [ "User settings" ], "x-api-elevation": "required" } }, "/users/{uid}/credentials/options": { "post": { "description": "Creation options for the browser. Answer them with `POST /v1/users/{uid}/credentials`. An account holds at most 20.\n", "operationId": "postUsersByUidCredentialsOptions", "parameters": [ { "description": "User ID, or @me for the current user", "in": "path", "name": "uid", "required": true, "schema": { "example": "@me", "pattern": "^(@me|[0-9]{1,19})$", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CredentialOptionsRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebAuthnOptions" } } }, "description": "OK", "headers": { "X-Sudo-Expires": { "description": "When sudo mode ends, sent when the request starts or extends it", "schema": { "format": "date-time", "type": "string" } } } }, "403": { "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ApiError" }, { "$ref": "#/components/schemas/MfaChallenge" } ] } } }, "description": "Forbidden, or `MfaChallenge` when a second factor is needed" }, "default": { "description": "Every failure returns this envelope; the HTTP status carries the category.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "summary": "Start registering a security key or passkey", "tags": [ "User settings" ], "x-api-elevation": "required" } }, "/users/{uid}/credentials/{cid}": { "delete": { "description": "Removes the credential and signs out every session. Fails with `mfa_enforced` when it is the last second factor and a workspace the account belongs to requires two-factor authentication.\n", "operationId": "deleteUsersByUidCredentialsByCid", "parameters": [ { "description": "User ID, or @me for the current user", "in": "path", "name": "uid", "required": true, "schema": { "example": "@me", "pattern": "^(@me|[0-9]{1,19})$", "type": "string" } }, { "description": "Credential ID", "in": "path", "name": "cid", "required": true, "schema": { "example": "1479097389678620681", "type": "string" } } ], "responses": { "204": { "description": "No Content", "headers": { "X-Sudo-Expires": { "description": "When sudo mode ends, sent when the request starts or extends it", "schema": { "format": "date-time", "type": "string" } } } }, "403": { "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ApiError" }, { "$ref": "#/components/schemas/MfaChallenge" } ] } } }, "description": "Forbidden, or `MfaChallenge` when a second factor is needed" }, "default": { "description": "Every failure returns this envelope; the HTTP status carries the category.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "summary": "Remove a security key or passkey", "tags": [ "User settings" ], "x-api-elevation": "required" }, "patch": { "operationId": "patchUsersByUidCredentialsByCid", "parameters": [ { "description": "User ID, or @me for the current user", "in": "path", "name": "uid", "required": true, "schema": { "example": "@me", "pattern": "^(@me|[0-9]{1,19})$", "type": "string" } }, { "description": "Credential ID", "in": "path", "name": "cid", "required": true, "schema": { "example": "1479097389678620681", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CredentialRenameRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CredentialView" } } }, "description": "OK" }, "default": { "description": "Every failure returns this envelope; the HTTP status carries the category.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "summary": "Rename a security key or passkey", "tags": [ "User settings" ] } }, "/users/{uid}/elevation": { "get": { "description": "When sudo mode on the current login ends.", "operationId": "getUsersByUidElevation", "parameters": [ { "description": "User ID, or @me for the current user", "in": "path", "name": "uid", "required": true, "schema": { "example": "@me", "pattern": "^(@me|[0-9]{1,19})$", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Elevation" } } }, "description": "OK" }, "default": { "description": "Every failure returns this envelope; the HTTP status carries the category.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "summary": "Get sudo mode", "tags": [ "User settings" ] }, "post": { "description": "Enters sudo mode on the current login. Send a second factor, or the password if the account has no second factor. A wrong code or password returns 403 `MfaChallenge`. Sudo mode ends two hours after the last sensitive action, when the password changes, or when a second factor is removed. An account with no password and no second factor is in sudo mode for ten minutes after sign-in, and must sign in again after that.\n", "operationId": "postUsersByUidElevation", "parameters": [ { "description": "User ID, or @me for the current user", "in": "path", "name": "uid", "required": true, "schema": { "example": "@me", "pattern": "^(@me|[0-9]{1,19})$", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ElevationRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Elevation" } } }, "description": "OK" }, "default": { "description": "Every failure returns this envelope; the HTTP status carries the category.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "summary": "Enter sudo mode", "tags": [ "User settings" ] }, "delete": { "description": "Ends sudo mode on the current login.", "operationId": "deleteUsersByUidElevation", "parameters": [ { "description": "User ID, or @me for the current user", "in": "path", "name": "uid", "required": true, "schema": { "example": "@me", "pattern": "^(@me|[0-9]{1,19})$", "type": "string" } } ], "responses": { "204": { "description": "No Content" }, "default": { "description": "Every failure returns this envelope; the HTTP status carries the category.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "summary": "Leave sudo mode", "tags": [ "User settings" ] } }, "/users/{uid}/elevation/options": { "post": { "description": "Assertion options for the account's security keys and passkeys. Answer them with `POST /v1/users/{uid}/elevation` and `webauthn`.\n", "operationId": "postUsersByUidElevationOptions", "parameters": [ { "description": "User ID, or @me for the current user", "in": "path", "name": "uid", "required": true, "schema": { "example": "@me", "pattern": "^(@me|[0-9]{1,19})$", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebAuthnOptions" } } }, "description": "OK" }, "default": { "description": "Every failure returns this envelope; the HTTP status carries the category.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "summary": "Start sudo mode with a security key", "tags": [ "User settings" ] } }, "/users/{uid}/identities": { "get": { "description": "Lists the external provider accounts that can sign in to this account.\n", "operationId": "getUsersByUidIdentities", "parameters": [ { "description": "User ID, or @me for the current user", "in": "path", "name": "uid", "required": true, "schema": { "example": "@me", "pattern": "^(@me|[0-9]{1,19})$", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "items": { "$ref": "#/components/schemas/UserIdentityListView" }, "type": "array" } } }, "description": "OK" }, "default": { "description": "Every failure returns this envelope; the HTTP status carries the category.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "summary": "Lists linked external accounts", "tags": [ "User settings" ] }, "post": { "description": "Attaches the provider account to this account. Fails when that provider account is already linked\nelsewhere, or when this account already has an account linked for the same provider.\n", "operationId": "postUsersByUidIdentities", "parameters": [ { "description": "User ID, or @me for the current user", "in": "path", "name": "uid", "required": true, "schema": { "example": "@me", "pattern": "^(@me|[0-9]{1,19})$", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IdentityLinkRequest" } } }, "required": true }, "responses": { "201": { "content": { "*/*": { "schema": { "$ref": "#/components/schemas/UserIdentityListView" } } }, "description": "Created" }, "default": { "description": "Every failure returns this envelope; the HTTP status carries the category.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "summary": "Complete linking an external account", "tags": [ "User settings" ] } }, "/users/{uid}/identities/start": { "post": { "description": "Returns the provider URL to send the browser to, together with the `state` value that authorization\nrequest is bound to. The request is bound to this account for its whole lifetime, so completing it\nlinks the provider account here regardless of which address the provider reports.\n\nRequires a login session, and 2FA when the account has it enabled.\n", "operationId": "postUsersByUidIdentitiesStart", "parameters": [ { "description": "User ID, or @me for the current user", "in": "path", "name": "uid", "required": true, "schema": { "example": "@me", "pattern": "^(@me|[0-9]{1,19})$", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IdentityStartRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SsoStartResponse" } } }, "description": "OK" }, "default": { "description": "Every failure returns this envelope; the HTTP status carries the category.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "summary": "Begin linking an external account", "tags": [ "User settings" ] } }, "/users/{uid}/identities/{iid}": { "delete": { "description": "Removes a linked provider account. An account left with no password can still recover one through the\npassword reset flow.\n", "operationId": "deleteUsersByUidIdentitiesByIid", "parameters": [ { "description": "User ID, or @me for the current user", "in": "path", "name": "uid", "required": true, "schema": { "example": "@me", "pattern": "^(@me|[0-9]{1,19})$", "type": "string" } }, { "description": "Linked identity ID", "in": "path", "name": "iid", "required": true, "schema": { "example": "1489276118237192255", "type": "string" } } ], "responses": { "202": { "description": "Accepted", "headers": { "X-Sudo-Expires": { "description": "When sudo mode ends, sent when the request starts or extends it", "schema": { "format": "date-time", "type": "string" } } } }, "403": { "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ApiError" }, { "$ref": "#/components/schemas/MfaChallenge" } ] } } }, "description": "Forbidden, or `MfaChallenge` when a second factor is needed" }, "default": { "description": "Every failure returns this envelope; the HTTP status carries the category.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "summary": "Unlinks an external account", "tags": [ "User settings" ], "x-api-elevation": "required" } }, "/users/{uid}/invites": { "get": { "description": "Pending invitations addressed to the user, with filtering and paging.", "operationId": "getUsersByUidInvites", "parameters": [ { "description": "User ID, or @me for the current user", "in": "path", "name": "uid", "required": true, "schema": { "example": "@me", "pattern": "^(@me|[0-9]{1,19})$", "type": "string" } }, { "description": "Quick search by email or ID", "in": "query", "name": "q", "required": false, "schema": { "type": "string" } }, { "description": "List of invite IDs to filter", "in": "query", "name": "id", "required": false, "schema": { "items": { "example": "1489276118237192255", "type": "string" }, "type": "array" } }, { "description": "Invited email to filter", "in": "query", "name": "email", "required": false, "schema": { "type": "string" } }, { "description": "Granted governance role to filter", "in": "query", "name": "role", "required": false, "schema": { "type": "string" } }, { "description": "List of workspace IDs to filter", "in": "query", "name": "workspace", "required": false, "schema": { "items": { "example": "1405508720263180365", "type": "string" }, "type": "array" } }, { "description": "How many items to return", "example": 50, "in": "query", "name": "limit", "required": false, "schema": { "format": "int32", "type": "integer" } }, { "description": "Page number to fetch", "example": 1, "in": "query", "name": "page", "required": false, "schema": { "format": "int32", "type": "integer" } }, { "description": "Field to order by", "example": "id", "in": "query", "name": "sort", "required": false, "schema": { "type": "string" } }, { "description": "Order direction (ASC/DESC)", "example": "asc", "in": "query", "name": "dir", "required": false, "schema": { "type": "string" } }, { "description": "Forward keyset cursor (for keyset pagination)", "in": "query", "name": "after", "required": false, "schema": { "type": "string" } }, { "description": "Backward keyset cursor (for keyset pagination)", "in": "query", "name": "before", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/KeysetResultInviteListView" } } }, "description": "OK" }, "default": { "description": "Every failure returns this envelope; the HTTP status carries the category.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "summary": "List pending invites for a user", "tags": [ "Workspaces" ] } }, "/users/{uid}/invoices": { "get": { "description": "Keyset-paginated invoices for the given user, newest first.", "operationId": "getUsersByUidInvoices", "parameters": [ { "description": "User id, or @me for the current user", "in": "path", "name": "uid", "required": true, "schema": { "example": "@me", "pattern": "^(@me|[0-9]{1,19})$", "type": "string" } }, { "description": "Quick search by user id or invoice number", "in": "query", "name": "q", "required": false, "schema": { "type": "string" } }, { "description": "Invoice ids to filter", "in": "query", "name": "id", "required": false, "schema": { "items": { "example": "1456074443980800000", "type": "string" }, "type": "array" } }, { "description": "Account ids to filter", "in": "query", "name": "account_id", "required": false, "schema": { "items": { "example": "1456074443980800000", "type": "string" }, "type": "array" } }, { "description": "User ids to filter", "in": "query", "name": "user", "required": false, "schema": { "items": { "example": "1053072706808680448", "type": "string" }, "type": "array" } }, { "description": "Subject ids with a line on the invoice", "in": "query", "name": "subject_id", "required": false, "schema": { "items": { "example": "1456074443980800000", "type": "string" }, "type": "array" } }, { "description": "Statuses to filter", "in": "query", "name": "status", "required": false, "schema": { "items": { "enum": [ "DRAFT", "OPEN", "PAID", "VOID", "UNCOLLECTIBLE" ], "type": "string" }, "type": "array" } }, { "description": "Kinds to filter", "in": "query", "name": "kind", "required": false, "schema": { "items": { "enum": [ "CONSOLIDATED", "TOPUP", "ORDER" ], "type": "string" }, "type": "array" } }, { "description": "Invoice number to match", "in": "query", "name": "number", "required": false, "schema": { "type": "string" } }, { "description": "Currency code to filter, e.g. USD", "in": "query", "name": "currency", "required": false, "schema": { "type": "string" } }, { "description": "Minimum invoice total in micro-USD (inclusive)", "in": "query", "name": "min_total", "required": false, "schema": { "format": "int64", "type": "integer" } }, { "description": "Maximum invoice total in micro-USD (inclusive)", "in": "query", "name": "max_total", "required": false, "schema": { "format": "int64", "type": "integer" } }, { "description": "Only open invoices with a positive amount due", "in": "query", "name": "outstanding", "required": false, "schema": { "type": "boolean" } }, { "description": "Created at or after this instant (ISO-8601)", "in": "query", "name": "created_after", "required": false, "schema": { "format": "date-time", "type": "string" } }, { "description": "Created at or before this instant (ISO-8601)", "in": "query", "name": "created_before", "required": false, "schema": { "format": "date-time", "type": "string" } }, { "description": "Issued at or after this instant (ISO-8601)", "in": "query", "name": "issued_after", "required": false, "schema": { "format": "date-time", "type": "string" } }, { "description": "Issued at or before this instant (ISO-8601)", "in": "query", "name": "issued_before", "required": false, "schema": { "format": "date-time", "type": "string" } }, { "description": "Due at or after this instant (ISO-8601)", "in": "query", "name": "due_after", "required": false, "schema": { "format": "date-time", "type": "string" } }, { "description": "Due at or before this instant (ISO-8601)", "in": "query", "name": "due_before", "required": false, "schema": { "format": "date-time", "type": "string" } }, { "description": "How many items to return", "example": 50, "in": "query", "name": "limit", "required": false, "schema": { "format": "int32", "type": "integer" } }, { "description": "Page number to fetch", "example": 1, "in": "query", "name": "page", "required": false, "schema": { "format": "int32", "type": "integer" } }, { "description": "Field to order by", "example": "id", "in": "query", "name": "sort", "required": false, "schema": { "type": "string" } }, { "description": "Order direction (ASC/DESC)", "example": "asc", "in": "query", "name": "dir", "required": false, "schema": { "type": "string" } }, { "description": "Forward keyset cursor (for keyset pagination)", "in": "query", "name": "after", "required": false, "schema": { "type": "string" } }, { "description": "Backward keyset cursor (for keyset pagination)", "in": "query", "name": "before", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/KeysetResultInvoiceView" } } }, "description": "OK" }, "default": { "description": "Every failure returns this envelope; the HTTP status carries the category.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "summary": "List a user's invoices", "tags": [ "Invoices" ] } }, "/users/{uid}/oauth-apps": { "get": { "description": "Lists the OAuth applications owned by the given user. Supports a quick search by name or ID.\n", "operationId": "getUsersByUidOauthApps", "parameters": [ { "description": "User ID, or @me for the current user", "in": "path", "name": "uid", "required": true, "schema": { "example": "@me", "pattern": "^(@me|[0-9]{1,19})$", "type": "string" } }, { "description": "Quick search by name or ID", "in": "query", "name": "q", "required": false, "schema": { "type": "string" } }, { "description": "List of application IDs to filter", "in": "query", "name": "id", "required": false, "schema": { "items": { "example": "1479097389678620681", "type": "string" }, "type": "array" } }, { "description": "Filter by application name", "in": "query", "name": "name", "required": false, "schema": { "type": "string" } }, { "description": "Filter by application description", "in": "query", "name": "description", "required": false, "schema": { "type": "string" } }, { "description": "Filter by active status", "in": "query", "name": "active", "required": false, "schema": { "type": "boolean" } }, { "description": "Filter by redirect URI (contains match)", "in": "query", "name": "redirect_uri", "required": false, "schema": { "type": "string" } }, { "description": "Filter by owner user ID", "in": "query", "name": "owner", "required": false, "schema": { "example": "1405506895740940329", "type": "string" } }, { "description": "How many items to return", "example": 50, "in": "query", "name": "limit", "required": false, "schema": { "format": "int32", "type": "integer" } }, { "description": "Page number to fetch", "example": 1, "in": "query", "name": "page", "required": false, "schema": { "format": "int32", "type": "integer" } }, { "description": "Field to order by", "example": "id", "in": "query", "name": "sort", "required": false, "schema": { "type": "string" } }, { "description": "Order direction (ASC/DESC)", "example": "asc", "in": "query", "name": "dir", "required": false, "schema": { "type": "string" } }, { "description": "Forward keyset cursor (for keyset pagination)", "in": "query", "name": "after", "required": false, "schema": { "type": "string" } }, { "description": "Backward keyset cursor (for keyset pagination)", "in": "query", "name": "before", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/KeysetResultOAuthApplicationListView" } } }, "description": "OK" }, "default": { "description": "Every failure returns this envelope; the HTTP status carries the category.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "summary": "List a user's OAuth applications", "tags": [ "OAuth Applications" ] } }, "/users/{uid}/password": { "put": { "description": "Sets a new account password and invalidates all active sessions. If the account has a second factor, this also needs sudo mode or that factor.", "operationId": "putUsersByUidPassword", "parameters": [ { "description": "User ID, or @me for the current user", "in": "path", "name": "uid", "required": true, "schema": { "example": "@me", "pattern": "^(@me|[0-9]{1,19})$", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdatePasswordRequest" } } }, "required": true }, "responses": { "202": { "description": "Accepted", "headers": { "X-Sudo-Expires": { "description": "When sudo mode ends, sent when the request starts or extends it", "schema": { "format": "date-time", "type": "string" } } } }, "403": { "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ApiError" }, { "$ref": "#/components/schemas/MfaChallenge" } ] } } }, "description": "Forbidden, or `MfaChallenge` when a second factor is needed" }, "default": { "description": "Every failure returns this envelope; the HTTP status carries the category.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "summary": "Update the account password", "tags": [ "User settings" ], "x-api-elevation": "conditional" } }, "/users/{uid}/payment-methods": { "get": { "description": "Keyset-paginated stored payment methods for the given user, newest first. Exactly one carries is_default, the method charged when no one is present.", "operationId": "getUsersByUidPaymentMethods", "parameters": [ { "description": "User id, or @me for the current user", "in": "path", "name": "uid", "required": true, "schema": { "example": "@me", "pattern": "^(@me|[0-9]{1,19})$", "type": "string" } }, { "description": "Quick search by user id, card brand, or last four", "in": "query", "name": "q", "required": false, "schema": { "type": "string" } }, { "description": "Payment method ids to filter", "in": "query", "name": "id", "required": false, "schema": { "items": { "example": "1456074443980800000", "type": "string" }, "type": "array" } }, { "description": "Account ids to filter", "in": "query", "name": "account_id", "required": false, "schema": { "items": { "example": "1456074443980800000", "type": "string" }, "type": "array" } }, { "description": "User ids to filter", "in": "query", "name": "user", "required": false, "schema": { "items": { "example": "1053072706808680448", "type": "string" }, "type": "array" } }, { "description": "Gateways to filter", "in": "query", "name": "gateway", "required": false, "schema": { "items": { "enum": [ "STRIPE", "PAYPAL", "MANUAL" ], "type": "string" }, "type": "array" } }, { "description": "Card brand to match, e.g. visa", "in": "query", "name": "brand", "required": false, "schema": { "type": "string" } }, { "description": "Card last four to match", "in": "query", "name": "last4", "required": false, "schema": { "type": "string" } }, { "description": "Only the account's default method", "in": "query", "name": "is_default", "required": false, "schema": { "type": "boolean" } }, { "description": "Created at or after this instant (ISO-8601)", "in": "query", "name": "created_after", "required": false, "schema": { "format": "date-time", "type": "string" } }, { "description": "Created at or before this instant (ISO-8601)", "in": "query", "name": "created_before", "required": false, "schema": { "format": "date-time", "type": "string" } }, { "description": "How many items to return", "example": 50, "in": "query", "name": "limit", "required": false, "schema": { "format": "int32", "type": "integer" } }, { "description": "Page number to fetch", "example": 1, "in": "query", "name": "page", "required": false, "schema": { "format": "int32", "type": "integer" } }, { "description": "Field to order by", "example": "id", "in": "query", "name": "sort", "required": false, "schema": { "type": "string" } }, { "description": "Order direction (ASC/DESC)", "example": "asc", "in": "query", "name": "dir", "required": false, "schema": { "type": "string" } }, { "description": "Forward keyset cursor (for keyset pagination)", "in": "query", "name": "after", "required": false, "schema": { "type": "string" } }, { "description": "Backward keyset cursor (for keyset pagination)", "in": "query", "name": "before", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/KeysetResultPaymentMethodView" } } }, "description": "OK" }, "default": { "description": "Every failure returns this envelope; the HTTP status carries the category.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "summary": "List a user's payment methods", "tags": [ "Payment methods" ] } }, "/users/{uid}/payment-methods/confirm": { "post": { "description": "Saves the method a completed checkout stored, so it is available immediately rather than once the gateway notifies us. Repeating it returns the same method. Responds with no content when the checkout stored nothing, which is the case for methods that cannot be charged later.", "operationId": "postUsersByUidPaymentMethodsConfirm", "parameters": [ { "description": "User id, or @me for the current user", "in": "path", "name": "uid", "required": true, "schema": { "example": "@me", "pattern": "^(@me|[0-9]{1,19})$", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmSetupRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentMethodView" } } }, "description": "The stored payment method, or no content when the checkout stored nothing" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "No account for that user, or the checkout belongs to another" }, "default": { "description": "Every failure returns this envelope; the HTTP status carries the category.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "summary": "Confirm a stored method", "tags": [ "Payment methods" ] } }, "/users/{uid}/payment-methods/setup": { "post": { "description": "Opens a checkout that stores a payment method without collecting money. Returns a client secret to mount in the browser; only methods that can be charged later are offered.", "operationId": "postUsersByUidPaymentMethodsSetup", "parameters": [ { "description": "User id, or @me for the current user", "in": "path", "name": "uid", "required": true, "schema": { "example": "@me", "pattern": "^(@me|[0-9]{1,19})$", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SetupCommand" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CheckoutResponse" } } }, "description": "The open checkout and its client secret" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "No account for that user" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "A concurrent request is already setting up this gateway" }, "default": { "description": "Every failure returns this envelope; the HTTP status carries the category.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "summary": "Open a checkout to store a method", "tags": [ "Payment methods" ] } }, "/users/{uid}/payments": { "get": { "description": "Keyset-paginated payments for the given user, newest first.", "operationId": "getUsersByUidPayments", "parameters": [ { "description": "User id, or @me for the current user", "in": "path", "name": "uid", "required": true, "schema": { "example": "@me", "pattern": "^(@me|[0-9]{1,19})$", "type": "string" } }, { "description": "Quick search by user id or gateway reference", "in": "query", "name": "q", "required": false, "schema": { "type": "string" } }, { "description": "Payment ids to filter", "in": "query", "name": "id", "required": false, "schema": { "items": { "example": "1456074443980800000", "type": "string" }, "type": "array" } }, { "description": "Account ids to filter", "in": "query", "name": "account_id", "required": false, "schema": { "items": { "example": "1456074443980800000", "type": "string" }, "type": "array" } }, { "description": "User ids to filter", "in": "query", "name": "user", "required": false, "schema": { "items": { "example": "1053072706808680448", "type": "string" }, "type": "array" } }, { "description": "Invoice ids to filter", "in": "query", "name": "invoice_id", "required": false, "schema": { "items": { "example": "1456074443980800000", "type": "string" }, "type": "array" } }, { "description": "Payment method ids to filter", "in": "query", "name": "payment_method_id", "required": false, "schema": { "items": { "example": "1456074443980800000", "type": "string" }, "type": "array" } }, { "description": "Gateways to filter", "in": "query", "name": "gateway", "required": false, "schema": { "items": { "enum": [ "STRIPE", "PAYPAL", "MANUAL" ], "type": "string" }, "type": "array" } }, { "description": "Directions to filter", "in": "query", "name": "direction", "required": false, "schema": { "items": { "enum": [ "INBOUND", "REFUND" ], "type": "string" }, "type": "array" } }, { "description": "Statuses to filter", "in": "query", "name": "status", "required": false, "schema": { "items": { "enum": [ "PENDING", "SUCCEEDED", "FAILED", "REFUNDED" ], "type": "string" }, "type": "array" } }, { "description": "Gateway reference to match", "in": "query", "name": "gateway_ref", "required": false, "schema": { "type": "string" } }, { "description": "Currency code to filter, e.g. USD", "in": "query", "name": "currency", "required": false, "schema": { "type": "string" } }, { "description": "Minimum amount in micro-USD (inclusive)", "in": "query", "name": "min_amount", "required": false, "schema": { "format": "int64", "type": "integer" } }, { "description": "Maximum amount in micro-USD (inclusive)", "in": "query", "name": "max_amount", "required": false, "schema": { "format": "int64", "type": "integer" } }, { "description": "Created at or after this instant (ISO-8601)", "in": "query", "name": "created_after", "required": false, "schema": { "format": "date-time", "type": "string" } }, { "description": "Created at or before this instant (ISO-8601)", "in": "query", "name": "created_before", "required": false, "schema": { "format": "date-time", "type": "string" } }, { "description": "Captured at or after this instant (ISO-8601)", "in": "query", "name": "captured_after", "required": false, "schema": { "format": "date-time", "type": "string" } }, { "description": "Captured at or before this instant (ISO-8601)", "in": "query", "name": "captured_before", "required": false, "schema": { "format": "date-time", "type": "string" } }, { "description": "How many items to return", "example": 50, "in": "query", "name": "limit", "required": false, "schema": { "format": "int32", "type": "integer" } }, { "description": "Page number to fetch", "example": 1, "in": "query", "name": "page", "required": false, "schema": { "format": "int32", "type": "integer" } }, { "description": "Field to order by", "example": "id", "in": "query", "name": "sort", "required": false, "schema": { "type": "string" } }, { "description": "Order direction (ASC/DESC)", "example": "asc", "in": "query", "name": "dir", "required": false, "schema": { "type": "string" } }, { "description": "Forward keyset cursor (for keyset pagination)", "in": "query", "name": "after", "required": false, "schema": { "type": "string" } }, { "description": "Backward keyset cursor (for keyset pagination)", "in": "query", "name": "before", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/KeysetResultPaymentView" } } }, "description": "OK" }, "default": { "description": "Every failure returns this envelope; the HTTP status carries the category.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "summary": "List a user's payments", "tags": [ "Payments" ] } }, "/users/{uid}/payments/checkout": { "post": { "description": "Opens a checkout session for the customer to pay an invoice, or to fund the wallet when no invoice is given. Returns a client secret to mount in the browser. The payment stays pending until the gateway confirms settlement, which is immediate for a card but can take days for a bank transfer or direct debit; whatever the customer pays with is stored for future charges when it can be. Resumes the session already collecting an invoice rather than opening a second.", "operationId": "postUsersByUidPaymentsCheckout", "parameters": [ { "description": "User id, or @me for the current user", "in": "path", "name": "uid", "required": true, "schema": { "example": "@me", "pattern": "^(@me|[0-9]{1,19})$", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CheckoutCommand" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CheckoutResponse" } } }, "description": "The open checkout and its client secret" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "A wallet funding amount outside $20 to $500" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "No account or wallet for that user, or no such invoice" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "The invoice is not open, already paid, or has another payment in flight" }, "default": { "description": "Every failure returns this envelope; the HTTP status carries the category.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "summary": "Open a checkout", "tags": [ "Payments" ] } }, "/users/{uid}/payments/topup": { "post": { "description": "Records a pending charge against the stored method the account pays with and settles it asynchronously; on success it funds the wallet with a TOPUP lot, settling a tied invoice or issuing a TOPUP receipt. Requires a stored method: to pay with a new one, open a checkout instead. Idempotent on the supplied key. Returns the pending payment.", "operationId": "postUsersByUidPaymentsTopup", "parameters": [ { "description": "User id, or @me for the current user", "in": "path", "name": "uid", "required": true, "schema": { "example": "@me", "pattern": "^(@me|[0-9]{1,19})$", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TopUpCommand" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentView" } } }, "description": "The pending payment" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "The amount is outside $20 to $500" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "No account or wallet for that user, or no such invoice" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "No stored default payment method, or the invoice is not collectible" }, "default": { "description": "Every failure returns this envelope; the HTTP status carries the category.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "summary": "Top up a wallet from the default payment method", "tags": [ "Payments" ] } }, "/users/{uid}/recovery-code": { "post": { "description": "Issues a new recovery code, shown only once, and returns the account lock code. The previous recovery code stops working. The lock code does not change.", "operationId": "postUsersByUidRecoveryCode", "parameters": [ { "description": "User ID, or @me for the current user", "in": "path", "name": "uid", "required": true, "schema": { "example": "@me", "pattern": "^(@me|[0-9]{1,19})$", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RecoveryCode" } } }, "description": "OK", "headers": { "X-Sudo-Expires": { "description": "When sudo mode ends, sent when the request starts or extends it", "schema": { "format": "date-time", "type": "string" } } } }, "403": { "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ApiError" }, { "$ref": "#/components/schemas/MfaChallenge" } ] } } }, "description": "Forbidden, or `MfaChallenge` when a second factor is needed" }, "default": { "description": "Every failure returns this envelope; the HTTP status carries the category.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "summary": "Replace the recovery code", "tags": [ "User settings" ], "x-api-elevation": "required" } }, "/users/{uid}/tokens": { "get": { "description": "Lists USER-scope tokens (both SESSION and API) bound to the given user account.\n", "operationId": "getUsersByUidTokens", "parameters": [ { "description": "User ID, or @me for the current user", "in": "path", "name": "uid", "required": true, "schema": { "example": "@me", "pattern": "^(@me|[0-9]{1,19})$", "type": "string" } }, { "description": "Quick search by name or ID", "in": "query", "name": "q", "required": false, "schema": { "type": "string" } }, { "description": "List of token IDs to filter", "in": "query", "name": "id", "required": false, "schema": { "items": { "example": "1479097389678620681", "type": "string" }, "type": "array" } }, { "description": "Token name to filter", "in": "query", "name": "name", "required": false, "schema": { "type": "string" } }, { "description": "Token origin to filter", "in": "query", "name": "origin", "required": false, "schema": { "enum": [ "SESSION", "API", "SYSTEM", "OAUTH" ], "type": "string" } }, { "description": "Token subject to filter", "in": "query", "name": "subject", "required": false, "schema": { "enum": [ "USER", "WORKSPACE", "RESOURCE" ], "type": "string" } }, { "description": "How many items to return", "example": 50, "in": "query", "name": "limit", "required": false, "schema": { "format": "int32", "type": "integer" } }, { "description": "Page number to fetch", "example": 1, "in": "query", "name": "page", "required": false, "schema": { "format": "int32", "type": "integer" } }, { "description": "Field to order by", "example": "id", "in": "query", "name": "sort", "required": false, "schema": { "type": "string" } }, { "description": "Order direction (ASC/DESC)", "example": "asc", "in": "query", "name": "dir", "required": false, "schema": { "type": "string" } }, { "description": "Forward keyset cursor (for keyset pagination)", "in": "query", "name": "after", "required": false, "schema": { "type": "string" } }, { "description": "Backward keyset cursor (for keyset pagination)", "in": "query", "name": "before", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/KeysetResultTokenListView" } } }, "description": "OK" }, "default": { "description": "Every failure returns this envelope; the HTTP status carries the category.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "summary": "List user-scope tokens", "tags": [ "Tokens" ] }, "post": { "description": "Creates an API token bound to the given user and limited to the supplied permission map. The plaintext\ncode is returned once, save it securely.\n", "operationId": "postUsersByUidTokens", "parameters": [ { "description": "User ID, or @me for the current user", "in": "path", "name": "uid", "required": true, "schema": { "example": "@me", "pattern": "^(@me|[0-9]{1,19})$", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TokenCreateRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TokenCreateResponse" } } }, "description": "OK", "headers": { "X-Sudo-Expires": { "description": "When sudo mode ends, sent when the request starts or extends it", "schema": { "format": "date-time", "type": "string" } } } }, "403": { "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ApiError" }, { "$ref": "#/components/schemas/MfaChallenge" } ] } } }, "description": "Forbidden, or `MfaChallenge` when a second factor is needed" }, "default": { "description": "Every failure returns this envelope; the HTTP status carries the category.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "summary": "Create a USER-scope API token", "tags": [ "Tokens" ], "x-api-elevation": "required" }, "delete": { "description": "Revokes all active SESSION (login) tokens for the given user. API tokens are not touched.\n", "operationId": "deleteUsersByUidTokens", "parameters": [ { "description": "User ID, or @me for the current user", "in": "path", "name": "uid", "required": true, "schema": { "example": "@me", "pattern": "^(@me|[0-9]{1,19})$", "type": "string" } } ], "responses": { "202": { "description": "Accepted" }, "default": { "description": "Every failure returns this envelope; the HTTP status carries the category.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "summary": "Revoke all user sessions", "tags": [ "Tokens" ] } }, "/users/{uid}/totp": { "put": { "description": "Finalizes the 2FA setup process. When this is the account's first second factor, the response carries\nthe recovery code, shown only once.\n", "operationId": "putUsersByUidTotp", "parameters": [ { "description": "User ID, or @me for the current user", "in": "path", "name": "uid", "required": true, "schema": { "example": "@me", "pattern": "^(@me|[0-9]{1,19})$", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TotpConfirmRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RecoveryCode" } } }, "description": "OK", "headers": { "X-Sudo-Expires": { "description": "When sudo mode ends, sent when the request starts or extends it", "schema": { "format": "date-time", "type": "string" } } } }, "403": { "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ApiError" }, { "$ref": "#/components/schemas/MfaChallenge" } ] } } }, "description": "Forbidden, or `MfaChallenge` when a second factor is needed" }, "default": { "description": "Every failure returns this envelope; the HTTP status carries the category.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "summary": "Finalizes 2FA setup process", "tags": [ "User settings" ], "x-api-elevation": "required" }, "post": { "description": "Initiates the 2FA setup process, a TOTP token will be returned and a confirmation call must be\nexecuted to finalize the setup.\n", "operationId": "postUsersByUidTotp", "parameters": [ { "description": "User ID, or @me for the current user", "in": "path", "name": "uid", "required": true, "schema": { "example": "@me", "pattern": "^(@me|[0-9]{1,19})$", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TotpCreated" } } }, "description": "OK", "headers": { "X-Sudo-Expires": { "description": "When sudo mode ends, sent when the request starts or extends it", "schema": { "format": "date-time", "type": "string" } } } }, "403": { "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ApiError" }, { "$ref": "#/components/schemas/MfaChallenge" } ] } } }, "description": "Forbidden, or `MfaChallenge` when a second factor is needed" }, "default": { "description": "Every failure returns this envelope; the HTTP status carries the category.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "summary": "Initiates 2FA setup process", "tags": [ "User settings" ], "x-api-elevation": "required" }, "delete": { "description": "Removes the authenticator app and signs out every session. Other second factors stay enrolled. Fails with\n`mfa_enforced` when it is the last one and a workspace the account belongs to requires two-factor\nauthentication.\n", "operationId": "deleteUsersByUidTotp", "parameters": [ { "description": "User ID, or @me for the current user", "in": "path", "name": "uid", "required": true, "schema": { "example": "@me", "pattern": "^(@me|[0-9]{1,19})$", "type": "string" } }, { "description": "Authenticator app code", "example": "000000", "in": "header", "name": "X-MFA", "schema": { "type": "string" } } ], "responses": { "202": { "description": "Accepted", "headers": { "X-Sudo-Expires": { "description": "When sudo mode ends, sent when the request starts or extends it", "schema": { "format": "date-time", "type": "string" } } } }, "403": { "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ApiError" }, { "$ref": "#/components/schemas/MfaChallenge" } ] } } }, "description": "Forbidden, or `MfaChallenge` when a second factor is needed" }, "default": { "description": "Every failure returns this envelope; the HTTP status carries the category.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "summary": "Removes the authenticator app", "tags": [ "User settings" ], "x-api-elevation": "required" } }, "/users/{uid}/wallet": { "get": { "description": "Returns the wallet and its current balance for the given user.", "operationId": "getUsersByUidWallet", "parameters": [ { "description": "User id, or @me for the current user", "in": "path", "name": "uid", "required": true, "schema": { "example": "@me", "pattern": "^(@me|[0-9]{1,19})$", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WalletView" } } }, "description": "The wallet and its current balance" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "No wallet for that user" }, "default": { "description": "Every failure returns this envelope; the HTTP status carries the category.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "summary": "Get a user's wallet balance", "tags": [ "Wallets" ] } }, "/users/{uid}/wallet/movements": { "get": { "description": "Keyset-paginated ledger movements for the user's wallet, newest first.", "operationId": "getUsersByUidWalletMovements", "parameters": [ { "description": "User id, or @me for the current user", "in": "path", "name": "uid", "required": true, "schema": { "example": "@me", "pattern": "^(@me|[0-9]{1,19})$", "type": "string" } }, { "description": "Quick search by reference, group reference, or entry id", "in": "query", "name": "q", "required": false, "schema": { "type": "string" } }, { "description": "Ledger entry ids to filter", "in": "query", "name": "id", "required": false, "schema": { "items": { "example": "1456074443980800000", "type": "string" }, "type": "array" } }, { "description": "Movement types to filter", "in": "query", "name": "type", "required": false, "schema": { "items": { "enum": [ "TOPUP", "USAGE_CHARGE", "FIXED_CHARGE", "INVOICE_SETTLEMENT", "REFUND", "ADJUSTMENT", "COUPON", "EXPIRY", "CANCEL_REFUND", "REPRICE_REFUND" ], "type": "string" }, "type": "array" } }, { "description": "Invoice ids to filter", "in": "query", "name": "invoice_id", "required": false, "schema": { "items": { "example": "1456074443980800000", "type": "string" }, "type": "array" } }, { "description": "Subject ids to filter", "in": "query", "name": "subject_id", "required": false, "schema": { "items": { "example": "1456074443980800000", "type": "string" }, "type": "array" } }, { "description": "Acting user ids to filter", "in": "query", "name": "actor", "required": false, "schema": { "items": { "example": "1053072706808680448", "type": "string" }, "type": "array" } }, { "description": "Reference to match", "in": "query", "name": "reference", "required": false, "schema": { "type": "string" } }, { "description": "Group reference to match", "in": "query", "name": "group_ref", "required": false, "schema": { "type": "string" } }, { "description": "Minimum amount in micro-USD (inclusive, signed)", "in": "query", "name": "min_amount", "required": false, "schema": { "format": "int64", "type": "integer" } }, { "description": "Maximum amount in micro-USD (inclusive, signed)", "in": "query", "name": "max_amount", "required": false, "schema": { "format": "int64", "type": "integer" } }, { "description": "Created at or after this instant (ISO-8601)", "in": "query", "name": "created_after", "required": false, "schema": { "format": "date-time", "type": "string" } }, { "description": "Created at or before this instant (ISO-8601)", "in": "query", "name": "created_before", "required": false, "schema": { "format": "date-time", "type": "string" } }, { "description": "How many items to return", "example": 50, "in": "query", "name": "limit", "required": false, "schema": { "format": "int32", "type": "integer" } }, { "description": "Page number to fetch", "example": 1, "in": "query", "name": "page", "required": false, "schema": { "format": "int32", "type": "integer" } }, { "description": "Field to order by", "example": "id", "in": "query", "name": "sort", "required": false, "schema": { "type": "string" } }, { "description": "Order direction (ASC/DESC)", "example": "asc", "in": "query", "name": "dir", "required": false, "schema": { "type": "string" } }, { "description": "Forward keyset cursor (for keyset pagination)", "in": "query", "name": "after", "required": false, "schema": { "type": "string" } }, { "description": "Backward keyset cursor (for keyset pagination)", "in": "query", "name": "before", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/KeysetResultLedgerEntryView" } } }, "description": "A page of ledger movements for the wallet" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "No wallet for that user" }, "default": { "description": "Every failure returns this envelope; the HTTP status carries the category.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "summary": "List a user's wallet movements", "tags": [ "Wallets" ] } }, "/users/{uid}/workspaces": { "get": { "description": "Lists the workspaces the given user belongs to, with filtering and paging.", "operationId": "getUsersByUidWorkspaces", "parameters": [ { "description": "User ID, or @me for the current user", "in": "path", "name": "uid", "required": true, "schema": { "example": "@me", "pattern": "^(@me|[0-9]{1,19})$", "type": "string" } }, { "description": "Quick search by name or ID", "in": "query", "name": "q", "required": false, "schema": { "type": "string" } }, { "description": "List of workspace IDs to filter", "in": "query", "name": "id", "required": false, "schema": { "items": { "example": "1405508720263180365", "type": "string" }, "type": "array" } }, { "description": "Workspace name to filter", "in": "query", "name": "name", "required": false, "schema": { "type": "string" } }, { "description": "List of owner user IDs to filter", "in": "query", "name": "owner", "required": false, "schema": { "items": { "example": "1405506895740940329", "type": "string" }, "type": "array" } }, { "description": "How many items to return", "example": 50, "in": "query", "name": "limit", "required": false, "schema": { "format": "int32", "type": "integer" } }, { "description": "Page number to fetch", "example": 1, "in": "query", "name": "page", "required": false, "schema": { "format": "int32", "type": "integer" } }, { "description": "Field to order by", "example": "id", "in": "query", "name": "sort", "required": false, "schema": { "type": "string" } }, { "description": "Order direction (ASC/DESC)", "example": "asc", "in": "query", "name": "dir", "required": false, "schema": { "type": "string" } }, { "description": "Forward keyset cursor (for keyset pagination)", "in": "query", "name": "after", "required": false, "schema": { "type": "string" } }, { "description": "Backward keyset cursor (for keyset pagination)", "in": "query", "name": "before", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/KeysetResultWorkspaceListView" } } }, "description": "OK" }, "default": { "description": "Every failure returns this envelope; the HTTP status carries the category.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "summary": "List a user's workspaces", "tags": [ "Workspaces" ] }, "post": { "description": "Creates a workspace owned by the given user.", "operationId": "postUsersByUidWorkspaces", "parameters": [ { "description": "User ID, or @me for the current user", "in": "path", "name": "uid", "required": true, "schema": { "example": "@me", "pattern": "^(@me|[0-9]{1,19})$", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateWorkspaceRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkspaceListView" } } }, "description": "OK" }, "default": { "description": "Every failure returns this envelope; the HTTP status carries the category.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "summary": "Create a workspace", "tags": [ "Workspaces" ] } }, "/verify-email": { "post": { "operationId": "postVerifyEmail", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VerifyEmailRequest" } } }, "required": true }, "responses": { "202": { "description": "Accepted" }, "default": { "description": "Every failure returns this envelope; the HTTP status carries the category.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "tags": [ "email-controller" ], "x-api-modifiers": [ "open" ], "security": [] } }, "/vpcs/{vid}": { "get": { "operationId": "getVpcsByVid", "parameters": [ { "description": "VPC ID", "in": "path", "name": "vid", "required": true, "schema": { "example": "1463882832936980610", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VpcListView" } } }, "description": "OK" }, "default": { "description": "Every failure returns this envelope; the HTTP status carries the category.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "summary": "Fetch VPC details", "tags": [ "VPCs" ] }, "delete": { "operationId": "deleteVpcsByVid", "parameters": [ { "description": "VPC ID", "in": "path", "name": "vid", "required": true, "schema": { "example": "1463882832936980610", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkflowData" } } }, "description": "OK" }, "default": { "description": "Every failure returns this envelope; the HTTP status carries the category.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "summary": "Delete VPC", "tags": [ "VPCs" ] }, "patch": { "operationId": "patchVpcsByVid", "parameters": [ { "description": "VPC ID", "in": "path", "name": "vid", "required": true, "schema": { "example": "1463882832936980610", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VpcListView" } } }, "description": "OK" }, "default": { "description": "Every failure returns this envelope; the HTTP status carries the category.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "summary": "Update VPC", "tags": [ "VPCs" ] } }, "/vpcs/{vid}/instances": { "get": { "operationId": "getVpcsByVidInstances", "parameters": [ { "description": "VPC ID", "in": "path", "name": "vid", "required": true, "schema": { "example": "1463882832936980610", "type": "string" } }, { "description": "Quick search by instance name or ID", "in": "query", "name": "q", "required": false, "schema": { "type": "string" } }, { "description": "How many items to return", "example": 50, "in": "query", "name": "limit", "required": false, "schema": { "format": "int32", "type": "integer" } }, { "description": "Page number to fetch", "example": 1, "in": "query", "name": "page", "required": false, "schema": { "format": "int32", "type": "integer" } }, { "description": "Field to order by", "example": "id", "in": "query", "name": "sort", "required": false, "schema": { "type": "string" } }, { "description": "Order direction (ASC/DESC)", "example": "asc", "in": "query", "name": "dir", "required": false, "schema": { "type": "string" } }, { "description": "Forward keyset cursor (for keyset pagination)", "in": "query", "name": "after", "required": false, "schema": { "type": "string" } }, { "description": "Backward keyset cursor (for keyset pagination)", "in": "query", "name": "before", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/KeysetResultVpcInstanceListView" } } }, "description": "OK" }, "default": { "description": "Every failure returns this envelope; the HTTP status carries the category.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "summary": "Search VPC instances", "tags": [ "VPCs" ] } }, "/vpcs/{vid}/router": { "put": { "description": "Offers the router's VPC address as the default route to every other port on the VPC. Instances pick it up on their next network lease renewal.", "operationId": "putVpcsByVidRouter", "parameters": [ { "description": "VPC ID", "in": "path", "name": "vid", "required": true, "schema": { "example": "1463882832936980610", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RouterRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VpcListView" } } }, "description": "OK" }, "default": { "description": "Every failure returns this envelope; the HTTP status carries the category.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "summary": "Set or clear VPC router", "tags": [ "VPCs" ] } }, "/webhooks/{gateway}": { "post": { "description": "Parses and normalizes a raw gateway event and records it. A first delivery is applied asynchronously to the tied payment; a re-delivered event with the same reference is ignored and moves no money. Always returns 200 with the recorded outcome (RECEIVED, or IGNORED for a duplicate).", "operationId": "postWebhooksByGateway", "parameters": [ { "description": "Originating gateway", "in": "path", "name": "gateway", "required": true, "schema": { "enum": [ "STRIPE", "PAYPAL", "MANUAL" ], "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "format": "byte", "type": "string" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookResponse" } } }, "description": "The recorded outcome" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "The same event is being ingested concurrently; retry" }, "default": { "description": "Every failure returns this envelope; the HTTP status carries the category.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "summary": "Ingest a gateway webhook", "tags": [ "Webhooks" ], "x-api-modifiers": [ "open" ], "security": [] } }, "/workflows/{wfid}": { "get": { "operationId": "getWorkflowsByWfid", "parameters": [ { "example": "9f2c1d7a-4b83-4c1e-9a55-6d0f3b8e27c4", "in": "path", "name": "wfid", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkflowData" } } }, "description": "OK" }, "default": { "description": "Every failure returns this envelope; the HTTP status carries the category.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "tags": [ "workflow-controller" ] } }, "/workspaces/{wid}": { "get": { "description": "Retrieves a workspace you belong to by its id.", "operationId": "getWorkspacesByWid", "parameters": [ { "in": "path", "name": "wid", "required": true, "schema": { "example": "1405508720263180365", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkspaceListView" } } }, "description": "OK" }, "default": { "description": "Every failure returns this envelope; the HTTP status carries the category.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "summary": "Fetch a workspace", "tags": [ "Workspaces" ] }, "delete": { "description": "Permanently deletes the workspace and all of its data. The workspace must be empty, so delete its\nresources first.\n", "operationId": "deleteWorkspacesByWid", "parameters": [ { "in": "path", "name": "wid", "required": true, "schema": { "example": "1405508720263180365", "type": "string" } } ], "responses": { "204": { "description": "No Content", "headers": { "X-Sudo-Expires": { "description": "When sudo mode ends, sent when the request starts or extends it", "schema": { "format": "date-time", "type": "string" } } } }, "403": { "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ApiError" }, { "$ref": "#/components/schemas/MfaChallenge" } ] } } }, "description": "Forbidden, or `MfaChallenge` when a second factor is needed" }, "default": { "description": "Every failure returns this envelope; the HTTP status carries the category.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "summary": "Delete a workspace", "tags": [ "Workspaces" ], "x-api-elevation": "required" }, "patch": { "description": "Updates the workspace settings.", "operationId": "patchWorkspacesByWid", "parameters": [ { "in": "path", "name": "wid", "required": true, "schema": { "example": "1405508720263180365", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PatchWorkspaceRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkspaceListView" } } }, "description": "OK" }, "default": { "description": "Every failure returns this envelope; the HTTP status carries the category.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "summary": "Update a workspace", "tags": [ "Workspaces" ] } }, "/workspaces/{wid}/apps": { "get": { "description": "Lists all apps owned by the given workspace with keyset pagination and optional filtering.", "operationId": "getWorkspacesByWidApps", "parameters": [ { "description": "Workspace ID", "in": "path", "name": "wid", "required": true, "schema": { "example": "1405508720263180365", "type": "string" } }, { "description": "Quick search by name, image, or ID", "in": "query", "name": "q", "required": false, "schema": { "type": "string" } }, { "description": "Filter by app name (partial match)", "in": "query", "name": "name", "required": false, "schema": { "type": "string" } }, { "description": "Filter by docker image (partial match)", "in": "query", "name": "image", "required": false, "schema": { "type": "string" } }, { "description": "Filter by app state", "in": "query", "name": "state", "required": false, "schema": { "enum": [ "PENDING", "AVAILABLE", "FAILED", "SUSPENDED", "DELETING", "UNPLACED" ], "type": "string" } }, { "description": "Filter by instance ID", "in": "query", "name": "instance", "required": false, "schema": { "example": "1463106077196308568", "type": "string" } }, { "description": "How many items to return", "example": 50, "in": "query", "name": "limit", "required": false, "schema": { "format": "int32", "type": "integer" } }, { "description": "Page number to fetch", "example": 1, "in": "query", "name": "page", "required": false, "schema": { "format": "int32", "type": "integer" } }, { "description": "Field to order by", "example": "id", "in": "query", "name": "sort", "required": false, "schema": { "type": "string" } }, { "description": "Order direction (ASC/DESC)", "example": "asc", "in": "query", "name": "dir", "required": false, "schema": { "type": "string" } }, { "description": "Forward keyset cursor (for keyset pagination)", "in": "query", "name": "after", "required": false, "schema": { "type": "string" } }, { "description": "Backward keyset cursor (for keyset pagination)", "in": "query", "name": "before", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/KeysetResultOptionallyEnrichedAppViewContainerLiveStats" } } }, "description": "OK" }, "default": { "description": "Every failure returns this envelope; the HTTP status carries the category.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "summary": "List apps in a workspace", "tags": [ "Apps" ] } }, "/workspaces/{wid}/audit": { "get": { "description": "Lists the actions performed in a workspace, newest first.", "operationId": "getWorkspacesByWidAudit", "parameters": [ { "description": "Workspace ID", "in": "path", "name": "wid", "required": true, "schema": { "example": "1405508720263180365", "type": "string" } }, { "description": "Actions to filter", "in": "query", "name": "action", "required": false, "schema": { "items": { "description": "Action recorded by an audit log entry", "enum": [ "INSTANCE_CREATED", "INSTANCE_TERMINATED", "INSTANCE_TERMINATION_SCHEDULED", "INSTANCE_TERMINATION_CANCELLED", "INSTANCE_POWER_ON", "INSTANCE_POWER_OFF", "INSTANCE_POWER_CYCLE", "INSTANCE_SHUTDOWN", "INSTANCE_POWER", "INSTANCE_SUSPENDED", "INSTANCE_RESUMED", "INSTANCE_NETWORK_SUSPENDED", "INSTANCE_NETWORK_RESUMED", "INSTANCE_BOOT_CHANGED", "INSTANCE_AUTOSTART_CHANGED", "INSTANCE_VIRTIO_CD_CHANGED", "INSTANCE_FIRMWARE_CHANGED", "INSTANCE_OS_CHANGED", "INSTANCE_TIMEZONE_CHANGED", "INSTANCE_CLOUD_INIT_UPDATED", "INSTANCE_HOSTNAME_CHANGED", "INSTANCE_PASSWORD_RESET", "INSTANCE_SSH_KEYS_SYNCED", "INSTANCE_RECIPE_INSTALLED", "INSTANCE_UPGRADED", "INSTANCE_UPGRADES_APPLIED", "INSTANCE_MIGRATION_STARTED", "INSTANCE_TRANSFERRED", "INSTANCE_REINSTALLED", "INSTANCE_PACKET_CAPTURE_STARTED", "SNAPSHOT_CREATED", "SNAPSHOT_DELETED", "SNAPSHOT_RESTORED", "BACKUP_CREATED", "BACKUP_RESTORED", "ISO_ATTACHED", "ISO_DETACHED", "VPC_ATTACHED", "VPC_DETACHED", "FIREWALL_RULE_CREATED", "FIREWALL_RULE_UPDATED", "FIREWALL_RULE_DELETED", "FIREWALL_UPDATED", "FIREWALL_RESET", "IP_ATTACHED", "IP_DETACHED", "IP_AUTO_ASSIGNED", "IP_RELEASED", "IP_ROTATED", "IP_PROTECTION_CHANGED", "ISO_UPLOADED", "ISO_IMPORTED", "TEMPLATE_CREATED", "TEMPLATE_IMPORTED", "IMAGE_DELETED", "VPC_DELETED", "VPC_ROUTER_CHANGED", "RECIPE_CREATED", "RECIPE_UPDATED", "RECIPE_DELETED", "DEDIBOX_POWER_ON", "DEDIBOX_POWER_OFF", "DEDIBOX_POWER_CYCLE", "DEDIBOX_SHUTDOWN", "DEDIBOX_RECONFIGURED", "DEDIBOX_VNC_RESET", "TOKEN_CREATED", "TOKEN_DELETED", "TOKEN_EXPOSED_REVOKED", "ACCOUNT_REGISTERED", "ACCOUNT_LOGIN_PASSWORD", "ACCOUNT_LOGIN_SSO", "ACCOUNT_LOGIN_PASSKEY", "ACCOUNT_LOGIN_PASSWORD_FAILED", "ACCOUNT_LOGIN_SSO_FAILED", "ACCOUNT_LOGIN_PASSKEY_FAILED", "ACCOUNT_LOGOUT", "ACCOUNT_SESSIONS_REVOKED", "ACCOUNT_SESSION_LOCATION_REVOKED", "ACCOUNT_RENAMED", "ACCOUNT_EMAIL_CHANGE_REQUESTED", "ACCOUNT_EMAIL_CHANGED", "ACCOUNT_EMAIL_VERIFIED", "ACCOUNT_EMAIL_UNVERIFIED", "ACCOUNT_PASSWORD_CHANGED", "ACCOUNT_PASSWORD_RESET_REQUESTED", "ACCOUNT_PASSWORD_RESET", "ACCOUNT_PASSWORD_CLEARED", "ACCOUNT_MFA_ENABLED", "ACCOUNT_MFA_DISABLED", "ACCOUNT_RECOVERY_CODE_REGENERATED", "ACCOUNT_CREDENTIAL_ADDED", "ACCOUNT_CREDENTIAL_RENAMED", "ACCOUNT_CREDENTIAL_REMOVED", "ACCOUNT_IDENTITY_LINKED", "ACCOUNT_IDENTITY_UNLINKED", "ACCOUNT_LOCKED", "ACCOUNT_UNLOCKED", "ACCOUNT_BILLING_LINK_CHANGED", "ACCOUNT_DELETED", "OAUTH_APPLICATION_AUTHORIZED", "OAUTH_APPLICATION_DEAUTHORIZED", "OAUTH_TOKEN_ISSUED", "OAUTH_TOKEN_REFRESHED", "OAUTH_TOKEN_REVOKED", "OAUTH_APPLICATION_CREATED", "OAUTH_APPLICATION_UPDATED", "OAUTH_APPLICATION_DELETED", "OAUTH_APPLICATION_SECRET_REGENERATED", "WORKSPACE_CREATED", "WORKSPACE_RENAMED", "WORKSPACE_SETTINGS_CHANGED", "WORKSPACE_DELETED", "MEMBER_INVITED", "MEMBER_INVITE_UPDATED", "MEMBER_INVITE_REVOKED", "MEMBER_JOINED", "MEMBER_ROLE_CHANGED", "MEMBER_PERMISSIONS_CHANGED", "MEMBER_REMOVED", "SSH_KEY_ADDED", "SSH_KEY_DELETED", "REGISTRY_CREDENTIAL_ADDED", "REGISTRY_CREDENTIAL_UPDATED", "REGISTRY_CREDENTIAL_DELETED" ], "type": "string" }, "type": "array" } }, { "description": "Kind of resource the entries are filed under", "in": "query", "name": "target_kind", "required": false, "schema": { "description": "Kind of resource an audit log entry is filed under", "enum": [ "INSTANCE", "DEDIBOX", "IMAGE", "VPC", "RECIPE", "FLOATING_IP", "TOKEN", "USER", "OAUTH_APPLICATION", "WORKSPACE", "SSH_KEY", "REGISTRY_CREDENTIAL" ], "type": "string" } }, { "description": "IDs of the resources the entries are filed under", "in": "query", "name": "target_id", "required": false, "schema": { "items": { "example": "1463106077196308568", "type": "string" }, "type": "array" } }, { "description": "Kind of principal that performed the action", "in": "query", "name": "actor_type", "required": false, "schema": { "description": "Kind of principal that performed an audited action", "enum": [ "USER", "TOKEN", "SYSTEM", "ANONYMOUS", "APPLICATION" ], "type": "string" } }, { "description": "IDs of the users or tokens that performed the action", "in": "query", "name": "actor_id", "required": false, "schema": { "items": { "example": "1053072706808680448", "type": "string" }, "type": "array" } }, { "description": "Only entries for the given workflow", "in": "query", "name": "workflow_id", "required": false, "schema": { "type": "string" } }, { "description": "Only entries at or after this time", "example": "2026-03-01T00:00:00Z", "in": "query", "name": "since", "required": false, "schema": { "format": "date-time", "type": "string" } }, { "description": "Only entries before this time", "example": "2026-04-01T00:00:00Z", "in": "query", "name": "until", "required": false, "schema": { "format": "date-time", "type": "string" } }, { "description": "Only entries from this address, or from any address in this CIDR range", "example": "203.0.113.0/24", "in": "query", "name": "ip", "required": false, "schema": { "type": "string" } }, { "description": "Autonomous system numbers the actor's address belongs to", "in": "query", "name": "asn", "required": false, "schema": { "items": { "example": "3320", "type": "string" }, "type": "array" } }, { "description": "ISO 3166-1 alpha-2 countries of the actor's address", "in": "query", "name": "country", "required": false, "schema": { "items": { "example": "DE", "type": "string" }, "type": "array" } }, { "description": "Kind of network the actor's address belongs to", "in": "query", "name": "network_type", "required": false, "schema": { "enum": [ "PROXY", "DATACENTER", "RESIDENTIAL", "UNKNOWN" ], "type": "string" } }, { "description": "How many items to return", "example": 50, "in": "query", "name": "limit", "required": false, "schema": { "format": "int32", "type": "integer" } }, { "description": "Page number to fetch", "example": 1, "in": "query", "name": "page", "required": false, "schema": { "format": "int32", "type": "integer" } }, { "description": "Field to order by", "example": "id", "in": "query", "name": "sort", "required": false, "schema": { "type": "string" } }, { "description": "Order direction (ASC/DESC)", "example": "asc", "in": "query", "name": "dir", "required": false, "schema": { "type": "string" } }, { "description": "Forward keyset cursor (for keyset pagination)", "in": "query", "name": "after", "required": false, "schema": { "type": "string" } }, { "description": "Backward keyset cursor (for keyset pagination)", "in": "query", "name": "before", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/KeysetResultAuditLogView" } } }, "description": "OK" }, "default": { "description": "Every failure returns this envelope; the HTTP status carries the category.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "summary": "Search the audit log", "tags": [ "Audit log" ] } }, "/workspaces/{wid}/audit/{aid}": { "get": { "operationId": "getWorkspacesByWidAuditByAid", "parameters": [ { "description": "Workspace ID", "in": "path", "name": "wid", "required": true, "schema": { "example": "1405508720263180365", "type": "string" } }, { "description": "Audit log entry ID", "in": "path", "name": "aid", "required": true, "schema": { "example": "1498223722102817012", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuditLogView" } } }, "description": "OK" }, "default": { "description": "Every failure returns this envelope; the HTTP status carries the category.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "summary": "Fetch an audit log entry", "tags": [ "Audit log" ] } }, "/workspaces/{wid}/bgp": { "get": { "operationId": "getWorkspacesByWidBgp", "parameters": [ { "in": "path", "name": "wid", "required": true, "schema": { "example": "1405508720263180365", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BgpResponse" } } }, "description": "OK" }, "default": { "description": "Every failure returns this envelope; the HTTP status carries the category.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "tags": [ "bgp-controller" ] } }, "/workspaces/{wid}/bgp/prefixes": { "get": { "operationId": "getWorkspacesByWidBgpPrefixes", "parameters": [ { "in": "path", "name": "wid", "required": true, "schema": { "example": "1405508720263180365", "type": "string" } }, { "description": "List of IDs to filter", "in": "query", "name": "id", "required": false, "schema": { "items": { "example": "1463882832936980610", "type": "string" }, "type": "array" } }, { "description": "Prefix definition to filter", "in": "query", "name": "prefix", "required": false, "schema": { "type": "string" } }, { "description": "Source of prefix", "in": "query", "name": "source", "required": false, "schema": { "enum": [ "MANUAL" ], "type": "string" } }, { "description": "If announcements are enabled", "in": "query", "name": "enabled", "required": false, "schema": { "type": "boolean" } }, { "description": "How many items to return", "example": 50, "in": "query", "name": "limit", "required": false, "schema": { "format": "int32", "type": "integer" } }, { "description": "Page number to fetch", "example": 1, "in": "query", "name": "page", "required": false, "schema": { "format": "int32", "type": "integer" } }, { "description": "Field to order by", "example": "id", "in": "query", "name": "sort", "required": false, "schema": { "type": "string" } }, { "description": "Order direction (ASC/DESC)", "example": "asc", "in": "query", "name": "dir", "required": false, "schema": { "type": "string" } }, { "description": "Forward keyset cursor (for keyset pagination)", "in": "query", "name": "after", "required": false, "schema": { "type": "string" } }, { "description": "Backward keyset cursor (for keyset pagination)", "in": "query", "name": "before", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/KeysetResultBgpPrefixListView" } } }, "description": "OK" }, "default": { "description": "Every failure returns this envelope; the HTTP status carries the category.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "tags": [ "bgp-controller" ] } }, "/workspaces/{wid}/dedibox": { "get": { "description": "Searches for dediboxes assigned to a workspace.\n", "operationId": "getWorkspacesByWidDedibox", "parameters": [ { "description": "Workspace ID", "in": "path", "name": "wid", "required": true, "schema": { "example": "1405508720263180365", "type": "string" } }, { "description": "Quick search by name or ID", "in": "query", "name": "q", "required": false, "schema": { "type": "string" } }, { "description": "List of dedibox IDs to filter", "in": "query", "name": "id", "required": false, "schema": { "items": { "example": "1326819038986244108", "type": "string" }, "type": "array" } }, { "description": "Dedibox name to filter", "in": "query", "name": "name", "required": false, "schema": { "type": "string" } }, { "description": "Region to filter", "in": "query", "name": "region", "required": false, "schema": { "enum": [ "NA_01" ], "type": "string" } }, { "description": "Filter by online status", "in": "query", "name": "online", "required": false, "schema": { "type": "boolean" } }, { "description": "How many items to return", "example": 50, "in": "query", "name": "limit", "required": false, "schema": { "format": "int32", "type": "integer" } }, { "description": "Page number to fetch", "example": 1, "in": "query", "name": "page", "required": false, "schema": { "format": "int32", "type": "integer" } }, { "description": "Field to order by", "example": "id", "in": "query", "name": "sort", "required": false, "schema": { "type": "string" } }, { "description": "Order direction (ASC/DESC)", "example": "asc", "in": "query", "name": "dir", "required": false, "schema": { "type": "string" } }, { "description": "Forward keyset cursor (for keyset pagination)", "in": "query", "name": "after", "required": false, "schema": { "type": "string" } }, { "description": "Backward keyset cursor (for keyset pagination)", "in": "query", "name": "before", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/KeysetResultEnrichedDediboxListViewDediboxLive" } } }, "description": "OK" }, "default": { "description": "Every failure returns this envelope; the HTTP status carries the category.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "summary": "Search for dediboxes", "tags": [ "Dedibox" ] } }, "/workspaces/{wid}/dedibox/ips": { "get": { "operationId": "getWorkspacesByWidDediboxIps", "parameters": [ { "in": "path", "name": "wid", "required": true, "schema": { "example": "1405508720263180365", "type": "string" } }, { "description": "Quick search by address or ID", "in": "query", "name": "q", "required": false, "schema": { "type": "string" } }, { "description": "List of IP IDs to filter", "in": "query", "name": "id", "required": false, "schema": { "items": { "example": "1464201868476432440", "type": "string" }, "type": "array" } }, { "description": "List of dedibox IDs to filter", "in": "query", "name": "dedibox", "required": false, "schema": { "items": { "example": "1326819038986244108", "type": "string" }, "type": "array" } }, { "description": "Address to filter", "in": "query", "name": "address", "required": false, "schema": { "type": "string" } }, { "description": "Filter by IP type", "in": "query", "name": "type", "required": false, "schema": { "enum": [ "IPv4", "IPv6" ], "type": "string" } }, { "description": "How many items to return", "example": 50, "in": "query", "name": "limit", "required": false, "schema": { "format": "int32", "type": "integer" } }, { "description": "Page number to fetch", "example": 1, "in": "query", "name": "page", "required": false, "schema": { "format": "int32", "type": "integer" } }, { "description": "Field to order by", "example": "id", "in": "query", "name": "sort", "required": false, "schema": { "type": "string" } }, { "description": "Order direction (ASC/DESC)", "example": "asc", "in": "query", "name": "dir", "required": false, "schema": { "type": "string" } }, { "description": "Forward keyset cursor (for keyset pagination)", "in": "query", "name": "after", "required": false, "schema": { "type": "string" } }, { "description": "Backward keyset cursor (for keyset pagination)", "in": "query", "name": "before", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/KeysetResultDediboxIpListView" } } }, "description": "OK" }, "default": { "description": "Every failure returns this envelope; the HTTP status carries the category.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "tags": [ "dedibox-ip-controller" ] } }, "/workspaces/{wid}/disks": { "get": { "description": "Searches disks assigned to a workspace.\n", "operationId": "getWorkspacesByWidDisks", "parameters": [ { "description": "Workspace ID", "in": "path", "name": "wid", "required": true, "schema": { "example": "1405508720263180365", "type": "string" } }, { "description": "Quick search by name or ID", "in": "query", "name": "q", "required": false, "schema": { "type": "string" } }, { "description": "List of disk IDs to filter", "in": "query", "name": "id", "required": false, "schema": { "items": { "example": "1463106081390612571", "type": "string" }, "type": "array" } }, { "description": "List of instance IDs to filter", "in": "query", "name": "instance", "required": false, "schema": { "items": { "example": "1463106077196308568", "type": "string" }, "type": "array" } }, { "description": "List of workspace IDs to filter", "in": "query", "name": "owner", "required": false, "schema": { "items": { "example": "1405508720263180365", "type": "string" }, "type": "array" } }, { "description": "Disk name to filter", "in": "query", "name": "name", "required": false, "schema": { "type": "string" } }, { "description": "Filter by boot disk", "in": "query", "name": "boot", "required": false, "schema": { "type": "boolean" } }, { "description": "Filter by state", "in": "query", "name": "state", "required": false, "schema": { "items": { "enum": [ "PENDING", "AVAILABLE", "FAILED", "SUSPENDED", "DELETING", "UNPLACED" ], "type": "string" }, "type": "array" } }, { "description": "Filter by storage backend", "in": "query", "name": "backend", "required": false, "schema": { "items": { "enum": [ "LOCAL", "CEPH" ], "type": "string" }, "type": "array" } }, { "description": "How many items to return", "example": 50, "in": "query", "name": "limit", "required": false, "schema": { "format": "int32", "type": "integer" } }, { "description": "Page number to fetch", "example": 1, "in": "query", "name": "page", "required": false, "schema": { "format": "int32", "type": "integer" } }, { "description": "Field to order by", "example": "id", "in": "query", "name": "sort", "required": false, "schema": { "type": "string" } }, { "description": "Order direction (ASC/DESC)", "example": "asc", "in": "query", "name": "dir", "required": false, "schema": { "type": "string" } }, { "description": "Forward keyset cursor (for keyset pagination)", "in": "query", "name": "after", "required": false, "schema": { "type": "string" } }, { "description": "Backward keyset cursor (for keyset pagination)", "in": "query", "name": "before", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/KeysetResultOptionallyEnrichedDiskListViewDiskLive" } } }, "description": "OK" }, "default": { "description": "Every failure returns this envelope; the HTTP status carries the category.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "summary": "Search workspace disks", "tags": [ "Disks" ] } }, "/workspaces/{wid}/firewall": { "get": { "description": "Retrieves every instance in the workspace with its default policies and rule count. Instances with\nno rules are included: a rule count alone does not describe how filtered an instance is.\n", "operationId": "getWorkspacesByWidFirewall", "parameters": [ { "description": "Workspace ID", "in": "path", "name": "wid", "required": true, "schema": { "example": "1405508720263180365", "type": "string" } }, { "description": "How many items to return", "example": 50, "in": "query", "name": "limit", "required": false, "schema": { "format": "int32", "type": "integer" } }, { "description": "Page number to fetch", "example": 1, "in": "query", "name": "page", "required": false, "schema": { "format": "int32", "type": "integer" } }, { "description": "Field to order by", "example": "id", "in": "query", "name": "sort", "required": false, "schema": { "type": "string" } }, { "description": "Order direction (ASC/DESC)", "example": "asc", "in": "query", "name": "dir", "required": false, "schema": { "type": "string" } }, { "description": "Forward keyset cursor (for keyset pagination)", "in": "query", "name": "after", "required": false, "schema": { "type": "string" } }, { "description": "Backward keyset cursor (for keyset pagination)", "in": "query", "name": "before", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/KeysetResultInstanceFirewallView" } } }, "description": "OK" }, "default": { "description": "Every failure returns this envelope; the HTTP status carries the category.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "summary": "List firewall posture for a workspace", "tags": [ "Firewall" ] } }, "/workspaces/{wid}/images": { "get": { "operationId": "getWorkspacesByWidImages", "parameters": [ { "description": "Workspace ID", "in": "path", "name": "wid", "required": true, "schema": { "example": "1405508720263180365", "type": "string" } }, { "description": "Quick search by name or ID", "in": "query", "name": "q", "required": false, "schema": { "type": "string" } }, { "description": "List of image IDs to filter", "in": "query", "name": "id", "required": false, "schema": { "items": { "example": "1471181001588760790", "type": "string" }, "type": "array" } }, { "description": "Image name to filter", "in": "query", "name": "name", "required": false, "schema": { "type": "string" } }, { "description": "Image group to filter", "in": "query", "name": "group", "required": false, "schema": { "type": "string" } }, { "description": "Image description to filter", "in": "query", "name": "description", "required": false, "schema": { "type": "string" } }, { "description": "OS family to filter", "in": "query", "name": "os", "required": false, "schema": { "enum": [ "WINDOWS", "LINUX", "BSD", "OTHER" ], "type": "string" } }, { "description": "Filter by kind", "in": "query", "name": "kind", "required": false, "schema": { "items": { "enum": [ "TEMPLATE", "BACKUP", "ISO" ], "type": "string" }, "type": "array" } }, { "description": "Filter by source instance ID (for backups/snapshots)", "in": "query", "name": "source_instance", "required": false, "schema": { "items": { "example": "1463106077196308568", "type": "string" }, "type": "array" } }, { "description": "Filter by source disk ID (for backups/snapshots)", "in": "query", "name": "source_disk", "required": false, "schema": { "items": { "example": "1463106081390612571", "type": "string" }, "type": "array" } }, { "description": "Filter by official images (no owner)", "in": "query", "name": "official", "required": false, "schema": { "type": "boolean" } }, { "description": "Filter by deprecated images", "in": "query", "name": "deprecated", "required": false, "schema": { "type": "boolean" } }, { "description": "Filter by state", "in": "query", "name": "state", "required": false, "schema": { "items": { "enum": [ "PENDING", "AVAILABLE", "FAILED", "SUSPENDED", "DELETING", "UNPLACED" ], "type": "string" }, "type": "array" } }, { "description": "List of workspace IDs to filter", "in": "query", "name": "owner", "required": false, "schema": { "items": { "example": "1405508720263180365", "type": "string" }, "type": "array" } }, { "description": "How many items to return", "example": 50, "in": "query", "name": "limit", "required": false, "schema": { "format": "int32", "type": "integer" } }, { "description": "Page number to fetch", "example": 1, "in": "query", "name": "page", "required": false, "schema": { "format": "int32", "type": "integer" } }, { "description": "Field to order by", "example": "id", "in": "query", "name": "sort", "required": false, "schema": { "type": "string" } }, { "description": "Order direction (ASC/DESC)", "example": "asc", "in": "query", "name": "dir", "required": false, "schema": { "type": "string" } }, { "description": "Forward keyset cursor (for keyset pagination)", "in": "query", "name": "after", "required": false, "schema": { "type": "string" } }, { "description": "Backward keyset cursor (for keyset pagination)", "in": "query", "name": "before", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/KeysetResultImageListView" } } }, "description": "OK" }, "default": { "description": "Every failure returns this envelope; the HTTP status carries the category.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "summary": "List images visible to a workspace", "tags": [ "Images" ] }, "post": { "operationId": "postWorkspacesByWidImages", "parameters": [ { "description": "Workspace ID", "in": "path", "name": "wid", "required": true, "schema": { "example": "1405508720263180365", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/CreateBackupRequest" }, { "$ref": "#/components/schemas/CreateIsoRequest" }, { "$ref": "#/components/schemas/CreateTemplateRequest" } ], "discriminator": { "mapping": { "BACKUP": "#/components/schemas/CreateBackupRequest", "ISO": "#/components/schemas/CreateIsoRequest", "TEMPLATE": "#/components/schemas/CreateTemplateRequest" }, "propertyName": "kind" } } } }, "required": true }, "responses": { "202": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ImageCreateResponse" } } }, "description": "Accepted" }, "default": { "description": "Every failure returns this envelope; the HTTP status carries the category.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "summary": "Create an image in a workspace", "tags": [ "Images" ] } }, "/workspaces/{wid}/instances": { "get": { "description": "Searches for instances on a workspace.\n", "operationId": "getWorkspacesByWidInstances", "parameters": [ { "description": "Workspace ID", "in": "path", "name": "wid", "required": true, "schema": { "example": "1405508720263180365", "type": "string" } }, { "description": "Quick search by name, IP address, or ID", "in": "query", "name": "q", "required": false, "schema": { "type": "string" } }, { "description": "Filter by IP address (public or private)", "in": "query", "name": "ip", "required": false, "schema": { "type": "string" } }, { "description": "List of instance IDs to filter", "in": "query", "name": "id", "required": false, "schema": { "items": { "example": "1463106077196308568", "type": "string" }, "type": "array" } }, { "description": "Instance names to filter", "in": "query", "name": "name", "required": false, "schema": { "type": "string" } }, { "description": "List of node IDs to filter", "in": "query", "name": "node", "required": false, "schema": { "items": { "example": "1326819038986244108", "type": "string" }, "type": "array" } }, { "description": "List of products to filter", "in": "query", "name": "sku", "required": false, "schema": { "items": { "example": "lightning-1g", "type": "string" }, "type": "array" } }, { "description": "List of ISO IDs to filter", "in": "query", "name": "iso", "required": false, "schema": { "items": { "example": "1471181001588760790", "type": "string" }, "type": "array" } }, { "description": "Boot target to filter", "in": "query", "name": "boot", "required": false, "schema": { "enum": [ "DISK", "ISO" ], "type": "string" } }, { "description": "Filter for only online/offline instances", "in": "query", "name": "online", "required": false, "schema": { "type": "boolean" } }, { "description": "Filter for instances with a specific state", "in": "query", "name": "state", "required": false, "schema": { "items": { "enum": [ "PENDING", "AVAILABLE", "FAILED", "SUSPENDED", "DELETING", "UNPLACED" ], "type": "string" }, "type": "array" } }, { "description": "Filter for only instances scheduled for termination", "in": "query", "name": "terminating", "required": false, "schema": { "type": "boolean" } }, { "description": "List of backup plan IDs to filter", "in": "query", "name": "backup_plan", "required": false, "schema": { "items": { "example": "1506320201023500406", "type": "string" }, "type": "array" } }, { "description": "Filter for only instances in a specific region", "in": "query", "name": "region", "required": false, "schema": { "enum": [ "NA_01" ], "type": "string" } }, { "description": "List of VPC IDs to filter", "in": "query", "name": "vpc", "required": false, "schema": { "items": { "example": "1463882832936980610", "type": "string" }, "type": "array" } }, { "description": "Filter for instances with a specific OS family", "in": "query", "name": "os", "required": false, "schema": { "enum": [ "WINDOWS", "LINUX", "BSD", "OTHER" ], "type": "string" } }, { "description": "List of workspace IDs to filter", "in": "query", "name": "owner", "required": false, "schema": { "items": { "example": "1405508720263180365", "type": "string" }, "type": "array" } }, { "description": "How many items to return", "example": 50, "in": "query", "name": "limit", "required": false, "schema": { "format": "int32", "type": "integer" } }, { "description": "Page number to fetch", "example": 1, "in": "query", "name": "page", "required": false, "schema": { "format": "int32", "type": "integer" } }, { "description": "Field to order by", "example": "id", "in": "query", "name": "sort", "required": false, "schema": { "type": "string" } }, { "description": "Order direction (ASC/DESC)", "example": "asc", "in": "query", "name": "dir", "required": false, "schema": { "type": "string" } }, { "description": "Forward keyset cursor (for keyset pagination)", "in": "query", "name": "after", "required": false, "schema": { "type": "string" } }, { "description": "Backward keyset cursor (for keyset pagination)", "in": "query", "name": "before", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/KeysetResultEnrichedInstanceListViewInstanceLive" } } }, "description": "OK" }, "default": { "description": "Every failure returns this envelope; the HTTP status carries the category.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "summary": "Search instances", "tags": [ "Instances" ] } }, "/workspaces/{wid}/instances/{iid}/workflows": { "get": { "operationId": "getWorkspacesByWidInstancesByIidWorkflows", "parameters": [ { "in": "path", "name": "wid", "required": true, "schema": { "example": "1405508720263180365", "type": "string" } }, { "in": "path", "name": "iid", "required": true, "schema": { "example": "1463106077196308568", "type": "string" } }, { "description": "Quick search by workflow ID prefix, name prefix, instance, or workspace", "in": "query", "name": "q", "required": false, "schema": { "type": "string" } }, { "description": "List of workflow IDs to filter", "in": "query", "name": "id", "required": false, "schema": { "items": { "type": "string" }, "type": "array" } }, { "description": "Workflow name to filter (e.g. instance.power)", "in": "query", "name": "name", "required": false, "schema": { "type": "string" } }, { "description": "List of instance IDs to scope workflows to", "in": "query", "name": "instance", "required": false, "schema": { "items": { "example": "1463106077196308568", "type": "string" }, "type": "array" } }, { "description": "List of workspace IDs to scope workflows to", "in": "query", "name": "workspace", "required": false, "schema": { "items": { "example": "1405508720263180365", "type": "string" }, "type": "array" } }, { "description": "List of execution states to filter", "in": "query", "name": "status", "required": false, "schema": { "items": { "enum": [ "QUEUED", "RUNNING", "FAILED", "COMPLETED", "ABORTED", "TIMED_OUT" ], "type": "string" }, "type": "array" } }, { "description": "Filter workflows started at or after this timestamp (ISO-8601)", "in": "query", "name": "started_after", "required": false, "schema": { "example": "2026-04-27T00:00:00Z", "format": "date-time", "type": "string" } }, { "description": "Filter workflows started at or before this timestamp (ISO-8601)", "in": "query", "name": "started_before", "required": false, "schema": { "example": "2026-04-28T00:00:00Z", "format": "date-time", "type": "string" } }, { "description": "How many items to return", "example": 50, "in": "query", "name": "limit", "required": false, "schema": { "format": "int32", "type": "integer" } }, { "description": "Page number to fetch", "example": 1, "in": "query", "name": "page", "required": false, "schema": { "format": "int32", "type": "integer" } }, { "description": "Field to order by", "example": "id", "in": "query", "name": "sort", "required": false, "schema": { "type": "string" } }, { "description": "Order direction (ASC/DESC)", "example": "asc", "in": "query", "name": "dir", "required": false, "schema": { "type": "string" } }, { "description": "Forward keyset cursor (for keyset pagination)", "in": "query", "name": "after", "required": false, "schema": { "type": "string" } }, { "description": "Backward keyset cursor (for keyset pagination)", "in": "query", "name": "before", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/KeysetResultWorkflowData" } } }, "description": "OK" }, "default": { "description": "Every failure returns this envelope; the HTTP status carries the category.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "tags": [ "workflow-controller" ] } }, "/workspaces/{wid}/invites": { "get": { "description": "Lists pending invitations for a workspace, with filtering and paging.", "operationId": "getWorkspacesByWidInvites", "parameters": [ { "in": "path", "name": "wid", "required": true, "schema": { "example": "1405508720263180365", "type": "string" } }, { "description": "Quick search by email or ID", "in": "query", "name": "q", "required": false, "schema": { "type": "string" } }, { "description": "List of invite IDs to filter", "in": "query", "name": "id", "required": false, "schema": { "items": { "example": "1489276118237192255", "type": "string" }, "type": "array" } }, { "description": "Invited email to filter", "in": "query", "name": "email", "required": false, "schema": { "type": "string" } }, { "description": "Granted governance role to filter", "in": "query", "name": "role", "required": false, "schema": { "type": "string" } }, { "description": "List of workspace IDs to filter", "in": "query", "name": "workspace", "required": false, "schema": { "items": { "example": "1405508720263180365", "type": "string" }, "type": "array" } }, { "description": "How many items to return", "example": 50, "in": "query", "name": "limit", "required": false, "schema": { "format": "int32", "type": "integer" } }, { "description": "Page number to fetch", "example": 1, "in": "query", "name": "page", "required": false, "schema": { "format": "int32", "type": "integer" } }, { "description": "Field to order by", "example": "id", "in": "query", "name": "sort", "required": false, "schema": { "type": "string" } }, { "description": "Order direction (ASC/DESC)", "example": "asc", "in": "query", "name": "dir", "required": false, "schema": { "type": "string" } }, { "description": "Forward keyset cursor (for keyset pagination)", "in": "query", "name": "after", "required": false, "schema": { "type": "string" } }, { "description": "Backward keyset cursor (for keyset pagination)", "in": "query", "name": "before", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/KeysetResultInviteListView" } } }, "description": "OK" }, "default": { "description": "Every failure returns this envelope; the HTTP status carries the category.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "summary": "List workspace invites", "tags": [ "Workspaces" ] }, "post": { "description": "Invites an email to the workspace with a role and grants.", "operationId": "postWorkspacesByWidInvites", "parameters": [ { "in": "path", "name": "wid", "required": true, "schema": { "example": "1405508720263180365", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateInviteRequest" } } }, "required": true }, "responses": { "201": { "content": { "*/*": { "schema": { "$ref": "#/components/schemas/InviteView" } } }, "description": "Created" }, "default": { "description": "Every failure returns this envelope; the HTTP status carries the category.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "summary": "Create an invite", "tags": [ "Workspaces" ] } }, "/workspaces/{wid}/ips": { "get": { "description": "Searches for ips assigned to a workspace.\n", "operationId": "getWorkspacesByWidIps", "parameters": [ { "description": "Workspace ID", "in": "path", "name": "wid", "required": true, "schema": { "example": "1405508720263180365", "type": "string" } }, { "description": "Quick search by address or ID", "in": "query", "name": "q", "required": false, "schema": { "type": "string" } }, { "description": "Filter by IP address", "in": "query", "name": "address", "required": false, "schema": { "type": "string" } }, { "description": "List of instance IDs to filter", "in": "query", "name": "instance", "required": false, "schema": { "items": { "example": "1463106077196308568", "type": "string" }, "type": "array" } }, { "description": "Filter by unassigned IPs", "in": "query", "name": "available", "required": false, "schema": { "type": "boolean" } }, { "description": "Filter by reverse DNS value", "in": "query", "name": "dns", "required": false, "schema": { "type": "string" } }, { "description": "Filter by region", "in": "query", "name": "region", "required": false, "schema": { "enum": [ "NA_01" ], "type": "string" } }, { "description": "List of workspace IDs to filter", "in": "query", "name": "owner", "required": false, "schema": { "items": { "example": "1405508720263180365", "type": "string" }, "type": "array" } }, { "description": "Filter by IP type", "in": "query", "name": "type", "required": false, "schema": { "enum": [ "IPv4", "IPv6" ], "type": "string" } }, { "description": "How many items to return", "example": 50, "in": "query", "name": "limit", "required": false, "schema": { "format": "int32", "type": "integer" } }, { "description": "Page number to fetch", "example": 1, "in": "query", "name": "page", "required": false, "schema": { "format": "int32", "type": "integer" } }, { "description": "Field to order by", "example": "id", "in": "query", "name": "sort", "required": false, "schema": { "type": "string" } }, { "description": "Order direction (ASC/DESC)", "example": "asc", "in": "query", "name": "dir", "required": false, "schema": { "type": "string" } }, { "description": "Forward keyset cursor (for keyset pagination)", "in": "query", "name": "after", "required": false, "schema": { "type": "string" } }, { "description": "Backward keyset cursor (for keyset pagination)", "in": "query", "name": "before", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/KeysetResultFloatingIpListView" } } }, "description": "OK" }, "default": { "description": "Every failure returns this envelope; the HTTP status carries the category.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "summary": "Search ips on a workspace", "tags": [ "IPs" ] } }, "/workspaces/{wid}/members": { "get": { "description": "Lists workspace members with their role and writable kinds, with filtering and paging.", "operationId": "getWorkspacesByWidMembers", "parameters": [ { "description": "Workspace ID", "in": "path", "name": "wid", "required": true, "schema": { "example": "1405508720263180365", "type": "string" } }, { "description": "Quick search by ID, name or email", "in": "query", "name": "q", "required": false, "schema": { "type": "string" } }, { "description": "List of user IDs to filter", "in": "query", "name": "id", "required": false, "schema": { "items": { "example": "1405506895740940329", "type": "string" }, "type": "array" } }, { "description": "User name to filter, matching any part of the name", "in": "query", "name": "name", "required": false, "schema": { "type": "string" } }, { "description": "User email to filter, matching any part of the address", "in": "query", "name": "email", "required": false, "schema": { "type": "string" } }, { "description": "How many items to return", "example": 50, "in": "query", "name": "limit", "required": false, "schema": { "format": "int32", "type": "integer" } }, { "description": "Page number to fetch", "example": 1, "in": "query", "name": "page", "required": false, "schema": { "format": "int32", "type": "integer" } }, { "description": "Field to order by", "example": "id", "in": "query", "name": "sort", "required": false, "schema": { "type": "string" } }, { "description": "Order direction (ASC/DESC)", "example": "asc", "in": "query", "name": "dir", "required": false, "schema": { "type": "string" } }, { "description": "Forward keyset cursor (for keyset pagination)", "in": "query", "name": "after", "required": false, "schema": { "type": "string" } }, { "description": "Backward keyset cursor (for keyset pagination)", "in": "query", "name": "before", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/KeysetResultEnrichedMemberUserViewMemberGrants" } } }, "description": "OK" }, "default": { "description": "Every failure returns this envelope; the HTTP status carries the category.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "summary": "List members", "tags": [ "Workspace members" ] } }, "/workspaces/{wid}/members/{uid}": { "get": { "description": "Fetches one member with their role and all writable kinds.", "operationId": "getWorkspacesByWidMembersByUid", "parameters": [ { "description": "Workspace ID", "in": "path", "name": "wid", "required": true, "schema": { "example": "1405508720263180365", "type": "string" } }, { "description": "User ID, or @me for the current user", "in": "path", "name": "uid", "required": true, "schema": { "example": "@me", "pattern": "^(@me|[0-9]{1,19})$", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MemberView" } } }, "description": "OK" }, "default": { "description": "Every failure returns this envelope; the HTTP status carries the category.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "summary": "Fetch a member", "tags": [ "Workspace members" ] }, "put": { "description": "Changes an existing member's governance role.", "operationId": "putWorkspacesByWidMembersByUid", "parameters": [ { "description": "Workspace ID", "in": "path", "name": "wid", "required": true, "schema": { "example": "1405508720263180365", "type": "string" } }, { "description": "User ID of the member to manage", "in": "path", "name": "uid", "required": true, "schema": { "example": "1405506895740940329", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SetMemberRoleRequest" } } }, "required": true }, "responses": { "204": { "description": "No Content" }, "default": { "description": "Every failure returns this envelope; the HTTP status carries the category.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "summary": "Change a member's role", "tags": [ "Workspace members" ] }, "delete": { "description": "Removes an existing member and all their write grants.", "operationId": "deleteWorkspacesByWidMembersByUid", "parameters": [ { "description": "Workspace ID", "in": "path", "name": "wid", "required": true, "schema": { "example": "1405508720263180365", "type": "string" } }, { "description": "User ID of the member to manage", "in": "path", "name": "uid", "required": true, "schema": { "example": "1405506895740940329", "type": "string" } } ], "responses": { "204": { "description": "No Content" }, "default": { "description": "Every failure returns this envelope; the HTTP status carries the category.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "summary": "Remove a member", "tags": [ "Workspace members" ] } }, "/workspaces/{wid}/members/{uid}/grants": { "put": { "description": "Replaces an existing member's writable kinds with exactly the given set.", "operationId": "putWorkspacesByWidMembersByUidGrants", "parameters": [ { "description": "Workspace ID", "in": "path", "name": "wid", "required": true, "schema": { "example": "1405508720263180365", "type": "string" } }, { "description": "User ID of the member to manage", "in": "path", "name": "uid", "required": true, "schema": { "example": "1405506895740940329", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SetGrantsRequest" } } }, "required": true }, "responses": { "204": { "description": "No Content" }, "default": { "description": "Every failure returns this envelope; the HTTP status carries the category.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "summary": "Set write grants", "tags": [ "Workspace members" ] } }, "/workspaces/{wid}/members/{uid}/grants/{kind}": { "put": { "description": "Lets an existing member write resources of the given kind.", "operationId": "putWorkspacesByWidMembersByUidGrantsByKind", "parameters": [ { "description": "Workspace ID", "in": "path", "name": "wid", "required": true, "schema": { "example": "1405508720263180365", "type": "string" } }, { "description": "User ID of the member to manage", "in": "path", "name": "uid", "required": true, "schema": { "example": "1405506895740940329", "type": "string" } }, { "in": "path", "name": "kind", "required": true, "schema": { "enum": [ "instance", "dedibox", "app", "image", "net_balancer", "disk", "floating_ip", "*" ], "type": "string" } } ], "responses": { "204": { "description": "No Content" }, "default": { "description": "Every failure returns this envelope; the HTTP status carries the category.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "summary": "Grant write on a kind", "tags": [ "Workspace members" ] }, "delete": { "description": "Removes an existing member's write access to the given kind.", "operationId": "deleteWorkspacesByWidMembersByUidGrantsByKind", "parameters": [ { "description": "Workspace ID", "in": "path", "name": "wid", "required": true, "schema": { "example": "1405508720263180365", "type": "string" } }, { "description": "User ID of the member to manage", "in": "path", "name": "uid", "required": true, "schema": { "example": "1405506895740940329", "type": "string" } }, { "in": "path", "name": "kind", "required": true, "schema": { "enum": [ "instance", "dedibox", "app", "image", "net_balancer", "disk", "floating_ip", "*" ], "type": "string" } } ], "responses": { "204": { "description": "No Content" }, "default": { "description": "Every failure returns this envelope; the HTTP status carries the category.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "summary": "Revoke write on a kind", "tags": [ "Workspace members" ] } }, "/workspaces/{wid}/net-lbs": { "get": { "operationId": "getWorkspacesByWidNetLbs", "parameters": [ { "in": "path", "name": "wid", "required": true, "schema": { "example": "1405508720263180365", "type": "string" } }, { "description": "Quick search by name or ID", "in": "query", "name": "q", "required": false, "schema": { "type": "string" } }, { "description": "List of balancer IDs to filter", "in": "query", "name": "id", "required": false, "schema": { "items": { "example": "1467950980661264556", "type": "string" }, "type": "array" } }, { "description": "Name to filter", "in": "query", "name": "name", "required": false, "schema": { "type": "string" } }, { "description": "IP address to filter", "in": "query", "name": "address", "required": false, "schema": { "type": "string" } }, { "description": "List of workspace IDs to filter", "in": "query", "name": "owner", "required": false, "schema": { "items": { "example": "1405508720263180365", "type": "string" }, "type": "array" } }, { "description": "List of instance IDs to filter", "in": "query", "name": "instances", "required": false, "schema": { "items": { "example": "1463106077196308568", "type": "string" }, "type": "array" } }, { "description": "How many items to return", "example": 50, "in": "query", "name": "limit", "required": false, "schema": { "format": "int32", "type": "integer" } }, { "description": "Page number to fetch", "example": 1, "in": "query", "name": "page", "required": false, "schema": { "format": "int32", "type": "integer" } }, { "description": "Field to order by", "example": "id", "in": "query", "name": "sort", "required": false, "schema": { "type": "string" } }, { "description": "Order direction (ASC/DESC)", "example": "asc", "in": "query", "name": "dir", "required": false, "schema": { "type": "string" } }, { "description": "Forward keyset cursor (for keyset pagination)", "in": "query", "name": "after", "required": false, "schema": { "type": "string" } }, { "description": "Backward keyset cursor (for keyset pagination)", "in": "query", "name": "before", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/KeysetResultNetBalancerListView" } } }, "description": "OK" }, "default": { "description": "Every failure returns this envelope; the HTTP status carries the category.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "tags": [ "net-balancer-user-rest" ] } }, "/workspaces/{wid}/net-lbs/{bid}": { "get": { "operationId": "getWorkspacesByWidNetLbsByBid", "parameters": [ { "in": "path", "name": "wid", "required": true, "schema": { "example": "1405508720263180365", "type": "string" } }, { "in": "path", "name": "bid", "required": true, "schema": { "example": "1467950980661264556", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NetBalancerDetailView" } } }, "description": "OK" }, "default": { "description": "Every failure returns this envelope; the HTTP status carries the category.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "tags": [ "net-balancer-user-rest" ] }, "patch": { "operationId": "patchWorkspacesByWidNetLbsByBid", "parameters": [ { "in": "path", "name": "wid", "required": true, "schema": { "example": "1405508720263180365", "type": "string" } }, { "in": "path", "name": "bid", "required": true, "schema": { "example": "1467950980661264556", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PatchNetBalancerRequest" } } }, "required": true }, "responses": { "200": { "description": "OK" }, "default": { "description": "Every failure returns this envelope; the HTTP status carries the category.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "tags": [ "net-balancer-user-rest" ] } }, "/workspaces/{wid}/net-lbs/{bid}/instances": { "get": { "operationId": "getWorkspacesByWidNetLbsByBidInstances", "parameters": [ { "in": "path", "name": "wid", "required": true, "schema": { "example": "1405508720263180365", "type": "string" } }, { "in": "path", "name": "bid", "required": true, "schema": { "example": "1467950980661264556", "type": "string" } }, { "description": "Quick search by name, IP address, or ID", "in": "query", "name": "q", "required": false, "schema": { "type": "string" } }, { "description": "Filter by IP address (public or private)", "in": "query", "name": "ip", "required": false, "schema": { "type": "string" } }, { "description": "List of instance IDs to filter", "in": "query", "name": "id", "required": false, "schema": { "items": { "example": "1463106077196308568", "type": "string" }, "type": "array" } }, { "description": "Instance names to filter", "in": "query", "name": "name", "required": false, "schema": { "type": "string" } }, { "description": "List of node IDs to filter", "in": "query", "name": "node", "required": false, "schema": { "items": { "example": "1326819038986244108", "type": "string" }, "type": "array" } }, { "description": "List of products to filter", "in": "query", "name": "sku", "required": false, "schema": { "items": { "example": "lightning-1g", "type": "string" }, "type": "array" } }, { "description": "List of ISO IDs to filter", "in": "query", "name": "iso", "required": false, "schema": { "items": { "example": "1471181001588760790", "type": "string" }, "type": "array" } }, { "description": "Boot target to filter", "in": "query", "name": "boot", "required": false, "schema": { "enum": [ "DISK", "ISO" ], "type": "string" } }, { "description": "Filter for only online/offline instances", "in": "query", "name": "online", "required": false, "schema": { "type": "boolean" } }, { "description": "Filter for instances with a specific state", "in": "query", "name": "state", "required": false, "schema": { "items": { "enum": [ "PENDING", "AVAILABLE", "FAILED", "SUSPENDED", "DELETING", "UNPLACED" ], "type": "string" }, "type": "array" } }, { "description": "Filter for only instances scheduled for termination", "in": "query", "name": "terminating", "required": false, "schema": { "type": "boolean" } }, { "description": "List of backup plan IDs to filter", "in": "query", "name": "backup_plan", "required": false, "schema": { "items": { "example": "1506320201023500406", "type": "string" }, "type": "array" } }, { "description": "Filter for only instances in a specific region", "in": "query", "name": "region", "required": false, "schema": { "enum": [ "NA_01" ], "type": "string" } }, { "description": "List of VPC IDs to filter", "in": "query", "name": "vpc", "required": false, "schema": { "items": { "example": "1463882832936980610", "type": "string" }, "type": "array" } }, { "description": "Filter for instances with a specific OS family", "in": "query", "name": "os", "required": false, "schema": { "enum": [ "WINDOWS", "LINUX", "BSD", "OTHER" ], "type": "string" } }, { "description": "List of workspace IDs to filter", "in": "query", "name": "owner", "required": false, "schema": { "items": { "example": "1405508720263180365", "type": "string" }, "type": "array" } }, { "description": "How many items to return", "example": 50, "in": "query", "name": "limit", "required": false, "schema": { "format": "int32", "type": "integer" } }, { "description": "Page number to fetch", "example": 1, "in": "query", "name": "page", "required": false, "schema": { "format": "int32", "type": "integer" } }, { "description": "Field to order by", "example": "id", "in": "query", "name": "sort", "required": false, "schema": { "type": "string" } }, { "description": "Order direction (ASC/DESC)", "example": "asc", "in": "query", "name": "dir", "required": false, "schema": { "type": "string" } }, { "description": "Forward keyset cursor (for keyset pagination)", "in": "query", "name": "after", "required": false, "schema": { "type": "string" } }, { "description": "Backward keyset cursor (for keyset pagination)", "in": "query", "name": "before", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/KeysetResultInstanceSimple" } } }, "description": "OK" }, "default": { "description": "Every failure returns this envelope; the HTTP status carries the category.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "tags": [ "net-balancer-user-rest" ] } }, "/workspaces/{wid}/net-lbs/{bid}/instances/{iid}": { "put": { "operationId": "putWorkspacesByWidNetLbsByBidInstancesByIid", "parameters": [ { "in": "path", "name": "wid", "required": true, "schema": { "example": "1405508720263180365", "type": "string" } }, { "in": "path", "name": "bid", "required": true, "schema": { "example": "1467950980661264556", "type": "string" } }, { "in": "path", "name": "iid", "required": true, "schema": { "example": "1463106077196308568", "type": "string" } } ], "responses": { "202": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkflowData" } } }, "description": "Accepted" }, "default": { "description": "Every failure returns this envelope; the HTTP status carries the category.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "tags": [ "net-balancer-user-rest" ] }, "delete": { "operationId": "deleteWorkspacesByWidNetLbsByBidInstancesByIid", "parameters": [ { "in": "path", "name": "wid", "required": true, "schema": { "example": "1405508720263180365", "type": "string" } }, { "in": "path", "name": "bid", "required": true, "schema": { "example": "1467950980661264556", "type": "string" } }, { "in": "path", "name": "iid", "required": true, "schema": { "example": "1463106077196308568", "type": "string" } } ], "responses": { "202": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkflowData" } } }, "description": "Accepted" }, "default": { "description": "Every failure returns this envelope; the HTTP status carries the category.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "tags": [ "net-balancer-user-rest" ] } }, "/workspaces/{wid}/orders": { "get": { "description": "Keyset-paginated orders placed in the given workspace, newest first. Requires workspace membership.", "operationId": "getWorkspacesByWidOrders", "parameters": [ { "description": "Workspace id", "in": "path", "name": "wid", "required": true, "schema": { "example": "1053072736118476800", "type": "string" } }, { "description": "Order ids to filter", "in": "query", "name": "id", "required": false, "schema": { "items": { "example": "1456074443980800000", "type": "string" }, "type": "array" } }, { "description": "Account ids to filter", "in": "query", "name": "account_id", "required": false, "schema": { "items": { "example": "1456074443980800000", "type": "string" }, "type": "array" } }, { "description": "Panel user ids of the paying account to filter", "in": "query", "name": "user", "required": false, "schema": { "items": { "example": "1053072706808680448", "type": "string" }, "type": "array" } }, { "description": "Workspace ids to filter", "in": "query", "name": "workspace_id", "required": false, "schema": { "items": { "example": "1053072736118476800", "type": "string" }, "type": "array" } }, { "description": "Statuses to filter", "in": "query", "name": "status", "required": false, "schema": { "items": { "enum": [ "DRAFT", "AWAITING_APPROVAL", "AWAITING_PAYMENT", "GREEN", "FULFILLED", "FAILED", "CANCELLED" ], "type": "string" }, "type": "array" } }, { "description": "Kinds to filter", "in": "query", "name": "kind", "required": false, "schema": { "items": { "enum": [ "PURCHASE", "UPGRADE", "ADJUST" ], "type": "string" }, "type": "array" } }, { "description": "How many items to return", "example": 50, "in": "query", "name": "limit", "required": false, "schema": { "format": "int32", "type": "integer" } }, { "description": "Page number to fetch", "example": 1, "in": "query", "name": "page", "required": false, "schema": { "format": "int32", "type": "integer" } }, { "description": "Field to order by", "example": "id", "in": "query", "name": "sort", "required": false, "schema": { "type": "string" } }, { "description": "Order direction (ASC/DESC)", "example": "asc", "in": "query", "name": "dir", "required": false, "schema": { "type": "string" } }, { "description": "Forward keyset cursor (for keyset pagination)", "in": "query", "name": "after", "required": false, "schema": { "type": "string" } }, { "description": "Backward keyset cursor (for keyset pagination)", "in": "query", "name": "before", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/KeysetResultOrderView" } } }, "description": "The workspace's orders" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Not a member of the workspace" }, "default": { "description": "Every failure returns this envelope; the HTTP status carries the category.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "summary": "List a workspace's orders", "tags": [ "Orders" ] }, "post": { "description": "Prices one or more packages and places the order. For PREPAID fixed packages, the order raises one invoice for the first cycle and pays it from the wallet first. collection tells if a stored payment method is being charged or if a checkout is necessary for the remaining amount. The order completes and provisions its resources when the invoice is paid. A POSTPAID or metered-only order collects nothing up front, completes immediately and bills in arrears. Servers count against the workspace quota. The order bills the workspace owner's account and requires the workspace admin role. When the workspace requires order approval, an order from a member other than the owner stays in AWAITING_APPROVAL and collects nothing until the owner approves it.", "operationId": "postWorkspacesByWidOrders", "parameters": [ { "description": "Workspace id the order is placed in", "in": "path", "name": "wid", "required": true, "schema": { "example": "1053072736118476800", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateOrderRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateOrderResponse" } } }, "description": "The placed order, whether it greened, and what is owed" }, "402": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Server quota exceeded, or the wallet balance is too low for a metered package" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Not an admin of the target workspace, or POSTPAID is not enabled for the owner" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Unknown workspace or package" }, "default": { "description": "Every failure returns this envelope; the HTTP status carries the category.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "summary": "Place an order", "tags": [ "Orders" ] } }, "/workspaces/{wid}/quota": { "get": { "description": "Fetches the quota available for a workspace.\n", "operationId": "getWorkspacesByWidQuota", "parameters": [ { "description": "Workspace ID", "in": "path", "name": "wid", "required": true, "schema": { "example": "1405508720263180365", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QuotaView" } } }, "description": "OK" }, "default": { "description": "Every failure returns this envelope; the HTTP status carries the category.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "summary": "Fetch workspace quota", "tags": [ "Workspaces" ] } }, "/workspaces/{wid}/recipes": { "get": { "description": "Searches for recipes assigned to a workspace.\n", "operationId": "getWorkspacesByWidRecipes", "parameters": [ { "description": "Workspace ID", "in": "path", "name": "wid", "required": true, "schema": { "example": "1405508720263180365", "type": "string" } }, { "description": "Quick search by name or ID", "in": "query", "name": "q", "required": false, "schema": { "type": "string" } }, { "description": "List of recipe IDs to filter", "in": "query", "name": "id", "required": false, "schema": { "items": { "example": "1471181001588760790", "type": "string" }, "type": "array" } }, { "description": "List of workspace IDs to filter", "in": "query", "name": "owner", "required": false, "schema": { "items": { "example": "1405508720263180365", "type": "string" }, "type": "array" } }, { "description": "Recipe name to filter", "in": "query", "name": "name", "required": false, "schema": { "type": "string" } }, { "description": "Recipe description to filter", "in": "query", "name": "description", "required": false, "schema": { "type": "string" } }, { "description": "Recipe category to filter", "in": "query", "name": "category", "required": false, "schema": { "enum": [ "DEFAULT", "GAMES", "SOFTWARE", "INFRASTRUCTURE", "AI", "MEDIA", "TOOLS", "DATABASES", "MONITORING", "PRODUCTIVITY", "DEVOPS", "AUTOMATION", "NETWORK" ], "type": "string" } }, { "description": "How many items to return", "example": 50, "in": "query", "name": "limit", "required": false, "schema": { "format": "int32", "type": "integer" } }, { "description": "Page number to fetch", "example": 1, "in": "query", "name": "page", "required": false, "schema": { "format": "int32", "type": "integer" } }, { "description": "Field to order by", "example": "id", "in": "query", "name": "sort", "required": false, "schema": { "type": "string" } }, { "description": "Order direction (ASC/DESC)", "example": "asc", "in": "query", "name": "dir", "required": false, "schema": { "type": "string" } }, { "description": "Forward keyset cursor (for keyset pagination)", "in": "query", "name": "after", "required": false, "schema": { "type": "string" } }, { "description": "Backward keyset cursor (for keyset pagination)", "in": "query", "name": "before", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/KeysetResultRecipeListView" } } }, "description": "OK" }, "default": { "description": "Every failure returns this envelope; the HTTP status carries the category.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "summary": "Search for recipes", "tags": [ "Recipes" ] }, "post": { "description": "Used to create a recipe under this workspace.\n", "operationId": "postWorkspacesByWidRecipes", "parameters": [ { "description": "Workspace ID", "in": "path", "name": "wid", "required": true, "schema": { "example": "1405508720263180365", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateRecipeRequest" } } }, "required": true }, "responses": { "201": { "content": { "*/*": { "schema": { "$ref": "#/components/schemas/RecipeDetailView" } } }, "description": "Created" }, "default": { "description": "Every failure returns this envelope; the HTTP status carries the category.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "summary": "Create a recipe", "tags": [ "Recipes" ] } }, "/workspaces/{wid}/registries": { "get": { "description": "Returns stored private registry credentials with keyset pagination and optional filtering. Passwords are never returned.", "operationId": "getWorkspacesByWidRegistries", "parameters": [ { "description": "Workspace ID", "in": "path", "name": "wid", "required": true, "schema": { "example": "1405508720263180365", "type": "string" } }, { "description": "Quick search by registry host, username, or ID", "in": "query", "name": "q", "required": false, "schema": { "type": "string" } }, { "description": "List of credential IDs to filter", "in": "query", "name": "id", "required": false, "schema": { "items": { "example": "1483754921000984881", "type": "string" }, "type": "array" } }, { "description": "Registry host substring to filter", "in": "query", "name": "registry", "required": false, "schema": { "type": "string" } }, { "description": "Username substring to filter", "in": "query", "name": "username", "required": false, "schema": { "type": "string" } }, { "description": "List of workspace IDs to filter", "in": "query", "name": "owner", "required": false, "schema": { "items": { "example": "1405508720263180365", "type": "string" }, "type": "array" } }, { "description": "How many items to return", "example": 50, "in": "query", "name": "limit", "required": false, "schema": { "format": "int32", "type": "integer" } }, { "description": "Page number to fetch", "example": 1, "in": "query", "name": "page", "required": false, "schema": { "format": "int32", "type": "integer" } }, { "description": "Field to order by", "example": "id", "in": "query", "name": "sort", "required": false, "schema": { "type": "string" } }, { "description": "Order direction (ASC/DESC)", "example": "asc", "in": "query", "name": "dir", "required": false, "schema": { "type": "string" } }, { "description": "Forward keyset cursor (for keyset pagination)", "in": "query", "name": "after", "required": false, "schema": { "type": "string" } }, { "description": "Backward keyset cursor (for keyset pagination)", "in": "query", "name": "before", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/KeysetResultRegistryCredentialView" } } }, "description": "OK" }, "default": { "description": "Every failure returns this envelope; the HTTP status carries the category.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "summary": "List registry credentials for a workspace", "tags": [ "Registry Credentials" ] }, "post": { "description": "Saves credentials for a private container registry. The registry host is canonicalized, and the credentials are validated against the live registry before being persisted. An existing credential for the same registry host is replaced.", "operationId": "postWorkspacesByWidRegistries", "parameters": [ { "description": "Workspace ID", "in": "path", "name": "wid", "required": true, "schema": { "example": "1405508720263180365", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateRegistryRequest" } } }, "required": true }, "responses": { "201": { "content": { "*/*": { "schema": { "$ref": "#/components/schemas/RegistryCredentialView" } } }, "description": "Created" }, "default": { "description": "Every failure returns this envelope; the HTTP status carries the category.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "summary": "Add or replace a registry credential", "tags": [ "Registry Credentials" ] } }, "/workspaces/{wid}/registries/{cid}": { "get": { "description": "Returns a stored credential by ID. The password field is never returned.", "operationId": "getWorkspacesByWidRegistriesByCid", "parameters": [ { "description": "Workspace ID", "in": "path", "name": "wid", "required": true, "schema": { "example": "1405508720263180365", "type": "string" } }, { "description": "Credential ID", "in": "path", "name": "cid", "required": true, "schema": { "example": "1483754921000984881", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RegistryCredentialView" } } }, "description": "OK" }, "default": { "description": "Every failure returns this envelope; the HTTP status carries the category.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "summary": "Get a single registry credential", "tags": [ "Registry Credentials" ] }, "delete": { "operationId": "deleteWorkspacesByWidRegistriesByCid", "parameters": [ { "description": "Workspace ID", "in": "path", "name": "wid", "required": true, "schema": { "example": "1405508720263180365", "type": "string" } }, { "description": "Credential ID", "in": "path", "name": "cid", "required": true, "schema": { "example": "1483754921000984881", "type": "string" } } ], "responses": { "204": { "description": "No Content" }, "default": { "description": "Every failure returns this envelope; the HTTP status carries the category.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "summary": "Delete a registry credential", "tags": [ "Registry Credentials" ] }, "patch": { "description": "Updates the username and/or password of a stored credential. The registry host is immutable. When credentials change, they are revalidated against the live registry before being persisted.", "operationId": "patchWorkspacesByWidRegistriesByCid", "parameters": [ { "description": "Workspace ID", "in": "path", "name": "wid", "required": true, "schema": { "example": "1405508720263180365", "type": "string" } }, { "description": "Credential ID", "in": "path", "name": "cid", "required": true, "schema": { "example": "1483754921000984881", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateRegistryRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RegistryCredentialView" } } }, "description": "OK" }, "default": { "description": "Every failure returns this envelope; the HTTP status carries the category.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "summary": "Update a registry credential", "tags": [ "Registry Credentials" ] } }, "/workspaces/{wid}/registries/{cid}/test": { "post": { "description": "Reauthenticates the stored credentials against the live registry. Returns 204 on success, or 400 with a description if the credentials no longer work.", "operationId": "postWorkspacesByWidRegistriesByCidTest", "parameters": [ { "description": "Workspace ID", "in": "path", "name": "wid", "required": true, "schema": { "example": "1405508720263180365", "type": "string" } }, { "description": "Credential ID", "in": "path", "name": "cid", "required": true, "schema": { "example": "1483754921000984881", "type": "string" } } ], "responses": { "204": { "description": "No Content" }, "default": { "description": "Every failure returns this envelope; the HTTP status carries the category.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "summary": "Re-test stored registry credentials", "tags": [ "Registry Credentials" ] } }, "/workspaces/{wid}/snapshots": { "get": { "description": "Searches for snapshots on a workspace.\n", "operationId": "getWorkspacesByWidSnapshots", "parameters": [ { "description": "Workspace ID", "in": "path", "name": "wid", "required": true, "schema": { "example": "1405508720263180365", "type": "string" } }, { "description": "List of snapshot IDs to filter", "in": "query", "name": "id", "required": false, "schema": { "items": { "example": "1463106081390612571", "type": "string" }, "type": "array" } }, { "description": "List of instance IDs to filter", "in": "query", "name": "instance", "required": false, "schema": { "items": { "example": "1463106077196308568", "type": "string" }, "type": "array" } }, { "description": "List of workspace IDs to filter", "in": "query", "name": "owner", "required": false, "schema": { "items": { "example": "1405508720263180365", "type": "string" }, "type": "array" } }, { "description": "List of disk IDs to filter", "in": "query", "name": "disk", "required": false, "schema": { "items": { "example": "1463106081390612571", "type": "string" }, "type": "array" } }, { "description": "Filter by state", "in": "query", "name": "state", "required": false, "schema": { "items": { "enum": [ "PENDING", "AVAILABLE", "FAILED", "SUSPENDED", "DELETING", "UNPLACED" ], "type": "string" }, "type": "array" } }, { "description": "How many items to return", "example": 50, "in": "query", "name": "limit", "required": false, "schema": { "format": "int32", "type": "integer" } }, { "description": "Page number to fetch", "example": 1, "in": "query", "name": "page", "required": false, "schema": { "format": "int32", "type": "integer" } }, { "description": "Field to order by", "example": "id", "in": "query", "name": "sort", "required": false, "schema": { "type": "string" } }, { "description": "Order direction (ASC/DESC)", "example": "asc", "in": "query", "name": "dir", "required": false, "schema": { "type": "string" } }, { "description": "Forward keyset cursor (for keyset pagination)", "in": "query", "name": "after", "required": false, "schema": { "type": "string" } }, { "description": "Backward keyset cursor (for keyset pagination)", "in": "query", "name": "before", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/KeysetResultSnapshotListView" } } }, "description": "OK" }, "default": { "description": "Every failure returns this envelope; the HTTP status carries the category.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "summary": "Search workspace snapshots", "tags": [ "Snapshots" ] } }, "/workspaces/{wid}/ssh": { "get": { "description": "Searches for ssh keys on a workspace.\n", "operationId": "getWorkspacesByWidSsh", "parameters": [ { "description": "Workspace ID", "in": "path", "name": "wid", "required": true, "schema": { "example": "1405508720263180365", "type": "string" } }, { "description": "Quick search by name or ID", "in": "query", "name": "q", "required": false, "schema": { "type": "string" } }, { "description": "List of SSH key IDs to filter", "in": "query", "name": "id", "required": false, "schema": { "items": { "example": "1506320201023500406", "type": "string" }, "type": "array" } }, { "description": "SSH key name to filter", "in": "query", "name": "name", "required": false, "schema": { "type": "string" } }, { "description": "List of workspace IDs to filter", "in": "query", "name": "owner", "required": false, "schema": { "items": { "example": "1405508720263180365", "type": "string" }, "type": "array" } }, { "description": "How many items to return", "example": 50, "in": "query", "name": "limit", "required": false, "schema": { "format": "int32", "type": "integer" } }, { "description": "Page number to fetch", "example": 1, "in": "query", "name": "page", "required": false, "schema": { "format": "int32", "type": "integer" } }, { "description": "Field to order by", "example": "id", "in": "query", "name": "sort", "required": false, "schema": { "type": "string" } }, { "description": "Order direction (ASC/DESC)", "example": "asc", "in": "query", "name": "dir", "required": false, "schema": { "type": "string" } }, { "description": "Forward keyset cursor (for keyset pagination)", "in": "query", "name": "after", "required": false, "schema": { "type": "string" } }, { "description": "Backward keyset cursor (for keyset pagination)", "in": "query", "name": "before", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/KeysetResultSshKeyListView" } } }, "description": "OK" }, "default": { "description": "Every failure returns this envelope; the HTTP status carries the category.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "summary": "Search workspace ssh keys", "tags": [ "SSH Keys" ] }, "post": { "description": "Uploads an SSH Key to a workspace.\n", "operationId": "postWorkspacesByWidSsh", "parameters": [ { "description": "Workspace ID", "in": "path", "name": "wid", "required": true, "schema": { "example": "1405508720263180365", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SshCreateRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SshKey" } } }, "description": "OK" }, "default": { "description": "Every failure returns this envelope; the HTTP status carries the category.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "summary": "Upload new SSH Key", "tags": [ "SSH Keys" ] } }, "/workspaces/{wid}/subjects": { "get": { "description": "Keyset-paginated services bought in the workspace, newest first, with their price, cycle, next renewal and state.", "operationId": "getWorkspacesByWidSubjects", "parameters": [ { "description": "Workspace id", "in": "path", "name": "wid", "required": true, "schema": { "example": "1053072736118476800", "type": "string" } }, { "description": "Quick search by resource name, or an exact subject id", "in": "query", "name": "q", "required": false, "schema": { "type": "string" } }, { "description": "Subject ids to filter", "in": "query", "name": "id", "required": false, "schema": { "items": { "example": "1456074443980800000", "type": "string" }, "type": "array" } }, { "description": "States to filter", "in": "query", "name": "state", "required": false, "schema": { "items": { "enum": [ "ACTIVE", "SUSPENDED", "TERMINATED" ], "type": "string" }, "type": "array" } }, { "description": "Kinds to filter", "in": "query", "name": "resource_kind", "required": false, "schema": { "items": { "enum": [ "SERVER", "IP_ADDRESS" ], "type": "string" }, "type": "array" } }, { "description": "Package SKUs to filter", "in": "query", "name": "package_code", "required": false, "schema": { "items": { "type": "string" }, "type": "array" } }, { "description": "Charge bases to filter", "in": "query", "name": "charge_basis", "required": false, "schema": { "items": { "enum": [ "FIXED", "METERED" ], "type": "string" }, "type": "array" } }, { "description": "How many items to return", "example": 50, "in": "query", "name": "limit", "required": false, "schema": { "format": "int32", "type": "integer" } }, { "description": "Page number to fetch", "example": 1, "in": "query", "name": "page", "required": false, "schema": { "format": "int32", "type": "integer" } }, { "description": "Field to order by", "example": "id", "in": "query", "name": "sort", "required": false, "schema": { "type": "string" } }, { "description": "Order direction (ASC/DESC)", "example": "asc", "in": "query", "name": "dir", "required": false, "schema": { "type": "string" } }, { "description": "Forward keyset cursor (for keyset pagination)", "in": "query", "name": "after", "required": false, "schema": { "type": "string" } }, { "description": "Backward keyset cursor (for keyset pagination)", "in": "query", "name": "before", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/KeysetResultSubjectView" } } }, "description": "The workspace's subjects" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Not a member of the workspace" }, "default": { "description": "Every failure returns this envelope; the HTTP status carries the category.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "summary": "List a workspace's subjects", "tags": [ "Subjects" ] } }, "/workspaces/{wid}/tokens": { "get": { "description": "Lists the tokens that belong to a workspace or to any of its resources.", "operationId": "getWorkspacesByWidTokens", "parameters": [ { "description": "Workspace ID", "in": "path", "name": "wid", "required": true, "schema": { "example": "1405508720263180365", "type": "string" } }, { "description": "Quick search by name or ID", "in": "query", "name": "q", "required": false, "schema": { "type": "string" } }, { "description": "List of token IDs to filter", "in": "query", "name": "id", "required": false, "schema": { "items": { "example": "1479097389678620681", "type": "string" }, "type": "array" } }, { "description": "Token name to filter", "in": "query", "name": "name", "required": false, "schema": { "type": "string" } }, { "description": "Token origin to filter", "in": "query", "name": "origin", "required": false, "schema": { "enum": [ "SESSION", "API", "SYSTEM", "OAUTH" ], "type": "string" } }, { "description": "Token subject to filter", "in": "query", "name": "subject", "required": false, "schema": { "enum": [ "USER", "WORKSPACE", "RESOURCE" ], "type": "string" } }, { "description": "How many items to return", "example": 50, "in": "query", "name": "limit", "required": false, "schema": { "format": "int32", "type": "integer" } }, { "description": "Page number to fetch", "example": 1, "in": "query", "name": "page", "required": false, "schema": { "format": "int32", "type": "integer" } }, { "description": "Field to order by", "example": "id", "in": "query", "name": "sort", "required": false, "schema": { "type": "string" } }, { "description": "Order direction (ASC/DESC)", "example": "asc", "in": "query", "name": "dir", "required": false, "schema": { "type": "string" } }, { "description": "Forward keyset cursor (for keyset pagination)", "in": "query", "name": "after", "required": false, "schema": { "type": "string" } }, { "description": "Backward keyset cursor (for keyset pagination)", "in": "query", "name": "before", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/KeysetResultTokenListView" } } }, "description": "OK" }, "default": { "description": "Every failure returns this envelope; the HTTP status carries the category.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "summary": "List workspace-scope tokens", "tags": [ "Tokens" ] }, "post": { "description": "Creates a token that belongs to a workspace or one of its resources. For a resource-scope token, pass\nowner_kind (INSTANCE|DEDIBOX|APP) and owner_id; the resource must belong to the path workspace. The\nplaintext code is returned once, save it securely.\n", "operationId": "postWorkspacesByWidTokens", "parameters": [ { "description": "Workspace ID", "in": "path", "name": "wid", "required": true, "schema": { "example": "1405508720263180365", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TokenCreateRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TokenCreateResponse" } } }, "description": "OK", "headers": { "X-Sudo-Expires": { "description": "When sudo mode ends, sent when the request starts or extends it", "schema": { "format": "date-time", "type": "string" } } } }, "403": { "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ApiError" }, { "$ref": "#/components/schemas/MfaChallenge" } ] } } }, "description": "Forbidden, or `MfaChallenge` when a second factor is needed" }, "default": { "description": "Every failure returns this envelope; the HTTP status carries the category.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "summary": "Create a workspace-scope or resource-scope token", "tags": [ "Tokens" ], "x-api-elevation": "required" } }, "/workspaces/{wid}/topology": { "get": { "description": "Returns all resources needed to render the workspace topology view\nin a single response: instances, floating IPs, VPCs, dediboxes, and\nnetwork load balancers with their associations.\n", "operationId": "getWorkspacesByWidTopology", "parameters": [ { "description": "Workspace ID", "in": "path", "name": "wid", "required": true, "schema": { "example": "1405508720263180365", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TopologyResponse" } } }, "description": "OK" }, "default": { "description": "Every failure returns this envelope; the HTTP status carries the category.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "summary": "Get workspace topology data", "tags": [ "Topology" ] } }, "/workspaces/{wid}/usage": { "get": { "description": "Keyset-paginated metered subjects of the workspace, each with the minutes and charge it accrued between from (inclusive) and to (exclusive). The window defaults to the current calendar month in UTC, up to now.", "operationId": "getWorkspacesByWidUsage", "parameters": [ { "description": "Workspace id", "in": "path", "name": "wid", "required": true, "schema": { "example": "1053072736118476800", "type": "string" } }, { "description": "Start of the window, inclusive; defaults to the start of the current UTC month", "in": "query", "name": "from", "required": false, "schema": { "format": "date-time", "type": "string" } }, { "description": "End of the window, exclusive; defaults to now", "in": "query", "name": "to", "required": false, "schema": { "format": "date-time", "type": "string" } }, { "description": "Quick search by resource name, or an exact subject id", "in": "query", "name": "q", "required": false, "schema": { "type": "string" } }, { "description": "Subject ids to filter", "in": "query", "name": "id", "required": false, "schema": { "items": { "example": "1456074443980800000", "type": "string" }, "type": "array" } }, { "description": "States to filter", "in": "query", "name": "state", "required": false, "schema": { "items": { "enum": [ "ACTIVE", "SUSPENDED", "TERMINATED" ], "type": "string" }, "type": "array" } }, { "description": "Kinds to filter", "in": "query", "name": "resource_kind", "required": false, "schema": { "items": { "enum": [ "SERVER", "IP_ADDRESS" ], "type": "string" }, "type": "array" } }, { "description": "Package SKUs to filter", "in": "query", "name": "package_code", "required": false, "schema": { "items": { "type": "string" }, "type": "array" } }, { "description": "Charge bases to filter", "in": "query", "name": "charge_basis", "required": false, "schema": { "items": { "enum": [ "FIXED", "METERED" ], "type": "string" }, "type": "array" } }, { "description": "How many items to return", "example": 50, "in": "query", "name": "limit", "required": false, "schema": { "format": "int32", "type": "integer" } }, { "description": "Page number to fetch", "example": 1, "in": "query", "name": "page", "required": false, "schema": { "format": "int32", "type": "integer" } }, { "description": "Field to order by", "example": "id", "in": "query", "name": "sort", "required": false, "schema": { "type": "string" } }, { "description": "Order direction (ASC/DESC)", "example": "asc", "in": "query", "name": "dir", "required": false, "schema": { "type": "string" } }, { "description": "Forward keyset cursor (for keyset pagination)", "in": "query", "name": "after", "required": false, "schema": { "type": "string" } }, { "description": "Backward keyset cursor (for keyset pagination)", "in": "query", "name": "before", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/KeysetResultSubjectUsageResponse" } } }, "description": "The workspace's metered subjects with their usage" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "The window ends before it starts" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Not a member of the workspace" }, "default": { "description": "Every failure returns this envelope; the HTTP status carries the category.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "summary": "List a workspace's metered usage", "tags": [ "Subjects" ] } }, "/workspaces/{wid}/vpcs": { "get": { "operationId": "getWorkspacesByWidVpcs", "parameters": [ { "description": "Workspace ID", "in": "path", "name": "wid", "required": true, "schema": { "example": "1405508720263180365", "type": "string" } }, { "description": "Quick search by name or ID", "in": "query", "name": "q", "required": false, "schema": { "type": "string" } }, { "description": "List of VPC IDs to filter", "in": "query", "name": "id", "required": false, "schema": { "items": { "example": "1463882832936980610", "type": "string" }, "type": "array" } }, { "description": "VPC name to filter", "in": "query", "name": "name", "required": false, "schema": { "type": "string" } }, { "description": "VPC description to filter", "in": "query", "name": "description", "required": false, "schema": { "type": "string" } }, { "description": "How many items to return", "example": 50, "in": "query", "name": "limit", "required": false, "schema": { "format": "int32", "type": "integer" } }, { "description": "Page number to fetch", "example": 1, "in": "query", "name": "page", "required": false, "schema": { "format": "int32", "type": "integer" } }, { "description": "Field to order by", "example": "id", "in": "query", "name": "sort", "required": false, "schema": { "type": "string" } }, { "description": "Order direction (ASC/DESC)", "example": "asc", "in": "query", "name": "dir", "required": false, "schema": { "type": "string" } }, { "description": "Forward keyset cursor (for keyset pagination)", "in": "query", "name": "after", "required": false, "schema": { "type": "string" } }, { "description": "Backward keyset cursor (for keyset pagination)", "in": "query", "name": "before", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/KeysetResultVpcListView" } } }, "description": "OK" }, "default": { "description": "Every failure returns this envelope; the HTTP status carries the category.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "summary": "Search workspace VPCs", "tags": [ "VPCs" ] }, "post": { "operationId": "postWorkspacesByWidVpcs", "parameters": [ { "description": "Workspace ID", "in": "path", "name": "wid", "required": true, "schema": { "example": "1405508720263180365", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateRequest" } } }, "required": true }, "responses": { "201": { "content": { "*/*": { "schema": { "$ref": "#/components/schemas/VpcListView" } } }, "description": "Created" }, "default": { "description": "Every failure returns this envelope; the HTTP status carries the category.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "summary": "Create VPC", "tags": [ "VPCs" ] } }, "/workspaces/{wid}/workflows": { "get": { "operationId": "getWorkspacesByWidWorkflows", "parameters": [ { "in": "path", "name": "wid", "required": true, "schema": { "example": "1405508720263180365", "type": "string" } }, { "description": "Quick search by workflow ID prefix, name prefix, instance, or workspace", "in": "query", "name": "q", "required": false, "schema": { "type": "string" } }, { "description": "List of workflow IDs to filter", "in": "query", "name": "id", "required": false, "schema": { "items": { "type": "string" }, "type": "array" } }, { "description": "Workflow name to filter (e.g. instance.power)", "in": "query", "name": "name", "required": false, "schema": { "type": "string" } }, { "description": "List of instance IDs to scope workflows to", "in": "query", "name": "instance", "required": false, "schema": { "items": { "example": "1463106077196308568", "type": "string" }, "type": "array" } }, { "description": "List of workspace IDs to scope workflows to", "in": "query", "name": "workspace", "required": false, "schema": { "items": { "example": "1405508720263180365", "type": "string" }, "type": "array" } }, { "description": "List of execution states to filter", "in": "query", "name": "status", "required": false, "schema": { "items": { "enum": [ "QUEUED", "RUNNING", "FAILED", "COMPLETED", "ABORTED", "TIMED_OUT" ], "type": "string" }, "type": "array" } }, { "description": "Filter workflows started at or after this timestamp (ISO-8601)", "in": "query", "name": "started_after", "required": false, "schema": { "example": "2026-04-27T00:00:00Z", "format": "date-time", "type": "string" } }, { "description": "Filter workflows started at or before this timestamp (ISO-8601)", "in": "query", "name": "started_before", "required": false, "schema": { "example": "2026-04-28T00:00:00Z", "format": "date-time", "type": "string" } }, { "description": "How many items to return", "example": 50, "in": "query", "name": "limit", "required": false, "schema": { "format": "int32", "type": "integer" } }, { "description": "Page number to fetch", "example": 1, "in": "query", "name": "page", "required": false, "schema": { "format": "int32", "type": "integer" } }, { "description": "Field to order by", "example": "id", "in": "query", "name": "sort", "required": false, "schema": { "type": "string" } }, { "description": "Order direction (ASC/DESC)", "example": "asc", "in": "query", "name": "dir", "required": false, "schema": { "type": "string" } }, { "description": "Forward keyset cursor (for keyset pagination)", "in": "query", "name": "after", "required": false, "schema": { "type": "string" } }, { "description": "Backward keyset cursor (for keyset pagination)", "in": "query", "name": "before", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/KeysetResultWorkflowData" } } }, "description": "OK" }, "default": { "description": "Every failure returns this envelope; the HTTP status carries the category.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "tags": [ "workflow-controller" ] } }, "/workspaces/{wid}/workflows/{wfid}": { "get": { "operationId": "getWorkspacesByWidWorkflowsByWfid", "parameters": [ { "in": "path", "name": "wid", "required": true, "schema": { "example": "1405508720263180365", "type": "string" } }, { "example": "9f2c1d7a-4b83-4c1e-9a55-6d0f3b8e27c4", "in": "path", "name": "wfid", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkflowData" } } }, "description": "OK" }, "default": { "description": "Every failure returns this envelope; the HTTP status carries the category.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "tags": [ "workflow-controller" ] } } }, "components": { "schemas": { "AcceptInviteRequest": { "properties": { "code": { "description": "Invite code", "type": "string" } }, "required": [ "code" ], "type": "object" }, "AccountLockDetails": { "description": "Account lock parameters", "properties": { "source": { "$ref": "#/components/schemas/LockSource", "description": "How the account was locked" }, "type": { "enum": [ "account_lock" ], "type": "string" } }, "required": [ "source", "type" ], "type": "object" }, "ApiError": { "properties": { "code": { "description": "Machine-readable code, present only where the status alone is ambiguous", "enum": [ "missing_mfa", "challenge_expired", "login_expired", "credential_unknown", "credential_rejected", "too_many_attempts", "mfa_enforced", "account_locked", "email_unverified", "session_relocated", "concurrent_modification", "resource_conflict", "insufficient_funds" ], "type": [ "string", "null" ] }, "error": { "description": "Human-readable message", "example": "Invoice 42 is already paid", "type": "string" }, "status": { "description": "The HTTP status, repeated in the body so a client that only has the payload can still branch on it", "example": 409, "format": "int32", "type": "integer" } }, "required": [ "code", "error", "status" ], "type": "object" }, "App": { "description": "OAuth application summary", "properties": { "description": { "description": "Application description", "type": "string" }, "id": { "description": "Application ID", "example": "1479097389678620681", "type": "string" }, "name": { "description": "Application name", "example": "Acme Dashboard", "type": "string" } }, "required": [ "description", "id", "name" ], "type": "object" }, "AuditAction": { "description": "Action recorded by an audit log entry", "enum": [ "INSTANCE_CREATED", "INSTANCE_TERMINATED", "INSTANCE_TERMINATION_SCHEDULED", "INSTANCE_TERMINATION_CANCELLED", "INSTANCE_POWER_ON", "INSTANCE_POWER_OFF", "INSTANCE_POWER_CYCLE", "INSTANCE_SHUTDOWN", "INSTANCE_POWER", "INSTANCE_SUSPENDED", "INSTANCE_RESUMED", "INSTANCE_NETWORK_SUSPENDED", "INSTANCE_NETWORK_RESUMED", "INSTANCE_BOOT_CHANGED", "INSTANCE_AUTOSTART_CHANGED", "INSTANCE_VIRTIO_CD_CHANGED", "INSTANCE_FIRMWARE_CHANGED", "INSTANCE_OS_CHANGED", "INSTANCE_TIMEZONE_CHANGED", "INSTANCE_CLOUD_INIT_UPDATED", "INSTANCE_HOSTNAME_CHANGED", "INSTANCE_PASSWORD_RESET", "INSTANCE_SSH_KEYS_SYNCED", "INSTANCE_RECIPE_INSTALLED", "INSTANCE_UPGRADED", "INSTANCE_UPGRADES_APPLIED", "INSTANCE_MIGRATION_STARTED", "INSTANCE_TRANSFERRED", "INSTANCE_REINSTALLED", "INSTANCE_PACKET_CAPTURE_STARTED", "SNAPSHOT_CREATED", "SNAPSHOT_DELETED", "SNAPSHOT_RESTORED", "BACKUP_CREATED", "BACKUP_RESTORED", "ISO_ATTACHED", "ISO_DETACHED", "VPC_ATTACHED", "VPC_DETACHED", "FIREWALL_RULE_CREATED", "FIREWALL_RULE_UPDATED", "FIREWALL_RULE_DELETED", "FIREWALL_UPDATED", "FIREWALL_RESET", "IP_ATTACHED", "IP_DETACHED", "IP_AUTO_ASSIGNED", "IP_RELEASED", "IP_ROTATED", "IP_PROTECTION_CHANGED", "ISO_UPLOADED", "ISO_IMPORTED", "TEMPLATE_CREATED", "TEMPLATE_IMPORTED", "IMAGE_DELETED", "VPC_DELETED", "VPC_ROUTER_CHANGED", "RECIPE_CREATED", "RECIPE_UPDATED", "RECIPE_DELETED", "DEDIBOX_POWER_ON", "DEDIBOX_POWER_OFF", "DEDIBOX_POWER_CYCLE", "DEDIBOX_SHUTDOWN", "DEDIBOX_RECONFIGURED", "DEDIBOX_VNC_RESET", "TOKEN_CREATED", "TOKEN_DELETED", "TOKEN_EXPOSED_REVOKED", "ACCOUNT_REGISTERED", "ACCOUNT_LOGIN_PASSWORD", "ACCOUNT_LOGIN_SSO", "ACCOUNT_LOGIN_PASSKEY", "ACCOUNT_LOGIN_PASSWORD_FAILED", "ACCOUNT_LOGIN_SSO_FAILED", "ACCOUNT_LOGIN_PASSKEY_FAILED", "ACCOUNT_LOGOUT", "ACCOUNT_SESSIONS_REVOKED", "ACCOUNT_SESSION_LOCATION_REVOKED", "ACCOUNT_RENAMED", "ACCOUNT_EMAIL_CHANGE_REQUESTED", "ACCOUNT_EMAIL_CHANGED", "ACCOUNT_EMAIL_VERIFIED", "ACCOUNT_EMAIL_UNVERIFIED", "ACCOUNT_PASSWORD_CHANGED", "ACCOUNT_PASSWORD_RESET_REQUESTED", "ACCOUNT_PASSWORD_RESET", "ACCOUNT_PASSWORD_CLEARED", "ACCOUNT_MFA_ENABLED", "ACCOUNT_MFA_DISABLED", "ACCOUNT_RECOVERY_CODE_REGENERATED", "ACCOUNT_CREDENTIAL_ADDED", "ACCOUNT_CREDENTIAL_RENAMED", "ACCOUNT_CREDENTIAL_REMOVED", "ACCOUNT_IDENTITY_LINKED", "ACCOUNT_IDENTITY_UNLINKED", "ACCOUNT_LOCKED", "ACCOUNT_UNLOCKED", "ACCOUNT_BILLING_LINK_CHANGED", "ACCOUNT_DELETED", "OAUTH_APPLICATION_AUTHORIZED", "OAUTH_APPLICATION_DEAUTHORIZED", "OAUTH_TOKEN_ISSUED", "OAUTH_TOKEN_REFRESHED", "OAUTH_TOKEN_REVOKED", "OAUTH_APPLICATION_CREATED", "OAUTH_APPLICATION_UPDATED", "OAUTH_APPLICATION_DELETED", "OAUTH_APPLICATION_SECRET_REGENERATED", "WORKSPACE_CREATED", "WORKSPACE_RENAMED", "WORKSPACE_SETTINGS_CHANGED", "WORKSPACE_DELETED", "MEMBER_INVITED", "MEMBER_INVITE_UPDATED", "MEMBER_INVITE_REVOKED", "MEMBER_JOINED", "MEMBER_ROLE_CHANGED", "MEMBER_PERMISSIONS_CHANGED", "MEMBER_REMOVED", "SSH_KEY_ADDED", "SSH_KEY_DELETED", "REGISTRY_CREDENTIAL_ADDED", "REGISTRY_CREDENTIAL_UPDATED", "REGISTRY_CREDENTIAL_DELETED" ], "type": "string" }, "AuditActorType": { "description": "Kind of principal that performed an audited action", "enum": [ "USER", "TOKEN", "SYSTEM", "ANONYMOUS", "APPLICATION" ], "type": "string" }, "AuditChange": { "description": "A field changed by an audited action", "properties": { "after": { "description": "Value after the action", "type": [ "string", "null" ] }, "before": { "description": "Value before the action", "type": [ "string", "null" ] } }, "required": [ "after", "before" ], "type": "object" }, "AuditContext": { "description": "Details of an audited action", "properties": { "changes": { "additionalProperties": { "$ref": "#/components/schemas/AuditChange" }, "description": "Fields the action changed, keyed by field name", "type": "object" }, "details": { "anyOf": [ { "$ref": "#/components/schemas/AuditDetails" }, { "type": "null" } ], "description": "Parameters of the action, for the actions that have any" }, "refs": { "additionalProperties": { "$ref": "#/components/schemas/AuditRef" }, "description": "Other resources involved, keyed by their role in the action", "type": "object" } }, "required": [ "changes", "details", "refs" ], "type": "object" }, "AuditDetails": { "description": "Parameters of the action, shaped by `type`", "discriminator": { "mapping": { "account_lock": "#/components/schemas/AccountLockDetails", "billing": "#/components/schemas/BillingDetails", "credential": "#/components/schemas/CredentialDetails", "credential_exposure": "#/components/schemas/CredentialExposureDetails", "email_change": "#/components/schemas/EmailChangeDetails", "firmware_change": "#/components/schemas/FirmwareChangeDetails", "identity": "#/components/schemas/IdentityDetails", "import": "#/components/schemas/ImportDetails", "invite": "#/components/schemas/InviteDetails", "login": "#/components/schemas/LoginDetails", "login_failure": "#/components/schemas/LoginFailureDetails", "membership": "#/components/schemas/MembershipDetails", "mfa_disabled": "#/components/schemas/MfaDisabledDetails", "oauth_grant": "#/components/schemas/OAuthGrantDetails", "oauth_revocation": "#/components/schemas/OAuthRevocationDetails", "packet_capture": "#/components/schemas/PacketCaptureDetails", "registration": "#/components/schemas/RegistrationDetails", "registry_credential_update": "#/components/schemas/RegistryCredentialUpdateDetails", "session_location": "#/components/schemas/SessionLocationDetails", "ssh_key": "#/components/schemas/SshKeyDetails", "termination_schedule": "#/components/schemas/TerminationScheduleDetails", "token": "#/components/schemas/TokenDetails", "upload": "#/components/schemas/UploadDetails", "vpc_router": "#/components/schemas/VpcRouterDetails" }, "propertyName": "type" }, "oneOf": [ { "$ref": "#/components/schemas/LoginDetails" }, { "$ref": "#/components/schemas/LoginFailureDetails" }, { "$ref": "#/components/schemas/RegistrationDetails" }, { "$ref": "#/components/schemas/MfaDisabledDetails" }, { "$ref": "#/components/schemas/CredentialDetails" }, { "$ref": "#/components/schemas/IdentityDetails" }, { "$ref": "#/components/schemas/EmailChangeDetails" }, { "$ref": "#/components/schemas/TokenDetails" }, { "$ref": "#/components/schemas/OAuthGrantDetails" }, { "$ref": "#/components/schemas/OAuthRevocationDetails" }, { "$ref": "#/components/schemas/TerminationScheduleDetails" }, { "$ref": "#/components/schemas/BillingDetails" }, { "$ref": "#/components/schemas/ImportDetails" }, { "$ref": "#/components/schemas/UploadDetails" }, { "$ref": "#/components/schemas/PacketCaptureDetails" }, { "$ref": "#/components/schemas/FirmwareChangeDetails" }, { "$ref": "#/components/schemas/InviteDetails" }, { "$ref": "#/components/schemas/MembershipDetails" }, { "$ref": "#/components/schemas/SshKeyDetails" }, { "$ref": "#/components/schemas/SessionLocationDetails" }, { "$ref": "#/components/schemas/RegistryCredentialUpdateDetails" }, { "$ref": "#/components/schemas/CredentialExposureDetails" }, { "$ref": "#/components/schemas/AccountLockDetails" }, { "$ref": "#/components/schemas/VpcRouterDetails" } ], "properties": { "type": { "type": "string" } }, "required": [ "type" ] }, "AuditLogView": { "description": "Audit log entry", "properties": { "action": { "$ref": "#/components/schemas/AuditAction", "description": "Action performed" }, "actor_asn": { "description": "Autonomous system number announcing the actor's address, when available", "example": "3320", "type": [ "string", "null" ] }, "actor_country": { "description": "ISO 3166-1 alpha-2 country of the actor's address, when available", "example": "DE", "type": [ "string", "null" ] }, "actor_id": { "description": "User or token that performed the action, absent for system actors", "example": "1053072706808680448", "type": [ "string", "null" ] }, "actor_ip": { "description": "IP address the actor connected from, when available", "example": "203.0.113.7", "type": [ "string", "null" ] }, "actor_name": { "description": "Name of the actor at the time of the action", "example": "Jane Doe", "type": "string" }, "actor_network": { "description": "Name of the network announcing the actor's address, when available", "example": "Deutsche Telekom AG", "type": [ "string", "null" ] }, "actor_network_type": { "anyOf": [ { "$ref": "#/components/schemas/NetworkType" }, { "type": "null" } ], "description": "Kind of network the actor's address belongs to, when available" }, "actor_staff": { "description": "Whether the action was performed by platform staff", "type": "boolean" }, "actor_type": { "$ref": "#/components/schemas/AuditActorType", "description": "Kind of principal that performed the action" }, "context": { "$ref": "#/components/schemas/AuditContext", "description": "Resources involved, changed fields and parameters of the action" }, "created": { "description": "When the action happened", "example": "2026-03-18T09:12:20Z", "format": "date-time", "type": "string" }, "id": { "description": "Audit log entry ID", "example": "1498223722102817012", "type": "string" }, "target_id": { "description": "ID of the resource the entry is filed under", "example": "1463106077196308568", "type": [ "string", "null" ] }, "target_kind": { "$ref": "#/components/schemas/AuditTarget", "description": "Kind of resource the entry is filed under" }, "target_name": { "description": "Name of the resource at the time of the action", "example": "web-1", "type": [ "string", "null" ] }, "user_id": { "description": "Account the action happened on", "example": "1053072706808680448", "type": [ "string", "null" ] }, "workflow_id": { "description": "Workflow started by the action", "example": "9f2c1d7a-4b83-4c1e-9a55-6d0f3b8e27c4", "type": [ "string", "null" ] }, "workspace_id": { "description": "Workspace the action happened in", "example": "1405508720263180365", "type": [ "string", "null" ] } }, "required": [ "action", "actor_asn", "actor_country", "actor_id", "actor_ip", "actor_name", "actor_network", "actor_network_type", "actor_staff", "actor_type", "context", "created", "id", "target_id", "target_kind", "target_name", "user_id", "workflow_id", "workspace_id" ], "type": "object" }, "AuditRef": { "description": "A resource involved in an audited action", "properties": { "id": { "description": "Resource ID", "example": "1506320201023500406", "type": "string" }, "name": { "description": "Resource name at the time of the action", "type": [ "string", "null" ] } }, "required": [ "id", "name" ], "type": "object" }, "AuditTarget": { "description": "Kind of resource an audit log entry is filed under", "enum": [ "INSTANCE", "DEDIBOX", "IMAGE", "VPC", "RECIPE", "FLOATING_IP", "TOKEN", "USER", "OAUTH_APPLICATION", "WORKSPACE", "SSH_KEY", "REGISTRY_CREDENTIAL" ], "type": "string" }, "BillingDetails": { "description": "Billing context of an action driven by billing or WHMCS", "properties": { "cause": { "anyOf": [ { "$ref": "#/components/schemas/SubjectEventCause" }, { "type": "null" } ], "description": "Why billing took the action" }, "subject": { "description": "Billing subject the action applied to", "example": "1547471862637355008", "type": [ "string", "null" ] }, "type": { "enum": [ "billing" ], "type": "string" }, "whmcs_service": { "description": "WHMCS service the action came from", "example": 4211, "format": "int32", "type": [ "integer", "null" ] } }, "required": [ "cause", "subject", "type", "whmcs_service" ], "type": "object" }, "BootDiskAction": { "description": "What happens to the boot disk during a firmware change", "enum": [ "KEEP", "WIPE" ], "type": "string" }, "CreateInviteRequest": { "properties": { "email": { "description": "Email address to invite", "type": "string" }, "role": { "description": "Governance role", "enum": [ "member", "admin", "owner" ], "type": "string" }, "write_kinds": { "description": "Resource kinds the member may write; ['*'] for all, empty or null for read-only", "items": { "enum": [ "instance", "dedibox", "app", "image", "net_balancer", "disk", "floating_ip", "*" ], "type": "string" }, "type": [ "array", "null" ] } }, "required": [ "email", "role" ], "type": "object" }, "CreateOAuthApplicationRequest": { "description": "Request to register a new OAuth application", "properties": { "description": { "description": "Application description, or null for none", "maxLength": 1024, "type": [ "string", "null" ] }, "name": { "description": "Application name", "example": "Acme Dashboard", "maxLength": 128, "minLength": 4, "type": "string" }, "redirect_uris": { "description": "Allowed redirect URIs, at least one (HTTPS required, localhost HTTP allowed)", "items": { "type": "string" }, "type": "array" }, "scopes": { "description": "OAuth scopes this application can request, at least one", "items": { "enum": [ "app:read", "app:write", "audit:read", "dedibox:read", "dedibox:write", "disk:read", "disk:write", "floating_ip:read", "floating_ip:write", "image:read", "image:write", "instance:read", "instance:write", "net_balancer:read", "net_balancer:write", "workspace:read", "workspace:write" ], "type": "string" }, "type": "array", "uniqueItems": true } }, "required": [ "name", "redirect_uris", "scopes" ], "type": "object" }, "CreateWorkspaceRequest": { "properties": { "name": { "description": "Workspace name", "example": "acme-production", "maxLength": 32, "minLength": 4, "type": "string" } }, "required": [ "name" ], "type": "object" }, "CredentialCreated": { "properties": { "credential": { "$ref": "#/components/schemas/CredentialView", "description": "The registered credential" }, "lock_code": { "description": "Account lock code, returned with the recovery code. Use it to lock the account.", "type": [ "string", "null" ] }, "recovery_code": { "description": "Recovery code, shown only here, when this is the account's first second factor. Signing in with it removes every second factor.", "type": [ "string", "null" ] } }, "required": [ "credential", "lock_code", "recovery_code" ], "type": "object" }, "CredentialDetails": { "description": "Security key or passkey parameters", "properties": { "kind": { "$ref": "#/components/schemas/CredentialKind", "description": "What the credential is registered as" }, "type": { "enum": [ "credential" ], "type": "string" } }, "required": [ "kind", "type" ], "type": "object" }, "CredentialExposureDetails": { "description": "Where a third party reported the token as exposed. Not verified.", "properties": { "location": { "description": "Reported location of the exposure", "example": "https://github.com/acme/app/blob/main/.env", "type": [ "string", "null" ] }, "source": { "description": "Reported kind of source the token was found in", "example": "commit", "type": [ "string", "null" ] }, "type": { "enum": [ "credential_exposure" ], "type": "string" } }, "required": [ "location", "source", "type" ], "type": "object" }, "CredentialKind": { "description": "What a WebAuthn credential is registered as", "enum": [ "SECURITY_KEY", "PASSKEY" ], "type": "string" }, "CredentialOptionsRequest": { "description": "What to register", "properties": { "kind": { "$ref": "#/components/schemas/CredentialKind", "description": "What the credential is registered as" } }, "required": [ "kind" ], "type": "object" }, "CredentialRegisterRequest": { "description": "The browser's answer to `POST credentials/options`, and a name for the credential", "properties": { "name": { "description": "Name for the credential", "maxLength": 64, "type": "string" }, "webauthn": { "$ref": "#/components/schemas/WebAuthnResponse", "description": "The browser's response" } }, "required": [ "name", "webauthn" ], "type": "object" }, "CredentialRenameRequest": { "properties": { "name": { "description": "Name for the credential", "maxLength": 64, "type": "string" } }, "required": [ "name" ], "type": "object" }, "CredentialRevokeRequest": { "description": "Credentials found exposed, to revoke", "properties": { "credentials": { "description": "Exposed credentials", "items": { "example": "gga.0123456789abcdef0123456789abcdef", "maxLength": 256, "type": "string" }, "maxItems": 100, "minItems": 1, "type": "array" }, "source": { "description": "Kind of source the credentials were found in", "example": "commit", "maxLength": 64, "pattern": "^[A-Za-z0-9._-]+$", "type": [ "string", "null" ] }, "url": { "description": "Public http(s) URL where the credentials were found", "example": "https://github.com/acme/app/blob/main/.env", "maxLength": 2048, "type": [ "string", "null" ] } }, "required": [ "credentials" ], "type": "object" }, "CredentialView": { "description": "Security key or passkey registered on an account", "properties": { "aaguid": { "description": "Authenticator model identifier, null when the authenticator does not report one", "example": "ee882879-721c-4913-9775-3dfcce97072a", "format": "uuid", "type": [ "string", "null" ] }, "backup_eligible": { "description": "Whether the credential can be synced to other devices", "type": "boolean" }, "backup_state": { "description": "Whether the credential is synced to other devices", "type": "boolean" }, "created": { "description": "When the credential was registered", "example": "2026-03-05T12:44:58Z", "format": "date-time", "type": "string" }, "id": { "description": "Credential ID", "example": "1479097389678620681", "type": "string" }, "kind": { "$ref": "#/components/schemas/CredentialKind", "description": "What the credential is registered as" }, "last_used": { "description": "When the credential was last used", "example": "2026-07-20T09:12:44Z", "format": "date-time", "type": [ "string", "null" ] }, "name": { "description": "Name the user gave the credential", "example": "YubiKey 5C", "type": "string" }, "transports": { "description": "How the browser can reach the authenticator", "items": { "example": "usb", "type": "string" }, "type": "array", "uniqueItems": true } }, "required": [ "aaguid", "backup_eligible", "backup_state", "created", "id", "kind", "last_used", "name", "transports" ], "type": "object" }, "Elevation": { "description": "Sudo mode on the current login", "properties": { "expires_at": { "description": "When sudo mode ends, extended by each sensitive action. Null when not in sudo mode", "format": "date-time", "type": [ "string", "null" ] } }, "required": [ "expires_at" ], "type": "object" }, "ElevationRequest": { "description": "Proof that starts sudo mode: a second factor, or the password while the account has none", "properties": { "password": { "description": "Account password, accepted only while the account has no second factor", "format": "password", "type": [ "string", "null" ] }, "totp": { "description": "Authenticator app code", "example": "000000", "type": [ "string", "null" ] }, "webauthn": { "anyOf": [ { "$ref": "#/components/schemas/WebAuthnResponse" }, { "type": "null" } ], "description": "A security key or passkey answering `POST elevation/options`" } }, "type": "object" }, "EmailChangeDetails": { "description": "Email change parameters", "properties": { "email": { "description": "Address the confirmation link was sent to", "example": "ada@example.com", "type": "string" }, "type": { "enum": [ "email_change" ], "type": "string" } }, "required": [ "email", "type" ], "type": "object" }, "EnrichedMemberUserViewMemberGrants": { "properties": { "email": { "description": "User's email address", "type": "string" }, "id": { "description": "User ID", "example": "1405506895740940329", "type": "string" }, "name": { "description": "User's name", "example": "Ada Lovelace", "type": "string" }, "role": { "description": "Governance role", "type": "string" }, "write_kinds": { "description": "Kinds the member may write", "items": { "enum": [ "instance", "dedibox", "app", "image", "net_balancer", "disk", "floating_ip", "*" ], "type": "string" }, "type": "array" } }, "required": [ "email", "id", "name", "role", "write_kinds" ], "type": "object" }, "EnrichedUserDetailViewUserLive": { "properties": { "email": { "description": "User's email address", "type": "string" }, "flags": { "description": "User's account flags", "items": { "$ref": "#/components/schemas/UserFlags" }, "type": "array", "uniqueItems": true }, "id": { "description": "User ID", "example": "1405506895740940329", "type": "string" }, "mfa_methods": { "description": "Second factors enrolled on the account", "items": { "description": "A second factor an account can enrol", "enum": [ "TOTP", "SECURITY_KEY", "PASSKEY" ], "type": "string" }, "type": "array", "uniqueItems": true }, "name": { "description": "User's name", "example": "Ada Lovelace", "type": "string" }, "whmcs_id": { "description": "WHMCS client ID linked to this account", "example": 4821, "format": "int32", "minimum": 1, "type": [ "integer", "null" ] } }, "required": [ "email", "flags", "id", "mfa_methods", "name", "whmcs_id" ], "type": "object" }, "FirmwareChangeDetails": { "description": "Firmware change parameters", "properties": { "disk": { "$ref": "#/components/schemas/BootDiskAction", "description": "What happened to the boot disk" }, "sector_size": { "description": "Sector size of the boot disk after the change, in bytes", "example": 4096, "format": "int32", "type": "integer" }, "type": { "enum": [ "firmware_change" ], "type": "string" } }, "required": [ "disk", "sector_size", "type" ], "type": "object" }, "IdentityDetails": { "description": "Linked identity parameters", "properties": { "provider": { "$ref": "#/components/schemas/IdentityProvider", "description": "External sign-in provider" }, "type": { "enum": [ "identity" ], "type": "string" } }, "required": [ "provider", "type" ], "type": "object" }, "IdentityLinkRequest": { "description": "Completes linking an external provider to the signed-in account", "properties": { "code": { "description": "Authorization code from the provider redirect", "example": "8f1c2d3e4a5b6c7d8e9f", "type": "string" }, "provider": { "$ref": "#/components/schemas/IdentityProvider", "description": "Provider that issued the code", "enum": [ "google", "github" ], "example": "github" }, "state": { "description": "The state value issued when the link flow started", "example": "9f8e7d6c5b4a39281706f5e4d3c2b1a0", "type": "string" } }, "required": [ "code", "provider", "state" ], "type": "object" }, "IdentityProvider": { "enum": [ "google", "github" ], "type": "string" }, "IdentityStartRequest": { "description": "Begins linking an external provider to the signed-in account", "properties": { "provider": { "$ref": "#/components/schemas/IdentityProvider", "description": "Provider to link", "enum": [ "google", "github" ], "example": "github" }, "redirect_uri": { "description": "Which of the configured redirect URIs the provider should return to. Defaults to the first configured URI.", "example": "https://dash.galaxygate.net/account/identities/callback", "type": [ "string", "null" ] } }, "required": [ "provider" ], "type": "object" }, "ImportDetails": { "description": "Image import parameters", "properties": { "type": { "enum": [ "import" ], "type": "string" }, "url": { "description": "URL the image was downloaded from", "example": "https://example.com/debian.qcow2", "type": "string" } }, "required": [ "type", "url" ], "type": "object" }, "InviteDetails": { "description": "Workspace invite parameters", "properties": { "email": { "description": "Address the invite was sent to, absent for open invite links", "example": "ada@example.com", "type": [ "string", "null" ] }, "role": { "$ref": "#/components/schemas/Role", "description": "Governance role in the workspace" }, "type": { "enum": [ "invite" ], "type": "string" }, "write_kinds": { "description": "Kinds the member may write", "items": { "enum": [ "instance", "dedibox", "app", "image", "net_balancer", "disk", "floating_ip", "*" ], "type": "string" }, "type": "array" } }, "required": [ "email", "role", "type", "write_kinds" ], "type": "object" }, "InviteListView": { "description": "Invite list item", "properties": { "accepted": { "description": "When accepted, if it has been", "example": "2026-04-02T15:22:08Z", "format": "date-time", "type": [ "string", "null" ] }, "email": { "description": "Invited email", "type": [ "string", "null" ] }, "expires": { "description": "Expiry time", "example": "2026-04-09T14:51:36Z", "format": "date-time", "type": [ "string", "null" ] }, "id": { "description": "Invite ID", "example": "1489276118237192255", "type": "string" }, "role": { "description": "Granted governance role", "type": [ "string", "null" ] }, "workspace": { "$ref": "#/components/schemas/WorkspaceSimple", "description": "Workspace the invite grants access to" }, "write_kinds": { "description": "Kinds the member may write", "items": { "enum": [ "instance", "dedibox", "app", "image", "net_balancer", "disk", "floating_ip", "audit", "*" ], "type": "string" }, "type": "array" } }, "required": [ "accepted", "email", "expires", "id", "role", "workspace", "write_kinds" ], "type": "object" }, "InviteView": { "properties": { "accepted": { "description": "When accepted, if it has been", "example": "2026-04-02T15:22:08Z", "format": "date-time", "type": [ "string", "null" ] }, "email": { "description": "Invited email", "type": [ "string", "null" ] }, "expires": { "description": "Expiry time", "example": "2026-04-09T14:51:36Z", "format": "date-time", "type": [ "string", "null" ] }, "id": { "description": "Invite ID", "example": "1489276118237192255", "type": "string" }, "role": { "description": "Granted governance role", "type": [ "string", "null" ] }, "workspace_id": { "description": "Workspace ID", "example": "1405508720263180365", "type": "string" }, "workspace_name": { "description": "Workspace name", "example": "acme-production", "type": [ "string", "null" ] }, "write_kinds": { "description": "Kinds the member may write", "items": { "enum": [ "instance", "dedibox", "app", "image", "net_balancer", "disk", "floating_ip", "*" ], "type": "string" }, "type": "array" } }, "required": [ "accepted", "email", "expires", "id", "role", "workspace_id", "workspace_name", "write_kinds" ], "type": "object" }, "KeysetResultAuditLogView": { "properties": { "after": { "type": [ "string", "null" ] }, "before": { "type": [ "string", "null" ] }, "has_next": { "type": "boolean" }, "has_previous": { "type": "boolean" }, "items": { "items": { "$ref": "#/components/schemas/AuditLogView" }, "type": "array" }, "limit": { "description": "Limit of items returned per page", "format": "int32", "maximum": 100, "minimum": 1, "type": "integer" }, "page": { "description": "Page number", "format": "int32", "maximum": 1000, "minimum": 1, "type": "integer" }, "total": { "description": "Total number of matching items", "format": "int64", "minimum": 0, "type": "integer" } }, "required": [ "after", "before", "has_next", "has_previous", "items", "limit", "page", "total" ], "type": "object" }, "KeysetResultCredentialView": { "properties": { "after": { "type": [ "string", "null" ] }, "before": { "type": [ "string", "null" ] }, "has_next": { "type": "boolean" }, "has_previous": { "type": "boolean" }, "items": { "items": { "$ref": "#/components/schemas/CredentialView" }, "type": "array" }, "limit": { "description": "Limit of items returned per page", "format": "int32", "maximum": 100, "minimum": 1, "type": "integer" }, "page": { "description": "Page number", "format": "int32", "maximum": 1000, "minimum": 1, "type": "integer" }, "total": { "description": "Total number of matching items", "format": "int64", "minimum": 0, "type": "integer" } }, "required": [ "after", "before", "has_next", "has_previous", "items", "limit", "page", "total" ], "type": "object" }, "KeysetResultEnrichedMemberUserViewMemberGrants": { "properties": { "after": { "type": [ "string", "null" ] }, "before": { "type": [ "string", "null" ] }, "has_next": { "type": "boolean" }, "has_previous": { "type": "boolean" }, "items": { "items": { "$ref": "#/components/schemas/EnrichedMemberUserViewMemberGrants" }, "type": "array" }, "limit": { "description": "Limit of items returned per page", "format": "int32", "maximum": 100, "minimum": 1, "type": "integer" }, "page": { "description": "Page number", "format": "int32", "maximum": 1000, "minimum": 1, "type": "integer" }, "total": { "description": "Total number of matching items", "format": "int64", "minimum": 0, "type": "integer" } }, "required": [ "after", "before", "has_next", "has_previous", "items", "limit", "page", "total" ], "type": "object" }, "KeysetResultInviteListView": { "properties": { "after": { "type": [ "string", "null" ] }, "before": { "type": [ "string", "null" ] }, "has_next": { "type": "boolean" }, "has_previous": { "type": "boolean" }, "items": { "items": { "$ref": "#/components/schemas/InviteListView" }, "type": "array" }, "limit": { "description": "Limit of items returned per page", "format": "int32", "maximum": 100, "minimum": 1, "type": "integer" }, "page": { "description": "Page number", "format": "int32", "maximum": 1000, "minimum": 1, "type": "integer" }, "total": { "description": "Total number of matching items", "format": "int64", "minimum": 0, "type": "integer" } }, "required": [ "after", "before", "has_next", "has_previous", "items", "limit", "page", "total" ], "type": "object" }, "KeysetResultOAuthApplicationListView": { "properties": { "after": { "type": [ "string", "null" ] }, "before": { "type": [ "string", "null" ] }, "has_next": { "type": "boolean" }, "has_previous": { "type": "boolean" }, "items": { "items": { "$ref": "#/components/schemas/OAuthApplicationListView" }, "type": "array" }, "limit": { "description": "Limit of items returned per page", "format": "int32", "maximum": 100, "minimum": 1, "type": "integer" }, "page": { "description": "Page number", "format": "int32", "maximum": 1000, "minimum": 1, "type": "integer" }, "total": { "description": "Total number of matching items", "format": "int64", "minimum": 0, "type": "integer" } }, "required": [ "after", "before", "has_next", "has_previous", "items", "limit", "page", "total" ], "type": "object" }, "KeysetResultOAuthAuthorizationListView": { "properties": { "after": { "type": [ "string", "null" ] }, "before": { "type": [ "string", "null" ] }, "has_next": { "type": "boolean" }, "has_previous": { "type": "boolean" }, "items": { "items": { "$ref": "#/components/schemas/OAuthAuthorizationListView" }, "type": "array" }, "limit": { "description": "Limit of items returned per page", "format": "int32", "maximum": 100, "minimum": 1, "type": "integer" }, "page": { "description": "Page number", "format": "int32", "maximum": 1000, "minimum": 1, "type": "integer" }, "total": { "description": "Total number of matching items", "format": "int64", "minimum": 0, "type": "integer" } }, "required": [ "after", "before", "has_next", "has_previous", "items", "limit", "page", "total" ], "type": "object" }, "KeysetResultTokenListView": { "properties": { "after": { "type": [ "string", "null" ] }, "before": { "type": [ "string", "null" ] }, "has_next": { "type": "boolean" }, "has_previous": { "type": "boolean" }, "items": { "items": { "$ref": "#/components/schemas/TokenListView" }, "type": "array" }, "limit": { "description": "Limit of items returned per page", "format": "int32", "maximum": 100, "minimum": 1, "type": "integer" }, "page": { "description": "Page number", "format": "int32", "maximum": 1000, "minimum": 1, "type": "integer" }, "total": { "description": "Total number of matching items", "format": "int64", "minimum": 0, "type": "integer" } }, "required": [ "after", "before", "has_next", "has_previous", "items", "limit", "page", "total" ], "type": "object" }, "KeysetResultWorkspaceListView": { "properties": { "after": { "type": [ "string", "null" ] }, "before": { "type": [ "string", "null" ] }, "has_next": { "type": "boolean" }, "has_previous": { "type": "boolean" }, "items": { "items": { "$ref": "#/components/schemas/WorkspaceListView" }, "type": "array" }, "limit": { "description": "Limit of items returned per page", "format": "int32", "maximum": 100, "minimum": 1, "type": "integer" }, "page": { "description": "Page number", "format": "int32", "maximum": 1000, "minimum": 1, "type": "integer" }, "total": { "description": "Total number of matching items", "format": "int64", "minimum": 0, "type": "integer" } }, "required": [ "after", "before", "has_next", "has_previous", "items", "limit", "page", "total" ], "type": "object" }, "LockAccountRequest": { "description": "Request to lock an account with the lock code from a security email", "properties": { "code": { "description": "Account lock code", "type": "string" } }, "required": [ "code" ], "type": "object" }, "LockSource": { "description": "How the account was locked", "enum": [ "EMAIL", "SIGN_IN", "STAFF" ], "type": "string" }, "LoginDetails": { "description": "Sign-in parameters", "properties": { "mfa": { "$ref": "#/components/schemas/MfaMethod", "description": "How the second factor was satisfied" }, "provider": { "anyOf": [ { "$ref": "#/components/schemas/IdentityProvider" }, { "type": "null" } ], "description": "External provider used, absent for password sign-ins" }, "type": { "enum": [ "login" ], "type": "string" } }, "required": [ "mfa", "provider", "type" ], "type": "object" }, "LoginFailure": { "description": "Why a sign-in was rejected", "enum": [ "PASSWORD", "MFA", "PASSKEY", "LOCKED", "DEACTIVATED", "EMAIL_UNVERIFIED", "SYSTEM" ], "type": "string" }, "LoginFailureDetails": { "description": "Rejected sign-in parameters", "properties": { "provider": { "anyOf": [ { "$ref": "#/components/schemas/IdentityProvider" }, { "type": "null" } ], "description": "External provider used, absent for password sign-ins" }, "reason": { "$ref": "#/components/schemas/LoginFailure", "description": "Why the sign-in was rejected" }, "type": { "enum": [ "login_failure" ], "type": "string" } }, "required": [ "provider", "reason", "type" ], "type": "object" }, "LoginRequest": { "description": "Credentials for authenticating a user", "properties": { "email": { "description": "Account email address", "format": "email", "type": "string" }, "mfa": { "description": "Authenticator app code, or the recovery code. Omit it or send null when the account has no second factor", "type": [ "string", "null" ] }, "password": { "description": "Account password, or the account lock code to lock the account", "format": "password", "type": "string" }, "webauthn": { "anyOf": [ { "$ref": "#/components/schemas/WebAuthnResponse" }, { "type": "null" } ], "description": "A security key or passkey answering the `webauthn` options of the sign-in's `MfaChallenge`" } }, "required": [ "email", "password" ], "type": "object" }, "MemberView": { "properties": { "email": { "description": "User email", "type": "string" }, "name": { "description": "User name", "example": "Ada Lovelace", "type": "string" }, "role": { "description": "Governance role", "type": "string" }, "user_id": { "description": "User ID", "example": "1405506895740940329", "type": "string" }, "write_kinds": { "description": "Kinds the member may write", "items": { "enum": [ "instance", "dedibox", "app", "image", "net_balancer", "disk", "floating_ip", "*" ], "type": "string" }, "type": "array" } }, "required": [ "email", "name", "role", "user_id", "write_kinds" ], "type": "object" }, "MembershipDetails": { "description": "Workspace membership parameters", "properties": { "role": { "$ref": "#/components/schemas/Role", "description": "Governance role in the workspace" }, "type": { "enum": [ "membership" ], "type": "string" }, "write_kinds": { "description": "Kinds the member may write", "items": { "enum": [ "instance", "dedibox", "app", "image", "net_balancer", "disk", "floating_ip", "*" ], "type": "string" }, "type": "array" } }, "required": [ "role", "type", "write_kinds" ], "type": "object" }, "MfaChallenge": { "description": "The operation needs a second factor; retry it with one of `methods`", "properties": { "code": { "description": "Always `missing_mfa`", "enum": [ "missing_mfa", "challenge_expired", "login_expired", "credential_unknown", "credential_rejected", "too_many_attempts", "mfa_enforced", "account_locked", "email_unverified", "session_relocated", "concurrent_modification", "resource_conflict", "insufficient_funds" ], "type": "string" }, "error": { "description": "Human-readable message", "type": "string" }, "methods": { "description": "Methods that can answer the challenge", "items": { "description": "A way to answer an MFA challenge", "enum": [ "PASSWORD", "SIGN_IN", "TOTP", "SECURITY_KEY", "PASSKEY" ], "type": "string" }, "type": "array", "uniqueItems": true }, "status": { "description": "The HTTP status", "example": 403, "format": "int32", "type": "integer" }, "webauthn": { "anyOf": [ { "$ref": "#/components/schemas/WebAuthnOptions" }, { "type": "null" } ], "description": "Assertion options for the account's security keys and passkeys, at sign-in only" } }, "required": [ "code", "error", "methods", "status", "webauthn" ], "type": "object" }, "MfaDisabledDetails": { "description": "Two-factor removal parameters", "properties": { "method": { "$ref": "#/components/schemas/MfaRemoval", "description": "How two-factor authentication was removed" }, "type": { "enum": [ "mfa_disabled" ], "type": "string" } }, "required": [ "method", "type" ], "type": "object" }, "MfaMethod": { "description": "How the second factor of a sign-in was satisfied", "enum": [ "NONE", "TOTP", "SECURITY_KEY", "PASSKEY", "RECOVERY_CODE" ], "type": "string" }, "MfaRemoval": { "description": "How two-factor authentication was removed", "enum": [ "SETTINGS", "RECOVERY_CODE", "STAFF" ], "type": "string" }, "NetworkType": { "enum": [ "PROXY", "DATACENTER", "RESIDENTIAL", "UNKNOWN" ], "type": "string" }, "OAuthApplicationCreatedResponse": { "description": "OAuth application creation response. The client secret is only returned once.", "properties": { "active": { "description": "Whether the application is active", "type": "boolean" }, "client_id": { "description": "Public client identifier", "example": "9f1c2d3e4b5a47c8b9d0e1f2a3b4c5d6", "type": "string" }, "client_secret": { "description": "Client secret, save it securely. Only returned once.", "type": "string" }, "created": { "description": "When the application was registered", "example": "2026-03-05T12:44:58Z", "format": "date-time", "type": "string" }, "description": { "description": "Application description", "type": "string" }, "id": { "description": "Application ID", "example": "1479097389678620681", "type": "string" }, "name": { "description": "Application name", "example": "Acme Dashboard", "type": "string" }, "redirect_uris": { "description": "Allowed redirect URIs", "items": { "type": "string" }, "type": "array" }, "scopes": { "description": "Allowed OAuth scopes", "items": { "enum": [ "app:read", "app:write", "audit:read", "dedibox:read", "dedibox:write", "disk:read", "disk:write", "floating_ip:read", "floating_ip:write", "image:read", "image:write", "instance:read", "instance:write", "net_balancer:read", "net_balancer:write", "workspace:read", "workspace:write" ], "type": "string" }, "type": "array", "uniqueItems": true } }, "required": [ "active", "client_id", "client_secret", "created", "description", "id", "name", "redirect_uris", "scopes" ], "type": "object" }, "OAuthApplicationListView": { "description": "OAuth application details", "properties": { "active": { "description": "Whether this application is active", "type": "boolean" }, "client_id": { "description": "Public client identifier", "type": "string" }, "created": { "description": "When this application was registered", "example": "2026-03-05T12:44:58Z", "format": "date-time", "type": "string" }, "description": { "description": "Application description", "type": [ "string", "null" ] }, "id": { "description": "Application ID", "example": "1479097389678620681", "type": "string" }, "name": { "description": "Application name", "example": "Acme Dashboard", "type": "string" }, "owner": { "$ref": "#/components/schemas/UserSimple", "description": "Staff member who registered this application" }, "redirect_uris": { "description": "Allowed redirect URIs", "items": { "type": "string" }, "type": "array" }, "scopes": { "description": "Allowed OAuth scopes", "items": { "enum": [ "app:read", "app:write", "audit:read", "dedibox:read", "dedibox:write", "disk:read", "disk:write", "floating_ip:read", "floating_ip:write", "image:read", "image:write", "instance:read", "instance:write", "net_balancer:read", "net_balancer:write", "workspace:read", "workspace:write" ], "type": "string" }, "type": "array", "uniqueItems": true } }, "required": [ "active", "client_id", "created", "description", "id", "name", "owner", "redirect_uris", "scopes" ], "type": "object" }, "OAuthApplicationSimple": { "description": "OAuth application reference", "properties": { "description": { "description": "Application description", "type": [ "string", "null" ] }, "id": { "description": "Application ID", "example": "1479097389678620681", "type": "string" }, "name": { "description": "Application name", "example": "Acme Dashboard", "type": "string" } }, "required": [ "description", "id", "name" ], "type": "object" }, "OAuthAuthorizationListView": { "description": "OAuth authorization (user approval of an application)", "properties": { "application": { "$ref": "#/components/schemas/OAuthApplicationSimple", "description": "OAuth application that was authorized" }, "created": { "description": "When this authorization was granted", "example": "2026-03-05T12:44:58Z", "format": "date-time", "type": "string" }, "id": { "description": "Authorization ID", "example": "1479097389678620681", "type": "string" }, "last_used": { "description": "When this authorization was last used", "example": "2026-07-20T09:12:44Z", "format": "date-time", "type": [ "string", "null" ] }, "scopes": { "description": "Approved scopes", "items": { "enum": [ "app:read", "app:write", "audit:read", "dedibox:read", "dedibox:write", "disk:read", "disk:write", "floating_ip:read", "floating_ip:write", "image:read", "image:write", "instance:read", "instance:write", "net_balancer:read", "net_balancer:write", "workspace:read", "workspace:write" ], "type": "string" }, "type": "array", "uniqueItems": true } }, "required": [ "application", "created", "id", "last_used", "scopes" ], "type": "object" }, "OAuthAuthorizeInfoResponse": { "description": "Information about an OAuth authorization request for the consent screen", "properties": { "application": { "$ref": "#/components/schemas/App", "description": "Application requesting authorization" }, "previously_approved_scopes": { "description": "Scopes previously approved by this user (empty if first authorization)", "items": { "enum": [ "app:read", "app:write", "audit:read", "dedibox:read", "dedibox:write", "disk:read", "disk:write", "floating_ip:read", "floating_ip:write", "image:read", "image:write", "instance:read", "instance:write", "net_balancer:read", "net_balancer:write", "workspace:read", "workspace:write" ], "type": "string" }, "type": "array", "uniqueItems": true }, "requested_scopes": { "description": "Scopes the application is requesting", "items": { "enum": [ "app:read", "app:write", "audit:read", "dedibox:read", "dedibox:write", "disk:read", "disk:write", "floating_ip:read", "floating_ip:write", "image:read", "image:write", "instance:read", "instance:write", "net_balancer:read", "net_balancer:write", "workspace:read", "workspace:write" ], "type": "string" }, "type": "array", "uniqueItems": true } }, "required": [ "application", "previously_approved_scopes", "requested_scopes" ], "type": "object" }, "OAuthAuthorizeRequest": { "description": "Request to approve or deny an OAuth authorization", "properties": { "approve": { "description": "Whether the user approves the request", "type": "boolean" }, "client_id": { "description": "Client identifier", "example": "9f1c2d3e4b5a47c8b9d0e1f2a3b4c5d6", "type": "string" }, "code_challenge": { "description": "PKCE code challenge (base64url-encoded SHA-256)", "type": "string" }, "code_challenge_method": { "description": "PKCE method, must be 'S256'", "type": "string" }, "redirect_uri": { "description": "Redirect URI", "type": "string" }, "response_type": { "description": "Response type, must be 'code'", "type": "string" }, "scope": { "description": "Approved scopes", "items": { "enum": [ "app:read", "app:write", "audit:read", "dedibox:read", "dedibox:write", "disk:read", "disk:write", "floating_ip:read", "floating_ip:write", "image:read", "image:write", "instance:read", "instance:write", "net_balancer:read", "net_balancer:write", "workspace:read", "workspace:write" ], "type": "string" }, "type": "array", "uniqueItems": true }, "state": { "description": "Opaque state parameter", "type": "string" } }, "required": [ "approve", "client_id", "code_challenge", "code_challenge_method", "redirect_uri", "response_type", "scope", "state" ], "type": "object" }, "OAuthAuthorizeResponse": { "description": "Authorization response containing the redirect URI with authorization code", "properties": { "redirect_uri": { "description": "Redirect URI with authorization code and state appended", "type": "string" } }, "required": [ "redirect_uri" ], "type": "object" }, "OAuthGrantDetails": { "description": "OAuth consent parameters", "properties": { "scopes": { "description": "Scopes granted to the application", "items": { "type": "string" }, "type": "array" }, "type": { "enum": [ "oauth_grant" ], "type": "string" } }, "required": [ "scopes", "type" ], "type": "object" }, "OAuthRevocationDetails": { "description": "OAuth token revocation parameters", "properties": { "reason": { "$ref": "#/components/schemas/OAuthRevocationReason", "description": "Why the tokens were revoked" }, "type": { "enum": [ "oauth_revocation" ], "type": "string" } }, "required": [ "reason", "type" ], "type": "object" }, "OAuthRevocationReason": { "description": "Why OAuth tokens were revoked", "enum": [ "CLIENT", "CODE_REUSE" ], "type": "string" }, "OAuthSecretRegeneratedResponse": { "description": "Response containing the regenerated client secret", "properties": { "client_secret": { "description": "New client secret, save it securely. Only returned once.", "type": "string" } }, "required": [ "client_secret" ], "type": "object" }, "PacketCaptureDetails": { "description": "Packet capture parameters", "properties": { "duration_seconds": { "description": "Capture length in seconds", "example": 30, "format": "int64", "type": "integer" }, "type": { "enum": [ "packet_capture" ], "type": "string" } }, "required": [ "duration_seconds", "type" ], "type": "object" }, "PasskeyLoginRequest": { "description": "The browser's answer to `POST /v1/login/passkey/options`", "properties": { "webauthn": { "$ref": "#/components/schemas/WebAuthnResponse", "description": "The browser's response" } }, "required": [ "webauthn" ], "type": "object" }, "PatchWorkspaceRequest": { "properties": { "disable_ssh_password": { "description": "Disable SSH password authentication when SSH keys are present", "type": "boolean" }, "mfa_required": { "description": "Require all members to have 2FA enabled", "type": "boolean" }, "name": { "description": "Workspace name", "example": "acme-production", "maxLength": 32, "minLength": 4, "type": "string" }, "order_approval_required": { "description": "Hold orders from members other than the owner until the owner approves them", "type": "boolean" } }, "type": "object" }, "RecoveryCode": { "properties": { "lock_code": { "description": "Account lock code. Use it to lock the account. It does not change until the account is locked. Null when the recovery code is null.", "example": "3f1c2a9e-6b7d-4e8f-9a0b-1c2d3e4f5a6b", "type": [ "string", "null" ] }, "recovery_code": { "description": "Recovery code, shown only here. Signing in with it removes every second factor. 32 characters of base32 (`A-Z`, `2-7`); accepted in any case, with spaces and `-` ignored. Null when the account already had one.", "example": "JBSWY3DPEHPK3PXPJBSWY3DPEHPK3PXP", "type": [ "string", "null" ] } }, "required": [ "lock_code", "recovery_code" ], "type": "object" }, "RefreshTokenRequest": { "description": "Request to refresh a user session token", "properties": { "code": { "description": "Plaintext token code to refresh", "type": "string" } }, "required": [ "code" ], "type": "object" }, "RefreshTokenResponse": { "description": "Response containing the updated token expiration", "properties": { "expires": { "description": "New expiration", "example": "2026-03-05T13:44:58Z", "format": "date-time", "type": "string" } }, "required": [ "expires" ], "type": "object" }, "RegisterRequest": { "description": "Request to register a new account", "properties": { "coupon": { "description": "Coupon code to redeem once the account is created, or null for none. A code that cannot be redeemed does not block the registration.", "type": [ "string", "null" ] }, "email": { "description": "Account email address", "format": "email", "type": "string" }, "invite_code": { "description": "Workspace invite code to redeem, or null for none", "type": [ "string", "null" ] }, "name": { "description": "Account display name", "example": "Ada Lovelace", "maxLength": 32, "minLength": 3, "type": "string" }, "password": { "description": "Account password", "format": "password", "minLength": 8, "type": "string" } }, "required": [ "email", "name", "password" ], "type": "object" }, "RegistrationDetails": { "description": "Registration parameters", "properties": { "provider": { "anyOf": [ { "$ref": "#/components/schemas/IdentityProvider" }, { "type": "null" } ], "description": "External provider registered with, absent for password registrations" }, "type": { "enum": [ "registration" ], "type": "string" } }, "required": [ "provider", "type" ], "type": "object" }, "RegistryCredentialUpdateDetails": { "description": "Container registry credential change parameters", "properties": { "password_changed": { "description": "Whether the password was replaced", "type": "boolean" }, "type": { "enum": [ "registry_credential_update" ], "type": "string" } }, "required": [ "password_changed", "type" ], "type": "object" }, "ResetPasswordRequest": { "description": "Request a password reset email, or redeem a reset code to set a new password", "properties": { "code": { "description": "Reset code to redeem, or null to request a reset email for 'email' instead", "type": [ "string", "null" ] }, "email": { "description": "Address to send a reset email to. Only read when 'code' is absent or null", "format": "email", "type": [ "string", "null" ] }, "password": { "description": "New password. Required when 'code' is set, otherwise null", "format": "password", "minLength": 8, "type": [ "string", "null" ] } }, "type": "object" }, "Role": { "enum": [ "MEMBER", "ADMIN", "OWNER" ], "type": "string" }, "SessionLocationDetails": { "description": "Where the revoked session was signed in from; the actor carries where it was used from", "properties": { "login_asn": { "description": "Autonomous system of the sign-in", "example": 28573, "format": "int64", "type": [ "integer", "null" ] }, "login_country": { "description": "ISO 3166-1 alpha-2 country of the sign-in", "example": "BR", "type": "string" }, "type": { "enum": [ "session_location" ], "type": "string" } }, "required": [ "login_asn", "login_country", "type" ], "type": "object" }, "SetGrantsRequest": { "properties": { "write_kinds": { "description": "The kinds the member may write; replaces the member's current set. An empty list or null clears every write grant", "example": [ "instance", "disk" ], "items": { "enum": [ "instance", "dedibox", "app", "image", "net_balancer", "disk", "floating_ip", "*" ], "type": "string" }, "type": [ "array", "null" ] } }, "type": "object" }, "SetMemberRoleRequest": { "properties": { "role": { "description": "Governance role", "enum": [ "member", "admin" ], "example": "member", "type": "string" } }, "required": [ "role" ], "type": "object" }, "SshKeyDetails": { "description": "SSH key parameters", "properties": { "fingerprint": { "description": "SHA-256 fingerprint of the public key, absent when the stored key cannot be decoded", "example": "SHA256:47DEQpj8HBSa+/TImW+5JCeuQeRkm5NMpJWZG3hSuFU", "type": [ "string", "null" ] }, "type": { "enum": [ "ssh_key" ], "type": "string" } }, "required": [ "fingerprint", "type" ], "type": "object" }, "SsoCallbackRequest": { "description": "Authorization code returned by the provider, exchanged for a session token", "properties": { "code": { "description": "Authorization code from the provider redirect. Required on the first call, and omitted when retrying with a 2FA code.", "example": "4/0AeaYSHDx...", "type": [ "string", "null" ] }, "mfa": { "description": "Authenticator app code or recovery code, when the account has a second factor", "example": "000000", "type": [ "string", "null" ] }, "provider": { "$ref": "#/components/schemas/IdentityProvider", "description": "Provider that issued the code", "enum": [ "google", "github" ], "example": "google" }, "state": { "description": "The state value issued when the flow started", "example": "9f8e7d6c5b4a39281706f5e4d3c2b1a0", "type": "string" }, "webauthn": { "anyOf": [ { "$ref": "#/components/schemas/WebAuthnResponse" }, { "type": "null" } ], "description": "A security key or passkey answering the `webauthn` options of the `MfaChallenge`" } }, "required": [ "provider", "state" ], "type": "object" }, "SsoStartResponse": { "description": "Where to send the browser to authenticate with the provider", "properties": { "state": { "description": "Opaque single-use value echoed back by the provider. Pass it to the callback exactly as received, and reject a callback whose state does not match this value.", "example": "9f8e7d6c5b4a39281706f5e4d3c2b1a0", "type": "string" }, "url": { "description": "Provider URL to redirect the browser to", "example": "https://accounts.google.com/o/oauth2/v2/auth?response_type=code&client_id=...", "type": "string" } }, "required": [ "state", "url" ], "type": "object" }, "SubjectEventCause": { "enum": [ "PAYMENT", "OPERATOR", "DUNNING", "CANCELLATION", "UNCOLLECTIBLE" ], "type": "string" }, "TerminationScheduleDetails": { "description": "Scheduled termination parameters", "properties": { "terminate_on": { "description": "When the instance will be terminated", "example": "2026-03-19T19:30:21Z", "format": "date-time", "type": "string" }, "type": { "enum": [ "termination_schedule" ], "type": "string" } }, "required": [ "terminate_on", "type" ], "type": "object" }, "TokenCreateRequest": { "description": "Request to create a new API token", "properties": { "expires": { "description": "Token expiration", "example": "2027-03-05T12:44:58Z", "format": "date-time", "type": "string" }, "name": { "description": "Token name", "example": "ci-deploy", "maxLength": 48, "minLength": 4, "type": "string" }, "scopes": { "description": "Capability scopes to grant (e.g. instance:write, net_balancer:read)", "items": { "enum": [ "app:read", "app:write", "audit:read", "dedibox:read", "dedibox:write", "disk:read", "disk:write", "floating_ip:read", "floating_ip:write", "image:read", "image:write", "instance:read", "instance:write", "net_balancer:read", "net_balancer:write", "workspace:read", "workspace:write" ], "type": "string" }, "type": "array", "uniqueItems": true }, "subject": { "description": "Token scope: WORKSPACE (default) or RESOURCE (workspace-scope endpoint only). Null is the same as omitting it and selects WORKSPACE", "enum": [ "USER", "WORKSPACE", "RESOURCE" ], "type": [ "string", "null" ] }, "subject_id": { "description": "ID of the resource this token is pinned to. Required when subject is RESOURCE, null otherwise", "example": "1463106077196308568", "type": [ "string", "null" ] } }, "required": [ "expires", "name", "scopes" ], "type": "object" }, "TokenCreateResponse": { "description": "Token creation response. The plaintext code is only returned once, save it securely.", "properties": { "code": { "description": "Plaintext token code. Only returned at creation time, save it securely.", "type": "string" }, "created": { "description": "When this token was created", "example": "2026-03-05T12:44:58Z", "format": "date-time", "type": "string" }, "expires": { "description": "When this token expires", "example": "2027-03-05T12:44:58Z", "format": "date-time", "type": [ "string", "null" ] }, "id": { "description": "Token ID", "example": "1479097389678620681", "type": "string" }, "name": { "description": "Name of the token", "example": "ci-deploy", "type": [ "string", "null" ] }, "origin": { "$ref": "#/components/schemas/TokenOrigin", "description": "How this token was created" }, "scopes": { "description": "Capability scopes granted to this token", "items": { "enum": [ "app:read", "app:write", "audit:read", "dedibox:read", "dedibox:write", "disk:read", "disk:write", "floating_ip:read", "floating_ip:write", "image:read", "image:write", "instance:read", "instance:write", "net_balancer:read", "net_balancer:write", "workspace:read", "workspace:write" ], "type": "string" }, "type": "array", "uniqueItems": true }, "subject": { "$ref": "#/components/schemas/TokenSubject", "description": "Kind of entity this token is bound to" }, "subject_id": { "description": "ID of the entity this token is bound to", "example": "1405508720263180365", "type": "string" }, "workspace_id": { "description": "Workspace this token can reach (null for USER-subject tokens)", "example": "1405508720263180365", "type": [ "string", "null" ] } }, "required": [ "code", "created", "expires", "id", "name", "origin", "scopes", "subject", "subject_id", "workspace_id" ], "type": "object" }, "TokenDetails": { "description": "API token parameters", "properties": { "expires": { "description": "When the token expires", "example": "2027-01-01T00:00:00Z", "format": "date-time", "type": [ "string", "null" ] }, "scopes": { "description": "Scopes granted to the token", "items": { "type": "string" }, "type": "array" }, "type": { "enum": [ "token" ], "type": "string" } }, "required": [ "expires", "scopes", "type" ], "type": "object" }, "TokenListView": { "description": "Token list item", "properties": { "created": { "description": "When this token was created", "example": "2026-03-05T12:44:58Z", "format": "date-time", "type": "string" }, "created_by": { "anyOf": [ { "$ref": "#/components/schemas/UserSimple" }, { "type": "null" } ], "description": "User who created this token" }, "expires": { "description": "When this token expires", "example": "2027-03-05T12:44:58Z", "format": "date-time", "type": [ "string", "null" ] }, "id": { "description": "Token ID", "example": "1479097389678620681", "type": "string" }, "last_ip": { "description": "Last known IP address to use this token", "type": [ "string", "null" ] }, "last_used": { "description": "Last known time this token was used", "example": "2026-07-20T09:12:44Z", "format": "date-time", "type": [ "string", "null" ] }, "name": { "description": "Name of the token", "example": "ci-deploy", "type": [ "string", "null" ] }, "origin": { "$ref": "#/components/schemas/TokenOrigin", "description": "How this token was created" }, "scopes": { "description": "Capability scopes granted to this token", "items": { "enum": [ "app:read", "app:write", "audit:read", "dedibox:read", "dedibox:write", "disk:read", "disk:write", "floating_ip:read", "floating_ip:write", "image:read", "image:write", "instance:read", "instance:write", "net_balancer:read", "net_balancer:write", "workspace:read", "workspace:write" ], "type": "string" }, "type": "array", "uniqueItems": true }, "subject": { "$ref": "#/components/schemas/TokenSubject", "description": "Kind of entity this token is bound to" }, "subject_id": { "description": "ID of the entity this token is bound to", "example": "1405506895740940329", "type": "string" }, "user": { "anyOf": [ { "$ref": "#/components/schemas/UserSimple" }, { "type": "null" } ], "description": "User account that owns this token (USER-scope only)" }, "workspace_id": { "description": "Workspace this token can reach", "example": "1405508720263180365", "type": [ "string", "null" ] } }, "required": [ "created", "created_by", "expires", "id", "last_ip", "last_used", "name", "origin", "scopes", "subject", "subject_id", "user", "workspace_id" ], "type": "object" }, "TokenOrigin": { "enum": [ "SESSION", "API", "SYSTEM", "OAUTH" ], "type": "string" }, "TokenSubject": { "enum": [ "USER", "WORKSPACE", "RESOURCE" ], "type": "string" }, "TotpConfirmRequest": { "properties": { "code": { "description": "TOTP code", "type": "string" } }, "required": [ "code" ], "type": "object" }, "TotpCreated": { "properties": { "code": { "description": "TOTP Token", "type": "string" }, "uri": { "description": "TOTP URI", "format": "uri", "type": "string" } }, "required": [ "code", "uri" ], "type": "object" }, "UpdateInviteRequest": { "properties": { "role": { "description": "Governance role", "enum": [ "member", "admin", "owner" ], "type": "string" }, "write_kinds": { "description": "Resource kinds the member may write; ['*'] for all, empty or null for read-only", "items": { "enum": [ "instance", "dedibox", "app", "image", "net_balancer", "disk", "floating_ip", "*" ], "type": "string" }, "type": [ "array", "null" ] } }, "required": [ "role" ], "type": "object" }, "UpdateOAuthApplicationRequest": { "description": "Request to update an OAuth application", "properties": { "active": { "description": "Whether the application is active, or null to leave it unchanged", "type": [ "boolean", "null" ] }, "description": { "description": "Application description, or null to leave it unchanged", "maxLength": 1024, "type": [ "string", "null" ] }, "name": { "description": "Application name, or null to leave it unchanged", "example": "Acme Dashboard", "maxLength": 128, "minLength": 4, "type": [ "string", "null" ] }, "redirect_uris": { "description": "Allowed redirect URIs, or null to leave them unchanged", "items": { "type": "string" }, "type": [ "array", "null" ] }, "scopes": { "description": "OAuth scopes this application can request, or null to leave them unchanged", "items": { "enum": [ "app:read", "app:write", "audit:read", "dedibox:read", "dedibox:write", "disk:read", "disk:write", "floating_ip:read", "floating_ip:write", "image:read", "image:write", "instance:read", "instance:write", "net_balancer:read", "net_balancer:write", "workspace:read", "workspace:write" ], "type": "string" }, "type": [ "array", "null" ], "uniqueItems": true } }, "type": "object" }, "UpdatePasswordRequest": { "properties": { "old_password": { "description": "Old Password", "format": "password", "minLength": 8, "type": "string" }, "password": { "description": "New Password", "format": "password", "minLength": 8, "type": "string" } }, "required": [ "old_password", "password" ], "type": "object" }, "UpdateUserRequest": { "properties": { "email": { "description": "User's email", "format": "email", "type": "string" }, "name": { "description": "User's name", "example": "Ada Lovelace", "maxLength": 32, "minLength": 3, "type": "string" } }, "type": "object" }, "UploadDetails": { "description": "Image upload parameters", "properties": { "size": { "description": "Expected size in bytes", "example": 8152356864, "format": "int64", "type": "integer" }, "type": { "enum": [ "upload" ], "type": "string" } }, "required": [ "size", "type" ], "type": "object" }, "UserFlags": { "enum": [ "EMAIL_VERIFIED", "HAS_MFA", "ADMINISTRATOR", "SYSTEM", "LOCKED", "DEACTIVATED" ], "type": "string" }, "UserIdentityListView": { "description": "External login identity linked to an account", "properties": { "created": { "description": "When this identity was linked", "example": "2026-03-05T12:44:58Z", "format": "date-time", "type": "string" }, "email": { "description": "Email address reported by the provider", "example": "ada@gmail.com", "type": [ "string", "null" ] }, "id": { "description": "Identity ID", "example": "1479097389678620681", "type": "string" }, "last_used": { "description": "When this identity was last used to log in", "example": "2026-07-20T09:12:44Z", "format": "date-time", "type": [ "string", "null" ] }, "provider": { "$ref": "#/components/schemas/IdentityProvider", "description": "External identity provider", "enum": [ "google", "github" ], "example": "google" } }, "required": [ "created", "email", "id", "last_used", "provider" ], "type": "object" }, "UserSimple": { "description": "User reference", "properties": { "id": { "description": "User ID", "example": "1405506895740940329", "type": "string" }, "name": { "description": "User's name", "example": "Ada Lovelace", "type": "string" } }, "required": [ "id", "name" ], "type": "object" }, "VerifyEmailRequest": { "description": "Request to verify an email address, or to have a verification email resent", "properties": { "code": { "description": "Verification code to redeem, or null to request a new verification email for 'email'", "type": [ "string", "null" ] }, "email": { "description": "Address to send a new verification email to. Only read when 'code' is absent or null", "format": "email", "type": [ "string", "null" ] } }, "type": "object" }, "VpcRouterDetails": { "description": "VPC router parameters", "properties": { "dns_server": { "description": "DNS server offered to peers, absent when none is set", "example": "192.168.0.2", "type": [ "string", "null" ] }, "type": { "enum": [ "vpc_router" ], "type": "string" } }, "required": [ "dns_server", "type" ], "type": "object" }, "WebAuthnOptions": { "description": "A WebAuthn ceremony to run in the browser", "properties": { "challenge_id": { "description": "Send back with the browser's response", "type": "string" }, "public_key": { "description": "Options for `PublicKeyCredential.parseCreationOptionsFromJSON` or `parseRequestOptionsFromJSON`", "type": "object" } }, "required": [ "challenge_id", "public_key" ], "type": "object" }, "WebAuthnResponse": { "description": "The browser's answer to a WebAuthn ceremony", "properties": { "challenge_id": { "description": "From the options this answers", "type": "string" }, "credential": { "description": "`PublicKeyCredential.toJSON()` of the browser's credential", "type": "object" } }, "required": [ "challenge_id", "credential" ], "type": "object" }, "WorkspaceFlags": { "enum": [ "MFA_REQUIRED", "DISABLE_SSH_PASSWORD", "DO_NOT_SUSPEND", "ORDER_APPROVAL_REQUIRED" ], "type": "string" }, "WorkspaceListView": { "description": "Workspace list item", "properties": { "flags": { "description": "Workspace flags", "items": { "$ref": "#/components/schemas/WorkspaceFlags" }, "type": "array", "uniqueItems": true }, "id": { "description": "Workspace ID", "example": "1405508720263180365", "type": "string" }, "name": { "description": "Workspace name", "example": "acme-production", "type": "string" }, "owner": { "$ref": "#/components/schemas/UserSimple", "description": "Owner of the workspace" } }, "required": [ "flags", "id", "name", "owner" ], "type": "object" }, "WorkspaceSimple": { "properties": { "id": { "example": "1405508720263180365", "type": "string" }, "name": { "example": "acme-production", "type": "string" } }, "required": [ "id", "name" ], "type": "object" }, "BackupPlanSimple": { "description": "Backup plan reference", "properties": { "id": { "description": "Backup plan ID", "example": "1506320201023500406", "type": "string" }, "name": { "description": "Backup plan name", "example": "nightly", "type": "string" } }, "required": [ "id", "name" ], "type": "object" }, "DediboxVncView": { "description": "Dedibox VNC access", "properties": { "port": { "description": "VNC port", "format": "int32", "maximum": 64000, "minimum": 1000, "type": "integer" }, "proxied": { "description": "If raw VNC should be proxied", "type": "boolean" }, "token": { "description": "VNC token", "type": "string" } }, "required": [ "port", "proxied", "token" ], "type": "object" }, "EnrichedDediboxDetailViewDediboxLive": { "properties": { "id": { "description": "Dedibox ID", "example": "1326819038986244108", "type": "string" }, "iso": { "anyOf": [ { "$ref": "#/components/schemas/ImageSimple" }, { "type": "null" } ], "description": "Image attached to this dedibox" }, "name": { "description": "Name of this dedibox", "example": "dedi-fra-01", "type": "string" }, "online": { "description": "If this dedibox is powered on", "type": "boolean" }, "owner": { "anyOf": [ { "$ref": "#/components/schemas/WorkspaceSimple" }, { "type": "null" } ], "description": "Workspace that owns this dedibox" }, "region": { "$ref": "#/components/schemas/Region", "description": "Region where this dedibox is deployed" }, "sku": { "description": "Product this dedibox was sold as", "example": "ryzen-7950x", "type": [ "string", "null" ] }, "vnc": { "$ref": "#/components/schemas/DediboxVncView", "description": "VNC access details for this dedibox" } }, "required": [ "id", "iso", "name", "online", "owner", "region", "sku", "vnc" ], "type": "object" }, "EnrichedInstanceListViewInstanceLive": { "properties": { "firmware": { "$ref": "#/components/schemas/Firmware", "description": "Firmware the instance boots with" }, "flags": { "description": "Pending changes and integrations of the instance; ADDRESS_CHANGE_PENDING means one of its IP addresses changes when its pending upgrades apply", "items": { "$ref": "#/components/schemas/InstanceFlags" }, "type": "array", "uniqueItems": true }, "id": { "example": "1463106077196308568", "type": "string" }, "ips": { "items": { "$ref": "#/components/schemas/FloatingIPSimple" }, "type": "array" }, "name": { "example": "web-01", "type": "string" }, "node": { "$ref": "#/components/schemas/NodeSimple" }, "online": { "description": "Whether this instance is currently running", "type": "boolean" }, "os": { "$ref": "#/components/schemas/OsInfoView", "description": "Operating system information" }, "owner": { "$ref": "#/components/schemas/WorkspaceSimple" }, "sku": { "description": "Product this instance was sold as", "example": "lightning-1g", "type": [ "string", "null" ] }, "state": { "enum": [ "PENDING", "AVAILABLE", "FAILED", "SUSPENDED", "DELETING", "UNPLACED" ], "type": "string" }, "subject": { "description": "Billing subject this instance is billed under, or null when it is not billed", "example": "1456074443980800000", "type": [ "string", "null" ] }, "terminate_on": { "example": "2026-08-01T00:00:00Z", "format": "date-time", "type": [ "string", "null" ] }, "upgrade_pending": { "description": "Whether upgrades are staged; they apply on the next restart or when pending upgrades are applied", "type": "boolean" } }, "required": [ "firmware", "flags", "id", "ips", "name", "node", "online", "os", "owner", "sku", "state", "subject", "terminate_on", "upgrade_pending" ], "type": "object" }, "Firmware": { "description": "Firmware an instance boots with", "enum": [ "BIOS", "UEFI", "UEFI_SECURE" ], "type": "string" }, "FloatingIPSimple": { "properties": { "address": { "type": "string" }, "id": { "example": "1464201868476432440", "type": "string" } }, "required": [ "address", "id" ], "type": "object" }, "ImageSimple": { "description": "Image reference", "properties": { "id": { "description": "Image ID", "example": "1471181001588760790", "type": "string" }, "name": { "description": "Image name", "example": "ubuntu-24.04", "type": "string" } }, "required": [ "id", "name" ], "type": "object" }, "InstanceFlags": { "enum": [ "PASSWORD_RESET_PENDING", "SSH_KEYS_SYNC_PENDING", "SPARSIFY_PENDING", "APPS_INTEGRATED", "ADDRESS_CHANGE_PENDING" ], "type": "string" }, "IoLimitsView": { "description": "IO limits", "properties": { "read_bytes_sec": { "description": "IO limit on reads (bytes/sec)", "example": 209715200, "format": "int64", "maximum": 100000000000, "minimum": 1, "type": [ "integer", "null" ] }, "read_iops": { "description": "IO limit on read IOPs", "example": 5000, "format": "int64", "maximum": 10000000, "minimum": 1, "type": [ "integer", "null" ] }, "write_bytes_sec": { "description": "IO limit on writes (bytes/sec)", "example": 104857600, "format": "int64", "maximum": 100000000000, "minimum": 1, "type": [ "integer", "null" ] }, "write_iops": { "description": "IO limit on write IOPs", "example": 3000, "format": "int64", "maximum": 10000000, "minimum": 1, "type": [ "integer", "null" ] } }, "required": [ "read_bytes_sec", "read_iops", "write_bytes_sec", "write_iops" ], "type": "object" }, "IpFamily": { "enum": [ "IPv4", "IPv6" ], "type": "string" }, "KeysetResultEnrichedInstanceListViewInstanceLive": { "properties": { "after": { "type": [ "string", "null" ] }, "before": { "type": [ "string", "null" ] }, "has_next": { "type": "boolean" }, "has_previous": { "type": "boolean" }, "items": { "items": { "$ref": "#/components/schemas/EnrichedInstanceListViewInstanceLive" }, "type": "array" }, "limit": { "description": "Limit of items returned per page", "format": "int32", "maximum": 100, "minimum": 1, "type": "integer" }, "page": { "description": "Page number", "format": "int32", "maximum": 1000, "minimum": 1, "type": "integer" }, "total": { "description": "Total number of matching items", "format": "int64", "minimum": 0, "type": "integer" } }, "required": [ "after", "before", "has_next", "has_previous", "items", "limit", "page", "total" ], "type": "object" }, "KeysetResultVpcListView": { "properties": { "after": { "type": [ "string", "null" ] }, "before": { "type": [ "string", "null" ] }, "has_next": { "type": "boolean" }, "has_previous": { "type": "boolean" }, "items": { "items": { "$ref": "#/components/schemas/VpcListView" }, "type": "array" }, "limit": { "description": "Limit of items returned per page", "format": "int32", "maximum": 100, "minimum": 1, "type": "integer" }, "page": { "description": "Page number", "format": "int32", "maximum": 1000, "minimum": 1, "type": "integer" }, "total": { "description": "Total number of matching items", "format": "int64", "minimum": 0, "type": "integer" } }, "required": [ "after", "before", "has_next", "has_previous", "items", "limit", "page", "total" ], "type": "object" }, "NodeFlags": { "enum": [ "CEPH" ], "type": "string" }, "NodeSimple": { "properties": { "flags": { "description": "Capability flags for this node", "items": { "$ref": "#/components/schemas/NodeFlags" }, "type": "array", "uniqueItems": true }, "id": { "example": "1326819038986244108", "type": "string" }, "name": { "example": "hv-fra-01", "type": "string" }, "region": { "$ref": "#/components/schemas/Region" } }, "required": [ "flags", "id", "name", "region" ], "type": "object" }, "OsDistro": { "enum": [ "DEBIAN", "UBUNTU" ], "type": "string" }, "OsFamily": { "enum": [ "WINDOWS", "LINUX", "BSD", "OTHER" ], "type": "string" }, "OsInfoView": { "description": "Operating system information", "properties": { "distro": { "anyOf": [ { "$ref": "#/components/schemas/OsDistro" }, { "type": "null" } ], "description": "Distribution, for grouping images of the same OS" }, "family": { "$ref": "#/components/schemas/OsFamily", "description": "OS family" }, "name": { "description": "OS display name (e.g. 'Ubuntu 24.04')", "example": "Ubuntu 24.04", "type": [ "string", "null" ] }, "version": { "description": "Distribution release (e.g. '13', '26.04')", "example": "26.04", "type": [ "string", "null" ] } }, "required": [ "distro", "family", "name", "version" ], "type": "object" }, "Region": { "enum": [ "NA_01" ], "type": "string" }, "ServiceGroup": { "enum": [ "UNDEFINED", "LIGHTNING", "RYZEN", "DEDICATED" ], "type": "string" }, "VpcListView": { "description": "VPC list item", "properties": { "description": { "description": "Description of this VPC", "type": "string" }, "dns_server": { "description": "DNS server offered to peers while a router is set", "example": "192.168.0.2", "type": [ "string", "null" ] }, "id": { "description": "VPC ID", "example": "1463882832936980610", "type": "string" }, "name": { "description": "Name of this VPC", "example": "vpc-internal", "type": "string" }, "owner": { "$ref": "#/components/schemas/WorkspaceSimple", "description": "Workspace that owns this VPC" }, "range": { "description": "CIDR range for IP allocation within this VPC", "type": "string" }, "router": { "description": "Instance that peers use as their default route; null when the VPC has no router", "example": "1471181001588760790", "type": [ "string", "null" ] }, "vni": { "description": "VXLAN id (VNI) of the VPC overlay network", "example": 4444, "format": "int32", "minimum": 1, "type": [ "integer", "null" ] } }, "required": [ "description", "dns_server", "id", "name", "owner", "range", "router", "vni" ], "type": "object" }, "WorkflowActivity": { "properties": { "attempts": { "$ref": "#/components/schemas/WorkflowRetryState", "description": "Retry attempt information" }, "name": { "description": "Activity type name", "example": "provision-create-instance", "type": "string" }, "status": { "description": "Current activity status", "enum": [ "PENDING", "IN_PROGRESS", "COMPLETED", "FAILED", "TIMED_OUT", "CANCELED" ], "type": "string" } }, "required": [ "attempts", "name", "status" ], "type": "object" }, "WorkflowChildExecution": { "properties": { "name": { "description": "Child workflow type name", "example": "app-integrate", "type": "string" }, "status": { "description": "Child workflow status", "enum": [ "QUEUED", "RUNNING", "FAILED", "COMPLETED", "ABORTED", "TIMED_OUT" ], "type": "string" }, "workflow_id": { "description": "Child workflow execution ID", "example": "3d81b60c-2f4a-4e5b-8c19-7ab52e0d9f31", "type": "string" } }, "required": [ "name", "status", "workflow_id" ], "type": "object" }, "WorkflowData": { "properties": { "data": { "additionalProperties": true, "description": "Workflow data (if any)", "type": [ "object", "null" ] }, "duration": { "description": "Duration in seconds", "example": 45, "format": "int64", "minimum": 0, "type": "integer" }, "id": { "description": "Workflow ID", "example": "9f2c1d7a-4b83-4c1e-9a55-6d0f3b8e27c4", "type": "string" }, "name": { "description": "Workflow name (type)", "example": "instance.provision", "type": "string" }, "progress": { "$ref": "#/components/schemas/WorkflowProgress", "description": "Workflow progress (activities and child workflows)" }, "started": { "description": "When the workflow started", "example": "2026-04-27T07:26:11Z", "format": "date-time", "type": "string" }, "state": { "description": "Workflow state", "enum": [ "QUEUED", "RUNNING", "FAILED", "COMPLETED", "ABORTED", "TIMED_OUT" ], "type": "string" } }, "required": [ "data", "duration", "id", "name", "started", "state" ], "type": "object" }, "WorkflowProgress": { "properties": { "activities": { "description": "Activity steps in execution order", "items": { "$ref": "#/components/schemas/WorkflowActivity" }, "type": "array" }, "children": { "description": "Child workflow executions", "items": { "$ref": "#/components/schemas/WorkflowChildExecution" }, "type": "array" }, "completed": { "description": "Number of completed activities", "format": "int32", "minimum": 0, "type": "integer" }, "total": { "description": "Total number of activities seen", "format": "int32", "minimum": 0, "type": "integer" } }, "required": [ "activities", "children", "completed", "total" ], "type": "object" }, "WorkflowRetryState": { "properties": { "current": { "description": "Current attempt number (1-indexed, 0 if not yet started)", "format": "int32", "minimum": 0, "type": "integer" }, "limit": { "description": "Maximum attempts allowed (0 = unlimited)", "format": "int32", "minimum": 0, "type": "integer" } }, "required": [ "current", "limit" ], "type": "object" }, "AppDomainResponse": { "description": "Available app domain", "properties": { "name": { "description": "Domain name", "example": "galaxygate.app", "type": "string" }, "proxy_mode": { "description": "Proxy mode", "type": "string" } }, "required": [ "name", "proxy_mode" ], "type": "object" }, "AppMetrics": { "description": "Time-series metrics for a Docker app container. See each field for its unit.", "properties": { "cpu": { "$ref": "#/components/schemas/PromMatrix", "description": "Container CPU usage as a fraction of one core. 1.0 = 100% of a single core; a container using two\ncores fully reports 2.0. Divide by the allocated core count for a 0..1 utilization ratio.\n" }, "memory": { "$ref": "#/components/schemas/PromMatrix", "description": "Container memory usage in bytes. Compare against the container's memory limit (available on the app\nentity and in the `live` stats block of list responses) for a utilization ratio.\n" }, "network_rx": { "$ref": "#/components/schemas/PromMatrix", "description": "Inbound network traffic in bytes per second. Always non-negative. Returns 0 for the first ~60s after\na container starts (not enough samples for a rate) and across container restarts.\n" }, "network_tx": { "$ref": "#/components/schemas/PromMatrix", "description": "Outbound network traffic in bytes per second. Same semantics as `network_rx`.\n" } }, "required": [ "cpu", "memory", "network_rx", "network_tx" ], "type": "object" }, "AppTemplateDetailView": { "description": "Full app template configuration", "properties": { "category": { "anyOf": [ { "$ref": "#/components/schemas/ContentCategory" }, { "type": "null" } ], "description": "Category used to group templates in the UI" }, "description": { "description": "Short description", "type": "string" }, "environment": { "description": "Environment variable specs (key, default value, description)", "items": { "$ref": "#/components/schemas/TemplateEnv" }, "type": "array" }, "id": { "description": "Template ID", "example": "1471181001588760790", "type": "string" }, "image": { "description": "Docker image including tag", "type": "string" }, "mounts": { "description": "Default volume mounts", "items": { "$ref": "#/components/schemas/AppVolumeMount" }, "type": "array" }, "name": { "description": "Template name", "example": "grafana", "type": "string" }, "ports": { "description": "Container ports the app exposes", "items": { "$ref": "#/components/schemas/TemplatePort" }, "type": "array" } }, "required": [ "category", "description", "environment", "id", "image", "mounts", "name", "ports" ], "type": "object" }, "AppTemplateSimple": { "properties": { "category": { "anyOf": [ { "$ref": "#/components/schemas/ContentCategory" }, { "type": "null" } ] }, "id": { "example": "1471181001588760790", "type": "string" }, "name": { "example": "grafana", "type": "string" } }, "required": [ "category", "id", "name" ], "type": "object" }, "AppTemplateView": { "description": "App template summary", "properties": { "category": { "anyOf": [ { "$ref": "#/components/schemas/ContentCategory" }, { "type": "null" } ], "description": "Category used to group templates in the UI" }, "description": { "description": "Short description", "type": "string" }, "id": { "description": "Template ID", "example": "1471181001588760790", "type": "string" }, "image": { "description": "Docker image including tag", "type": "string" }, "name": { "description": "Template name", "example": "grafana", "type": "string" } }, "required": [ "category", "description", "id", "image", "name" ], "type": "object" }, "AppVolumeMount": { "description": "Volume mount for an app container", "properties": { "container_path": { "description": "Container mount path", "example": "/var/lib/data", "type": "string" }, "host_path": { "description": "Host path on the Instance, only for BIND mounts", "example": "/etc/myapp/secret", "type": [ "string", "null" ] }, "read_only": { "description": "Whether the mount is read-only", "example": false, "type": "boolean" }, "type": { "description": "VOLUME stores the data in a Docker volume owned by the app, BIND mounts host_path from the Instance", "enum": [ "VOLUME", "BIND" ], "example": "VOLUME", "type": "string" } }, "required": [ "container_path", "host_path", "read_only", "type" ], "type": "object" }, "AppVolumeMountRequest": { "description": "Volume mount for an app container", "properties": { "container_path": { "description": "Container mount path", "example": "/var/lib/data", "type": "string" }, "host_path": { "description": "Host path on the Instance, only for BIND mounts", "example": "/etc/myapp/secret", "type": [ "string", "null" ] }, "read_only": { "description": "Whether the mount is read-only", "example": false, "type": "boolean" }, "type": { "description": "VOLUME stores the data in a Docker volume owned by the app, BIND mounts host_path from the Instance. Defaults to VOLUME", "enum": [ "VOLUME", "BIND" ], "example": "VOLUME", "type": [ "string", "null" ] } }, "required": [ "container_path", "read_only" ], "type": "object" }, "ContentCategory": { "enum": [ "DEFAULT", "GAMES", "SOFTWARE", "INFRASTRUCTURE", "AI", "MEDIA", "TOOLS", "DATABASES", "MONITORING", "PRODUCTIVITY", "DEVOPS", "AUTOMATION", "NETWORK" ], "type": "string" }, "CreateAppRequest": { "description": "Request to create an app", "properties": { "domain": { "description": "Custom domain name for the app (e.g. grafana.galaxygate.app); requires at least one port marked as http", "type": [ "string", "null" ] }, "environment": { "additionalProperties": { "type": "string" }, "description": "Environment variables", "type": [ "object", "null" ] }, "image": { "description": "Docker image including tag", "example": "nginx:latest", "type": "string" }, "mounts": { "description": "Volume mounts", "items": { "$ref": "#/components/schemas/AppVolumeMountRequest" }, "type": [ "array", "null" ] }, "name": { "description": "App name (unique within workspace)", "example": "grafana", "type": "string" }, "ports": { "description": "Port mappings", "items": { "$ref": "#/components/schemas/PortMappingRequest" }, "type": [ "array", "null" ] } }, "required": [ "image", "name" ], "type": "object" }, "CreateAppTemplateRequest": { "description": "Request to create an app template", "properties": { "category": { "anyOf": [ { "$ref": "#/components/schemas/ContentCategory" }, { "type": "null" } ], "description": "Category used to group templates in the UI" }, "description": { "description": "Short description of what this template deploys", "type": "string" }, "environment": { "description": "Environment variable specs (key, default value, description); values may contain placeholders resolved at deploy time", "items": { "$ref": "#/components/schemas/TemplateEnvRequest" }, "type": [ "array", "null" ] }, "image": { "description": "Docker image including tag", "example": "plexinc/pms-docker:latest", "type": "string" }, "mounts": { "description": "Default volume mounts", "items": { "$ref": "#/components/schemas/AppVolumeMountRequest" }, "type": [ "array", "null" ] }, "name": { "description": "Template name (globally unique)", "example": "grafana", "type": "string" }, "ports": { "description": "Container ports the app exposes", "items": { "$ref": "#/components/schemas/TemplatePortRequest" }, "type": [ "array", "null" ] } }, "required": [ "description", "image", "name" ], "type": "object" }, "CreateRegistryRequest": { "description": "Add or replace a private registry credential for the workspace", "properties": { "password": { "description": "Password, personal access token, or deploy token", "type": "string" }, "registry": { "description": "Registry host (e.g. ghcr.io). Accepts URLs and aliases \u2014 they are canonicalized server-side.", "example": "ghcr.io", "type": "string" }, "username": { "description": "Username for the registry", "type": "string" } }, "required": [ "password", "registry", "username" ], "type": "object" }, "DeployFromTemplateRequest": { "description": "Request to deploy an app from a template", "properties": { "domain": { "description": "Custom domain name for the app (e.g. grafana.galaxygate.app); only valid when the template has a port marked as http", "type": [ "string", "null" ] }, "environment": { "additionalProperties": { "type": [ "string", "null" ] }, "description": "Environment variables; merged over the template defaults (override per-key, null values delete the template's default for that key)", "type": [ "object", "null" ] }, "mounts": { "description": "Volume mounts; when supplied, fully replaces the template's default mounts", "items": { "$ref": "#/components/schemas/AppVolumeMountRequest" }, "type": [ "array", "null" ] }, "name": { "description": "App name (unique within workspace)", "example": "grafana", "type": "string" }, "template_id": { "description": "App template ID", "example": "1471181001588760790", "type": "string" } }, "required": [ "name", "template_id" ], "type": "object" }, "DomainCheckRequest": { "description": "Request to check if a domain name is available for use as an app subdomain", "properties": { "domain": { "description": "Full domain name to check (e.g. grafana.galaxygate.app)", "example": "grafana.galaxygate.app", "type": "string" } }, "required": [ "domain" ], "type": "object" }, "EnrichedAppDetailViewAppDetailLive": { "properties": { "app_id": { "description": "App entity ID", "example": "1483754921000984881", "type": "string" }, "container_id": { "description": "Docker container ID", "example": "9f2b6c1d4a83e57b0c9d1e2f3a4b5c6d7e8f9a0b1c2d3e4f5a6b7c8d9e0f1a2b", "type": [ "string", "null" ] }, "cpu": { "description": "CPU usage ratio (0.0 to N, where N = number of cores)", "example": 0.35, "format": "double", "minimum": 0, "type": "number" }, "domain": { "description": "Custom domain assigned to this app", "type": [ "string", "null" ] }, "environment": { "additionalProperties": { "type": "string" }, "description": "Environment variables", "type": "object" }, "id": { "description": "App ID", "example": "1483754921000984881", "type": "string" }, "image": { "description": "Docker image including tag", "type": "string" }, "instance": { "$ref": "#/components/schemas/InstanceSimple", "description": "Instance this app runs on" }, "instance_id": { "description": "Instance ID", "example": "1463106077196308568", "type": "string" }, "locked": { "description": "Lock reason during operations", "type": [ "string", "null" ] }, "memory_limit": { "description": "Memory limit (in bytes)", "example": 536870912, "format": "int64", "minimum": 0, "type": "integer" }, "memory_usage": { "description": "Memory usage (in bytes)", "example": 268435456, "format": "int64", "minimum": 0, "type": "integer" }, "mounts": { "description": "Volume mounts", "items": { "$ref": "#/components/schemas/AppVolumeMount" }, "type": "array" }, "name": { "description": "App name", "example": "grafana", "type": "string" }, "network_rx": { "description": "Network received (in bytes)", "example": 1073741824, "format": "int64", "minimum": 0, "type": "integer" }, "network_tx": { "description": "Network transmitted (in bytes)", "example": 524288000, "format": "int64", "minimum": 0, "type": "integer" }, "owner": { "$ref": "#/components/schemas/WorkspaceSimple", "description": "Workspace that owns this app" }, "ports": { "description": "Port mappings", "items": { "$ref": "#/components/schemas/PortMapping" }, "type": "array" }, "running": { "description": "Whether the container is currently running", "type": "boolean" }, "state": { "description": "App lifecycle state", "enum": [ "PENDING", "AVAILABLE", "FAILED", "SUSPENDED", "DELETING", "UNPLACED" ], "type": "string" }, "template": { "anyOf": [ { "$ref": "#/components/schemas/AppTemplateSimple" }, { "type": "null" } ], "description": "App template this app was deployed from, if any" }, "updated_at": { "description": "When stats were last collected (epoch milliseconds)", "example": 1784557800000, "format": "int64", "minimum": 0, "type": "integer" } }, "required": [ "container_id", "domain", "environment", "id", "image", "instance", "locked", "mounts", "name", "owner", "ports", "state", "template" ], "type": "object" }, "InstanceSimple": { "description": "Instance reference", "properties": { "id": { "description": "Instance ID", "example": "1463106077196308568", "type": "string" }, "name": { "description": "Instance name", "example": "web-01", "type": "string" } }, "required": [ "id", "name" ], "type": "object" }, "KeysetResultAppTemplateView": { "properties": { "after": { "type": [ "string", "null" ] }, "before": { "type": [ "string", "null" ] }, "has_next": { "type": "boolean" }, "has_previous": { "type": "boolean" }, "items": { "items": { "$ref": "#/components/schemas/AppTemplateView" }, "type": "array" }, "limit": { "description": "Limit of items returned per page", "format": "int32", "maximum": 100, "minimum": 1, "type": "integer" }, "page": { "description": "Page number", "format": "int32", "maximum": 1000, "minimum": 1, "type": "integer" }, "total": { "description": "Total number of matching items", "format": "int64", "minimum": 0, "type": "integer" } }, "required": [ "after", "before", "has_next", "has_previous", "items", "limit", "page", "total" ], "type": "object" }, "KeysetResultOptionallyEnrichedAppViewContainerLiveStats": { "properties": { "after": { "type": [ "string", "null" ] }, "before": { "type": [ "string", "null" ] }, "has_next": { "type": "boolean" }, "has_previous": { "type": "boolean" }, "items": { "items": { "$ref": "#/components/schemas/OptionallyEnrichedAppViewContainerLiveStats" }, "type": "array" }, "limit": { "description": "Limit of items returned per page", "format": "int32", "maximum": 100, "minimum": 1, "type": "integer" }, "page": { "description": "Page number", "format": "int32", "maximum": 1000, "minimum": 1, "type": "integer" }, "total": { "description": "Total number of matching items", "format": "int64", "minimum": 0, "type": "integer" } }, "required": [ "after", "before", "has_next", "has_previous", "items", "limit", "page", "total" ], "type": "object" }, "KeysetResultRegistryCredentialView": { "properties": { "after": { "type": [ "string", "null" ] }, "before": { "type": [ "string", "null" ] }, "has_next": { "type": "boolean" }, "has_previous": { "type": "boolean" }, "items": { "items": { "$ref": "#/components/schemas/RegistryCredentialView" }, "type": "array" }, "limit": { "description": "Limit of items returned per page", "format": "int32", "maximum": 100, "minimum": 1, "type": "integer" }, "page": { "description": "Page number", "format": "int32", "maximum": 1000, "minimum": 1, "type": "integer" }, "total": { "description": "Total number of matching items", "format": "int64", "minimum": 0, "type": "integer" } }, "required": [ "after", "before", "has_next", "has_previous", "items", "limit", "page", "total" ], "type": "object" }, "MatrixPoint": { "properties": { "time": { "format": "int64", "type": "integer" }, "value": { "type": "string" } }, "required": [ "time", "value" ], "type": "object" }, "OptionallyEnrichedAppViewContainerLiveStats": { "properties": { "app_id": { "description": "App entity ID. Absent when live data is unavailable.", "example": "1483754921000984881", "type": "string" }, "container_id": { "description": "Docker container ID", "example": "9f2b6c1d4a83e57b0c9d1e2f3a4b5c6d7e8f9a0b1c2d3e4f5a6b7c8d9e0f1a2b", "type": [ "string", "null" ] }, "cpu": { "description": "CPU usage ratio (0.0 to N, where N = number of cores). Absent when live data is unavailable.", "example": 0.35, "format": "double", "minimum": 0, "type": "number" }, "domain": { "description": "Custom domain assigned to this app", "type": [ "string", "null" ] }, "id": { "description": "App ID", "example": "1483754921000984881", "type": "string" }, "image": { "description": "Docker image including tag", "type": "string" }, "instance": { "$ref": "#/components/schemas/InstanceSimple", "description": "Instance this app runs on" }, "instance_id": { "description": "Instance ID. Absent when live data is unavailable.", "example": "1463106077196308568", "type": "string" }, "locked": { "description": "Lock reason during operations", "type": [ "string", "null" ] }, "memory_limit": { "description": "Memory limit (in bytes). Absent when live data is unavailable.", "example": 536870912, "format": "int64", "minimum": 0, "type": "integer" }, "memory_usage": { "description": "Memory usage (in bytes). Absent when live data is unavailable.", "example": 268435456, "format": "int64", "minimum": 0, "type": "integer" }, "name": { "description": "App name", "example": "grafana", "type": "string" }, "network_rx": { "description": "Network received (in bytes). Absent when live data is unavailable.", "example": 1073741824, "format": "int64", "minimum": 0, "type": "integer" }, "network_tx": { "description": "Network transmitted (in bytes). Absent when live data is unavailable.", "example": 524288000, "format": "int64", "minimum": 0, "type": "integer" }, "owner": { "$ref": "#/components/schemas/WorkspaceSimple", "description": "Workspace that owns this app" }, "running": { "description": "Whether the container is currently running. Absent when live data is unavailable.", "type": "boolean" }, "state": { "description": "App lifecycle state", "enum": [ "PENDING", "AVAILABLE", "FAILED", "SUSPENDED", "DELETING", "UNPLACED" ], "type": "string" }, "template": { "anyOf": [ { "$ref": "#/components/schemas/AppTemplateSimple" }, { "type": "null" } ], "description": "App template this app was deployed from, if any" }, "updated_at": { "description": "When stats were last collected (epoch milliseconds). Absent when live data is unavailable.", "example": 1784557800000, "format": "int64", "minimum": 0, "type": "integer" } }, "required": [ "container_id", "domain", "id", "image", "instance", "locked", "name", "owner", "state", "template" ], "type": "object" }, "PortMapping": { "description": "Port mapping for a service", "properties": { "container_port": { "description": "Container port number", "example": 80, "format": "int32", "maximum": 65535, "minimum": 1, "type": "integer" }, "host_port": { "description": "Host port number", "example": 8080, "format": "int32", "maximum": 65535, "minimum": 1, "type": "integer" }, "http": { "description": "Whether this port serves HTTP traffic eligible for a custom subdomain", "type": "boolean" }, "protocol": { "$ref": "#/components/schemas/PortProtocol", "description": "Transport protocol", "example": "TCP" } }, "required": [ "container_port", "host_port", "http", "protocol" ], "type": "object" }, "PortMappingRequest": { "description": "Port mapping for an app", "properties": { "container_port": { "description": "Container port number", "example": 80, "format": "int32", "maximum": 65535, "minimum": 1, "type": "integer" }, "host_port": { "description": "Host port number", "example": 8080, "format": "int32", "maximum": 65535, "minimum": 1, "type": "integer" }, "http": { "description": "Whether this port serves HTTP traffic eligible for a custom subdomain", "type": "boolean" }, "protocol": { "$ref": "#/components/schemas/PortProtocol", "description": "Transport protocol", "example": "TCP" } }, "required": [ "container_port", "host_port", "http", "protocol" ], "type": "object" }, "PortProtocol": { "enum": [ "TCP", "UDP" ], "type": "string" }, "PromMatrix": { "properties": { "metric": { "type": "string" }, "points": { "items": { "$ref": "#/components/schemas/MatrixPoint" }, "type": "array" } }, "required": [ "metric", "points" ], "type": "object" }, "RegistryCredentialView": { "description": "Stored credentials for a private container registry", "properties": { "created_at": { "description": "When this credential was added", "example": "2026-03-18T09:12:20Z", "format": "date-time", "type": "string" }, "id": { "description": "Credential ID", "example": "1483754921000984881", "type": "string" }, "owner": { "$ref": "#/components/schemas/WorkspaceSimple", "description": "Workspace that owns this credential" }, "registry": { "description": "Canonical registry host (e.g. ghcr.io, docker.io)", "type": "string" }, "username": { "description": "Username for the registry", "type": "string" } }, "required": [ "created_at", "id", "owner", "registry", "username" ], "type": "object" }, "Resource": { "properties": { "id": { "description": "Resource ID", "example": "1506320201023500406", "type": "string" }, "name": { "description": "User-friendly resource name", "example": "web-01", "type": "string" }, "parent": { "anyOf": [ { "$ref": "#/components/schemas/Resource" }, { "type": "null" } ], "description": "Resource parent/owner" }, "type": { "$ref": "#/components/schemas/ResourceType", "description": "Resource type" } }, "required": [ "id", "name", "parent", "type" ], "type": "object" }, "ResourceType": { "enum": [ "DEDIBOX", "DISK", "FIREWALL_RULE", "FLOATING_IP", "IMAGE", "INSTANCE", "NET_BALANCER", "NODE", "INSTANCE_PRESET", "SNAPSHOT", "TOKEN", "USER", "VPC", "WORKSPACE", "STORAGE_SERVER", "APP" ], "type": "string" }, "TemplateEnv": { "description": "An environment variable exposed by an app template. Values may contain placeholders (see the deploy-from-template endpoint for the supported set) that are resolved at deploy time.", "properties": { "description": { "description": "Short hint describing what the variable is for, shown in the deploy UI", "example": "Claim token used by Plex to associate the server with your account", "type": [ "string", "null" ] }, "key": { "description": "Environment variable name passed to the container", "example": "PLEX_CLAIM", "type": "string" }, "value": { "description": "Default value; null means the user must supply it at deploy time", "example": "{{random:32}}", "type": [ "string", "null" ] } }, "required": [ "description", "key", "value" ], "type": "object" }, "TemplateEnvRequest": { "description": "An environment variable exposed by an app template. Values may contain placeholders (see the deploy-from-template endpoint for the supported set) that are resolved at deploy time.", "properties": { "description": { "description": "Short hint describing what the variable is for, shown in the deploy UI", "example": "Claim token used by Plex to associate the server with your account", "maxLength": 500, "type": [ "string", "null" ] }, "key": { "description": "Environment variable name passed to the container", "example": "PLEX_CLAIM", "type": "string" }, "value": { "description": "Default value; null means the user must supply it at deploy time", "example": "{{random:32}}", "maxLength": 4096, "type": [ "string", "null" ] } }, "required": [ "key" ], "type": "object" }, "TemplatePort": { "description": "Port an app template exposes; at deploy time the host port defaults to the container port if free on the target Instance, otherwise a random free port is allocated", "properties": { "container_port": { "description": "Container port the app listens on", "example": 32400, "format": "int32", "maximum": 65535, "minimum": 1, "type": "integer" }, "description": { "description": "Short hint describing what the port is for, shown in the deploy UI", "example": "Plex web interface and DLNA", "type": "string" }, "http": { "description": "Whether this port serves HTTP traffic eligible for a custom subdomain; at most one port per template may be marked as http", "type": "boolean" }, "name": { "description": "Slug identifier for this port, unique within the template; referenced by placeholders like {{host_port.}}", "example": "web", "type": "string" }, "protocol": { "$ref": "#/components/schemas/PortProtocol", "description": "Transport protocol", "example": "TCP" } }, "required": [ "container_port", "description", "http", "name", "protocol" ], "type": "object" }, "TemplatePortRequest": { "description": "Port an app template exposes; at deploy time the host port defaults to the container port if free on the target Instance, otherwise a random free port is allocated", "properties": { "container_port": { "description": "Container port the app listens on", "example": 32400, "format": "int32", "maximum": 65535, "minimum": 1, "type": "integer" }, "description": { "description": "Short hint describing what the port is for, shown in the deploy UI", "example": "Plex web interface and DLNA", "maxLength": 500, "type": "string" }, "http": { "description": "Whether this port serves HTTP traffic eligible for a custom subdomain; at most one port per template may be marked as http", "type": "boolean" }, "name": { "description": "Slug identifier for this port, unique within the template; referenced by placeholders like {{host_port.}}", "example": "web", "type": "string" }, "protocol": { "$ref": "#/components/schemas/PortProtocol", "description": "Transport protocol", "example": "TCP" } }, "required": [ "container_port", "description", "http", "name", "protocol" ], "type": "object" }, "UpdateAppRequest": { "description": "Request to update an app", "properties": { "environment": { "additionalProperties": { "type": "string" }, "description": "Environment variables", "type": [ "object", "null" ] }, "image": { "description": "Docker image including tag", "example": "nginx:latest", "type": [ "string", "null" ] }, "mounts": { "description": "Volume mounts", "items": { "$ref": "#/components/schemas/AppVolumeMountRequest" }, "type": [ "array", "null" ] }, "ports": { "description": "Port mappings", "items": { "$ref": "#/components/schemas/PortMappingRequest" }, "type": [ "array", "null" ] } }, "type": "object" }, "UpdateAppTemplateRequest": { "description": "Request to update an app template; omitted fields are left unchanged. Setting a non-nullable field to null is rejected; setting category to null clears it.", "properties": { "category": { "description": "Category used to group templates in the UI, or null to clear it", "enum": [ "DEFAULT", "GAMES", "SOFTWARE", "INFRASTRUCTURE", "AI", "MEDIA", "TOOLS", "DATABASES", "MONITORING", "PRODUCTIVITY", "DEVOPS", "AUTOMATION", "NETWORK" ], "type": [ "string", "null" ] }, "description": { "description": "Short description of what this template deploys", "type": "string" }, "environment": { "description": "Environment variable specs (key, default value, description); values may contain placeholders resolved at deploy time", "items": { "$ref": "#/components/schemas/TemplateEnvRequest" }, "type": "array" }, "image": { "description": "Docker image including tag", "type": "string" }, "mounts": { "description": "Default volume mounts", "items": { "$ref": "#/components/schemas/AppVolumeMountRequest" }, "type": "array" }, "name": { "description": "Template name (globally unique)", "example": "grafana", "type": "string" }, "ports": { "description": "Container ports the app exposes", "items": { "$ref": "#/components/schemas/TemplatePortRequest" }, "type": "array" } }, "type": "object" }, "UpdateRegistryRequest": { "description": "Request to update an existing registry credential. Omitted fields are left unchanged. Neither field may be set to null; the registry host is immutable.", "properties": { "password": { "description": "New password, personal access token, or deploy token", "type": "string" }, "username": { "description": "New username for the registry", "type": "string" } }, "type": "object" }, "WorkflowWithResource": { "properties": { "resource": { "$ref": "#/components/schemas/Resource", "description": "Resource information" }, "workflow": { "$ref": "#/components/schemas/WorkflowData", "description": "Workflow information" } }, "required": [ "resource", "workflow" ], "type": "object" }, "EnrichedTopologyInstanceViewInstanceLive": { "properties": { "id": { "example": "1463106077196308568", "type": "string" }, "name": { "example": "web-01", "type": "string" }, "online": { "description": "Whether this instance is currently running", "type": "boolean" }, "sku": { "description": "Product this instance was sold as", "example": "lightning-1g", "type": [ "string", "null" ] }, "state": { "enum": [ "PENDING", "AVAILABLE", "FAILED", "SUSPENDED", "DELETING", "UNPLACED" ], "type": "string" } }, "required": [ "id", "name", "online", "sku", "state" ], "type": "object" }, "TopologyDediboxView": { "properties": { "id": { "example": "1326819038986244108", "type": "string" }, "name": { "example": "dedi-fra-01", "type": "string" }, "sku": { "description": "Product this dedibox was sold as", "example": "ryzen-7950x", "type": [ "string", "null" ] } }, "required": [ "id", "name", "sku" ], "type": "object" }, "TopologyFloatingIPView": { "properties": { "address": { "type": "string" }, "id": { "example": "1464201868476432440", "type": "string" }, "instance_id": { "example": "1463106077196308568", "type": [ "string", "null" ] }, "protected": { "type": "boolean" } }, "required": [ "address", "id", "instance_id", "protected" ], "type": "object" }, "TopologyNetBalancerView": { "properties": { "address": { "type": "string" }, "id": { "example": "1467950980661264556", "type": "string" }, "instance_ids": { "items": { "example": "1467950980661264556", "type": "string" }, "type": "array" } }, "required": [ "address", "id", "instance_ids" ], "type": "object" }, "TopologyResponse": { "properties": { "dediboxes": { "items": { "$ref": "#/components/schemas/TopologyDediboxView" }, "type": "array" }, "instances": { "items": { "$ref": "#/components/schemas/EnrichedTopologyInstanceViewInstanceLive" }, "type": "array" }, "ips": { "items": { "$ref": "#/components/schemas/TopologyFloatingIPView" }, "type": "array" }, "net_balancers": { "items": { "$ref": "#/components/schemas/TopologyNetBalancerView" }, "type": "array" }, "vpcs": { "items": { "$ref": "#/components/schemas/VpcSimple" }, "type": "array" } }, "required": [ "dediboxes", "instances", "ips", "net_balancers", "vpcs" ], "type": "object" }, "VpcSimple": { "description": "VPC reference", "properties": { "id": { "description": "VPC ID", "example": "1463882832936980610", "type": "string" }, "name": { "description": "Name of this VPC", "example": "vpc-internal", "type": "string" }, "range": { "description": "CIDR range for IP allocation", "type": "string" }, "vni": { "description": "VXLAN id (VNI) of the VPC overlay network", "example": 4444, "format": "int32", "minimum": 1, "type": [ "integer", "null" ] } }, "required": [ "id", "name", "range", "vni" ], "type": "object" }, "AccountView": { "description": "A billing account, one per user, owning the wallet its subjects bill against.", "properties": { "consolidated_billing": { "description": "Whether the account may buy fixed packages as POSTPAID, billed on the monthly invoice", "type": "boolean" }, "created_at": { "description": "Creation timestamp of the account", "format": "date-time", "type": "string" }, "credit_limit": { "description": "How far the wallet may go negative before new authorizations stop, in micro-USD (1 USD = 1,000,000); defaults to 0", "example": 50000000, "format": "int64", "type": "integer" }, "grace_period_seconds": { "description": "How long past an invoice due date the subjects stay up before suspension, in seconds; defaults to 0", "example": 86400, "format": "int64", "type": "integer" }, "id": { "description": "Account id", "example": "1456074443980800000", "type": "string" }, "name": { "description": "Account display name", "example": "acme-corp", "type": "string" }, "next_payment_at": { "description": "When the payment run next falls due; null while none is scheduled", "format": "date-time", "type": [ "string", "null" ] }, "payment_day": { "description": "The account's monthly date: the day of the monthly invoice and of MONTHLY_DATE renewals. In shorter months, the last day of the month applies. Null until the first purchase", "example": 1, "format": "int32", "type": [ "integer", "null" ] }, "postpaid_partial": { "description": "Whether a postpaid subject bills only the consumed part of its final cycle", "type": "boolean" }, "prepaid_credit": { "description": "Whether cancelling a prepaid subject early refunds its unused portion as wallet credit", "type": "boolean" }, "state": { "description": "Lifecycle state of the account", "enum": [ "ACTIVE", "CLOSED" ], "type": "string" }, "user": { "$ref": "#/components/schemas/UserSimple", "description": "User the account bills for" } }, "required": [ "consolidated_billing", "created_at", "credit_limit", "grace_period_seconds", "id", "name", "next_payment_at", "payment_day", "postpaid_partial", "prepaid_credit", "state", "user" ], "type": "object" }, "CancelQuoteResponse": { "description": "The refund that a cancel of the subject gives at this time.", "properties": { "period_end": { "description": "End of the subject's current cycle; null for a subject billed without cycles", "format": "date-time", "type": [ "string", "null" ] }, "reason": { "description": "The reason for the refund amount", "enum": [ "REFUNDED", "FORFEIT", "NOTHING_UNUSED", "UNPAID", "METERED", "POSTPAID" ], "type": "string" }, "refund": { "description": "Wallet credit the cancel refunds, micro-USD; 0 unless reason is REFUNDED", "example": 2999700, "format": "int64", "type": "integer" } }, "required": [ "period_end", "reason", "refund" ], "type": "object" }, "CheckoutCommand": { "description": "Opens a customer-present checkout for the user: supply an invoice to collect it, or an amount to fund the wallet. The gateway hosts the payment form.", "properties": { "amount": { "description": "Amount to fund the wallet by, micro-USD, between $20 and $500. Required when no invoice is supplied, and ignored when one is, since the invoice sets the amount", "example": 25000000, "format": "int64", "maximum": 500000000, "minimum": 20000000, "type": [ "integer", "null" ] }, "gateway": { "description": "Gateway hosting the checkout", "enum": [ "STRIPE", "PAYPAL", "MANUAL" ], "example": "STRIPE", "type": "string" }, "invoice_id": { "description": "Invoice to collect; null funds the wallet by the amount below", "example": "1456074443980800000", "type": [ "string", "null" ] } }, "required": [ "gateway" ], "type": "object" }, "CheckoutResponse": { "description": "A checkout session to mount in the browser. The payment is pending until the customer completes it and the gateway confirms settlement, which for a bank transfer or direct debit can take days.", "properties": { "client_secret": { "description": "Client secret Stripe.js initializes the checkout with", "example": "cs_test_a1B2c3D4e5_secret_x9Y8z7", "type": "string" }, "payment_id": { "description": "Pending payment this checkout collects; null when the checkout only stores a method", "example": "1456074443980800000", "type": [ "string", "null" ] }, "session_ref": { "description": "Gateway session reference", "example": "cs_test_a1B2c3D4e5", "type": "string" } }, "required": [ "client_secret", "payment_id", "session_ref" ], "type": "object" }, "ConfirmSetupRequest": { "description": "Hands back a completed checkout session so the method it stored is available immediately. Safe to repeat, and safe to skip: the method is stored either way.", "properties": { "gateway": { "description": "Gateway that hosted the checkout", "enum": [ "STRIPE", "PAYPAL", "MANUAL" ], "example": "STRIPE", "type": "string" }, "session_ref": { "description": "Session reference returned when the checkout was opened", "example": "cs_test_a1B2c3D4e5", "minLength": 1, "type": "string" } }, "required": [ "gateway", "session_ref" ], "type": "object" }, "CouponRedemptionView": { "description": "One coupon a user redeemed and the credit it granted.", "properties": { "amount": { "description": "Credit the coupon grants, micro-USD", "example": 10000000, "format": "int64", "type": "integer" }, "code": { "description": "Code of the coupon redeemed", "example": "WELCOME10", "type": "string" }, "coupon_id": { "description": "Coupon redeemed", "example": "1456074443980800000", "type": "string" }, "credit_lot_id": { "description": "Credit lot the redemption minted in the wallet", "example": "1456074443980800000", "type": "string" }, "id": { "description": "Redemption id", "example": "1456074443980800000", "type": "string" }, "redeemed_at": { "description": "When the coupon was redeemed", "format": "date-time", "type": "string" } }, "required": [ "amount", "code", "coupon_id", "credit_lot_id", "id", "redeemed_at" ], "type": "object" }, "CouponValidity": { "description": "Whether a coupon code can be redeemed, and what redeeming it would grant.", "properties": { "amount": { "description": "Credit redeeming it grants, micro-USD; null when no coupon carries that code", "example": 10000000, "format": "int64", "type": [ "integer", "null" ] }, "expiry_days": { "description": "Days after redemption the granted credit expires; null when the credit never expires or when no coupon carries that code", "example": 90, "format": "int32", "type": [ "integer", "null" ] }, "reason": { "description": "Why it cannot be redeemed; null when it can", "enum": [ "NOT_FOUND", "EXHAUSTED", "ALREADY_REDEEMED" ], "type": [ "string", "null" ] }, "valid": { "description": "Whether the coupon can be redeemed", "type": "boolean" } }, "required": [ "amount", "expiry_days", "reason", "valid" ], "type": "object" }, "CreateOrderItemRequest": { "description": "One line on an order: a package to purchase, or a change to an existing subject on an upgrade.", "properties": { "package_code": { "description": "Package SKU code: the package to buy, or on an upgrade the package the subject moves to, which may be its current one to choose new values for its open fields.", "example": "vps-small", "type": "string" }, "properties": { "anyOf": [ { "$ref": "#/components/schemas/KindProperties" }, { "type": "null" } ], "description": "Purchase only: provisioning inputs for the new resource. A SERVER purchase must name the template or backup to install. The kind must match the package's kind. These values do not change the price and are never returned. An upgrade rejects this field." }, "prorate": { "description": "Upgrade only: split the in-progress cycle at now and prorate the change. Defaults to true; ignored on a purchase.", "example": true, "type": [ "boolean", "null" ] }, "resource_name": { "description": "Display name for the resource; defaults to the package name. A server's name is also its hostname: letters, digits and hyphens in dot-separated labels, at most 63 characters.", "example": "web-01", "type": [ "string", "null" ] }, "spec": { "anyOf": [ { "$ref": "#/components/schemas/KindSpec" }, { "type": "null" } ], "description": "Values for the fields the package leaves open, typed by the package's kind. On an upgrade, an open field left out keeps the subject's current value." }, "target_subject_id": { "description": "On an upgrade, the id of the subject to change. Required for an upgrade item, and the subject must belong to the order's workspace.", "example": "1456074443980800000", "type": [ "string", "null" ] } }, "required": [ "package_code" ], "type": "object" }, "CreateOrderRequest": { "description": "Places an order of one or more packages into a workspace. The workspace is named in the path.", "properties": { "idempotency_key": { "description": "Optional idempotency key; a replay returns the original order", "example": "order-1042-a1", "type": [ "string", "null" ] }, "items": { "description": "The packages being ordered, one subject each", "items": { "$ref": "#/components/schemas/CreateOrderItemRequest" }, "type": "array" }, "kind": { "description": "PURCHASE provisions new subjects; UPGRADE changes an existing one", "enum": [ "PURCHASE", "UPGRADE", "ADJUST" ], "example": "PURCHASE", "type": "string" }, "payment_mode": { "description": "Payment mode for fixed packages in a purchase. PREPAID pays the first cycle now. POSTPAID bills each cycle on the monthly invoice and requires consolidated billing on the workspace. Default is PREPAID. Metered packages always bill for usage.", "enum": [ "PREPAID", "POSTPAID" ], "example": "PREPAID", "type": [ "string", "null" ] }, "renewal": { "description": "When prepaid fixed packages renew. TODAY: the first cycle starts now. MONTHLY_DATE: the first period is one full cycle plus the days until the account's monthly date, and the order charges for the extra days. If the account has no monthly date, MONTHLY_DATE is the same as TODAY. Default is TODAY.", "enum": [ "TODAY", "MONTHLY_DATE" ], "example": "MONTHLY_DATE", "type": [ "string", "null" ] } }, "required": [ "items", "kind" ], "type": "object" }, "CreateOrderResponse": { "description": "The result of placing an order.", "properties": { "authorized": { "description": "Whether the order greened (paid in full and its subjects provisioned)", "type": "boolean" }, "collection": { "description": "What to do about the invoice: NONE if nothing is owed, IN_FLIGHT while a stored method is being charged, REQUIRED to open a checkout against it", "enum": [ "NONE", "IN_FLIGHT", "REQUIRED", "APPROVAL_REQUIRED", "OWNER_REQUIRED" ], "type": "string" }, "invoice_id": { "description": "Invoice raised to collect the order, if any", "example": "1456074443980800000", "type": [ "string", "null" ] }, "order": { "$ref": "#/components/schemas/OrderView", "description": "The order as it stands after placement" } }, "required": [ "authorized", "collection", "invoice_id", "order" ], "type": "object" }, "GatewayClientConfig": { "description": "Configuration to initialise the client library of one gateway", "oneOf": [ { "$ref": "#/components/schemas/StripeClientConfig" } ] }, "InvoiceLineItemView": { "description": "One priced line composing an invoice's subtotal.", "properties": { "amount": { "description": "Total charged on this line, micro-USD", "example": 1080000, "format": "int64", "type": "integer" }, "created_at": { "description": "Creation time of the line item", "format": "date-time", "type": "string" }, "description": { "description": "Human-readable description of the charge", "example": "web-01 usage", "type": "string" }, "id": { "description": "Line item id", "example": "1456074443980800000", "type": "string" }, "invoice_id": { "description": "Invoice this line belongs to", "example": "1456074443980800000", "type": "string" }, "kind": { "description": "FIXED_CYCLE, RENEWAL, METERED_USAGE, TOPUP, PRORATION_REFUND, CREDIT, ADJUSTMENT or TAX", "enum": [ "FIXED_CYCLE", "RENEWAL", "METERED_USAGE", "TOPUP", "PRORATION_REFUND", "CREDIT", "ADJUSTMENT", "TAX" ], "type": "string" }, "metadata": { "additionalProperties": {}, "description": "Free-form details attached to the line", "type": [ "object", "null" ] }, "period_end": { "description": "End of the period this line covers, if any", "format": "date-time", "type": [ "string", "null" ] }, "period_start": { "description": "Start of the period this line covers, if any", "format": "date-time", "type": [ "string", "null" ] }, "quantity": { "description": "Number of units billed on this line", "example": 720, "format": "int64", "type": "integer" }, "subject_id": { "description": "Billing subject this line is charged for, if any", "example": "1456074443980800000", "type": [ "string", "null" ] }, "unit_amount": { "description": "Price of a single unit, micro-USD", "example": 1500, "format": "int64", "type": "integer" } }, "required": [ "amount", "created_at", "description", "id", "invoice_id", "kind", "metadata", "period_end", "period_start", "quantity", "subject_id", "unit_amount" ], "type": "object" }, "InvoiceRenderResponse": { "description": "A rendered invoice: its own fields flattened inline, plus the line items composing it.", "properties": { "account_id": { "description": "Account the invoice is billed to", "example": "1456074443980800000", "type": "string" }, "amount_due": { "description": "Amount still payable on this invoice, micro-USD", "example": 7500000, "format": "int64", "type": "integer" }, "amount_paid": { "description": "Amount already applied to this invoice, micro-USD", "example": 5000000, "format": "int64", "type": "integer" }, "created_at": { "description": "Creation time of the invoice", "format": "date-time", "type": "string" }, "currency": { "description": "ISO 4217 currency code of the invoice", "example": "USD", "type": "string" }, "due_at": { "description": "Payment due date, stamped when the invoice is issued", "format": "date-time", "type": [ "string", "null" ] }, "id": { "description": "Invoice id", "example": "1456074443980800000", "type": "string" }, "issued_at": { "description": "Issue time, null while the invoice is DRAFT", "format": "date-time", "type": [ "string", "null" ] }, "kind": { "description": "CONSOLIDATED, TOPUP or ORDER", "enum": [ "CONSOLIDATED", "TOPUP", "ORDER" ], "type": "string" }, "line_items": { "description": "Line items composing the invoice subtotal", "items": { "$ref": "#/components/schemas/InvoiceLineItemView" }, "type": "array" }, "number": { "description": "Human-readable invoice number, allocated when the invoice is issued and null while DRAFT", "example": "INV-2026-000001", "type": [ "string", "null" ] }, "paid_at": { "description": "Settlement time, null until the invoice is fully paid", "format": "date-time", "type": [ "string", "null" ] }, "pending_payment_count": { "description": "How many payments against this invoice are still awaiting confirmation", "example": 1, "format": "int64", "type": "integer" }, "period_end": { "description": "End of the billed period, if the invoice covers one", "format": "date-time", "type": [ "string", "null" ] }, "period_start": { "description": "Start of the billed period, if the invoice covers one", "format": "date-time", "type": [ "string", "null" ] }, "status": { "description": "DRAFT, OPEN, PAID, VOID or UNCOLLECTIBLE", "enum": [ "DRAFT", "OPEN", "PAID", "VOID", "UNCOLLECTIBLE" ], "type": "string" }, "subject_id": { "description": "Billing subject this invoice covers, null for consolidated and top-up invoices", "example": "1456074443980800000", "type": [ "string", "null" ] }, "subtotal": { "description": "Sum of the line items before tax, micro-USD", "example": 12500000, "format": "int64", "type": "integer" }, "tax_total": { "description": "Tax charged on top of the subtotal, micro-USD", "example": 0, "format": "int64", "type": "integer" }, "total": { "description": "Total invoiced, subtotal plus tax, micro-USD", "example": 12500000, "format": "int64", "type": "integer" }, "user": { "$ref": "#/components/schemas/UserSimple", "description": "User the account bills for" } }, "required": [ "account_id", "amount_due", "amount_paid", "created_at", "currency", "due_at", "id", "issued_at", "kind", "line_items", "number", "paid_at", "pending_payment_count", "period_end", "period_start", "status", "subject_id", "subtotal", "tax_total", "total", "user" ], "type": "object" }, "InvoiceView": { "description": "A collection request against an account, with its totals, status and lifecycle timestamps.", "properties": { "account_id": { "description": "Account the invoice is billed to", "example": "1456074443980800000", "type": "string" }, "amount_due": { "description": "Amount still payable on this invoice, micro-USD", "example": 7500000, "format": "int64", "type": "integer" }, "amount_paid": { "description": "Amount already applied to this invoice, micro-USD", "example": 5000000, "format": "int64", "type": "integer" }, "created_at": { "description": "Creation time of the invoice", "format": "date-time", "type": "string" }, "currency": { "description": "ISO 4217 currency code of the invoice", "example": "USD", "type": "string" }, "due_at": { "description": "Payment due date, stamped when the invoice is issued", "format": "date-time", "type": [ "string", "null" ] }, "id": { "description": "Invoice id", "example": "1456074443980800000", "type": "string" }, "issued_at": { "description": "Issue time, null while the invoice is DRAFT", "format": "date-time", "type": [ "string", "null" ] }, "kind": { "description": "CONSOLIDATED, TOPUP or ORDER", "enum": [ "CONSOLIDATED", "TOPUP", "ORDER" ], "type": "string" }, "number": { "description": "Human-readable invoice number, allocated when the invoice is issued and null while DRAFT", "example": "INV-2026-000001", "type": [ "string", "null" ] }, "paid_at": { "description": "Settlement time, null until the invoice is fully paid", "format": "date-time", "type": [ "string", "null" ] }, "pending_payment_count": { "description": "How many payments against this invoice are still awaiting confirmation", "example": 1, "format": "int64", "type": "integer" }, "period_end": { "description": "End of the billed period, if the invoice covers one", "format": "date-time", "type": [ "string", "null" ] }, "period_start": { "description": "Start of the billed period, if the invoice covers one", "format": "date-time", "type": [ "string", "null" ] }, "status": { "description": "DRAFT, OPEN, PAID, VOID or UNCOLLECTIBLE", "enum": [ "DRAFT", "OPEN", "PAID", "VOID", "UNCOLLECTIBLE" ], "type": "string" }, "subject_id": { "description": "Billing subject this invoice covers, null for consolidated and top-up invoices", "example": "1456074443980800000", "type": [ "string", "null" ] }, "subtotal": { "description": "Sum of the line items before tax, micro-USD", "example": 12500000, "format": "int64", "type": "integer" }, "tax_total": { "description": "Tax charged on top of the subtotal, micro-USD", "example": 0, "format": "int64", "type": "integer" }, "total": { "description": "Total invoiced, subtotal plus tax, micro-USD", "example": 12500000, "format": "int64", "type": "integer" }, "user": { "$ref": "#/components/schemas/UserSimple", "description": "User the account bills for" } }, "required": [ "account_id", "amount_due", "amount_paid", "created_at", "currency", "due_at", "id", "issued_at", "kind", "number", "paid_at", "pending_payment_count", "period_end", "period_start", "status", "subject_id", "subtotal", "tax_total", "total", "user" ], "type": "object" }, "IpAddressProperties": { "description": "Provisioning inputs for an IP_ADDRESS; it takes none.", "properties": { "kind": { "description": "The kind these properties are for", "enum": [ "IP_ADDRESS" ], "type": "string" } }, "required": [ "kind" ], "type": "object" }, "IpAddressSpec": { "description": "Values for an IP_ADDRESS package's open fields.", "properties": { "ddos": { "description": "Whether the address is DDoS protected", "example": false, "type": [ "boolean", "null" ], "x-mutation": "FLEXIBLE", "x-priced": true, "x-required-on-package": true }, "family": { "description": "Address family", "enum": [ "IPv4", "IPv6" ], "example": "IPv4", "type": [ "string", "null" ], "x-mutation": "IMMUTABLE", "x-priced": true, "x-required-on-package": true }, "kind": { "description": "The kind this spec is for", "enum": [ "IP_ADDRESS" ], "type": "string" }, "region": { "description": "Where the address is routed", "enum": [ "NA_01" ], "example": "NA_01", "type": [ "string", "null" ], "x-mutation": "IMMUTABLE", "x-priced": false, "x-required-on-package": true } }, "required": [ "kind" ], "type": "object" }, "Item": { "description": "An order item with its part lines.", "properties": { "item": { "$ref": "#/components/schemas/OrderItemView", "description": "The item" }, "parts": { "description": "The item's part lines", "items": { "$ref": "#/components/schemas/OrderItemPartView" }, "type": "array" } }, "required": [ "item", "parts" ], "type": "object" }, "KeysetResultCouponRedemptionView": { "properties": { "after": { "type": [ "string", "null" ] }, "before": { "type": [ "string", "null" ] }, "has_next": { "type": "boolean" }, "has_previous": { "type": "boolean" }, "items": { "items": { "$ref": "#/components/schemas/CouponRedemptionView" }, "type": "array" }, "limit": { "description": "Limit of items returned per page", "format": "int32", "maximum": 100, "minimum": 1, "type": "integer" }, "page": { "description": "Page number", "format": "int32", "maximum": 1000, "minimum": 1, "type": "integer" }, "total": { "description": "Total number of matching items", "format": "int64", "minimum": 0, "type": "integer" } }, "required": [ "after", "before", "has_next", "has_previous", "items", "limit", "page", "total" ], "type": "object" }, "KeysetResultInvoiceView": { "properties": { "after": { "type": [ "string", "null" ] }, "before": { "type": [ "string", "null" ] }, "has_next": { "type": "boolean" }, "has_previous": { "type": "boolean" }, "items": { "items": { "$ref": "#/components/schemas/InvoiceView" }, "type": "array" }, "limit": { "description": "Limit of items returned per page", "format": "int32", "maximum": 100, "minimum": 1, "type": "integer" }, "page": { "description": "Page number", "format": "int32", "maximum": 1000, "minimum": 1, "type": "integer" }, "total": { "description": "Total number of matching items", "format": "int64", "minimum": 0, "type": "integer" } }, "required": [ "after", "before", "has_next", "has_previous", "items", "limit", "page", "total" ], "type": "object" }, "KeysetResultLedgerEntryView": { "properties": { "after": { "type": [ "string", "null" ] }, "before": { "type": [ "string", "null" ] }, "has_next": { "type": "boolean" }, "has_previous": { "type": "boolean" }, "items": { "items": { "$ref": "#/components/schemas/LedgerEntryView" }, "type": "array" }, "limit": { "description": "Limit of items returned per page", "format": "int32", "maximum": 100, "minimum": 1, "type": "integer" }, "page": { "description": "Page number", "format": "int32", "maximum": 1000, "minimum": 1, "type": "integer" }, "total": { "description": "Total number of matching items", "format": "int64", "minimum": 0, "type": "integer" } }, "required": [ "after", "before", "has_next", "has_previous", "items", "limit", "page", "total" ], "type": "object" }, "KeysetResultOrderView": { "properties": { "after": { "type": [ "string", "null" ] }, "before": { "type": [ "string", "null" ] }, "has_next": { "type": "boolean" }, "has_previous": { "type": "boolean" }, "items": { "items": { "$ref": "#/components/schemas/OrderView" }, "type": "array" }, "limit": { "description": "Limit of items returned per page", "format": "int32", "maximum": 100, "minimum": 1, "type": "integer" }, "page": { "description": "Page number", "format": "int32", "maximum": 1000, "minimum": 1, "type": "integer" }, "total": { "description": "Total number of matching items", "format": "int64", "minimum": 0, "type": "integer" } }, "required": [ "after", "before", "has_next", "has_previous", "items", "limit", "page", "total" ], "type": "object" }, "KeysetResultPackageDetailResponse": { "properties": { "after": { "type": [ "string", "null" ] }, "before": { "type": [ "string", "null" ] }, "has_next": { "type": "boolean" }, "has_previous": { "type": "boolean" }, "items": { "items": { "$ref": "#/components/schemas/PackageDetailResponse" }, "type": "array" }, "limit": { "description": "Limit of items returned per page", "format": "int32", "maximum": 100, "minimum": 1, "type": "integer" }, "page": { "description": "Page number", "format": "int32", "maximum": 1000, "minimum": 1, "type": "integer" }, "total": { "description": "Total number of matching items", "format": "int64", "minimum": 0, "type": "integer" } }, "required": [ "after", "before", "has_next", "has_previous", "items", "limit", "page", "total" ], "type": "object" }, "KeysetResultPackageTransitionResponse": { "properties": { "after": { "type": [ "string", "null" ] }, "before": { "type": [ "string", "null" ] }, "has_next": { "type": "boolean" }, "has_previous": { "type": "boolean" }, "items": { "items": { "$ref": "#/components/schemas/PackageTransitionResponse" }, "type": "array" }, "limit": { "description": "Limit of items returned per page", "format": "int32", "maximum": 100, "minimum": 1, "type": "integer" }, "page": { "description": "Page number", "format": "int32", "maximum": 1000, "minimum": 1, "type": "integer" }, "total": { "description": "Total number of matching items", "format": "int64", "minimum": 0, "type": "integer" } }, "required": [ "after", "before", "has_next", "has_previous", "items", "limit", "page", "total" ], "type": "object" }, "KeysetResultPaymentMethodView": { "properties": { "after": { "type": [ "string", "null" ] }, "before": { "type": [ "string", "null" ] }, "has_next": { "type": "boolean" }, "has_previous": { "type": "boolean" }, "items": { "items": { "$ref": "#/components/schemas/PaymentMethodView" }, "type": "array" }, "limit": { "description": "Limit of items returned per page", "format": "int32", "maximum": 100, "minimum": 1, "type": "integer" }, "page": { "description": "Page number", "format": "int32", "maximum": 1000, "minimum": 1, "type": "integer" }, "total": { "description": "Total number of matching items", "format": "int64", "minimum": 0, "type": "integer" } }, "required": [ "after", "before", "has_next", "has_previous", "items", "limit", "page", "total" ], "type": "object" }, "KeysetResultPaymentView": { "properties": { "after": { "type": [ "string", "null" ] }, "before": { "type": [ "string", "null" ] }, "has_next": { "type": "boolean" }, "has_previous": { "type": "boolean" }, "items": { "items": { "$ref": "#/components/schemas/PaymentView" }, "type": "array" }, "limit": { "description": "Limit of items returned per page", "format": "int32", "maximum": 100, "minimum": 1, "type": "integer" }, "page": { "description": "Page number", "format": "int32", "maximum": 1000, "minimum": 1, "type": "integer" }, "total": { "description": "Total number of matching items", "format": "int64", "minimum": 0, "type": "integer" } }, "required": [ "after", "before", "has_next", "has_previous", "items", "limit", "page", "total" ], "type": "object" }, "KeysetResultSubjectTransitionResponse": { "properties": { "after": { "type": [ "string", "null" ] }, "before": { "type": [ "string", "null" ] }, "has_next": { "type": "boolean" }, "has_previous": { "type": "boolean" }, "items": { "items": { "$ref": "#/components/schemas/SubjectTransitionResponse" }, "type": "array" }, "limit": { "description": "Limit of items returned per page", "format": "int32", "maximum": 100, "minimum": 1, "type": "integer" }, "page": { "description": "Page number", "format": "int32", "maximum": 1000, "minimum": 1, "type": "integer" }, "total": { "description": "Total number of matching items", "format": "int64", "minimum": 0, "type": "integer" } }, "required": [ "after", "before", "has_next", "has_previous", "items", "limit", "page", "total" ], "type": "object" }, "KeysetResultSubjectUsageResponse": { "properties": { "after": { "type": [ "string", "null" ] }, "before": { "type": [ "string", "null" ] }, "has_next": { "type": "boolean" }, "has_previous": { "type": "boolean" }, "items": { "items": { "$ref": "#/components/schemas/SubjectUsageResponse" }, "type": "array" }, "limit": { "description": "Limit of items returned per page", "format": "int32", "maximum": 100, "minimum": 1, "type": "integer" }, "page": { "description": "Page number", "format": "int32", "maximum": 1000, "minimum": 1, "type": "integer" }, "total": { "description": "Total number of matching items", "format": "int64", "minimum": 0, "type": "integer" } }, "required": [ "after", "before", "has_next", "has_previous", "items", "limit", "page", "total" ], "type": "object" }, "KeysetResultSubjectView": { "properties": { "after": { "type": [ "string", "null" ] }, "before": { "type": [ "string", "null" ] }, "has_next": { "type": "boolean" }, "has_previous": { "type": "boolean" }, "items": { "items": { "$ref": "#/components/schemas/SubjectView" }, "type": "array" }, "limit": { "description": "Limit of items returned per page", "format": "int32", "maximum": 100, "minimum": 1, "type": "integer" }, "page": { "description": "Page number", "format": "int32", "maximum": 1000, "minimum": 1, "type": "integer" }, "total": { "description": "Total number of matching items", "format": "int64", "minimum": 0, "type": "integer" } }, "required": [ "after", "before", "has_next", "has_previous", "items", "limit", "page", "total" ], "type": "object" }, "KeysetResultUsageRecordView": { "properties": { "after": { "type": [ "string", "null" ] }, "before": { "type": [ "string", "null" ] }, "has_next": { "type": "boolean" }, "has_previous": { "type": "boolean" }, "items": { "items": { "$ref": "#/components/schemas/UsageRecordView" }, "type": "array" }, "limit": { "description": "Limit of items returned per page", "format": "int32", "maximum": 100, "minimum": 1, "type": "integer" }, "page": { "description": "Page number", "format": "int32", "maximum": 1000, "minimum": 1, "type": "integer" }, "total": { "description": "Total number of matching items", "format": "int64", "minimum": 0, "type": "integer" } }, "required": [ "after", "before", "has_next", "has_previous", "items", "limit", "page", "total" ], "type": "object" }, "KindProperties": { "description": "Provisioning inputs for a purchase, typed by kind", "discriminator": { "mapping": { "IP_ADDRESS": "#/components/schemas/IpAddressProperties", "SERVER": "#/components/schemas/ServerProperties" }, "propertyName": "kind" }, "oneOf": [ { "$ref": "#/components/schemas/ServerProperties" }, { "$ref": "#/components/schemas/IpAddressProperties" } ] }, "KindSpec": { "description": "Values for the fields a package leaves open, typed by kind", "discriminator": { "mapping": { "IP_ADDRESS": "#/components/schemas/IpAddressSpec", "SERVER": "#/components/schemas/ServerSpec" }, "propertyName": "kind" }, "oneOf": [ { "$ref": "#/components/schemas/ServerSpec" }, { "$ref": "#/components/schemas/IpAddressSpec" } ] }, "LedgerEntryView": { "description": "One line of a wallet's append-only journal, recording a single movement of credit.", "properties": { "actor": { "anyOf": [ { "$ref": "#/components/schemas/UserSimple" }, { "type": "null" } ], "description": "User who initiated the movement, if any" }, "amount": { "description": "Signed movement amount, micro-USD; positive credits, negative draws", "example": -2500000, "format": "int64", "type": "integer" }, "balance_after": { "description": "Wallet balance after this entry, micro-USD", "example": 9750000, "format": "int64", "type": "integer" }, "created_at": { "description": "When the entry was written", "format": "date-time", "type": "string" }, "group_ref": { "description": "Ties together the entries a single draw produces across credit lots", "example": "1456074443980800000", "type": [ "string", "null" ] }, "id": { "description": "Ledger entry id", "example": "1456074443980800000", "type": "string" }, "invoice_id": { "description": "Invoice this entry relates to, if any", "example": "1456074443980800000", "type": [ "string", "null" ] }, "lot_id": { "description": "Credit lot this entry credits or draws; null on an overdraft entry", "example": "1456074443980800000", "type": [ "string", "null" ] }, "reference": { "description": "Free-form reference describing the movement", "example": "Support goodwill credit", "type": [ "string", "null" ] }, "subject_id": { "description": "Billing subject this entry is attributed to, if any", "example": "1456074443980800000", "type": [ "string", "null" ] }, "type": { "description": "Kind of movement this entry records", "enum": [ "TOPUP", "USAGE_CHARGE", "FIXED_CHARGE", "INVOICE_SETTLEMENT", "REFUND", "ADJUSTMENT", "COUPON", "EXPIRY", "CANCEL_REFUND", "REPRICE_REFUND" ], "type": "string" }, "wallet_id": { "description": "Wallet this entry belongs to", "example": "1456074443980800000", "type": "string" } }, "required": [ "actor", "amount", "balance_after", "created_at", "group_ref", "id", "invoice_id", "lot_id", "reference", "subject_id", "type", "wallet_id" ], "type": "object" }, "MoveMonthlyDateRequest": { "description": "Moves the account's monthly date.", "properties": { "day": { "description": "New day of the month. In shorter months the last day of the month applies.", "example": 15, "format": "int32", "maximum": 31, "minimum": 1, "type": [ "integer", "null" ] } }, "required": [ "day" ], "type": "object" }, "MoveRenewalDayRequest": { "description": "Moves a prepaid subject's renewal forward to a day of the month.", "properties": { "day": { "description": "Day of the month to renew on. In shorter months the last day of the month applies. Defaults to the account's monthly date.", "example": 15, "format": "int32", "maximum": 31, "minimum": 1, "type": [ "integer", "null" ] } }, "type": "object" }, "OrderDetailResponse": { "description": "An order with its items and their part lines.", "properties": { "items": { "description": "The order's items, each with its part lines", "items": { "$ref": "#/components/schemas/Item" }, "type": "array" }, "order": { "$ref": "#/components/schemas/OrderView", "description": "The order" } }, "required": [ "items", "order" ], "type": "object" }, "OrderItemPartView": { "description": "One field of an order item, with its priced contribution.", "properties": { "amount": { "description": "This part's contribution to the item charge, micro-USD", "example": 0, "format": "int64", "type": "integer" }, "id": { "description": "Order item part id", "example": "1456074443980800000", "type": "string" }, "order_item_id": { "description": "Order item this part belongs to", "example": "1456074443980800000", "type": "string" }, "part_code": { "description": "Field code", "example": "ram", "type": "string" }, "quantity": { "description": "Value of a numeric field", "example": 8, "format": "int64", "type": [ "integer", "null" ] }, "rate_card_id": { "description": "Rate card that priced this part, if any", "example": "1456074443980800000", "type": [ "string", "null" ] }, "unit_price": { "description": "Monthly rate snapshot, micro-USD", "example": 5000000, "format": "int64", "type": "integer" }, "value": { "description": "Value of an enum or boolean field", "example": "LOCAL", "type": [ "string", "null" ] } }, "required": [ "amount", "id", "order_item_id", "part_code", "quantity", "rate_card_id", "unit_price", "value" ], "type": "object" }, "OrderItemView": { "description": "One package on an order, with its snapshotted price and charge terms.", "properties": { "amount": { "description": "This item's contribution to the order total, micro-USD", "example": 20000000, "format": "int64", "type": "integer" }, "base_price": { "description": "Flat base price snapshot, micro-USD", "example": 20000000, "format": "int64", "type": "integer" }, "charge_basis": { "description": "FIXED or METERED", "enum": [ "FIXED", "METERED" ], "type": "string" }, "cycle_count": { "description": "Cycle length in units", "example": 1, "format": "int32", "type": [ "integer", "null" ] }, "cycle_unit": { "description": "Cycle unit, e.g. MONTH", "type": [ "string", "null" ] }, "id": { "description": "Order item id", "example": "1456074443980800000", "type": "string" }, "kind": { "description": "PURCHASE or UPGRADE", "enum": [ "PURCHASE", "UPGRADE", "ADJUST" ], "type": "string" }, "order_id": { "description": "Order this item belongs to", "example": "1456074443980800000", "type": "string" }, "package_code": { "description": "Package SKU code purchased", "example": "vps-small", "type": "string" }, "payment_mode": { "description": "PREPAID or POSTPAID", "enum": [ "PREPAID", "POSTPAID" ], "type": "string" }, "resource_kind": { "description": "Kind of resource this item bills for", "enum": [ "SERVER", "IP_ADDRESS" ], "example": "SERVER", "type": "string" }, "resource_name": { "description": "Display name for the resource", "example": "web-01", "type": "string" }, "subject_id": { "description": "Subject created for this item on green, null until then", "example": "1456074443980800000", "type": [ "string", "null" ] }, "target_subject_id": { "description": "Subject an upgrade targets, null for a purchase", "example": "1456074443980800000", "type": [ "string", "null" ] } }, "required": [ "amount", "base_price", "charge_basis", "cycle_count", "cycle_unit", "id", "kind", "order_id", "package_code", "payment_mode", "resource_kind", "resource_name", "subject_id", "target_subject_id" ], "type": "object" }, "OrderView": { "description": "A purchase or upgrade transaction, with its totals, status and the invoice it collects on.", "properties": { "account_id": { "description": "Account the order is billed to", "example": "1456074443980800000", "type": "string" }, "actor": { "$ref": "#/components/schemas/UserSimple", "description": "User who placed the order" }, "created_at": { "description": "Creation time of the order", "format": "date-time", "type": "string" }, "greened_at": { "description": "Time the order greened into subjects, null until then", "format": "date-time", "type": [ "string", "null" ] }, "id": { "description": "Order id", "example": "1456074443980800000", "type": "string" }, "invoice_id": { "description": "Invoice raised to collect the order, null until one is raised", "example": "1456074443980800000", "type": [ "string", "null" ] }, "kind": { "description": "PURCHASE or UPGRADE", "enum": [ "PURCHASE", "UPGRADE", "ADJUST" ], "type": "string" }, "status": { "description": "DRAFT, AWAITING_APPROVAL, AWAITING_PAYMENT, GREEN, FULFILLED, FAILED or CANCELLED. FAILED means the invoice was not paid, or the subject changed before a paid plan change applied and the payment was returned as account credit.", "enum": [ "DRAFT", "AWAITING_APPROVAL", "AWAITING_PAYMENT", "GREEN", "FULFILLED", "FAILED", "CANCELLED" ], "type": "string" }, "subtotal": { "description": "Sum of the item amounts before tax, micro-USD", "example": 20000000, "format": "int64", "type": "integer" }, "total": { "description": "Total to collect for the order, micro-USD", "example": 20000000, "format": "int64", "type": "integer" }, "user": { "$ref": "#/components/schemas/UserSimple", "description": "Workspace owner the order bills" }, "workspace": { "anyOf": [ { "$ref": "#/components/schemas/WorkspaceSimple" }, { "type": "null" } ], "description": "Workspace the order was placed in" } }, "required": [ "account_id", "actor", "created_at", "greened_at", "id", "invoice_id", "kind", "status", "subtotal", "total", "user", "workspace" ], "type": "object" }, "PackageDetailResponse": { "description": "A package with its offers, its rate card and its cheapest price.", "properties": { "base_price": { "description": "Price per cycle covering every pinned field, micro-USD", "example": 20000000, "format": "int64", "type": "integer" }, "charge_basis": { "description": "FIXED or METERED", "enum": [ "FIXED", "METERED" ], "type": "string" }, "code": { "description": "Unique package code", "example": "vps-small", "type": "string" }, "created_at": { "description": "Creation time", "format": "date-time", "type": "string" }, "cycle_count": { "description": "Cycle length in units", "example": 1, "format": "int32", "type": [ "integer", "null" ] }, "cycle_unit": { "description": "Calendar cycle unit", "example": "MONTH", "type": [ "string", "null" ] }, "from_price": { "description": "Cheapest price the package sells at, micro-USD: the base price plus every field the buyer chooses at its cheapest value. Per cycle for FIXED charge, per active hour for METERED. Equal to base_price when the buyer chooses nothing priced; null when the package cannot be priced", "example": 6000000, "format": "int64", "type": [ "integer", "null" ] }, "id": { "description": "Package id", "example": "1456074443980800000", "type": "string" }, "name": { "description": "Display name", "example": "VPS Small", "type": "string" }, "rate_card": { "anyOf": [ { "$ref": "#/components/schemas/RateCardDetailResponse" }, { "type": "null" } ], "description": "Rate card for the fields the buyer selects; null when the base price is the full price" }, "rate_card_id": { "description": "Rate card pricing the fields the buyer chooses", "example": "1456074443980800000", "type": [ "string", "null" ] }, "resource_kind": { "description": "Kind sold, which fixes the shape of the spec", "enum": [ "SERVER", "IP_ADDRESS" ], "example": "SERVER", "type": "string" }, "spec": { "description": "One offer per field", "items": { "$ref": "#/components/schemas/PackageSpecPartView" }, "type": "array" }, "state": { "description": "ACTIVE (sold) or RETIRED (not sold); a retired package stays readable by code", "enum": [ "ACTIVE", "RETIRED" ], "type": "string" } }, "required": [ "base_price", "charge_basis", "code", "created_at", "cycle_count", "cycle_unit", "from_price", "id", "name", "rate_card", "rate_card_id", "resource_kind", "spec", "state" ], "type": "object" }, "PackageSpecPartView": { "description": "A package's offer for one field: a pinned value, or a choice left to the buyer.", "properties": { "id": { "description": "Spec part id", "example": "1456074443980800000", "type": "string" }, "max_qty": { "description": "Largest value the buyer may choose for an open numeric field", "example": 16, "format": "int64", "type": [ "integer", "null" ] }, "min_qty": { "description": "Smallest value the buyer may choose for an open numeric field", "example": 1, "format": "int64", "type": [ "integer", "null" ] }, "mode": { "description": "PINNED (the package sets the value) or OPEN (the buyer chooses it)", "enum": [ "PINNED", "OPEN" ], "example": "PINNED", "type": "string" }, "package_id": { "description": "Package this spec line belongs to", "example": "1456074443980800000", "type": "string" }, "part_code": { "description": "Field code", "example": "ram", "type": "string" }, "quantity": { "description": "Pinned value of a numeric field", "example": 4096, "format": "int64", "type": [ "integer", "null" ] }, "value": { "description": "Pinned value of an enum or boolean field", "example": "LOCAL", "type": [ "string", "null" ] } }, "required": [ "id", "max_qty", "min_qty", "mode", "package_id", "part_code", "quantity", "value" ], "type": "object" }, "PackageTransitionResponse": { "description": "A move a subject on the source package may make, with the package it goes to.", "properties": { "created_at": { "description": "Creation time", "format": "date-time", "type": "string" }, "direction": { "description": "UPGRADE or DOWNGRADE", "enum": [ "UPGRADE", "DOWNGRADE" ], "example": "UPGRADE", "type": "string" }, "id": { "description": "Transition id", "example": "1456074443980800000", "type": "string" }, "target": { "$ref": "#/components/schemas/PackageDetailResponse", "description": "The package the move goes to, in the same shape as a package list item" } }, "required": [ "created_at", "direction", "id", "target" ], "type": "object" }, "PaymentMethodView": { "description": "A payment method stored at a gateway so an account can be charged without the customer present.", "properties": { "account_id": { "description": "Account this method belongs to", "example": "1456074443980800000", "type": "string" }, "brand": { "description": "Card brand", "example": "visa", "type": [ "string", "null" ] }, "created_at": { "description": "When the method was stored", "format": "date-time", "type": "string" }, "exp_month": { "description": "Card expiry month", "example": 9, "format": "int32", "type": [ "integer", "null" ] }, "exp_year": { "description": "Card expiry year", "example": 2029, "format": "int32", "type": [ "integer", "null" ] }, "gateway": { "description": "Gateway holding this method", "enum": [ "STRIPE", "PAYPAL", "MANUAL" ], "type": "string" }, "gateway_customer_ref": { "description": "Gateway's own reference for the customer holding this method", "example": "cus_QF8xJ2mNbT1a", "type": "string" }, "gateway_method_ref": { "description": "Gateway's own reference for the stored method", "example": "pm_1PqL9xErTn8kQz1a", "type": "string" }, "id": { "description": "Payment method id", "example": "1456074443980800000", "type": "string" }, "is_default": { "description": "Whether this is the account's default method for automatic charges", "type": "boolean" }, "last4": { "description": "Last four digits of the card", "example": "4242", "type": [ "string", "null" ] }, "user": { "$ref": "#/components/schemas/UserSimple", "description": "User the account bills for" } }, "required": [ "account_id", "brand", "created_at", "exp_month", "exp_year", "gateway", "gateway_customer_ref", "gateway_method_ref", "id", "is_default", "last4", "user" ], "type": "object" }, "PaymentView": { "description": "A real-money movement collected from or returned to an account through a payment gateway.", "properties": { "account_id": { "description": "Account this payment belongs to", "example": "1456074443980800000", "type": "string" }, "amount": { "description": "Payment amount, micro-USD", "example": 5000000, "format": "int64", "type": "integer" }, "captured_at": { "description": "When the gateway settled the payment; null while it is pending", "format": "date-time", "type": [ "string", "null" ] }, "created_at": { "description": "When the payment was created", "format": "date-time", "type": "string" }, "credit_lot_id": { "description": "Wallet credit lot a succeeded inbound payment mints; null otherwise", "example": "1456074443980800000", "type": [ "string", "null" ] }, "currency": { "description": "ISO currency code of the amount", "example": "USD", "type": "string" }, "direction": { "description": "INBOUND for money collected, REFUND for money returned", "enum": [ "INBOUND", "REFUND" ], "type": "string" }, "failure_reason": { "description": "Why the gateway declined a failed payment; null otherwise", "example": "card_declined", "type": [ "string", "null" ] }, "gateway": { "description": "Gateway processing this payment", "enum": [ "STRIPE", "PAYPAL", "MANUAL" ], "type": "string" }, "gateway_ref": { "description": "Gateway's own reference for this payment", "example": "ch_3PqL9xErTn8kQz1a", "type": [ "string", "null" ] }, "id": { "description": "Payment id", "example": "1456074443980800000", "type": "string" }, "invoice_id": { "description": "Invoice this payment applies to, if any", "example": "1456074443980800000", "type": [ "string", "null" ] }, "payment_method_id": { "description": "Stored payment method charged for this payment, if any", "example": "1456074443980800000", "type": [ "string", "null" ] }, "refund_of": { "description": "For a refund, ID of the original payment; null otherwise", "example": "1456074443980800000", "type": [ "string", "null" ] }, "refunded_amount": { "description": "Amount refunded from this payment, micro-USD; 0 if not refunded or if this payment is a refund", "example": 0, "format": "int64", "type": "integer" }, "status": { "description": "PENDING until the gateway settles the payment, then SUCCEEDED, FAILED, or REFUNDED", "enum": [ "PENDING", "SUCCEEDED", "FAILED", "REFUNDED" ], "type": "string" }, "user": { "$ref": "#/components/schemas/UserSimple", "description": "User the account bills for" } }, "required": [ "account_id", "amount", "captured_at", "created_at", "credit_lot_id", "currency", "direction", "failure_reason", "gateway", "gateway_ref", "id", "invoice_id", "payment_method_id", "refund_of", "refunded_amount", "status", "user" ], "type": "object" }, "RateCardDetailResponse": { "description": "A rate card with its prices.", "properties": { "code": { "description": "Unique rate card code", "example": "server-parts", "type": "string" }, "created_at": { "description": "Creation time", "format": "date-time", "type": "string" }, "id": { "description": "Rate card id", "example": "1456074443980800000", "type": "string" }, "name": { "description": "Display name", "example": "Server parts", "type": "string" }, "parts": { "description": "Prices", "items": { "$ref": "#/components/schemas/RateCardPartView" }, "type": "array" }, "state": { "description": "ACTIVE or RETIRED", "enum": [ "ACTIVE", "RETIRED" ], "type": "string" } }, "required": [ "code", "created_at", "id", "name", "parts", "state" ], "type": "object" }, "RateCardPartView": { "description": "One price on a rate card, micro-USD per month.", "properties": { "id": { "description": "Rate card part id", "example": "1456074443980800000", "type": "string" }, "part_code": { "description": "Field code", "example": "ram", "type": "string" }, "per_units": { "description": "How many units of a numeric field unit_price covers", "example": 1024, "format": "int64", "type": "integer" }, "rate_card_id": { "description": "Rate card this price belongs to", "example": "1456074443980800000", "type": "string" }, "unit_price": { "description": "Price per month, micro-USD: per per_units units, or flat for a value", "example": 2000000, "format": "int64", "type": "integer" }, "value": { "description": "The enum or boolean value this flat price is for; null when the line prices a numeric field", "example": "true", "type": [ "string", "null" ] } }, "required": [ "id", "part_code", "per_units", "rate_card_id", "unit_price", "value" ], "type": "object" }, "RedeemCouponRequest": { "description": "A coupon code to redeem into the user's wallet.", "properties": { "code": { "description": "Coupon code", "example": "WELCOME10", "minLength": 1, "type": "string" } }, "required": [ "code" ], "type": "object" }, "RedeemCouponResponse": { "description": "The result of a coupon redemption: the wallet after the grant and the COUPON ledger entry it wrote.", "properties": { "entry": { "$ref": "#/components/schemas/LedgerEntryView", "description": "The COUPON ledger entry recording the granted credit" }, "wallet": { "$ref": "#/components/schemas/WalletView", "description": "The wallet as it stands after the credit lands" } }, "required": [ "entry", "wallet" ], "type": "object" }, "RenewalDayQuoteResponse": { "description": "What moving a subject's renewal day costs at this time.", "properties": { "anchor_day": { "description": "The day of the month the subject renews on after the move", "example": 15, "format": "int32", "type": "integer" }, "charge": { "description": "The charge for the added days, micro-USD", "example": 2500000, "format": "int64", "type": "integer" }, "new_period_end": { "description": "When the subject renews after the move", "format": "date-time", "type": "string" }, "period_end": { "description": "When the subject renews before the move", "format": "date-time", "type": "string" } }, "required": [ "anchor_day", "charge", "new_period_end", "period_end" ], "type": "object" }, "RenewalDayResponse": { "description": "The result of moving a subject's renewal day.", "properties": { "applied": { "description": "Whether the renewal moved. False while the invoice for the added days is unpaid.", "type": "boolean" }, "collection": { "description": "NONE if nothing is owed, IN_FLIGHT while a stored method is charging, REQUIRED to go to a checkout", "enum": [ "NONE", "IN_FLIGHT", "REQUIRED", "APPROVAL_REQUIRED", "OWNER_REQUIRED" ], "type": "string" }, "invoice_id": { "description": "The invoice for the added days, when they could not be paid from the wallet", "example": "1456074443980800000", "type": [ "string", "null" ] }, "subject": { "$ref": "#/components/schemas/SubjectView", "description": "The subject after the move" } }, "required": [ "applied", "collection", "invoice_id", "subject" ], "type": "object" }, "ServerProperties": { "description": "Provisioning inputs for a SERVER.", "properties": { "image": { "description": "Template or backup installed on the disk", "example": "1447636552321908736", "type": "string" }, "kind": { "description": "The kind these properties are for", "enum": [ "SERVER" ], "type": "string" } }, "required": [ "image", "kind" ], "type": "object" }, "ServerSpec": { "description": "Values for a SERVER package's open fields.", "properties": { "backup": { "description": "Backup schedule", "enum": [ "WEEKLY", "DAILY" ], "example": "WEEKLY", "type": [ "string", "null" ], "x-mutation": "FLEXIBLE", "x-priced": true, "x-required-on-package": false }, "cpu": { "description": "Virtual CPU cores", "example": 4, "format": "int64", "maximum": 128, "minimum": 1, "type": [ "integer", "null" ], "x-mutation": "FLEXIBLE", "x-priced": true, "x-required-on-package": true, "x-unit": "vCPU" }, "ddos": { "description": "Whether the included IPv4 addresses are DDoS protected", "example": false, "type": [ "boolean", "null" ], "x-mutation": "FLEXIBLE", "x-priced": true, "x-required-on-package": false }, "disk": { "description": "Disk size in GiB", "example": 100, "format": "int64", "maximum": 4000, "minimum": 10, "multipleOf": 10, "type": [ "integer", "null" ], "x-mutation": "GROW_ONLY", "x-priced": true, "x-required-on-package": true, "x-unit": "GiB" }, "download": { "description": "Download bandwidth in Mbps", "example": 1000, "format": "int64", "maximum": 10000, "minimum": 100, "multipleOf": 100, "type": [ "integer", "null" ], "x-mutation": "FLEXIBLE", "x-priced": true, "x-required-on-package": true, "x-unit": "Mbps" }, "io_read": { "description": "Disk read limit in MiB/s", "example": 500, "format": "int64", "maximum": 95000, "minimum": 1, "type": [ "integer", "null" ], "x-mutation": "FLEXIBLE", "x-priced": false, "x-required-on-package": false, "x-unit": "MiB/s" }, "io_read_iops": { "description": "Disk read limit in IOPS", "example": 20000, "format": "int64", "maximum": 10000000, "minimum": 1, "type": [ "integer", "null" ], "x-mutation": "FLEXIBLE", "x-priced": false, "x-required-on-package": false, "x-unit": "IOPS" }, "io_write": { "description": "Disk write limit in MiB/s", "example": 250, "format": "int64", "maximum": 95000, "minimum": 1, "type": [ "integer", "null" ], "x-mutation": "FLEXIBLE", "x-priced": false, "x-required-on-package": false, "x-unit": "MiB/s" }, "io_write_iops": { "description": "Disk write limit in IOPS", "example": 10000, "format": "int64", "maximum": 10000000, "minimum": 1, "type": [ "integer", "null" ], "x-mutation": "FLEXIBLE", "x-priced": false, "x-required-on-package": false, "x-unit": "IOPS" }, "ipv4": { "description": "IPv4 addresses included", "example": 1, "format": "int64", "maximum": 16, "minimum": 0, "type": [ "integer", "null" ], "x-mutation": "IMMUTABLE", "x-priced": true, "x-required-on-package": true, "x-unit": "count" }, "ipv6": { "description": "IPv6 addresses included", "example": 1, "format": "int64", "maximum": 16, "minimum": 0, "type": [ "integer", "null" ], "x-mutation": "IMMUTABLE", "x-priced": true, "x-required-on-package": true, "x-unit": "count" }, "kind": { "description": "The kind this spec is for", "enum": [ "SERVER" ], "type": "string" }, "ram": { "description": "Memory in MiB", "example": 8192, "format": "int64", "maximum": 524288, "minimum": 512, "multipleOf": 512, "type": [ "integer", "null" ], "x-mutation": "FLEXIBLE", "x-priced": true, "x-required-on-package": true, "x-unit": "MiB" }, "region": { "description": "Where the server runs", "enum": [ "NA_01" ], "example": "NA_01", "type": [ "string", "null" ], "x-mutation": "IMMUTABLE", "x-priced": false, "x-required-on-package": true }, "service_group": { "description": "Hardware line the server runs on", "enum": [ "LIGHTNING", "RYZEN", "DEDICATED" ], "example": "LIGHTNING", "type": [ "string", "null" ], "x-mutation": "IMMUTABLE", "x-priced": true, "x-required-on-package": true }, "storage_backend": { "description": "Storage the disk lives on", "enum": [ "LOCAL", "CEPH" ], "example": "LOCAL", "type": [ "string", "null" ], "x-mutation": "IMMUTABLE", "x-priced": true, "x-required-on-package": true }, "upload": { "description": "Upload bandwidth in Mbps", "example": 1000, "format": "int64", "maximum": 10000, "minimum": 100, "multipleOf": 100, "type": [ "integer", "null" ], "x-mutation": "FLEXIBLE", "x-priced": true, "x-required-on-package": true, "x-unit": "Mbps" } }, "required": [ "kind" ], "type": "object" }, "SetupCommand": { "description": "Opens a checkout that stores a payment method for the user without collecting money now.", "properties": { "gateway": { "description": "Gateway that will hold the method", "enum": [ "STRIPE", "PAYPAL", "MANUAL" ], "example": "STRIPE", "type": "string" } }, "required": [ "gateway" ], "type": "object" }, "StripeClientConfig": { "description": "Configuration for Stripe.js and the checkout Payment Element", "properties": { "publishable_key": { "description": "Publishable API key for Stripe.js", "example": "pk_live_51H...", "type": "string" } }, "required": [ "publishable_key" ], "type": "object" }, "SubjectDetailResponse": { "description": "A subject with its spec and the priced fields behind its price.", "properties": { "account_id": { "description": "Account billed for this subject", "example": "1456074443980800000", "type": "string" }, "anchor_day": { "description": "FIXED only: day of the month the cycle renews on, or the last day of a shorter month", "example": 15, "format": "int32", "maximum": 31, "minimum": 1, "type": [ "integer", "null" ] }, "base_price": { "description": "Base price per cycle of the package, micro-USD", "example": 6000000, "format": "int64", "type": "integer" }, "charge_basis": { "description": "FIXED (exact price per calendar cycle) or METERED (rate times active time)", "enum": [ "FIXED", "METERED" ], "type": "string" }, "created_at": { "description": "Creation time of the subject", "format": "date-time", "type": "string" }, "current_period_end": { "description": "End of the current billing cycle", "format": "date-time", "type": [ "string", "null" ] }, "current_period_start": { "description": "Start of the current billing cycle", "format": "date-time", "type": [ "string", "null" ] }, "cycle_count": { "description": "FIXED only: number of cycle units per billing period", "example": 1, "format": "int32", "type": [ "integer", "null" ] }, "cycle_price": { "description": "FIXED only: amount charged per cycle, micro-USD", "example": 12500000, "format": "int64", "type": [ "integer", "null" ] }, "cycle_unit": { "description": "FIXED only: calendar cycle unit, MONTH or YEAR", "example": "MONTH", "type": [ "string", "null" ] }, "external_ref": { "description": "External collector reference, null when billing owns the meter", "type": [ "string", "null" ] }, "id": { "description": "Billing subject id", "example": "1456074443980800000", "type": "string" }, "last_tick_at": { "description": "Time of the most recent metered accrual", "format": "date-time", "type": [ "string", "null" ] }, "package_code": { "description": "SKU of the package the subject is on, null when it was not bought from the catalog", "example": "lightning-1g", "type": [ "string", "null" ] }, "paid_through_at": { "description": "Fixed-prepaid subjects: the time coverage is paid up to", "format": "date-time", "type": [ "string", "null" ] }, "parts": { "description": "One line per field, with what it contributes to the price", "items": { "$ref": "#/components/schemas/SubjectPartView" }, "type": "array" }, "payment_mode": { "description": "PREPAID or POSTPAID", "enum": [ "PREPAID", "POSTPAID" ], "type": "string" }, "rate": { "description": "METERED only: rate per active hour, micro-USD", "example": 1500, "format": "int64", "type": [ "integer", "null" ] }, "resource_id": { "description": "Upstream resource id, null for a subject bought through an order", "example": "1463106077196308568", "type": [ "string", "null" ] }, "resource_kind": { "description": "Kind of resource being billed", "enum": [ "SERVER", "IP_ADDRESS" ], "type": "string" }, "resource_name": { "description": "Name of the billed resource, retained even once the resource is gone", "example": "web-01", "type": "string" }, "spec": { "additionalProperties": {}, "description": "Every field the subject carries, keyed by field code: numbers, enum names and booleans", "example": { "cpu": 2, "disk": 30, "ram": 4096, "region": "NA_01" }, "type": "object" }, "state": { "description": "ACTIVE, SUSPENDED or TERMINATED", "enum": [ "ACTIVE", "SUSPENDED", "TERMINATED" ], "type": "string" }, "suspend_reason": { "description": "BILLING or OPERATIONAL while the subject is suspended", "enum": [ "BILLING", "OPERATIONAL" ], "type": [ "string", "null" ] }, "suspended_at": { "description": "Suspension time, null while the subject is not suspended", "format": "date-time", "type": [ "string", "null" ] }, "terminated_at": { "description": "Termination time, null until the subject is terminated", "format": "date-time", "type": [ "string", "null" ] }, "user": { "$ref": "#/components/schemas/UserSimple", "description": "User the account bills for" }, "workspace": { "anyOf": [ { "$ref": "#/components/schemas/WorkspaceSimple" }, { "type": "null" } ], "description": "Workspace the subject belongs to" } }, "required": [ "account_id", "anchor_day", "base_price", "charge_basis", "created_at", "current_period_end", "current_period_start", "cycle_count", "cycle_price", "cycle_unit", "external_ref", "id", "last_tick_at", "package_code", "paid_through_at", "parts", "payment_mode", "rate", "resource_id", "resource_kind", "resource_name", "spec", "state", "suspend_reason", "suspended_at", "terminated_at", "user", "workspace" ], "type": "object" }, "SubjectPartView": { "description": "One field of a subject, with its priced contribution.", "properties": { "amount": { "description": "This part's contribution to the charge, micro-USD; 0 when bundled", "example": 10000000, "format": "int64", "type": "integer" }, "id": { "description": "Subject part id", "example": "1456074443980800000", "type": "string" }, "part_code": { "description": "Field code", "example": "ram", "type": "string" }, "quantity": { "description": "Value of a numeric field", "example": 6, "format": "int64", "type": [ "integer", "null" ] }, "rate_card_id": { "description": "Rate card that priced this part, for audit", "example": "1456074443980800000", "type": [ "string", "null" ] }, "subject_id": { "description": "Subject this part belongs to", "example": "1456074443980800000", "type": "string" }, "unit_price": { "description": "Monthly rate snapshot, micro-USD; 0 when bundled into the subject base price", "example": 5000000, "format": "int64", "type": "integer" }, "value": { "description": "Value of an enum or boolean field", "example": "LOCAL", "type": [ "string", "null" ] } }, "required": [ "amount", "id", "part_code", "quantity", "rate_card_id", "subject_id", "unit_price", "value" ], "type": "object" }, "SubjectTransitionResponse": { "description": "A move the subject's package offers, priced for this subject.", "properties": { "created_at": { "description": "Creation time", "format": "date-time", "type": "string" }, "direction": { "description": "UPGRADE or DOWNGRADE", "enum": [ "UPGRADE", "DOWNGRADE" ], "example": "UPGRADE", "type": "string" }, "eligible": { "description": "Whether an upgrade order for this move, with no field changes, would be accepted now", "type": "boolean" }, "id": { "description": "Transition id", "example": "1456074443980800000", "type": "string" }, "new_price": { "description": "Price after the move with the subject's current values kept in the target's open fields, micro-USD: per cycle for FIXED, per active hour for METERED; null when not eligible", "example": 18000000, "format": "int64", "type": [ "integer", "null" ] }, "prorated_delta": { "description": "Amount that a move now settles for the rest of the paid cycle, micro-USD: positive is charged, negative is refunded to the wallet. 0 unless the subject is FIXED PREPAID; null when not eligible", "example": 6000000, "format": "int64", "type": [ "integer", "null" ] }, "reason": { "description": "Why the move is refused, the same message the upgrade order returns; null when eligible", "example": "field disk may only grow, not shrink from 120", "type": [ "string", "null" ] }, "target": { "$ref": "#/components/schemas/PackageDetailResponse", "description": "The package the move goes to, in the same shape as a package list item" } }, "required": [ "created_at", "direction", "eligible", "id", "new_price", "prorated_delta", "reason", "target" ], "type": "object" }, "SubjectUsageResponse": { "description": "A metered subject with the usage it accrued over the requested window.", "properties": { "account_id": { "description": "Account billed for this subject", "example": "1456074443980800000", "type": "string" }, "anchor_day": { "description": "FIXED only: day of the month the cycle renews on, or the last day of a shorter month", "example": 15, "format": "int32", "maximum": 31, "minimum": 1, "type": [ "integer", "null" ] }, "base_price": { "description": "Base price per cycle of the package, micro-USD", "example": 6000000, "format": "int64", "type": "integer" }, "charge_basis": { "description": "FIXED (exact price per calendar cycle) or METERED (rate times active time)", "enum": [ "FIXED", "METERED" ], "type": "string" }, "created_at": { "description": "Creation time of the subject", "format": "date-time", "type": "string" }, "current_period_end": { "description": "End of the current billing cycle", "format": "date-time", "type": [ "string", "null" ] }, "current_period_start": { "description": "Start of the current billing cycle", "format": "date-time", "type": [ "string", "null" ] }, "cycle_count": { "description": "FIXED only: number of cycle units per billing period", "example": 1, "format": "int32", "type": [ "integer", "null" ] }, "cycle_price": { "description": "FIXED only: amount charged per cycle, micro-USD", "example": 12500000, "format": "int64", "type": [ "integer", "null" ] }, "cycle_unit": { "description": "FIXED only: calendar cycle unit, MONTH or YEAR", "example": "MONTH", "type": [ "string", "null" ] }, "external_ref": { "description": "External collector reference, null when billing owns the meter", "type": [ "string", "null" ] }, "id": { "description": "Billing subject id", "example": "1456074443980800000", "type": "string" }, "last_tick_at": { "description": "Time of the most recent metered accrual", "format": "date-time", "type": [ "string", "null" ] }, "package_code": { "description": "SKU of the package the subject is on, null when it was not bought from the catalog", "example": "lightning-1g", "type": [ "string", "null" ] }, "paid_through_at": { "description": "Fixed-prepaid subjects: the time coverage is paid up to", "format": "date-time", "type": [ "string", "null" ] }, "payment_mode": { "description": "PREPAID or POSTPAID", "enum": [ "PREPAID", "POSTPAID" ], "type": "string" }, "rate": { "description": "METERED only: rate per active hour, micro-USD", "example": 1500, "format": "int64", "type": [ "integer", "null" ] }, "resource_id": { "description": "Upstream resource id, null for a subject bought through an order", "example": "1463106077196308568", "type": [ "string", "null" ] }, "resource_kind": { "description": "Kind of resource being billed", "enum": [ "SERVER", "IP_ADDRESS" ], "type": "string" }, "resource_name": { "description": "Name of the billed resource, retained even once the resource is gone", "example": "web-01", "type": "string" }, "state": { "description": "ACTIVE, SUSPENDED or TERMINATED", "enum": [ "ACTIVE", "SUSPENDED", "TERMINATED" ], "type": "string" }, "suspend_reason": { "description": "BILLING or OPERATIONAL while the subject is suspended", "enum": [ "BILLING", "OPERATIONAL" ], "type": [ "string", "null" ] }, "suspended_at": { "description": "Suspension time, null while the subject is not suspended", "format": "date-time", "type": [ "string", "null" ] }, "terminated_at": { "description": "Termination time, null until the subject is terminated", "format": "date-time", "type": [ "string", "null" ] }, "usage_amount": { "description": "Charge accrued in the window, micro-USD", "example": 36000, "format": "int64", "type": "integer" }, "usage_from": { "description": "Start of the window, inclusive", "format": "date-time", "type": "string" }, "usage_minutes": { "description": "Metered minutes accrued in the window", "example": 1440, "format": "int64", "type": "integer" }, "usage_to": { "description": "End of the window, exclusive", "format": "date-time", "type": "string" }, "user": { "$ref": "#/components/schemas/UserSimple", "description": "User the account bills for" }, "workspace": { "anyOf": [ { "$ref": "#/components/schemas/WorkspaceSimple" }, { "type": "null" } ], "description": "Workspace the subject belongs to" } }, "required": [ "account_id", "anchor_day", "base_price", "charge_basis", "created_at", "current_period_end", "current_period_start", "cycle_count", "cycle_price", "cycle_unit", "external_ref", "id", "last_tick_at", "package_code", "paid_through_at", "payment_mode", "rate", "resource_id", "resource_kind", "resource_name", "state", "suspend_reason", "suspended_at", "terminated_at", "usage_amount", "usage_from", "usage_minutes", "usage_to", "user", "workspace" ], "type": "object" }, "SubjectView": { "description": "A billable resource together with its billing terms and current state.", "properties": { "account_id": { "description": "Account billed for this subject", "example": "1456074443980800000", "type": "string" }, "anchor_day": { "description": "FIXED only: day of the month the cycle renews on, or the last day of a shorter month", "example": 15, "format": "int32", "maximum": 31, "minimum": 1, "type": [ "integer", "null" ] }, "base_price": { "description": "Base price per cycle of the package, micro-USD", "example": 6000000, "format": "int64", "type": "integer" }, "charge_basis": { "description": "FIXED (exact price per calendar cycle) or METERED (rate times active time)", "enum": [ "FIXED", "METERED" ], "type": "string" }, "created_at": { "description": "Creation time of the subject", "format": "date-time", "type": "string" }, "current_period_end": { "description": "End of the current billing cycle", "format": "date-time", "type": [ "string", "null" ] }, "current_period_start": { "description": "Start of the current billing cycle", "format": "date-time", "type": [ "string", "null" ] }, "cycle_count": { "description": "FIXED only: number of cycle units per billing period", "example": 1, "format": "int32", "type": [ "integer", "null" ] }, "cycle_price": { "description": "FIXED only: amount charged per cycle, micro-USD", "example": 12500000, "format": "int64", "type": [ "integer", "null" ] }, "cycle_unit": { "description": "FIXED only: calendar cycle unit, MONTH or YEAR", "example": "MONTH", "type": [ "string", "null" ] }, "external_ref": { "description": "External collector reference, null when billing owns the meter", "type": [ "string", "null" ] }, "id": { "description": "Billing subject id", "example": "1456074443980800000", "type": "string" }, "last_tick_at": { "description": "Time of the most recent metered accrual", "format": "date-time", "type": [ "string", "null" ] }, "package_code": { "description": "SKU of the package the subject is on, null when it was not bought from the catalog", "example": "lightning-1g", "type": [ "string", "null" ] }, "paid_through_at": { "description": "Fixed-prepaid subjects: the time coverage is paid up to", "format": "date-time", "type": [ "string", "null" ] }, "payment_mode": { "description": "PREPAID or POSTPAID", "enum": [ "PREPAID", "POSTPAID" ], "type": "string" }, "rate": { "description": "METERED only: rate per active hour, micro-USD", "example": 1500, "format": "int64", "type": [ "integer", "null" ] }, "resource_id": { "description": "Upstream resource id, null for a subject bought through an order", "example": "1463106077196308568", "type": [ "string", "null" ] }, "resource_kind": { "description": "Kind of resource being billed", "enum": [ "SERVER", "IP_ADDRESS" ], "type": "string" }, "resource_name": { "description": "Name of the billed resource, retained even once the resource is gone", "example": "web-01", "type": "string" }, "state": { "description": "ACTIVE, SUSPENDED or TERMINATED", "enum": [ "ACTIVE", "SUSPENDED", "TERMINATED" ], "type": "string" }, "suspend_reason": { "description": "BILLING or OPERATIONAL while the subject is suspended", "enum": [ "BILLING", "OPERATIONAL" ], "type": [ "string", "null" ] }, "suspended_at": { "description": "Suspension time, null while the subject is not suspended", "format": "date-time", "type": [ "string", "null" ] }, "terminated_at": { "description": "Termination time, null until the subject is terminated", "format": "date-time", "type": [ "string", "null" ] }, "user": { "$ref": "#/components/schemas/UserSimple", "description": "User the account bills for" }, "workspace": { "anyOf": [ { "$ref": "#/components/schemas/WorkspaceSimple" }, { "type": "null" } ], "description": "Workspace the subject belongs to" } }, "required": [ "account_id", "anchor_day", "base_price", "charge_basis", "created_at", "current_period_end", "current_period_start", "cycle_count", "cycle_price", "cycle_unit", "external_ref", "id", "last_tick_at", "package_code", "paid_through_at", "payment_mode", "rate", "resource_id", "resource_kind", "resource_name", "state", "suspend_reason", "suspended_at", "terminated_at", "user", "workspace" ], "type": "object" }, "TopUpCommand": { "description": "A top-up charged to the account's default stored payment method: on success it funds the wallet with a TOPUP lot, settling a tied invoice or issuing a TOPUP receipt.", "properties": { "amount": { "description": "Amount to charge, micro-USD, between $20 and $500", "example": 25000000, "format": "int64", "maximum": 500000000, "minimum": 20000000, "type": "integer" }, "idempotency_key": { "description": "Key that makes a replay return the existing payment rather than charging again", "example": "topup-1042-2026-08-13-a1b2", "type": [ "string", "null" ] }, "invoice_id": { "description": "Invoice this top-up settles, if any; null issues a TOPUP receipt instead", "example": "1456074443980800000", "type": [ "string", "null" ] } }, "required": [ "amount" ], "type": "object" }, "UsageRecordView": { "description": "Metered usage for a billing subject over a single period, and the charge it produced.", "properties": { "account_id": { "description": "Account billed for the usage", "example": "1456074443980800000", "type": "string" }, "amount": { "description": "Charge for the metered minutes, micro-USD", "example": 1500, "format": "int64", "type": "integer" }, "created_at": { "description": "Creation time of the usage record", "format": "date-time", "type": "string" }, "id": { "description": "Usage record id", "example": "1456074443980800000", "type": "string" }, "invoice_id": { "description": "Invoice this usage is rolled up into, null until it is invoiced", "example": "1456074443980800000", "type": [ "string", "null" ] }, "ledger_entry_id": { "description": "Ledger entry this usage is settled under, null until it is settled", "example": "1456074443980800000", "type": [ "string", "null" ] }, "minutes": { "description": "Metered minutes in the period", "example": 60, "format": "int64", "type": "integer" }, "period_end": { "description": "End of the metered period", "format": "date-time", "type": "string" }, "period_start": { "description": "Start of the metered period", "format": "date-time", "type": "string" }, "rate": { "description": "Rate applied to the period, micro-USD per active hour", "example": 1500, "format": "int64", "type": "integer" }, "subject_id": { "description": "Billing subject the usage is metered for", "example": "1456074443980800000", "type": "string" } }, "required": [ "account_id", "amount", "created_at", "id", "invoice_id", "ledger_entry_id", "minutes", "period_end", "period_start", "rate", "subject_id" ], "type": "object" }, "WalletView": { "description": "An account's prepaid balance, credited by top-ups and drawn down by charges.", "properties": { "account_id": { "description": "Account this wallet belongs to", "example": "1456074443980800000", "type": "string" }, "balance": { "description": "Current balance, micro-USD; negative when the account is overdrawn", "example": 12500000, "format": "int64", "type": "integer" }, "currency": { "description": "ISO currency code of the balance", "example": "USD", "type": "string" }, "id": { "description": "Wallet id", "example": "1456074443980800000", "type": "string" }, "unbilled_usage": { "description": "Metered usage already drawn from the balance but not yet posted as a USAGE_CHARGE movement, micro-USD. The balance is authoritative", "example": 4304, "format": "int64", "type": "integer" }, "updated_at": { "description": "When the balance last changed", "format": "date-time", "type": "string" }, "user": { "$ref": "#/components/schemas/UserSimple", "description": "User the account bills for" } }, "required": [ "account_id", "balance", "currency", "id", "unbilled_usage", "updated_at", "user" ], "type": "object" }, "WebhookResponse": { "description": "The outcome of ingesting a gateway webhook.", "properties": { "event_id": { "description": "Recorded event id", "example": "1456074443980800000", "type": "string" }, "event_ref": { "description": "Gateway event reference", "example": "evt_1QxYz123", "type": "string" }, "gateway": { "description": "Originating gateway", "enum": [ "STRIPE", "PAYPAL", "MANUAL" ], "example": "STRIPE", "type": "string" }, "payment_id": { "description": "Payment this event reconciled, if any", "example": "1456074443980800000", "type": [ "string", "null" ] }, "status": { "description": "RECEIVED when the event is accepted for processing, IGNORED when it repeats one already accepted or carries nothing to act on", "enum": [ "RECEIVED", "PROCESSED", "IGNORED", "FAILED" ], "type": "string" }, "type": { "description": "Normalized event type", "example": "payment.succeeded", "type": "string" } }, "required": [ "event_id", "event_ref", "gateway", "payment_id", "status", "type" ], "type": "object" }, "DediboxIpListView": { "description": "Dedibox IP list item", "properties": { "address": { "description": "IP address", "type": "string" }, "dedibox": { "$ref": "#/components/schemas/DediboxSimple", "description": "Dedibox this IP belongs to" }, "id": { "description": "Dedibox IP ID", "example": "1464201868476432440", "type": "string" }, "type": { "description": "IP version type", "enum": [ "IPv4", "IPv6" ], "type": "string" } }, "required": [ "address", "dedibox", "id", "type" ], "type": "object" }, "DediboxSimple": { "description": "Dedibox reference", "properties": { "id": { "description": "Dedibox ID", "example": "1326819038986244108", "type": "string" }, "name": { "description": "Name of this dedibox", "example": "dedi-fra-01", "type": "string" } }, "required": [ "id", "name" ], "type": "object" }, "KeysetResultDediboxIpListView": { "properties": { "after": { "type": [ "string", "null" ] }, "before": { "type": [ "string", "null" ] }, "has_next": { "type": "boolean" }, "has_previous": { "type": "boolean" }, "items": { "items": { "$ref": "#/components/schemas/DediboxIpListView" }, "type": "array" }, "limit": { "description": "Limit of items returned per page", "format": "int32", "maximum": 100, "minimum": 1, "type": "integer" }, "page": { "description": "Page number", "format": "int32", "maximum": 1000, "minimum": 1, "type": "integer" }, "total": { "description": "Total number of matching items", "format": "int64", "minimum": 0, "type": "integer" } }, "required": [ "after", "before", "has_next", "has_previous", "items", "limit", "page", "total" ], "type": "object" }, "KeysetResultInstanceSimple": { "properties": { "after": { "type": [ "string", "null" ] }, "before": { "type": [ "string", "null" ] }, "has_next": { "type": "boolean" }, "has_previous": { "type": "boolean" }, "items": { "items": { "$ref": "#/components/schemas/InstanceSimple" }, "type": "array" }, "limit": { "description": "Limit of items returned per page", "format": "int32", "maximum": 100, "minimum": 1, "type": "integer" }, "page": { "description": "Page number", "format": "int32", "maximum": 1000, "minimum": 1, "type": "integer" }, "total": { "description": "Total number of matching items", "format": "int64", "minimum": 0, "type": "integer" } }, "required": [ "after", "before", "has_next", "has_previous", "items", "limit", "page", "total" ], "type": "object" }, "KeysetResultNetBalancerListView": { "properties": { "after": { "type": [ "string", "null" ] }, "before": { "type": [ "string", "null" ] }, "has_next": { "type": "boolean" }, "has_previous": { "type": "boolean" }, "items": { "items": { "$ref": "#/components/schemas/NetBalancerListView" }, "type": "array" }, "limit": { "description": "Limit of items returned per page", "format": "int32", "maximum": 100, "minimum": 1, "type": "integer" }, "page": { "description": "Page number", "format": "int32", "maximum": 1000, "minimum": 1, "type": "integer" }, "total": { "description": "Total number of matching items", "format": "int64", "minimum": 0, "type": "integer" } }, "required": [ "after", "before", "has_next", "has_previous", "items", "limit", "page", "total" ], "type": "object" }, "NetBalancerDetailView": { "description": "Network load balancer detail", "properties": { "address": { "description": "IP address of this balancer. Each attached instance must hold this address itself, for example on its loopback interface, to answer traffic sent to it", "type": "string" }, "id": { "description": "Load balancer ID", "example": "1467950980661264556", "type": "string" }, "name": { "description": "Name of this load balancer", "example": "lb-public", "type": "string" }, "owner": { "anyOf": [ { "$ref": "#/components/schemas/WorkspaceSimple" }, { "type": "null" } ], "description": "Workspace that owns this load balancer (null when it is not assigned to one)" } }, "required": [ "address", "id", "name", "owner" ], "type": "object" }, "NetBalancerListView": { "description": "Network load balancer list item", "properties": { "address": { "description": "IP address of this balancer. Each attached instance must hold this address itself, for example on its loopback interface, to answer traffic sent to it", "type": "string" }, "id": { "description": "Load balancer ID", "example": "1467950980661264556", "type": "string" }, "name": { "description": "Name of this load balancer", "example": "lb-public", "type": "string" }, "owner": { "anyOf": [ { "$ref": "#/components/schemas/WorkspaceSimple" }, { "type": "null" } ], "description": "Workspace that owns this load balancer (null when it is not assigned to one)" } }, "required": [ "address", "id", "name", "owner" ], "type": "object" }, "PatchNetBalancerRequest": { "properties": { "address": { "description": "IPv4 address in CIDR notation", "type": "string" }, "name": { "description": "Display name of the load balancer", "example": "lb-public", "maxLength": 32, "minLength": 4, "type": "string" }, "owner": { "description": "Workspace that owns this load balancer", "example": "1405508720263180365", "type": "string" } }, "type": "object" }, "AttachInformation": { "properties": { "ip": { "description": "IP address", "example": "1464201868476432440", "type": [ "string", "null" ] }, "message": { "description": "Message describing operation result", "type": [ "string", "null" ] }, "operation": { "description": "Operation performed", "enum": [ "IGNORED", "FOUND_EXISTING", "ATTACHED_EXISTING", "NO_AVAILABLE", "ATTACHED_NEW", "FAILED" ], "type": "string" } }, "required": [ "ip", "message", "operation" ], "type": "object" }, "AttachIpRequest": { "properties": { "instance": { "description": "Instance ID", "example": "1463106077196308568", "type": "string" }, "ip": { "description": "FloatingIP ID", "example": "1464201868476432440", "type": "string" } }, "required": [ "instance", "ip" ], "type": "object" }, "AttachResult": { "properties": { "v4": { "$ref": "#/components/schemas/AttachInformation", "description": "IPv4 result" }, "v6": { "$ref": "#/components/schemas/AttachInformation", "description": "IPv6 result" } }, "required": [ "v4", "v6" ], "type": "object" }, "AutoAttachOptions": { "properties": { "filtered": { "description": "Use filtered IPs", "type": "boolean" } }, "required": [ "filtered" ], "type": "object" }, "DetachIpRequest": { "properties": { "ip": { "description": "FloatingIP ID", "example": "1464201868476432440", "type": "string" } }, "required": [ "ip" ], "type": "object" }, "EditRdnsRequest": { "properties": { "dns": { "description": "Reverse dns data; null or blank clears the entry", "type": [ "string", "null" ] } }, "type": "object" }, "FirewallAction": { "description": "What happens to traffic a rule matches.\n\n`ACCEPT` admits the traffic, and replies to the connections it admits are allowed back automatically.\n\n`STATELESS` admits the traffic without tracking connections. Replies are not allowed back automatically, so the return direction needs a rule of its own.\n\n`DROP` discards the traffic.\n", "enum": [ "ACCEPT", "STATELESS", "DROP" ], "type": "string" }, "FirewallActionCounts": { "description": "Rule counts by action within one direction", "properties": { "accept": { "description": "Rules admitting traffic, with replies allowed back automatically", "format": "int64", "minimum": 0, "type": "integer" }, "drop": { "description": "Rules discarding traffic", "format": "int64", "minimum": 0, "type": "integer" }, "stateless": { "description": "Rules admitting traffic without tracking connections", "format": "int64", "minimum": 0, "type": "integer" } }, "required": [ "accept", "drop", "stateless" ], "type": "object" }, "FirewallAdmitRequest": { "description": "Firewall rule admitting traffic, optionally rate limited", "properties": { "action": { "$ref": "#/components/schemas/FirewallAction", "description": "Whether replies to the admitted connections are allowed back automatically" }, "bps_limit": { "description": "Rate limit in bits per second applied to the traffic this rule admits", "example": 1000000000, "format": "int64", "maximum": 10000000000, "minimum": 1, "type": [ "integer", "null" ] }, "description": { "description": "Optional description for the rule", "type": [ "string", "null" ] }, "direction": { "$ref": "#/components/schemas/FirewallDirection", "description": "Traffic direction" }, "local_cidr": { "description": "Local address CIDR", "example": "192.0.2.0/24", "format": "CIDR", "type": [ "string", "null" ] }, "local_port_end": { "description": "Ending port on the instance's own side, defaults to the start (TCP/UDP only)", "format": "int32", "maximum": 65535, "minimum": 1, "type": [ "integer", "null" ] }, "local_port_start": { "description": "Starting port on the instance's own side (TCP/UDP only)", "format": "int32", "maximum": 65535, "minimum": 1, "type": [ "integer", "null" ] }, "priority": { "description": "Rule priority, higher evaluates first", "format": "int32", "maximum": 1000, "minimum": 0, "type": [ "integer", "null" ] }, "protocol": { "$ref": "#/components/schemas/Protocol", "description": "Network protocol" }, "remote_cidr": { "description": "Remote address CIDR", "example": "192.0.2.0/24", "format": "CIDR", "type": [ "string", "null" ] }, "remote_port_end": { "description": "Ending port on the peer's side, defaults to the start (TCP/UDP only)", "format": "int32", "maximum": 65535, "minimum": 1, "type": [ "integer", "null" ] }, "remote_port_start": { "description": "Starting port on the peer's side (TCP/UDP only)", "format": "int32", "maximum": 65535, "minimum": 1, "type": [ "integer", "null" ] }, "type": { "$ref": "#/components/schemas/IpFamily", "description": "IP version" } }, "required": [ "action", "direction", "protocol", "type" ], "type": "object" }, "FirewallDefaultsRequest": { "description": "Policies applied to traffic matching no rule", "properties": { "inbound": { "anyOf": [ { "$ref": "#/components/schemas/FirewallPolicy" }, { "type": "null" } ], "description": "Policy for inbound traffic matching no rule" }, "outbound": { "anyOf": [ { "$ref": "#/components/schemas/FirewallPolicy" }, { "type": "null" } ], "description": "Policy for outbound traffic matching no rule" } }, "type": "object" }, "FirewallDirection": { "enum": [ "INBOUND", "OUTBOUND" ], "type": "string" }, "FirewallDropRequest": { "description": "Firewall rule discarding traffic", "properties": { "action": { "$ref": "#/components/schemas/FirewallAction", "description": "Discards the traffic" }, "description": { "description": "Optional description for the rule", "type": [ "string", "null" ] }, "direction": { "$ref": "#/components/schemas/FirewallDirection", "description": "Traffic direction" }, "local_cidr": { "description": "Local address CIDR", "example": "192.0.2.0/24", "format": "CIDR", "type": [ "string", "null" ] }, "local_port_end": { "description": "Ending port on the instance's own side, defaults to the start (TCP/UDP only)", "format": "int32", "maximum": 65535, "minimum": 1, "type": [ "integer", "null" ] }, "local_port_start": { "description": "Starting port on the instance's own side (TCP/UDP only)", "format": "int32", "maximum": 65535, "minimum": 1, "type": [ "integer", "null" ] }, "priority": { "description": "Rule priority, higher evaluates first", "format": "int32", "maximum": 1000, "minimum": 0, "type": [ "integer", "null" ] }, "protocol": { "$ref": "#/components/schemas/Protocol", "description": "Network protocol" }, "remote_cidr": { "description": "Remote address CIDR", "example": "192.0.2.0/24", "format": "CIDR", "type": [ "string", "null" ] }, "remote_port_end": { "description": "Ending port on the peer's side, defaults to the start (TCP/UDP only)", "format": "int32", "maximum": 65535, "minimum": 1, "type": [ "integer", "null" ] }, "remote_port_start": { "description": "Starting port on the peer's side (TCP/UDP only)", "format": "int32", "maximum": 65535, "minimum": 1, "type": [ "integer", "null" ] }, "type": { "$ref": "#/components/schemas/IpFamily", "description": "IP version" } }, "required": [ "action", "direction", "protocol", "type" ], "type": "object" }, "FirewallPatchRequest": { "properties": { "defaults": { "$ref": "#/components/schemas/FirewallDefaultsRequest", "description": "Default policy per direction" }, "rules": { "description": "Replaces every rule on this instance when supplied", "items": { "$ref": "#/components/schemas/FirewallRuleRequest" }, "type": "array" } }, "type": "object" }, "FirewallPolicy": { "description": "What happens to traffic in a direction that matches no rule.\n\n`ACCEPT` admits the traffic, and replies to the connections it admits are allowed back automatically.\n\n`DROP` discards the traffic.\n\nThere is no stateless default: applying one to a whole direction would leave the instance unable to receive replies to the connections it opens.\n", "enum": [ "ACCEPT", "DROP" ], "type": "string" }, "FirewallRuleCounts": { "description": "Rule counts by direction and action", "properties": { "inbound": { "$ref": "#/components/schemas/FirewallActionCounts", "description": "Rules applying to traffic reaching the instance" }, "outbound": { "$ref": "#/components/schemas/FirewallActionCounts", "description": "Rules applying to traffic leaving the instance" }, "total": { "description": "Rules on this instance in total", "format": "int64", "minimum": 0, "type": "integer" } }, "required": [ "inbound", "outbound", "total" ], "type": "object" }, "FirewallRuleListView": { "description": "Firewall rule list item", "properties": { "action": { "$ref": "#/components/schemas/FirewallAction", "description": "Firewall action" }, "bps_limit": { "description": "Rate limit in bits per second applied to the traffic this rule admits", "example": 1000000000, "format": "int64", "maximum": 10000000000, "minimum": 1, "type": [ "integer", "null" ] }, "description": { "description": "Optional description for the rule", "type": [ "string", "null" ] }, "direction": { "$ref": "#/components/schemas/FirewallDirection", "description": "Traffic direction this rule applies to" }, "id": { "description": "Firewall rule ID", "example": "1467950980661264556", "type": "string" }, "instance": { "$ref": "#/components/schemas/InstanceSimple", "description": "Instance this rule applies to" }, "local_cidr": { "description": "Local address CIDR", "type": [ "string", "null" ] }, "local_port_end": { "description": "Ending port on the instance's own side (TCP/UDP only)", "format": "int32", "maximum": 65535, "minimum": 1, "type": [ "integer", "null" ] }, "local_port_start": { "description": "Starting port on the instance's own side (TCP/UDP only)", "format": "int32", "maximum": 65535, "minimum": 1, "type": [ "integer", "null" ] }, "priority": { "description": "Rule priority, higher numbers execute first", "format": "int32", "maximum": 1000, "minimum": 0, "type": "integer" }, "protocol": { "$ref": "#/components/schemas/Protocol", "description": "Network protocol" }, "remote_cidr": { "description": "Remote address CIDR", "type": "string" }, "remote_port_end": { "description": "Ending port on the peer's side (TCP/UDP only)", "format": "int32", "maximum": 65535, "minimum": 1, "type": [ "integer", "null" ] }, "remote_port_start": { "description": "Starting port on the peer's side (TCP/UDP only)", "format": "int32", "maximum": 65535, "minimum": 1, "type": [ "integer", "null" ] }, "type": { "description": "IP rule version", "enum": [ "IPv4", "IPv6" ], "type": "string" } }, "required": [ "action", "bps_limit", "description", "direction", "id", "instance", "local_cidr", "local_port_end", "local_port_start", "priority", "protocol", "remote_cidr", "remote_port_end", "remote_port_start", "type" ], "type": "object" }, "FirewallRuleRequest": { "description": "Firewall rule", "discriminator": { "mapping": { "ACCEPT": "#/components/schemas/FirewallAdmitRequest", "DROP": "#/components/schemas/FirewallDropRequest", "STATELESS": "#/components/schemas/FirewallAdmitRequest" }, "propertyName": "action" }, "oneOf": [ { "$ref": "#/components/schemas/FirewallAdmitRequest" }, { "$ref": "#/components/schemas/FirewallDropRequest" } ], "properties": { "action": { "type": "string" } }, "required": [ "action" ] }, "FloatingIpListView": { "description": "Floating IP list item", "properties": { "address": { "description": "IP address", "type": "string" }, "dns": { "description": "DNS reverse record", "type": [ "string", "null" ] }, "id": { "description": "Floating IP ID", "example": "1464201868476432440", "type": "string" }, "instance": { "anyOf": [ { "$ref": "#/components/schemas/InstanceSimple" }, { "type": "null" } ], "description": "Instance this floating IP is assigned to" }, "locked": { "description": "If this floating IP is locked", "type": "boolean" }, "owner": { "anyOf": [ { "$ref": "#/components/schemas/WorkspaceSimple" }, { "type": "null" } ], "description": "Workspace that owns this floating IP" }, "pending_protection": { "description": "DDoS protection the IP moves to, on a new address, when its instance next restarts or applies pending upgrades; null when no change is pending", "example": true, "type": [ "boolean", "null" ] }, "range": { "$ref": "#/components/schemas/IpRangeSimple", "description": "IP range this address belongs to" }, "subject": { "description": "Billing subject this IP is billed under, or null when it is not billed", "example": "1456074443980800000", "type": [ "string", "null" ] } }, "required": [ "address", "dns", "id", "instance", "locked", "owner", "pending_protection", "range", "subject" ], "type": "object" }, "InstanceFirewallRef": { "description": "Policies applied to traffic matching no firewall rule.", "properties": { "inbound": { "$ref": "#/components/schemas/FirewallPolicy", "description": "Policy for inbound traffic matching no rule" }, "outbound": { "$ref": "#/components/schemas/FirewallPolicy", "description": "Policy for outbound traffic matching no rule" } }, "required": [ "inbound", "outbound" ], "type": "object" }, "InstanceFirewallView": { "description": "Firewall posture of one instance", "properties": { "defaults": { "$ref": "#/components/schemas/InstanceFirewallRef", "description": "Policies applied to traffic matching no firewall rule" }, "instance": { "$ref": "#/components/schemas/InstanceSimple", "description": "Instance this posture belongs to" }, "rules": { "$ref": "#/components/schemas/FirewallRuleCounts", "description": "Rule counts by direction and action" } }, "required": [ "defaults", "instance", "rules" ], "type": "object" }, "IpFlags": { "enum": [ "PROTECTED" ], "type": "string" }, "IpRangeSimple": { "description": "IP range reference", "properties": { "flags": { "description": "IP range flags", "items": { "$ref": "#/components/schemas/IpFlags" }, "type": "array", "uniqueItems": true }, "id": { "description": "IP range ID", "example": "1464201868476432440", "type": "string" }, "region": { "description": "Region of this IP range", "enum": [ "NA_01" ], "type": "string" }, "type": { "description": "IP version type", "enum": [ "IPv4", "IPv6" ], "type": "string" } }, "required": [ "flags", "id", "region", "type" ], "type": "object" }, "KeysetResultFirewallRuleListView": { "properties": { "after": { "type": [ "string", "null" ] }, "before": { "type": [ "string", "null" ] }, "has_next": { "type": "boolean" }, "has_previous": { "type": "boolean" }, "items": { "items": { "$ref": "#/components/schemas/FirewallRuleListView" }, "type": "array" }, "limit": { "description": "Limit of items returned per page", "format": "int32", "maximum": 100, "minimum": 1, "type": "integer" }, "page": { "description": "Page number", "format": "int32", "maximum": 1000, "minimum": 1, "type": "integer" }, "total": { "description": "Total number of matching items", "format": "int64", "minimum": 0, "type": "integer" } }, "required": [ "after", "before", "has_next", "has_previous", "items", "limit", "page", "total" ], "type": "object" }, "KeysetResultFloatingIpListView": { "properties": { "after": { "type": [ "string", "null" ] }, "before": { "type": [ "string", "null" ] }, "has_next": { "type": "boolean" }, "has_previous": { "type": "boolean" }, "items": { "items": { "$ref": "#/components/schemas/FloatingIpListView" }, "type": "array" }, "limit": { "description": "Limit of items returned per page", "format": "int32", "maximum": 100, "minimum": 1, "type": "integer" }, "page": { "description": "Page number", "format": "int32", "maximum": 1000, "minimum": 1, "type": "integer" }, "total": { "description": "Total number of matching items", "format": "int64", "minimum": 0, "type": "integer" } }, "required": [ "after", "before", "has_next", "has_previous", "items", "limit", "page", "total" ], "type": "object" }, "KeysetResultInstanceFirewallView": { "properties": { "after": { "type": [ "string", "null" ] }, "before": { "type": [ "string", "null" ] }, "has_next": { "type": "boolean" }, "has_previous": { "type": "boolean" }, "items": { "items": { "$ref": "#/components/schemas/InstanceFirewallView" }, "type": "array" }, "limit": { "description": "Limit of items returned per page", "format": "int32", "maximum": 100, "minimum": 1, "type": "integer" }, "page": { "description": "Page number", "format": "int32", "maximum": 1000, "minimum": 1, "type": "integer" }, "total": { "description": "Total number of matching items", "format": "int64", "minimum": 0, "type": "integer" } }, "required": [ "after", "before", "has_next", "has_previous", "items", "limit", "page", "total" ], "type": "object" }, "NetworkAutoAttachRequest": { "properties": { "instance": { "description": "Instance ID", "example": "1463106077196308568", "type": "string" }, "skip_duplicate": { "description": "Skip operation if instance already has a matching IP", "type": "boolean" }, "v4": { "anyOf": [ { "$ref": "#/components/schemas/AutoAttachOptions" }, { "type": "null" } ], "description": "IPv4 options" }, "v6": { "anyOf": [ { "$ref": "#/components/schemas/AutoAttachOptions" }, { "type": "null" } ], "description": "IPv6 options" } }, "required": [ "instance", "skip_duplicate" ], "type": "object" }, "Protocol": { "enum": [ "TCP", "UDP", "ICMP", "ALL" ], "type": "string" }, "ReinstallRecommendedFirewallRequest": { "properties": { "instance": { "description": "Instance ID", "example": "1463106077196308568", "type": "string" } }, "required": [ "instance" ], "type": "object" }, "WorkflowWithDataAttachResult": { "properties": { "data": { "$ref": "#/components/schemas/AttachResult", "description": "Data returned along with the workflow" }, "workflow": { "$ref": "#/components/schemas/WorkflowData", "description": "Workflow information" } }, "required": [ "data", "workflow" ], "type": "object" }, "BatchResponse": { "properties": { "skipped": { "description": "Instances that were not accepted into the batch", "items": { "$ref": "#/components/schemas/SkippedInstance" }, "type": "array" }, "workflow": { "$ref": "#/components/schemas/WorkflowData", "description": "Workflow running the accepted instances" } }, "required": [ "skipped", "workflow" ], "type": "object" }, "SkippedInstance": { "properties": { "instance": { "description": "Instance ID", "example": "1463106077196308568", "type": "string" }, "reason": { "description": "Why the instance was not acted on", "example": "Instance is currently busy", "type": "string" } }, "required": [ "instance", "reason" ], "type": "object" }, "ApplyUpgradeRequest": { "properties": { "instance": { "description": "Instance ID", "example": "1463106077196308568", "type": "string" } }, "required": [ "instance" ], "type": "object" }, "AttachDiskRequest": { "properties": { "instance_id": { "description": "Instance to attach the disk to", "example": "1463106077196308568", "type": "string" } }, "required": [ "instance_id" ], "type": "object" }, "AttachIsoRequest": { "properties": { "instance": { "description": "Instance ID", "example": "1463106077196308568", "type": "string" }, "iso": { "description": "ISO ID", "example": "1471181001588760790", "type": "string" } }, "required": [ "instance", "iso" ], "type": "object" }, "BGPCommunity": { "enum": [ "DEFAULT", "PROTECTED" ], "type": "string" }, "BGPSource": { "enum": [ "MANUAL" ], "type": "string" }, "BackupSource": { "allOf": [ { "$ref": "#/components/schemas/ImageSource" }, { "properties": { "backup_id": { "description": "Backup image ID to promote", "example": "1471181001588760790", "type": "string" } }, "required": [ "backup_id" ], "type": "object" } ], "description": "Promote an existing backup into a new image", "required": [ "backup_id" ] }, "BatchPowerRequest": { "properties": { "action": { "$ref": "#/components/schemas/PowerAction", "description": "Power action" }, "instances": { "description": "Instance IDs", "items": { "example": "1463106077196308568", "type": "string" }, "type": "array" } }, "required": [ "action", "instances" ], "type": "object" }, "BatchTransferRequest": { "properties": { "instances": { "description": "Instance IDs", "items": { "example": "1463106077196308568", "type": "string" }, "type": "array" }, "workspace": { "description": "Workspace to move the instances to", "example": "1405508720263180365", "type": "string" } }, "required": [ "instances", "workspace" ], "type": "object" }, "BgpPrefixListView": { "description": "BGP prefix list item", "properties": { "community": { "$ref": "#/components/schemas/BGPCommunity", "description": "BGP community for this prefix" }, "enabled": { "description": "If announcements for this prefix are enabled", "type": "boolean" }, "id": { "description": "BGP prefix ID", "example": "1463882832936980610", "type": "string" }, "prefix": { "description": "Network prefix", "type": "string" }, "source": { "$ref": "#/components/schemas/BGPSource", "description": "Source of the prefix" } }, "required": [ "community", "enabled", "id", "prefix", "source" ], "type": "object" }, "BgpResponse": { "description": "BGP configuration", "properties": { "asn": { "description": "ASN registered to this workspace", "example": 64512, "format": "int64", "maximum": 4294967294, "minimum": 1, "type": "integer" }, "id": { "description": "BGP configuration ID", "example": "1506320201023500406", "type": "string" }, "instance": { "anyOf": [ { "$ref": "#/components/schemas/InstanceSimple" }, { "type": "null" } ], "description": "Instance designated as the BGP endpoint" }, "password": { "description": "BGP session password", "type": "string" } }, "required": [ "asn", "id", "instance", "password" ], "type": "object" }, "BootTarget": { "enum": [ "DISK", "ISO" ], "type": "string" }, "ChangeFirmwareRequest": { "properties": { "disk": { "$ref": "#/components/schemas/BootDiskAction", "description": "Whether to keep or erase the boot disk" }, "firmware": { "$ref": "#/components/schemas/Firmware", "description": "Firmware to switch to" }, "sector_size": { "description": "Sector size of the boot disk after a WIPE, in bytes: 512 or 4096. Defaults to 512 for BIOS and 4096 for UEFI and UEFI_SECURE. KEEP cannot change the sector size, and BIOS boots only 512 B sectors", "example": 4096, "format": "int32", "type": [ "integer", "null" ] } }, "required": [ "disk", "firmware" ], "type": "object" }, "CreateBackupRequest": { "allOf": [ { "$ref": "#/components/schemas/CreateImageRequest" }, { "properties": { "description": { "description": "Image description", "maxLength": 1000, "minLength": 4, "type": [ "string", "null" ] }, "group": { "description": "Catalog group used to bucket images (e.g. linux, windows)", "maxLength": 32, "minLength": 4, "type": [ "string", "null" ] }, "name": { "description": "Image name; one is generated when omitted", "example": "nightly-2026-07-28", "maxLength": 64, "minLength": 4, "type": [ "string", "null" ] }, "source": { "description": "Where the bytes come from", "oneOf": [ { "$ref": "#/components/schemas/BackupSource" }, { "$ref": "#/components/schemas/InstanceSource" }, { "$ref": "#/components/schemas/UploadSource" }, { "$ref": "#/components/schemas/UrlSource" } ], "discriminator": { "mapping": { "BACKUP": "#/components/schemas/BackupSource", "INSTANCE": "#/components/schemas/InstanceSource", "UPLOAD": "#/components/schemas/UploadSource", "URL": "#/components/schemas/UrlSource" }, "propertyName": "type" } } }, "required": [ "source" ], "type": "object" } ], "description": "Create a backup from an INSTANCE source", "required": [ "source" ] }, "CreateImageRequest": { "description": "Create an image (TEMPLATE, ISO or BACKUP)", "discriminator": { "mapping": { "BACKUP": "#/components/schemas/CreateBackupRequest", "ISO": "#/components/schemas/CreateIsoRequest", "TEMPLATE": "#/components/schemas/CreateTemplateRequest" }, "propertyName": "kind" }, "properties": { "kind": { "type": "string" } }, "required": [ "kind" ] }, "CreateIsoRequest": { "allOf": [ { "$ref": "#/components/schemas/CreateImageRequest" }, { "properties": { "description": { "description": "Image description", "maxLength": 1000, "minLength": 4, "type": [ "string", "null" ] }, "group": { "description": "Catalog group used to bucket images (e.g. linux, windows)", "maxLength": 32, "minLength": 4, "type": [ "string", "null" ] }, "name": { "description": "Image name", "example": "debian-13-netinst", "maxLength": 64, "minLength": 4, "type": "string" }, "os": { "anyOf": [ { "$ref": "#/components/schemas/OsRequest" }, { "type": "null" } ], "description": "Operating system metadata" }, "source": { "description": "Where the bytes come from", "oneOf": [ { "$ref": "#/components/schemas/BackupSource" }, { "$ref": "#/components/schemas/InstanceSource" }, { "$ref": "#/components/schemas/UploadSource" }, { "$ref": "#/components/schemas/UrlSource" } ], "discriminator": { "mapping": { "BACKUP": "#/components/schemas/BackupSource", "INSTANCE": "#/components/schemas/InstanceSource", "UPLOAD": "#/components/schemas/UploadSource", "URL": "#/components/schemas/UrlSource" }, "propertyName": "type" } } }, "required": [ "name", "source" ], "type": "object" } ], "description": "Create an ISO from an UPLOAD or URL source", "required": [ "name", "source" ] }, "CreateRecipeRequest": { "properties": { "category": { "description": "Category for the recipe", "enum": [ "DEFAULT", "GAMES", "SOFTWARE", "INFRASTRUCTURE", "AI", "MEDIA", "TOOLS", "DATABASES", "MONITORING", "PRODUCTIVITY", "DEVOPS", "AUTOMATION", "NETWORK" ], "type": "string" }, "commands": { "description": "List of commands to execute", "items": { "$ref": "#/components/schemas/RecipeCommandRequest" }, "type": "array" }, "description": { "description": "Description of the recipe", "maxLength": 4096, "minLength": 1, "type": [ "string", "null" ] }, "fields": { "description": "Fields for the recipe", "items": { "$ref": "#/components/schemas/RecipeFieldRequest" }, "type": "array" }, "icon": { "description": "Icon for the recipe", "type": [ "string", "null" ] }, "name": { "description": "Name of the recipe", "example": "install-docker", "maxLength": 32, "minLength": 4, "type": "string" } }, "required": [ "category", "commands", "fields", "name" ], "type": "object" }, "CreateRequest": { "properties": { "description": { "description": "Description for the VPC", "maxLength": 240, "type": "string" }, "name": { "description": "Name for the VPC", "example": "vpc-internal", "maxLength": 32, "minLength": 4, "type": "string" }, "range": { "description": "Private (RFC1918) CIDR for IP allocation; a random 192.168.X.0/24 is assigned when omitted", "type": "string" } }, "required": [ "description", "name" ], "type": "object" }, "CreateSnapshotRequest": { "properties": { "disk_id": { "description": "Disk ID", "example": "1463106081390612571", "type": "string" }, "instance_id": { "description": "Instance ID", "example": "1463106077196308568", "type": "string" } }, "required": [ "instance_id" ], "type": "object" }, "CreateTemplateFromBackupRequest": { "description": "Promote a backup into a template, keeping the backup's OS and boot mode", "properties": { "description": { "description": "Image description", "maxLength": 1000, "minLength": 4, "type": [ "string", "null" ] }, "kind": { "enum": [ "TEMPLATE" ], "type": "string" }, "name": { "description": "Image name", "example": "my-app-server", "maxLength": 64, "minLength": 4, "type": "string" }, "source": { "$ref": "#/components/schemas/BackupSource", "description": "Where the bytes come from" } }, "required": [ "kind", "name", "source" ], "type": "object" }, "CreateTemplateFromUrlRequest": { "description": "Import a template from a remote URL", "properties": { "description": { "description": "Image description", "maxLength": 1000, "minLength": 4, "type": [ "string", "null" ] }, "firmware": { "$ref": "#/components/schemas/Firmware", "description": "Firmware the image boots with" }, "group": { "description": "Catalog group used to bucket images (e.g. linux, windows)", "maxLength": 32, "minLength": 4, "type": [ "string", "null" ] }, "kind": { "enum": [ "TEMPLATE" ], "type": "string" }, "name": { "description": "Image name", "example": "ubuntu-24.04", "maxLength": 64, "minLength": 4, "type": "string" }, "os": { "$ref": "#/components/schemas/OsRequest", "description": "Operating system metadata" }, "source": { "$ref": "#/components/schemas/UrlSource", "description": "Where the bytes come from" } }, "required": [ "firmware", "kind", "name", "os", "source" ], "type": "object" }, "CreateTemplateRequest": { "description": "Create a template from a URL or BACKUP source", "oneOf": [ { "$ref": "#/components/schemas/CreateTemplateFromBackupRequest" }, { "$ref": "#/components/schemas/CreateTemplateFromUrlRequest" } ] }, "DHCP": { "description": "DHCP configuration", "properties": { "enabled": { "description": "If DHCP is enabled", "type": [ "boolean", "null" ] }, "v4": { "anyOf": [ { "$ref": "#/components/schemas/FloatingIpListView" }, { "type": "null" } ], "description": "IPv4 address" }, "v6": { "anyOf": [ { "$ref": "#/components/schemas/FloatingIpListView" }, { "type": "null" } ], "description": "IPv6 address" } }, "required": [ "enabled", "v4", "v6" ], "type": "object" }, "DediboxResetVncRequest": { "properties": { "dedibox_id": { "description": "Dedibox ID", "example": "1326819038986244108", "type": "string" } }, "required": [ "dedibox_id" ], "type": "object" }, "DetachIsoRequest": { "properties": { "instance": { "description": "Instance ID", "example": "1463106077196308568", "type": "string" } }, "required": [ "instance" ], "type": "object" }, "DiskSimple": { "description": "Disk reference", "properties": { "id": { "description": "Disk ID", "example": "1463106081390612571", "type": "string" }, "name": { "description": "Name of this disk", "example": "web-01-data", "type": "string" } }, "required": [ "id", "name" ], "type": "object" }, "EnrichedDediboxListViewDediboxLive": { "properties": { "id": { "description": "Dedibox ID", "example": "1326819038986244108", "type": "string" }, "name": { "description": "Name of this dedibox", "example": "dedi-fra-01", "type": "string" }, "online": { "description": "If this dedibox is powered on", "type": "boolean" }, "owner": { "anyOf": [ { "$ref": "#/components/schemas/WorkspaceSimple" }, { "type": "null" } ], "description": "Workspace that owns this dedibox" }, "region": { "description": "Region where this dedibox is deployed", "enum": [ "NA_01" ], "type": "string" }, "sku": { "description": "Product this dedibox was sold as", "example": "ryzen-7950x", "type": [ "string", "null" ] } }, "required": [ "id", "name", "online", "owner", "region", "sku" ], "type": "object" }, "EnrichedInstanceDetailViewInstanceLive": { "properties": { "autostart": { "description": "Whether the instance starts when its node boots", "type": "boolean" }, "backup_plan": { "anyOf": [ { "$ref": "#/components/schemas/BackupPlanSimple" }, { "type": "null" } ] }, "boot": { "$ref": "#/components/schemas/BootTarget", "description": "Boot target" }, "details": { "$ref": "#/components/schemas/InstanceDetailsView" }, "disable_cloudinit": { "description": "If cloud-init is disabled", "type": "boolean" }, "firewall": { "$ref": "#/components/schemas/InstanceFirewallRef", "description": "Policies applied to traffic matching no firewall rule" }, "firmware": { "$ref": "#/components/schemas/Firmware", "description": "Firmware the instance boots with" }, "flags": { "description": "Pending changes and integrations of the instance; ADDRESS_CHANGE_PENDING means one of its IP addresses changes when its pending upgrades apply", "items": { "$ref": "#/components/schemas/InstanceFlags" }, "type": "array", "uniqueItems": true }, "id": { "description": "Instance ID", "example": "1463106077196308568", "type": "string" }, "iso": { "anyOf": [ { "$ref": "#/components/schemas/ImageSimple" }, { "type": "null" } ] }, "locked": { "description": "Lock reason", "type": [ "string", "null" ] }, "mac": { "description": "MAC address of the public network interface", "type": "string" }, "name": { "description": "Instance name", "example": "web-01", "type": "string" }, "network_suspended": { "description": "If networking is suspended", "type": "boolean" }, "next_backup": { "description": "When the next backup is scheduled", "example": "2026-07-26T02:00:00Z", "format": "date-time", "type": [ "string", "null" ] }, "node": { "$ref": "#/components/schemas/NodeSimple" }, "online": { "description": "Whether this instance is currently running", "type": "boolean" }, "owner": { "$ref": "#/components/schemas/WorkspaceSimple" }, "sku": { "description": "Product this instance was sold as", "example": "lightning-1g", "type": [ "string", "null" ] }, "smtp_enabled": { "description": "Whether SMTP is allowed", "type": "boolean" }, "state": { "$ref": "#/components/schemas/ResourceState", "description": "Availability state" }, "subject": { "description": "Billing subject this instance is billed under, or null when it is not billed", "example": "1456074443980800000", "type": [ "string", "null" ] }, "terminate_on": { "description": "When this instance will be permanently deleted", "example": "2026-08-01T00:00:00Z", "format": "date-time", "type": [ "string", "null" ] }, "upgrade_pending": { "description": "Whether upgrades are staged; they apply on the next restart or when pending upgrades are applied", "type": "boolean" }, "user_cloudinit": { "description": "User supplied cloud-init configuration", "type": [ "string", "null" ] }, "whmcs": { "description": "WHMCS service ID", "example": 4821, "format": "int32", "minimum": 1, "type": [ "integer", "null" ] } }, "required": [ "autostart", "backup_plan", "boot", "details", "disable_cloudinit", "firewall", "firmware", "flags", "id", "iso", "locked", "mac", "name", "network_suspended", "next_backup", "node", "online", "owner", "sku", "smtp_enabled", "state", "subject", "terminate_on", "upgrade_pending", "user_cloudinit", "whmcs" ], "type": "object" }, "FeedbackRequest": { "properties": { "message": { "description": "Feedback message", "example": "It would be great if the instance list could be filtered by tag.", "maxLength": 2000, "minLength": 10, "type": "string" } }, "required": [ "message" ], "type": "object" }, "FieldType": { "enum": [ "TEXT", "PASSWORD", "NUMBER", "EMAIL", "BOOLEAN" ], "type": "string" }, "HostnameRequest": { "properties": { "hostname": { "description": "Hostname to use: letters, digits and hyphens in dot-separated labels", "example": "portal-instance-01", "maxLength": 63, "type": "string" }, "instance_id": { "description": "Instance ID", "example": "1463106077196308568", "type": "string" } }, "required": [ "hostname", "instance_id" ], "type": "object" }, "ImageCreateResponse": { "oneOf": [ { "$ref": "#/components/schemas/WorkflowWithResource" }, { "$ref": "#/components/schemas/WorkflowWithUpload" } ] }, "ImageDetailView": { "description": "Image detail", "properties": { "deprecated": { "description": "If this image should no longer be used", "type": [ "boolean", "null" ] }, "description": { "description": "Description of this image", "type": [ "string", "null" ] }, "firmware": { "anyOf": [ { "$ref": "#/components/schemas/Firmware" }, { "type": "null" } ], "description": "Firmware the image boots with, null for an ISO" }, "group": { "description": "Catalog group used to bucket images (e.g. linux, windows)", "type": [ "string", "null" ] }, "id": { "description": "Image ID", "example": "1471181001588760790", "type": "string" }, "kind": { "$ref": "#/components/schemas/ImageKind", "description": "What kind of image this is" }, "name": { "description": "Name of this image", "example": "ubuntu-24.04", "type": "string" }, "official": { "description": "If this image is provided by the platform (has no owning workspace)", "type": "boolean" }, "os": { "anyOf": [ { "$ref": "#/components/schemas/OsInfoView" }, { "type": "null" } ], "description": "Operating system information" }, "owner": { "anyOf": [ { "$ref": "#/components/schemas/WorkspaceSimple" }, { "type": "null" } ], "description": "Workspace that owns this image (null for official images)" }, "server": { "$ref": "#/components/schemas/StorageServerSimple", "description": "Storage server where this image is physically stored" }, "size": { "description": "Size of the image (in bytes)", "example": 2147483648, "format": "int64", "minimum": 0, "type": [ "integer", "null" ] }, "source": { "anyOf": [ { "$ref": "#/components/schemas/ImageSourceRef" }, { "type": "null" } ], "description": "Where this image's bytes were taken from (backups / snapshots only)" }, "state": { "$ref": "#/components/schemas/ResourceState", "description": "Availability state of this image" } }, "required": [ "deprecated", "description", "firmware", "group", "id", "kind", "name", "official", "os", "owner", "server", "size", "source", "state" ], "type": "object" }, "ImageKind": { "enum": [ "TEMPLATE", "BACKUP", "ISO" ], "type": "string" }, "ImageListView": { "description": "Image list item", "properties": { "deprecated": { "description": "If this image should no longer be used", "type": [ "boolean", "null" ] }, "description": { "description": "Description of this image", "type": [ "string", "null" ] }, "firmware": { "anyOf": [ { "$ref": "#/components/schemas/Firmware" }, { "type": "null" } ], "description": "Firmware the image boots with, null for an ISO" }, "group": { "description": "Catalog group used to bucket images (e.g. linux, windows)", "type": [ "string", "null" ] }, "id": { "description": "Image ID", "example": "1471181001588760790", "type": "string" }, "kind": { "$ref": "#/components/schemas/ImageKind", "description": "What kind of image this is" }, "name": { "description": "Name of this image", "example": "ubuntu-24.04", "type": "string" }, "official": { "description": "If this image is provided by the platform (has no owning workspace)", "type": "boolean" }, "os": { "anyOf": [ { "$ref": "#/components/schemas/OsInfoView" }, { "type": "null" } ], "description": "Operating system information" }, "owner": { "anyOf": [ { "$ref": "#/components/schemas/WorkspaceSimple" }, { "type": "null" } ], "description": "Workspace that owns this image (null for official images)" }, "server": { "$ref": "#/components/schemas/StorageServerSimple", "description": "Storage server where this image is physically stored" }, "size": { "description": "Size of the image (in bytes)", "example": 2147483648, "format": "int64", "minimum": 0, "type": [ "integer", "null" ] }, "source": { "anyOf": [ { "$ref": "#/components/schemas/ImageSourceRef" }, { "type": "null" } ], "description": "Where this image's bytes were taken from (backups / snapshots only)" }, "state": { "$ref": "#/components/schemas/ResourceState", "description": "Availability state of this image" } }, "required": [ "deprecated", "description", "firmware", "group", "id", "kind", "name", "official", "os", "owner", "server", "size", "source", "state" ], "type": "object" }, "ImageSource": { "description": "Where the image bytes come from", "discriminator": { "mapping": { "BACKUP": "#/components/schemas/BackupSource", "INSTANCE": "#/components/schemas/InstanceSource", "UPLOAD": "#/components/schemas/UploadSource", "URL": "#/components/schemas/UrlSource" }, "propertyName": "type" }, "properties": { "type": { "type": "string" } }, "required": [ "type" ] }, "ImageSourceRef": { "description": "Where an image's bytes were taken from (instance + disk refs for backups).", "properties": { "disk": { "description": "Disk ID this image was taken from", "example": "1463106081390612571", "type": [ "string", "null" ] }, "instance": { "description": "Instance ID this image was taken from", "example": "1463106077196308568", "type": [ "string", "null" ] } }, "required": [ "disk", "instance" ], "type": "object" }, "InstallRecipeRequest": { "properties": { "fields": { "additionalProperties": { "type": "string" }, "description": "User supplied fields", "type": "object" }, "instance": { "description": "Instance ID", "example": "1463106077196308568", "type": "string" }, "recipe": { "description": "Recipe ID", "example": "1471181001588760790", "type": "string" } }, "required": [ "fields", "instance", "recipe" ], "type": "object" }, "InstanceDetailsView": { "description": "Instance configuration details", "properties": { "attach_virtio_cd": { "description": "If a virtio driver CD should be attached", "type": "boolean" }, "cpu": { "description": "Number of vCPU cores", "example": 4, "format": "int32", "maximum": 256, "minimum": 1, "type": "integer" }, "disk": { "description": "Disk size (in bytes)", "example": 107374182400, "format": "int64", "maximum": 1048576000000, "minimum": 10485760000, "type": "integer" }, "download": { "description": "Download speed (in bytes/sec)", "example": 125000000, "format": "int64", "maximum": 1250000000, "minimum": 125000, "type": "integer" }, "group": { "$ref": "#/components/schemas/ServiceGroup", "description": "Service group" }, "hidden": { "description": "If virtualization masking techniques should be employed", "type": "boolean" }, "id": { "description": "Instance details ID", "example": "1506320201023500406", "type": "string" }, "io_limits": { "anyOf": [ { "$ref": "#/components/schemas/IoLimitsView" }, { "type": "null" } ], "description": "IO limits defined on this instance" }, "memory": { "description": "Memory (in bytes)", "example": 4294967296, "format": "int64", "maximum": 549755813888, "minimum": 536870912, "type": "integer" }, "os": { "$ref": "#/components/schemas/OsInfoView", "description": "Operating system information" }, "timezone": { "description": "Timezone the guest's hardware clock runs in for Windows guests; other families keep it in UTC", "example": "Europe/Berlin", "type": "string" }, "upload": { "description": "Upload speed (in bytes/sec)", "example": 125000000, "format": "int64", "maximum": 1250000000, "minimum": 125000, "type": "integer" } }, "required": [ "attach_virtio_cd", "cpu", "disk", "download", "group", "hidden", "id", "io_limits", "memory", "os", "timezone", "upload" ], "type": "object" }, "InstanceMetrics": { "description": "Time-series metrics for a single instance. See each field for its unit.", "properties": { "bandwidth_incoming_bytes": { "description": "Total bytes received by the VM over the `[start, end]` window of this request \u2014 the integral of\n`network_incoming`. Useful for a \"bandwidth consumed in the last 5 minutes / hour / month\" readout\nwithout making the frontend integrate the time series itself.\n", "example": 1073741824, "format": "int64", "minimum": 0, "type": "integer" }, "bandwidth_outgoing_bytes": { "description": "Total bytes transmitted by the VM over the `[start, end]` window of this request \u2014 the integral of\n`network_outgoing`.\n", "example": 536870912, "format": "int64", "minimum": 0, "type": "integer" }, "cpu": { "$ref": "#/components/schemas/PromMatrix", "description": "CPU usage as a percentage where 100 = 1 full core. A 4-vCPU VM saturating all cores reports 400.\nDivide by the instance's allocated vCPU count for a 0..100 utilization percentage.\n" }, "disk_reads": { "$ref": "#/components/schemas/PromMatrix", "description": "Aggregate disk read bandwidth across all VM disks in KiB/s (kibibytes per second). Not split per\ndisk. Always non-negative.\n" }, "disk_total": { "$ref": "#/components/schemas/PromMatrix", "description": "Total capacity in bytes across all real filesystems inside the guest. Typically flat over time \u2014\nchanges when disks are attached, detached, or resized. Empty if the guest agent is unavailable.\n" }, "disk_used": { "$ref": "#/components/schemas/PromMatrix", "description": "Bytes currently used across all real filesystems inside the guest (tmpfs and pseudo-filesystems\nexcluded). Sampled from the guest agent on a 1-minute cadence. Empty if the guest agent is\nunavailable or has not yet reported. Pair with `disk_total` for a usage percentage.\n" }, "disk_writes": { "$ref": "#/components/schemas/PromMatrix", "description": "Aggregate disk write bandwidth across all VM disks in KiB/s. Always non-negative.\n" }, "memory": { "description": "Guest-reported memory telemetry as a list of named series. Each element's `metric` field identifies\nthe series; currently one of:\n\n * `used` \u2014 memory currently in use by the guest OS, in bytes. Equivalent to what `free` reports\n as used. Compare against `details.memory` on the instance for a utilization percentage.\n * `rss` \u2014 resident set size of the VM on the host, in bytes. Complementary to `used`; diverges\n when the guest has large disk caches or is swapping.\n * `swap_in` \u2014 bytes per second being paged in from swap back to RAM. Non-zero often correlates\n with latency spikes inside the guest.\n * `swap_out` \u2014 bytes per second being paged out from RAM to swap. Non-zero indicates the guest\n is under memory pressure.\n * `major_faults` \u2014 major page faults per second. High values are an early warning for OOMs.\n\nAll values reflect the guest kernel's own view (not host accounting). Series are only populated for\ninstances where the guest agent is reporting memory stats; others will come back empty.\n", "items": { "$ref": "#/components/schemas/PromMatrix" }, "type": "array" }, "network_incoming": { "$ref": "#/components/schemas/PromMatrix", "description": "Incoming (rx) network traffic on the VM's public interface, in bytes per second. Always\nnon-negative.\n" }, "network_outgoing": { "$ref": "#/components/schemas/PromMatrix", "description": "Outgoing (tx) network traffic on the VM's public interface, in bytes per second. Always\nnon-negative.\n" } }, "required": [ "bandwidth_incoming_bytes", "bandwidth_outgoing_bytes", "cpu", "disk_reads", "disk_total", "disk_used", "disk_writes", "memory", "network_incoming", "network_outgoing" ], "type": "object" }, "InstanceSource": { "allOf": [ { "$ref": "#/components/schemas/ImageSource" }, { "properties": { "disk_id": { "description": "Source disk ID; defaults to the instance's boot disk when omitted", "example": "1463106081390612571", "type": [ "string", "null" ] }, "instance_id": { "description": "Source instance ID; defaults to the disk's instance when omitted", "example": "1463106077196308568", "type": [ "string", "null" ] } }, "type": "object" } ], "description": "Capture from a live instance disk" }, "InstanceVpcListView": { "description": "VPC attachment on an instance", "properties": { "id": { "description": "Attachment ID", "example": "1506320201023500406", "type": "string" }, "ip_address": { "description": "Allocated IP address for this instance within the VPC", "type": "string" }, "mac": { "description": "MAC address of this instance's VPC network adapter", "example": "a6:00:00:b0:ee:f0", "type": "string" }, "vpc": { "$ref": "#/components/schemas/VpcSimple", "description": "Attached VPC" } }, "required": [ "id", "ip_address", "mac", "vpc" ], "type": "object" }, "KeysetResultBgpPrefixListView": { "properties": { "after": { "type": [ "string", "null" ] }, "before": { "type": [ "string", "null" ] }, "has_next": { "type": "boolean" }, "has_previous": { "type": "boolean" }, "items": { "items": { "$ref": "#/components/schemas/BgpPrefixListView" }, "type": "array" }, "limit": { "description": "Limit of items returned per page", "format": "int32", "maximum": 100, "minimum": 1, "type": "integer" }, "page": { "description": "Page number", "format": "int32", "maximum": 1000, "minimum": 1, "type": "integer" }, "total": { "description": "Total number of matching items", "format": "int64", "minimum": 0, "type": "integer" } }, "required": [ "after", "before", "has_next", "has_previous", "items", "limit", "page", "total" ], "type": "object" }, "KeysetResultEnrichedDediboxListViewDediboxLive": { "properties": { "after": { "type": [ "string", "null" ] }, "before": { "type": [ "string", "null" ] }, "has_next": { "type": "boolean" }, "has_previous": { "type": "boolean" }, "items": { "items": { "$ref": "#/components/schemas/EnrichedDediboxListViewDediboxLive" }, "type": "array" }, "limit": { "description": "Limit of items returned per page", "format": "int32", "maximum": 100, "minimum": 1, "type": "integer" }, "page": { "description": "Page number", "format": "int32", "maximum": 1000, "minimum": 1, "type": "integer" }, "total": { "description": "Total number of matching items", "format": "int64", "minimum": 0, "type": "integer" } }, "required": [ "after", "before", "has_next", "has_previous", "items", "limit", "page", "total" ], "type": "object" }, "KeysetResultImageListView": { "properties": { "after": { "type": [ "string", "null" ] }, "before": { "type": [ "string", "null" ] }, "has_next": { "type": "boolean" }, "has_previous": { "type": "boolean" }, "items": { "items": { "$ref": "#/components/schemas/ImageListView" }, "type": "array" }, "limit": { "description": "Limit of items returned per page", "format": "int32", "maximum": 100, "minimum": 1, "type": "integer" }, "page": { "description": "Page number", "format": "int32", "maximum": 1000, "minimum": 1, "type": "integer" }, "total": { "description": "Total number of matching items", "format": "int64", "minimum": 0, "type": "integer" } }, "required": [ "after", "before", "has_next", "has_previous", "items", "limit", "page", "total" ], "type": "object" }, "KeysetResultInstanceVpcListView": { "properties": { "after": { "type": [ "string", "null" ] }, "before": { "type": [ "string", "null" ] }, "has_next": { "type": "boolean" }, "has_previous": { "type": "boolean" }, "items": { "items": { "$ref": "#/components/schemas/InstanceVpcListView" }, "type": "array" }, "limit": { "description": "Limit of items returned per page", "format": "int32", "maximum": 100, "minimum": 1, "type": "integer" }, "page": { "description": "Page number", "format": "int32", "maximum": 1000, "minimum": 1, "type": "integer" }, "total": { "description": "Total number of matching items", "format": "int64", "minimum": 0, "type": "integer" } }, "required": [ "after", "before", "has_next", "has_previous", "items", "limit", "page", "total" ], "type": "object" }, "KeysetResultOptionallyEnrichedDiskListViewDiskLive": { "properties": { "after": { "type": [ "string", "null" ] }, "before": { "type": [ "string", "null" ] }, "has_next": { "type": "boolean" }, "has_previous": { "type": "boolean" }, "items": { "items": { "$ref": "#/components/schemas/OptionallyEnrichedDiskListViewDiskLive" }, "type": "array" }, "limit": { "description": "Limit of items returned per page", "format": "int32", "maximum": 100, "minimum": 1, "type": "integer" }, "page": { "description": "Page number", "format": "int32", "maximum": 1000, "minimum": 1, "type": "integer" }, "total": { "description": "Total number of matching items", "format": "int64", "minimum": 0, "type": "integer" } }, "required": [ "after", "before", "has_next", "has_previous", "items", "limit", "page", "total" ], "type": "object" }, "KeysetResultRecipeListView": { "properties": { "after": { "type": [ "string", "null" ] }, "before": { "type": [ "string", "null" ] }, "has_next": { "type": "boolean" }, "has_previous": { "type": "boolean" }, "items": { "items": { "$ref": "#/components/schemas/RecipeListView" }, "type": "array" }, "limit": { "description": "Limit of items returned per page", "format": "int32", "maximum": 100, "minimum": 1, "type": "integer" }, "page": { "description": "Page number", "format": "int32", "maximum": 1000, "minimum": 1, "type": "integer" }, "total": { "description": "Total number of matching items", "format": "int64", "minimum": 0, "type": "integer" } }, "required": [ "after", "before", "has_next", "has_previous", "items", "limit", "page", "total" ], "type": "object" }, "KeysetResultSnapshotListView": { "properties": { "after": { "type": [ "string", "null" ] }, "before": { "type": [ "string", "null" ] }, "has_next": { "type": "boolean" }, "has_previous": { "type": "boolean" }, "items": { "items": { "$ref": "#/components/schemas/SnapshotListView" }, "type": "array" }, "limit": { "description": "Limit of items returned per page", "format": "int32", "maximum": 100, "minimum": 1, "type": "integer" }, "page": { "description": "Page number", "format": "int32", "maximum": 1000, "minimum": 1, "type": "integer" }, "total": { "description": "Total number of matching items", "format": "int64", "minimum": 0, "type": "integer" } }, "required": [ "after", "before", "has_next", "has_previous", "items", "limit", "page", "total" ], "type": "object" }, "KeysetResultSshKeyListView": { "properties": { "after": { "type": [ "string", "null" ] }, "before": { "type": [ "string", "null" ] }, "has_next": { "type": "boolean" }, "has_previous": { "type": "boolean" }, "items": { "items": { "$ref": "#/components/schemas/SshKeyListView" }, "type": "array" }, "limit": { "description": "Limit of items returned per page", "format": "int32", "maximum": 100, "minimum": 1, "type": "integer" }, "page": { "description": "Page number", "format": "int32", "maximum": 1000, "minimum": 1, "type": "integer" }, "total": { "description": "Total number of matching items", "format": "int64", "minimum": 0, "type": "integer" } }, "required": [ "after", "before", "has_next", "has_previous", "items", "limit", "page", "total" ], "type": "object" }, "KeysetResultVpcInstanceListView": { "properties": { "after": { "type": [ "string", "null" ] }, "before": { "type": [ "string", "null" ] }, "has_next": { "type": "boolean" }, "has_previous": { "type": "boolean" }, "items": { "items": { "$ref": "#/components/schemas/VpcInstanceListView" }, "type": "array" }, "limit": { "description": "Limit of items returned per page", "format": "int32", "maximum": 100, "minimum": 1, "type": "integer" }, "page": { "description": "Page number", "format": "int32", "maximum": 1000, "minimum": 1, "type": "integer" }, "total": { "description": "Total number of matching items", "format": "int64", "minimum": 0, "type": "integer" } }, "required": [ "after", "before", "has_next", "has_previous", "items", "limit", "page", "total" ], "type": "object" }, "KeysetResultWorkflowData": { "properties": { "after": { "type": [ "string", "null" ] }, "before": { "type": [ "string", "null" ] }, "has_next": { "type": "boolean" }, "has_previous": { "type": "boolean" }, "items": { "items": { "$ref": "#/components/schemas/WorkflowData" }, "type": "array" }, "limit": { "description": "Limit of items returned per page", "format": "int32", "maximum": 100, "minimum": 1, "type": "integer" }, "page": { "description": "Page number", "format": "int32", "maximum": 1000, "minimum": 1, "type": "integer" }, "total": { "description": "Total number of matching items", "format": "int64", "minimum": 0, "type": "integer" } }, "required": [ "after", "before", "has_next", "has_previous", "items", "limit", "page", "total" ], "type": "object" }, "OptionallyEnrichedDiskDetailViewDiskLive": { "properties": { "backend": { "description": "Storage backend", "enum": [ "LOCAL", "CEPH" ], "type": "string" }, "boot": { "description": "If this is a boot disk", "type": "boolean" }, "id": { "description": "Disk ID", "example": "1463106081390612571", "type": "string" }, "instance": { "anyOf": [ { "$ref": "#/components/schemas/InstanceSimple" }, { "type": "null" } ], "description": "Instance attached to this disk" }, "name": { "description": "Name of this disk", "example": "web-01-data", "type": "string" }, "node": { "anyOf": [ { "$ref": "#/components/schemas/NodeSimple" }, { "type": "null" } ], "description": "Node this disk's block lives on" }, "owner": { "$ref": "#/components/schemas/WorkspaceSimple", "description": "Workspace that owns this disk" }, "partition_scheme": { "anyOf": [ { "$ref": "#/components/schemas/PartitionScheme" }, { "type": "null" } ], "description": "Partition table last detected on this boot disk, or null when it was never checked" }, "region": { "description": "Region this disk belongs to", "enum": [ "NA_01" ], "type": [ "string", "null" ] }, "size": { "description": "Disk size (in bytes)", "example": 107374182400, "format": "int64", "minimum": 0, "type": "integer" }, "state": { "$ref": "#/components/schemas/ResourceState", "description": "Availability state of this disk" }, "usage_pct": { "description": "Estimated disk usage in percentage. Absent when live data is unavailable.", "example": 42.5, "format": "float", "type": "number" } }, "required": [ "backend", "boot", "id", "instance", "name", "node", "owner", "partition_scheme", "region", "size", "state" ], "type": "object" }, "OptionallyEnrichedDiskListViewDiskLive": { "properties": { "backend": { "description": "Storage backend", "enum": [ "LOCAL", "CEPH" ], "type": "string" }, "boot": { "description": "If this is a boot disk", "type": "boolean" }, "id": { "description": "Disk ID", "example": "1463106081390612571", "type": "string" }, "instance": { "anyOf": [ { "$ref": "#/components/schemas/InstanceSimple" }, { "type": "null" } ], "description": "Instance attached to this disk" }, "name": { "description": "Name of this disk", "example": "web-01-data", "type": "string" }, "owner": { "$ref": "#/components/schemas/WorkspaceSimple", "description": "Workspace that owns this disk" }, "partition_scheme": { "anyOf": [ { "$ref": "#/components/schemas/PartitionScheme" }, { "type": "null" } ], "description": "Partition table last detected on this boot disk, or null when it was never checked" }, "region": { "description": "Region this disk belongs to", "enum": [ "NA_01" ], "type": [ "string", "null" ] }, "size": { "description": "Disk size (in bytes)", "example": 107374182400, "format": "int64", "minimum": 0, "type": "integer" }, "state": { "$ref": "#/components/schemas/ResourceState", "description": "Availability state of this disk" }, "usage_pct": { "description": "Estimated disk usage in percentage. Absent when live data is unavailable.", "example": 42.5, "format": "float", "type": "number" } }, "required": [ "backend", "boot", "id", "instance", "name", "owner", "partition_scheme", "region", "size", "state" ], "type": "object" }, "OsRequest": { "description": "Operating system metadata", "properties": { "family": { "$ref": "#/components/schemas/OsFamily", "description": "OS family" }, "name": { "description": "OS display name (e.g. 'Ubuntu 24.04')", "example": "Ubuntu 24.04", "type": [ "string", "null" ] } }, "required": [ "family" ], "type": "object" }, "PartitionScheme": { "description": "Partition table found on a disk", "enum": [ "GPT", "MBR", "EMPTY", "UNKNOWN" ], "type": "string" }, "PatchDediboxRequest": { "properties": { "name": { "description": "Dedibox name", "example": "dedi-fra-01", "maxLength": 32, "minLength": 4, "type": "string" } }, "type": "object" }, "PatchDiskRequest": { "properties": { "name": { "description": "Name of the disk", "example": "web-01-data", "maxLength": 32, "minLength": 4, "type": "string" } }, "type": "object" }, "PatchImageOs": { "properties": { "family": { "description": "OS family", "enum": [ "WINDOWS", "LINUX", "BSD", "OTHER" ], "type": "string" }, "name": { "description": "OS display name (e.g. 'Ubuntu 24.04'), or null to clear it", "example": "Ubuntu 24.04", "type": [ "string", "null" ] } }, "type": "object" }, "PatchImageRequest": { "properties": { "description": { "description": "Image description, or null to clear it", "maxLength": 1000, "minLength": 4, "type": [ "string", "null" ] }, "group": { "description": "Catalog group used to bucket images (e.g. linux, windows), or null to clear it", "maxLength": 32, "minLength": 4, "type": [ "string", "null" ] }, "name": { "description": "Image name", "example": "ubuntu-24.04", "maxLength": 32, "minLength": 4, "type": "string" }, "os": { "$ref": "#/components/schemas/PatchImageOs", "description": "Operating system metadata" } }, "type": "object" }, "PatchInstanceRequest": { "properties": { "attach_virtio_cd": { "description": "Whether the VirtIO driver CD is attached. A running instance gets the change live", "type": "boolean" }, "autostart": { "description": "Whether the instance starts when its node boots", "type": "boolean" }, "boot": { "enum": [ "DISK", "ISO" ], "type": "string" }, "disable_cloudinit": { "description": "If vendor cloud-init features are disabled on this instance", "type": "boolean" }, "name": { "description": "Instance name, also its hostname: letters, digits and hyphens in dot-separated labels", "example": "web-01", "maxLength": 63, "type": "string" }, "os_family": { "description": "OS family of the guest, applied on the next power cycle", "enum": [ "WINDOWS", "LINUX", "BSD", "OTHER" ], "type": "string" }, "os_name": { "description": "OS display name (e.g. 'Ubuntu 24.04'), or null to clear it", "example": "Ubuntu 24.04", "type": [ "string", "null" ] }, "sync_hostname": { "type": "boolean" }, "timezone": { "description": "IANA timezone the hardware clock of a Windows guest runs in, applied on the next power cycle. Other families keep the clock in UTC", "example": "Europe/Berlin", "type": "string" }, "user_cloudinit": { "description": "Cloud-init user data, or null to clear it", "type": [ "string", "null" ] } }, "type": "object" }, "PatchRecipeRequest": { "properties": { "category": { "description": "Category for the recipe", "enum": [ "DEFAULT", "GAMES", "SOFTWARE", "INFRASTRUCTURE", "AI", "MEDIA", "TOOLS", "DATABASES", "MONITORING", "PRODUCTIVITY", "DEVOPS", "AUTOMATION", "NETWORK" ], "type": "string" }, "commands": { "description": "List of commands to execute", "items": { "$ref": "#/components/schemas/RecipeCommandRequest" }, "type": "array" }, "description": { "description": "Description of the recipe", "type": "string" }, "fields": { "description": "Fields for the recipe", "items": { "$ref": "#/components/schemas/RecipeFieldRequest" }, "type": "array" }, "icon": { "description": "Icon for the recipe", "type": "string" }, "name": { "description": "Name of the recipe", "example": "install-docker", "type": "string" } }, "type": "object" }, "PowerAction": { "enum": [ "POWER_CYCLE", "POWER_OFF", "POWER_ON", "SHUTDOWN" ], "type": "string" }, "PowerCycleRequest": { "properties": { "action": { "$ref": "#/components/schemas/PowerAction", "description": "Power Operation" }, "dedibox_id": { "description": "Dedibox ID", "example": "1326819038986244108", "type": "string" } }, "required": [ "action", "dedibox_id" ], "type": "object" }, "PowerRequest": { "properties": { "action": { "$ref": "#/components/schemas/PowerAction", "description": "Power operation to perform" } }, "required": [ "action" ], "type": "object" }, "QuotaView": { "description": "Workspace quota", "properties": { "firewall_rules_per_ip": { "default": 10, "description": "Maximum number of firewall rules per IP address", "format": "int32", "minimum": 0, "type": "integer" }, "id": { "description": "Quota ID, or null when the workspace uses the default limits", "example": "1471181001588760790", "type": [ "string", "null" ] }, "iso_count": { "default": 5, "description": "Maximum number of ISOs that can be uploaded", "format": "int32", "minimum": 0, "type": "integer" }, "iso_storage_bytes": { "default": 15728640000, "description": "Maximum total ISO size that can be stored (in bytes)", "example": 15728640000, "format": "int64", "minimum": 0, "type": "integer" }, "max_bgp_prefixes": { "default": 30, "description": "Maximum number of BGP prefixes that can be announced", "format": "int32", "minimum": 0, "type": "integer" }, "max_cpu_cores": { "default": 32, "description": "Maximum vCPUs across the workspace's servers", "format": "int32", "minimum": 0, "type": "integer" }, "max_instances": { "default": 10, "description": "Maximum number of servers the workspace can hold", "format": "int32", "minimum": 0, "type": "integer" }, "max_memory_bytes": { "default": 68719476736, "description": "Maximum memory across the workspace's servers (in bytes)", "example": 68719476736, "format": "int64", "minimum": 0, "type": "integer" }, "max_ssh_keys": { "default": 8, "description": "Maximum number of SSH keys that can be uploaded", "format": "int32", "minimum": 0, "type": "integer" }, "max_storage_bytes": { "default": 1048576000000, "description": "Maximum disk across the workspace's servers (in bytes)", "example": 1048576000000, "format": "int64", "minimum": 0, "type": "integer" }, "max_vpcs": { "default": 3, "description": "Maximum number of VPCs that can be created", "format": "int32", "minimum": 0, "type": "integer" }, "owner": { "$ref": "#/components/schemas/WorkspaceSimple", "description": "Workspace this quota applies to" } }, "required": [ "firewall_rules_per_ip", "id", "iso_count", "iso_storage_bytes", "max_bgp_prefixes", "max_cpu_cores", "max_instances", "max_memory_bytes", "max_ssh_keys", "max_storage_bytes", "max_vpcs", "owner" ], "type": "object" }, "RecipeCommand": { "properties": { "args": { "description": "Arguments passed to the executable", "items": { "type": "string" }, "type": "array" }, "path": { "description": "Absolute path of the executable to run", "example": "/usr/bin/apt-get", "type": "string" } }, "required": [ "args", "path" ], "type": "object" }, "RecipeCommandRequest": { "description": "A command the recipe runs on the instance", "properties": { "args": { "description": "Arguments passed to the executable", "items": { "type": "string" }, "type": "array" }, "path": { "description": "Absolute path of the executable to run", "example": "/usr/bin/apt-get", "type": "string" } }, "required": [ "args", "path" ], "type": "object" }, "RecipeDetailView": { "description": "Recipe with the commands it runs and the inputs it asks for", "properties": { "category": { "description": "Category for the recipe", "enum": [ "DEFAULT", "GAMES", "SOFTWARE", "INFRASTRUCTURE", "AI", "MEDIA", "TOOLS", "DATABASES", "MONITORING", "PRODUCTIVITY", "DEVOPS", "AUTOMATION", "NETWORK" ], "type": "string" }, "commands": { "description": "Executable commands for this recipe", "items": { "$ref": "#/components/schemas/RecipeCommand" }, "type": "array" }, "description": { "description": "Description of the recipe", "type": [ "string", "null" ] }, "fields": { "description": "Input fields for this recipe", "items": { "$ref": "#/components/schemas/RecipeField" }, "type": "array" }, "icon": { "description": "Icon for the recipe", "type": [ "string", "null" ] }, "id": { "description": "Recipe ID", "example": "1471181001588760790", "type": "string" }, "name": { "description": "Name of the recipe", "example": "install-docker", "type": "string" }, "owner": { "anyOf": [ { "$ref": "#/components/schemas/WorkspaceSimple" }, { "type": "null" } ], "description": "Workspace that owns this recipe" } }, "required": [ "category", "commands", "description", "fields", "icon", "id", "name", "owner" ], "type": "object" }, "RecipeField": { "properties": { "description": { "type": [ "string", "null" ] }, "id": { "type": "string" }, "label": { "type": "string" }, "required": { "type": "boolean" }, "type": { "$ref": "#/components/schemas/FieldType" } }, "required": [ "description", "id", "label", "required", "type" ], "type": "object" }, "RecipeFieldRequest": { "description": "An input the recipe asks for when it is installed", "properties": { "description": { "description": "Hint shown under the input", "maxLength": 1024, "type": [ "string", "null" ] }, "id": { "description": "Identifier the commands reference the value by", "example": "domain", "maxLength": 64, "type": "string" }, "label": { "description": "Label shown next to the input", "example": "Domain name", "maxLength": 128, "type": "string" }, "required": { "description": "Whether the input must be filled in to install the recipe", "type": "boolean" }, "type": { "$ref": "#/components/schemas/FieldType", "description": "Kind of value the input takes" } }, "required": [ "id", "label", "required", "type" ], "type": "object" }, "RecipeListView": { "description": "Recipe list item", "properties": { "category": { "description": "Category for the recipe", "enum": [ "DEFAULT", "GAMES", "SOFTWARE", "INFRASTRUCTURE", "AI", "MEDIA", "TOOLS", "DATABASES", "MONITORING", "PRODUCTIVITY", "DEVOPS", "AUTOMATION", "NETWORK" ], "type": "string" }, "description": { "description": "Description of the recipe", "type": [ "string", "null" ] }, "icon": { "description": "Icon for the recipe", "type": [ "string", "null" ] }, "id": { "description": "Recipe ID", "example": "1471181001588760790", "type": "string" }, "name": { "description": "Name of the recipe", "example": "install-docker", "type": "string" }, "owner": { "anyOf": [ { "$ref": "#/components/schemas/WorkspaceSimple" }, { "type": "null" } ], "description": "Workspace that owns this recipe" } }, "required": [ "category", "description", "icon", "id", "name", "owner" ], "type": "object" }, "ResetRequest": { "properties": { "instance_id": { "description": "Instance ID", "example": "1463106077196308568", "type": "string" } }, "required": [ "instance_id" ], "type": "object" }, "ResetResponse": { "properties": { "password": { "description": "Instance Password", "type": "string" }, "task_id": { "description": "Audit Log ID", "example": "1498223722102817012", "type": "string" } }, "required": [ "password", "task_id" ], "type": "object" }, "ResourceState": { "enum": [ "PENDING", "AVAILABLE", "FAILED", "SUSPENDED", "DELETING", "UNPLACED" ], "type": "string" }, "RestoreImageRequest": { "properties": { "disk_id": { "description": "Disk ID to restore onto (defaults to the instance's boot disk)", "example": "1463106081390612571", "type": [ "string", "null" ] }, "instance_id": { "description": "Instance ID to restore onto", "example": "1463106077196308568", "type": "string" }, "restart": { "description": "If the instance should be restarted", "type": "boolean" } }, "required": [ "instance_id" ], "type": "object" }, "RestoreSnapshotRequest": { "properties": { "restart": { "description": "If the instance should be restarted", "type": "boolean" }, "snapshot_id": { "description": "Snapshot ID", "example": "1463106081390612571", "type": "string" } }, "required": [ "snapshot_id" ], "type": "object" }, "RouterRequest": { "properties": { "dns_server": { "description": "IPv4 DNS server offered to the other ports while a router is set; none is offered when omitted", "example": "192.168.0.2", "type": [ "string", "null" ] }, "router": { "description": "Instance attached to this VPC that becomes the default route for its other ports; null clears the router", "example": "1471181001588760790", "type": [ "string", "null" ] } }, "type": "object" }, "SnapshotListView": { "description": "Snapshot list item", "properties": { "created": { "description": "When this snapshot was created", "example": "2026-01-20T09:41:13Z", "format": "date-time", "type": "string" }, "disk": { "$ref": "#/components/schemas/DiskSimple", "description": "Disk for this snapshot" }, "id": { "description": "Snapshot ID", "example": "1463106081390612571", "type": "string" }, "instance": { "$ref": "#/components/schemas/InstanceSimple", "description": "Instance for this snapshot" }, "owner": { "$ref": "#/components/schemas/WorkspaceSimple", "description": "Workspace that owns this snapshot" }, "state": { "$ref": "#/components/schemas/ResourceState", "description": "Ready state of this snapshot" } }, "required": [ "created", "disk", "id", "instance", "owner", "state" ], "type": "object" }, "SshCreateRequest": { "properties": { "name": { "description": "Name for the SSH key", "example": "laptop", "maxLength": 32, "minLength": 4, "type": "string" }, "public_key": { "description": "Public key", "example": "ssh-rsa ...", "type": "string" } }, "required": [ "name", "public_key" ], "type": "object" }, "SshKey": { "properties": { "id": { "description": "Entity ID", "example": "1506320201023500406", "type": "string" }, "name": { "description": "Name of the SSH key", "example": "laptop", "type": "string" }, "owner": { "$ref": "#/components/schemas/Workspace" }, "public_key": { "description": "Value of the public key", "format": "openssh-rsa", "type": "string" }, "user": { "$ref": "#/components/schemas/User", "description": "User that uploaded this SSH key" } }, "required": [ "id", "name", "owner", "public_key", "user" ], "type": "object" }, "SshKeyListView": { "description": "SSH key list item", "properties": { "id": { "description": "SSH key ID", "example": "1506320201023500406", "type": "string" }, "name": { "description": "Name of the SSH key", "example": "laptop", "type": "string" }, "owner": { "$ref": "#/components/schemas/WorkspaceSimple", "description": "Workspace that owns this SSH key" }, "public_key": { "description": "Value of the public key", "type": "string" }, "user": { "$ref": "#/components/schemas/UserSimple", "description": "User that uploaded this SSH key" } }, "required": [ "id", "name", "owner", "public_key", "user" ], "type": "object" }, "StorageServerSimple": { "description": "Storage server reference (id + name)", "properties": { "id": { "description": "Storage server ID", "example": "1326819038986244108", "type": "string" }, "name": { "description": "Storage server name", "example": "ceph-fra-01", "type": "string" } }, "required": [ "id", "name" ], "type": "object" }, "SyncRequest": { "properties": { "instance_id": { "description": "Instance ID", "example": "1463106077196308568", "type": "string" } }, "required": [ "instance_id" ], "type": "object" }, "UpdateDhcpRequest": { "properties": { "enabled": { "description": "If DHCP is served to the instance", "type": "boolean" }, "v4": { "description": "Floating IPv4 ID to serve over DHCP, or null to serve none", "example": "1464201868476432440", "type": [ "string", "null" ] }, "v6": { "description": "Floating IPv6 ID to serve over DHCP, or null to serve none", "example": "1464201868476432440", "type": [ "string", "null" ] } }, "required": [ "enabled" ], "type": "object" }, "UpdateRequest": { "properties": { "description": { "description": "Description for the VPC", "maxLength": 240, "type": [ "string", "null" ] }, "name": { "description": "Name for the VPC", "example": "vpc-internal", "maxLength": 32, "minLength": 4, "type": [ "string", "null" ] } }, "type": "object" }, "UploadSource": { "allOf": [ { "$ref": "#/components/schemas/ImageSource" }, { "properties": { "size_bytes": { "description": "Exact size in bytes that will be uploaded", "example": 2147483648, "format": "int64", "maximum": 10737418240, "minimum": 1, "type": "integer" } }, "required": [ "size_bytes" ], "type": "object" } ], "description": "Upload the bytes to a signed URL returned by the create call", "required": [ "size_bytes" ] }, "UploadTarget": { "properties": { "expires_at": { "description": "When the URL stops being valid", "example": "2026-02-11T16:43:04Z", "format": "date-time", "type": "string" }, "max_size_bytes": { "description": "Exact byte count the client must upload", "example": 5368709120, "format": "int64", "minimum": 0, "type": "integer" }, "url": { "description": "Absolute URL the client should PUT the file to", "type": "string" } }, "required": [ "expires_at", "max_size_bytes", "url" ], "type": "object" }, "UrlSource": { "allOf": [ { "$ref": "#/components/schemas/ImageSource" }, { "properties": { "url": { "description": "Source URL", "example": "https://cloud-images.example.net/noble-server-cloudimg-amd64.img", "type": "string" } }, "required": [ "url" ], "type": "object" } ], "description": "Fetch the image from a remote URL", "required": [ "url" ] }, "User": { "properties": { "email": { "description": "User's email address", "type": "string" }, "flags": { "description": "User's account flags", "items": { "$ref": "#/components/schemas/UserFlags" }, "type": "array", "uniqueItems": true }, "id": { "description": "Entity ID", "example": "1506320201023500406", "type": "string" }, "name": { "description": "User's name", "example": "Ada Lovelace", "type": "string" }, "whmcs_id": { "description": "WHMCS client ID linked to this account", "format": "int32", "minimum": 1, "type": [ "integer", "null" ] } }, "required": [ "email", "flags", "id", "name", "whmcs_id" ], "type": "object" }, "VpcAttachRequest": { "properties": { "vpc": { "description": "VPC ID to attach", "example": "1463882832936980610", "type": "string" } }, "required": [ "vpc" ], "type": "object" }, "VpcInstanceListView": { "description": "Instance attachment on a VPC", "properties": { "id": { "description": "Attachment ID", "example": "1506320201023500406", "type": "string" }, "instance": { "$ref": "#/components/schemas/InstanceSimple", "description": "Attached instance" }, "ip_address": { "description": "Allocated IP address within the VPC", "type": "string" } }, "required": [ "id", "instance", "ip_address" ], "type": "object" }, "WorkflowWithUpload": { "properties": { "resource": { "$ref": "#/components/schemas/Resource", "description": "Resource information" }, "upload": { "$ref": "#/components/schemas/UploadTarget", "description": "Direct upload target" }, "workflow": { "$ref": "#/components/schemas/WorkflowData", "description": "Workflow information" } }, "required": [ "resource", "upload", "workflow" ], "type": "object" }, "Workspace": { "properties": { "flags": { "description": "List of workspace flags", "items": { "$ref": "#/components/schemas/WorkspaceFlags" }, "type": "array", "uniqueItems": true }, "id": { "description": "Entity ID", "example": "1506320201023500406", "type": "string" }, "name": { "description": "Workspace name", "example": "acme-production", "type": "string" }, "owner": { "$ref": "#/components/schemas/User", "description": "Owner of the workspace" } }, "required": [ "flags", "id", "name", "owner" ], "type": "object" } }, "securitySchemes": { "cookie": { "type": "apiKey", "in": "cookie", "name": "Session" }, "api": { "type": "http", "scheme": "bearer", "bearerFormat": "gg.XXYYZZ" } } } }