{ "openapi": "3.1.0", "info": { "title": "smolfleet API", "description": "Control plane for smolvm — deploy and run machines across a cluster.", "license": { "name": "Apache-2.0" }, "version": "0.1.0" }, "servers": [ { "url": "https://api.smolmachines.com", "description": "Hosted smolfleet" } ], "paths": { "/health": { "get": { "tags": [ "health" ], "summary": "Cluster health.", "description": "Returns aggregate cluster health. Public; no authentication.", "operationId": "health_check", "responses": { "200": { "description": "Cluster health", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClusterHealth" } } } } } } }, "/livez": { "get": { "tags": [ "health" ], "summary": "Liveness probe.", "description": "Returns 200 while the process is alive. Public; no authentication.", "operationId": "livez", "responses": { "200": { "description": "Process is alive" } } } }, "/metrics": { "get": { "tags": [ "health" ], "summary": "Prometheus metrics.", "description": "Returns Prometheus text-format metrics, including per-tenant counts. Requires the `admin` scope.", "operationId": "metrics", "responses": { "200": { "description": "Prometheus metrics (text)" }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Key lacks the required scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limited; retry after the Retry-After header", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/readyz": { "get": { "tags": [ "health" ], "summary": "Readiness probe.", "description": "Returns 200 when the state backend is reachable, 503 otherwise. Public; no authentication.", "operationId": "readyz", "responses": { "200": { "description": "Ready to serve" }, "503": { "description": "State backend unreachable" } } } }, "/v1/account": { "get": { "tags": [ "billing" ], "summary": "Get the caller's account.", "description": "Returns the caller's plan, effective limits, and period usage and spend. Requires the `usage:read` or `machine:read` scope.", "operationId": "account_get", "responses": { "200": { "description": "Tenant account: plan, effective limits, period usage + spend", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccountInfo" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Key lacks the required scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limited; retry after the Retry-After header", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/v1/account/attribution": { "post": { "tags": [ "billing" ], "summary": "Record signup attribution.", "description": "Stores where the account's first visit came from, once per account. Requires the `usage:read` or `machine:read` scope.", "operationId": "account_attribution", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SignupAttribution" } } }, "required": true }, "responses": { "200": { "description": "Whether the attribution was stored. False when the tenant already has one, is not a new account, or the report held nothing usable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SignupAttributionResponse" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Key lacks the required scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limited; retry after the Retry-After header", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/v1/account/plan": { "post": { "tags": [ "billing" ], "summary": "Change the account's plan.", "description": "Moves the account to a self-serve plan; a plan with a fee is billed through the card on file. Requires the `billing:write` scope.", "operationId": "account_plan_change", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChangePlanRequest" } } }, "required": true }, "responses": { "200": { "description": "The plan now in effect: a move onto a fee plan applies at once, a move off one when the paid period ends.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PlanInfo" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "402": { "description": "The plan's monthly fee has no saved card to bill (subscribe through /v1/account/plan/checkout instead), or the card was declined; the plan does not move.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Key lacks the required scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Current usage exceeds the target plan's limits, or this account's plan is already changing", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "That plan is not self-serve", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limited; retry after the Retry-After header", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Paid plans are not enabled on this deployment", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/v1/account/plan/checkout": { "post": { "tags": [ "billing" ], "summary": "Subscribe to a plan through Stripe Checkout.", "description": "Returns a Stripe-hosted page that shows the plan and its monthly price, takes a card and collects the first month. Once Stripe confirms the payment the account moves onto the plan and keeps the card for later charges. For an account with no card on file; with one, change plan directly. Requires the `billing:write` scope.", "operationId": "account_plan_checkout", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChangePlanRequest" } } }, "required": true }, "responses": { "200": { "description": "Returns {\"url\": } for a Stripe Checkout in subscription mode; the browser comes back to the console's billing page." }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Key lacks the required scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "The account is already on that plan, or already pays a plan fee", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "That plan is not self-serve, or has no monthly fee", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limited; retry after the Retry-After header", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Paid plans are not enabled on this deployment", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/v1/account/plans": { "get": { "tags": [ "billing" ], "summary": "List available plans.", "description": "Returns the self-serve plans this account can move to, with prices and limits. Any valid API key.", "operationId": "account_plans_list", "responses": { "200": { "description": "Plans this tenant may switch to itself", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AvailablePlansResponse" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Key lacks the required scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limited; retry after the Retry-After header", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/v1/agents": { "get": { "tags": [ "agents" ], "summary": "List agents.", "description": "Returns the agents in the caller's account. Requires the `machine:read` scope.", "operationId": "agent_list", "parameters": [ { "name": "after", "in": "query", "description": "Last session name from the previous page", "required": false, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "description": "Page size, 1-100 (default 20)", "required": false, "schema": { "type": "integer", "format": "int32", "minimum": 0 } } ], "responses": { "200": { "description": "Paginated agent session summaries", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentListPage" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Key lacks the required scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limited; retry after the Retry-After header", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] }, "post": { "tags": [ "agents" ], "summary": "Create an agent.", "description": "Creates a managed agent and the machine it runs in. Requires the `machine:create` scope.", "operationId": "agent_create", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateAgentRequest" } } }, "required": true }, "responses": { "202": { "description": "Session created; its machine and harness are set up in the background (status `starting`, then `ready` or `failed`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentInfo" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Key lacks the required scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "A session with that name exists", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limited; retry after the Retry-After header", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/v1/agents/{name}": { "get": { "tags": [ "agents" ], "summary": "Get an agent.", "description": "Returns one agent's state and its machine. Requires the `machine:read` scope.", "operationId": "agent_get", "parameters": [ { "name": "name", "in": "path", "description": "Session name", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Session with its turns", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentInfo" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Key lacks the required scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limited; retry after the Retry-After header", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] }, "delete": { "tags": [ "agents" ], "summary": "Delete an agent.", "description": "Deletes the agent and its machine. Requires the `machine:delete` scope.", "operationId": "agent_delete", "parameters": [ { "name": "name", "in": "path", "description": "Session name", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "Session, machine and unshared checkpoints deleted" }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Key lacks the required scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limited; retry after the Retry-After header", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/v1/agents/{name}/branch": { "post": { "tags": [ "agents" ], "summary": "Branch an agent.", "description": "Creates a new agent from a live copy-on-write branch of this agent's machine. Requires the `machine:create` scope.", "operationId": "agent_branch", "parameters": [ { "name": "name", "in": "path", "description": "Session name", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentBranchRequest" } } }, "required": true }, "responses": { "201": { "description": "New session from the state right after the turn", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentInfo" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Key lacks the required scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limited; retry after the Retry-After header", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/v1/agents/{name}/fork": { "post": { "tags": [ "agents" ], "summary": "Fork an agent.", "description": "Alias of branch: creates a new agent from a live branch of this agent's machine. Requires the `machine:create` scope.", "operationId": "agent_fork", "parameters": [ { "name": "name", "in": "path", "description": "Session name", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentForkRequest" } } }, "required": true }, "responses": { "201": { "description": "New session from the state right after the turn", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentInfo" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Key lacks the required scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limited; retry after the Retry-After header", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/v1/agents/{name}/pause": { "post": { "tags": [ "agents" ], "summary": "Pause an agent.", "description": "Checkpoints and stops the agent's machine so it can resume later. Requires the `machine:create` scope.", "operationId": "agent_pause", "parameters": [ { "name": "name", "in": "path", "description": "Session name", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "Paused; the next turn resumes it" }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Key lacks the required scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limited; retry after the Retry-After header", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/v1/agents/{name}/resume": { "post": { "tags": [ "agents" ], "summary": "Resume an agent.", "description": "Starts a paused agent's machine from its checkpoint. Requires the `machine:create` scope.", "operationId": "agent_resume", "parameters": [ { "name": "name", "in": "path", "description": "Session name", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "Resumed" }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Key lacks the required scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limited; retry after the Retry-After header", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/v1/agents/{name}/rewind": { "post": { "tags": [ "agents" ], "summary": "Rewind an agent.", "description": "Restores the agent to an earlier turn's checkpoint. Requires the `machine:create` scope.", "operationId": "agent_rewind", "parameters": [ { "name": "name", "in": "path", "description": "Session name", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentRewindRequest" } } }, "required": true }, "responses": { "200": { "description": "Session restored to the state right after the turn", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentInfo" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Key lacks the required scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limited; retry after the Retry-After header", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/v1/agents/{name}/turns": { "post": { "tags": [ "agents" ], "summary": "Send an agent a turn.", "description": "Starts a new turn with the given input. Requires the `machine:exec` scope.", "operationId": "agent_turn_send", "parameters": [ { "name": "name", "in": "path", "description": "Session name", "required": true, "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "description": "Retry the same turn without running it twice; a different request using the same key conflicts", "required": false, "schema": { "type": [ "string", "null" ] } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SendAgentTurnRequest" } } }, "required": true }, "responses": { "202": { "description": "Turn started; it runs whether or not a client stays connected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentTurnAccepted" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Key lacks the required scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "A turn is already running, or the session is not ready", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limited; retry after the Retry-After header", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/v1/agents/{name}/turns/{turn}/cancel": { "post": { "tags": [ "agents" ], "summary": "Cancel an agent turn.", "description": "Stops a turn that is still running. Requires the `machine:create` or `machine:exec` scope.", "operationId": "agent_turn_cancel", "parameters": [ { "name": "name", "in": "path", "description": "Session name", "required": true, "schema": { "type": "string" } }, { "name": "turn", "in": "path", "description": "Running turn number", "required": true, "schema": { "type": "integer", "format": "int64", "minimum": 0 } } ], "responses": { "204": { "description": "Turn cancelled and its machine stopped; the next turn restarts it" }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Key lacks the required scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Turn is not running", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limited; retry after the Retry-After header", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/v1/agents/{name}/turns/{turn}/events": { "get": { "tags": [ "agents" ], "summary": "Stream an agent turn's events.", "description": "Returns the events a turn produced, streaming while it runs. Requires the `machine:read` scope.", "operationId": "agent_turn_events", "parameters": [ { "name": "name", "in": "path", "description": "Session name", "required": true, "schema": { "type": "string" } }, { "name": "turn", "in": "path", "description": "Turn number", "required": true, "schema": { "type": "integer", "format": "int64", "minimum": 0 } }, { "name": "after", "in": "query", "description": "Replay only events numbered above this", "required": false, "schema": { "type": "integer", "format": "int64", "minimum": 0 } } ], "responses": { "200": { "description": "text/event-stream: an `event` per agent event (`id` = its number), then `done` with the finished turn" }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Key lacks the required scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limited; retry after the Retry-After header", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/v1/apikeys": { "get": { "tags": [ "apikeys" ], "summary": "List API keys.", "description": "Returns the account's API keys (metadata only, never the secret). Requires the `members:write` scope (owner or admin).", "operationId": "apikey_list", "responses": { "200": { "description": "List API keys", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/ApiKeyInfo" } } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Listing keys needs members:write, which an owner or an admin holds.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limited; retry after the Retry-After header", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] }, "post": { "tags": [ "apikeys" ], "summary": "Create an API key.", "description": "Mints a scoped API key; the plaintext secret is returned once, and a key never carries more scopes than its creator holds. Requires the `members:write` scope (owner or admin).", "operationId": "apikey_create", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateApiKeyRequest" } } }, "required": true }, "responses": { "201": { "description": "API key created; the plaintext key is in this response and nowhere else, and the key records the person it acts for.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiKeyCreated" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "402": { "description": "An organization with no payment method on file mints nothing", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Minting keys needs members:write, which an owner or an admin holds; or a scope the caller does not hold, or one no key may carry (anything under members:, billing: or key:, and admin or *), named in the message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "On an organization, personId is missing or does not name a member of it; on a personal account, personId names someone other than the caller.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limited; retry after the Retry-After header", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/v1/apikeys/{id}": { "delete": { "tags": [ "apikeys" ], "summary": "Revoke an API key.", "description": "Revokes an API key immediately; the key is kept with a revocation stamp. Requires the `members:write` scope (owner or admin).", "operationId": "apikey_delete", "parameters": [ { "name": "id", "in": "path", "description": "API key id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "API key revoked; the row stays with a revocation stamp." }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Revoking keys needs members:write, which an owner or an admin holds; on an organization a key with nobody behind it revokes nothing.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "No such key on this account", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limited; retry after the Retry-After header", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/v1/billing/auto-recharge": { "get": { "tags": [ "billing" ], "summary": "Get auto-recharge settings.", "description": "Returns the tenant's opt-in auto-recharge settings. Requires the `usage:read` or `machine:read` scope.", "operationId": "auto_recharge_get", "responses": { "200": { "description": "Current opt-in auto-recharge settings (effective threshold/amount + whether a card is saved)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AutoRechargeSettings" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Key lacks the required scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limited; retry after the Retry-After header", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] }, "post": { "tags": [ "billing" ], "summary": "Update auto-recharge settings.", "description": "Updates opt-in auto-recharge; enabling with no saved card returns a setup URL. Requires the `billing:write` scope.", "operationId": "auto_recharge_set", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateAutoRechargeRequest" } } }, "required": true }, "responses": { "200": { "description": "Updated auto-recharge settings. When enabling with no card on file, the response carries a setupUrl to add one.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AutoRechargeSettings" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Key lacks the required scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limited; retry after the Retry-After header", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/v1/billing/card": { "get": { "tags": [ "billing" ], "summary": "Get the card on file.", "description": "Returns the brand, last four digits and expiry of the card the account's plan fee and auto top-ups are charged to. Requires the `usage:read` or `machine:read` scope.", "operationId": "billing_card_get", "responses": { "200": { "description": "The card on file", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CardOnFile" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Key lacks the required scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "No card on file, or card payments are not enabled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limited; retry after the Retry-After header", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "502": { "description": "The payment provider did not answer", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/v1/billing/checkout-session": { "post": { "tags": [ "billing" ], "summary": "Start a prepaid top-up.", "description": "Starts a one-time Stripe Checkout to add prepaid credit; the wallet is credited when Stripe's webhook confirms payment. Requires the `billing:write` scope.", "operationId": "billing_checkout_session", "responses": { "200": { "description": "Start a one-time Stripe Checkout to add prepaid credit. Request body: {\"amount_usd\": <1..=2000>}. Returns {\"url\": }; redirect the browser there. The wallet is credited only when Stripe's webhook confirms payment." }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Key lacks the required scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limited; retry after the Retry-After header", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/v1/billing/meters": { "get": { "tags": [ "billing" ], "summary": "List tenant meters.", "description": "Returns per-tenant metered usage and cost for the period. Requires the `admin` scope.", "operationId": "billing_meters", "responses": { "200": { "description": "Per-tenant metered usage + cost for the period", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/TenantMeter" } } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Key lacks the required scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limited; retry after the Retry-After header", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/v1/billing/payment-method-setup": { "post": { "tags": [ "billing" ], "summary": "Start adding a payment method.", "description": "Returns a checkout URL where a card is saved for the account; an organization needs one before it can create anything that costs money. Requires the `billing:write` scope.", "operationId": "billing_payment_method_setup", "responses": { "200": { "description": "Returns {\"url\": } for a Stripe Checkout in setup mode that puts a card on file without charging it." }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Key lacks the required scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Card payments are not enabled on this deployment", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limited; retry after the Retry-After header", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/v1/cache-disks": { "get": { "tags": [ "cache-disks" ], "summary": "List cache disks.", "description": "Every cache disk in the caller's account, with its versions newest first. Requires the `machine:read` scope.", "operationId": "cache_disk_list", "responses": { "200": { "description": "Cache disks", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListCacheDisksResponse" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Key lacks the required scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limited; retry after the Retry-After header", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] }, "post": { "tags": [ "cache-disks" ], "summary": "Create a cache disk.", "description": "Creates a cache disk whose version 0 is an empty filesystem of `sizeGb`. Machines start from a version with `cacheDisk` on create, each through its own copy-on-write layer. Requires the `machine:create` scope.", "operationId": "cache_disk_create", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateCacheDiskRequest" } } }, "required": true }, "responses": { "201": { "description": "Cache disk created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CacheDiskInfo" } } } }, "400": { "description": "Invalid name, size or mount path", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Key lacks the required scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "A cache disk with that name exists", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Cache disks are not available on this platform", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limited; retry after the Retry-After header", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/v1/cache-disks/{id}": { "get": { "tags": [ "cache-disks" ], "summary": "Get a cache disk.", "description": "One cache disk by id or name, with its versions newest first. Requires the `machine:read` scope.", "operationId": "cache_disk_get", "parameters": [ { "name": "id", "in": "path", "description": "Cache disk id or name", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Cache disk", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CacheDiskInfo" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Key lacks the required scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limited; retry after the Retry-After header", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] }, "delete": { "tags": [ "cache-disks" ], "summary": "Delete a cache disk.", "description": "Deletes a cache disk and every version. Refused while a machine runs with it. Requires the `machine:delete` scope.", "operationId": "cache_disk_delete", "parameters": [ { "name": "id", "in": "path", "description": "Cache disk id or name", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "Deleted" }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Key lacks the required scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "A machine still runs with it", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limited; retry after the Retry-After header", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/v1/checkpoints": { "get": { "tags": [ "checkpoints" ], "summary": "List all checkpoints.", "description": "Returns every checkpoint the caller owns, newest first, including those whose\nmachine has since been deleted (`machineDeleted`), which stay restorable until\ndeleted themselves. Requires the `machine:read` scope.", "operationId": "checkpoint_list_all", "responses": { "200": { "description": "Portable checkpoints", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/PortableCheckpointInfo" } } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Key lacks the required scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limited; retry after the Retry-After header", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] }, "post": { "tags": [ "checkpoints" ], "summary": "Upload a checkpoint.", "description": "Starts uploading a `.checkpoint` file captured outside the cloud, such as a\nmachine checkpointed on a laptop. `PUT` each consecutive `partSizeBytes`\nslice of the file to the matching URL, then complete the upload. Requires the\n`machine:create` scope.", "operationId": "portable_checkpoint_upload", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateCheckpointUploadRequest" } } }, "required": true }, "responses": { "201": { "description": "Upload URLs for each part", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CheckpointUpload" } } } }, "400": { "description": "Key is not tenant-scoped", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Key lacks the required scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Size out of range", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limited; retry after the Retry-After header", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Checkpoint storage unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/v1/checkpoints/{id}": { "get": { "tags": [ "checkpoints" ], "summary": "Get a checkpoint.", "description": "Returns one checkpoint's metadata and lineage. Requires the `machine:read` scope.", "operationId": "portable_checkpoint_get", "parameters": [ { "name": "id", "in": "path", "description": "Portable checkpoint id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Capture status", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PortableCheckpointInfo" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Key lacks the required scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limited; retry after the Retry-After header", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] }, "delete": { "tags": [ "checkpoints" ], "summary": "Delete a checkpoint.", "description": "Deletes a stored checkpoint. Requires the `machine:delete` scope.", "operationId": "portable_checkpoint_delete", "parameters": [ { "name": "id", "in": "path", "description": "Portable checkpoint id", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "Portable checkpoint deleted" }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Key lacks the required scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Checkpoint is referenced by a machine", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limited; retry after the Retry-After header", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/v1/checkpoints/{id}/complete": { "post": { "tags": [ "checkpoints" ], "summary": "Complete a checkpoint upload.", "description": "Joins the uploaded parts and reads the checkpoint's manifest. The checkpoint\nis then `available` and can be restored. Requires the `machine:create` scope.", "operationId": "portable_checkpoint_complete", "parameters": [ { "name": "id", "in": "path", "description": "Portable checkpoint id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Checkpoint ready to restore", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PortableCheckpointInfo" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Key lacks the required scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Checkpoint is not an upload in progress", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Upload incomplete or not a restorable checkpoint", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limited; retry after the Retry-After header", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/v1/checkpoints/{id}/download": { "get": { "tags": [ "checkpoints" ], "summary": "Download a checkpoint.", "description": "Returns the checkpoint as a single portable file. Requires the `machine:files` or `machine:exec` scope.", "operationId": "portable_checkpoint_download", "parameters": [ { "name": "id", "in": "path", "description": "Portable checkpoint id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Portable .smolcheckpoint artifact" }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Key lacks the required scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Checkpoint is not available", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limited; retry after the Retry-After header", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/v1/checkpoints/{id}/restore": { "post": { "tags": [ "checkpoints" ], "summary": "Restore a checkpoint.", "description": "Creates a new machine from a checkpoint. Requires the `machine:create` scope.", "operationId": "portable_checkpoint_restore", "parameters": [ { "name": "id", "in": "path", "description": "Portable checkpoint id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestorePortableCheckpointRequest" } } }, "required": true }, "responses": { "201": { "description": "Stopped machine created from checkpoint", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MachineInfo" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Key lacks the required scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Checkpoint is not available", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limited; retry after the Retry-After header", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/v1/credentials": { "get": { "tags": [ "credentials" ], "summary": "List credentials.", "description": "Returns the names of stored credentials; values are never returned. Requires the `machine:read` scope.", "operationId": "credential_list", "responses": { "200": { "description": "Stored credentials, without their values", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/CredentialInfo" } } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Key lacks the required scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limited; retry after the Retry-After header", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/v1/credentials/{name}": { "put": { "tags": [ "credentials" ], "summary": "Set a credential.", "description": "Creates or replaces a stored credential that machines can use without seeing its value. Requires the `machine:create` scope.", "operationId": "credential_set", "parameters": [ { "name": "name", "in": "path", "description": "Credential name", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SetCredentialRequest" } } }, "required": true }, "responses": { "200": { "description": "Stored; machines bound to it use the new value from their next boot", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CredentialInfo" } } } }, "400": { "description": "Invalid name, variable, hosts or value", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Key lacks the required scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limited; retry after the Retry-After header", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] }, "delete": { "tags": [ "credentials" ], "summary": "Delete a credential.", "description": "Removes a stored credential so new machines no longer receive it. Requires the `machine:delete` scope.", "operationId": "credential_delete", "parameters": [ { "name": "name", "in": "path", "description": "Credential name", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "Deleted" }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Key lacks the required scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limited; retry after the Retry-After header", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/v1/groups": { "get": { "tags": [ "groups" ], "summary": "List deployment groups.", "description": "Returns every group in the caller's tenant with replica and instance status. Requires a valid API key for the tenant; no specific scope.", "operationId": "group_list", "responses": { "200": { "description": "List groups", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/GroupInfo" } } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Key lacks the required scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limited; retry after the Retry-After header", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] }, "post": { "tags": [ "groups" ], "summary": "Create or update a group deployment.", "description": "Deploys an image as a replicated group; re-deploying an existing name rolls it according to the requested strategy. Requires the `group:write` scope (legacy alias `app:write`).", "operationId": "group_deploy", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeployRequest" } } }, "required": true }, "responses": { "200": { "description": "Group deployed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GroupInfo" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Key lacks the required scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limited; retry after the Retry-After header", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/v1/groups/{name}": { "get": { "tags": [ "groups" ], "summary": "Get a group.", "description": "Returns one group's configuration and per-instance status. Requires a valid API key for the tenant; no specific scope.", "operationId": "group_get", "parameters": [ { "name": "name", "in": "path", "description": "Group name", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Group", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GroupInfo" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Key lacks the required scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limited; retry after the Retry-After header", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] }, "delete": { "tags": [ "groups" ], "summary": "Destroy a group.", "description": "Stops and removes every instance of the group. Requires the `group:write` scope (legacy alias `app:write`).", "operationId": "group_destroy", "parameters": [ { "name": "name", "in": "path", "description": "Group name", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "Destroyed" }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Key lacks the required scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limited; retry after the Retry-After header", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/v1/groups/{name}/logs": { "get": { "tags": [ "groups" ], "summary": "Stream group logs.", "description": "Streams log lines from the group's instances as text/event-stream. Requires a valid API key for the tenant; no specific scope.", "operationId": "group_logs", "parameters": [ { "name": "name", "in": "path", "description": "Group name", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Streamed log lines (text/event-stream)" }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Key lacks the required scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limited; retry after the Retry-After header", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/v1/groups/{name}/promote": { "post": { "tags": [ "groups" ], "summary": "Promote a canary.", "description": "Promotes the group's canary revision to stable. Requires the `group:write` scope (legacy alias `app:write`).", "operationId": "group_promote", "parameters": [ { "name": "name", "in": "path", "description": "Group name", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Canary promoted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GroupInfo" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Key lacks the required scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limited; retry after the Retry-After header", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/v1/groups/{name}/redeploy": { "post": { "tags": [ "groups" ], "summary": "Redeploy a group.", "description": "Re-pulls the group's image and rolls its instances. Requires the `group:write` scope (legacy alias `app:write`).", "operationId": "group_redeploy", "parameters": [ { "name": "name", "in": "path", "description": "Group name", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Redeployed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GroupInfo" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Key lacks the required scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limited; retry after the Retry-After header", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/v1/groups/{name}/scale": { "post": { "tags": [ "groups" ], "summary": "Scale a group.", "description": "Changes the group's replica count; new instances are placed immediately. Requires the `group:write` scope (legacy alias `app:write`).", "operationId": "group_scale", "parameters": [ { "name": "name", "in": "path", "description": "Group name", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ScaleRequest" } } }, "required": true }, "responses": { "200": { "description": "Scaled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GroupInfo" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Key lacks the required scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limited; retry after the Retry-After header", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/v1/machines": { "get": { "tags": [ "machines" ], "summary": "List machines.", "description": "Returns every machine in the caller's tenant. Requires the `machine:read` scope.", "operationId": "machine_list", "parameters": [ { "name": "label", "in": "query", "description": "Only machines carrying this label, as `key=value`. Repeat to require several labels (all must match).", "required": false, "schema": { "type": "array", "items": { "type": "string" } }, "explode": true } ], "responses": { "200": { "description": "List machines", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/MachineInfo" } } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Key lacks the required scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Malformed label filter", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limited; retry after the Retry-After header", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] }, "post": { "tags": [ "machines" ], "summary": "Create a machine.", "description": "Creates (and by default boots) a machine from an OCI image or packed artifact. Requires the `machine:create` scope.", "operationId": "machine_create", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateMachineRequest" } } }, "required": true }, "responses": { "201": { "description": "Machine created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MachineInfo" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Key lacks the required scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Name already exists", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Quota exceeded, invalid labels, or nestedVirt requested where the platform does not offer it (code nested_virt_unavailable)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limited; retry after the Retry-After header", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/v1/machines/{id}": { "get": { "tags": [ "machines" ], "summary": "Get a machine.", "description": "Returns one machine's configuration, state, and placement. Requires the `machine:read` scope.", "operationId": "machine_get", "parameters": [ { "name": "id", "in": "path", "description": "Machine id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Machine", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MachineInfo" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Key lacks the required scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limited; retry after the Retry-After header", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] }, "delete": { "tags": [ "machines" ], "summary": "Delete a machine.", "description": "Stops the machine if needed and removes it and its local storage. Requires the `machine:delete` scope.", "operationId": "machine_delete", "parameters": [ { "name": "id", "in": "path", "description": "Machine id", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "Deleted" }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Key lacks the required scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limited; retry after the Retry-After header", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/v1/machines/{id}/branches": { "post": { "tags": [ "machines" ], "summary": "Branch a machine.", "description": "Creates a live copy-on-write clone of a running machine. Requires the `machine:create` scope.", "operationId": "machine_branch", "parameters": [ { "name": "id", "in": "path", "description": "Branchable source machine id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForkRequest" } } }, "required": true }, "responses": { "201": { "description": "Child created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MachineInfo" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Key lacks the required scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limited; retry after the Retry-After header", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/v1/machines/{id}/branches/batch": { "post": { "tags": [ "machines" ], "summary": "Branch a machine many times.", "description": "Creates several live copy-on-write clones of a running machine in one call. Requires the `machine:create` scope.", "operationId": "machine_branch_batch", "parameters": [ { "name": "id", "in": "path", "description": "Branchable source machine id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForkBatchRequest" } } }, "required": true }, "responses": { "201": { "description": "Children created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForkBatchResponse" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Key lacks the required scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limited; retry after the Retry-After header", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/v1/machines/{id}/cache-disk/publish": { "post": { "tags": [ "cache-disks" ], "summary": "Publish a machine's cache disk.", "description": "Publishes a stopped machine's cache disk (the version it started from plus everything it wrote) as its cache disk's next version, which later machines can start from. Requires the `machine:create` scope.", "operationId": "machine_cache_disk_publish", "parameters": [ { "name": "id", "in": "path", "description": "Machine id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "New version published", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublishCacheDiskResponse" } } } }, "400": { "description": "The machine has no cache disk", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Key lacks the required scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Machine not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "The machine is running or has never run", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Cache disks are not available on this platform", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limited; retry after the Retry-After header", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/v1/machines/{id}/checkpoints": { "get": { "tags": [ "checkpoints" ], "summary": "List a machine's checkpoints.", "description": "Returns the checkpoints captured from a machine. Requires the `machine:read` scope.", "operationId": "portable_checkpoint_list", "parameters": [ { "name": "id", "in": "path", "description": "Machine id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Portable checkpoints", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/PortableCheckpointInfo" } } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Key lacks the required scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limited; retry after the Retry-After header", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] }, "post": { "tags": [ "checkpoints" ], "summary": "Create a checkpoint.", "description": "Captures the machine's full state as a portable checkpoint. Requires the `machine:create` scope.", "operationId": "portable_checkpoint_create", "parameters": [ { "name": "id", "in": "path", "description": "Running forkable machine id", "required": true, "schema": { "type": "string" } }, { "name": "wait", "in": "query", "description": "Defaults to true. False accepts a background capture; poll checkpoint status before restore.", "required": false, "schema": { "type": "boolean" } } ], "responses": { "201": { "description": "Portable checkpoint captured", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PortableCheckpointInfo" } } } }, "202": { "description": "Capture accepted, not yet durable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PortableCheckpointInfo" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Key lacks the required scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Machine is not ready for capture", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limited; retry after the Retry-After header", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/v1/machines/{id}/code": { "post": { "tags": [ "machines" ], "summary": "Execute a code snippet.", "description": "Runs a code snippet with the matching interpreter inside the machine and returns the result. Requires the `machine:exec` scope.", "operationId": "machine_code", "parameters": [ { "name": "id", "in": "path", "description": "Machine id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MachineCodeRequest" } } }, "required": true }, "responses": { "200": { "description": "Code result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MachineExecResponse" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Key lacks the required scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limited; retry after the Retry-After header", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/v1/machines/{id}/connect-token": { "post": { "tags": [ "machines" ], "summary": "Mint a connect token.", "description": "Returns a short-lived token that opens only this machine's connect bridge, `/v1/machines/{id}/connect/{port}`, and, by default, its descendants. Pass `port` to limit access to one published guest port, and `includeDescendants: false` to exclude branches. It is refused on every other endpoint, expires after `ttlSeconds` (3600 by default, never past the minting key's own expiry), and can be sent as the `access_token` query parameter on a WebSocket upgrade, so a client that cannot set headers, such as a DevTools client, can still connect. Requires the `machine:exec` scope.", "operationId": "machine_connect_token", "parameters": [ { "name": "id", "in": "path", "description": "Machine id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "description": "Optional; `ttlSeconds` from 60 to 86400, `port` for a single published guest port, and `includeDescendants: false` for this machine only", "content": { "application/json": { "schema": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/CreateConnectTokenRequest" } ] } } } }, "responses": { "201": { "description": "Connect token minted; the token is in this response and nowhere else", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConnectToken" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Key lacks the machine:exec scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Machine not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "ttlSeconds is out of range", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limited; retry after the Retry-After header", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/v1/machines/{id}/connect/{port}": { "get": { "tags": [ "machines" ], "summary": "Bridge to a guest port.", "description": "Forward an HTTP request (any method, body included, up to 10 MiB) or a WebSocket upgrade to a published guest port. Append a path after the port to reach a subpath: `/v1/machines/{id}/connect/{port}/{rest}`.", "operationId": "machine_connect", "parameters": [ { "name": "id", "in": "path", "description": "Machine id", "required": true, "schema": { "type": "string" } }, { "name": "port", "in": "path", "description": "Guest port to bridge to", "required": true, "schema": { "type": "integer", "format": "int32", "minimum": 0 } } ], "responses": { "101": { "description": "Switching to the machine's TCP bridge" }, "200": { "description": "The guest service's response, status and body passed through" }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Key lacks the required scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Machine or published port not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limited; retry after the Retry-After header", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Machine is not running", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] }, "put": { "tags": [ "machines" ], "summary": "Connect to a machine port (PUT).", "description": "Forward an HTTP request (any method, body included, up to 10 MiB) or a WebSocket upgrade to a published guest port. Append a path after the port to reach a subpath: `/v1/machines/{id}/connect/{port}/{rest}`.", "operationId": "machine_connect_put", "parameters": [ { "name": "id", "in": "path", "description": "Machine id", "required": true, "schema": { "type": "string" } }, { "name": "port", "in": "path", "description": "Guest port to bridge to", "required": true, "schema": { "type": "integer", "format": "int32", "minimum": 0 } } ], "requestBody": { "description": "Forwarded to the guest service unchanged", "content": { "*/*": { "schema": { "type": "string" } } }, "required": true }, "responses": { "101": { "description": "Switching to the machine's TCP bridge" }, "200": { "description": "The guest service's response, status and body passed through" }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Key lacks the required scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Machine or published port not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limited; retry after the Retry-After header", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Machine is not running", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] }, "post": { "tags": [ "machines" ], "summary": "Connect to a machine port (POST).", "description": "Forward an HTTP request (any method, body included, up to 10 MiB) or a WebSocket upgrade to a published guest port. Append a path after the port to reach a subpath: `/v1/machines/{id}/connect/{port}/{rest}`.", "operationId": "machine_connect_post", "parameters": [ { "name": "id", "in": "path", "description": "Machine id", "required": true, "schema": { "type": "string" } }, { "name": "port", "in": "path", "description": "Guest port to bridge to", "required": true, "schema": { "type": "integer", "format": "int32", "minimum": 0 } } ], "requestBody": { "description": "Forwarded to the guest service unchanged", "content": { "*/*": { "schema": { "type": "string" } } }, "required": true }, "responses": { "101": { "description": "Switching to the machine's TCP bridge" }, "200": { "description": "The guest service's response, status and body passed through" }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Key lacks the required scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Machine or published port not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limited; retry after the Retry-After header", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Machine is not running", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] }, "delete": { "tags": [ "machines" ], "summary": "Connect to a machine port (DELETE).", "description": "Forward an HTTP request (any method, body included, up to 10 MiB) or a WebSocket upgrade to a published guest port. Append a path after the port to reach a subpath: `/v1/machines/{id}/connect/{port}/{rest}`.", "operationId": "machine_connect_delete", "parameters": [ { "name": "id", "in": "path", "description": "Machine id", "required": true, "schema": { "type": "string" } }, { "name": "port", "in": "path", "description": "Guest port to bridge to", "required": true, "schema": { "type": "integer", "format": "int32", "minimum": 0 } } ], "responses": { "101": { "description": "Switching to the machine's TCP bridge" }, "200": { "description": "The guest service's response, status and body passed through" }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Key lacks the required scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Machine or published port not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limited; retry after the Retry-After header", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Machine is not running", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] }, "patch": { "tags": [ "machines" ], "summary": "Connect to a machine port (PATCH).", "description": "Forward an HTTP request (any method, body included, up to 10 MiB) or a WebSocket upgrade to a published guest port. Append a path after the port to reach a subpath: `/v1/machines/{id}/connect/{port}/{rest}`.", "operationId": "machine_connect_patch", "parameters": [ { "name": "id", "in": "path", "description": "Machine id", "required": true, "schema": { "type": "string" } }, { "name": "port", "in": "path", "description": "Guest port to bridge to", "required": true, "schema": { "type": "integer", "format": "int32", "minimum": 0 } } ], "requestBody": { "description": "Forwarded to the guest service unchanged", "content": { "*/*": { "schema": { "type": "string" } } }, "required": true }, "responses": { "101": { "description": "Switching to the machine's TCP bridge" }, "200": { "description": "The guest service's response, status and body passed through" }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Key lacks the required scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Machine or published port not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limited; retry after the Retry-After header", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Machine is not running", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/v1/machines/{id}/events": { "get": { "tags": [ "machines" ], "summary": "List machine events.", "description": "Returns the machine's lifecycle event history. Requires the `machine:read` scope.", "operationId": "machine_events", "parameters": [ { "name": "id", "in": "path", "description": "Machine id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Machine events", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/EventInfo" } } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Key lacks the required scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limited; retry after the Retry-After header", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/v1/machines/{id}/exec": { "post": { "tags": [ "machines" ], "summary": "Execute a command.", "description": "Runs a command in the machine and returns exit code, stdout, and stderr. Requires the `machine:exec` scope.", "operationId": "machine_exec", "parameters": [ { "name": "id", "in": "path", "description": "Machine id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MachineCommandRequest" } } }, "required": true }, "responses": { "200": { "description": "Command result. Buffered JSON by default; with `stream: true` in the body the response is an SSE stream of `event: stdout|stderr|error|exit` frames instead, terminated by `exit` carrying `{\"exitCode\": N}`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MachineExecResponse" } }, "text/event-stream": { "schema": { "type": "string" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Key lacks the required scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limited; retry after the Retry-After header", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/v1/machines/{id}/exec/interactive": { "get": { "tags": [ "machines" ], "summary": "Open an interactive terminal.", "description": "Upgrades to a WebSocket running a program on a pseudo-terminal in the machine. Requires the `machine:exec` scope.", "operationId": "machine_exec_interactive", "parameters": [ { "name": "id", "in": "path", "description": "Machine id", "required": true, "schema": { "type": "string" } }, { "name": "cmd", "in": "query", "description": "Program to run, a single path with no arguments (default: `/bin/sh`). `command` is accepted as an alias.", "required": false, "schema": { "type": "string" } }, { "name": "cols", "in": "query", "description": "Initial terminal width in columns", "required": false, "schema": { "type": "integer", "format": "int32", "minimum": 0 } }, { "name": "rows", "in": "query", "description": "Initial terminal height in rows", "required": false, "schema": { "type": "integer", "format": "int32", "minimum": 0 } }, { "name": "access_token", "in": "query", "description": "API key, for clients that cannot set an Authorization header on a WebSocket, such as browsers", "required": false, "schema": { "type": "string" } }, { "name": "smol_tenant", "in": "query", "description": "The account to act in, for a browser that cannot set the Smol-Tenant header on a WebSocket. Accepted on this handshake only, and only when the header is absent; a value that is not an account id is refused with 400", "required": false, "schema": { "type": "string" } } ], "responses": { "101": { "description": "Switching to a terminal WebSocket, started on the machine (a stopped machine is started first). Client to machine: binary frames are keystrokes; a text frame `{\"type\":\"resize\",\"cols\":N,\"rows\":N}` resizes the terminal; `{\"type\":\"stdin\",\"data\":\"...\"}` and any other text frame are typed as input. Machine to client: binary frames are terminal output; a final text frame `{\"type\":\"exit\",\"code\":N}` precedes the close. Closing the socket ends the program. The server pings every 30 seconds and ends a session whose client has not answered for 90 seconds; a connection lasts at most one hour, so long sessions should reconnect into a terminal multiplexer." }, "401": { "description": "Missing or invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Key lacks the required scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limited; retry after the Retry-After header", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "502": { "description": "The machine's terminal could not be reached", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/v1/machines/{id}/exec/stream": { "post": { "tags": [ "machines" ], "summary": "Run a command and stream its output.", "description": "Runs a command and returns stdout, stderr, and the exit code as Server-Sent Events. Requires the `machine:exec` scope.", "operationId": "machine_exec_stream", "parameters": [ { "name": "id", "in": "path", "description": "Machine id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MachineCommandRequest" } } }, "required": true }, "responses": { "200": { "description": "Command output as Server-Sent Events, written as it is produced and never truncated. Frames are `event: stdout|stderr|error|exit` with `data:` lines; the terminal `exit` frame carries `{\"exitCode\": N}`. Identical to `POST /v1/machines/{id}/exec` with `stream: true` — a dedicated path for clients that route by URL rather than by request body.", "content": { "text/event-stream": { "schema": { "type": "string" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Key lacks the required scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limited; retry after the Retry-After header", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/v1/machines/{id}/export": { "post": { "tags": [ "machines" ], "summary": "Export a machine.", "description": "Packs the machine's filesystem and pushes it to the registry as a reusable artifact. Requires the `machine:create` scope.", "operationId": "machine_export", "parameters": [ { "name": "id", "in": "path", "description": "Machine id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Machine exported to the registry as an artifact" }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Key lacks the required scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limited; retry after the Retry-After header", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/v1/machines/{id}/files/{path}": { "get": { "tags": [ "machines" ], "summary": "Download a file.", "description": "Reads the file at the given path inside the machine. Requires the `machine:files` scope.", "operationId": "machine_file_download", "parameters": [ { "name": "id", "in": "path", "description": "Machine id", "required": true, "schema": { "type": "string" } }, { "name": "path", "in": "path", "description": "Guest file path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "File bytes", "content": { "application/octet-stream": { "schema": { "type": "array", "items": { "type": "integer", "format": "int32", "minimum": 0 } } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Key lacks the required scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limited; retry after the Retry-After header", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] }, "put": { "tags": [ "machines" ], "summary": "Upload a file.", "description": "Writes the request body to the given path inside the machine. Requires the `machine:files` scope.", "operationId": "machine_file_upload", "parameters": [ { "name": "id", "in": "path", "description": "Machine id", "required": true, "schema": { "type": "string" } }, { "name": "path", "in": "path", "description": "Guest file path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/octet-stream": { "schema": { "type": "array", "items": { "type": "integer", "format": "int32", "minimum": 0 } } } }, "required": true }, "responses": { "200": { "description": "File uploaded" }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Key lacks the required scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limited; retry after the Retry-After header", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/v1/machines/{id}/fork": { "post": { "tags": [ "machines" ], "summary": "Fork a machine.", "description": "Creates a running copy-on-write clone of a forkable golden machine, inheriting its memory and filesystem state. Requires the `machine:create` scope.", "operationId": "machine_fork", "parameters": [ { "name": "id", "in": "path", "description": "Forkable golden machine id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForkRequest" } } }, "required": true }, "responses": { "201": { "description": "Clone created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MachineInfo" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Key lacks the required scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limited; retry after the Retry-After header", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/v1/machines/{id}/fork-batch": { "post": { "tags": [ "machines" ], "summary": "Fork a machine in batch.", "description": "Creates up to 64 clones of a forkable golden machine in one call. Requires the `machine:create` scope.", "operationId": "machine_fork_batch", "parameters": [ { "name": "id", "in": "path", "description": "Forkable golden machine id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForkBatchRequest" } } }, "required": true }, "responses": { "201": { "description": "Clones created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForkBatchResponse" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Key lacks the required scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limited; retry after the Retry-After header", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/v1/machines/{id}/jobs": { "get": { "tags": [ "machines" ], "summary": "List jobs.", "description": "A machine's jobs, newest first, as last recorded (up to 100). Get one job for its live state. Requires the `machine:read` scope.", "operationId": "machine_job_list", "parameters": [ { "name": "id", "in": "path", "description": "Machine id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Jobs", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MachineJobList" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Key lacks the required scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limited; retry after the Retry-After header", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] }, "post": { "tags": [ "machines" ], "summary": "Start a job.", "description": "Starts a command detached and returns at once. Its stdout, stderr and exit code are kept in the machine, so the caller can disconnect and poll `GET /v1/machines/{id}/jobs/{job_id}` and read output from an offset. A running job keeps the machine from auto-stopping. Wakes a stopped machine. The image needs `sh`. Requires the `machine:exec` scope.", "operationId": "machine_job_create", "parameters": [ { "name": "id", "in": "path", "description": "Machine id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MachineJobRequest" } } }, "required": true }, "responses": { "202": { "description": "The job is running", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MachineJob" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Key lacks the required scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "The job could not start in this machine", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limited; retry after the Retry-After header", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Retryable: the machine was unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/v1/machines/{id}/jobs/{job_id}": { "get": { "tags": [ "machines" ], "summary": "Get a job.", "description": "The job's live state: a running job's machine is asked whether it has finished. `lost` means the machine stopped or restarted while the job ran. Requires the `machine:read` scope.", "operationId": "machine_job_get", "parameters": [ { "name": "id", "in": "path", "description": "Machine id", "required": true, "schema": { "type": "string" } }, { "name": "job_id", "in": "path", "description": "Job id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "The job", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MachineJob" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Key lacks the required scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limited; retry after the Retry-After header", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Retryable: the machine was unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/v1/machines/{id}/jobs/{job_id}/cancel": { "post": { "tags": [ "machines" ], "summary": "Cancel a job.", "description": "Sends SIGTERM to a running job. Its exit code, 143, is recorded once it has stopped. Requires the `machine:exec` scope.", "operationId": "machine_job_cancel", "parameters": [ { "name": "id", "in": "path", "description": "Machine id", "required": true, "schema": { "type": "string" } }, { "name": "job_id", "in": "path", "description": "Job id", "required": true, "schema": { "type": "string" } } ], "responses": { "202": { "description": "The job, as it stands after the signal", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MachineJob" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Key lacks the required scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limited; retry after the Retry-After header", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Retryable: the machine was unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/v1/machines/{id}/jobs/{job_id}/output": { "get": { "tags": [ "machines" ], "summary": "Read job output.", "description": "A slice of the job's stdout or stderr from `offset`. Ask again from `nextOffset` until `eof`. Wakes a stopped machine, where the output is kept. Requires the `machine:exec` scope.", "operationId": "machine_job_output", "parameters": [ { "name": "id", "in": "path", "description": "Machine id", "required": true, "schema": { "type": "string" } }, { "name": "job_id", "in": "path", "description": "Job id", "required": true, "schema": { "type": "string" } }, { "name": "stream", "in": "query", "description": "`stdout` (default) or `stderr`", "required": false, "schema": { "type": "string" } }, { "name": "offset", "in": "query", "description": "Byte offset to start at (default 0)", "required": false, "schema": { "type": "integer", "format": "int64", "minimum": 0 } }, { "name": "limit", "in": "query", "description": "Most bytes to return (default 262144, at most 1048576)", "required": false, "schema": { "type": "integer", "format": "int64", "minimum": 0 } } ], "responses": { "200": { "description": "Output slice", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MachineJobOutput" } } } }, "400": { "description": "Unknown stream", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Key lacks the required scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found, or the output is gone from the machine", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limited; retry after the Retry-After header", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Retryable: the machine was unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/v1/machines/{id}/lineage": { "get": { "tags": [ "machines" ], "summary": "Get a machine's lineage.", "description": "Returns the machines and checkpoints this machine was branched or restored from. Requires the `machine:read` scope.", "operationId": "machine_lineage", "parameters": [ { "name": "id", "in": "path", "description": "Machine id in the lineage", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Complete branch lineage", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MachineLineage" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Key lacks the required scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limited; retry after the Retry-After header", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/v1/machines/{id}/logs": { "get": { "tags": [ "machines" ], "summary": "Stream machine console logs.", "description": "Streams the machine's console output as server-sent events; falls back to the archived log when the machine is not running. Requires the `machine:read` scope.", "operationId": "machine_logs", "parameters": [ { "name": "id", "in": "path", "description": "Machine id", "required": true, "schema": { "type": "string" } }, { "name": "follow", "in": "query", "description": "Keep the stream open and send new output as it is produced. Default false, which sends the backlog and ends the stream, so a client that wants to tail has to ask.", "required": false, "schema": { "type": "boolean" } }, { "name": "tail", "in": "query", "description": "Limit the initial backlog to the last N lines. Absent means the whole retained backlog, which on a long-lived machine is the reason a console asks for a bounded one.", "required": false, "schema": { "type": "integer", "minimum": 0 } } ], "responses": { "200": { "description": "Console log stream (server-sent events)", "content": { "text/plain": { "schema": { "type": "string" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Key lacks the required scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limited; retry after the Retry-After header", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/v1/machines/{id}/pause": { "post": { "tags": [ "machines" ], "summary": "Pause a machine.", "description": "Checkpoints the machine's memory and disks, then stops it so it can resume where it left off. Requires the `machine:create` scope.", "operationId": "machine_pause", "parameters": [ { "name": "id", "in": "path", "description": "Machine id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Execution saved durably and machine paused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MachineInfo" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Key lacks the required scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Machine cannot be paused in its current state", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limited; retry after the Retry-After header", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/v1/machines/{id}/resize": { "post": { "tags": [ "machines" ], "summary": "Resize a running machine.", "description": "Changes a running machine's vCPUs, memory or disk in place, without a restart. Fields left out keep their current value. Memory and disk only grow; vCPUs can also shrink. The new size must fit the plan's per-machine limits and the machine's node. Requires the `machine:create` scope.", "operationId": "machine_resize", "parameters": [ { "name": "id", "in": "path", "description": "Machine id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResizeMachineRequest" } } }, "required": true }, "responses": { "200": { "description": "Machine resized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MachineInfo" } } } }, "400": { "description": "Invalid size, or memory or disk asked to shrink", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Key lacks the required scope, or the size exceeds the plan", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Machine is not running, or its node has no room for the new size", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limited; retry after the Retry-After header", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/v1/machines/{id}/resume": { "post": { "tags": [ "machines" ], "summary": "Resume a machine.", "description": "Starts a paused machine from its checkpoint. Requires the `machine:create` scope.", "operationId": "machine_resume", "parameters": [ { "name": "id", "in": "path", "description": "Machine id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Saved execution resumed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MachineInfo" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Key lacks the required scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "No durable saved execution is ready", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limited; retry after the Retry-After header", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/v1/machines/{id}/rollback": { "post": { "tags": [ "checkpoints" ], "summary": "Roll a machine back to a checkpoint.", "description": "Replaces the machine's running state with one of its own checkpoints and\nstarts it again. Unlike a restore, the machine keeps its id, name, network\npolicy and credentials, so callers holding the id carry on as before. Work\ndone since the checkpoint is discarded. The machine must have no live\nbranches, since they share its running state.", "operationId": "machine_rollback", "parameters": [ { "name": "id", "in": "path", "description": "Machine id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RollbackMachineRequest" } } }, "required": true }, "responses": { "200": { "description": "Machine started from the checkpoint", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MachineInfo" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Key lacks the required scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "No usable checkpoint, the machine is busy, or it has live branches", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limited; retry after the Retry-After header", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "502": { "description": "The old machine could not be torn down or the checkpoint could not be restored", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/v1/machines/{id}/sessions": { "get": { "tags": [ "machines" ], "summary": "List exec sessions.", "description": "Returns the machine's open exec sessions. Requires the `machine:read` scope.", "operationId": "machine_session_list", "parameters": [ { "name": "id", "in": "path", "description": "Machine id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "List sessions", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/MachineSessionInfo" } } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Key lacks the required scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limited; retry after the Retry-After header", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] }, "post": { "tags": [ "machines" ], "summary": "Create an exec session.", "description": "Opens a persistent exec session whose working directory and environment survive between commands. Requires the `machine:exec` scope.", "operationId": "machine_session_create", "parameters": [ { "name": "id", "in": "path", "description": "Machine id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateMachineSessionRequest" } } }, "required": true }, "responses": { "200": { "description": "Session created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MachineSessionInfo" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Key lacks the required scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limited; retry after the Retry-After header", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/v1/machines/{id}/sessions/{session_id}": { "delete": { "tags": [ "machines" ], "summary": "Delete an exec session.", "description": "Closes an exec session and discards its state. Requires the `machine:exec` scope.", "operationId": "machine_session_delete", "parameters": [ { "name": "id", "in": "path", "description": "Machine id", "required": true, "schema": { "type": "string" } }, { "name": "session_id", "in": "path", "description": "Session id", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "Session deleted" }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Key lacks the required scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limited; retry after the Retry-After header", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/v1/machines/{id}/sessions/{session_id}/exec": { "post": { "tags": [ "machines" ], "summary": "Execute in a session.", "description": "Runs a command inside an existing session, inheriting its state. Requires the `machine:exec` scope.", "operationId": "machine_session_exec", "parameters": [ { "name": "id", "in": "path", "description": "Machine id", "required": true, "schema": { "type": "string" } }, { "name": "session_id", "in": "path", "description": "Session id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MachineCommandRequest" } } }, "required": true }, "responses": { "200": { "description": "Command result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MachineExecResponse" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Key lacks the required scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limited; retry after the Retry-After header", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/v1/machines/{id}/snapshot": { "post": { "tags": [ "machines" ], "summary": "Snapshot a machine.", "description": "Starts a durability snapshot of the machine's filesystem. Requires the `machine:create` scope.", "operationId": "machine_snapshot_create", "parameters": [ { "name": "id", "in": "path", "description": "Machine id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Durability snapshot started" }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Key lacks the required scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limited; retry after the Retry-After header", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/v1/machines/{id}/snapshots": { "get": { "tags": [ "machines" ], "summary": "List machine snapshots.", "description": "Returns the machine's durability snapshots. Requires the `machine:read` scope.", "operationId": "machine_snapshot_list", "parameters": [ { "name": "id", "in": "path", "description": "Machine id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "List durability snapshots" }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Key lacks the required scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limited; retry after the Retry-After header", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/v1/machines/{id}/start": { "post": { "tags": [ "machines" ], "summary": "Start a machine.", "description": "Boots a stopped machine, preserving its filesystem. Requires the `machine:create` scope.", "operationId": "machine_start", "parameters": [ { "name": "id", "in": "path", "description": "Machine id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Started", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MachineInfo" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Key lacks the required scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limited; retry after the Retry-After header", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/v1/machines/{id}/stop": { "post": { "tags": [ "machines" ], "summary": "Stop a machine.", "description": "Stops a running machine; billing for compute stops, storage persists. Requires the `machine:create` scope.", "operationId": "machine_stop", "parameters": [ { "name": "id", "in": "path", "description": "Machine id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Stopped", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MachineInfo" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Key lacks the required scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limited; retry after the Retry-After header", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/v1/machines/{id}/tunnel/{port}": { "get": { "tags": [ "machines" ], "summary": "Open a TCP tunnel to a machine port.", "description": "Upgrades to a WebSocket carrying raw TCP to a port inside the machine. Requires the `machine:exec` scope.", "operationId": "machine_tunnel", "parameters": [ { "name": "id", "in": "path", "description": "Tenant-owned running machine id", "required": true, "schema": { "type": "string" } }, { "name": "port", "in": "path", "description": "Published guest TCP port", "required": true, "schema": { "type": "integer", "format": "int32", "minimum": 0 } } ], "responses": { "101": { "description": "Binary WebSocket frames carry raw TCP bytes; requires machine:exec scope" }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Missing machine:exec scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Machine or published port not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limited; retry after the Retry-After header", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Machine is not running", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/v1/machines/{id}/usage": { "get": { "tags": [ "machines" ], "summary": "Get machine usage.", "description": "Returns the machine's metered usage and cost so far this billing period. Requires the `machine:read` scope.", "operationId": "machine_usage", "parameters": [ { "name": "id", "in": "path", "description": "Machine id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Usage and cost so far this billing period", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MachineUsageResponse" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Key lacks the required scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limited; retry after the Retry-After header", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/v1/me": { "get": { "tags": [ "billing" ], "summary": "Get caller identity.", "description": "Returns the caller's subject, tenant, scopes, and registry namespace. Requires any valid API key; no specific scope.", "operationId": "me_get", "responses": { "200": { "description": "Caller identity: subject, tenant, scopes, and the registry namespace it may push to", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MeResponse" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Key lacks the required scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limited; retry after the Retry-After header", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/v1/nodes": { "get": { "tags": [ "nodes" ], "summary": "List cluster nodes.", "description": "Returns every worker node with capacity and health. Requires the `admin` scope.", "operationId": "node_list", "responses": { "200": { "description": "List nodes", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/NodeInfo" } } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Key lacks the required scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limited; retry after the Retry-After header", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/v1/nodes/register": { "post": { "tags": [ "nodes" ], "summary": "Register a node.", "description": "Enrolls a worker node. Authenticated by a node join token in the Authorization header, not an API key.", "operationId": "node_register", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NodeInfo" } } }, "required": true }, "responses": { "200": { "description": "Node registered", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NodeInfo" } } } } } } }, "/v1/nodes/{id}/cordon": { "post": { "tags": [ "nodes" ], "summary": "Cordon a node.", "description": "Stops new machines from being placed on a node. Requires the `admin` scope.", "operationId": "node_cordon", "parameters": [ { "name": "id", "in": "path", "description": "Node id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "No new placements land on the node; what runs on it is untouched" }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Key lacks the required scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limited; retry after the Retry-After header", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/v1/nodes/{id}/credential": { "delete": { "tags": [ "nodes" ], "summary": "Revoke a node credential.", "description": "Invalidates the node's credential so it can no longer authenticate. Requires the `admin` scope.", "operationId": "node_credential_revoke", "parameters": [ { "name": "id", "in": "path", "description": "Node id", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "Credential revoked" }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Key lacks the required scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limited; retry after the Retry-After header", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/v1/nodes/{id}/drain": { "post": { "tags": [ "nodes" ], "summary": "Drain a node.", "description": "Marks a node as draining so no new machines are placed on it. Requires the `admin` scope.", "operationId": "node_drain", "parameters": [ { "name": "id", "in": "path", "description": "Node id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Node draining" }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Key lacks the required scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limited; retry after the Retry-After header", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/v1/nodes/{id}/heartbeat": { "post": { "tags": [ "nodes" ], "summary": "Node heartbeat.", "description": "Reports node liveness and capacity. Authenticated by the node's credential, not an API key.", "operationId": "node_heartbeat", "parameters": [ { "name": "id", "in": "path", "description": "Node id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Heartbeat accepted" } } } }, "/v1/nodes/{id}/uncordon": { "post": { "tags": [ "nodes" ], "summary": "Uncordon a node.", "description": "Lets a cordoned node receive new machines again. Requires the `admin` scope.", "operationId": "node_uncordon", "parameters": [ { "name": "id", "in": "path", "description": "Node id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Operator cordon lifted" }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Key lacks the required scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limited; retry after the Retry-After header", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/v1/operations": { "get": { "tags": [ "operations" ], "summary": "List async operations.", "description": "Returns recent asynchronous operations for the caller's tenant. Requires a valid API key for the tenant; no specific scope.", "operationId": "operation_list", "responses": { "200": { "description": "List operations" }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Key lacks the required scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limited; retry after the Retry-After header", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/v1/operations/{id}": { "get": { "tags": [ "operations" ], "summary": "Get an async operation.", "description": "Returns one asynchronous operation's status and result. Requires a valid API key for the tenant; no specific scope.", "operationId": "operation_get", "parameters": [ { "name": "id", "in": "path", "description": "Operation id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Operation" }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Key lacks the required scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limited; retry after the Retry-After header", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/v1/org": { "get": { "tags": [ "org" ], "summary": "Get the current organization.", "description": "Returns the organization the request acts in, with its machine counts. Any valid credential for that organization.", "operationId": "org_get", "responses": { "200": { "description": "The organization context of the account the request acts in, with how many machines it has and runs; the tenant id, slug and display name are null and the counts absent for an individual account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrgSummary" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Key lacks the required scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limited; retry after the Retry-After header", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] }, "post": { "tags": [ "org" ], "summary": "Create an organization.", "description": "Creates an organization with the caller as its owner. Requires a user login, not an API key.", "operationId": "org_create", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateOrgRequest" } } }, "required": true }, "responses": { "201": { "description": "Organization created on the default plan with the caller as its owner; the body carries the tenant id that Smol-Tenant names.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrgSummary" } } } }, "400": { "description": "Slug outside the allowed shape, or display name outside 1 to 100 characters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "The caller authenticated with an API key rather than a user login", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "That identifier is already taken", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limited; retry after the Retry-After header", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] }, "delete": { "tags": [ "org" ], "summary": "Delete an organization.", "description": "Deletes the organization the request acts in, once it holds no machines or balance and its subscription is cancelled. Requires a user login, not an API key, held by the organization's owner.", "operationId": "org_delete", "responses": { "204": { "description": "Organization deleted, with its plan fee subscription ended and its keys, membership rows, registry entries, custom domains, registry credentials and leases gone; the account is marked deleted." }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Only an owner can delete an organization, or the caller is an API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "The organization still owns a machine, a volume, a pool, a checkpoint or a snapshot, holds credit on its balance, or owes for the period, each named in the message", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "An individual account, not an organization", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limited; retry after the Retry-After header", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "The plan fee subscription could not be ended at Stripe, or plan billing is not enabled here; nothing was deleted.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] }, "patch": { "tags": [ "org" ], "summary": "Rename an organization.", "description": "Changes the organization's display name. Requires a user login, not an API key, and the `members:write` scope (owner or admin).", "operationId": "org_rename", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RenameOrgRequest" } } }, "required": true }, "responses": { "200": { "description": "Renamed; only the display label changes, since the slug is final, and the body reads as GET /v1/org does without the counts.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrgSummary" } } } }, "400": { "description": "A display name outside 1 to 100 characters after trimming", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Renaming an organization is an owner or admin action, or the caller is an API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "An individual account, not an organization", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limited; retry after the Retry-After header", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/v1/org/convert": { "post": { "tags": [ "org" ], "summary": "Convert your own account into an organization.", "description": "Makes the caller's own account an organization in place, with them as its owner; its machines, keys, registry entries, balance and card are unchanged. Requires a user login, not an API key.", "operationId": "org_convert", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConvertOrgRequest" } } }, "required": true }, "responses": { "200": { "description": "The caller's own account is now an organization with them as its owner; its machines, keys, registry entries, balance and card are unchanged.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrgSummary" } } } }, "400": { "description": "A display name outside 1 to 100 characters after trimming", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "402": { "description": "The account has no card on file, which an organization needs before it can create anything", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "The caller authenticated with an API key, or is working in an account other than their own", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "The account is already an organization", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limited; retry after the Retry-After header", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/v1/org/invitations": { "get": { "tags": [ "org" ], "summary": "List pending invitations.", "description": "Returns the organization's invitations that have not been accepted. Requires the `members:write` scope (owner or admin).", "operationId": "org_invitations_list", "responses": { "200": { "description": "The invitations this organization still waits on, oldest first, without their tokens.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/OrgInvitation" } } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Reading the pending list is an owner or admin action", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "An individual account, not an organization", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limited; retry after the Retry-After header", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/v1/org/invitations/accept": { "post": { "tags": [ "org" ], "summary": "Accept an invitation.", "description": "Joins the organization an invitation names; it must be addressed to the login's verified email. Requires a user login, not an API key.", "operationId": "org_invitation_accept", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AcceptInvitationRequest" } } }, "required": true }, "responses": { "200": { "description": "Joined, answering the membership as the switcher lists it; name the invitation by the link's token or the pending list's id, and its address must match the login's verified one.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrgMembership" } } } }, "400": { "description": "Named neither a token nor an id", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "The invitation was sent to a different address than the one signed in with, the account has no verified address, or the caller is an API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "No such invitation, or it has been taken up or withdrawn", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Already on that organization", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "410": { "description": "The invitation has expired", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limited; retry after the Retry-After header", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/v1/org/invitations/mine": { "get": { "tags": [ "org" ], "summary": "List your invitations.", "description": "Returns the invitations addressed to the logged-in person's verified email. Requires a user login, not an API key.", "operationId": "org_invitations_mine", "responses": { "200": { "description": "Every invitation waiting on the login's verified address, oldest first, each naming its organization; no Smol-Tenant header or members scope is needed.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/PendingInvitation" } } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "The caller authenticated with an API key rather than a user login, or has no verified address", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limited; retry after the Retry-After header", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/v1/org/invitations/{id}": { "delete": { "tags": [ "org" ], "summary": "Withdraw an invitation.", "description": "Cancels a pending invitation so its link no longer works. Requires a user login, not an API key, and the `members:write` scope (owner or admin).", "operationId": "org_invitation_revoke", "parameters": [ { "name": "id", "in": "path", "description": "The invitation's id, as the pending list reports it", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "Invitation withdrawn; the row is deleted, so the emailed link stops resolving." }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Withdrawing an invitation is an owner or admin action, or the caller is an API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "No pending invitation with that id on this organization", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "An individual account, not an organization", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limited; retry after the Retry-After header", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/v1/org/invitations/{id}/resend": { "post": { "tags": [ "org" ], "summary": "Resend an invitation.", "description": "Sends the invitation again with a new link, which replaces the old one. Requires a user login, not an API key, and the `members:write` scope (owner or admin).", "operationId": "org_invitation_resend", "parameters": [ { "name": "id", "in": "path", "description": "The invitation's id, as the pending list reports it", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Sent again with a new link on the same row, restarting the seven days; the previous link stops resolving.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InviteResult" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Resending an invitation is an owner or admin action, or the caller is an API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "No pending invitation with that id on this organization, or it has been taken up or withdrawn", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "410": { "description": "The invitation has expired; invite again", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "An individual account, not an organization", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limited; retry after the Retry-After header", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/v1/org/members": { "get": { "tags": [ "org" ], "summary": "List organization members.", "description": "Returns the people in the organization and their roles. Requires the `members:read` or `members:write` scope.", "operationId": "org_members_list", "parameters": [ { "name": "limit", "in": "query", "description": "How many people to return, 1 to 200, default 100; a larger value is clamped to 200.", "required": false, "schema": { "type": "integer", "format": "int32", "minimum": 0 } }, { "name": "offset", "in": "query", "description": "How many people to skip, default 0.", "required": false, "schema": { "type": "integer", "format": "int32", "minimum": 0 } } ], "responses": { "200": { "description": "One page of the roster, oldest first, each with the person's account id as userId, their membership email and their role as a one-element roles list; empty for an individual account.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/OrgMember" } } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Reading the roster needs members:read or members:write, which every role holds", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limited; retry after the Retry-After header", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/v1/org/members/invite": { "post": { "tags": [ "org" ], "summary": "Invite a member.", "description": "Emails an invitation to join the organization with a given role. Requires a user login, not an API key, and the `members:write` scope (owner or admin).", "operationId": "org_member_invite", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InviteMemberRequest" } } }, "required": true }, "responses": { "201": { "description": "Invitation recorded and, with a mail provider configured, sent; the body carries the accept link, the only readable copy of the token, which lapses in seven days.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InviteResult" } } } }, "400": { "description": "Not an email address, or a role other than owner, admin or member", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "402": { "description": "The organization has no payment method on file", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Inviting is an owner or admin action, or the caller is an API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "That address already has an outstanding invitation to this organization, or is already on its roster", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "An individual account, not an organization", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limited; retry after the Retry-After header", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/v1/org/members/{id}": { "delete": { "tags": [ "org" ], "summary": "Remove a member.", "description": "Removes the person from the organization and revokes their API keys in the same step. Requires a user login, not an API key, and the `members:write` scope (owner or admin).", "operationId": "org_member_remove", "parameters": [ { "name": "id", "in": "path", "description": "The member's account id as the roster reports it in userId, or \"me\" to leave, which needs no role.", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Removed; the body names the organization's API keys revoked with them and the machines they created that are left running.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RemoveMemberResult" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Taking somebody else off is an owner or admin action, or the caller is an API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "That person is not on this organization", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "The removal would leave the organization with no owner; the message names the way out", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "An individual account, not an organization", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limited; retry after the Retry-After header", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/v1/org/members/{id}/role": { "patch": { "tags": [ "org" ], "summary": "Change a member's role.", "description": "Sets a member's role; an organization always keeps at least one owner. Requires a user login, not an API key, and the `members:write` scope (owner or admin).", "operationId": "org_member_role", "parameters": [ { "name": "id", "in": "path", "description": "The member's account id, as the roster reports it in userId", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SetRoleRequest" } } }, "required": true }, "responses": { "204": { "description": "Role changed; it takes effect on that person's next request." }, "400": { "description": "A role other than owner, admin or member", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Changing a role is an owner or admin action, or the caller is an API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "That person is not on this organization", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "The change would leave the organization with no owner; the message names the way out", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "An individual account, not an organization", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limited; retry after the Retry-After header", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/v1/org/memberships": { "get": { "tags": [ "org" ], "summary": "List your organizations.", "description": "Returns every organization the logged-in person belongs to, for switching accounts. Requires a user login, not an API key.", "operationId": "org_memberships", "responses": { "200": { "description": "Every organization the caller belongs to, most recently used first, with their role and the account's status; empty for a person on none.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/OrgMembership" } } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "The caller authenticated with an API key rather than a user login", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limited; retry after the Retry-After header", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/v1/plans": { "get": { "tags": [ "plans" ], "summary": "List plans.", "description": "Returns the configured quota/rate/budget plans. Requires the `admin` scope.", "operationId": "plan_list", "responses": { "200": { "description": "List plans", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/PlanInfo" } } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Key lacks the required scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limited; retry after the Retry-After header", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] }, "post": { "tags": [ "plans" ], "summary": "Create a plan.", "description": "Creates a quota/rate/budget plan tenants can be assigned to. Requires the `admin` scope.", "operationId": "plan_create", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreatePlanRequest" } } }, "required": true }, "responses": { "201": { "description": "Plan created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PlanInfo" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Key lacks the required scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limited; retry after the Retry-After header", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/v1/plans/{id}": { "patch": { "tags": [ "plans" ], "summary": "Update a plan.", "description": "Changes a plan's price or limits. Requires the `admin` scope.", "operationId": "plan_update", "parameters": [ { "name": "id", "in": "path", "description": "Plan id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdatePlanRequest" } } }, "required": true }, "responses": { "200": { "description": "Plan updated; applies from the next machine create", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PlanInfo" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Key lacks the required scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Plan not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limited; retry after the Retry-After header", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/v1/pricing": { "get": { "tags": [ "usage" ], "summary": "Get the public rate card.", "description": "Returns per-unit rates and the volume schedule. Public; no authentication.", "operationId": "pricing_get", "responses": { "200": { "description": "Public rate card", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicPricing" } } } } } } }, "/v1/status/machines": { "get": { "tags": [ "usage" ], "summary": "Get public machine statistics.", "description": "Returns the lifetime count of machines started on the platform. Public; no API key needed.", "operationId": "machine_stats_get", "responses": { "200": { "description": "Lifetime count of machines started by customers", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicMachineStats" } } } } } } }, "/v1/tenants": { "get": { "tags": [ "tenants" ], "summary": "List tenants.", "description": "Returns every tenant. Requires the `admin` scope.", "operationId": "tenant_list", "responses": { "200": { "description": "List tenants", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/TenantInfo" } } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Key lacks the required scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limited; retry after the Retry-After header", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] }, "post": { "tags": [ "tenants" ], "summary": "Create a tenant.", "description": "Creates a tenant with the given plan and limits. Requires the `admin` scope.", "operationId": "tenant_create", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateTenantRequest" } } }, "required": true }, "responses": { "201": { "description": "Tenant created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TenantInfo" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Key lacks the required scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limited; retry after the Retry-After header", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/v1/tenants/{id}": { "get": { "tags": [ "tenants" ], "summary": "Get a tenant.", "description": "Returns one tenant's plan, limits, and status. Requires the `admin` scope.", "operationId": "tenant_get", "parameters": [ { "name": "id", "in": "path", "description": "Tenant id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Tenant", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TenantInfo" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Key lacks the required scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limited; retry after the Retry-After header", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] }, "patch": { "tags": [ "tenants" ], "summary": "Update a tenant.", "description": "Patches a tenant's plan, limits, or metadata. Requires the `admin` scope.", "operationId": "tenant_update", "parameters": [ { "name": "id", "in": "path", "description": "Tenant id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateTenantRequest" } } }, "required": true }, "responses": { "200": { "description": "Updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TenantInfo" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Key lacks the required scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limited; retry after the Retry-After header", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/v1/tenants/{id}/reactivate": { "post": { "tags": [ "tenants" ], "summary": "Reactivate a tenant.", "description": "Lifts a tenant's suspension. Requires the `admin` scope.", "operationId": "tenant_reactivate", "parameters": [ { "name": "id", "in": "path", "description": "Tenant id", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "Reactivated" }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Key lacks the required scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limited; retry after the Retry-After header", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/v1/tenants/{id}/suspend": { "post": { "tags": [ "tenants" ], "summary": "Suspend a tenant.", "description": "Suspends a tenant; its API calls fail with 402 until reactivated. Requires the `admin` scope.", "operationId": "tenant_suspend", "parameters": [ { "name": "id", "in": "path", "description": "Tenant id", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "Suspended" }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Key lacks the required scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limited; retry after the Retry-After header", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/v1/tokens": { "get": { "tags": [ "tokens" ], "summary": "List join tokens.", "description": "Returns the cluster's node join tokens. Requires the `admin` scope.", "operationId": "token_list", "responses": { "200": { "description": "List join tokens" }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Key lacks the required scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limited; retry after the Retry-After header", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] }, "post": { "tags": [ "tokens" ], "summary": "Create a join token.", "description": "Mints a join token a new worker node can register with. Requires the `admin` scope.", "operationId": "token_create", "responses": { "200": { "description": "Join token created" }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Key lacks the required scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limited; retry after the Retry-After header", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/v1/tokens/{prefix}": { "delete": { "tags": [ "tokens" ], "summary": "Delete a join token.", "description": "Revokes a join token by prefix. Requires the `admin` scope.", "operationId": "token_delete", "parameters": [ { "name": "prefix", "in": "path", "description": "Token prefix", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "Token deleted" }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Key lacks the required scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limited; retry after the Retry-After header", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/v1/usage": { "get": { "tags": [ "usage" ], "summary": "Query usage.", "description": "Returns metered usage for the caller's tenant over the requested period. Requires the `usage:read` or `machine:read` scope.", "operationId": "usage_query", "responses": { "200": { "description": "Usage report", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UsageResponse" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Key lacks the required scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limited; retry after the Retry-After header", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/v1/volumes": { "get": { "tags": [ "volumes" ], "summary": "List volumes.", "description": "Returns every persistent volume in the caller's tenant. Requires a valid API key for the tenant; no specific scope.", "operationId": "volume_list", "responses": { "200": { "description": "List volumes", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/VolumeInfo" } } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Key lacks the required scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limited; retry after the Retry-After header", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] }, "post": { "tags": [ "volumes" ], "summary": "Create a volume.", "description": "Creates a persistent volume that can be mounted into machines. Requires a valid API key for the tenant; no specific scope.", "operationId": "volume_create", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateVolumeRequest" } } }, "required": true }, "responses": { "200": { "description": "Volume created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VolumeInfo" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Key lacks the required scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limited; retry after the Retry-After header", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/v1/volumes/{id}": { "get": { "tags": [ "volumes" ], "summary": "Get a volume.", "description": "Returns one volume's configuration and attachment state. Requires a valid API key for the tenant; no specific scope.", "operationId": "volume_get", "parameters": [ { "name": "id", "in": "path", "description": "Volume id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Volume", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VolumeInfo" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Key lacks the required scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limited; retry after the Retry-After header", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] }, "delete": { "tags": [ "volumes" ], "summary": "Delete a volume.", "description": "Removes an unattached volume and its data. Requires a valid API key for the tenant; no specific scope.", "operationId": "volume_delete", "parameters": [ { "name": "id", "in": "path", "description": "Volume id", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "Volume deleted" }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Key lacks the required scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limited; retry after the Retry-After header", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } } }, "components": { "schemas": { "AcceptInvitationRequest": { "type": "object", "description": "Body of `POST /v1/org/invitations/accept`: the token out of the link.", "properties": { "id": { "type": [ "string", "null" ], "description": "The invitation's id from `GET /v1/org/invitations/mine`, a handle not a credential." }, "token": { "type": [ "string", "null" ], "description": "The token from the emailed link, absent when accepting from the pending list." } } }, "AccountInfo": { "type": "object", "description": "The tenant self-service account view: plan, effective limits, usage, spend.", "required": [ "tenantId", "status", "effectiveMaxCpus", "effectiveMaxMemoryMb", "effectiveMaxDiskGb", "effectiveMaxMachines", "periodUsage", "periodCost" ], "properties": { "budgetRemainingMicros": { "type": [ "integer", "null" ], "format": "int64", "minimum": 0 }, "effectiveMaxCpus": { "type": "integer", "format": "int32", "minimum": 0 }, "effectiveMaxDiskGb": { "type": "integer", "format": "int64", "description": "Largest disk (GB) one machine may request on this account.", "minimum": 0 }, "effectiveMaxMachines": { "type": "integer", "format": "int32", "minimum": 0 }, "effectiveMaxMemoryMb": { "type": "integer", "format": "int64", "minimum": 0 }, "lowBalanceThresholdMicros": { "type": "integer", "format": "int64", "description": "Effective low-balance email threshold (micros): the balance at which a\nlow-balance warning email fires. Always the resolved value — the\nper-tenant override if set, else the platform default. `0` means the\ncustomer has turned the email off.", "minimum": 0 }, "monthlyBudgetMicros": { "type": [ "integer", "null" ], "format": "int64", "minimum": 0 }, "pendingPlanId": { "type": [ "string", "null" ], "description": "The plan the account moves to when its paid period ends, or null if none is scheduled." }, "periodCost": { "$ref": "#/components/schemas/CostBreakdown" }, "periodUsage": { "$ref": "#/components/schemas/UsageResponse" }, "plan": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/PlanInfo" } ] }, "prepaidCreditMicros": { "type": "integer", "format": "int64", "description": "Prepaid wallet balance (micros). Topped up via Stripe Checkout; drawn down\nby metered usage. 0 for tenants that have never added credit.", "minimum": 0 }, "status": { "type": "string" }, "tenantId": { "type": "string" } } }, "AgentBranchRequest": { "type": "object", "description": "Start a new session `name` from the state right after `turn`.", "required": [ "turn", "name" ], "properties": { "name": { "type": "string" }, "turn": { "type": "integer", "format": "int64", "minimum": 0 } } }, "AgentForkRequest": { "type": "object", "description": "Start a new session `name` from the state right after `turn`.", "required": [ "turn", "name" ], "properties": { "name": { "type": "string" }, "turn": { "type": "integer", "format": "int64", "minimum": 0 } } }, "AgentInfo": { "type": "object", "description": "A managed agent session.", "required": [ "name", "harness", "status", "turns", "createdAt" ], "properties": { "createdAt": { "type": "string" }, "error": { "type": [ "string", "null" ] }, "harness": { "type": "string" }, "machineId": { "type": [ "string", "null" ], "description": "The machine the session currently runs on (it changes on rewind)." }, "model": { "type": [ "string", "null" ] }, "name": { "type": "string" }, "runningTurn": { "type": [ "integer", "null" ], "format": "int64", "description": "The turn in progress, if any.", "minimum": 0 }, "status": { "type": "string", "description": "`starting` during setup, `turning` during a turn, `cancelling`,\n`rewinding`, `forking`, `pausing`, `resuming`, `ready`, `deleting`, or\n`failed`; stale work may read as `interrupted`." }, "turns": { "type": "array", "items": { "$ref": "#/components/schemas/AgentTurnInfo" } } } }, "AgentListPage": { "type": "object", "required": [ "items" ], "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/AgentSummary" } }, "nextCursor": { "type": [ "string", "null" ] } } }, "AgentRewindRequest": { "type": "object", "description": "Return a session to the state right after `turn`.", "required": [ "turn" ], "properties": { "turn": { "type": "integer", "format": "int64", "minimum": 0 } } }, "AgentSummary": { "type": "object", "description": "A session entry for the paginated list. Turn history is fetched from the\nsession detail rather than repeated for every session in the account.", "required": [ "name", "harness", "status", "createdAt" ], "properties": { "createdAt": { "type": "string" }, "error": { "type": [ "string", "null" ] }, "harness": { "type": "string" }, "machineId": { "type": [ "string", "null" ] }, "model": { "type": [ "string", "null" ] }, "name": { "type": "string" }, "runningTurn": { "type": [ "integer", "null" ], "format": "int64", "minimum": 0 }, "status": { "type": "string" } } }, "AgentTurnAccepted": { "type": "object", "description": "A turn that was accepted and is running.", "required": [ "turn" ], "properties": { "turn": { "type": "integer", "format": "int64", "minimum": 0 } } }, "AgentTurnInfo": { "type": "object", "description": "One turn of a managed agent session.", "required": [ "index", "prompt", "status", "isError", "checkpointed", "startedAt" ], "properties": { "checkpointed": { "type": "boolean", "description": "Whether the session can be rewound or branched to this turn." }, "costUsd": { "type": [ "number", "null" ], "format": "double", "description": "What the turn cost at the model provider, when the harness reports it." }, "finishedAt": { "type": [ "string", "null" ] }, "index": { "type": "integer", "format": "int64", "minimum": 0 }, "isError": { "type": "boolean" }, "prompt": { "type": "string" }, "result": { "type": [ "string", "null" ], "description": "The agent's final answer, or why the turn failed." }, "startedAt": { "type": "string" }, "status": { "type": "string", "description": "`preparing`, `running`, `cancelling`, `cancelled`, `done`, `failed`, or `interrupted`." } } }, "ApiKeyCreated": { "type": "object", "required": [ "id", "key" ], "properties": { "id": { "type": "string" }, "key": { "type": "string" } } }, "ApiKeyInfo": { "type": "object", "required": [ "id", "scopes", "createdAt" ], "properties": { "createdAt": { "type": "string" }, "createdBy": { "type": [ "string", "null" ], "description": "The account id of the person behind this key; null when nobody is." }, "description": { "type": [ "string", "null" ] }, "expiresAt": { "type": [ "string", "null" ] }, "id": { "type": "string" }, "lastUsedAt": { "type": [ "string", "null" ] }, "scopes": { "type": "array", "items": { "type": "string" } } } }, "AutoRechargeSettings": { "type": "object", "description": "Threshold/amount are the RESOLVED effective values (per-tenant override, else\nfleet default), so the UI can render exactly what will happen.", "required": [ "enabled", "thresholdMicros", "amountMicros", "hasSavedCard" ], "properties": { "amountMicros": { "type": "integer", "format": "int64", "description": "Amount (micros) charged to the saved card each recharge.", "minimum": 0 }, "enabled": { "type": "boolean", "description": "Whether auto-recharge is enabled for this tenant." }, "hasSavedCard": { "type": "boolean", "description": "Whether a card is saved on file (auto-recharge cannot fire without one)." }, "setupUrl": { "type": [ "string", "null" ], "description": "When enabling without a saved card, a Stripe-hosted URL to add one. Absent\nonce a card is on file (or on plain reads)." }, "thresholdMicros": { "type": "integer", "format": "int64", "description": "Balance (micros) at or below which a recharge fires.", "minimum": 0 } } }, "AvailablePlansResponse": { "type": "object", "description": "The plan a tenant is on, and the ones it may move to itself.", "required": [ "available" ], "properties": { "available": { "type": "array", "items": { "$ref": "#/components/schemas/PlanInfo" }, "description": "Every self-serve plan, cheapest first. Includes the current plan when\nthat is itself self-serve, so a client can render the whole ladder." }, "current": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/PlanInfo", "description": "The tenant's current plan, if it has one." } ] } } }, "CacheDiskInfo": { "type": "object", "description": "A cache disk: a disk image many machines start from, each through its own\ncopy-on-write layer, published in immutable versions.", "required": [ "id", "name", "sizeGb", "mountPath", "latestVersion", "versions", "createdAt" ], "properties": { "createdAt": { "type": "string" }, "id": { "type": "string" }, "latestVersion": { "type": "integer", "format": "int32", "minimum": 0 }, "mountPath": { "type": "string" }, "name": { "type": "string" }, "sizeGb": { "type": "integer", "format": "int32", "minimum": 0 }, "versions": { "type": "array", "items": { "$ref": "#/components/schemas/CacheDiskVersionInfo" }, "description": "Newest first." } } }, "CacheDiskVersionInfo": { "type": "object", "description": "One immutable version of a cache disk.", "required": [ "version", "sizeBytes", "sha256", "createdAt" ], "properties": { "createdAt": { "type": "string" }, "sha256": { "type": "string", "description": "SHA-256 (hex) of the version's disk image." }, "sizeBytes": { "type": "integer", "format": "int64", "minimum": 0 }, "sourceMachineId": { "type": [ "string", "null" ], "description": "The machine whose cache this version was published from; `null` for v0." }, "version": { "type": "integer", "format": "int32", "description": "0 is the empty filesystem a cache disk starts as; each publish adds one.", "minimum": 0 } } }, "CardOnFile": { "type": "object", "description": "Opt-in saved-card auto-recharge settings (`GET`/`POST /v1/billing/auto-recharge`).\nThe card on file: what the account's plan fee and auto top-ups are charged\nto, as Stripe describes it. Never the number itself.", "required": [ "brand", "last4", "expMonth", "expYear" ], "properties": { "brand": { "type": "string", "description": "Card network, e.g. `visa`, `mastercard`, `amex`." }, "expMonth": { "type": "integer", "format": "int32", "minimum": 0 }, "expYear": { "type": "integer", "format": "int32", "minimum": 0 }, "last4": { "type": "string", "description": "Last four digits." } } }, "ChangePlanRequest": { "type": "object", "description": "Ask to move this tenant onto a different plan. Only plans whose\n`self_serve` flag is set may be chosen; operator tiers are assigned by an\nadmin.", "required": [ "planId" ], "properties": { "planId": { "type": "string", "description": "Plan id to move onto, e.g. `plan-startup-paid`." } } }, "CheckpointState": { "type": "string", "description": "User-visible state of a live-RAM checkpoint.", "enum": [ "mutable", "freezing", "frozen" ] }, "CheckpointUpload": { "type": "object", "description": "Where to send a checkpoint file's bytes. Each URL takes one consecutive\n`partSizeBytes` slice of the file, the last one the remainder, with a plain\nHTTP `PUT` and no authorization header. Then call\n`POST /v1/checkpoints/{id}/complete`.", "required": [ "checkpoint", "partSizeBytes", "uploadUrls", "expiresAt" ], "properties": { "checkpoint": { "$ref": "#/components/schemas/PortableCheckpointInfo", "description": "The checkpoint, `uploading` until completed." }, "expiresAt": { "type": "string", "description": "When the upload URLs stop working (RFC 3339)." }, "partSizeBytes": { "type": "integer", "format": "int64", "minimum": 0 }, "uploadUrls": { "type": "array", "items": { "type": "string" } } } }, "ClusterHealth": { "type": "object", "required": [ "clusterId", "version", "nodesTotal", "nodesReady", "groupsTotal", "poolsTotal", "uptimeSecs" ], "properties": { "apiVersion": { "type": "integer", "format": "int32", "description": "Version of the public control-plane contract.", "minimum": 0 }, "buildSha": { "type": [ "string", "null" ], "description": "Source revision injected by the release pipeline, when available." }, "capabilities": { "type": "array", "items": { "type": "string" }, "description": "Stable feature identifiers clients and deployment checks can gate on." }, "clusterId": { "type": "string" }, "groupsTotal": { "type": "integer", "format": "int32", "minimum": 0 }, "nodesReady": { "type": "integer", "format": "int32", "minimum": 0 }, "nodesTotal": { "type": "integer", "format": "int32", "minimum": 0 }, "poolsTotal": { "type": "integer", "format": "int32", "minimum": 0 }, "uptimeSecs": { "type": "integer", "format": "int64", "minimum": 0 }, "version": { "type": "string" } } }, "CommandSpec": { "oneOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "string" } ] }, "ConnectToken": { "type": "object", "description": "A connect token: a short-lived credential that opens only\n`/v1/machines/{id}/connect/{port}` on its selected machine and ports,\noptionally including descendants. Send it as a Bearer token, or as\nthe `access_token` query parameter on a WebSocket upgrade, so a client that\ncannot set headers (a DevTools client, a browser `WebSocket`) can still\nconnect.", "required": [ "id", "token", "expiresAt", "machineId" ], "properties": { "expiresAt": { "type": "string", "description": "RFC 3339 time after which the token is refused." }, "id": { "type": "string", "description": "API key id, for revoking this token via `DELETE /v1/apikeys/{id}`." }, "machineId": { "type": "string", "description": "The machine the token was minted for." }, "token": { "type": "string" } } }, "ConvertOrgRequest": { "type": "object", "description": "`POST /v1/org/convert` turns the caller's own account into an organization in place.", "required": [ "displayName" ], "properties": { "displayName": { "type": "string", "description": "Human readable name, shown in the console, trimmed to 1 to 100 characters." } } }, "CostBreakdown": { "type": "object", "description": "Cost breakdown for a usage period (all amounts in integer micros).", "required": [ "cpuMicros", "memoryMicros", "execMicros", "totalMicros" ], "properties": { "amountDueMicros": { "type": "integer", "format": "int64", "description": "What the tenant actually owes: `total − discount − credit_applied`.", "minimum": 0 }, "baseMicros": { "type": "integer", "format": "int64", "description": "Per-machine \"slot\" fee: alive machine-hours × the plan's base rate. Prices\nthe held VM slot (isolation, scheduling, readiness) independent of consumed\ncompute — it is NOT allocated vCPU/RAM. `serde(default)` so older\nclients/payloads omitting it still deserialize.", "minimum": 0 }, "cpuMicros": { "type": "integer", "format": "int64", "minimum": 0 }, "creditAppliedMicros": { "type": "integer", "format": "int64", "description": "Portion of the free credit actually consumed this period\n(`min(free_credit, subtotal − discount)`).", "minimum": 0 }, "diskMicros": { "type": "integer", "format": "int64", "description": "Disk gb·hour cost. `serde(default)` so older clients/payloads omitting it\nstill deserialize.", "minimum": 0 }, "egressMicros": { "type": "integer", "format": "int64", "description": "Egress (gb total) cost.", "minimum": 0 }, "execMicros": { "type": "integer", "format": "int64", "minimum": 0 }, "freeCreditMicros": { "type": "integer", "format": "int64", "description": "The plan's recurring free-credit allotment for the period.", "minimum": 0 }, "memoryMicros": { "type": "integer", "format": "int64", "minimum": 0 }, "monthlyFeeMicros": { "type": "integer", "format": "int64", "description": "Flat platform fee charged for this period (0 on usage-only plans).", "minimum": 0 }, "totalMicros": { "type": "integer", "format": "int64", "description": "Gross subtotal: sum of all resource line items, before discounts/credits.", "minimum": 0 }, "volumeDiscountMicros": { "type": "integer", "format": "int64", "description": "Graduated volume discount applied to the subtotal (period-level only;\nalways 0 on per-machine breakdowns).", "minimum": 0 } } }, "CreateAgentRequest": { "type": "object", "description": "Start a managed agent session: a harness (Claude Code, Codex, OpenCode, or\nany program) in its own machine, driven as a sequence of turns.", "required": [ "name" ], "properties": { "allowHosts": { "type": "array", "items": { "type": "string" }, "description": "Hosts the agent may reach beyond its model provider and package registry.\nThe `command` harness has neither, so callers must name hosts or\nexplicitly opt into unrestricted outbound access." }, "arch": { "type": [ "string", "null" ], "description": "`amd64` or `arm64`. A session with checkpoints runs on amd64 unless\npinned here." }, "checkpoints": { "type": [ "boolean", "null" ], "description": "Checkpoint after every turn so the session can be rewound or branched\n(default true)." }, "cpus": { "type": [ "integer", "null" ], "format": "int32", "description": "vCPUs (default 2).", "minimum": 0 }, "credential": { "type": [ "string", "null" ], "description": "A stored credential holding the model API key. The session's machine then\nnever holds the key: the agent sees a placeholder and the node\nsubstitutes the key on requests to the provider, so turns need no key in\ntheir `env`. Its variable must be the one the harness reads (e.g.\n`ANTHROPIC_API_KEY`) and its hosts must include the provider's." }, "harness": { "type": [ "string", "null" ], "description": "`claude-code` (default), `codex`, `opencode`, or `command`." }, "image": { "type": [ "string", "null" ], "description": "Image for the `command` harness." }, "memoryMb": { "type": [ "integer", "null" ], "format": "int32", "description": "Memory in MiB (default 2048).", "minimum": 0 }, "model": { "type": [ "string", "null" ], "description": "Model: optional for `codex`, required as `provider/model` for `opencode`." }, "name": { "type": "string", "description": "Session name, unique within the account." }, "openNetwork": { "type": "boolean", "description": "Allow all outbound traffic instead of the host allow-list." }, "program": { "type": "array", "items": { "type": "string" }, "description": "Program for the `command` harness; the prompt is appended." } } }, "CreateApiKeyRequest": { "type": "object", "properties": { "description": { "type": [ "string", "null" ] }, "expiresInDays": { "type": [ "integer", "null" ], "format": "int64", "minimum": 0 }, "personId": { "type": [ "string", "null" ], "description": "The account id of the organization member this key acts for. Required when\nacting in an organization, and the person the key is narrowed to and\nrevoked with. A personal account's key is for its owner, so leave it out." }, "scopes": { "type": "array", "items": { "type": "string" } }, "tenantId": { "type": [ "string", "null" ], "description": "Tenant to scope this key to (admin only). Keys created with a tenant_id\ncan only access resources belonging to that tenant." } } }, "CreateCacheDiskRequest": { "type": "object", "description": "Create a cache disk.", "required": [ "name" ], "properties": { "mountPath": { "type": [ "string", "null" ], "description": "Absolute guest path machines mount it at unless they say otherwise.\nDefault `/cache`." }, "name": { "type": "string", "description": "Unique within your account: 1-63 chars of `[a-z0-9]([a-z0-9._-]*[a-z0-9])?`.", "example": "deps" }, "sizeGb": { "type": [ "integer", "null" ], "format": "int32", "description": "Size of the cache filesystem in GiB (1-500). Default 20.", "minimum": 0 } }, "additionalProperties": false }, "CreateCheckpointUploadRequest": { "type": "object", "description": "Start uploading a `.checkpoint` file captured outside the cloud, such as\non a laptop with `smolvm machine checkpoint`.", "required": [ "sizeBytes" ], "properties": { "image": { "type": [ "string", "null" ], "description": "OCI image the checkpointed machine was created from, when the client\nknows it. A checkpoint records only its machine, so without this the\nrestored machine's source is unknown." }, "sizeBytes": { "type": "integer", "format": "int64", "description": "Exact size of the file in bytes.", "minimum": 0 } } }, "CreateConnectTokenRequest": { "type": "object", "description": "Body for `POST /v1/machines/{id}/connect-token`. Empty is fine.", "properties": { "includeDescendants": { "type": [ "boolean", "null" ], "description": "Whether branches of the target machine are reachable. Omitted keeps the\nexisting behavior; pass false to confine access to this machine." }, "port": { "type": [ "integer", "null" ], "format": "int32", "description": "Restrict the credential to one published guest port. Omitted means all\npublished ports for compatibility with existing clients.", "minimum": 0 }, "ttlSeconds": { "type": [ "integer", "null" ], "format": "int64", "description": "How long the token lasts, in seconds: 60 to 86400, 3600 when left out.\nIt never outlives the API key that mints it.", "minimum": 0 } } }, "CreateMachineRequest": { "type": "object", "required": [ "source" ], "properties": { "autoStopSeconds": { "type": [ "integer", "null" ], "format": "int64", "minimum": 0 }, "branchable": { "type": "boolean", "description": "Create this machine as a branch source: it boots with cloneable live RAM\nso `POST /v1/machines/:id/branches` can create independent copy-on-write\nchildren. Default false." }, "cacheDisk": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/MachineCacheDiskSpec", "description": "A cache disk the machine starts from: a published version of one of your\ncache disks, read through the machine's own copy-on-write layer and\nmounted at `mountPath`. Branches carry it." } ] }, "command": { "type": "array", "items": { "type": "string" }, "description": "Optional workload command (argv) that overrides the source image's or\n`.smolmachine` artifact's own entrypoint+cmd when the machine starts, so a\ndeploy of an off-the-shelf image can say what to run/serve. Empty (default)\n= use the source's own entrypoint, preserving prior behavior." }, "credentials": { "type": "array", "items": { "type": "string" }, "description": "Names of stored credentials this machine binds. Each gives the guest a\nplaceholder in the credential's variable; the node substitutes the value\nonly on HTTPS requests to the credential's hosts, so the machine never\nholds it." }, "env": { "type": "object", "additionalProperties": { "type": "string" }, "propertyNames": { "type": "string" } }, "ephemeral": { "type": "boolean" }, "labels": { "type": "object", "description": "Free-form key/value labels for finding the machine again later\n(`GET /v1/machines?label=key=value`). At most 32; keys are 1-63 chars of\n`[a-z0-9]([a-z0-9._/-]*[a-z0-9])?`, values up to 255 chars.", "additionalProperties": { "type": "string" }, "propertyNames": { "type": "string" } }, "mounts": { "type": "array", "items": { "$ref": "#/components/schemas/MachineMountSpec" } }, "name": { "type": [ "string", "null" ] }, "nestedVirt": { "type": "boolean", "description": "Expose nested virtualization (VMX/SVM) to the guest so it can run its own\nhypervisor. Refused with 422 `nested_virt_unavailable` unless this platform\nenables it, so a request for it is never silently dropped. Default false." }, "network": { "$ref": "#/components/schemas/MachineNetwork" }, "ports": { "type": "array", "items": { "$ref": "#/components/schemas/MachinePort" }, "description": "Ports to publish (web groups), at most 16. Guest ports only; hostPort is\nallocated." }, "public": { "type": "boolean", "description": "Opt in to UNAUTHENTICATED public ingress: when true (and the machine has a\npublished port), its `*.apps`/`/proxy` URL is reachable by anyone. Default\nfalse — a published port is reachable only via the authenticated path." }, "remoteMounts": { "type": "array", "items": { "$ref": "#/components/schemas/RemoteMountSpec" }, "description": "S3-compatible buckets mounted inside the guest. Unlike `mounts` these\nplace no constraint on which node runs the machine." }, "resources": { "$ref": "#/components/schemas/MachineResources" }, "source": { "$ref": "#/components/schemas/MachineSource" }, "ttlSeconds": { "type": [ "integer", "null" ], "format": "int64", "minimum": 0 }, "workdir": { "type": [ "string", "null" ] } } }, "CreateMachineSessionRequest": { "type": "object", "properties": { "cwd": { "type": [ "string", "null" ] }, "env": { "type": "object", "additionalProperties": { "type": "string" }, "propertyNames": { "type": "string" } }, "id": { "type": [ "string", "null" ] } } }, "CreateOrgRequest": { "type": "object", "description": "`POST /v1/org` creates an organization and makes the caller its owner.", "required": [ "displayName", "name" ], "properties": { "displayName": { "type": "string", "description": "Human readable name, shown in the console." }, "name": { "type": "string", "description": "The slug: lowercase alphanumeric plus `-`/`_`, 3 to 50 characters, unique and final." } } }, "CreatePlanRequest": { "type": "object", "required": [ "name" ], "properties": { "allowAlwaysOn": { "type": "boolean", "description": "May keep a published-port machine running instead of scaling to zero." }, "budgetPolicy": { "type": "string" }, "freeCreditMicros": { "type": "integer", "format": "int64", "minimum": 0 }, "id": { "type": [ "string", "null" ] }, "isDefault": { "type": "boolean" }, "maxConcurrentMachines": { "type": "integer", "format": "int32", "minimum": 0 }, "maxCpus": { "type": "integer", "format": "int32", "minimum": 0 }, "maxDiskGb": { "type": [ "integer", "null" ], "format": "int64", "description": "Largest disk (GB) one machine may request; omitted = platform maximum.", "minimum": 0 }, "maxEgressGb": { "type": [ "integer", "null" ], "format": "int64", "minimum": 0 }, "maxGroups": { "type": "integer", "format": "int32", "minimum": 0 }, "maxMachines": { "type": "integer", "format": "int32", "minimum": 0 }, "maxMemoryMb": { "type": "integer", "format": "int64", "minimum": 0 }, "monthlyBudgetMicros": { "type": [ "integer", "null" ], "format": "int64", "minimum": 0 }, "monthlyFeeMicros": { "type": "integer", "format": "int64", "description": "Flat recurring platform fee (micros per period); 0 = usage-only plan.", "minimum": 0 }, "name": { "type": "string" }, "rateBaseHourMicros": { "type": "integer", "format": "int64", "minimum": 0 }, "rateCpuHourMicros": { "type": "integer", "format": "int64", "minimum": 0 }, "rateDiskGbHourMicros": { "type": "integer", "format": "int64", "minimum": 0 }, "rateEgressGbMicros": { "type": "integer", "format": "int64", "minimum": 0 }, "rateExecMicros": { "type": "integer", "format": "int64", "minimum": 0 }, "rateMemoryGbHourMicros": { "type": "integer", "format": "int64", "minimum": 0 } } }, "CreateTenantRequest": { "type": "object", "required": [ "name" ], "properties": { "id": { "type": [ "string", "null" ] }, "name": { "type": "string" }, "planId": { "type": [ "string", "null" ] } } }, "CreateVolumeRequest": { "type": "object", "required": [ "name", "sizeGb" ], "properties": { "backend": { "type": [ "string", "null" ], "description": "Low-level storage backend override (`\"local\"` | `\"pd\"`). Prefer `durable`;\nthis is for power users and takes precedence when set. Unknown values are\nrejected by the handler." }, "durable": { "type": [ "boolean", "null" ], "description": "Durability of the volume. `false`/absent (the default) is **ephemeral** —\nfast node-local storage that is lost if the host node fails. `true` is\n**durable** — a disk that re-attaches to a live node on failover (requires\nthe deployment to have a durable backend configured). This is the\ncustomer-facing knob; it maps to `backend` internally." }, "name": { "type": "string" }, "node": { "type": [ "string", "null" ] }, "sizeGb": { "type": "integer", "format": "int64", "minimum": 0 } } }, "CredentialInfo": { "type": "object", "description": "A stored credential, without its value.", "required": [ "name", "envVar", "hosts", "createdAt", "updatedAt" ], "properties": { "createdAt": { "type": "string" }, "envVar": { "type": "string" }, "hosts": { "type": "array", "items": { "type": "string" } }, "name": { "type": "string" }, "updatedAt": { "type": "string" } } }, "DeployRequest": { "type": "object", "required": [ "name", "image" ], "properties": { "coLocateWith": { "type": [ "string", "null" ] }, "cpus": { "type": "integer", "format": "int32", "minimum": 0 }, "domain": { "type": [ "string", "null" ] }, "env": { "type": "array", "items": { "$ref": "#/components/schemas/EnvVar" } }, "health": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/HealthCheck" } ] }, "image": { "type": "string" }, "memoryMb": { "type": "integer", "format": "int32", "minimum": 0 }, "name": { "type": "string" }, "network": { "type": "boolean" }, "port": { "type": "integer", "format": "int32", "minimum": 0 }, "publicIngress": { "type": "boolean", "description": "Opt-in: expose this group's published port on the UNAUTHENTICATED public\n`/proxy` / `*.apps` ingress. Default false — the app is reachable only by\nits owner tenant (or admin) until explicitly made public, matching the\nper-machine `public_ingress` default." }, "stopGraceSecs": { "type": "integer", "format": "int64", "minimum": 0 }, "strategy": { "$ref": "#/components/schemas/DeployStrategy" }, "volume": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/VolumeMount" } ] } } }, "DeployStrategy": { "oneOf": [ { "type": "object", "description": "Replace instances in batches. Each batch: start new → health check → destroy old.", "required": [ "type" ], "properties": { "batchSize": { "type": "integer", "format": "int32", "description": "Instances to replace per batch (default: 1).", "minimum": 0 }, "type": { "type": "string", "enum": [ "rolling" ] }, "useHealthCheck": { "type": "boolean", "description": "Wait for health check to pass before destroying old instances." }, "waitSeconds": { "type": "integer", "format": "int64", "description": "Seconds to wait between batches if not using health checks (default: 5).", "minimum": 0 } } }, { "type": "object", "description": "Deploy N canary instances first. If healthy, replace the rest.\nIf canaries fail, roll back without touching existing instances.", "required": [ "type" ], "properties": { "autoPromote": { "type": "boolean", "description": "Auto-promote after health check passes. If false, requires manual promotion." }, "canaryCount": { "type": "integer", "format": "int32", "description": "Number of canary instances to deploy (default: 1).", "minimum": 0 }, "type": { "type": "string", "enum": [ "canary" ] } } }, { "type": "object", "description": "Deploy a complete new set alongside the old. Switch traffic atomically,\nthen destroy old instances.", "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "blueGreen" ] } } } ] }, "DiskDurability": { "type": "string", "description": "When a machine's guest disk writes must reach the node's physical disk.", "enum": [ "full", "deferred" ] }, "EnvVar": { "type": "object", "required": [ "key", "value" ], "properties": { "key": { "type": "string" }, "value": { "type": "string" } } }, "ErrorResponse": { "type": "object", "description": "RFC 9457 problem-details error body. Every 4xx/5xx from the API carries\nthis shape as `application/problem+json`: `code` is stable and\nmachine-readable (e.g. `not_found`, `too_many_requests`), `detail` is the\nhuman-readable message, and `title`/`status` mirror the HTTP status line.", "required": [ "type", "title", "status", "detail", "code" ], "properties": { "code": { "type": "string", "description": "Stable machine-readable error code for branching without parsing prose." }, "detail": { "type": "string", "description": "Human-readable description of what failed and how to resolve it." }, "retryable": { "type": "boolean", "description": "Whether the same request can succeed if sent again unchanged. True for\n408, 429, 502, 503 and 504, which also carry `Retry-After`." }, "status": { "type": "integer", "format": "int32", "description": "HTTP status code, repeated in the body for log-friendly errors.", "minimum": 0 }, "title": { "type": "string", "description": "Canonical reason phrase for the status (e.g. `Not Found`)." }, "type": { "type": "string", "description": "Problem type URI; `about:blank` when the status code says it all." } } }, "EventInfo": { "type": "object", "required": [ "id", "level", "message", "createdAt" ], "properties": { "createdAt": { "type": "string" }, "id": { "type": "string" }, "level": { "type": "string" }, "message": { "type": "string" } } }, "ForkBatchRequest": { "type": "object", "description": "Request to branch a running source into many children in one call. The\noperation is transactional: if any child fails, every child is rolled back.", "properties": { "branchable": { "type": "boolean", "description": "Let every child become another branch source." }, "count": { "type": "integer", "format": "int32", "description": "Number of children to branch (1..=`MAX_FORK_BATCH`). Ignored when `names` is\nnon-empty.", "minimum": 0 }, "freezeSource": { "type": "boolean", "description": "Keep the source paused as a reusable branch base, as for a single branch." }, "labels": { "type": [ "object", "null" ], "description": "Labels for every child. Omitted = copy the source's labels.", "additionalProperties": { "type": "string" }, "propertyNames": { "type": "string" } }, "namePrefix": { "type": [ "string", "null" ], "description": "Prefix for auto-named children when `count` is used. Defaults to the source's\nname." }, "names": { "type": "array", "items": { "type": "string" }, "description": "Explicit child names. When non-empty, its length is the batch size and\n`count` is ignored; otherwise children are auto-named `{name_prefix}-{n}`." }, "ports": { "type": "array", "items": { "$ref": "#/components/schemas/MachinePort" }, "description": "Inbound port forwards applied to every child. Empty means each child gets\nfresh host ports so siblings do not collide." } } }, "ForkBatchResponse": { "type": "object", "description": "Result of a batch branch: the children, in request order.", "required": [ "clones" ], "properties": { "clones": { "type": "array", "items": { "$ref": "#/components/schemas/MachineInfo" } } } }, "ForkRequest": { "type": "object", "description": "Request to branch a running source into an independent copy-on-write child.", "required": [ "name" ], "properties": { "branchable": { "type": "boolean", "description": "Materialize the child as another checkpoint source so it can execute,\nreach a later decision point, and branch again. This pays one eager guest\nmemory copy while the child boots; its descendants remain copy-on-write." }, "freezeSource": { "type": "boolean", "description": "Keep the source paused as a reusable branch base instead of resuming it.\nLater branches restore the same checkpoint, and a frozen source no longer\ncounts toward the concurrency cap. It cannot execute again; stop it, or\nwork in its children." }, "labels": { "type": [ "object", "null" ], "description": "Labels for the child. Omitted = copy the source's labels; supplied\n(even empty) = use exactly these.", "additionalProperties": { "type": "string" }, "propertyNames": { "type": "string" } }, "name": { "type": "string", "description": "Name for the new child machine." }, "ports": { "type": "array", "items": { "$ref": "#/components/schemas/MachinePort" }, "description": "Guest ports the clone publishes. Empty = the source's guest ports. Host\nports are always allocated by the control plane; any `hostPort` is ignored." } } }, "GroupInfo": { "type": "object", "required": [ "id", "name", "image", "replicas", "status", "port", "instances", "createdAt", "updatedAt" ], "properties": { "createdAt": { "type": "string" }, "domain": { "type": [ "string", "null" ] }, "id": { "type": "string" }, "image": { "type": "string" }, "instances": { "type": "array", "items": { "$ref": "#/components/schemas/InstanceInfo" } }, "name": { "type": "string" }, "port": { "type": "integer", "format": "int32", "minimum": 0 }, "replicas": { "type": "integer", "format": "int32", "minimum": 0 }, "status": { "type": "string" }, "updatedAt": { "type": "string" } } }, "HealthCheck": { "type": "object", "required": [ "type" ], "properties": { "intervalSecs": { "type": "integer", "format": "int64", "minimum": 0 }, "path": { "type": [ "string", "null" ] }, "port": { "type": [ "integer", "null" ], "format": "int32", "minimum": 0 }, "retries": { "type": "integer", "format": "int32", "minimum": 0 }, "timeoutSecs": { "type": "integer", "format": "int64", "minimum": 0 }, "type": { "$ref": "#/components/schemas/HealthCheckType" } } }, "HealthCheckType": { "type": "string", "enum": [ "http", "tcp", "exec" ] }, "InstanceInfo": { "type": "object", "required": [ "id", "nodeId", "status", "generation" ], "properties": { "generation": { "type": "integer", "format": "int64", "minimum": 0 }, "hostPort": { "type": [ "integer", "null" ], "format": "int32", "minimum": 0 }, "id": { "type": "string" }, "nodeId": { "type": "string" }, "status": { "type": "string" } } }, "InviteMemberRequest": { "type": "object", "description": "Body of `POST /v1/org/members/invite`, declared here so it reaches the client spec.", "required": [ "email", "role" ], "properties": { "email": { "type": "string", "description": "The address to invite, matched case-insensitively against the IdP's verified address." }, "role": { "type": "string", "description": "`owner`, `admin` or `member`." } } }, "InviteResult": { "type": "object", "description": "Result of inviting a member: the accept link, which comes back even with no\nemail provider configured (the admin can copy and share it directly).", "required": [ "emailSent" ], "properties": { "emailSent": { "type": "boolean", "description": "Whether the link was handed to a mailer; false on a deployment with none." }, "invitationUrl": { "type": [ "string", "null" ], "description": "The accept link, carrying the only readable copy of the token." } } }, "ListCacheDisksResponse": { "type": "object", "required": [ "cacheDisks" ], "properties": { "cacheDisks": { "type": "array", "items": { "$ref": "#/components/schemas/CacheDiskInfo" } } } }, "MachineCacheDisk": { "type": "object", "description": "The cache disk a machine runs with.", "required": [ "cacheDiskId", "version", "mountPath" ], "properties": { "cacheDiskId": { "type": "string" }, "intoSlot": { "type": "boolean", "description": "Put in a cache slot by a restore, which needs an engine that serves slots." }, "mountPath": { "type": "string" }, "slot": { "type": "boolean", "description": "Attached unmounted, as a slot a restore can put another cache in." }, "version": { "type": "integer", "format": "int32", "minimum": 0 } } }, "MachineCacheDiskSpec": { "type": "object", "description": "Which cache disk a machine starts from, on create.", "required": [ "cache" ], "properties": { "cache": { "type": "string", "description": "The cache disk's id or name.", "example": "deps" }, "mountPath": { "type": [ "string", "null" ], "description": "Absolute guest path to mount it at; the cache disk's own mount path when\nleft out." }, "slot": { "type": "boolean", "description": "Attach it as a slot: left unmounted, so a checkpoint of the machine can\nbe restored with a different cache mounted here (`cacheDisk` on restore).\nThe slot's size is this cache disk's size; its contents are never read." }, "version": { "type": [ "integer", "null" ], "format": "int32", "description": "Version to start from; the latest when left out.", "minimum": 0 } }, "additionalProperties": false }, "MachineCapabilities": { "type": "object", "description": "Dynamic machine operations for clients that must feature-detect instead of\nguessing from a server or engine version.", "required": [ "exec", "branch", "branchBatch", "nestedBranch", "maxBranchBatch", "fork", "forkBatch", "nestedFork", "maxForkBatch" ], "properties": { "branch": { "type": "boolean" }, "branchBatch": { "type": "boolean" }, "exec": { "type": "boolean" }, "fork": { "type": "boolean" }, "forkBatch": { "type": "boolean" }, "maxBranchBatch": { "type": "integer", "format": "int32", "minimum": 0 }, "maxForkBatch": { "type": "integer", "format": "int32", "description": "Legacy alias for `max_branch_batch`.", "minimum": 0 }, "nestedBranch": { "type": "boolean" }, "nestedFork": { "type": "boolean" } } }, "MachineCodeRequest": { "type": "object", "required": [ "language", "code" ], "properties": { "code": { "type": "string" }, "cwd": { "type": [ "string", "null" ] }, "env": { "type": "object", "additionalProperties": { "type": "string" }, "propertyNames": { "type": "string" } }, "language": { "type": "string" }, "timeoutSeconds": { "type": [ "integer", "null" ], "format": "int64", "minimum": 0 }, "user": { "type": [ "string", "null" ], "description": "Run as this user (image user name or `uid[:gid]`), overriding the image's USER." } } }, "MachineCommandRequest": { "type": "object", "required": [ "command" ], "properties": { "background": { "type": "boolean", "description": "Run the command detached: spawn it in the background and return its PID\nimmediately. Use for long-lived daemons (dev server, agent runner)." }, "command": { "$ref": "#/components/schemas/CommandSpec" }, "cwd": { "type": [ "string", "null" ] }, "env": { "type": "object", "additionalProperties": { "type": "string" }, "propertyNames": { "type": "string" } }, "stdin": { "type": [ "string", "null" ] }, "stream": { "type": "boolean", "description": "Stream stdout and stderr as Server-Sent Events instead of buffering the\nwhole run into one JSON body. The response is then `text/event-stream`,\nnot `MachineExecResponse`: frames are `event: stdout|stderr|error|exit`\nwith `data:` lines, and the terminal `exit` frame carries\n`{\"exitCode\": N}`. Streamed output is not capped, so this is the right\npath for long-running or high-volume commands." }, "timeoutSeconds": { "type": [ "integer", "null" ], "format": "int64", "minimum": 0 }, "user": { "type": [ "string", "null" ], "description": "Run as this user: a name from the image or a numeric `uid[:gid]`,\noverriding the image's USER. Forwarded to the machine's runtime; an\nolder runtime that cannot honour it rejects the request rather than\nrunning the command as the wrong account." } } }, "MachineExecResponse": { "type": "object", "required": [ "stdout", "stderr", "exitCode", "durationMs", "machineId" ], "properties": { "durationMs": { "type": "integer", "format": "int64", "minimum": 0 }, "exitCode": { "type": "integer", "format": "int32" }, "machineId": { "type": "string" }, "stderr": { "type": "string", "description": "Lossy UTF-8 stderr, capped. Prefer `stderrB64`." }, "stderrB64": { "type": "string", "format": "byte", "description": "Byte-exact stderr (base64), binary-safe and NOT truncated. Serializes as\n`stderrB64`." }, "stderrTruncated": { "type": "boolean" }, "stdout": { "type": "string", "description": "Lossy UTF-8 stdout, capped (see `stdout_truncated`). Kept for old clients\nand log views; prefer `stdoutB64` for byte-exact, untruncated output." }, "stdoutB64": { "type": "string", "format": "byte", "description": "Byte-exact stdout (base64), binary-safe and NOT truncated. Preferred by\nclients that need fidelity (`smol cloud exec`). `rename_all=camelCase`\nserializes this as `stdoutB64`." }, "stdoutTruncated": { "type": "boolean" }, "user": { "type": [ "string", "null" ], "description": "The user the command was run as, echoed back when the request set one.\nA client that asked for a user and does not see it here is talking to a\ncontrol plane that predates the field and dropped it — which the\nclient must treat as an error, never as \"ran as the default account\"." } } }, "MachineInfo": { "type": "object", "required": [ "id", "source", "state", "resources", "network", "env", "ephemeral", "createdAt", "updatedAt" ], "properties": { "arch": { "type": [ "string", "null" ], "description": "The machine's actual CPU arch (`arm64`/`amd64`): the arch of the node it\nruns on, falling back to `source.arch` (a `.smolmachine`'s pinned arch)\nwhen the machine is unplaced or its node is gone. `None` only when neither\nis known. Lets the console show an arch badge for every machine, including\nones whose source pinned no arch. Populated by the server's `machine_info`." }, "autoStopSeconds": { "type": [ "integer", "null" ], "format": "int64", "minimum": 0 }, "branchGeneration": { "type": [ "integer", "null" ], "format": "int32", "description": "Zero for a root branch source, one for its children, and so on.", "minimum": 0 }, "branchState": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/CheckpointState", "description": "Lifecycle of a live branch source." } ] }, "branchable": { "type": "boolean", "description": "Whether this machine can produce live copy-on-write branches." }, "cacheDisk": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/MachineCacheDisk", "description": "The cache disk the machine runs with, if any." } ] }, "capabilities": { "$ref": "#/components/schemas/MachineCapabilities", "description": "Operations the control plane can safely offer for this machine right now." }, "checkpointState": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/CheckpointState", "description": "Legacy alias for `branch_state`." } ] }, "createdAt": { "type": "string" }, "createdBy": { "type": [ "string", "null" ], "description": "The account id of whoever created the machine; null when nobody is." }, "env": { "type": "object", "additionalProperties": { "type": "string" }, "propertyNames": { "type": "string" } }, "ephemeral": { "type": "boolean" }, "error": { "type": [ "string", "null" ], "description": "When [`Self::state`] is `\"error\"`, a human-readable reason the machine\nfailed — the latest control-plane error event (e.g. `\"start failed: …\"`,\n`\"auto-start failed: …\"`, or `\"machine stuck in creating state\"`). `null`\nfor machines that are not in an error state. Gives clients something\nactionable instead of a bare `error` with no explanation." }, "forkGeneration": { "type": [ "integer", "null" ], "format": "int32", "description": "Legacy alias for `branch_generation`.", "minimum": 0 }, "forkable": { "type": "boolean", "description": "Legacy alias for `branchable`." }, "id": { "type": "string" }, "labels": { "type": "object", "description": "Labels set at create time (or inherited from a branch source).", "additionalProperties": { "type": "string" }, "propertyNames": { "type": "string" } }, "lastActivityAt": { "type": [ "string", "null" ] }, "name": { "type": [ "string", "null" ] }, "network": { "$ref": "#/components/schemas/MachineNetwork" }, "parentMachineId": { "type": [ "string", "null" ], "description": "Immediate live-RAM checkpoint this machine was branched from. `null` for\nordinary machines and root checkpoints." }, "ports": { "type": "array", "items": { "$ref": "#/components/schemas/MachinePort" }, "description": "Published ports with their allocated node host ports." }, "ready": { "type": "boolean", "description": "Whether the machine is READY to do work. `state == \"started\"` only means\nthe VM process launched on the node — the guest OS and your in-VM workload\nstill need a moment to boot. `ready` becomes true once the guest agent is\nreachable (an `exec`/`connect` will succeed) and, if the machine publishes\na port, that port is accepting connections. Wait for `ready` (poll\n`GET /v1/machines/:id`) before expecting an in-guest worker to have started\nor before connecting to it — do NOT act on `started` alone." }, "readyAt": { "type": [ "string", "null" ], "description": "When a probe first observed this machine serving (RFC3339), or `null`.\n\nThis is a readiness gate, not a boot timestamp: it is stamped when the\npublished port accepts a connection (or, for a machine with no published\nports, when its guest agent answers), and it is cleared on every stop so\na restart must re-prove itself. A short-lived machine may finish its\nwhole life as `null` here without anything being wrong. Use `createdAt`\nif you want when the machine came into existence." }, "resources": { "$ref": "#/components/schemas/MachineResources" }, "rootBranchId": { "type": [ "string", "null" ], "description": "Root source for this live branch lineage. A root points to itself;\nordinary machines have no lineage." }, "rootCheckpointId": { "type": [ "string", "null" ], "description": "Legacy alias for `root_branch_id`." }, "source": { "$ref": "#/components/schemas/MachineSource" }, "state": { "type": "string" }, "ttlSeconds": { "type": [ "integer", "null" ], "format": "int64", "minimum": 0 }, "updatedAt": { "type": "string" }, "url": { "type": [ "string", "null" ], "description": "Public ingress URL for the machine's first published port, when the\nmachine is started and the control plane has a public base URL\nconfigured. `null` for stopped machines, machines with no published\nport, or when the deployment exposes no public base URL." }, "workdir": { "type": [ "string", "null" ] } } }, "MachineJob": { "type": "object", "description": "A job and what is known about it.", "required": [ "id", "machineId", "command", "state", "createdAt" ], "properties": { "command": { "type": "array", "items": { "type": "string" }, "description": "The command as it was run (argv)." }, "createdAt": { "type": "string" }, "exitCode": { "type": [ "integer", "null" ], "format": "int32", "description": "The command's exit code once `exited`; 143 when it was cancelled or\nhit its timeout." }, "finishedAt": { "type": [ "string", "null" ] }, "id": { "type": "string" }, "machineId": { "type": "string" }, "state": { "type": "string", "description": "`running`, `exited` (see `exitCode`), or `lost`: the machine stopped\nor restarted while the job ran, so it never finished." }, "stderrBytes": { "type": [ "integer", "null" ], "format": "int64", "description": "Bytes of stderr written so far, when the machine was asked.", "minimum": 0 }, "stdoutBytes": { "type": [ "integer", "null" ], "format": "int64", "description": "Bytes of stdout written so far, when the machine was asked.", "minimum": 0 } } }, "MachineJobList": { "type": "object", "description": "A machine's jobs, newest first.", "required": [ "jobs" ], "properties": { "jobs": { "type": "array", "items": { "$ref": "#/components/schemas/MachineJob" } } } }, "MachineJobOutput": { "type": "object", "description": "A slice of a job's stdout or stderr.", "required": [ "stream", "offset", "nextOffset", "data", "eof" ], "properties": { "data": { "type": "string", "description": "The slice as lossy UTF-8." }, "dataB64": { "type": "string", "format": "byte", "description": "The slice, byte-exact (base64)." }, "eof": { "type": "boolean", "description": "True once the job has finished and this slice reaches the end of the\nstream: nothing more will be written." }, "nextOffset": { "type": "integer", "format": "int64", "description": "Byte offset to ask for next.", "minimum": 0 }, "offset": { "type": "integer", "format": "int64", "description": "Byte offset this slice starts at.", "minimum": 0 }, "stream": { "type": "string", "description": "`stdout` or `stderr`." } } }, "MachineJobRequest": { "type": "object", "description": "Start a command as a job: it runs detached, and its output and exit code\nare kept in the machine until read, so a client can disconnect and poll.", "required": [ "command" ], "properties": { "command": { "$ref": "#/components/schemas/CommandSpec" }, "cwd": { "type": [ "string", "null" ] }, "env": { "type": "object", "additionalProperties": { "type": "string" }, "propertyNames": { "type": "string" } }, "timeoutSeconds": { "type": [ "integer", "null" ], "format": "int64", "description": "Stop the job with SIGTERM after this many seconds. Unset: no limit.", "minimum": 0 }, "user": { "type": [ "string", "null" ], "description": "Run as this user (image user name or `uid[:gid]`)." } } }, "MachineLineage": { "type": "object", "description": "One complete live branch lineage, suitable for rendering as a tree. Parent\nrelationships remain on each machine so clients do not have to infer them\nfrom names or creation order.", "required": [ "rootMachineId", "machines" ], "properties": { "machines": { "type": "array", "items": { "$ref": "#/components/schemas/MachineInfo" } }, "rootMachineId": { "type": "string" } } }, "MachineMountSpec": { "type": "object", "required": [ "volume", "mountPath" ], "properties": { "mountPath": { "type": "string", "description": "Mount path inside the VM." }, "readonly": { "type": "boolean", "description": "Mount as read-only." }, "volume": { "type": "string", "description": "Volume name to mount." } } }, "MachineNetwork": { "oneOf": [ { "type": "object", "description": "No outbound access for the guest. The image PULL runs in-guest too, so a\n`blocked` machine whose image isn't already node-cached CANNOT fetch it and\nits start fails on an unreachable registry — opt into this deliberately.", "required": [ "mode" ], "properties": { "mode": { "type": "string", "enum": [ "blocked" ] } } }, { "type": "object", "description": "Unrestricted outbound access. This is the DEFAULT: it matches what the\n`smol` CLI already sends, and means a create that omits `network` (raw\nAPI/SDK) can pull remote images out of the box instead of failing the\nstart on an unreachable registry. Tighten with `blocked`/`allowCidrs`.", "required": [ "mode" ], "properties": { "mode": { "type": "string", "enum": [ "open" ] } } }, { "type": "object", "required": [ "mode" ], "properties": { "cidrs": { "type": "array", "items": { "type": "string" } }, "hosts": { "type": "array", "items": { "type": "string" } }, "mode": { "type": "string", "enum": [ "allowCidrs" ] } } } ] }, "MachinePort": { "type": "object", "description": "A machine-published port. On create, supply only `port` (the guest port the\nworkload listens on); the control plane allocates `hostPort` on the chosen\nnode at first start and routes ingress to it. Publishing a port implies the\nvirtio-net network backend on the node (TSI is outbound-only).", "required": [ "port" ], "properties": { "hostPort": { "type": [ "integer", "null" ], "format": "int32", "description": "Node host port allocated at placement (read-only; ignored on create).", "minimum": 0 }, "port": { "type": "integer", "format": "int32", "description": "Guest port the workload listens on.", "minimum": 0 } } }, "MachineResources": { "type": "object", "properties": { "cpus": { "type": "integer", "format": "int32", "minimum": 0 }, "diskDurability": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/DiskDurability", "description": "When guest disk writes must reach the node's disk. Unset means `full`.\nBranches keep their source's." } ] }, "diskGb": { "type": [ "integer", "null" ], "format": "int64", "minimum": 0 }, "memoryMb": { "type": "integer", "format": "int32", "minimum": 0 } } }, "MachineSessionInfo": { "type": "object", "required": [ "id", "machineId", "status", "env", "createdAt" ], "properties": { "createdAt": { "type": "string" }, "cwd": { "type": [ "string", "null" ] }, "env": { "type": "object", "additionalProperties": { "type": "string" }, "propertyNames": { "type": "string" } }, "id": { "type": "string" }, "lastExecAt": { "type": [ "string", "null" ] }, "machineId": { "type": "string" }, "status": { "type": "string" } } }, "MachineSource": { "oneOf": [ { "type": "object", "required": [ "reference", "type" ], "properties": { "arch": { "type": [ "string", "null" ], "description": "Requested CPU arch (\"arm64\"/\"amd64\"). Optional: an OCI image is\nusually multi-arch (the node pulls its own variant), so `None`\nmeans \"no constraint\" — but a caller that NEEDS a specific arch\n(e.g. x86-only binaries inside) can pin placement with it. Was\npreviously silently dropped by deserialization." }, "reference": { "type": "string" }, "type": { "type": "string", "enum": [ "image" ] } } }, { "type": "object", "required": [ "reference", "type" ], "properties": { "arch": { "type": [ "string", "null" ], "description": "Canonical CPU arch the packed artifact targets (\"arm64\"/\"amd64\").\nA `.smolmachine` is single-arch, so this becomes a hard placement\nconstraint. `None` (older clients) means \"no arch constraint\"." }, "reference": { "type": "string" }, "type": { "type": "string", "enum": [ "smolmachine" ] } } } ] }, "MachineUsageResponse": { "type": "object", "description": "Per-machine usage + cost for the current billing period (\"cost so far\").", "required": [ "machineId", "from", "to", "usage", "cost" ], "properties": { "cost": { "$ref": "#/components/schemas/CostBreakdown" }, "from": { "type": "string", "description": "Start of the period (inclusive), RFC3339." }, "machineId": { "type": "string", "description": "The machine this usage is for." }, "to": { "type": "string", "description": "End of the period (now), RFC3339." }, "usage": { "$ref": "#/components/schemas/UsageResponse" } } }, "MeResponse": { "type": "object", "description": "Identity self-discovery (`GET /v1/me`): who the caller is and where they\nmay push registry artifacts. Requires authentication but NO scopes — any\nidentity may ask who it is. This is how the CLI resolves a bare\n`myapp:v1` push reference to `tenants//myapp:v1`.", "required": [ "subject", "scopes" ], "properties": { "registryNamespace": { "type": [ "string", "null" ], "description": "The OCI repository namespace this identity may push to\n(`tenants/`), ready to prefix onto a repo name." }, "scopes": { "type": "array", "items": { "type": "string" }, "description": "Scopes this identity holds." }, "subject": { "type": "string", "description": "Acting principal: the JWT subject or the API key id." }, "tenantId": { "type": [ "string", "null" ], "description": "Canonical tenant id, if the identity is tenant-scoped. `None` for\nadmin keys and identities without a provisioned tenant." }, "tenantName": { "type": [ "string", "null" ], "description": "Tenant display name (the IdP email/name captured at provisioning)." }, "tenantStatus": { "type": [ "string", "null" ], "description": "Tenant status (`active`, `waitlisted`, `suspended`)." } } }, "NodeInfo": { "type": "object", "required": [ "id", "address", "smolvmAddress", "status", "totalCpus", "availableCpus", "totalMemoryMb", "availableMemoryMb", "totalDiskGb", "availableDiskGb", "labels", "registeredAt" ], "properties": { "address": { "type": "string" }, "availableCpus": { "type": "integer", "format": "int32", "minimum": 0 }, "availableDiskGb": { "type": "integer", "format": "int64", "minimum": 0 }, "availableMemoryMb": { "type": "integer", "format": "int64", "minimum": 0 }, "bootId": { "type": [ "string", "null" ], "description": "Runtime's per-process boot id, forwarded from the node's `/capacity`. A\nchange between heartbeats means the serve restarted (its warm pool wiped),\nwhich the control uses to prune the node's now-stale pool records. Absent on\nan older node/runtime that doesn't report it." }, "csrPem": { "type": [ "string", "null" ], "description": "PEM-encoded certificate signing request, sent only at registration. When\npresent, the control plane signs it as the node's mTLS **server** cert\n(overriding the CSR's subject/SANs with the validated node id/addresses)\nand returns the cert in `RegisterResponse`. The node's private key never\nleaves it. Absent ⇒ control plane has no node-CA configured, or this is\nan older node; the registration still succeeds (cert fields stay empty)." }, "diskCordonedAt": { "type": [ "string", "null" ], "description": "Set (RFC3339) when the control plane soft-cordons this node for DISK\npressure — its heartbeat-reported host-free disk dropped below the cordon\nthreshold, so it stops receiving NEW placements. SEPARATE from the\ndata-plane cordon: the node stays `status = \"ready\"` and is never reaped;\nits running machines are untouched. Cleared when free disk recovers past\nthe (higher, hysteretic) un-cordon threshold. `None` = not disk-cordoned." }, "id": { "type": "string" }, "labels": { "type": "object", "additionalProperties": { "type": "string" }, "propertyNames": { "type": "string" } }, "lastHeartbeatAt": { "type": [ "string", "null" ] }, "registeredAt": { "type": "string" }, "reservedDiskGb": { "type": "integer", "format": "int64", "description": "Sum of the (thin/nominal) local-SSD footprints reserved by the machines\nplaced on this node — the disk-overcommit ledger. Unlike `available_disk_gb`\n(overwritten by every heartbeat with the host's live free space), this is a\nreserve/release decrement ledger the scheduler gates admission on, so a node\ncan't be packed past `total_disk_gb * ratio`. Reconciled by the capacity\nself-heal. Default 0 (legacy rows / never reserved).", "minimum": 0 }, "runtime": { "type": "string", "description": "The runtime this node speaks (e.g. `\"smolvm\"`). The control plane resolves\na driver from this name; `smolvm_address` is that runtime's endpoint.\nDefaults to `\"smolvm\"` so a node that doesn't report a runtime (the only\nruntime today) is handled transparently." }, "smolvmAddress": { "type": "string", "description": "The runtime endpoint (HTTP address) on this node." }, "smolvmVersion": { "type": [ "string", "null" ], "description": "The smolvm engine version this node's runtime reports on `/health`,\nrecorded by the control plane. Read-only: a node never sets it. A\ncheckpoint is only restored on a node at the capturing engine's version\nor newer. Absent until the runtime has been probed." }, "status": { "type": "string" }, "totalCpus": { "type": "integer", "format": "int32", "minimum": 0 }, "totalDiskGb": { "type": "integer", "format": "int64", "minimum": 0 }, "totalMemoryMb": { "type": "integer", "format": "int64", "minimum": 0 }, "usedCpus": { "type": "number", "format": "double", "description": "Real CPU usage as fractional CPUs (e.g., 2.5 = 2.5 CPUs worth of load).\nReported by the node from hypervisor/process stats. Separate from\n`available_cpus` (which is allocation-based bookkeeping)." }, "usedDiskGb": { "type": "integer", "format": "int64", "description": "Real disk space consumed by VM overlay/storage files in GB. Reported\nfrom filesystem stat of VM disk images. Separate from\n`available_disk_gb` (which reflects the entire host filesystem).", "minimum": 0 }, "usedMemoryMb": { "type": "integer", "format": "int64", "description": "Real memory usage in MB. Reported by the node from RSS of VM processes.\nSeparate from `available_memory_mb` (which is allocation-based bookkeeping).", "minimum": 0 } } }, "OrgInvitation": { "type": "object", "description": "One invitation an organization awaits; the token lives only in the invite link.", "required": [ "id", "email", "role", "invitedBy", "expiresAt", "createdAt" ], "properties": { "createdAt": { "type": "string" }, "email": { "type": "string", "description": "The address invited, lowercased the way it is matched at acceptance." }, "expiresAt": { "type": "string", "description": "When it lapses. After this it is neither listed nor acceptable." }, "id": { "type": "string" }, "invitedBy": { "type": "string", "description": "The account id of the person who sent it." }, "role": { "type": "string", "description": "The role the membership row will carry: `owner`, `admin` or `member`." } } }, "OrgMachineSummary": { "type": "object", "description": "One machine named in a removal's response.", "required": [ "id", "state" ], "properties": { "id": { "type": "string" }, "name": { "type": [ "string", "null" ] }, "state": { "type": "string" } } }, "OrgMember": { "type": "object", "description": "A member of an organization, with their org roles.", "required": [ "userId", "roles" ], "properties": { "email": { "type": [ "string", "null" ] }, "name": { "type": [ "string", "null" ], "description": "Always null: the roster is read from our own rows, which hold no profile." }, "picture": { "type": [ "string", "null" ], "description": "Always null, for the same reason as `name`." }, "roles": { "type": "array", "items": { "type": "string" } }, "userId": { "type": "string", "description": "The person's own account id; memberships, roles and removal key on it, not the IdP subject." } } }, "OrgMembership": { "type": "object", "description": "One account a person belongs to; the switcher lists these, login lands on the latest.", "required": [ "tenantId", "name", "role", "status" ], "properties": { "displayName": { "type": [ "string", "null" ], "description": "The human readable name the console shows." }, "lastUsedAt": { "type": [ "string", "null" ], "description": "When the caller last acted here, or null if never; the list orders by it, latest first." }, "name": { "type": "string", "description": "The slug, unique across the fleet and final once chosen." }, "role": { "type": "string", "description": "The role the caller holds here: `owner`, `admin` or `member`." }, "status": { "type": "string", "description": "The account's state: `active`, `suspended`, `waitlisted` or `deleted`." }, "tenantId": { "type": "string", "description": "The organization's tenant id used in `Smol-Tenant` to act in this account." } } }, "OrgQuota": { "type": "object", "description": "An organization's limits and usage, counted once across every member's machines.", "required": [ "machines", "running" ], "properties": { "machines": { "type": "integer", "format": "int32", "description": "How many machines it has now, by the same count the refusal reports.", "minimum": 0 }, "running": { "type": "integer", "format": "int32", "description": "How many are running now, by the concurrency cap's own predicate.", "minimum": 0 } } }, "OrgSummary": { "type": "object", "description": "Summary of the caller's org context driving the console's member UI.", "required": [ "isOrganization", "canManageMembers" ], "properties": { "canManageMembers": { "type": "boolean", "description": "True when the caller may invite/change-role/remove members (owner/admin)." }, "displayName": { "type": [ "string", "null" ], "description": "The display name the owner may rename; null when the account is not an organization." }, "isOrganization": { "type": "boolean", "description": "True when the account is an organization (vs an individual login)." }, "name": { "type": [ "string", "null" ], "description": "The slug, unique and final once chosen; null when the account is not an organization." }, "quota": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/OrgQuota", "description": "How many machines it has and runs; null when the account is not an organization." } ] }, "tenantId": { "type": [ "string", "null" ], "description": "The org's tenant id for `Smol-Tenant`; null when the account is not an organization." } } }, "PendingInvitation": { "type": "object", "description": "One invitation waiting on the caller; the address is not carried, it is the caller's own.", "required": [ "id", "tenantId", "organization", "role", "invitedBy", "expiresAt", "createdAt" ], "properties": { "createdAt": { "type": "string" }, "expiresAt": { "type": "string", "description": "When it lapses. After this it is neither listed nor acceptable." }, "id": { "type": "string", "description": "What the accept names, a handle not a credential; the caller's address must still match." }, "invitedBy": { "type": "string", "description": "The account id of the person who sent it." }, "organization": { "type": "string", "description": "The organization's display name, falling back to its slug, since the caller has no roster." }, "role": { "type": "string", "description": "The role the membership row will carry: `owner`, `admin` or `member`." }, "tenantId": { "type": "string", "description": "The organization it joins, for the `Smol-Tenant` header afterwards." } } }, "PlanInfo": { "type": "object", "description": "A reusable plan: quota + per-unit rates (money in integer micros) + budget.", "required": [ "id", "name", "maxGroups", "maxCpus", "maxMemoryMb", "maxMachines", "maxConcurrentMachines", "rateCpuHourMicros", "rateMemoryGbHourMicros", "rateExecMicros", "monthlyFeeMicros", "allowAlwaysOn", "budgetPolicy", "isDefault", "createdAt" ], "properties": { "allowAlwaysOn": { "type": "boolean" }, "budgetPolicy": { "type": "string" }, "createdAt": { "type": "string" }, "freeCreditMicros": { "type": "integer", "format": "int64", "description": "Recurring free credit applied to each billing period, in micros (e.g.\n5_000_000 = $5/month free). Discount applies after volume tiers.", "minimum": 0 }, "id": { "type": "string" }, "isDefault": { "type": "boolean" }, "maxConcurrentMachines": { "type": "integer", "format": "int32", "minimum": 0 }, "maxCpus": { "type": "integer", "format": "int32", "minimum": 0 }, "maxDiskGb": { "type": [ "integer", "null" ], "format": "int64", "description": "Largest disk (GB) one machine may request; `null` = platform maximum.", "minimum": 0 }, "maxEgressGb": { "type": [ "integer", "null" ], "format": "int64", "minimum": 0 }, "maxGroups": { "type": "integer", "format": "int32", "minimum": 0 }, "maxMachines": { "type": "integer", "format": "int32", "minimum": 0 }, "maxMemoryMb": { "type": "integer", "format": "int64", "minimum": 0 }, "monthlyBudgetMicros": { "type": [ "integer", "null" ], "format": "int64", "minimum": 0 }, "monthlyFeeMicros": { "type": "integer", "format": "int64", "description": "Flat recurring platform fee (micros per period); 0 = usage-only plan.", "minimum": 0 }, "name": { "type": "string" }, "rateBaseHourMicros": { "type": "integer", "format": "int64", "description": "Per-machine-alive-hour \"slot\" fee in micros (e.g. 40_000 = $0.04/hr). Prices\nthe held VM slot on top of consumed CPU/RAM — not allocated resources.", "minimum": 0 }, "rateCpuHourMicros": { "type": "integer", "format": "int64", "minimum": 0 }, "rateDiskGbHourMicros": { "type": "integer", "format": "int64", "minimum": 0 }, "rateEgressGbMicros": { "type": "integer", "format": "int64", "minimum": 0 }, "rateExecMicros": { "type": "integer", "format": "int64", "minimum": 0 }, "rateMemoryGbHourMicros": { "type": "integer", "format": "int64", "minimum": 0 }, "selfServe": { "type": "boolean", "description": "Whether a tenant may switch itself onto this plan. Operator-only tiers\nare false and never appear in the self-serve list." } } }, "PortableCheckpointInfo": { "type": "object", "description": "Portable live-state capture; only `available` denotes a completed upload.", "required": [ "id", "machineId", "status", "sizeBytes", "arch", "createdAt", "downloadUrl" ], "properties": { "arch": { "type": "string" }, "createdAt": { "type": "string" }, "downloadUrl": { "type": "string", "description": "Authenticated endpoint that downloads the `.smolcheckpoint` file." }, "engineVersion": { "type": [ "string", "null" ], "description": "smolvm version of the node that captured it. A restore is only placed\non a node at this version or newer. Absent for older checkpoints, which\nrestore anywhere." }, "id": { "type": "string" }, "machineDeleted": { "type": "boolean", "description": "The machine it was captured from has been deleted. The checkpoint stays\nuntil it is deleted itself, and can still be restored or downloaded." }, "machineId": { "type": "string" }, "sizeBytes": { "type": "integer", "format": "int64", "minimum": 0 }, "status": { "type": "string", "description": "`creating`, `uploading`, `available`, `failed`, or `deleting`." } } }, "PublicMachineStats": { "type": "object", "description": "The lifetime count of machine starts on the platform, served UNAUTHENTICATED\nat `GET /v1/status/machines` for the marketing site. Counted from the audit\ntrail, so it is a real number and only ever grows. Operator-owned accounts\n(demos, QA) are left out via the `public_stats.exclude_tenants` server\nsetting, so the figure means \"machines our customers launched\".", "required": [ "updatedAt" ], "properties": { "machinesStarted": { "type": [ "integer", "null" ], "format": "int64", "description": "Machines started by customers since `since`. `null` when the count could\nnot be computed — the site hides the figure rather than show a zero.", "minimum": 0 }, "since": { "type": [ "string", "null" ], "description": "The first day the count covers (`YYYY-MM-DD`), when known." }, "updatedAt": { "type": "string", "description": "When the figure was last computed (RFC 3339)." } } }, "PublicPricing": { "type": "object", "description": "The published rate card, served UNAUTHENTICATED at `GET /v1/pricing`. Read\nstraight from the default plan so the public pricing page and the in-console\nbilling breakdown share ONE source of truth — no hand-synced copy to drift.\nAll rates are in micros (1e-6 USD).", "required": [ "currency", "baseHourMicros", "cpuHourMicros", "memoryGbHourMicros", "diskGbHourMicros", "egressGbMicros", "signupCreditMicros", "freeCreditMicros", "volumeTiers" ], "properties": { "baseHourMicros": { "type": "integer", "format": "int64", "description": "Base \"slot\" fee per running machine-hour — the held VM (isolation,\nscheduling, readiness), independent of consumed compute.", "minimum": 0 }, "cpuHourMicros": { "type": "integer", "format": "int64", "description": "Active consumed vCPU-hour.", "minimum": 0 }, "currency": { "type": "string", "description": "Currency code; always \"usd\" today." }, "diskGbHourMicros": { "type": "integer", "format": "int64", "description": "Disk GB-hour — both active disk and held storage on a stopped machine\nbill at this rate.", "minimum": 0 }, "egressGbMicros": { "type": "integer", "format": "int64", "description": "Network egress per GB.", "minimum": 0 }, "freeCreditMicros": { "type": "integer", "format": "int64", "description": "Deprecated alias of [`Self::signup_credit_micros`], kept so clients written\nagainst the old contract keep parsing. It once meant a recurring monthly\nallowance; that allowance no longer exists, so the value is the same\none-time grant. Read `signup_credit_micros` instead.", "minimum": 0 }, "memoryGbHourMicros": { "type": "integer", "format": "int64", "description": "Active resident-memory (RSS) GB-hour.", "minimum": 0 }, "signupCreditMicros": { "type": "integer", "format": "int64", "description": "One-time credit granted when an account is created, in micros. It is paid\ninto the account's prepaid balance and drawn down like any other credit —\nit does NOT reset monthly and is not a per-period discount.", "minimum": 0 }, "volumeTiers": { "type": "array", "items": { "$ref": "#/components/schemas/VolumeTier" }, "description": "Graduated volume-discount bands, low bound → high." } } }, "PublishCacheDiskResponse": { "type": "object", "description": "The version a publish created, and the cache disk it now belongs to.", "required": [ "cacheDisk", "version" ], "properties": { "cacheDisk": { "$ref": "#/components/schemas/CacheDiskInfo" }, "version": { "$ref": "#/components/schemas/CacheDiskVersionInfo" } } }, "RemoteMountSpec": { "type": "object", "description": "An S3-compatible bucket mounted into the machine.\n\nDeliberately separate from [`MachineMountSpec`], which references a\nprovisioned cloud volume. The two are opposite kinds of resource: a cloud\nvolume is stateful, claimed exclusively and pins the machine to its node,\nwhile a bucket is stateless, shareable and reachable from any node. Reusing\nthe volume type would drag a bucket through claim and node-pinning logic\nthat works against it.\n\nCredentials come from the machine's `env` (`AWS_ACCESS_KEY_ID` /\n`AWS_SECRET_ACCESS_KEY`, optional `AWS_ENDPOINT_URL` and `AWS_REGION`), the\nsame place every AWS SDK reads them. Without them the bucket is read\nanonymously, which is how public datasets are consumed.", "required": [ "source", "mountPath" ], "properties": { "mountPath": { "type": "string", "description": "Mount path inside the VM." }, "readonly": { "type": "boolean", "description": "Mount as read-only." }, "source": { "type": "string", "description": "`s3://bucket[/prefix]`." } } }, "RemoveMemberResult": { "type": "object", "description": "What removing somebody from an organization revokes and what it leaves running.", "required": [ "revokedKeyIds", "runningMachines" ], "properties": { "revokedKeyIds": { "type": "array", "items": { "type": "string" }, "description": "The ids of the organization's API keys that were revoked." }, "runningMachines": { "type": "array", "items": { "$ref": "#/components/schemas/OrgMachineSummary" }, "description": "The organization's machines this person created that are left running." } } }, "RenameOrgRequest": { "type": "object", "description": "`PATCH /v1/org` renames the organization; the slug is final so only the name changes.", "required": [ "displayName" ], "properties": { "displayName": { "type": "string", "description": "The new display name, trimmed, 1 to 100 characters, same bound as at creation." } } }, "ResizeMachineRequest": { "type": "object", "description": "Change the size of a running machine. Set any of the fields; each one left\nout keeps its current value. RAM and disk only grow; CPUs can also shrink.", "properties": { "cpus": { "type": [ "integer", "null" ], "format": "int32", "description": "Online vCPU count.", "minimum": 0 }, "diskGb": { "type": [ "integer", "null" ], "format": "int64", "description": "Storage disk size in GiB. Grow only.", "minimum": 0 }, "memoryMb": { "type": [ "integer", "null" ], "format": "int32", "description": "Total guest RAM in MiB. Grow only.", "minimum": 0 } } }, "RestorePortableCheckpointRequest": { "type": "object", "description": "Create a stopped machine from a durable portable checkpoint.", "required": [ "name" ], "properties": { "cacheDisk": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/MachineCacheDiskSpec", "description": "For a checkpoint captured with a cache slot: the cache to mount in it.\nIt must be no larger than the slot's cache disk, and is mounted at the\nslot's path unless `mountPath` says otherwise (it must match)." } ] }, "name": { "type": "string" }, "network": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/MachineNetwork", "description": "Network for the restored machine. Omitted means `blocked`: the\ncheckpoint may come from a machine with less access than its restorer\nintends to give it." } ] } } }, "RollbackMachineRequest": { "type": "object", "description": "Roll a machine back to one of its checkpoints, keeping its id and name.", "properties": { "checkpointId": { "type": [ "string", "null" ], "description": "The checkpoint to return to. It must have been captured from this\nmachine. Omitted means the machine's newest available checkpoint." } }, "additionalProperties": false }, "ScaleRequest": { "type": "object", "required": [ "count" ], "properties": { "count": { "type": "integer", "format": "int32", "minimum": 0 } } }, "SendAgentTurnRequest": { "type": "object", "description": "Send a prompt to a managed agent session.", "required": [ "prompt" ], "properties": { "env": { "type": "object", "description": "Environment for this turn only — typically the model API key. Never\nstored.", "additionalProperties": { "type": "string" }, "propertyNames": { "type": "string" } }, "prompt": { "type": "string" }, "timeoutSeconds": { "type": [ "integer", "null" ], "format": "int64", "description": "Longest the turn may run (default 1800 s).", "minimum": 0 } } }, "SetCredentialRequest": { "type": "object", "description": "Store a credential for credential substitution. The value is write-only:\nit is sealed at rest and never returned.", "required": [ "envVar", "hosts", "value" ], "properties": { "envVar": { "type": "string", "description": "The environment variable a machine that binds this credential sees —\nholding a placeholder, never the value." }, "hosts": { "type": "array", "items": { "type": "string" }, "description": "The only hosts the value is ever sent to (HTTPS requests only)." }, "value": { "type": "string" } } }, "SetRoleRequest": { "type": "object", "description": "Body of `PATCH /v1/org/members/{id}/role`.", "required": [ "role" ], "properties": { "role": { "type": "string", "description": "`owner`, `admin` or `member`." } } }, "SignupAttribution": { "type": "object", "description": "First-touch marketing attribution, reported once by the console right after a\nnew account's first login. Every field is optional and untrusted: the control\nplane keeps an allowlisted, length-capped, query-stripped copy and ignores the\nrest. Stored at most once per tenant and only for recently created tenants.", "properties": { "firstSeenAt": { "type": [ "string", "null" ], "description": "When the visitor first landed (RFC 3339), which can precede signup by days." }, "landingPath": { "type": [ "string", "null" ], "description": "The first path on this site the visitor landed on." }, "referrer": { "type": [ "string", "null" ], "description": "The external page that sent the visitor, as scheme://host/path — the\nquery string and fragment are dropped before storage." }, "utmCampaign": { "type": [ "string", "null" ] }, "utmContent": { "type": [ "string", "null" ] }, "utmMedium": { "type": [ "string", "null" ] }, "utmSource": { "type": [ "string", "null" ] }, "utmTerm": { "type": [ "string", "null" ] } } }, "SignupAttributionResponse": { "type": "object", "description": "Whether a reported attribution was stored. `false` is not an error: the tenant\nalready has one, is not a new account, or the report carried nothing usable.", "required": [ "recorded" ], "properties": { "recorded": { "type": "boolean" } } }, "TenantInfo": { "type": "object", "description": "A tenant (customer account). Quota override fields are `None` when inherited\nfrom the plan. See docs/product-backend-layer.md.", "required": [ "id", "name", "status", "createdAt" ], "properties": { "createdAt": { "type": "string" }, "externalBillingId": { "type": [ "string", "null" ] }, "id": { "type": "string" }, "maxCpus": { "type": [ "integer", "null" ], "format": "int32", "minimum": 0 }, "maxDiskGb": { "type": [ "integer", "null" ], "format": "int64", "description": "Per-tenant override of the plan's per-machine disk ceiling (GB).", "minimum": 0 }, "maxGroups": { "type": [ "integer", "null" ], "format": "int32", "minimum": 0 }, "maxMemoryMb": { "type": [ "integer", "null" ], "format": "int64", "minimum": 0 }, "maxSandboxPools": { "type": [ "integer", "null" ], "format": "int32", "minimum": 0 }, "name": { "type": "string" }, "planId": { "type": [ "string", "null" ] }, "signupAttribution": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/SignupAttribution", "description": "How this tenant found us, when it was captured at signup." } ] }, "status": { "type": "string" }, "updatedAt": { "type": [ "string", "null" ] } } }, "TenantMeter": { "type": "object", "description": "One tenant's metered usage for a period, in the shape a billing system\ningests (`GET /v1/billing/meters`).", "required": [ "tenantId", "cpuHours", "memoryGbHours", "execCount", "cost" ], "properties": { "cost": { "$ref": "#/components/schemas/CostBreakdown" }, "cpuHours": { "type": "number", "format": "double" }, "diskGbHours": { "type": "number", "format": "double", "description": "Disk gb·hours metered for the period." }, "egressGb": { "type": "number", "format": "double", "description": "Egress gb (networking, billed by gb total) for the period." }, "execCount": { "type": "integer", "format": "int64", "minimum": 0 }, "externalBillingId": { "type": [ "string", "null" ] }, "memoryGbHours": { "type": "number", "format": "double" }, "tenantId": { "type": "string" } } }, "UpdateAutoRechargeRequest": { "type": "object", "description": "Update opt-in auto-recharge (`POST /v1/billing/auto-recharge`). Omitted\noverride fields reset to the fleet default (`null`).", "required": [ "enabled" ], "properties": { "amountMicros": { "type": [ "integer", "null" ], "format": "int64", "description": "Top-up amount in micros (`null` → fleet default). Must be `≥ $1` and\n`> threshold`.", "minimum": 0 }, "enabled": { "type": "boolean", "description": "Master switch. Disabling never charges; enabling requires a saved card\n(the response returns a `setupUrl` to add one when none is on file yet)." }, "thresholdMicros": { "type": [ "integer", "null" ], "format": "int64", "description": "Trigger threshold in micros (`null` → fleet default). Must be `< amount`.", "minimum": 0 } } }, "UpdatePlanRequest": { "type": "object", "description": "`PATCH /v1/plans/{id}`: change a plan's limits in place. Every field is\noptional; only the given ones change. Takes effect on the next machine\ncreate for every tenant on the plan.", "properties": { "maxConcurrentMachines": { "type": [ "integer", "null" ], "format": "int32", "minimum": 0 }, "maxCpus": { "type": [ "integer", "null" ], "format": "int32", "minimum": 0 }, "maxDiskGb": { "type": [ "integer", "null" ], "format": "int64", "minimum": 0 }, "maxMachines": { "type": [ "integer", "null" ], "format": "int32", "minimum": 0 }, "maxMemoryMb": { "type": [ "integer", "null" ], "format": "int64", "minimum": 0 } } }, "UpdateTenantRequest": { "type": "object", "description": "Partial update — only present fields change.", "properties": { "externalBillingId": { "type": [ "string", "null" ] }, "freeCreditMicros": { "type": [ "integer", "null" ], "format": "int64", "description": "Per-tenant free-credit override (micros). Present → this tenant's monthly\nfree allotment is set to exactly this, overriding its plan's. Absent →\nunchanged (still falls back to the plan). Admin-only.", "minimum": 0 }, "maxCpus": { "type": [ "integer", "null" ], "format": "int32", "description": "Per-machine size overrides for this tenant (each `null` = leave as is).\nThey sit above the plan's ceilings, for a deal that needs bigger machines\nwithout a new plan.", "minimum": 0 }, "maxDiskGb": { "type": [ "integer", "null" ], "format": "int64", "minimum": 0 }, "maxMemoryMb": { "type": [ "integer", "null" ], "format": "int64", "minimum": 0 }, "planId": { "type": [ "string", "null" ] }, "status": { "type": [ "string", "null" ] } } }, "UsageResponse": { "type": "object", "required": [ "tenantId", "from", "to", "totalUptimeSeconds", "cpuHours", "memoryGbHours", "diskGbHours", "egressGb", "machineCount" ], "properties": { "consumedFrom": { "type": "string", "description": "Start of the period the consumed metrics actually cover.\n\n`totalUptimeSeconds` and `machineCount` are computed over the requested\n`from`..`to`. The four consumed dimensions cannot be: they come from the\ntenant's running per-billing-period counters — the same numbers billing\ncharges on — and no per-window consumed history exists to recompute them\nfrom. (Deriving them from the window instead reported PROVISIONED\nfigures that ran 177x the actual bill.)\n\nSo for any window other than the current billing period this differs\nfrom `from`, rather than leaving the response looking as though every\nnumber shared one time base." }, "consumedTo": { "type": "string", "description": "End of the period the consumed metrics actually cover. See\n`consumedFrom`." }, "cpuHours": { "type": "number", "format": "double", "description": "The four metered-and-priced dimensions, over `consumedFrom`..`consumedTo`\n— NOT over `from`..`to`. Exec is intentionally absent: it\nis metered for the event timeline but priced at $0, so surfacing it as\n\"usage\" here would imply a charge that never happens." }, "diskGbHours": { "type": "number", "format": "double" }, "egressGb": { "type": "number", "format": "double" }, "from": { "type": "string" }, "machineCount": { "type": "integer", "format": "int32", "minimum": 0 }, "memoryGbHours": { "type": "number", "format": "double" }, "tenantId": { "type": "string" }, "to": { "type": "string" }, "totalUptimeSeconds": { "type": "integer", "format": "int64", "minimum": 0 } } }, "VolumeInfo": { "type": "object", "required": [ "id", "name", "nodeId", "sizeGb", "status", "createdAt", "durability" ], "properties": { "createdAt": { "type": "string" }, "durability": { "type": "string", "description": "`\"ephemeral\"` — lives on a single node's disk and is lost if that node\nfails (the default); `\"durable\"` — backed by a detachable disk that\nre-attaches to a live node on failover. Derived from the storage backend." }, "groupInstanceId": { "type": [ "string", "null" ] }, "id": { "type": "string" }, "name": { "type": "string" }, "nodeId": { "type": "string" }, "sizeGb": { "type": "integer", "format": "int64", "minimum": 0 }, "status": { "type": "string" } } }, "VolumeMount": { "type": "object", "required": [ "name", "mountPath" ], "properties": { "mountPath": { "type": "string" }, "name": { "type": "string" }, "sizeGb": { "type": "integer", "format": "int64", "minimum": 0 } } }, "VolumeTier": { "type": "object", "description": "One band of the graduated (tax-bracket-style) volume discount: only spend\n*within* the band is discounted at `discount_bps`.", "required": [ "discountBps" ], "properties": { "discountBps": { "type": "integer", "format": "int32", "description": "Discount applied to spend within this band, in basis points (e.g. 1000 = 10%).", "minimum": 0 }, "upToMicros": { "type": [ "integer", "null" ], "format": "int64", "description": "Upper bound of this band in micros; `null` = the final, unbounded band.", "minimum": 0 } } } }, "securitySchemes": { "ApiKeyAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "smk_...", "description": "API key sent as `Authorization: Bearer `. Keys carry scopes; a key with no scopes is rejected. Scopes: `admin` (full access), `machine:create`, `machine:read`, `machine:exec`, `machine:files`, `machine:delete`, `group:write` (legacy alias `app:write`), `usage:read`, `billing:read`, `billing:write`, `members:read`, `members:write`, and `*` (all scopes). Each operation's description states the scope it requires. A user login can act in an organization it belongs to by sending `Smol-Tenant: `; an API key always acts in the account it was minted for. Errors are RFC 9457 `application/problem+json` with a stable `code` field and a `retryable` flag; retryable errors (408, 429, 502, 503, 504) carry `Retry-After`. An exec whose machine stopped under it returns 503 `machine_interrupted`: the command may have partly run, and a retry runs it again. Suspended or out-of-credit tenants receive 402; rate-limited requests receive 429 with `RateLimit-*` headers." } } }, "tags": [ { "name": "machines", "description": "First-class machine lifecycle and exec" }, { "name": "cache-disks", "description": "Disk images many machines start from, each through its own copy-on-write layer, published in versions" }, { "name": "credentials", "description": "Credentials substituted on the way out, never held by a machine" }, { "name": "agents", "description": "Managed agent sessions: a harness in its own machine, run as rewindable turns" }, { "name": "checkpoints", "description": "Portable live machine checkpoints" }, { "name": "groups", "description": "Long-running group deployments" }, { "name": "nodes", "description": "Cluster node enrollment and status" }, { "name": "tokens", "description": "Node join tokens" }, { "name": "volumes", "description": "Persistent volumes" }, { "name": "usage", "description": "Usage and billing" }, { "name": "apikeys", "description": "API key management" }, { "name": "tenants", "description": "Customer accounts (product-backend)" }, { "name": "plans", "description": "Quota + rate + budget plans" }, { "name": "billing", "description": "Self-service account and metering" }, { "name": "operations", "description": "Async operations" }, { "name": "health", "description": "Health, probes, and metrics" } ] }