{ "openapi": "3.1.0", "info": { "title": "Personal token API", "description": "User-scoped API for account and organization management.", "version": "0.1.0" }, "servers": [ { "url": "https://api.microsandbox.dev" } ], "security": [ { "bearer": [] } ], "paths": { "/v1/users/me": { "get": { "tags": [ "Account" ], "summary": "Get your profile", "operationId": "get_me", "responses": { "200": { "description": "Current user", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/User" } } } }, "401": { "description": "Unauthorized" } }, "security": [ { "bearer": [] } ] }, "delete": { "tags": [ "Account" ], "summary": "Delete your account", "description": "Deletes the account's personal information, signs out active sessions, removes\norganization memberships, and revokes pending invitations sent by the user.\nAudit history is retained.\n\nRequires fresh credential proof: the current password (password-backed\naccounts) or a TOTP code (MFA-enabled accounts). At least one must be\nsupplied; both being valid is fine but a single matching proof is enough.\n\nReturns `409 Conflict` if the user is the sole owner of an organization -\nownership must be transferred first.", "operationId": "delete_me", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeleteMeRequest" } } }, "required": true }, "responses": { "200": { "description": "Account deleted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MessageResponse" } } } }, "400": { "description": "Missing credential proof" }, "401": { "description": "Invalid password or MFA code" }, "409": { "description": "Sole owner of an organization" } }, "security": [ { "bearer": [] } ] }, "patch": { "tags": [ "Account" ], "summary": "Update your profile", "operationId": "update_me", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateMeRequest" } } }, "required": true }, "responses": { "200": { "description": "Profile updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/User" } } } }, "401": { "description": "Unauthorized" } }, "security": [ { "bearer": [] } ] } }, "/v1/orgs": { "get": { "tags": [ "Organization" ], "summary": "List your organizations", "operationId": "list_orgs", "responses": { "200": { "description": "User's organizations", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/OrgWithRole" } } } } }, "401": { "description": "Unauthorized" } }, "security": [ { "bearer": [] } ] }, "post": { "tags": [ "Organization" ], "summary": "Create an organization", "description": "The current user becomes its owner.", "operationId": "create_org", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateOrgRequest" } } }, "required": true }, "responses": { "200": { "description": "Organization created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Organization" } } } }, "400": { "description": "Invalid request" }, "401": { "description": "Unauthorized" }, "409": { "description": "Slug already taken" } }, "security": [ { "bearer": [] } ] } }, "/v1/orgs/{slug}": { "get": { "tags": [ "Organization" ], "summary": "Get an organization", "operationId": "get_org", "parameters": [ { "name": "slug", "in": "path", "description": "Organization slug", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Organization details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrgWithRole" } } } }, "401": { "description": "Unauthorized" }, "403": { "description": "Not a member" } }, "security": [ { "bearer": [] } ] }, "delete": { "tags": [ "Organization" ], "summary": "Delete an organization", "description": "Hides the organization immediately and schedules its resources for cleanup.\nThe request must confirm the organization slug.", "operationId": "delete_org", "parameters": [ { "name": "slug", "in": "path", "description": "Organization slug", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeleteOrgRequest" } } }, "required": true }, "responses": { "200": { "description": "Organization scheduled for deletion", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MessageResponse" } } } }, "400": { "description": "Confirmation does not match" }, "401": { "description": "Unauthorized" }, "403": { "description": "Owner role required" } }, "security": [ { "bearer": [] } ] }, "patch": { "tags": [ "Organization" ], "summary": "Update an organization", "operationId": "update_org", "parameters": [ { "name": "slug", "in": "path", "description": "Organization slug", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateOrgRequest" } } }, "required": true }, "responses": { "200": { "description": "Organization updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Organization" } } } }, "401": { "description": "Unauthorized" }, "403": { "description": "Insufficient permissions" } }, "security": [ { "bearer": [] } ] } }, "/v1/orgs/{slug}/members": { "get": { "tags": [ "Members" ], "summary": "List organization members", "operationId": "list_members", "parameters": [ { "name": "slug", "in": "path", "description": "Organization slug", "required": true, "schema": { "type": "string" } }, { "name": "cursor", "in": "query", "description": "Pagination cursor", "required": false, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "description": "Page size (default 20, max 100)", "required": false, "schema": { "type": "integer", "format": "int64" } } ], "responses": { "200": { "description": "Paginated list of members", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaginatedMemberResponse" } } } }, "401": { "description": "Unauthorized" }, "403": { "description": "Not a member" } }, "security": [ { "bearer": [] } ] } }, "/v1/orgs/{slug}/members/{user_id}": { "delete": { "tags": [ "Members" ], "summary": "Remove a member", "operationId": "remove_member", "parameters": [ { "name": "slug", "in": "path", "description": "Organization slug", "required": true, "schema": { "type": "string" } }, { "name": "user_id", "in": "path", "description": "Target user ID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Member removed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MessageResponse" } } } }, "400": { "description": "Cannot remove yourself" }, "401": { "description": "Unauthorized" }, "403": { "description": "Insufficient permissions" }, "404": { "description": "Member not found" } }, "security": [ { "bearer": [] } ] }, "patch": { "tags": [ "Members" ], "summary": "Change a member's role", "operationId": "update_member_role", "parameters": [ { "name": "slug", "in": "path", "description": "Organization slug", "required": true, "schema": { "type": "string" } }, { "name": "user_id", "in": "path", "description": "Target user ID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateMemberRoleRequest" } } }, "required": true }, "responses": { "200": { "description": "Role updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrgMember" } } } }, "401": { "description": "Unauthorized" }, "403": { "description": "Insufficient permissions" }, "404": { "description": "Member not found" } }, "security": [ { "bearer": [] } ] } }, "/v1/invites/{token}/accept": { "post": { "tags": [ "Invites" ], "summary": "Accept an invite", "operationId": "accept_invite", "parameters": [ { "name": "token", "in": "path", "description": "Invite token", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Invite accepted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MessageResponse" } } } }, "400": { "description": "Invalid or expired token" }, "401": { "description": "Unauthorized" }, "403": { "description": "Email mismatch" } }, "security": [ { "bearer": [] } ] } }, "/v1/invites/{token}/decline": { "post": { "tags": [ "Invites" ], "summary": "Decline an invite", "operationId": "decline_invite", "parameters": [ { "name": "token", "in": "path", "description": "Invite token", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Invite declined", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MessageResponse" } } } }, "400": { "description": "Invalid or expired token" }, "401": { "description": "Unauthorized" }, "403": { "description": "Email mismatch" } }, "security": [ { "bearer": [] } ] } }, "/v1/orgs/{slug}/invites": { "get": { "tags": [ "Invites" ], "summary": "List pending invites", "operationId": "list_invites", "parameters": [ { "name": "slug", "in": "path", "description": "Organization slug", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "List of pending invites", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/OrgInvite" } } } } }, "401": { "description": "Unauthorized" }, "403": { "description": "Insufficient permissions" } }, "security": [ { "bearer": [] } ] }, "post": { "tags": [ "Invites" ], "summary": "Invite a member", "operationId": "create_invite", "parameters": [ { "name": "slug", "in": "path", "description": "Organization slug", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateInviteRequest" } } }, "required": true }, "responses": { "200": { "description": "Invite created or refreshed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrgInvite" } } } }, "400": { "description": "Invalid email" }, "401": { "description": "Unauthorized" }, "403": { "description": "Insufficient permissions" }, "409": { "description": "User already a member" } }, "security": [ { "bearer": [] } ] } }, "/v1/orgs/{slug}/invites/{invite_id}": { "delete": { "tags": [ "Invites" ], "summary": "Cancel an invite", "operationId": "cancel_invite", "parameters": [ { "name": "slug", "in": "path", "description": "Organization slug", "required": true, "schema": { "type": "string" } }, { "name": "invite_id", "in": "path", "description": "Invite ID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Invite cancelled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MessageResponse" } } } }, "401": { "description": "Unauthorized" }, "403": { "description": "Insufficient permissions" }, "404": { "description": "Invite not found" } }, "security": [ { "bearer": [] } ] } }, "/v1/orgs/{slug}/oidc": { "get": { "tags": [ "OIDC" ], "summary": "Get organization SSO settings", "operationId": "get_oidc_config", "parameters": [ { "name": "slug", "in": "path", "description": "Organization slug", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OIDC configuration", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrgOidcConfig" } } } }, "401": { "description": "Unauthorized" }, "403": { "description": "Insufficient permissions" }, "404": { "description": "OIDC not configured" } }, "security": [ { "bearer": [] } ] }, "put": { "tags": [ "OIDC" ], "summary": "Configure organization SSO", "operationId": "upsert_oidc_config", "parameters": [ { "name": "slug", "in": "path", "description": "Organization slug", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpsertOidcConfigRequest" } } }, "required": true }, "responses": { "200": { "description": "OIDC config created or updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrgOidcConfig" } } } }, "401": { "description": "Unauthorized" }, "403": { "description": "Insufficient permissions" } }, "security": [ { "bearer": [] } ] }, "delete": { "tags": [ "OIDC" ], "summary": "Remove organization SSO settings", "operationId": "delete_oidc_config", "parameters": [ { "name": "slug", "in": "path", "description": "Organization slug", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OIDC config removed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MessageResponse" } } } }, "401": { "description": "Unauthorized" }, "403": { "description": "Insufficient permissions" }, "404": { "description": "OIDC not configured" } }, "security": [ { "bearer": [] } ] } }, "/v1/orgs/{slug}/api-keys": { "get": { "tags": [ "Credentials" ], "summary": "List API keys", "description": "Admins and owners see all keys. Members see only their own keys.", "operationId": "list_api_keys", "parameters": [ { "name": "slug", "in": "path", "description": "Organization slug", "required": true, "schema": { "type": "string" } }, { "name": "cursor", "in": "query", "description": "Pagination cursor", "required": false, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "description": "Page size (default 20, max 100)", "required": false, "schema": { "type": "integer", "format": "int64" } } ], "responses": { "200": { "description": "Paginated list of API keys", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaginatedApiKeyResponse" } } } }, "401": { "description": "Unauthorized" }, "403": { "description": "Insufficient permissions" } }, "security": [ { "bearer": [] } ] } }, "/v1/users/me/pats": { "get": { "tags": [ "Credentials" ], "summary": "List personal tokens", "description": "Returns metadata without token values.", "operationId": "list_pats", "responses": { "200": { "description": "Active PATs for the current user", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/PersonalAccessTokenResponse" } } } } }, "401": { "description": "Unauthorized" } }, "security": [ { "bearer": [] } ] } }, "/v1/users/me/pats/{id}": { "delete": { "tags": [ "Credentials" ], "summary": "Revoke a personal token", "description": "Returns not found when the token is missing or already revoked.", "operationId": "revoke_pat", "parameters": [ { "name": "id", "in": "path", "description": "PAT id", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "PAT revoked", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MessageResponse" } } } }, "401": { "description": "Unauthorized" }, "404": { "description": "PAT not found" } }, "security": [ { "bearer": [] } ] } }, "/v1/orgs/{slug}/registries": { "get": { "tags": [ "Registry credentials" ], "summary": "List registry credentials", "description": "Returns credential metadata without secret values.", "operationId": "list_registry_credentials", "parameters": [ { "name": "slug", "in": "path", "description": "Organization slug", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Configured registry credentials", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/RegistryCredentialResponse" } } } } }, "401": { "description": "Unauthorized" }, "403": { "description": "Insufficient permissions" } }, "security": [ { "bearer": [] } ] }, "put": { "tags": [ "Registry credentials" ], "summary": "Create or update a registry credential", "description": "Each registry host can have one stored credential.", "operationId": "upsert_registry_credential", "parameters": [ { "name": "slug", "in": "path", "description": "Organization slug", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpsertRegistryCredentialRequest" } } }, "required": true }, "responses": { "200": { "description": "Credential created or updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RegistryCredentialResponse" } } } }, "400": { "description": "Invalid request" }, "401": { "description": "Unauthorized" }, "403": { "description": "Insufficient permissions" } }, "security": [ { "bearer": [] } ] } }, "/v1/orgs/{slug}/registries/{id}": { "delete": { "tags": [ "Registry credentials" ], "summary": "Delete a registry credential", "operationId": "delete_registry_credential", "parameters": [ { "name": "slug", "in": "path", "description": "Organization slug", "required": true, "schema": { "type": "string" } }, { "name": "id", "in": "path", "description": "Registry credential id", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Credential removed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MessageResponse" } } } }, "401": { "description": "Unauthorized" }, "403": { "description": "Insufficient permissions" }, "404": { "description": "Credential not found" } }, "security": [ { "bearer": [] } ] } }, "/v1/orgs/{slug}/sandbox-slug/check": { "get": { "tags": [ "Sandboxes" ], "summary": "Check sandbox name availability", "description": "Check whether the sandbox slug is valid and available.", "operationId": "check_slug", "parameters": [ { "name": "slug", "in": "path", "description": "Organization slug", "required": true, "schema": { "type": "string" } }, { "name": "sandbox_slug", "in": "query", "description": "Candidate slug to validate + check. Named `sandbox_slug` in the query to\ndisambiguate from the org `:slug` route param.", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Slug validity + availability", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SlugAvailability" } } } }, "401": { "description": "Unauthorized" } }, "security": [ { "bearer": [] } ] } }, "/v1/orgs/{slug}/sandbox-slug/suggest": { "get": { "tags": [ "Sandboxes" ], "summary": "Suggest a sandbox name", "description": "Generate an available sandbox slug.", "operationId": "suggest_slug", "parameters": [ { "name": "slug", "in": "path", "description": "Organization slug", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "A suggested available slug", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SlugSuggestion" } } } }, "401": { "description": "Unauthorized" } }, "security": [ { "bearer": [] } ] } }, "/v1/orgs/{slug}/sandboxes": { "get": { "tags": [ "Sandboxes" ], "summary": "List sandboxes", "operationId": "list_sandboxes", "parameters": [ { "name": "slug", "in": "path", "description": "Organization slug", "required": true, "schema": { "type": "string" } }, { "name": "cursor", "in": "query", "description": "Pagination cursor", "required": false, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "description": "Page size (default 20, max 100)", "required": false, "schema": { "type": "integer", "format": "int64" } }, { "name": "labels", "in": "query", "description": "JSON object of labels to AND-match", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Paginated list of sandboxes", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaginatedSandboxResponse" } } } }, "401": { "description": "Unauthorized" }, "403": { "description": "Not a member" } }, "security": [ { "bearer": [] } ] }, "post": { "tags": [ "Sandboxes" ], "summary": "Create a sandbox", "description": "By default, the sandbox is created without starting. Use `start=true` to\nstart it immediately and `wait_for=running` to wait until it is ready.", "operationId": "create_sandbox", "parameters": [ { "name": "slug", "in": "path", "description": "Organization slug", "required": true, "schema": { "type": "string" } }, { "name": "start", "in": "query", "description": "If `true`, durably queue the sandbox for immediate orchestrator dispatch.", "required": false, "schema": { "type": "boolean" } }, { "name": "wait_for", "in": "query", "description": "Optional lifecycle state to wait for after durable start admission.", "required": false, "schema": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/SandboxWaitFor" } ] } }, { "name": "wait_timeout", "in": "query", "description": "Server-side wait budget in seconds; valid only with `wait_for`.", "required": false, "schema": { "type": [ "integer", "null" ], "format": "int64", "minimum": 0 } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateSandboxRequest" } } }, "required": true }, "responses": { "200": { "description": "Sandbox created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SandboxResponse" } } } }, "400": { "description": "Invalid request" }, "401": { "description": "Unauthorized" }, "409": { "description": "Name already exists" }, "429": { "description": "Readiness wait capacity exhausted" }, "502": { "description": "Orchestrator unreachable" } }, "security": [ { "bearer": [] } ] } }, "/v1/orgs/{slug}/sandboxes/{sandbox_id}": { "get": { "tags": [ "Sandboxes" ], "summary": "Get a sandbox", "operationId": "get_sandbox", "parameters": [ { "name": "slug", "in": "path", "description": "Organization slug", "required": true, "schema": { "type": "string" } }, { "name": "sandbox_id", "in": "path", "description": "Sandbox ID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Sandbox details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SandboxResponse" } } } }, "401": { "description": "Unauthorized" }, "404": { "description": "Sandbox not found" } }, "security": [ { "bearer": [] } ] }, "delete": { "tags": [ "Sandboxes" ], "summary": "Delete a sandbox", "description": "Resource cleanup continues asynchronously.", "operationId": "delete_sandbox", "parameters": [ { "name": "slug", "in": "path", "description": "Organization slug", "required": true, "schema": { "type": "string" } }, { "name": "sandbox_id", "in": "path", "description": "Sandbox ID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Sandbox scheduled for deletion", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MessageResponse" } } } }, "401": { "description": "Unauthorized" }, "404": { "description": "Sandbox not found" } }, "security": [ { "bearer": [] } ] }, "patch": { "tags": [ "Sandboxes" ], "summary": "Update a sandbox", "operationId": "update_sandbox", "parameters": [ { "name": "slug", "in": "path", "description": "Organization slug", "required": true, "schema": { "type": "string" } }, { "name": "sandbox_id", "in": "path", "description": "Sandbox ID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateSandboxRequest" } } }, "required": true }, "responses": { "200": { "description": "Updated sandbox", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SandboxResponse" } } } }, "400": { "description": "Invalid name/slug" }, "401": { "description": "Unauthorized" }, "404": { "description": "Sandbox not found" }, "409": { "description": "Name or slug already taken" } }, "security": [ { "bearer": [] } ] } }, "/v1/orgs/{slug}/sandboxes/{sandbox_id}/metrics": { "get": { "tags": [ "Sandboxes" ], "summary": "Get sandbox metrics", "description": "Returns CPU, memory, disk, and network metrics for a time range.", "operationId": "get_sandbox_metrics", "parameters": [ { "name": "slug", "in": "path", "description": "Organization slug", "required": true, "schema": { "type": "string" } }, { "name": "sandbox_id", "in": "path", "description": "Sandbox ID", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "range_secs", "in": "query", "description": "Look-back window in seconds (default 3600 = 1h, max 604800 = 7d).", "required": false, "schema": { "type": [ "integer", "null" ], "format": "int64", "minimum": 0 } }, { "name": "step_secs", "in": "query", "description": "Sample resolution in seconds (default 30, min 5).", "required": false, "schema": { "type": [ "integer", "null" ], "format": "int64", "minimum": 0 } } ], "responses": { "200": { "description": "Sandbox metrics", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SandboxMetricsResponse" } } } }, "400": { "description": "Invalid range/step" }, "401": { "description": "Unauthorized" }, "404": { "description": "Sandbox not found" }, "502": { "description": "Metrics backend unavailable" } }, "security": [ { "bearer": [] } ] } }, "/v1/orgs/{slug}/sandboxes/{sandbox_id}/start": { "post": { "tags": [ "Sandboxes" ], "summary": "Start a sandbox", "operationId": "start_sandbox", "parameters": [ { "name": "slug", "in": "path", "description": "Organization slug", "required": true, "schema": { "type": "string" } }, { "name": "sandbox_id", "in": "path", "description": "Sandbox ID", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "wait_for", "in": "query", "description": "Optional lifecycle state to wait for after durable start admission.", "required": false, "schema": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/SandboxWaitFor" } ] } }, { "name": "wait_timeout", "in": "query", "description": "Server-side wait budget in seconds; valid only with `wait_for`.", "required": false, "schema": { "type": [ "integer", "null" ], "format": "int64", "minimum": 0 } } ], "responses": { "200": { "description": "Sandbox start admitted or requested wait completed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SandboxResponse" } } } }, "401": { "description": "Unauthorized" }, "404": { "description": "Sandbox not found" }, "409": { "description": "Invalid state transition" }, "429": { "description": "Readiness wait capacity exhausted" }, "502": { "description": "Orchestrator unreachable" } }, "security": [ { "bearer": [] } ] } }, "/v1/orgs/{slug}/sandboxes/{sandbox_id}/stop": { "post": { "tags": [ "Sandboxes" ], "summary": "Stop a sandbox", "operationId": "stop_sandbox", "parameters": [ { "name": "slug", "in": "path", "description": "Organization slug", "required": true, "schema": { "type": "string" } }, { "name": "sandbox_id", "in": "path", "description": "Sandbox ID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Sandbox stopping", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SandboxResponse" } } } }, "401": { "description": "Unauthorized" }, "404": { "description": "Sandbox not found" }, "409": { "description": "Invalid state transition" }, "502": { "description": "Sandbox orchestrator unreachable" } }, "security": [ { "bearer": [] } ] } }, "/v1/orgs/{slug}/sandboxes/{sandbox_id}/volumes": { "get": { "tags": [ "Sandboxes" ], "summary": "List mounted volumes", "operationId": "list_sandbox_volumes", "parameters": [ { "name": "slug", "in": "path", "description": "Organization slug", "required": true, "schema": { "type": "string" } }, { "name": "sandbox_id", "in": "path", "description": "Sandbox ID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Mounted volumes", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/SandboxVolumeMount" } } } } }, "401": { "description": "Unauthorized" }, "404": { "description": "Sandbox not found" } }, "security": [ { "bearer": [] } ] } }, "/v1/orgs/{slug}/sandboxes/snapshot-candidates": { "get": { "tags": [ "Snapshots" ], "summary": "List sandboxes available for snapshots", "operationId": "list_snapshot_candidates", "parameters": [ { "name": "slug", "in": "path", "description": "Organization slug", "required": true, "schema": { "type": "string" } }, { "name": "cursor", "in": "query", "description": "Pagination cursor", "required": false, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "description": "Page size (default 20, max 100)", "required": false, "schema": { "type": "integer", "format": "int64" } } ], "responses": { "200": { "description": "Paginated snapshot candidates", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaginatedSnapshotCandidateResponse" } } } }, "401": { "description": "Unauthorized" }, "403": { "description": "Insufficient permissions" } }, "security": [ { "bearer": [] } ] } }, "/v1/orgs/{slug}/snapshot-operations": { "get": { "tags": [ "Snapshots" ], "summary": "List snapshot operations", "operationId": "list_operations", "parameters": [ { "name": "slug", "in": "path", "description": "Organization slug", "required": true, "schema": { "type": "string" } }, { "name": "cursor", "in": "query", "description": "Pagination cursor", "required": false, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "description": "Page size (default 20, max 100)", "required": false, "schema": { "type": "integer", "format": "int64" } }, { "name": "exclude_redundant", "in": "query", "description": "Hide successful managed operations and superseded host-volume operations represented in snapshot inventory", "required": false, "schema": { "type": "boolean" } } ], "responses": { "200": { "description": "Explicit snapshot operations", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaginatedSnapshotOperationResponse" } } } }, "401": { "description": "Unauthorized" }, "403": { "description": "Insufficient permissions" } }, "security": [ { "bearer": [] } ] } }, "/v1/orgs/{slug}/snapshot-operations/{operation_id}": { "get": { "tags": [ "Snapshots" ], "summary": "Get a snapshot operation", "operationId": "get_operation", "parameters": [ { "name": "slug", "in": "path", "description": "Organization slug", "required": true, "schema": { "type": "string" } }, { "name": "operation_id", "in": "path", "description": "Snapshot operation id", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Snapshot operation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CloudSnapshotOperation" } } } }, "401": { "description": "Unauthorized" }, "404": { "description": "Snapshot operation not found" } }, "security": [ { "bearer": [] } ] } }, "/v1/orgs/{slug}/snapshots": { "get": { "tags": [ "Snapshots" ], "summary": "List snapshots", "operationId": "list_snapshots", "parameters": [ { "name": "slug", "in": "path", "description": "Organization slug", "required": true, "schema": { "type": "string" } }, { "name": "cursor", "in": "query", "description": "Pagination cursor", "required": false, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "description": "Page size (default 20, max 100)", "required": false, "schema": { "type": "integer", "format": "int64" } } ], "responses": { "200": { "description": "Managed snapshots", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaginatedSnapshotResponse" } } } }, "401": { "description": "Unauthorized" }, "403": { "description": "Insufficient permissions" } }, "security": [ { "bearer": [] } ] }, "post": { "tags": [ "Snapshots" ], "summary": "Create a snapshot", "operationId": "create", "parameters": [ { "name": "slug", "in": "path", "description": "Organization slug", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CloudCreateSnapshotRequest" } } }, "required": true }, "responses": { "202": { "description": "Snapshot capture queued", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CloudSnapshotOperation" } } } }, "400": { "description": "Invalid snapshot request" }, "401": { "description": "Unauthorized" }, "403": { "description": "Insufficient permissions" }, "404": { "description": "Source sandbox not found" }, "409": { "description": "Snapshot destination already exists" }, "422": { "description": "Unsupported or ineligible snapshot request" } }, "security": [ { "bearer": [] } ] } }, "/v1/orgs/{slug}/snapshots/by-name/{name}": { "get": { "tags": [ "Snapshots" ], "summary": "Get a snapshot by name", "operationId": "get_snapshot_by_name", "parameters": [ { "name": "slug", "in": "path", "description": "Organization slug", "required": true, "schema": { "type": "string" } }, { "name": "name", "in": "path", "description": "Managed snapshot name", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Managed snapshot", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CloudSnapshot" } } } }, "401": { "description": "Unauthorized" }, "404": { "description": "Snapshot not found" } }, "security": [ { "bearer": [] } ] }, "delete": { "tags": [ "Snapshots" ], "summary": "Delete a snapshot by name", "operationId": "delete_snapshot_by_name", "parameters": [ { "name": "slug", "in": "path", "description": "Organization slug", "required": true, "schema": { "type": "string" } }, { "name": "name", "in": "path", "description": "Managed snapshot name", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Snapshot deleted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MessageResponse" } } } }, "401": { "description": "Unauthorized" }, "404": { "description": "Snapshot not found" } }, "security": [ { "bearer": [] } ] } }, "/v1/orgs/{slug}/snapshots/{snapshot_id}": { "get": { "tags": [ "Snapshots" ], "summary": "Get a snapshot by ID", "operationId": "get", "parameters": [ { "name": "slug", "in": "path", "description": "Organization slug", "required": true, "schema": { "type": "string" } }, { "name": "snapshot_id", "in": "path", "description": "Managed snapshot id", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Managed snapshot", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CloudSnapshot" } } } }, "401": { "description": "Unauthorized" }, "404": { "description": "Snapshot not found" } }, "security": [ { "bearer": [] } ] }, "delete": { "tags": [ "Snapshots" ], "summary": "Delete a snapshot by ID", "operationId": "delete", "parameters": [ { "name": "slug", "in": "path", "description": "Organization slug", "required": true, "schema": { "type": "string" } }, { "name": "snapshot_id", "in": "path", "description": "Managed snapshot id", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Snapshot deleted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MessageResponse" } } } }, "401": { "description": "Unauthorized" }, "404": { "description": "Snapshot not found" } }, "security": [ { "bearer": [] } ] } }, "/v1/orgs/{slug}/volumes": { "get": { "tags": [ "Volumes" ], "summary": "List volumes", "operationId": "list_volumes", "parameters": [ { "name": "slug", "in": "path", "description": "Organization slug", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "The org's volumes", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/VolumeResponse" } } } } }, "401": { "description": "Unauthorized" }, "403": { "description": "Insufficient permissions" } }, "security": [ { "bearer": [] } ] }, "post": { "tags": [ "Volumes" ], "summary": "Create a volume", "operationId": "create_volume", "parameters": [ { "name": "slug", "in": "path", "description": "Organization slug", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateVolumeRequest" } } }, "required": true }, "responses": { "200": { "description": "Volume created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VolumeResponse" } } } }, "400": { "description": "Invalid request" }, "401": { "description": "Unauthorized" }, "403": { "description": "Insufficient permissions" }, "409": { "description": "Volume name already in use" } }, "security": [ { "bearer": [] } ] } }, "/v1/orgs/{slug}/volumes/default": { "get": { "tags": [ "Volumes" ], "summary": "Get the default volume", "operationId": "get_default", "parameters": [ { "name": "slug", "in": "path", "description": "Organization slug", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Get the default volume", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VolumeResponse" } } } }, "401": { "description": "Unauthorized" }, "403": { "description": "Insufficient permissions" } }, "security": [ { "bearer": [] } ] } }, "/v1/orgs/{slug}/volumes/{id}": { "delete": { "tags": [ "Volumes" ], "summary": "Delete a volume", "operationId": "delete_volume", "parameters": [ { "name": "slug", "in": "path", "description": "Organization slug", "required": true, "schema": { "type": "string" } }, { "name": "id", "in": "path", "description": "Volume id", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Volume scheduled for deletion", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MessageResponse" } } } }, "401": { "description": "Unauthorized" }, "403": { "description": "Insufficient permissions" }, "404": { "description": "Volume not found" }, "409": { "description": "The host volume cannot be deleted, or it is in use by a sandbox" } }, "security": [ { "bearer": [] } ] }, "patch": { "tags": [ "Volumes" ], "summary": "Update a volume", "operationId": "update_volume", "parameters": [ { "name": "slug", "in": "path", "description": "Organization slug", "required": true, "schema": { "type": "string" } }, { "name": "id", "in": "path", "description": "Volume id", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateVolumeRequest" } } }, "required": true }, "responses": { "200": { "description": "Volume updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VolumeResponse" } } } }, "400": { "description": "Invalid request (e.g. cap exceeds the org cap)" }, "401": { "description": "Unauthorized" }, "403": { "description": "Insufficient permissions" }, "404": { "description": "Volume not found" }, "409": { "description": "The host volume cannot be capped" } }, "security": [ { "bearer": [] } ] } }, "/v1/orgs/{slug}/volumes/{id}/files": { "get": { "tags": [ "Volumes" ], "summary": "List directory contents", "operationId": "list_directory_contents", "parameters": [ { "name": "slug", "in": "path", "description": "Organization slug", "required": true, "schema": { "type": "string" } }, { "name": "id", "in": "path", "description": "Volume UUID", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "x-msb-file-path", "in": "header", "description": "URL-safe base64 encoded volume-relative UTF-8 path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "List directory contents", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VolumeFileListResponse" } } } }, "400": { "description": "Invalid request" }, "401": { "description": "Unauthorized" }, "403": { "description": "Insufficient permissions" }, "404": { "description": "Volume or path not found" }, "502": { "description": "Volume filesystem unavailable" } }, "security": [ { "bearer": [] } ] }, "delete": { "tags": [ "Volumes" ], "summary": "Delete a file or directory", "operationId": "remove", "parameters": [ { "name": "slug", "in": "path", "description": "Organization slug", "required": true, "schema": { "type": "string" } }, { "name": "id", "in": "path", "description": "Volume UUID", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "x-msb-file-path", "in": "header", "description": "URL-safe base64 encoded volume-relative UTF-8 path", "required": true, "schema": { "type": "string" } }, { "name": "x-msb-file-recursive", "in": "header", "description": "Recursively remove a directory; defaults to false", "required": false, "schema": { "type": [ "boolean", "null" ] } } ], "responses": { "200": { "description": "Delete a file or directory", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VolumeFileMutationResponse" } } } }, "400": { "description": "Invalid request" }, "401": { "description": "Unauthorized" }, "403": { "description": "Insufficient permissions" }, "404": { "description": "Volume or path not found" }, "502": { "description": "Volume filesystem unavailable" } }, "security": [ { "bearer": [] } ] } }, "/v1/orgs/{slug}/volumes/{id}/files/content": { "get": { "tags": [ "Volumes" ], "summary": "Read a file", "operationId": "read", "parameters": [ { "name": "slug", "in": "path", "description": "Organization slug", "required": true, "schema": { "type": "string" } }, { "name": "id", "in": "path", "description": "Volume UUID", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "x-msb-file-path", "in": "header", "description": "URL-safe base64 encoded volume-relative UTF-8 path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Read a file", "content": { "application/octet-stream": { "schema": { "$ref": "#/components/schemas/VolumeFileContent" } } } }, "400": { "description": "Invalid request" }, "401": { "description": "Unauthorized" }, "403": { "description": "Insufficient permissions" }, "404": { "description": "Volume or path not found" }, "502": { "description": "Volume filesystem unavailable" } }, "security": [ { "bearer": [] } ] }, "put": { "tags": [ "Volumes" ], "summary": "Write a file", "operationId": "write", "parameters": [ { "name": "slug", "in": "path", "description": "Organization slug", "required": true, "schema": { "type": "string" } }, { "name": "id", "in": "path", "description": "Volume UUID", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "x-msb-file-path", "in": "header", "description": "URL-safe base64 encoded volume-relative UTF-8 path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/octet-stream": { "schema": { "$ref": "#/components/schemas/VolumeFileContent" } } }, "required": true }, "responses": { "200": { "description": "Write a file", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VolumeFileMutationResponse" } } } }, "400": { "description": "Invalid request" }, "401": { "description": "Unauthorized" }, "403": { "description": "Insufficient permissions" }, "404": { "description": "Volume or path not found" }, "502": { "description": "Volume filesystem unavailable" } }, "security": [ { "bearer": [] } ] } }, "/v1/orgs/{slug}/volumes/{id}/files/copy": { "post": { "tags": [ "Volumes" ], "summary": "Copy a file or directory", "operationId": "copy", "parameters": [ { "name": "slug", "in": "path", "description": "Organization slug", "required": true, "schema": { "type": "string" } }, { "name": "id", "in": "path", "description": "Volume UUID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FileMoveRequest" } } }, "required": true }, "responses": { "200": { "description": "Copy a file or directory", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VolumeFileMutationResponse" } } } }, "400": { "description": "Invalid request" }, "401": { "description": "Unauthorized" }, "403": { "description": "Insufficient permissions" }, "404": { "description": "Volume or path not found" }, "502": { "description": "Volume filesystem unavailable" } }, "security": [ { "bearer": [] } ] } }, "/v1/orgs/{slug}/volumes/{id}/files/exists": { "get": { "tags": [ "Volumes" ], "summary": "Check if a file exists", "operationId": "exists", "parameters": [ { "name": "slug", "in": "path", "description": "Organization slug", "required": true, "schema": { "type": "string" } }, { "name": "id", "in": "path", "description": "Volume UUID", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "x-msb-file-path", "in": "header", "description": "URL-safe base64 encoded volume-relative UTF-8 path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Check if a file exists", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VolumeFileExistsResponse" } } } }, "400": { "description": "Invalid request" }, "401": { "description": "Unauthorized" }, "403": { "description": "Insufficient permissions" }, "404": { "description": "Volume or path not found" }, "502": { "description": "Volume filesystem unavailable" } }, "security": [ { "bearer": [] } ] }, "post": { "tags": [ "Volumes" ], "summary": "Check if files exist", "operationId": "exists_batch", "parameters": [ { "name": "slug", "in": "path", "description": "Organization slug", "required": true, "schema": { "type": "string" } }, { "name": "id", "in": "path", "description": "Volume UUID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FilePathsRequest" } } }, "required": true }, "responses": { "200": { "description": "Check if files exist", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VolumeFileExistsBatchResponse" } } } }, "400": { "description": "Invalid request" }, "401": { "description": "Unauthorized" }, "403": { "description": "Insufficient permissions" }, "404": { "description": "Volume or path not found" }, "502": { "description": "Volume filesystem unavailable" } }, "security": [ { "bearer": [] } ] } }, "/v1/orgs/{slug}/volumes/{id}/files/mkdir": { "post": { "tags": [ "Volumes" ], "summary": "Create a directory", "operationId": "mkdir", "parameters": [ { "name": "slug", "in": "path", "description": "Organization slug", "required": true, "schema": { "type": "string" } }, { "name": "id", "in": "path", "description": "Volume UUID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FilePathRequest" } } }, "required": true }, "responses": { "200": { "description": "Create a directory", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VolumeFileMutationResponse" } } } }, "400": { "description": "Invalid request" }, "401": { "description": "Unauthorized" }, "403": { "description": "Insufficient permissions" }, "404": { "description": "Volume or path not found" }, "502": { "description": "Volume filesystem unavailable" } }, "security": [ { "bearer": [] } ] } }, "/v1/orgs/{slug}/volumes/{id}/files/rename": { "post": { "tags": [ "Volumes" ], "summary": "Move a file or directory", "operationId": "rename", "parameters": [ { "name": "slug", "in": "path", "description": "Organization slug", "required": true, "schema": { "type": "string" } }, { "name": "id", "in": "path", "description": "Volume UUID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FileMoveRequest" } } }, "required": true }, "responses": { "200": { "description": "Move a file or directory", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VolumeFileMutationResponse" } } } }, "400": { "description": "Invalid request" }, "401": { "description": "Unauthorized" }, "403": { "description": "Insufficient permissions" }, "404": { "description": "Volume or path not found" }, "502": { "description": "Volume filesystem unavailable" } }, "security": [ { "bearer": [] } ] } }, "/v1/orgs/{slug}/volumes/{id}/files/stat": { "get": { "tags": [ "Volumes" ], "summary": "Get file details", "operationId": "stat", "parameters": [ { "name": "slug", "in": "path", "description": "Organization slug", "required": true, "schema": { "type": "string" } }, { "name": "id", "in": "path", "description": "Volume UUID", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "x-msb-file-path", "in": "header", "description": "URL-safe base64 encoded volume-relative UTF-8 path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Get file details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VolumeFileStatResponse" } } } }, "400": { "description": "Invalid request" }, "401": { "description": "Unauthorized" }, "403": { "description": "Insufficient permissions" }, "404": { "description": "Volume or path not found" }, "502": { "description": "Volume filesystem unavailable" } }, "security": [ { "bearer": [] } ] } }, "/v1/orgs/{slug}/volumes/{id}/metrics": { "get": { "tags": [ "Volumes" ], "summary": "Get volume metrics", "operationId": "get_volume_metrics", "parameters": [ { "name": "slug", "in": "path", "description": "Organization slug", "required": true, "schema": { "type": "string" } }, { "name": "id", "in": "path", "description": "Volume id", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "range_secs", "in": "query", "description": "Look-back window in seconds (default 3600 = 1h, max 604800 = 7d).", "required": false, "schema": { "type": [ "integer", "null" ], "format": "int64", "minimum": 0 } }, { "name": "step_secs", "in": "query", "description": "Sample resolution in seconds (default 30, min 5).", "required": false, "schema": { "type": [ "integer", "null" ], "format": "int64", "minimum": 0 } } ], "responses": { "200": { "description": "Volume performance metrics", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VolumeMetricsResponse" } } } }, "400": { "description": "Invalid time range or resolution" }, "401": { "description": "Unauthorized" }, "403": { "description": "Insufficient permissions" }, "404": { "description": "Volume not found" }, "502": { "description": "Metrics backend unavailable" } }, "security": [ { "bearer": [] } ] } }, "/v1/orgs/{slug}/quotas": { "get": { "tags": [ "Quotas" ], "summary": "Get quota usage", "operationId": "get_quotas", "parameters": [ { "name": "slug", "in": "path", "description": "Organization slug", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Quota usage", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QuotaUsage" } } } }, "401": { "description": "Unauthorized" }, "403": { "description": "Not a member" }, "404": { "description": "Org not found" } }, "security": [ { "bearer": [] } ] } }, "/v1/orgs/{slug}/billing": { "get": { "tags": [ "Billing" ], "summary": "Get billing summary", "operationId": "get_billing", "parameters": [ { "name": "slug", "in": "path", "description": "Organization slug", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Billing summary", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BillingSummaryResponse" } } } }, "401": { "description": "Unauthorized" }, "403": { "description": "Not a member" } }, "security": [ { "bearer": [] } ] } }, "/v1/orgs/{slug}/billing/cancel": { "post": { "tags": [ "Billing" ], "summary": "Cancel the subscription", "description": "Cancellation takes effect at the end of the billing period.", "operationId": "cancel_subscription", "parameters": [ { "name": "slug", "in": "path", "description": "Organization slug", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Cancellation scheduled for period end", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BillingSummaryResponse" } } } }, "401": { "description": "Unauthorized" }, "403": { "description": "Insufficient permissions" } }, "security": [ { "bearer": [] } ] } }, "/v1/orgs/{slug}/billing/invoices": { "get": { "tags": [ "Billing" ], "summary": "List invoices", "operationId": "list_invoices", "parameters": [ { "name": "slug", "in": "path", "description": "Organization slug", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Invoice list", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Invoice" } } } } }, "401": { "description": "Unauthorized" } }, "security": [ { "bearer": [] } ] } }, "/v1/orgs/{slug}/billing/invoices/{invoice_id}": { "get": { "tags": [ "Billing" ], "summary": "Get an invoice", "operationId": "get_invoice", "parameters": [ { "name": "slug", "in": "path", "description": "Organization slug", "required": true, "schema": { "type": "string" } }, { "name": "invoice_id", "in": "path", "description": "Invoice ID", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Invoice detail", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Invoice" } } } }, "401": { "description": "Unauthorized" }, "404": { "description": "Invoice not found" } }, "security": [ { "bearer": [] } ] } }, "/v1/orgs/{slug}/billing/payment-portal": { "get": { "tags": [ "Billing" ], "summary": "Open the payment portal", "description": "Returns a URL for managing payment methods.", "operationId": "payment_portal", "parameters": [ { "name": "slug", "in": "path", "description": "Organization slug", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Payment portal URL", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentPortalResponse" } } } }, "401": { "description": "Unauthorized" }, "403": { "description": "Insufficient permissions" } }, "security": [ { "bearer": [] } ] } }, "/v1/orgs/{slug}/billing/plan": { "put": { "tags": [ "Billing" ], "summary": "Change the billing plan", "operationId": "change_plan", "parameters": [ { "name": "slug", "in": "path", "description": "Organization slug", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChangePlanRequest" } } }, "required": true }, "responses": { "200": { "description": "Plan changed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BillingSummaryResponse" } } } }, "400": { "description": "Invalid plan or payment method required" }, "401": { "description": "Unauthorized" }, "403": { "description": "Insufficient permissions" } }, "security": [ { "bearer": [] } ] } }, "/v1/orgs/{slug}/billing/plans": { "get": { "tags": [ "Billing" ], "summary": "List billing plans", "operationId": "list_plans", "parameters": [ { "name": "slug", "in": "path", "description": "Organization slug", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Available plans", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/BillingPlan" } } } } }, "401": { "description": "Unauthorized" } }, "security": [ { "bearer": [] } ] } }, "/v1/orgs/{slug}/billing/usage": { "get": { "tags": [ "Billing" ], "summary": "Get estimated usage costs", "description": "Includes the subscription and estimated overage for the current period.", "operationId": "get_usage", "parameters": [ { "name": "slug", "in": "path", "description": "Organization slug", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Cost estimate for the current period", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UsageSummary" } } } }, "401": { "description": "Unauthorized" } }, "security": [ { "bearer": [] } ] } }, "/v1/orgs/{slug}/billing/usage/sandbox": { "get": { "tags": [ "Billing" ], "summary": "Get sandbox usage", "description": "Groups compute usage by sandbox and day for the requested time range.", "operationId": "get_sandbox_breakdown", "parameters": [ { "name": "slug", "in": "path", "description": "Organization slug", "required": true, "schema": { "type": "string" } }, { "name": "from", "in": "query", "description": "Window start (RFC 3339); defaults to month start", "required": false, "schema": { "type": "string" } }, { "name": "to", "in": "query", "description": "Window end (RFC 3339); defaults to now", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Per-sandbox / per-day usage", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UsageBreakdown" } } } }, "401": { "description": "Unauthorized" } }, "security": [ { "bearer": [] } ] } }, "/v1/orgs/{slug}/billing/usage/storage": { "get": { "tags": [ "Billing" ], "summary": "Get storage usage", "description": "Groups persistent storage usage by volume and day for the requested time range.", "operationId": "get_storage_breakdown", "parameters": [ { "name": "slug", "in": "path", "description": "Organization slug", "required": true, "schema": { "type": "string" } }, { "name": "from", "in": "query", "description": "Window start (RFC 3339); defaults to month start", "required": false, "schema": { "type": "string" } }, { "name": "to", "in": "query", "description": "Window end (RFC 3339); defaults to now", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Per-volume / per-day storage usage", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StorageBreakdown" } } } }, "401": { "description": "Unauthorized" } }, "security": [ { "bearer": [] } ] } }, "/v1/orgs/{slug}/events": { "get": { "tags": [ "Audit events" ], "summary": "List audit events", "description": "Returns customer-visible audit events with optional filters.", "operationId": "list_events", "parameters": [ { "name": "slug", "in": "path", "description": "Organization slug", "required": true, "schema": { "type": "string" } }, { "name": "event_type", "in": "query", "description": "Filter by event type (e.g. \"api_key_created\").", "required": false, "schema": { "type": [ "string", "null" ] } }, { "name": "since", "in": "query", "description": "Only return events at or after this timestamp.", "required": false, "schema": { "type": [ "string", "null" ], "format": "date-time" } }, { "name": "until", "in": "query", "description": "Only return events at or before this timestamp.", "required": false, "schema": { "type": [ "string", "null" ], "format": "date-time" } }, { "name": "cursor", "in": "query", "description": "Opaque cursor from a previous response.", "required": false, "schema": { "type": [ "string", "null" ] } }, { "name": "limit", "in": "query", "description": "Number of items to return (default: 20, max: 100).", "required": false, "schema": { "type": [ "integer", "null" ], "format": "int64" } } ], "responses": { "200": { "description": "Paginated list of audit events", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaginatedEventResponse" } } } }, "401": { "description": "Unauthorized" }, "403": { "description": "Insufficient permissions" } }, "security": [ { "bearer": [] } ] } }, "/v1/orgs/{slug}/events/{event_id}": { "get": { "tags": [ "Audit events" ], "summary": "Get an audit event", "operationId": "get_event", "parameters": [ { "name": "slug", "in": "path", "description": "Organization slug", "required": true, "schema": { "type": "string" } }, { "name": "event_id", "in": "path", "description": "Event ID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Event details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EventResponse" } } } }, "401": { "description": "Unauthorized" }, "403": { "description": "Insufficient permissions" }, "404": { "description": "Event not found" } }, "security": [ { "bearer": [] } ] } } }, "components": { "schemas": { "Action": { "type": "string", "description": "Action to take on traffic matched by a [`Rule`] (or a policy default).", "enum": [ "allow", "deny" ] }, "ApiKeyResponse": { "type": "object", "description": "API key metadata returned in list responses. Never includes the raw key or hashes.", "required": [ "id", "name", "created_at" ], "properties": { "created_at": { "type": "string", "format": "date-time" }, "expires_at": { "type": [ "string", "null" ], "format": "date-time" }, "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" } } }, "BillingEffectiveState": { "type": "string", "description": "Effective billing state derived from plan, period end, and suspension.", "enum": [ "free", "active", "past_due", "suspended" ] }, "BillingPlan": { "type": "object", "description": "Billing plan definition with resource quotas.\n\n`name` is the plan's identity, an arbitrary catalog string (no fixed enum) -\n\"free\"/\"builder\"/… are just the names we ship. Every quota is `Option`:\n`None` = unlimited (counts/budgets) or the platform default (per-sandbox\nvCPU/memory/disk). There is no magic 0.", "required": [ "id", "name", "display_name", "self_serve", "is_default", "created_at", "updated_at" ], "properties": { "created_at": { "type": "string", "format": "date-time" }, "description": { "type": [ "string", "null" ] }, "display_name": { "type": "string" }, "id": { "type": "string", "format": "uuid" }, "included_disk_gib_hours": { "type": [ "integer", "null" ], "format": "int32" }, "included_memory_gib_hours": { "type": [ "integer", "null" ], "format": "int32" }, "included_storage_gib": { "type": [ "integer", "null" ], "format": "int32" }, "included_vcpu_hours": { "type": [ "integer", "null" ], "format": "int32", "description": "Monthly included allowances bundled into the flat fee (pool of vCPU-hours /\nmemory GiB-hours / writable-disk GiB-hours / durable-storage GiB). Usage\nbeyond the pool is metered overage on priced plans; on an unpriced (free)\nplan the compute pool is a hard wall." }, "is_default": { "type": "boolean", "description": "The plan new orgs are assigned. Exactly one row is the default." }, "max_concurrent_ephemeral_running": { "type": [ "integer", "null" ], "format": "int32", "description": "Max simultaneously-running *ephemeral* sandboxes (cheap, self-cleaning)." }, "max_concurrent_persistent_running": { "type": [ "integer", "null" ], "format": "int32", "description": "Max simultaneously-running *persistent* sandboxes (snapshot/restore cost)." }, "max_disk_size_mib_per_sandbox": { "type": [ "integer", "null" ], "format": "int32", "description": "Maximum writable disk size (MiB) per sandbox." }, "max_memory_mib_per_sandbox": { "type": [ "integer", "null" ], "format": "int32" }, "max_sandboxes": { "type": [ "integer", "null" ], "format": "int32" }, "max_snapshot_storage_gib": { "type": [ "integer", "null" ], "format": "int32", "description": "Per-org managed-snapshot storage hard cap (GiB), compared against the\nsummed compressed archive size of the org's managed snapshots." }, "max_total_storage_gib": { "type": [ "integer", "null" ], "format": "int32", "description": "Per-org durable-storage hard cap (GiB). Used storage is billed at a flat\nper-GB-month rate (no free allotment)." }, "max_uptime_minutes_per_sandbox": { "type": [ "integer", "null" ], "format": "int32" }, "max_vcpus_per_sandbox": { "type": [ "integer", "null" ], "format": "int32" }, "monthly_sandbox_minutes": { "type": [ "integer", "null" ], "format": "int32", "description": "Deprecated wall-clock minutes budget (NULL). The compute wall is now\n`included_vcpu_hours` on unpriced plans." }, "name": { "type": "string" }, "self_serve": { "type": "boolean", "description": "May a user self-subscribe to this plan via the API? Fail-closed; the\nchange-plan check keys on this flag, not the plan name." }, "subscription_price_cents": { "type": [ "integer", "null" ], "format": "int64", "description": "Flat monthly subscription price (cents); `None` = unpriced (free). Source\nof upgrade/downgrade ordering - compare prices, not a fixed tier rank." }, "trial_duration_days": { "type": [ "integer", "null" ], "format": "int32" }, "updated_at": { "type": "string", "format": "date-time" }, "usage_disk_gib_hour_usd": { "type": [ "number", "null" ], "format": "double" }, "usage_memory_gib_hour_usd": { "type": [ "number", "null" ], "format": "double" }, "usage_snapshot_storage_gib_month_usd": { "type": [ "number", "null" ], "format": "double", "description": "Managed-snapshot storage rate (USD/GiB-month), separate from volumes." }, "usage_storage_gib_month_usd": { "type": [ "number", "null" ], "format": "double" }, "usage_vcpu_hour_usd": { "type": [ "number", "null" ], "format": "double", "description": "Per-unit overage rates (USD) charged on usage beyond the included pool;\n`None` on the free/unpriced plan (no overage path). Drive the live cost\nestimate `subscription + Σ overage`; Autumn's invoice stays authoritative." } } }, "BillingPlanSummary": { "type": "object", "description": "Summary of a billing plan (subset of full plan).", "required": [ "name", "display_name", "has_custom_billing_terms" ], "properties": { "display_name": { "type": "string" }, "has_custom_billing_terms": { "type": "boolean" }, "name": { "type": "string" } } }, "BillingPricingTerms": { "type": "object", "description": "Pricing fields which may be inherited from a plan or negotiated per customer.", "properties": { "included_disk_gib_hours": { "type": [ "integer", "null" ], "format": "int32" }, "included_memory_gib_hours": { "type": [ "integer", "null" ], "format": "int32" }, "included_storage_gib": { "type": [ "integer", "null" ], "format": "int32" }, "included_vcpu_hours": { "type": [ "integer", "null" ], "format": "int32" }, "subscription_price_cents": { "type": [ "integer", "null" ], "format": "int64" }, "usage_disk_gib_hour_usd": { "type": [ "number", "null" ], "format": "double" }, "usage_memory_gib_hour_usd": { "type": [ "number", "null" ], "format": "double" }, "usage_snapshot_storage_gib_month_usd": { "type": [ "number", "null" ], "format": "double" }, "usage_storage_gib_month_usd": { "type": [ "number", "null" ], "format": "double" }, "usage_vcpu_hour_usd": { "type": [ "number", "null" ], "format": "double" } } }, "BillingSummaryResponse": { "type": "object", "description": "Billing summary response for an organization.", "required": [ "plan", "effective_pricing", "effective_state", "is_suspended" ], "properties": { "available_credit_cents": { "type": [ "integer", "null" ], "format": "int64", "description": "Positive USD credit Stripe will apply automatically to future invoices.", "minimum": 0 }, "billing_terms_override": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/BillingTermsOverrideSummary", "description": "Current agreement metadata, including setup and payment-pending states." } ] }, "checkout_url": { "type": [ "string", "null" ], "description": "Hosted-checkout URL to complete payment for a just-changed plan (Autumn).\nSet only on a plan change that needs payment; the client redirects to it." }, "current_period_ends_at": { "type": [ "string", "null" ], "format": "date-time" }, "effective_pricing": { "$ref": "#/components/schemas/BillingPricingTerms", "description": "Effective commercial terms after applying any org-specific agreement." }, "effective_state": { "$ref": "#/components/schemas/BillingEffectiveState" }, "is_suspended": { "type": "boolean" }, "pending_plan": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/BillingPlanSummary", "description": "Plan the org will switch to at `current_period_ends_at`, if a downgrade is scheduled." } ] }, "plan": { "$ref": "#/components/schemas/BillingPlanSummary" } } }, "BillingTermsOverrideSummary": { "type": "object", "description": "Effective window for the org's active negotiated billing terms.", "required": [ "status", "plan", "effective_from" ], "properties": { "effective_from": { "type": "string", "format": "date-time" }, "effective_until": { "type": [ "string", "null" ], "format": "date-time" }, "plan": { "$ref": "#/components/schemas/BillingPlanSummary" }, "post_expiry_plan": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/BillingPlanSummary", "description": "Explicit plan assigned at expiry; absent means target-plan retail pricing." } ] }, "status": { "$ref": "#/components/schemas/OrgBillingTermsOverrideStatus" } } }, "CertCacheConfig": { "type": "object", "description": "Per-domain certificate cache configuration.", "properties": { "capacity": { "type": "integer", "description": "Maximum number of cached certificates. Default: 1000.", "minimum": 0 }, "validity_hours": { "type": "integer", "format": "int64", "description": "Certificate validity duration in hours. Default: 24.", "minimum": 0 } } }, "ChangePlanRequest": { "type": "object", "description": "PUT /v1/orgs/:slug/billing/plan - change billing plan.", "required": [ "plan" ], "properties": { "plan": { "type": "string", "description": "Catalog name of the plan to switch to (e.g. \"builder\")." } } }, "CheckpointSnapshotState": { "type": "object", "description": "Immutable checkpoint-manifest-backed snapshot state.", "required": [ "checkpoint_id", "manifest" ], "properties": { "checkpoint_id": { "type": "string", "description": "Stable identifier for the captured cut." }, "manifest": { "type": "string", "description": "SHA-256 identity of the disk or composite checkpoint manifest." } }, "additionalProperties": false }, "CloudCreateSandboxRequest": { "oneOf": [ { "allOf": [ { "$ref": "#/components/schemas/CloudSandboxSpec", "description": "Settings shared by every sandbox source." }, { "type": "object", "required": [ "reference" ], "properties": { "patches": { "type": "array", "items": { "$ref": "#/components/schemas/CloudPatch" }, "description": "Rootfs patches applied before VM start." }, "pull_policy": { "$ref": "#/components/schemas/CloudPullPolicy", "description": "OCI image pull policy." }, "reference": { "type": "string", "description": "OCI image reference." }, "resources": { "$ref": "#/components/schemas/CloudSandboxResources", "description": "CPU, memory, and writable-disk resources." } } }, { "type": "object", "description": "Create a sandbox from an OCI image.", "required": [ "source" ], "properties": { "source": { "type": "string", "enum": [ "oci" ] } } } ], "description": "Create a sandbox from an OCI image." }, { "allOf": [ { "$ref": "#/components/schemas/CloudSandboxSpec", "description": "Settings shared by every sandbox source." }, { "type": "object", "required": [ "path" ], "properties": { "patches": { "type": "array", "items": { "$ref": "#/components/schemas/CloudPatch" }, "description": "Rootfs patches applied before VM start." }, "path": { "type": "string", "description": "Host directory used as the root filesystem." }, "resources": { "$ref": "#/components/schemas/CloudSandboxComputeResources", "description": "CPU and memory resources." } } }, { "type": "object", "description": "Create a sandbox from a host directory.", "required": [ "source" ], "properties": { "source": { "type": "string", "enum": [ "bind" ] } } } ], "description": "Create a sandbox from a host directory." }, { "allOf": [ { "$ref": "#/components/schemas/CloudSandboxSpec", "description": "Settings shared by every sandbox source." }, { "type": "object", "required": [ "path", "format" ], "properties": { "format": { "$ref": "#/components/schemas/CloudDiskImageFormat", "description": "Disk image format." }, "fstype": { "type": [ "string", "null" ], "description": "Inner filesystem type, when it cannot be detected automatically." }, "patches": { "type": "array", "items": { "$ref": "#/components/schemas/CloudPatch" }, "description": "Rootfs patches applied before VM start." }, "path": { "type": "string", "description": "Host path to the disk image." }, "resources": { "$ref": "#/components/schemas/CloudSandboxComputeResources", "description": "CPU and memory resources." } } }, { "type": "object", "description": "Create a sandbox from a disk image file.", "required": [ "source" ], "properties": { "source": { "type": "string", "enum": [ "disk_image" ] } } } ], "description": "Create a sandbox from a disk image file." }, { "allOf": [ { "$ref": "#/components/schemas/CloudSandboxSpec", "description": "Settings shared by every sandbox source." }, { "type": "object", "required": [ "disk_snapshot_ref" ], "properties": { "disk_snapshot_ref": { "$ref": "#/components/schemas/CloudSnapshotLocation", "description": "Disk snapshot to restore." }, "pull_policy": { "$ref": "#/components/schemas/CloudPullPolicy", "description": "Pull policy used if the snapshot's pinned base image must be fetched." }, "resources": { "$ref": "#/components/schemas/CloudSandboxComputeResources", "description": "CPU and memory resources." } } }, { "type": "object", "description": "Create a fresh-booted sandbox from a disk snapshot.", "required": [ "source" ], "properties": { "source": { "type": "string", "enum": [ "disk_snapshot" ] } } } ], "description": "Create a fresh-booted sandbox from a disk snapshot." } ], "description": "Wire shape of a cloud sandbox create request body.\n\nEach root filesystem origin is a distinct source variant. The common\nsandbox settings remain flat beside the source-specific fields. Legacy\nrequests carrying an `image` object are accepted during migration." }, "CloudCreateSnapshotRequest": { "oneOf": [ { "allOf": [ { "$ref": "#/components/schemas/CloudSnapshotSpec", "description": "Settings shared by every snapshot kind." }, { "type": "object", "description": "Capture disk state only.", "required": [ "kind" ], "properties": { "kind": { "type": "string", "enum": [ "disk" ] } } } ], "description": "Capture disk state only." } ], "description": "Wire shape of a cloud snapshot create request body." }, "CloudDiskImageFormat": { "type": "string", "description": "Disk image format for cloud disk-image sources. Twin of [`DiskImageFormat`]\nwith a snake_case wire.", "enum": [ "qcow2", "raw", "vmdk" ] }, "CloudErrorDetails": { "type": "object", "description": "Nested cloud API error details.", "properties": { "code": { "type": [ "string", "null" ], "description": "Machine-readable error code." }, "message": { "type": [ "string", "null" ], "description": "Human-readable error message." } } }, "CloudHostPattern": { "oneOf": [ { "type": "object", "description": "Exact hostname match.", "required": [ "value", "type" ], "properties": { "type": { "type": "string", "enum": [ "exact" ] }, "value": { "type": "string", "description": "Hostname to match exactly." } } }, { "type": "object", "description": "Wildcard match (e.g. `*.openai.com`).", "required": [ "value", "type" ], "properties": { "type": { "type": "string", "enum": [ "wildcard" ] }, "value": { "type": "string", "description": "Wildcard pattern." } } }, { "type": "object", "description": "Any host (dangerous - the secret can be exfiltrated).", "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "any" ] } } } ], "description": "Host allowlist pattern for cloud secrets. Twin of [`HostPattern`], with the\ndomain's scalar variants normalized to `{ value }` for a uniform union." }, "CloudNetworkSpec": { "type": "object", "description": "Cloud network specification: a subset of the domain [`crate::domain::NetworkSpec`].\nInterface overrides, host port mapping, DNS, TLS interception, rate limits,\nand host-CA trust are not part of this type. Unknown fields are ignored for\ncompatibility with newer clients; accepting them does not enable their behavior.", "properties": { "enabled": { "type": "boolean", "description": "Whether networking is enabled for this sandbox.", "default": true }, "max_connections": { "type": [ "integer", "null" ], "description": "Max concurrent guest connections.", "default": null, "minimum": 0 }, "policy": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/NetworkPolicy", "description": "Egress/ingress policy." } ], "default": null }, "secrets": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/CloudSecretsConfig", "description": "Secret-injection config." } ], "default": null }, "strict": { "type": "boolean", "description": "Require hostname-based policy allows to use inspectable application authority.", "default": false } } }, "CloudPatch": { "oneOf": [ { "type": "object", "description": "Write text content to a file.", "required": [ "path", "content", "replace", "type" ], "properties": { "content": { "type": "string", "description": "Text content to write." }, "mode": { "type": [ "integer", "null" ], "format": "int32", "description": "File permissions, such as `0o644`. `None` uses the default.", "minimum": 0 }, "path": { "type": "string", "description": "Absolute guest path, such as `/etc/app.conf`." }, "replace": { "type": "boolean", "description": "Allow replacing a file that already exists in the rootfs." }, "type": { "type": "string", "enum": [ "text" ] } } }, { "type": "object", "description": "Write raw bytes to a file.", "required": [ "path", "content", "replace", "type" ], "properties": { "content": { "type": "array", "items": { "type": "integer", "format": "int32", "minimum": 0 }, "description": "Raw byte content to write." }, "mode": { "type": [ "integer", "null" ], "format": "int32", "description": "File permissions, such as `0o644`. `None` uses the default.", "minimum": 0 }, "path": { "type": "string", "description": "Absolute guest path." }, "replace": { "type": "boolean", "description": "Allow replacing a file that already exists in the rootfs." }, "type": { "type": "string", "enum": [ "file" ] } } }, { "type": "object", "description": "Copy a file from the host into the rootfs.", "required": [ "src", "dst", "replace", "type" ], "properties": { "dst": { "type": "string", "description": "Absolute guest destination path." }, "mode": { "type": [ "integer", "null" ], "format": "int32", "description": "File permissions. `None` preserves source permissions.", "minimum": 0 }, "replace": { "type": "boolean", "description": "Allow replacing a file that already exists in the rootfs." }, "src": { "type": "string", "description": "Host path to copy from." }, "type": { "type": "string", "enum": [ "copy_file" ] } } }, { "type": "object", "description": "Copy a directory from the host into the rootfs.", "required": [ "src", "dst", "replace", "type" ], "properties": { "dst": { "type": "string", "description": "Absolute guest destination path." }, "replace": { "type": "boolean", "description": "Allow replacing files that already exist in the rootfs." }, "src": { "type": "string", "description": "Host directory to copy from." }, "type": { "type": "string", "enum": [ "copy_dir" ] } } }, { "type": "object", "description": "Create a symlink.", "required": [ "target", "link", "replace", "type" ], "properties": { "link": { "type": "string", "description": "Absolute guest path where the symlink is created." }, "replace": { "type": "boolean", "description": "Allow replacing a path that already exists in the rootfs." }, "target": { "type": "string", "description": "Symlink target path." }, "type": { "type": "string", "enum": [ "symlink" ] } } }, { "type": "object", "description": "Create a directory.", "required": [ "path", "type" ], "properties": { "mode": { "type": [ "integer", "null" ], "format": "int32", "description": "Directory permissions, such as `0o755`. `None` uses the default.", "minimum": 0 }, "path": { "type": "string", "description": "Absolute guest path." }, "type": { "type": "string", "enum": [ "mkdir" ] } } }, { "type": "object", "description": "Remove a file or directory.", "required": [ "path", "type" ], "properties": { "path": { "type": "string", "description": "Absolute guest path to remove." }, "type": { "type": "string", "enum": [ "remove" ] } } }, { "type": "object", "description": "Append content to an existing file.", "required": [ "path", "content", "type" ], "properties": { "content": { "type": "string", "description": "Content to append." }, "path": { "type": "string", "description": "Absolute guest path of the file to append to." }, "type": { "type": "string", "enum": [ "append" ] } } } ], "description": "Filesystem change applied before the sandbox starts. The type field selects the operation." }, "CloudPullPolicy": { "type": "string", "description": "Cloud pull policy. Twin of domain [`PullPolicy`] with a snake_case wire.", "enum": [ "if_missing", "always", "never" ] }, "CloudRlimit": { "type": "object", "description": "A POSIX resource limit. Twin of [`Rlimit`] using [`CloudRlimitResource`].", "required": [ "resource", "soft", "hard" ], "properties": { "hard": { "type": "integer", "format": "int64", "description": "Hard limit (ceiling, requires privileges to raise).", "minimum": 0 }, "resource": { "$ref": "#/components/schemas/CloudRlimitResource", "description": "Resource type." }, "soft": { "type": "integer", "format": "int64", "description": "Soft limit (can be raised up to the hard limit by the process).", "minimum": 0 } } }, "CloudRlimitResource": { "type": "string", "description": "POSIX resource-limit identifiers. Twin of [`RlimitResource`] with a\nsnake_case wire.", "enum": [ "cpu", "fsize", "data", "stack", "core", "rss", "nproc", "nofile", "memlock", "as", "locks", "sigpending", "msgqueue", "nice", "rtprio", "rttime" ] }, "CloudSandboxComputeResources": { "type": "object", "description": "CPU and memory request shared by sources without a managed writable disk.", "properties": { "memory_mib": { "type": "integer", "format": "int32", "description": "Guest memory in MiB.", "default": 512, "minimum": 0 }, "vcpus": { "type": "integer", "format": "int32", "description": "Number of virtual CPUs.", "default": 1, "minimum": 0 } } }, "CloudSandboxResources": { "type": "object", "description": "Cloud resource request.", "properties": { "disk_size_mib": { "type": [ "integer", "null" ], "format": "int32", "description": "Writable disk size in MiB. Applies only to OCI root filesystems.", "default": null, "minimum": 0 }, "memory_mib": { "type": "integer", "format": "int32", "description": "Guest memory in MiB.", "default": 512, "minimum": 0 }, "vcpus": { "type": "integer", "format": "int32", "description": "Number of virtual CPUs.", "default": 1, "minimum": 0 } } }, "CloudSandboxRuntimeOptions": { "type": "object", "description": "Cloud guest runtime options: a subset of [`crate::domain::SandboxRuntimeOptions`]. The\nhostname and the metrics-sampling knobs are not part of this type.\nUnknown fields are ignored for compatibility with newer clients.", "properties": { "cmd": { "type": [ "array", "null" ], "items": { "type": "string" }, "description": "Command override.", "default": null }, "entrypoint": { "type": [ "array", "null" ], "items": { "type": "string" }, "description": "Entrypoint override.", "default": null }, "log_level": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/SandboxLogLevel", "description": "Runtime log level." } ], "default": null }, "scripts": { "type": "object", "description": "Named in-guest scripts.", "default": {}, "additionalProperties": { "type": "string" }, "propertyNames": { "type": "string" } }, "shell": { "type": [ "string", "null" ], "description": "Default shell.", "default": null }, "user": { "type": [ "string", "null" ], "description": "Guest user.", "default": null }, "workdir": { "type": [ "string", "null" ], "description": "Working directory for guest commands.", "default": null } } }, "CloudSandboxSpec": { "type": "object", "description": "Settings shared by every cloud sandbox creation source.", "required": [ "name" ], "properties": { "env": { "type": "array", "items": { "$ref": "#/components/schemas/EnvVar" }, "description": "Environment variables visible to commands in the sandbox.", "default": [] }, "init": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/HandoffInit", "description": "Hand off PID 1 to a guest init binary after agentd setup." } ], "default": null }, "labels": { "type": "object", "description": "User-defined labels attached to the sandbox.", "default": {}, "additionalProperties": { "type": "string" }, "propertyNames": { "type": "string" } }, "lifecycle": { "oneOf": [ { "$ref": "#/components/schemas/SandboxPolicy", "description": "Sandbox lifecycle policy." } ], "default": { "ephemeral": false, "idle_timeout_secs": null, "max_duration_secs": null } }, "mounts": { "type": "array", "items": { "$ref": "#/components/schemas/CloudVolumeMount" }, "description": "Volume mounts.", "default": [] }, "name": { "type": "string", "description": "Unique sandbox name.", "default": "" }, "network": { "oneOf": [ { "$ref": "#/components/schemas/CloudNetworkSpec", "description": "Network specification." } ], "default": { "enabled": true, "strict": false } }, "rlimits": { "type": "array", "items": { "$ref": "#/components/schemas/CloudRlimit" }, "description": "Sandbox-wide resource limits inherited by guest processes.", "default": [] }, "runtime": { "oneOf": [ { "$ref": "#/components/schemas/CloudSandboxRuntimeOptions", "description": "Guest runtime options." } ], "default": { "cmd": null, "entrypoint": null, "log_level": null, "scripts": {}, "shell": null, "user": null, "workdir": null } }, "security_profile": { "oneOf": [ { "$ref": "#/components/schemas/SecurityProfile", "description": "In-guest security profile." } ], "default": "default" } } }, "CloudSecretEntry": { "type": "object", "description": "A single cloud secret entry. Twin of domain [`SecretEntry`].", "required": [ "env_var", "placeholder" ], "properties": { "allowed_hosts": { "type": "array", "items": { "$ref": "#/components/schemas/CloudHostPattern" }, "description": "Hosts allowed to receive this secret." }, "env_var": { "type": "string", "description": "Environment variable name exposed to the sandbox." }, "injection": { "$ref": "#/components/schemas/SecretInjection", "description": "Where the secret may be injected." }, "on_violation": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/CloudViolationAction", "description": "Per-secret violation action overriding the config default." } ] }, "placeholder": { "type": "string", "description": "Placeholder the sandbox sees instead of the real value." }, "require_tls_identity": { "type": "boolean", "description": "Require verified TLS identity before substituting (default: true)." }, "source": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/CloudSecretSource", "description": "Host-side source resolved into `value` at spawn time." } ] }, "value": { "type": "string", "description": "The secret value (empty when `source` carries a reference instead)." } } }, "CloudSecretSource": { "oneOf": [ { "type": "object", "description": "Read from a host environment variable at apply time.", "required": [ "var", "type" ], "properties": { "type": { "type": "string", "enum": [ "env" ] }, "var": { "type": "string", "description": "Host environment variable name." } } }, { "type": "object", "description": "Read from a host-side secret store reference.", "required": [ "reference", "type" ], "properties": { "reference": { "type": "string", "description": "Store-specific secret reference." }, "type": { "type": "string", "enum": [ "store" ] } } } ], "description": "Host-side source for a cloud secret. Twin of [`SecretSource`]." }, "CloudSecretsConfig": { "type": "object", "description": "Secret-injection config for the cloud API. Twin of domain [`SecretsConfig`].", "properties": { "entries": { "type": "array", "items": { "$ref": "#/components/schemas/CloudSecretEntry" }, "description": "Secrets to inject." }, "on_violation": { "$ref": "#/components/schemas/CloudViolationAction", "description": "Default action when a placeholder leaks to a disallowed host." } } }, "CloudSnapshot": { "oneOf": [ { "allOf": [ { "$ref": "#/components/schemas/CloudSnapshotDetails", "description": "Fields shared by every snapshot kind." }, { "type": "object", "description": "A disk-only snapshot.", "required": [ "kind" ], "properties": { "kind": { "type": "string", "enum": [ "disk" ] } } } ], "description": "A disk-only snapshot." } ], "description": "Wire shape of a completed cloud snapshot." }, "CloudSnapshotDetails": { "type": "object", "description": "Fields shared by every completed cloud snapshot kind.", "required": [ "name", "location", "digest", "size_bytes", "manifest", "labels", "created_at" ], "properties": { "created_at": { "type": "string", "format": "date-time", "description": "Creation timestamp." }, "digest": { "type": "string", "description": "Snapshot identity: the `sha256:` digest of the canonical descriptor." }, "labels": { "type": "object", "description": "User-defined labels stored on the snapshot.", "additionalProperties": { "type": "string" }, "propertyNames": { "type": "string" } }, "location": { "$ref": "#/components/schemas/CloudSnapshotLocation", "description": "Where the snapshot artifact resides." }, "manifest": { "$ref": "#/components/schemas/SnapshotManifest", "description": "Canonical snapshot descriptor." }, "name": { "type": "string", "description": "Snapshot name." }, "sandbox_id": { "type": [ "string", "null" ], "description": "Identifier of the sandbox the snapshot was captured from, when known." }, "size_bytes": { "type": "integer", "format": "int64", "description": "Stored payload size in bytes.", "minimum": 0 } } }, "CloudSnapshotKind": { "type": "string", "description": "Kind of cloud snapshot artifact or capture operation.", "enum": [ "disk" ] }, "CloudSnapshotLocation": { "oneOf": [ { "type": "object", "description": "Held in managed snapshot storage.", "required": [ "id", "type" ], "properties": { "id": { "type": "string", "description": "Identifier of the stored artifact." }, "type": { "type": "string", "enum": [ "managed" ] } } }, { "type": "object", "description": "Stored in a directory on a mounted host volume.", "required": [ "path", "type" ], "properties": { "path": { "type": "string", "description": "Artifact directory path on the host volume." }, "type": { "type": "string", "enum": [ "host_volume" ] } } } ], "description": "Public locator for a managed or host-volume cloud snapshot." }, "CloudSnapshotOperation": { "type": "object", "description": "Wire shape of the asynchronous snapshot operation returned by snapshot\ncapture endpoints.", "required": [ "id", "kind", "status", "created_at", "updated_at" ], "properties": { "completed_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Timestamp of the terminal status, when the operation has finished." }, "created_at": { "type": "string", "format": "date-time", "description": "Creation timestamp." }, "error": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/CloudErrorDetails", "description": "Error details for a failed operation." } ] }, "id": { "type": "string", "description": "Server-side operation identifier." }, "kind": { "$ref": "#/components/schemas/CloudSnapshotKind", "description": "Kind of snapshot being captured." }, "result": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/CloudSnapshot", "description": "The resulting snapshot, present once the operation succeeds." } ] }, "status": { "$ref": "#/components/schemas/CloudSnapshotOperationStatus", "description": "Current operation status." }, "updated_at": { "type": "string", "format": "date-time", "description": "Timestamp of the most recent status change." } } }, "CloudSnapshotOperationStatus": { "type": "string", "description": "Status of an asynchronous cloud snapshot operation.", "enum": [ "queued", "in_progress", "succeeded", "failed" ] }, "CloudSnapshotSpec": { "type": "object", "description": "Settings shared by every cloud snapshot capture kind.", "required": [ "sandbox_id", "name" ], "properties": { "dest_dir": { "type": [ "string", "null" ], "description": "Directory on a mounted host volume to write the artifact into. `None`\nstores the snapshot in managed snapshot storage." }, "force": { "type": "boolean", "description": "Replace an existing snapshot with the same name." }, "labels": { "type": "object", "description": "User-defined labels stored on the snapshot.", "additionalProperties": { "type": "string" }, "propertyNames": { "type": "string" } }, "name": { "type": "string", "description": "Snapshot name." }, "record_integrity": { "type": "boolean", "description": "Record payload integrity metadata during capture." }, "sandbox_id": { "type": "string", "description": "Immutable identifier of the sandbox to capture." } } }, "CloudViolationAction": { "oneOf": [ { "type": "object", "description": "Block the request silently.", "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "block" ] } } }, { "type": "object", "description": "Block and log (default).", "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "block_and_log" ] } } }, { "type": "object", "description": "Block and terminate the sandbox.", "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "block_and_terminate" ] } } }, { "type": "object", "description": "Forward the request with the placeholder unchanged for matching hosts.", "required": [ "hosts", "type" ], "properties": { "hosts": { "type": "array", "items": { "$ref": "#/components/schemas/CloudHostPattern" }, "description": "Hosts for which the placeholder passes through unchanged." }, "type": { "type": "string", "enum": [ "passthrough" ] } } } ], "description": "Action on a cloud secret violation. Twin of [`ViolationAction`], with\n`Passthrough`'s host list normalized to a `hosts` field." }, "CloudVolumeMount": { "oneOf": [ { "type": "object", "description": "Bind mount a host directory into the guest.", "required": [ "host", "guest", "type" ], "properties": { "guest": { "type": "string", "description": "Guest path to mount at." }, "host": { "type": "string", "description": "Host directory to bind into the guest." }, "host_permissions": { "$ref": "#/components/schemas/HostPermissions", "description": "Host permission policy applied to the mount." }, "options": { "$ref": "#/components/schemas/MountOptions", "description": "Mount options (read-only, no-exec, …)." }, "quota_mib": { "type": [ "integer", "null" ], "format": "int32", "description": "Optional guest-write quota in MiB.", "minimum": 0 }, "stat_virtualization": { "$ref": "#/components/schemas/StatVirtualization", "description": "How guest `stat()` results are virtualized." }, "type": { "type": "string", "enum": [ "bind" ] } } }, { "type": "object", "description": "Mount a named volume into the guest.", "required": [ "name", "guest", "type" ], "properties": { "guest": { "type": "string", "description": "Guest path to mount at." }, "host_permissions": { "$ref": "#/components/schemas/HostPermissions", "description": "Host permission policy applied to the mount." }, "name": { "type": "string", "description": "Named volume to mount." }, "options": { "$ref": "#/components/schemas/MountOptions", "description": "Mount options (read-only, no-exec, …)." }, "stat_virtualization": { "$ref": "#/components/schemas/StatVirtualization", "description": "How guest `stat()` results are virtualized." }, "type": { "type": "string", "enum": [ "named" ] } } }, { "type": "object", "description": "Temporary filesystem backed by guest memory.", "required": [ "guest", "type" ], "properties": { "guest": { "type": "string", "description": "Guest path to mount at." }, "options": { "$ref": "#/components/schemas/MountOptions", "description": "Mount options (read-only, no-exec, …)." }, "size_mib": { "type": [ "integer", "null" ], "format": "int32", "description": "Optional size cap in MiB.", "minimum": 0 }, "type": { "type": "string", "enum": [ "tmpfs" ] } } }, { "type": "object", "description": "Mount a disk image file as a virtio-blk device at a guest path.", "required": [ "host", "guest", "format", "type" ], "properties": { "format": { "$ref": "#/components/schemas/CloudDiskImageFormat", "description": "Disk image format." }, "fstype": { "type": [ "string", "null" ], "description": "Inner filesystem type (auto-detected if absent)." }, "guest": { "type": "string", "description": "Guest path to mount at." }, "host": { "type": "string", "description": "Host path to the disk image file." }, "options": { "$ref": "#/components/schemas/MountOptions", "description": "Mount options (read-only, no-exec, …)." }, "type": { "type": "string", "enum": [ "disk_image" ] } } } ], "description": "Persistent volume mounted at a path inside the sandbox." }, "CreateInviteRequest": { "type": "object", "description": "Request body for `POST /v1/orgs/:slug/invites`.", "required": [ "email", "role" ], "properties": { "email": { "type": "string" }, "role": { "$ref": "#/components/schemas/OrgRole" } } }, "CreateOrgRequest": { "type": "object", "description": "POST /v1/orgs - create a new organization.", "required": [ "name", "slug" ], "properties": { "name": { "type": "string" }, "slug": { "type": "string" } } }, "CreateSandboxRequest": { "allOf": [ { "$ref": "#/components/schemas/CloudCreateSandboxRequest", "description": "The microsandbox create request - source, resources, runtime, env,\nmounts, network, and lifecycle - flattened onto the request body." }, { "type": "object", "properties": { "registry": { "$ref": "#/components/schemas/RegistrySelection", "description": "Registry-credential selection for the image pull. Absent ⇒ `Auto`\n(infer the credential from the image's registry host). Credential-only:\nthis never changes *where* the image is pulled from - the image string\ncontrols that - only *which* stored credential, if any, is presented." }, "slug": { "type": [ "string", "null" ], "description": "Optional globally-unique slug - the SSH username token. Lowercase\nletters, digits, and single hyphens; 3-63 chars. Omitted ⇒ a dictionary\nslug is generated. Must be globally unique (409 on conflict)." } } } ], "description": "What the user sends in `POST /v1/sandboxes`.\n\nThe body carries the shared microsandbox [`CloudCreateSandboxRequest`] union.\nIts source-specific and common [`CloudSandboxSpec`] fields stay flat on the\nwire beside the cloud-only SSH `slug` and registry-credential selection." }, "CreateVolumeRequest": { "type": "object", "description": "POST /v1/orgs/{slug}/volumes", "required": [ "name" ], "properties": { "capacity_gib": { "type": [ "integer", "null" ], "format": "int32", "description": "Optional per-volume storage cap in GiB (#496). Omitted/`null` = no\nper-volume limit (the org's plan cap still governs). Must be `>= 1` and\n`<= the org's storage cap`.", "minimum": 0 }, "labels": { "type": "object", "description": "User-defined labels (free-form string map). Omitted = none. Keys using a\nplatform-reserved prefix are rejected.", "additionalProperties": { "type": "string" }, "propertyNames": { "type": "string" } }, "name": { "type": "string", "description": "Volume name, unique within the org. Lowercase alphanumeric with single\ninternal hyphens (e.g. `team-ml`). Creates a `managed` volume; the host\ndisk is system-provisioned and has no name." }, "storage": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/VolumeType", "description": "Physical backing for the volume. Omitted = `block` (the default and only\nvalue today)." } ] } } }, "DeleteMeRequest": { "type": "object", "description": "DELETE /v1/users/me - body confirms the destructive action.\n\nProvide exactly one credential proof: the current password (for\npassword-backed accounts) or a TOTP code (when MFA is enabled).\nOAuth-only accounts must enrol in MFA before deletion is permitted.", "properties": { "mfa_code": { "type": [ "string", "null" ], "description": "TOTP code - required when MFA is enabled." }, "password": { "type": [ "string", "null" ], "description": "Current account password - required for password-backed accounts." } } }, "DeleteOrgRequest": { "type": "object", "description": "DELETE /v1/orgs/:slug - delete an organization. `confirm` must echo the org slug,\nmirroring the dashboard's type-to-confirm, so a deletion can't fire by accident.", "required": [ "confirm" ], "properties": { "confirm": { "type": "string" } } }, "Destination": { "oneOf": [ { "type": "string", "description": "Match any destination.", "enum": [ "any" ] }, { "type": "object", "description": "IP address or CIDR block (e.g. `\"1.2.3.4\"`, `\"10.0.0.0/8\"`).", "required": [ "cidr" ], "properties": { "cidr": { "type": "string", "description": "IP address or CIDR block (e.g. `\"1.2.3.4\"`, `\"10.0.0.0/8\"`)." } } }, { "type": "object", "description": "Exact domain name (e.g. `\"example.com\"`).", "required": [ "domain" ], "properties": { "domain": { "type": "string", "description": "Exact domain name (e.g. `\"example.com\"`)." } } }, { "type": "object", "description": "Domain suffix - the apex and any subdomain of it.", "required": [ "domain_suffix" ], "properties": { "domain_suffix": { "type": "string", "description": "Domain suffix - the apex and any subdomain of it." } } }, { "type": "object", "description": "A pre-defined destination group.", "required": [ "group" ], "properties": { "group": { "$ref": "#/components/schemas/DestinationGroup", "description": "A pre-defined destination group." } } } ], "description": "Traffic destination matched by a network rule, such as an IP range or domain name." }, "DestinationGroup": { "type": "string", "description": "Pre-defined destination category for a [`Destination::Group`] match.", "enum": [ "public", "loopback", "private", "link_local", "metadata", "multicast", "host" ] }, "Direction": { "type": "string", "description": "Direction a [`Rule`] applies to.", "enum": [ "egress", "ingress", "any" ] }, "DiskImageFormat": { "type": "string", "description": "Disk image format for virtio-blk root filesystems and volume mounts.", "enum": [ "Qcow2", "Raw", "Vmdk" ] }, "DnsConfig": { "type": "object", "description": "DNS interception and filtering settings. Carried in [`NetworkSpec::dns`].", "properties": { "nameservers": { "type": "array", "items": { "type": "string" }, "description": "Upstream nameservers as `IP`, `IP:PORT`, `HOST`, or `HOST:PORT`\nstrings. Empty falls back to the host's `/etc/resolv.conf`.", "default": [] }, "query_timeout_ms": { "type": "integer", "format": "int64", "description": "Per-query timeout in milliseconds. Default: 5000.", "default": 5000, "minimum": 0 }, "rebind_protection": { "type": "boolean", "description": "Whether DNS-rebinding protection is enabled. Default: true.", "default": true } } }, "EnvVar": { "type": "object", "description": "Environment variable entry.", "required": [ "key", "value" ], "properties": { "key": { "type": "string", "description": "Environment variable name." }, "value": { "type": "string", "description": "Environment variable value." } } }, "EventActor": { "oneOf": [ { "type": "object", "required": [ "user_id", "label", "redacted_email", "kind" ], "properties": { "kind": { "type": "string", "enum": [ "user" ] }, "label": { "type": "string" }, "redacted_email": { "type": "string" }, "user_id": { "type": "string", "format": "uuid" } } }, { "type": "object", "required": [ "api_key_id", "name", "kind" ], "properties": { "api_key_id": { "type": "string", "format": "uuid" }, "kind": { "type": "string", "enum": [ "api_key" ] }, "name": { "type": "string" } } }, { "type": "object", "required": [ "code", "label", "kind" ], "properties": { "code": { "type": "string" }, "kind": { "type": "string", "enum": [ "system" ] }, "label": { "type": "string" } } }, { "type": "object", "description": "The authorized SSH key that authenticated a front-door session. The\nprincipal SSH actually proves at connect is the *key*, not a person -\nthe scope-only model (D8) doesn't bind a key to a user (a global key may\nbe shared), so the session is attributed to the key (label + fingerprint),\nwhile whoever registered it rides the event payload as `added_by`.", "required": [ "key_id", "fingerprint", "kind" ], "properties": { "fingerprint": { "type": "string", "description": "`SHA256:…` fingerprint." }, "key_id": { "type": "string", "format": "uuid" }, "kind": { "type": "string", "enum": [ "ssh_key" ] }, "label": { "type": [ "string", "null" ], "description": "Human label set at registration (e.g. `alice-laptop`), if any." } } } ], "description": "Maximum total length, in characters, of the truncated `command` field in\nImmutable actor snapshot stored alongside an event." }, "EventResponse": { "type": "object", "description": "A single audit/lifecycle event returned by the API.", "required": [ "id", "org_id", "category", "event_type", "actor", "payload", "timestamp" ], "properties": { "actor": { "$ref": "#/components/schemas/EventActor" }, "category": { "type": "string" }, "event_type": { "type": "string" }, "id": { "type": "string", "format": "uuid" }, "org_id": { "type": "string", "format": "uuid" }, "payload": {}, "timestamp": { "type": "string", "format": "date-time" } } }, "FileMoveRequest": { "type": "object", "required": [ "from", "to" ], "properties": { "from": { "type": "string" }, "to": { "type": "string" } } }, "FilePathRequest": { "type": "object", "required": [ "path" ], "properties": { "path": { "type": "string" } } }, "FilePathsRequest": { "type": "object", "required": [ "paths" ], "properties": { "paths": { "type": "array", "items": { "type": "string" }, "description": "Volume-relative paths to check, at most 100 per request.", "maxItems": 100 } } }, "FileSnapshotState": { "type": "object", "description": "Concrete file-backed snapshot state.", "required": [ "format", "fstype", "upper" ], "properties": { "format": { "$ref": "#/components/schemas/SnapshotFormat", "description": "On-disk payload format." }, "fstype": { "type": "string", "description": "Filesystem type inside the payload." }, "upper": { "$ref": "#/components/schemas/UpperLayer", "description": "File-backed upper-layer binding." } }, "additionalProperties": false }, "HandoffInit": { "type": "object", "description": "Fully-assembled handoff-init specification.", "required": [ "cmd" ], "properties": { "args": { "type": "array", "items": { "type": "string" }, "description": "Supplemental argv. `argv[0]` is implicitly `cmd`." }, "cmd": { "type": "string", "description": "Init binary: absolute path inside the guest rootfs, or the literal `auto`.\n\nAlways a Linux-style `/`-separated path - never build it with host OS path APIs, whose semantics diverge on Windows (`\\` separators, `/sbin/init` treated as relative)." }, "env": { "type": "array", "items": { "type": "array", "items": false, "prefixItems": [ { "type": "string" }, { "type": "string" } ] }, "description": "Extra env vars merged on top of the inherited env." } } }, "HostPermissions": { "type": "string", "description": "Host permission propagation policy for a virtiofs-backed volume mount.\n\nSerializes/deserializes as the lowercase variant name (`\"private\"`, `\"mirror\"`) to align with the CLI and NAPI spellings.", "enum": [ "private", "mirror" ] }, "ImageRef": { "type": "object", "description": "Reference to the pinned OCI image used by the snapshot.", "required": [ "ref", "manifest_digest" ], "properties": { "manifest_digest": { "type": "string", "description": "Pinned OCI manifest digest." }, "ref": { "type": "string", "description": "Human-readable image reference." } }, "additionalProperties": false }, "InterceptCaConfig": { "type": "object", "description": "Certificate authority configuration for TLS interception.", "properties": { "cert_path": { "type": [ "string", "null" ], "description": "Path to an existing CA certificate PEM file. If `None`, a CA is\nauto-generated and persisted." }, "key_path": { "type": [ "string", "null" ], "description": "Path to an existing CA private key PEM file. If `None`, a key is\nauto-generated and persisted." } } }, "InterfaceOverrides": { "type": "object", "description": "Optional guest interface overrides. Unset fields are derived from the\nsandbox slot by the local network engine. Carried in\n[`NetworkSpec::interface`].", "properties": { "ipv4_address": { "type": [ "string", "null" ], "description": "Guest IPv4 address (e.g. `172.16.0.2`). Default: derived from slot.", "default": null }, "ipv4_pool": { "type": [ "string", "null" ], "description": "Guest IPv4 pool CIDR (e.g. `\"172.16.0.0/12\"`). Default: derived from slot.", "default": null }, "ipv6_address": { "type": [ "string", "null" ], "description": "Guest IPv6 address. Default: derived from slot.", "default": null }, "ipv6_pool": { "type": [ "string", "null" ], "description": "Guest IPv6 pool CIDR. Default: derived from slot.", "default": null }, "mac": { "type": [ "array", "null" ], "items": { "type": "integer", "format": "int32", "minimum": 0 }, "description": "Guest MAC address as six octets. Default: derived from slot.", "default": null }, "mtu": { "type": [ "integer", "null" ], "format": "int32", "description": "Interface MTU. Default: 1500.", "default": null, "minimum": 0 } } }, "Invoice": { "type": "object", "description": "Invoice from the billing provider (Autumn/Stripe).", "required": [ "id", "status", "total_cents", "currency", "period_start", "period_end", "created_at" ], "properties": { "created_at": { "type": "string", "format": "date-time" }, "currency": { "type": "string" }, "id": { "type": "string" }, "invoice_url": { "type": [ "string", "null" ] }, "period_end": { "type": "string", "format": "date-time" }, "period_start": { "type": "string", "format": "date-time" }, "status": { "type": "string" }, "total_cents": { "type": "integer", "format": "int64" } } }, "MessageResponse": { "type": "object", "description": "Simple message response for operations without a body.", "required": [ "message" ], "properties": { "message": { "type": "string" } } }, "MetricSeries": { "type": "object", "description": "One labelled series for a metric.", "required": [ "labels", "samples" ], "properties": { "labels": { "type": "object", "description": "Series labels (e.g. `sandbox_name`), minus internal Prometheus names.", "additionalProperties": { "type": "string" }, "propertyNames": { "type": "string" } }, "samples": { "type": "array", "items": { "type": "array", "items": { "type": "number", "format": "double" } }, "description": "`[epoch_millis, value]` pairs in ascending time order." } } }, "MetricsRange": { "type": "object", "description": "The resolved time window a metrics response covers.", "required": [ "start", "end", "step_secs" ], "properties": { "end": { "type": "integer", "format": "int64", "description": "Window end, epoch milliseconds." }, "start": { "type": "integer", "format": "int64", "description": "Window start, epoch milliseconds." }, "step_secs": { "type": "integer", "format": "int64", "description": "Sample resolution in seconds.", "minimum": 0 } } }, "MountOptions": { "type": "object", "description": "Guest mount behavior shared by every volume mount kind.", "properties": { "nodev": { "type": "boolean", "description": "Whether device files on the mount are ignored.", "default": false }, "noexec": { "type": "boolean", "description": "Whether direct execution from the mount is disabled.\n\nThis prevents `execve` of binaries or scripts located on the mount. Interpreters can still read files from the mount, for example `sh /mnt/script.sh`, because the interpreter itself executes from a different filesystem.", "default": false }, "nosuid": { "type": "boolean", "description": "Whether setuid and setgid privilege elevation from files on the mount is ignored.", "default": false }, "override_gid": { "type": [ "integer", "null" ], "format": "int32", "description": "Guest gid presented for host files under this mount that carry no\nper-file stat override. See [`override_uid`](Self::override_uid); the two\nmust be set together.", "default": null, "minimum": 0 }, "override_uid": { "type": [ "integer", "null" ], "format": "int32", "description": "Guest uid presented for host files under this mount that carry no\nper-file stat override.\n\nHost-created files (written outside the guest) have no override, so\nwithout this they surface with the runtime's fallback owner. When set,\nsuch files are presented as this uid instead. Must be set together with\n[`override_gid`](Self::override_gid). `None` keeps the fallback.", "default": null, "minimum": 0 }, "readonly": { "type": "boolean", "description": "Whether the mount is read-only.\n\nGuest writes fail with the kernel's read-only filesystem behavior. Virtiofs-backed mounts also reject writes on the host-side filesystem server as defense in depth.", "default": false } } }, "NetworkPolicy": { "type": "object", "description": "Egress/ingress network policy: an ordered [`Rule`] list plus a\nper-direction default [`Action`]. Carried in [`NetworkSpec::policy`].", "properties": { "default_egress": { "$ref": "#/components/schemas/Action", "description": "Default action for egress traffic matching no rule. Default: `Deny`." }, "default_ingress": { "$ref": "#/components/schemas/Action", "description": "Default action for ingress traffic matching no rule. Default: `Deny`." }, "rules": { "type": "array", "items": { "$ref": "#/components/schemas/Rule" }, "description": "Ordered rules, evaluated first-match-wins per direction." } } }, "OrgBillingTermsOverrideStatus": { "type": "string", "description": "Operational state of one immutable negotiated-pricing version.", "enum": [ "applying", "pending_payment", "scheduled", "active", "failed", "expired" ] }, "OrgInvite": { "type": "object", "description": "An email-based invitation to join an organization.", "required": [ "id", "org_id", "email", "role", "invited_by", "expires_at", "created_at" ], "properties": { "accepted_at": { "type": [ "string", "null" ], "format": "date-time" }, "created_at": { "type": "string", "format": "date-time" }, "declined_at": { "type": [ "string", "null" ], "format": "date-time" }, "email": { "type": "string" }, "expires_at": { "type": "string", "format": "date-time" }, "id": { "type": "string", "format": "uuid" }, "invited_by": { "type": "string", "format": "uuid" }, "org_id": { "type": "string", "format": "uuid" }, "role": { "$ref": "#/components/schemas/OrgRole" } } }, "OrgMember": { "type": "object", "description": "A user's membership in an organization.", "required": [ "id", "org_id", "user_id", "role", "created_at", "updated_at" ], "properties": { "created_at": { "type": "string", "format": "date-time" }, "id": { "type": "string", "format": "uuid" }, "org_id": { "type": "string", "format": "uuid" }, "role": { "$ref": "#/components/schemas/OrgRole" }, "updated_at": { "type": "string", "format": "date-time" }, "user_id": { "type": "string", "format": "uuid" } } }, "OrgMemberResponse": { "type": "object", "description": "Member with joined user profile data - repository read view.", "required": [ "id", "user_id", "email", "role", "joined_at" ], "properties": { "avatar_url": { "type": [ "string", "null" ] }, "display_name": { "type": [ "string", "null" ] }, "email": { "type": "string" }, "id": { "type": "string", "format": "uuid" }, "joined_at": { "type": "string", "format": "date-time" }, "role": { "$ref": "#/components/schemas/OrgRole" }, "user_id": { "type": "string", "format": "uuid" } } }, "OrgOidcConfig": { "type": "object", "description": "OIDC configuration for an organization's enterprise SSO.", "required": [ "id", "org_id", "issuer_url", "client_id", "allowed_domains", "enabled", "created_at", "updated_at" ], "properties": { "allowed_domains": { "type": "array", "items": { "type": "string" } }, "client_id": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "enabled": { "type": "boolean" }, "id": { "type": "string", "format": "uuid" }, "issuer_url": { "type": "string" }, "org_id": { "type": "string", "format": "uuid" }, "updated_at": { "type": "string", "format": "date-time" } } }, "OrgRole": { "type": "string", "description": "Organization membership role.", "enum": [ "owner", "admin", "member", "viewer" ] }, "OrgWithRole": { "type": "object", "description": "Organization with the requesting user's role included.", "required": [ "id", "name", "slug", "mfa_required", "role", "created_at", "updated_at" ], "properties": { "created_at": { "type": "string", "format": "date-time" }, "id": { "type": "string", "format": "uuid" }, "mfa_required": { "type": "boolean" }, "name": { "type": "string" }, "role": { "$ref": "#/components/schemas/OrgRole" }, "slug": { "type": "string" }, "updated_at": { "type": "string", "format": "date-time" } } }, "Organization": { "type": "object", "description": "A tenant organization. Users belong to orgs via `OrgMember`.", "required": [ "id", "name", "slug", "mfa_required", "created_at", "updated_at" ], "properties": { "created_at": { "type": "string", "format": "date-time" }, "id": { "type": "string", "format": "uuid" }, "mfa_required": { "type": "boolean" }, "name": { "type": "string" }, "slug": { "type": "string" }, "updated_at": { "type": "string", "format": "date-time" } } }, "PaginatedApiKeyResponse": { "type": "object", "description": "Paginated list of API keys (OpenAPI schema for `PaginatedResponse`).", "required": [ "data", "has_more" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/ApiKeyResponse" } }, "has_more": { "type": "boolean" }, "next_cursor": { "type": [ "string", "null" ] } } }, "PaginatedEventResponse": { "type": "object", "description": "Wrapper for paginated event responses (needed for OpenAPI schema generation).", "required": [ "data", "has_more" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/EventResponse" } }, "has_more": { "type": "boolean" }, "next_cursor": { "type": [ "string", "null" ] } } }, "PaginatedMemberResponse": { "type": "object", "description": "Paginated list of organization members.", "required": [ "data", "has_more" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/OrgMemberResponse" } }, "has_more": { "type": "boolean" }, "next_cursor": { "type": [ "string", "null" ] } } }, "PaginatedSandboxResponse": { "type": "object", "description": "Paginated list of sandboxes.", "required": [ "data", "has_more" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/SandboxResponse" } }, "has_more": { "type": "boolean" }, "next_cursor": { "type": [ "string", "null" ] } } }, "PaginatedSnapshotCandidateResponse": { "type": "object", "description": "Paginated list of sandboxes eligible for snapshots.", "required": [ "data", "has_more" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/SandboxResponse" } }, "has_more": { "type": "boolean" }, "next_cursor": { "type": [ "string", "null" ] } } }, "PaginatedSnapshotOperationResponse": { "type": "object", "description": "Paginated list of snapshot operations.", "required": [ "data", "has_more" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/SnapshotOperationListItem" } }, "has_more": { "type": "boolean" }, "next_cursor": { "type": [ "string", "null" ] } } }, "PaginatedSnapshotResponse": { "type": "object", "description": "Paginated list of managed snapshots.", "required": [ "data", "has_more" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/CloudSnapshot" } }, "has_more": { "type": "boolean" }, "next_cursor": { "type": [ "string", "null" ] } } }, "PaymentPortalResponse": { "type": "object", "description": "Response for the payment-portal endpoint - a hosted URL the client redirects\nto for adding/managing payment methods (Stripe Checkout / billing-portal).", "required": [ "portal_url" ], "properties": { "portal_url": { "type": "string" } } }, "PersonalAccessTokenResponse": { "type": "object", "description": "PAT metadata returned in list responses. Never includes the raw token.", "required": [ "id", "name", "prefix", "created_at" ], "properties": { "created_at": { "type": "string", "format": "date-time" }, "expires_at": { "type": [ "string", "null" ], "format": "date-time" }, "id": { "type": "string", "format": "uuid" }, "last_used_at": { "type": [ "string", "null" ], "format": "date-time" }, "name": { "type": "string" }, "prefix": { "type": "string", "description": "Last 8 chars of the original token - safe to display." } } }, "PoolUsage": { "type": "object", "description": "An org's monthly pool usage against its hard-cap pools - the shared home of\nthe exhaustion predicates, whether read per-org (embedded in `QuotaUsage`)\nor in the quota monitor's batched sweep (`OrgPoolUsage`).", "required": [ "hard_cap", "vcpu_hours_used", "memory_gib_hours_used" ], "properties": { "hard_cap": { "type": "boolean", "description": "Whether the plan hard-stops at its included pools (no overflow).\nDERIVED (not a stored column): true iff the resolved plan is unpriced -\nan unpriced plan has no overage path, so its pools become walls." }, "included_memory_gib_hours": { "type": [ "integer", "null" ], "format": "int32", "description": "Included memory GiB-hours/month; `None` = unlimited." }, "included_vcpu_hours": { "type": [ "integer", "null" ], "format": "int32", "description": "Included vCPU-hours/month; `None` = unlimited. On `hard_cap` plans this\nis the compute wall; on priced plans, usage beyond it is metered overage." }, "memory_gib_hours_used": { "type": "number", "format": "double", "description": "Memory GiB-hours consumed this billing month (compute-on-read from `sandbox_runs`)." }, "vcpu_hours_used": { "type": "number", "format": "double", "description": "vCPU-hours consumed this billing month (compute-on-read from `sandbox_runs`)." } } }, "PortProtocol": { "type": "string", "description": "Transport protocol for a published port.", "enum": [ "tcp", "udp" ] }, "PortRange": { "type": "object", "description": "Inclusive guest-side port range for a [`Rule`] match.", "required": [ "start", "end" ], "properties": { "end": { "type": "integer", "format": "int32", "description": "End port (inclusive).", "minimum": 0 }, "start": { "type": "integer", "format": "int32", "description": "Start port (inclusive).", "minimum": 0 } } }, "Protocol": { "type": "string", "description": "Protocol filter for a [`Rule`].", "enum": [ "tcp", "udp", "icmpv4", "icmpv6" ] }, "PublishedPortSpec": { "type": "object", "description": "A published port mapping between host and guest.", "required": [ "host_port", "guest_port", "host_bind" ], "properties": { "guest_port": { "type": "integer", "format": "int32", "description": "Guest-side port to forward to.", "minimum": 0 }, "host_bind": { "type": "string", "description": "Host address to bind. Defaults to loopback." }, "host_port": { "type": "integer", "format": "int32", "description": "Host-side port to bind.", "minimum": 0 }, "protocol": { "$ref": "#/components/schemas/PortProtocol", "description": "Transport protocol." } } }, "QuotaUsage": { "allOf": [ { "$ref": "#/components/schemas/PoolUsage" }, { "type": "object", "required": [ "pool_exhausted", "total_sandboxes", "concurrent_ephemeral_running", "concurrent_persistent_running", "snapshot_storage_bytes", "is_suspended" ], "properties": { "concurrent_ephemeral_running": { "type": "integer", "format": "int64", "description": "Currently running/starting ephemeral sandboxes." }, "concurrent_persistent_running": { "type": "integer", "format": "int64", "description": "Currently running/starting persistent sandboxes." }, "included_disk_gib_hours": { "type": [ "integer", "null" ], "format": "int32", "description": "Included writable-disk GiB-hours/month (display/billing only - never a wall)." }, "included_storage_gib": { "type": [ "integer", "null" ], "format": "int32", "description": "Included durable-storage GiB/month." }, "is_suspended": { "type": "boolean", "description": "Whether sandbox usage has been manually suspended for the organization." }, "max_concurrent_ephemeral_running": { "type": [ "integer", "null" ], "format": "int32", "description": "Maximum simultaneously-running ephemeral sandboxes." }, "max_concurrent_persistent_running": { "type": [ "integer", "null" ], "format": "int32", "description": "Maximum simultaneously-running persistent sandboxes." }, "max_disk_size_mib_per_sandbox": { "type": [ "integer", "null" ], "format": "int32", "description": "Maximum writable disk size (MiB) per sandbox." }, "max_memory_mib_per_sandbox": { "type": [ "integer", "null" ], "format": "int32", "description": "Maximum memory (MiB) per sandbox." }, "max_sandboxes": { "type": [ "integer", "null" ], "format": "int32", "description": "Maximum total sandboxes the org can have." }, "max_snapshot_storage_gib": { "type": [ "integer", "null" ], "format": "int32", "description": "Per-org managed-snapshot storage hard cap (GiB)." }, "max_total_storage_gib": { "type": [ "integer", "null" ], "format": "int32", "description": "Per-org durable-storage hard cap (GiB)." }, "max_uptime_minutes_per_sandbox": { "type": [ "integer", "null" ], "format": "int32", "description": "Maximum uptime per sandbox (minutes), if set." }, "max_vcpus_per_sandbox": { "type": [ "integer", "null" ], "format": "int32", "description": "Maximum CPU cores per sandbox." }, "pool_exhausted": { "type": "boolean", "description": "Snapshot of [`PoolUsage::pool_exhausted`] at read time, for API\nconsumers - true when this org's sandboxes are being stopped and starts\nrefused." }, "snapshot_storage_bytes": { "type": "integer", "format": "int64", "description": "Exact summed compressed archive size (bytes) of the org's managed\nsnapshots - the value snapshot quota enforcement compares." }, "total_sandboxes": { "type": "integer", "format": "int64", "description": "Total sandboxes (all states) for the org." } } } ], "description": "Resolved quota limits and current usage for an organization.\n\nLimits are resolved via COALESCE: per-org override > plan. Every limit is\n`Option`: `None` = unlimited (counts/budgets) or the platform default\n(per-sandbox vCPU/memory/disk). The API materializes resource defaults in\nresponses. There is no magic 0." }, "RegistryCredentialResponse": { "type": "object", "description": "Registry credential metadata. Secret values are never returned.", "required": [ "id", "registry_host", "username", "created_at", "updated_at" ], "properties": { "created_at": { "type": "string", "format": "date-time" }, "id": { "type": "string", "format": "uuid" }, "registry_host": { "type": "string" }, "updated_at": { "type": "string", "format": "date-time" }, "username": { "type": "string" } } }, "RegistrySelection": { "oneOf": [ { "type": "object", "description": "Infer a stored credential from the image registry host.", "required": [ "mode" ], "properties": { "mode": { "type": "string", "enum": [ "auto" ] } } }, { "type": "object", "description": "Force an anonymous pull.", "required": [ "mode" ], "properties": { "mode": { "type": "string", "enum": [ "anonymous" ] } } }, { "type": "object", "description": "Use an already-stored organization credential.", "required": [ "credential_id", "mode" ], "properties": { "credential_id": { "type": "string", "format": "uuid", "description": "Id of a configured `OrgRegistryCredential` belonging to the org." }, "mode": { "type": "string", "enum": [ "specific" ] } } }, { "type": "object", "description": "Use plaintext credentials for this create-and-start operation only.", "required": [ "username", "password", "mode" ], "properties": { "mode": { "type": "string", "enum": [ "inline" ] }, "password": { "type": "string", "format": "password", "description": "Registry password or access token. Always redacted from `Debug`." }, "username": { "type": "string", "description": "Registry username." } } } ], "description": "Registry credential selection accepted on sandbox-create requests.\n\n`Inline` is deliberately request-only: its plaintext fields must be vaulted\nbefore persistence and must never enter the sandbox row, a worker launch\ndefinition, a log, or an API response." }, "Rlimit": { "type": "object", "description": "A POSIX resource limit.", "required": [ "resource", "soft", "hard" ], "properties": { "hard": { "type": "integer", "format": "int64", "description": "Hard limit (ceiling, requires privileges to raise).", "minimum": 0 }, "resource": { "$ref": "#/components/schemas/RlimitResource", "description": "Resource type." }, "soft": { "type": "integer", "format": "int64", "description": "Soft limit (can be raised up to hard limit by the process).", "minimum": 0 } } }, "RlimitResource": { "type": "string", "description": "POSIX resource limit identifiers.", "enum": [ "Cpu", "Fsize", "Data", "Stack", "Core", "Rss", "Nproc", "Nofile", "Memlock", "As", "Locks", "Sigpending", "Msgqueue", "Nice", "Rtprio", "Rttime" ] }, "Rule": { "type": "object", "description": "A single egress/ingress policy rule. Evaluated first-match-wins per\ndirection.", "required": [ "direction", "destination", "action" ], "properties": { "action": { "$ref": "#/components/schemas/Action", "description": "Action to take on a match." }, "destination": { "$ref": "#/components/schemas/Destination", "description": "Destination filter (direction-dependent interpretation)." }, "direction": { "$ref": "#/components/schemas/Direction", "description": "Direction this rule applies to." }, "ports": { "type": "array", "items": { "$ref": "#/components/schemas/PortRange" }, "description": "Guest-side port-range set; empty matches any port." }, "protocols": { "type": "array", "items": { "$ref": "#/components/schemas/Protocol" }, "description": "Protocol set; empty matches any protocol." } } }, "SandboxDailyUsage": { "type": "object", "description": "Compute usage for one sandbox on one UTC day, across both billed dimensions.\n\nComputed on read from `sandbox_runs` (not from the billing provider) - open runs accrue\nagainst `now()`, so a *running* sandbox shows live usage. Quantities are\nseconds-based (vCPU-seconds, MiB-seconds), the same units the metering events\ncarry; display converts to vCPU-hours / GiB-hours. Sum over days for a\nsandbox's period total; sum over sandboxes for the daily series.", "required": [ "sandbox_id", "day", "vcpu_seconds", "mem_mib_seconds", "disk_mib_seconds" ], "properties": { "day": { "type": "string", "format": "date-time", "description": "UTC midnight of the day this usage falls in." }, "disk_mib_seconds": { "type": "number", "format": "double", "description": "Σ(overlap_secs × disk_mib) for this sandbox on this day - provisioned\nwritable disk billed on the same GiB-seconds basis while the sandbox runs." }, "mem_mib_seconds": { "type": "number", "format": "double", "description": "Σ(overlap_secs × mem_mib) for this sandbox on this day." }, "sandbox_id": { "type": "string", "format": "uuid" }, "vcpu_seconds": { "type": "number", "format": "double", "description": "Σ(overlap_secs × vcpus) for this sandbox on this day." } } }, "SandboxIdentity": { "type": "object", "description": "Minimal sandbox display info - the directory that turns the `sandbox_id`s in\na [`UsageBreakdown`]'s rows into human labels without a second round-trip.", "required": [ "id", "name", "slug" ], "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "slug": { "type": "string" } } }, "SandboxLogLevel": { "type": "string", "description": "Runtime log verbosity for sandbox specs.", "enum": [ "error", "warn", "info", "debug", "trace" ] }, "SandboxMetricsResponse": { "type": "object", "description": "Per-sandbox metrics over a time range, keyed by metric (`cpu`,\n`memory_bytes`, `net_rx_bytes_rate`, …). See `plans/monitoring-plan.md`\n§ B for the catalog.", "required": [ "sandbox_id", "range", "metrics" ], "properties": { "metrics": { "type": "object", "description": "Metric key → series. An empty series means \"no data in range\".", "additionalProperties": { "type": "array", "items": { "$ref": "#/components/schemas/MetricSeries" } }, "propertyNames": { "type": "string" } }, "range": { "$ref": "#/components/schemas/MetricsRange", "description": "The resolved query window." }, "sandbox_id": { "type": "string", "format": "uuid", "description": "The sandbox these metrics belong to." } } }, "SandboxMountResponse": { "oneOf": [ { "type": "object", "description": "Host-subpath bind mount.", "required": [ "guest", "options", "stat_virtualization", "host_permissions", "type" ], "properties": { "guest": { "type": "string" }, "host_permissions": { "$ref": "#/components/schemas/HostPermissions" }, "options": { "$ref": "#/components/schemas/MountOptions" }, "quota_mib": { "type": [ "integer", "null" ], "format": "int32", "minimum": 0 }, "stat_virtualization": { "$ref": "#/components/schemas/StatVirtualization" }, "type": { "type": "string", "enum": [ "Bind" ] } } }, { "type": "object", "description": "Named-volume mount.", "required": [ "guest", "options", "stat_virtualization", "host_permissions", "type" ], "properties": { "guest": { "type": "string" }, "host_permissions": { "$ref": "#/components/schemas/HostPermissions" }, "options": { "$ref": "#/components/schemas/MountOptions" }, "stat_virtualization": { "$ref": "#/components/schemas/StatVirtualization" }, "type": { "type": "string", "enum": [ "Named" ] } } }, { "type": "object", "description": "Guest-memory tmpfs.", "required": [ "guest", "options", "type" ], "properties": { "guest": { "type": "string" }, "options": { "$ref": "#/components/schemas/MountOptions" }, "size_mib": { "type": [ "integer", "null" ], "format": "int32", "minimum": 0 }, "type": { "type": "string", "enum": [ "Tmpfs" ] } } }, { "type": "object", "description": "Disk-image mount.", "required": [ "guest", "format", "options", "type" ], "properties": { "format": { "$ref": "#/components/schemas/DiskImageFormat" }, "fstype": { "type": [ "string", "null" ] }, "guest": { "type": "string" }, "options": { "$ref": "#/components/schemas/MountOptions" }, "type": { "type": "string", "enum": [ "DiskImage" ] } } } ], "description": "A mount, projected for the user: guest path + options, never the resolved\nvolume id / source." }, "SandboxNetworkResponse": { "type": "object", "description": "Network config, projected for the user. Secrets drop their vault path.", "required": [ "enabled", "ports", "trust_host_cas" ], "properties": { "dns": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/DnsConfig" } ] }, "enabled": { "type": "boolean" }, "interface": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/InterfaceOverrides" } ] }, "max_connections": { "type": [ "integer", "null" ], "minimum": 0 }, "policy": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/NetworkPolicy" } ] }, "ports": { "type": "array", "items": { "$ref": "#/components/schemas/PublishedPortSpec" } }, "secrets": { "type": "array", "items": { "$ref": "#/components/schemas/SandboxSecretResponse" } }, "tls": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/TlsConfig" } ] }, "trust_host_cas": { "type": "boolean" } } }, "SandboxPolicy": { "type": "object", "description": "Sandbox lifecycle policy.", "properties": { "ephemeral": { "type": "boolean", "description": "Whether the sandbox is ephemeral.\n\nEphemeral sandboxes are one-off: the host runtime that owns the\nprocess removes the persisted DB row and on-disk state when the VM\nreaches a terminal status, and other host runtimes opportunistically\nclean up ephemeral leftovers from runtimes that died before they\ncould self-clean. Defaults to `false` (persistent); named and created\nsandboxes stay inspectable and restartable after they stop." }, "idle_timeout_secs": { "type": [ "integer", "null" ], "format": "int64", "description": "Idle timeout in seconds. `None` = no idle detection.", "minimum": 0 }, "max_duration_secs": { "type": [ "integer", "null" ], "format": "int64", "description": "Hard cap on total sandbox lifetime in seconds. `None` = run forever.", "minimum": 0 } } }, "SandboxResponse": { "type": "object", "description": "Sandbox details and resolved configuration.", "required": [ "id", "org_id", "name", "slug", "status", "ephemeral", "created_at" ], "properties": { "automatic_recovery_ends_at": { "type": [ "string", "null" ], "format": "date-time", "description": "When an explicit recovery choice becomes necessary." }, "created_at": { "type": "string", "format": "date-time" }, "ephemeral": { "type": "boolean" }, "id": { "type": "string", "format": "uuid" }, "last_failure_message": { "type": [ "string", "null" ], "description": "Human-readable reason for the last failure." }, "name": { "type": "string" }, "org_id": { "type": "string", "format": "uuid" }, "slug": { "type": "string" }, "spec": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/SandboxSpecResponse", "description": "Curated projection of the resolved spec; absent until resolved." } ] }, "started_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Latest run's start time; `null` if the sandbox has never run." }, "status": { "$ref": "#/components/schemas/SandboxStatus" }, "status_reason": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/SandboxStatusReason", "description": "Scheduler condition while `status` is `starting`." } ] }, "stopped_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Latest run's stop time; `null` while open or never run." }, "temporarily_unavailable_since": { "type": [ "string", "null" ], "format": "date-time", "description": "When the current worker outage became user-visible." } } }, "SandboxRuntimeOptions": { "type": "object", "description": "Guest runtime options for a sandbox.", "properties": { "cmd": { "type": [ "array", "null" ], "items": { "type": "string" }, "description": "Image command override.", "default": null }, "disable_metrics_sample": { "type": "boolean", "description": "Force-disable metrics sampling regardless of `metrics_sample_interval_ms`.", "default": false }, "entrypoint": { "type": [ "array", "null" ], "items": { "type": "string" }, "description": "Image entrypoint override.", "default": null }, "hostname": { "type": [ "string", "null" ], "description": "Guest hostname override.", "default": null }, "log_level": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/SandboxLogLevel", "description": "Runtime log verbosity." } ], "default": null }, "metrics_sample_interval_ms": { "type": [ "integer", "null" ], "format": "int64", "description": "Metrics sampling interval in milliseconds. `None` disables sampling.", "default": 1000, "minimum": 0 }, "scripts": { "type": "object", "description": "Named scripts available inside the guest.", "default": {}, "additionalProperties": { "type": "string" }, "propertyNames": { "type": "string" } }, "shell": { "type": [ "string", "null" ], "description": "Default shell for scripts and interactive sessions.", "default": null }, "user": { "type": [ "string", "null" ], "description": "Guest user identity override.", "default": null }, "workdir": { "type": [ "string", "null" ], "description": "Working directory inside the guest.", "default": null } } }, "SandboxSecretResponse": { "type": "object", "description": "A network secret, projected for the user: the env var, placeholder, and its\nallow-list / injection policy. The value isn't in the resolved spec at all,\nand the OpenBao vault path is never exposed.", "required": [ "env_var", "placeholder", "allowed_hosts", "injection" ], "properties": { "allowed_hosts": { "type": "array", "items": { "type": "object" } }, "env_var": { "type": "string" }, "injection": { "type": "object" }, "on_violation": { "type": "object" }, "placeholder": { "type": "string" } } }, "SandboxSpecResponse": { "type": "object", "description": "Resolved sandbox configuration. Secret values are omitted.", "required": [ "resources", "runtime", "env", "labels", "rlimits", "lifecycle", "mounts", "network" ], "properties": { "env": { "type": "array", "items": { "$ref": "#/components/schemas/EnvVar" }, "description": "Environment variables." }, "image": { "type": [ "string", "null" ], "description": "OCI image reference the sandbox boots; `null` for a non-OCI rootfs." }, "labels": { "type": "object", "description": "User-defined labels.", "additionalProperties": { "type": "string" }, "propertyNames": { "type": "string" } }, "lifecycle": { "$ref": "#/components/schemas/SandboxPolicy", "description": "Lifecycle policy." }, "mounts": { "type": "array", "items": { "$ref": "#/components/schemas/SandboxMountResponse" }, "description": "Volume mounts - guest path + options only; volume ids omitted." }, "network": { "$ref": "#/components/schemas/SandboxNetworkResponse", "description": "Network config - secret values/vault paths omitted." }, "resources": { "$ref": "#/components/schemas/CloudSandboxResources", "description": "CPU, memory, and writable-disk sizing." }, "rlimits": { "type": "array", "items": { "$ref": "#/components/schemas/Rlimit" }, "description": "Resource limits." }, "runtime": { "$ref": "#/components/schemas/SandboxRuntimeOptions", "description": "Guest runtime options." } } }, "SandboxStatus": { "type": "string", "description": "Sandbox lifecycle status.", "enum": [ "created", "starting", "running", "temporarily_unavailable", "recovery_decision_required", "stopping", "stopped", "failed" ] }, "SandboxStatusReason": { "type": "string", "description": "Why a submitted sandbox is still waiting for placement on a worker. Only\nmeaningful while `status` is `starting`.", "enum": [ "scheduling", "insufficient_capacity" ] }, "SandboxVolumeMount": { "type": "object", "description": "Public mount context for one resolved sandbox-volume binding.", "required": [ "volume_id", "mount_path", "read_only" ], "properties": { "mount_path": { "type": "string", "description": "Absolute path where the volume is mounted inside the guest." }, "name": { "type": [ "string", "null" ], "description": "User-facing volume name; `None` identifies the organization host disk." }, "read_only": { "type": "boolean", "description": "Whether this binding is read-only." }, "volume_id": { "type": "string", "format": "uuid", "description": "Resolved volume identifier, suitable for the volume metrics API." } } }, "SandboxWaitFor": { "type": "string", "enum": [ "running" ], "description": "Lifecycle state an opt-in create request may wait to observe." }, "ScopedUpstreamCaCert": { "type": "object", "description": "A CA certificate PEM file trusted only for matching upstream hosts.", "required": [ "pattern", "path" ], "properties": { "path": { "type": "string", "description": "Path to the CA certificate PEM file." }, "pattern": { "type": "string", "description": "Host pattern this CA applies to. Supports exact hosts and `*.suffix` wildcards." } } }, "ScopedVerifyUpstream": { "type": "object", "description": "An upstream certificate verification override for matching hosts.", "required": [ "pattern", "verify" ], "properties": { "pattern": { "type": "string", "description": "Host pattern this override applies to. Supports exact hosts and `*.suffix` wildcards." }, "verify": { "type": "boolean", "description": "Whether to verify matching upstream server certificates." } } }, "SecretInjection": { "type": "object", "description": "Where in the HTTP request a secret can be injected.", "properties": { "basic_auth": { "type": "boolean", "description": "Substitute in HTTP Basic Auth (default: true)." }, "body": { "type": "boolean", "description": "Substitute in request body (default: false).\n\nFixed-length HTTP/1 bodies up to 16 MiB update `Content-Length`;\nlarger fixed-length bodies are blocked. Chunked HTTP/1 bodies are\ndecoded and re-encoded with fresh chunk sizes. Encoded bodies pass\nthrough unchanged. HTTP/2 DATA-frame body substitution is not\nsupported; matching body placeholders are blocked." }, "headers": { "type": "boolean", "description": "Substitute in HTTP headers (default: true)." }, "query_params": { "type": "boolean", "description": "Substitute in URL query parameters (default: false)." } } }, "SecurityProfile": { "type": "string", "description": "Sandbox-level in-guest security profile.", "enum": [ "default", "restricted" ] }, "SlugAvailability": { "type": "object", "description": "Whether a candidate slug is well-formed and currently unused. `valid` is\nthe format check; `available` is the global-uniqueness check (only meaningful\nwhen `valid`). `reason` explains an invalid format. Lets the create form\nguide the user before the sandbox is created.", "required": [ "slug", "valid", "available" ], "properties": { "available": { "type": "boolean" }, "reason": { "type": [ "string", "null" ] }, "slug": { "type": "string" }, "valid": { "type": "boolean" } } }, "SlugSuggestion": { "type": "object", "description": "A suggested, currently-available sandbox slug to prefill the create form.", "required": [ "slug" ], "properties": { "slug": { "type": "string" } } }, "SnapshotDestinationKind": { "type": "string", "description": "Type of storage used by a snapshot.", "enum": [ "managed", "host_volume" ] }, "SnapshotFormat": { "type": "string", "description": "On-disk format of a file-state upper layer.", "enum": [ "raw", "qcow2" ] }, "SnapshotManifest": { "type": "object", "description": "Final schema-1 snapshot descriptor.\n\nField order is identity-bearing. Do not reorder these fields.\n\nGenerated bindings and API schemas expose this type as `SnapshotManifest`.", "required": [ "schema", "artifact", "scope", "created_at", "image", "state", "labels", "extensions", "requires" ], "properties": { "artifact": { "type": "string", "description": "Artifact kind. Exactly [`SNAPSHOT_ARTIFACT_KIND`]." }, "created_at": { "type": "string", "description": "Normalized RFC 3339 creation timestamp." }, "extensions": { "type": "object", "description": "Namespaced additive extension values." }, "image": { "$ref": "#/components/schemas/ImageRef", "description": "Pinned base image." }, "labels": { "type": "object", "description": "User-supplied labels, sorted by key in canonical form.", "additionalProperties": { "type": "string" }, "propertyNames": { "type": "string" } }, "parent": { "type": [ "string", "null" ], "description": "Exact snapshot identity of the logical lineage parent." }, "requires": { "type": "array", "items": { "type": "string" }, "description": "Sorted unique must-understand extension keys." }, "schema": { "type": "integer", "format": "int32", "description": "Schema version. Exactly [`SCHEMA_VERSION`].", "minimum": 0 }, "scope": { "$ref": "#/components/schemas/SnapshotScope", "description": "Snapshot payload scope." }, "source_sandbox": { "type": [ "string", "null" ], "description": "Informational source-sandbox name." }, "state": { "$ref": "#/components/schemas/SnapshotState", "description": "Closed file/checkpoint state variant." } }, "additionalProperties": false }, "SnapshotOperationListItem": { "allOf": [ { "$ref": "#/components/schemas/CloudSnapshotOperation", "description": "Public operation state and result." }, { "type": "object", "required": [ "snapshot_name", "destination_kind", "sandbox_name" ], "properties": { "destination_kind": { "$ref": "#/components/schemas/SnapshotDestinationKind", "description": "Storage destination selected for the snapshot." }, "sandbox_id": { "type": [ "string", "null" ], "description": "Source sandbox identifier, absent after sandbox deletion." }, "sandbox_name": { "type": "string", "description": "Source sandbox name retained for operation history." }, "snapshot_name": { "type": "string", "description": "Snapshot name requested by the user." } } } ], "description": "An explicit snapshot operation with enough request context to display it." }, "SnapshotScope": { "type": "string", "description": "Snapshot payload scope.", "enum": [ "disk", "resumable" ] }, "SnapshotState": { "oneOf": [ { "allOf": [ { "$ref": "#/components/schemas/FileSnapshotState", "description": "Concrete file-backed disk state." }, { "type": "object", "required": [ "kind" ], "properties": { "kind": { "type": "string", "enum": [ "file" ] } } } ], "description": "Concrete file-backed disk state." }, { "allOf": [ { "$ref": "#/components/schemas/CheckpointSnapshotState", "description": "Manifest-backed disk or resumable state." }, { "type": "object", "required": [ "kind" ], "properties": { "kind": { "type": "string", "enum": [ "checkpoint" ] } } } ], "description": "Manifest-backed disk or resumable state." } ], "description": "Closed snapshot state family." }, "StatVirtualization": { "type": "string", "description": "Stat virtualization policy for a virtiofs-backed volume mount.\n\nSerializes/deserializes as the lowercase variant name (`\"strict\"`, `\"relaxed\"`, `\"off\"`) so persisted JSON aligns with the CLI grammar (`stat-virt=strict|relaxed|off`) and the NAPI string contract.", "enum": [ "strict", "relaxed", "off" ] }, "StorageBreakdown": { "type": "object", "description": "Per-volume durable-storage usage breakdown for an org over a window:\nper-(volume, day) rows plus a directory of the volumes they reference. The\nstorage sibling of [`UsageBreakdown`](crate::UsageBreakdown). Deleted volumes'\nintervals persist, so `rows` may reference `volume_id`s absent from `volumes`;\nthe client labels those as deleted.", "required": [ "rows", "volumes" ], "properties": { "rows": { "type": "array", "items": { "$ref": "#/components/schemas/StorageDailyUsage" } }, "volumes": { "type": "array", "items": { "$ref": "#/components/schemas/VolumeIdentity" } } } }, "StorageDailyUsage": { "type": "object", "description": "Durable-storage usage for one volume on one UTC day, computed on read from\n`storage_metering_intervals`. `mib_seconds` is Σ(used_mib × overlap_seconds)\nover the day; display converts to GiB-hours or an average GiB. Sum over days\nfor a volume's period total; sum over volumes for the daily series. The\nstorage sibling of [`SandboxDailyUsage`](crate::SandboxDailyUsage).", "required": [ "volume_id", "day", "mib_seconds" ], "properties": { "day": { "type": "string", "format": "date-time", "description": "UTC midnight of the day this usage falls in." }, "mib_seconds": { "type": "number", "format": "double", "description": "Σ(used_mib × overlap_seconds) for this volume on this day." }, "volume_id": { "type": "string", "format": "uuid" } } }, "TlsConfig": { "type": "object", "description": "TLS interception configuration. Carried in [`NetworkSpec::tls`](NetworkSpec).\n\nThe local network engine terminates TCP at its in-process stack, so TLS MITM\nis handled by proxy tasks - these fields configure which ports/domains are\nintercepted and how the interception CA is sourced.", "properties": { "block_quic_on_intercept": { "type": "boolean", "description": "Drop UDP to intercepted ports when TLS interception is active, forcing\nQUIC traffic to fall back to TCP/TLS." }, "bypass": { "type": "array", "items": { "type": "string" }, "description": "Domains to bypass (no MITM). Supports exact match and `*.suffix` wildcards." }, "cache": { "$ref": "#/components/schemas/CertCacheConfig", "description": "Per-domain certificate cache configuration." }, "enabled": { "type": "boolean", "description": "Whether TLS interception is enabled." }, "intercept_ca": { "$ref": "#/components/schemas/InterceptCaConfig", "description": "Interception CA configuration. The TLS proxy uses this CA to sign\nper-domain certs it presents to the guest during interception." }, "intercepted_ports": { "type": "array", "items": { "type": "integer", "format": "int32", "minimum": 0 }, "description": "TCP ports subject to TLS interception (default: `[443]`)." }, "scoped_upstream_ca_cert": { "type": "array", "items": { "$ref": "#/components/schemas/ScopedUpstreamCaCert" }, "description": "Host-scoped CA certificate PEM files to trust for upstream server verification." }, "scoped_verify_upstream": { "type": "array", "items": { "$ref": "#/components/schemas/ScopedVerifyUpstream" }, "description": "Host-scoped upstream verification overrides." }, "upstream_ca_cert": { "type": "array", "items": { "type": "string" }, "description": "CA certificate PEM files to trust for upstream server verification." }, "verify_upstream": { "type": "boolean", "description": "Whether to verify the upstream server's TLS certificate." } } }, "UpdateMeRequest": { "type": "object", "description": "PATCH /v1/users/me", "properties": { "avatar_url": { "type": [ "string", "null" ] }, "display_name": { "type": [ "string", "null" ] } } }, "UpdateMemberRoleRequest": { "type": "object", "description": "PATCH /v1/orgs/:slug/members/:user_id - update a member's role.", "required": [ "role" ], "properties": { "role": { "$ref": "#/components/schemas/OrgRole" } } }, "UpdateOrgRequest": { "type": "object", "description": "PATCH /v1/orgs/:slug - update an organization.", "properties": { "mfa_required": { "type": [ "boolean", "null" ] }, "name": { "type": [ "string", "null" ] }, "slug": { "type": [ "string", "null" ] } } }, "UpdateSandboxRequest": { "type": "object", "description": "Request body for `PATCH /v1/orgs/:slug/sandboxes/:id` - rename a sandbox.\nEach field updates only when present; omit one to leave it unchanged.\n`name` is the per-org display label; `slug` is the globally-unique SSH\naddress handle (changing it breaks existing `ssh @msb.run`).", "properties": { "name": { "type": [ "string", "null" ], "description": "New per-org display name. Omit to leave unchanged." }, "slug": { "type": [ "string", "null" ], "description": "New globally-unique slug (the SSH username token). Omit to leave unchanged." } } }, "UpdateVolumeRequest": { "type": "object", "description": "PATCH /v1/orgs/{slug}/volumes/{id} - update the cap and/or labels (#496).\n\nEvery field is independently optional: an **omitted** field is left unchanged.\n`capacity_gib` uses the double-`Option` distinction - omit to leave as-is,\nexplicit `null` to clear the cap, a number to set it.", "properties": { "capacity_gib": { "type": [ "integer", "null" ], "format": "int32", "description": "New per-volume storage cap in GiB. Omitted = unchanged; `null` = clear the\ncap (back to no per-volume limit); a value sets it. A set value must be\n`>= 1` and `<= the org's storage cap`.", "minimum": 0 }, "labels": { "type": [ "object", "null" ], "description": "Replacement label set. Omitted = unchanged; an object replaces the labels\nwholesale (an empty object clears them). Reserved-prefix keys are rejected.", "additionalProperties": { "type": "string" }, "propertyNames": { "type": "string" } } } }, "UpperIntegrity": { "oneOf": [ { "type": "object", "description": "Ordinary SHA-256 retained only for exact legacy compatibility and\narchive metadata. New file snapshots never emit this variant.", "required": [ "digest", "algorithm" ], "properties": { "algorithm": { "type": "string", "enum": [ "sha256" ] }, "digest": { "type": "string", "description": "Algorithm output in qualified digest form." } } }, { "type": "object", "description": "Released logical-byte sparse SHA-256 representation.", "required": [ "digest", "algorithm" ], "properties": { "algorithm": { "type": "string", "enum": [ "msb-sparse-sha256-v1" ] }, "digest": { "type": "string", "description": "Algorithm output in qualified digest form." } } }, { "type": "object", "description": "Current sparse-aware fixed-leaf BLAKE3 Merkle representation.", "required": [ "root", "logical_size", "leaf_size", "algorithm" ], "properties": { "algorithm": { "type": "string", "enum": [ "msb-file-merkle-blake3-v1" ] }, "leaf_size": { "type": "integer", "format": "int32", "description": "Fixed leaf size. Exactly [`FILE_MERKLE_BLAKE3_LEAF_SIZE`].", "minimum": 0 }, "logical_size": { "type": "integer", "format": "int64", "description": "Exact logical file length bound into the final root.", "minimum": 0 }, "root": { "type": "string", "description": "Domain-separated Merkle root in qualified digest form." } } } ], "description": "Content integrity descriptor for a file-state upper layer." }, "UpperLayer": { "type": "object", "description": "Captured file-state upper-layer metadata.", "required": [ "file", "size_bytes" ], "properties": { "file": { "type": "string", "description": "One normal filename relative to the artifact directory." }, "integrity": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/UpperIntegrity", "description": "Optional semantic payload integrity. The field itself is required so\nreaders distinguish an intentional `null` from a malformed descriptor." } ] }, "size_bytes": { "type": "integer", "format": "int64", "description": "Apparent file size, including sparse holes.", "minimum": 0 } }, "additionalProperties": false }, "UpsertOidcConfigRequest": { "type": "object", "description": "PUT /v1/orgs/:slug/oidc - create or update OIDC config.", "required": [ "issuer_url", "client_id", "client_secret" ], "properties": { "allowed_domains": { "type": "array", "items": { "type": "string" } }, "client_id": { "type": "string" }, "client_secret": { "type": "string" }, "issuer_url": { "type": "string" } } }, "UpsertRegistryCredentialRequest": { "type": "object", "description": "PUT /v1/orgs/{slug}/registries", "required": [ "registry_host", "username", "password" ], "properties": { "password": { "type": "string", "description": "Password or access token. Stored in OpenBao - never persisted to the DB." }, "registry_host": { "type": "string", "description": "Registry host, e.g. `ghcr.io` or `localhost:5000`. Canonicalized\nserver-side; Docker Hub aliases fold to `docker.io`." }, "username": { "type": "string", "description": "Registry username." } } }, "UsageBreakdown": { "type": "object", "description": "Compute-on-read usage breakdown for an org over a window: per-(sandbox, day)\nquantity rows plus a directory of the sandboxes they reference. The frontend\ngroups `rows` by sandbox (for the per-sandbox table) or by day (for the\nchart) and labels them via `sandboxes`.", "required": [ "rows", "sandboxes" ], "properties": { "rows": { "type": "array", "items": { "$ref": "#/components/schemas/SandboxDailyUsage" } }, "sandboxes": { "type": "array", "items": { "$ref": "#/components/schemas/SandboxIdentity" } } } }, "UsageDailyPoint": { "type": "object", "description": "One day's metered quantity for a single billable metric - the unit of a\nusage time-series chart. Cost is intentionally omitted: invoices are\nperiod-aggregated, so a per-day dollar figure would have to be derived.", "required": [ "date", "metric", "quantity" ], "properties": { "date": { "type": "string", "format": "date-time", "description": "Start of the day window (UTC)." }, "metric": { "type": "string", "description": "Billable-metric name this quantity belongs to." }, "quantity": { "type": "number", "format": "double" } } }, "UsageLineItem": { "type": "object", "description": "A single line item in a usage summary.", "required": [ "name", "quantity", "unit", "amount_cents" ], "properties": { "amount_cents": { "type": "integer", "format": "int64" }, "name": { "type": "string" }, "quantity": { "type": "number", "format": "double" }, "unit": { "type": "string" } } }, "UsageSummary": { "type": "object", "description": "Usage summary from the billing provider.", "required": [ "period_start", "period_end", "line_items", "total_cents" ], "properties": { "daily": { "type": "array", "items": { "$ref": "#/components/schemas/UsageDailyPoint" }, "description": "Per-day metered quantities for charting. One entry per (day, metric).\nEmpty when no daily series is available (e.g. provider error)." }, "line_items": { "type": "array", "items": { "$ref": "#/components/schemas/UsageLineItem" }, "description": "Period-aggregated breakdown - one entry per billable metric / charge." }, "period_end": { "type": "string", "format": "date-time" }, "period_start": { "type": "string", "format": "date-time" }, "projected_spend_cents": { "type": "integer", "format": "int64", "description": "End-of-period spend projection: `total_cents` linearly extrapolated over\nthe billing period. Equals `total_cents` when the period can't be\nextrapolated (no future end, or zero elapsed). Never below `total_cents`." }, "snapshot_storage_gib": { "type": [ "number", "null" ], "format": "double", "description": "Current managed-snapshot storage (GiB), or `None` when never metered." }, "storage_gib": { "type": [ "number", "null" ], "format": "double", "description": "Current volume-storage usage (GiB), or `None` when never metered." }, "total_cents": { "type": "integer", "format": "int64" } } }, "User": { "type": "object", "description": "Registered user profile.", "required": [ "id", "email", "email_verified", "status", "created_at", "updated_at" ], "properties": { "avatar_url": { "type": [ "string", "null" ] }, "created_at": { "type": "string", "format": "date-time" }, "display_name": { "type": [ "string", "null" ] }, "email": { "type": "string" }, "email_verified": { "type": "boolean" }, "id": { "type": "string", "format": "uuid" }, "status": { "$ref": "#/components/schemas/UserStatus" }, "updated_at": { "type": "string", "format": "date-time" } } }, "UserStatus": { "type": "string", "description": "User account status.", "enum": [ "active", "suspended", "pending_verification" ] }, "VolumeFileContent": { "type": "string", "format": "binary", "description": "Raw bytes uploaded to or downloaded from a file." }, "VolumeFileExistsBatchResponse": { "type": "object", "description": "Requested paths that exist in the volume.", "required": [ "existing_paths" ], "properties": { "existing_paths": { "type": "array", "items": { "type": "string" } } } }, "VolumeFileExistsResponse": { "type": "object", "description": "Whether the requested path exists.", "required": [ "exists" ], "properties": { "exists": { "type": "boolean" } } }, "VolumeFileInfo": { "type": "object", "description": "Metadata for a file or directory within a volume.", "required": [ "path", "kind", "size", "mode", "uid", "gid", "readonly" ], "properties": { "accessed_at": { "type": [ "string", "null" ], "format": "date-time" }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "gid": { "type": "integer", "format": "int32", "minimum": 0 }, "kind": { "$ref": "#/components/schemas/VolumeFileKind" }, "mode": { "type": "integer", "format": "int32", "description": "Unix file mode bits.", "minimum": 0 }, "modified_at": { "type": [ "string", "null" ], "format": "date-time" }, "path": { "type": "string", "description": "Volume-relative path." }, "readonly": { "type": "boolean" }, "size": { "type": "integer", "format": "int64", "description": "Size in bytes.", "minimum": 0 }, "uid": { "type": "integer", "format": "int32", "minimum": 0 } } }, "VolumeFileKind": { "type": "string", "description": "Type of a volume entry.", "enum": [ "file", "directory" ] }, "VolumeFileListResponse": { "type": "object", "description": "Immediate entries in a directory.", "required": [ "entries" ], "properties": { "entries": { "type": "array", "items": { "$ref": "#/components/schemas/VolumeFileInfo" } } } }, "VolumeFileMutationResponse": { "type": "object", "description": "Confirmation that a filesystem change succeeded.", "required": [ "ok" ], "properties": { "ok": { "type": "boolean" } } }, "VolumeFileStatResponse": { "type": "object", "description": "Metadata for the requested path.", "required": [ "metadata" ], "properties": { "metadata": { "$ref": "#/components/schemas/VolumeFileInfo" } } }, "VolumeIdentity": { "type": "object", "description": "Minimal volume display info - the directory that turns the `volume_id`s in a\n[`StorageBreakdown`](crate::StorageBreakdown)'s rows into human labels. A\ndeleted volume's intervals outlive its row, so a breakdown may reference ids\nabsent from this directory; the client labels those as deleted.", "required": [ "id" ], "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": [ "string", "null" ], "description": "`None` for the host volume (nameless)." } } }, "VolumeKind": { "type": "string", "description": "Volume role: the organization's shared host volume or a named managed volume.", "enum": [ "host", "managed" ] }, "VolumeMetricsResponse": { "type": "object", "description": "Per-volume JuiceFS performance metrics over a time range.", "required": [ "volume_id", "range", "metrics" ], "properties": { "metrics": { "type": "object", "description": "Metric key → aggregate series across every worker mounting the volume.\nAn empty series means \"no data in range\".", "additionalProperties": { "type": "array", "items": { "$ref": "#/components/schemas/MetricSeries" } }, "propertyNames": { "type": "string" } }, "range": { "$ref": "#/components/schemas/MetricsRange", "description": "The resolved query window." }, "volume_id": { "type": "string", "format": "uuid", "description": "The volume these metrics belong to." } } }, "VolumeResponse": { "type": "object", "description": "Volume details and usage.", "required": [ "id", "kind", "storage", "status", "labels", "created_at", "updated_at" ], "properties": { "capacity_bytes": { "type": [ "integer", "null" ], "format": "int64", "description": "The volume's configured per-volume storage cap in bytes, or `null` when\nno cap is set (#496). Derived from the stored `capacity_gib` (the user's\nconfigured intent) - the effective ceiling is `min(this, org cap)`.", "minimum": 0 }, "created_at": { "type": "string", "format": "date-time" }, "id": { "type": "string", "format": "uuid" }, "kind": { "$ref": "#/components/schemas/VolumeKind", "description": "`host` - the org's shared host disk (not deletable); `managed` - a\nuser-created named volume." }, "labels": { "type": "object", "description": "User-defined labels (empty object when none set).", "additionalProperties": { "type": "string" }, "propertyNames": { "type": "string" } }, "name": { "type": [ "string", "null" ], "description": "User-facing name. `null` for the host volume (it has no name; it's\nidentified by `kind`)." }, "status": { "$ref": "#/components/schemas/VolumeStatus" }, "storage": { "$ref": "#/components/schemas/VolumeType", "description": "How the volume is physically backed (`block` today)." }, "updated_at": { "type": "string", "format": "date-time" }, "used_bytes": { "type": [ "integer", "null" ], "format": "int64", "description": "Bytes currently used under this volume's subtree. `null` when usage is\nunavailable - the usage service is disabled or unreachable (list degrades\ngracefully rather than failing) - or on create/delete, which don't sample\nit.", "minimum": 0 } } }, "VolumeStatus": { "type": "string", "description": "Lifecycle status of a volume.", "enum": [ "active", "deleting" ] }, "VolumeType": { "type": "string", "description": "How a volume is physically backed - distinct from [`VolumeKind`] (ownership).\nEvery volume is `Block` today; the enum exists so future backings can be added\n(and reported to the SDK) without another schema change.", "enum": [ "block" ] } }, "securitySchemes": { "bearer": { "type": "http", "scheme": "bearer", "description": "Personal access token (msb_pat_…) or session JWT - the credential an agent acts with on a user's behalf." } } } }