{ "openapi": "3.1.0", "info": { "title": "Suble v3 API", "version": "3.0.0", "description": "Provision and manage cloud infrastructure on Suble — order VPS instances, manage Docker containers and databases, private networks, billing and more.", "contact": { "name": "Suble", "url": "https://suble.io" } }, "servers": [ { "url": "https://api.v3.suble.io", "description": "Production" } ], "tags": [ { "name": "Catalog" }, { "name": "Projects & members" }, { "name": "Instances" }, { "name": "Backups, restore, resize" }, { "name": "Firewall" }, { "name": "Private networks" }, { "name": "Templates" }, { "name": "Jobs (async progress)" }, { "name": "API keys" }, { "name": "DDoS protection" }, { "name": "Colocation" }, { "name": "IP transit" }, { "name": "IP ranges" }, { "name": "Account (SSH keys, security, limits)" }, { "name": "Current user" }, { "name": "Notifications" }, { "name": "Billing & credits" }, { "name": "Auth (email verification)" } ], "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "API key or OAuth access token", "description": "Project API key (sk_proj_…) or OAuth 2.1 access token, sent as `Authorization: Bearer `." } } }, "paths": { "/plans": { "get": { "tags": [ "Catalog" ], "summary": "List active compute plans", "description": "Returns every active compute plan (the Suble VPS catalog) ordered by display sort. Each plan describes its hardware resources and pricing in integer øre excluding VAT.", "operationId": "getplans", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "example": { "plans": [ { "uid": "pln_bxs1", "code": "bxs-1", "name": "BXS 1", "family": "bxs", "vcpu": 1, "memoryMb": 2048, "diskGb": 40, "networkMbps": 10000, "priceMonthlyOre": 4000, "priceHourlyOre": 6 } ] } } } } } } }, "/images": { "get": { "tags": [ "Catalog" ], "summary": "List active OS images", "description": "Returns every active OS image available for provisioning instances, grouped by family and ordered by version descending. Each image carries its default user, connection protocol, minimum disk requirement, and guest-agent support flag.", "operationId": "getimages", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "example": { "images": [ { "uid": "img_ubuntu2404", "family": "ubuntu", "version": "24.04", "displayName": "Ubuntu 24.04 LTS", "protocol": "ssh", "defaultUser": "ubuntu", "minDiskGb": 10, "hasGuestAgent": true } ] } } } } } } }, "/apps": { "get": { "tags": [ "Catalog" ], "summary": "List one-click app catalog", "description": "Returns the catalog of one-click apps, deduplicated to the latest active version per slug (highest id wins). Each entry includes a derived category and the minimum resource/image requirements for installation.", "operationId": "getapps", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "example": { "apps": [ { "uid": "app_coolify", "slug": "coolify", "version": "4.1.0", "name": "Coolify", "description": "Self-hostable PaaS to deploy apps and databases.", "logo": "https://cdn.suble.io/apps/coolify.svg", "category": "panel", "requirements": { "minVcpu": 2, "minMemoryMb": 4096, "minDiskGb": 40, "image": { "family": "ubuntu", "version": "24.04" } } } ] } } } } } } }, "/apps/{slug}": { "get": { "tags": [ "Catalog" ], "summary": "Get a one-click app by slug", "description": "Returns the latest active version of a single one-click app identified by its slug. Responds 404 when no active app matches the slug.", "operationId": "getapps_slug", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "slug", "in": "path", "required": true, "description": "App slug to look up (e.g. \"coolify\", \"wordpress\", \"postgresql\"). Matched against apps.slug where active = 1; ORDER BY id DESC LIMIT 1 returns the highest-id (newest) active row.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "example": { "app": { "uid": "app_coolify", "slug": "coolify", "version": "4.1.0", "name": "Coolify", "description": "Self-hostable PaaS to deploy apps and databases.", "logo": "https://cdn.suble.io/apps/coolify.svg", "category": "panel", "requirements": { "minVcpu": 2, "minMemoryMb": 4096, "minDiskGb": 40, "image": { "family": "ubuntu", "version": "24.04" } } } } } } }, "404": { "description": "app_not_found — No active app exists with the given slug" } } } }, "/projects": { "get": { "tags": [ "Projects & members" ], "summary": "List accessible projects", "description": "Returns every project the caller owns or is a member of. Staff callers see all projects in the system.", "operationId": "getprojects", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "example": [ { "uid": "prj_8kd2mq4zr1ab", "name": "Production", "category": "business", "role": "owner", "instanceCount": 3, "memberCount": 2, "createdAt": "2026-03-14T09:21:00.000Z" } ] } } } } }, "post": { "tags": [ "Projects & members" ], "summary": "Create a project", "description": "Creates a new project owned by the authenticated caller and returns the created project entity.", "operationId": "postprojects", "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "Project display name; coerced to string and trimmed, must be non-empty." }, "category": { "type": "string", "description": "Accepted per the router docstring ({ name, category? }) but ignored by the handler; the response category is always \"business\"." } }, "required": [ "name" ] }, "example": { "name": "Production", "category": "business" } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "example": { "uid": "prj_8kd2mq4zr1ab", "name": "Production", "category": "business", "role": "owner", "instanceCount": 0, "memberCount": 1, "createdAt": "2026-06-20T12:00:00.000Z" } } } }, "400": { "description": "invalid_name — `name` is missing, empty, or whitespace after trimming" } } } }, "/projects/{project}": { "get": { "tags": [ "Projects & members" ], "summary": "Get a project", "description": "Fetches a single project by its uid, with live instance and member counts.", "operationId": "getprojects_project", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "project", "in": "path", "required": true, "description": "Project uid (prj_ prefix).", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "example": { "uid": "prj_8kd2mq4zr1ab", "name": "Production", "category": "business", "role": "owner", "instanceCount": 3, "memberCount": 2, "createdAt": "2026-03-14T09:21:00.000Z" } } } }, "404": { "description": "not_found — Project passes middleware but the handler read-back returns nothing (rare)" } } }, "patch": { "tags": [ "Projects & members" ], "summary": "Update a project", "description": "Renames a project. Only the name field is mutable; returns the updated project.", "operationId": "patchprojects_project", "security": [ { "bearerAuth": [ "WRITE_SETTINGS" ] } ], "parameters": [ { "name": "project", "in": "path", "required": true, "description": "Project uid (prj_ prefix).", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "New project name; if non-null it is coerced to string and trimmed before update. If null/omitted the project is returned unchanged." } } }, "example": { "name": "Production EU" } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "example": { "uid": "prj_8kd2mq4zr1ab", "name": "Production EU", "category": "business", "role": "owner", "instanceCount": 3, "memberCount": 2, "createdAt": "2026-03-14T09:21:00.000Z" } } } }, "404": { "description": "not_found — Project row read-back returns nothing after the update" } } }, "delete": { "tags": [ "Projects & members" ], "summary": "Delete a project", "description": "Deletes a project and its member rows. Refuses if the project still has non-deleted instances.", "operationId": "deleteprojects_project", "security": [ { "bearerAuth": [ "WRITE_SETTINGS" ] } ], "parameters": [ { "name": "project", "in": "path", "required": true, "description": "Project uid (prj_ prefix).", "schema": { "type": "string" } } ], "responses": { "204": { "description": "Success" }, "404": { "description": "not_found — Project uid does not resolve to a row in the handler" }, "409": { "description": "project_not_empty — The project still has one or more instances whose status is not 'deleted'" } } } }, "/projects/{project}/members": { "get": { "tags": [ "Projects & members" ], "summary": "List project members", "description": "Lists the project owner plus all invited members with their role and acceptance status.", "operationId": "getprojects_project_members", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "project", "in": "path", "required": true, "description": "Project uid (prj_ prefix).", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "example": [ { "email": "owner@acme.com", "fullname": "Ada Owner", "role": "owner", "status": "accepted" }, { "email": "dev@acme.com", "fullname": "Dev Member", "role": "member", "status": "accepted" } ] } } } } }, "post": { "tags": [ "Projects & members" ], "summary": "Invite a project member", "description": "Adds an existing Suble user (by email) to the project as a member with full project permissions.", "operationId": "postprojects_project_members", "security": [ { "bearerAuth": [ "WRITE_MEMBERS" ] } ], "parameters": [ { "name": "project", "in": "path", "required": true, "description": "Project uid (prj_ prefix).", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "email": { "type": "string", "description": "Email of an existing Suble user to add; coerced to string, trimmed, and lower-cased." }, "role": { "type": "string", "description": "Documented in the router header ({ email, role? }) but ignored by the handler; all members receive the same MEMBER_PERMS bitmask." } }, "required": [ "email" ] }, "example": { "email": "dev@acme.com", "role": "member" } } } }, "responses": { "204": { "description": "Success" }, "400": { "description": "invalid_email — `email` is missing or empty after trimming" }, "404": { "description": "not_found — Project uid does not resolve in the handler" }, "409": { "description": "already_member — That user is already a member of the project" } } } }, "/projects/{project}/members/{email}": { "patch": { "tags": [ "Projects & members" ], "summary": "Update a member role (no-op)", "description": "Accepts a member role change. In the sandbox role is advisory (members always carry full permissions), so this is a no-op.", "operationId": "patchprojects_project_members_email", "security": [ { "bearerAuth": [ "WRITE_MEMBERS" ] } ], "parameters": [ { "name": "project", "in": "path", "required": true, "description": "Project uid (prj_ prefix).", "schema": { "type": "string" } }, { "name": "email", "in": "path", "required": true, "description": "Member email address (URL-encoded path segment).", "schema": { "type": "string" } } ], "responses": { "204": { "description": "Success" } } }, "delete": { "tags": [ "Projects & members" ], "summary": "Remove a project member", "description": "Removes a member from the project, matched by the member's email address.", "operationId": "deleteprojects_project_members_email", "security": [ { "bearerAuth": [ "WRITE_MEMBERS" ] } ], "parameters": [ { "name": "project", "in": "path", "required": true, "description": "Project uid (prj_ prefix).", "schema": { "type": "string" } }, { "name": "email", "in": "path", "required": true, "description": "Member email address; the handler decodeURIComponent-decodes the path segment.", "schema": { "type": "string" } } ], "responses": { "204": { "description": "Success" } } } }, "/projects/{project}/instances": { "get": { "tags": [ "Instances" ], "summary": "List instances in a project", "description": "Returns all non-deleted instances in the project with their plan, primary IP, image/app, and current job progress. Joins plans, public_ips, os_images, apps, and the active job for each instance.", "operationId": "getprojects_project_instances", "security": [ { "bearerAuth": [ "READ_VPS" ] } ], "parameters": [ { "name": "project", "in": "path", "required": true, "description": "Project uid (e.g. prj_xxxxxxxxxxxx)", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "example": { "instances": [ { "uid": "ins_a1b2c3d4e5f6", "name": "web-01", "status": "running", "power_state": "running", "backup_tier": "basic", "error_code": null, "error_message": null, "created_at": "2026-06-18T09:12:44.000Z", "plan_code": "bxs-2-4", "primary_ip": "185.234.12.7", "image_name": "Ubuntu 24.04 LTS", "app_slug": null, "app_name": null, "job_uid": null, "job_type": null, "progress_step": null, "progress_total": null, "progress_percent": null, "progress_message": null } ] } } } } } }, "post": { "tags": [ "Instances" ], "summary": "Create an instance", "description": "Provisions a new instance from an OS image, a project template, or an app. Validates the plan against image/app minimums, enqueues an async instance.create job, and returns 202 with the queued instance and job.", "operationId": "postprojects_project_instances", "security": [ { "bearerAuth": [ "ORDER_PRODUCT" ] } ], "parameters": [ { "name": "project", "in": "path", "required": true, "description": "Project uid", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "Hostname: lowercase RFC1123 label, regex ^[a-z0-9]([a-z0-9-]{0,62}[a-z0-9])?$. Must be unique among active instances in the project." }, "plan": { "type": "string", "description": "Plan code (e.g. bxs-2-4); must reference an active plan (active = 1)." }, "source": { "type": "object", "description": "Exactly one of {image: }, {template: