{ "openapi": "3.1.0", "info": { "title": "Shardflux API", "version": "0.1.0", "description": "The public Shardflux HTTP API, as called by the TypeScript and Python SDKs and the CLI. Authenticate every request with a project API key: `Authorization: Bearer sfk__`. Error responses use the ErrorBody schema. Workspace tools (exec, PTY, processes, files, git, browser) are served by the workspace’s cell at `cell_endpoint` with a tool token from POST /v1/workspaces/{workspace_id}/tool-tokens and are not part of this document." }, "externalDocs": { "description": "Endpoint reference", "url": "https://docs.shardflux.dev/reference/http-api/endpoints" }, "servers": [ { "url": "https://api.shardflux.dev", "description": "Production" } ], "tags": [ { "name": "Principal", "description": "The API key making the request: its organization, project and tool permissions." }, { "name": "Organizations", "description": "The organization an API key belongs to." }, { "name": "Projects", "description": "The project an API key belongs to." }, { "name": "Workspaces", "description": "Open workspaces by key, and suspend, resume, snapshot, fork, reset or close them." }, { "name": "Operations", "description": "Lifecycle operations (open, suspend, resume, fork, ...) and their progress." }, { "name": "Tool tokens", "description": "Short-lived tokens for the workspace tools (exec, PTY, files, git, browser) served at the workspace’s cell_endpoint, and agent sessions." }, { "name": "Volumes", "description": "Persistent volumes shared between workspaces of a project." }, { "name": "Templates", "description": "Published templates and their versions, files, recipes and diffs." }, { "name": "Template builds", "description": "Build template versions from a recipe or an uploaded context, and look up packages and languages." }, { "name": "Template drafts", "description": "Draft templates: iterate on states and test instances, then publish a version." }, { "name": "Secrets", "description": "Project secrets, their versions, and the secrets bound to a workspace." }, { "name": "Egress policy", "description": "Outbound network policy of a project or a workspace." }, { "name": "Usage and spend", "description": "Metered usage, estimates, grants and spend of an organization or a workspace." }, { "name": "Entitlements", "description": "The limits and features the organization’s plan grants." }, { "name": "Billing", "description": "The plan catalog and the organization’s subscription." }, { "name": "Client versions", "description": "The latest and the oldest supported version of every Shardflux client package." }, { "name": "Feedback", "description": "Send product feedback straight to the Shardflux team: what failed, confused you or is missing." } ], "paths": { "/v1/client-versions": { "get": { "operationId": "getV1ClientVersions", "summary": "Latest and minimum supported version of every Shardflux client", "tags": [ "Client versions" ], "description": "Unauthenticated, `Cache-Control: public, max-age=3600`. Clients compare their own version: below `minimum_supported` they are unsupported, below `latest` outdated. They check at most once a day (the CLI) or once per process (the SDKs), in the background, and never fail because of it.", "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "required": [ "clients" ], "properties": { "clients": { "type": "array", "items": { "type": "object", "required": [ "package", "ecosystem", "latest", "minimum_supported", "upgrade_command", "release_notes_url" ], "properties": { "package": { "type": "string", "description": "Registry package name, e.g. `@shardflux/cli`; with `ecosystem` it names one client." }, "ecosystem": { "anyOf": [ { "type": "string", "enum": [ "npm" ] }, { "type": "string", "enum": [ "pypi" ] } ] }, "latest": { "anyOf": [ { "type": "string", "description": "Latest published version; null while the package is not distributed (clients stay silent)." }, { "type": "null" } ] }, "minimum_supported": { "type": "string", "description": "Oldest version this API still serves correctly; older clients should tell their user to update." }, "upgrade_command": { "type": "string" }, "release_notes_url": { "type": "string" } }, "additionalProperties": false } } }, "additionalProperties": false } } } }, "4XX": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "examples": { "not_found": { "$ref": "#/components/examples/not_found" }, "rate_limited": { "$ref": "#/components/examples/rate_limited" }, "validation_failed": { "$ref": "#/components/examples/validation_failed" } } } } }, "5XX": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "examples": { "not_found": { "$ref": "#/components/examples/not_found" }, "rate_limited": { "$ref": "#/components/examples/rate_limited" }, "validation_failed": { "$ref": "#/components/examples/validation_failed" } } } } } } } }, "/v1/me": { "get": { "operationId": "getV1Me", "summary": "The authenticated principal", "tags": [ "Principal" ], "security": [ { "apiKey": [] } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "required": [ "type", "user", "memberships", "api_key" ], "properties": { "type": { "anyOf": [ { "type": "string", "enum": [ "user" ] }, { "type": "string", "enum": [ "api_key" ] } ] }, "user": { "anyOf": [ { "type": "object", "required": [ "id", "email", "email_verified", "display_name", "mfa_enabled" ], "properties": { "id": { "type": "string", "format": "uuid", "description": "UUIDv7, lowercase canonical form." }, "email": { "type": "string" }, "email_verified": { "type": "boolean" }, "display_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "mfa_enabled": { "type": "boolean" } }, "additionalProperties": false }, { "type": "null" } ] }, "memberships": { "type": "array", "items": { "type": "object", "required": [ "organization_id", "organization_name", "organization_slug", "role" ], "properties": { "organization_id": { "type": "string", "format": "uuid", "description": "UUIDv7, lowercase canonical form." }, "organization_name": { "type": "string" }, "organization_slug": { "type": "string" }, "role": { "type": "string", "enum": [ "owner", "admin", "member", "billing" ] } }, "additionalProperties": false } }, "api_key": { "anyOf": [ { "type": "object", "required": [ "id", "key_id", "organization_id", "project_id", "tool_permissions" ], "properties": { "id": { "type": "string", "format": "uuid", "description": "UUIDv7, lowercase canonical form." }, "key_id": { "type": "string" }, "organization_id": { "type": "string", "format": "uuid", "description": "UUIDv7, lowercase canonical form." }, "project_id": { "type": "string", "format": "uuid", "description": "UUIDv7, lowercase canonical form." }, "tool_permissions": { "type": "array", "items": { "type": "string", "enum": [ "exec", "files", "pty", "process", "git", "browser" ] } } }, "additionalProperties": false }, { "type": "null" } ] } }, "additionalProperties": false } } } }, "4XX": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "examples": { "not_found": { "$ref": "#/components/examples/not_found" }, "rate_limited": { "$ref": "#/components/examples/rate_limited" }, "validation_failed": { "$ref": "#/components/examples/validation_failed" } } } } }, "5XX": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "examples": { "not_found": { "$ref": "#/components/examples/not_found" }, "rate_limited": { "$ref": "#/components/examples/rate_limited" }, "validation_failed": { "$ref": "#/components/examples/validation_failed" } } } } } } } }, "/v1/organizations": { "get": { "operationId": "getV1Organizations", "summary": "Organizations visible to the principal", "tags": [ "Organizations" ], "parameters": [ { "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 }, "in": "query", "name": "limit", "required": false }, { "schema": { "type": "string", "maxLength": 200 }, "in": "query", "name": "cursor", "required": false } ], "security": [ { "apiKey": [] } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "next_cursor" ], "properties": { "data": { "type": "array", "items": { "type": "object", "required": [ "id", "name", "slug", "role", "created_at" ], "properties": { "id": { "type": "string", "format": "uuid", "description": "UUIDv7, lowercase canonical form." }, "name": { "type": "string" }, "slug": { "type": "string" }, "role": { "anyOf": [ { "type": "string", "enum": [ "owner", "admin", "member", "billing" ] }, { "type": "null" } ] }, "created_at": { "type": "string", "format": "date-time", "description": "RFC 3339 UTC timestamp with Z." } }, "additionalProperties": false } }, "next_cursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "additionalProperties": false } } } }, "4XX": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "examples": { "not_found": { "$ref": "#/components/examples/not_found" }, "rate_limited": { "$ref": "#/components/examples/rate_limited" }, "validation_failed": { "$ref": "#/components/examples/validation_failed" } } } } }, "5XX": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "examples": { "not_found": { "$ref": "#/components/examples/not_found" }, "rate_limited": { "$ref": "#/components/examples/rate_limited" }, "validation_failed": { "$ref": "#/components/examples/validation_failed" } } } } } } } }, "/v1/organizations/{organization_id}": { "get": { "operationId": "getV1OrganizationsOrganizationId", "summary": "Get an organization", "tags": [ "Organizations" ], "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "organization_id", "required": true, "description": "UUIDv7, lowercase canonical form." } ], "security": [ { "apiKey": [] } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "required": [ "id", "name", "slug", "role", "created_at" ], "properties": { "id": { "type": "string", "format": "uuid", "description": "UUIDv7, lowercase canonical form." }, "name": { "type": "string" }, "slug": { "type": "string" }, "role": { "anyOf": [ { "type": "string", "enum": [ "owner", "admin", "member", "billing" ] }, { "type": "null" } ] }, "created_at": { "type": "string", "format": "date-time", "description": "RFC 3339 UTC timestamp with Z." } }, "additionalProperties": false } } } }, "4XX": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "examples": { "not_found": { "$ref": "#/components/examples/not_found" }, "rate_limited": { "$ref": "#/components/examples/rate_limited" }, "validation_failed": { "$ref": "#/components/examples/validation_failed" } } } } }, "5XX": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "examples": { "not_found": { "$ref": "#/components/examples/not_found" }, "rate_limited": { "$ref": "#/components/examples/rate_limited" }, "validation_failed": { "$ref": "#/components/examples/validation_failed" } } } } } } } }, "/v1/organizations/{organization_id}/projects": { "get": { "operationId": "getV1OrganizationsOrganizationIdProjects", "summary": "List projects", "tags": [ "Projects" ], "parameters": [ { "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 }, "in": "query", "name": "limit", "required": false }, { "schema": { "type": "string", "maxLength": 200 }, "in": "query", "name": "cursor", "required": false }, { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "organization_id", "required": true, "description": "UUIDv7, lowercase canonical form." } ], "security": [ { "apiKey": [] } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "next_cursor" ], "properties": { "data": { "type": "array", "items": { "type": "object", "required": [ "id", "organization_id", "name", "slug", "created_at" ], "properties": { "id": { "type": "string", "format": "uuid", "description": "UUIDv7, lowercase canonical form." }, "organization_id": { "type": "string", "format": "uuid", "description": "UUIDv7, lowercase canonical form." }, "name": { "type": "string" }, "slug": { "type": "string" }, "created_at": { "type": "string", "format": "date-time", "description": "RFC 3339 UTC timestamp with Z." } }, "additionalProperties": false } }, "next_cursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "additionalProperties": false } } } }, "4XX": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "examples": { "not_found": { "$ref": "#/components/examples/not_found" }, "rate_limited": { "$ref": "#/components/examples/rate_limited" }, "validation_failed": { "$ref": "#/components/examples/validation_failed" } } } } }, "5XX": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "examples": { "not_found": { "$ref": "#/components/examples/not_found" }, "rate_limited": { "$ref": "#/components/examples/rate_limited" }, "validation_failed": { "$ref": "#/components/examples/validation_failed" } } } } } } } }, "/v1/projects/{project_id}": { "get": { "operationId": "getV1ProjectsProjectId", "summary": "Get a project", "tags": [ "Projects" ], "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "project_id", "required": true, "description": "UUIDv7, lowercase canonical form." } ], "security": [ { "apiKey": [] } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "required": [ "id", "organization_id", "name", "slug", "created_at" ], "properties": { "id": { "type": "string", "format": "uuid", "description": "UUIDv7, lowercase canonical form." }, "organization_id": { "type": "string", "format": "uuid", "description": "UUIDv7, lowercase canonical form." }, "name": { "type": "string" }, "slug": { "type": "string" }, "created_at": { "type": "string", "format": "date-time", "description": "RFC 3339 UTC timestamp with Z." } }, "additionalProperties": false } } } }, "4XX": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "examples": { "not_found": { "$ref": "#/components/examples/not_found" }, "rate_limited": { "$ref": "#/components/examples/rate_limited" }, "validation_failed": { "$ref": "#/components/examples/validation_failed" } } } } }, "5XX": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "examples": { "not_found": { "$ref": "#/components/examples/not_found" }, "rate_limited": { "$ref": "#/components/examples/rate_limited" }, "validation_failed": { "$ref": "#/components/examples/validation_failed" } } } } } } } }, "/v1/workspaces/open": { "post": { "operationId": "postV1WorkspacesOpen", "summary": "Open a workspace by key (create on first use, reconnect or resume afterwards)", "tags": [ "Workspaces" ], "description": "New keys resolve `template` to its latest published version; reopening never changes or resets the workspace (the response reports the template version actually used). 200 when the workspace is already running and ready (with `cell_endpoint` and a tool token); otherwise 202 with the operation to poll. A running workspace whose startup failed (`startup.state` failed) is not ready: the open is 202 with an `open` operation (input.startup_retry) that runs the failed step again. Concurrent opens of one key share one workspace and one operation. `secrets` (optional) binds secret names injected into every exec/PTY start: it sets the binding of a new key and replaces it on an existing key (omitted = unchanged); an unknown or unusable name is 422 details.reason secret_not_available with details.names (nothing is created or changed). The template version’s secret inputs join the binding on create and whenever `secrets` is given; a required one this workspace may not use is 422 input_required (details.kind secret); a bound name equal to a template env key or text input is 422 env_collision (details.name). `inputs` (optional): the version’s text inputs {NAME: string}; stored on create (else the declared default) and replaced on an existing key (omitted = unchanged); 422 input_unknown, input_invalid or input_required (details.names). `lifetime`: omitted = the version’s default (else persistent); `session` workspaces are discarded when the session ends (close(), idle timeout), after which the key opens a NEW workspace; reopening a live key with another lifetime is 409 lifetime_mismatch. A new workspace is `layered` when its version supports it and layered opens are enabled (`disk_layout`). Errors: 404 template/key outside scope, 402 `entitlement_required`, 403 `quota_exceeded` (details.limit), 409 operation in progress, deleted key (workspace_deleted) or lifetime_mismatch, 422 reserved_key_prefix (keys starting with sf:). Supports Idempotency-Key. Held open: with `Prefer: wait=` (at most 20) an open whose outcome is an operation is held until the operation is terminal or the wait elapses; success answers 200 with the running workspace, the succeeded operation and a tool token (`Preference-Applied: wait=`), anything else 202 with the fresh operation. Without `Preference-Applied` the server did not wait: poll the operation. `mode`: omitted = processful for a new key and the stored mode for an existing one; `file_first` creates a workspace whose state is a versioned file tree with no VM between executions: it is ready at once (200 with a tool token, `observed_state` running, `tree_revision` 0, no operation), needs a layered template version (409 layout_unsupported otherwise) and is persistent (`lifetime: session` or `idle_policy` with it are 422 not_supported_for_mode); each open of a file-first key re-resolves the size of its execution VMs from `caps`, the template and the plan. 422 mode_not_available while the deployment does not offer file-first workspaces; reopening a key with another mode is 409 mode_mismatch.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "key", "template" ], "properties": { "key": { "type": "string", "minLength": 1, "maxLength": 200, "pattern": "^[^\\u0000-\\u001f\\u007f]+$", "description": "Stable workspace key, unique per organization (e.g. `${customerId}/${projectId}`)." }, "template": { "type": "string", "minLength": 1, "maxLength": 100, "pattern": "^[a-z0-9](?:[a-z0-9._-]{0,98}[a-z0-9])?$", "description": "Template slug; new workspaces use its latest published version." }, "caps": { "type": "object", "properties": { "cpu_millis": { "type": "integer", "minimum": 1, "maximum": 1000000 }, "memory_mib": { "type": "integer", "minimum": 1, "maximum": 16777216 }, "disk_gib": { "type": "integer", "minimum": 1, "maximum": 1000000 } }, "additionalProperties": false, "description": "Optional user caps; the ceiling is min(template, cap, plan). Absent fields add no restriction." }, "project_id": { "type": "string", "format": "uuid", "description": "UUIDv7, lowercase canonical form." }, "agent_label": { "type": "string", "minLength": 1, "maxLength": 100, "pattern": "^[^\\u0000-\\u001f\\u007f]+$", "description": "Attribution label; one agent session per (workspace, principal, label)." }, "tools": { "type": "array", "items": { "type": "string", "enum": [ "exec", "files", "pty", "process", "git", "browser" ] }, "uniqueItems": true, "minItems": 1, "maxItems": 6 }, "secrets": { "type": "array", "items": { "type": "string", "pattern": "^[A-Z_][A-Z0-9_]{0,127}$" }, "maxItems": 50, "uniqueItems": true, "description": "Secret names bound to the workspace (max 50, unique): injected as environment variables into every exec and PTY start (terminal sessions included), together with the call’s own `secret_refs`. Each must name a live secret this workspace may use (its project, its id, and allowed_tools including exec and pty), else 422 details.reason secret_not_available with details.names." }, "inputs": { "type": "object", "properties": {}, "additionalProperties": true, "description": "Open-time inputs of the template version: {NAME: string} for its declared text inputs. A new workspace stores each given value, else the declared default; on an existing key `inputs` replaces them all (omitted = unchanged). Secret inputs are not passed here: they bind the stored secret of the same name. 422 input_unknown (undeclared name, details.names), input_invalid (a secret input, a non-string, or a value over 4096 bytes or with CR, LF or NUL; details.names), input_required (details {names, kind})." }, "lifetime": { "$ref": "#/components/schemas/WorkspaceLifetime" }, "idle_policy": { "type": "string", "pattern": "^(adaptive|never|fixed:[0-9]{2,6})$", "description": "adaptive (the learned timeout, default), never, or fixed: (60..604800)." }, "mode": { "$ref": "#/components/schemas/WorkspaceMode" } }, "additionalProperties": false } } } }, "parameters": [ { "schema": { "type": "string", "maxLength": 200 }, "in": "header", "name": "prefer", "required": false, "description": "RFC 7240 preference, e.g. `wait=20` (held open)." } ], "security": [ { "apiKey": [] } ], "responses": { "200": { "description": "200: running and ready (tool_token set). 202: poll `operation` (GET /operations/{id}).", "content": { "application/json": { "schema": { "type": "object", "required": [ "workspace", "operation", "cell_endpoint", "tool_token" ], "properties": { "workspace": { "$ref": "#/components/schemas/Workspace" }, "operation": { "anyOf": [ { "$ref": "#/components/schemas/Operation" }, { "type": "null" } ] }, "cell_endpoint": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "tool_token": { "anyOf": [ { "$ref": "#/components/schemas/ToolToken" }, { "type": "null" } ] } }, "additionalProperties": false, "description": "200: running and ready (tool_token set). 202: poll `operation` (GET /operations/{id})." } } } }, "202": { "description": "200: running and ready (tool_token set). 202: poll `operation` (GET /operations/{id}).", "content": { "application/json": { "schema": { "type": "object", "required": [ "workspace", "operation", "cell_endpoint", "tool_token" ], "properties": { "workspace": { "$ref": "#/components/schemas/Workspace" }, "operation": { "anyOf": [ { "$ref": "#/components/schemas/Operation" }, { "type": "null" } ] }, "cell_endpoint": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "tool_token": { "anyOf": [ { "$ref": "#/components/schemas/ToolToken" }, { "type": "null" } ] } }, "additionalProperties": false, "description": "200: running and ready (tool_token set). 202: poll `operation` (GET /operations/{id})." } } } }, "4XX": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "examples": { "not_found": { "$ref": "#/components/examples/not_found" }, "rate_limited": { "$ref": "#/components/examples/rate_limited" }, "validation_failed": { "$ref": "#/components/examples/validation_failed" } } } } }, "5XX": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "examples": { "not_found": { "$ref": "#/components/examples/not_found" }, "rate_limited": { "$ref": "#/components/examples/rate_limited" }, "validation_failed": { "$ref": "#/components/examples/validation_failed" } } } } } } } }, "/v1/workspaces": { "get": { "operationId": "getV1Workspaces", "summary": "List workspaces (API keys: their project; users: their organizations)", "tags": [ "Workspaces" ], "description": "By default only persistent standard workspaces; `lifetime` and `purpose` (each also `any`) show sessions, drafts and test instances. Ended sessions are tombstones: add include_deleted=true.", "parameters": [ { "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 }, "in": "query", "name": "limit", "required": false }, { "schema": { "type": "string", "maxLength": 200 }, "in": "query", "name": "cursor", "required": false }, { "schema": { "type": "string", "format": "uuid" }, "in": "query", "name": "organization_id", "required": false, "description": "UUIDv7, lowercase canonical form." }, { "schema": { "type": "string", "format": "uuid" }, "in": "query", "name": "project_id", "required": false, "description": "UUIDv7, lowercase canonical form." }, { "schema": { "type": "string", "enum": [ "creating", "starting", "running", "suspending", "suspended", "resuming", "forking", "stopping", "failed", "deleting", "deleted" ] }, "in": "query", "name": "state", "required": false, "description": "Observed state filter." }, { "schema": { "type": "string", "enum": [ "running", "suspended", "deleted" ] }, "in": "query", "name": "desired_state", "required": false }, { "schema": { "type": "string", "minLength": 1, "maxLength": 200 }, "in": "query", "name": "key_prefix", "required": false }, { "schema": { "type": "boolean", "default": false }, "in": "query", "name": "include_deleted", "required": false }, { "schema": { "type": "string", "enum": [ "persistent", "session", "any" ], "default": "persistent" }, "in": "query", "name": "lifetime", "required": false, "description": "persistent (default), session or any. Key lookups pass any." }, { "schema": { "type": "string", "enum": [ "standard", "template_draft", "template_test", "any" ], "default": "standard" }, "in": "query", "name": "purpose", "required": false, "description": "standard (default), template_draft, template_test or any. Key lookups pass any." } ], "security": [ { "apiKey": [] } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "next_cursor" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Workspace" } }, "next_cursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "additionalProperties": false } } } }, "4XX": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "examples": { "not_found": { "$ref": "#/components/examples/not_found" }, "rate_limited": { "$ref": "#/components/examples/rate_limited" }, "validation_failed": { "$ref": "#/components/examples/validation_failed" } } } } }, "5XX": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "examples": { "not_found": { "$ref": "#/components/examples/not_found" }, "rate_limited": { "$ref": "#/components/examples/rate_limited" }, "validation_failed": { "$ref": "#/components/examples/validation_failed" } } } } } } } }, "/v1/organizations/{organization_id}/workspaces": { "get": { "operationId": "getV1OrganizationsOrganizationIdWorkspaces", "summary": "List an organization’s workspaces (API keys see only their project)", "tags": [ "Workspaces" ], "parameters": [ { "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 }, "in": "query", "name": "limit", "required": false }, { "schema": { "type": "string", "maxLength": 200 }, "in": "query", "name": "cursor", "required": false }, { "schema": { "type": "string", "format": "uuid" }, "in": "query", "name": "project_id", "required": false, "description": "UUIDv7, lowercase canonical form." }, { "schema": { "type": "string", "enum": [ "creating", "starting", "running", "suspending", "suspended", "resuming", "forking", "stopping", "failed", "deleting", "deleted" ] }, "in": "query", "name": "state", "required": false, "description": "Observed state filter." }, { "schema": { "type": "string", "enum": [ "running", "suspended", "deleted" ] }, "in": "query", "name": "desired_state", "required": false }, { "schema": { "type": "string", "minLength": 1, "maxLength": 200 }, "in": "query", "name": "key_prefix", "required": false }, { "schema": { "type": "boolean", "default": false }, "in": "query", "name": "include_deleted", "required": false }, { "schema": { "type": "string", "enum": [ "persistent", "session", "any" ], "default": "persistent" }, "in": "query", "name": "lifetime", "required": false, "description": "persistent (default), session or any. Key lookups pass any." }, { "schema": { "type": "string", "enum": [ "standard", "template_draft", "template_test", "any" ], "default": "standard" }, "in": "query", "name": "purpose", "required": false, "description": "standard (default), template_draft, template_test or any. Key lookups pass any." }, { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "organization_id", "required": true, "description": "UUIDv7, lowercase canonical form." } ], "security": [ { "apiKey": [] } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "next_cursor" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Workspace" } }, "next_cursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "additionalProperties": false } } } }, "4XX": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "examples": { "not_found": { "$ref": "#/components/examples/not_found" }, "rate_limited": { "$ref": "#/components/examples/rate_limited" }, "validation_failed": { "$ref": "#/components/examples/validation_failed" } } } } }, "5XX": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "examples": { "not_found": { "$ref": "#/components/examples/not_found" }, "rate_limited": { "$ref": "#/components/examples/rate_limited" }, "validation_failed": { "$ref": "#/components/examples/validation_failed" } } } } } } } }, "/v1/workspaces/{workspace_id}": { "get": { "operationId": "getV1WorkspacesWorkspaceId", "summary": "Get a workspace: desired/observed state, cell, template version, caps/ceilings, grants, active operation, pending reason", "tags": [ "Workspaces" ], "description": "Tombstoned workspaces stay readable (deleted_at set) until final cleanup.", "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "workspace_id", "required": true, "description": "UUIDv7, lowercase canonical form." } ], "security": [ { "apiKey": [] } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Workspace" } } } }, "4XX": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "examples": { "not_found": { "$ref": "#/components/examples/not_found" }, "rate_limited": { "$ref": "#/components/examples/rate_limited" }, "validation_failed": { "$ref": "#/components/examples/validation_failed" } } } } }, "5XX": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "examples": { "not_found": { "$ref": "#/components/examples/not_found" }, "rate_limited": { "$ref": "#/components/examples/rate_limited" }, "validation_failed": { "$ref": "#/components/examples/validation_failed" } } } } } } }, "delete": { "operationId": "deleteV1WorkspacesWorkspaceId", "summary": "Delete a workspace (tombstone now, storage cleanup by the cell)", "tags": [ "Workspaces" ], "description": "Sets desired_state=deleted and deleted_at, revokes tool access immediately (workspace revocation watermark, agent sessions revoked) and creates a `delete` operation for the cell. A file-first workspace’s tree revisions are deleted with the tombstone and the cell deletes its stored files. Repeating returns the same operation. The key is never reused. Supports Idempotency-Key.", "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "workspace_id", "required": true, "description": "UUIDv7, lowercase canonical form." } ], "security": [ { "apiKey": [] } ], "responses": { "202": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "required": [ "operation", "workspace" ], "properties": { "operation": { "$ref": "#/components/schemas/Operation" }, "workspace": { "$ref": "#/components/schemas/Workspace" } }, "additionalProperties": false } } } }, "4XX": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "examples": { "not_found": { "$ref": "#/components/examples/not_found" }, "rate_limited": { "$ref": "#/components/examples/rate_limited" }, "validation_failed": { "$ref": "#/components/examples/validation_failed" } } } } }, "5XX": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "examples": { "not_found": { "$ref": "#/components/examples/not_found" }, "rate_limited": { "$ref": "#/components/examples/rate_limited" }, "validation_failed": { "$ref": "#/components/examples/validation_failed" } } } } } } } }, "/v1/workspaces/{workspace_id}/inputs": { "get": { "operationId": "getV1WorkspacesWorkspaceIdInputs", "summary": "The workspace’s text inputs", "tags": [ "Workspaces" ], "description": "The text inputs the workspace was opened with (the given value, else the declared default). Every exec, PTY, start command and service gets them as environment variables, above the template env and below the call’s own env. Secret inputs are bound secrets (GET …/secrets). Set on create; replaced by an open of the key with `inputs`. Deleted workspaces stay readable.", "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "workspace_id", "required": true, "description": "UUIDv7, lowercase canonical form." } ], "security": [ { "apiKey": [] } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkspaceInputs" } } } }, "4XX": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "examples": { "not_found": { "$ref": "#/components/examples/not_found" }, "rate_limited": { "$ref": "#/components/examples/rate_limited" }, "validation_failed": { "$ref": "#/components/examples/validation_failed" } } } } }, "5XX": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "examples": { "not_found": { "$ref": "#/components/examples/not_found" }, "rate_limited": { "$ref": "#/components/examples/rate_limited" }, "validation_failed": { "$ref": "#/components/examples/validation_failed" } } } } } } } }, "/v1/workspaces/{workspace_id}/idle-policy": { "put": { "operationId": "putV1WorkspacesWorkspaceIdIdlePolicy", "summary": "Set or clear the workspace idle policy (automatic suspend)", "tags": [ "Workspaces" ], "description": "idle_policy: adaptive (the learned timeout), never, or fixed: (60..604800); null clears it so the template default (else adaptive) applies. Work signals always win: a running command, an attached session or a keepalive keeps the workspace running. Applies from the idle loop’s next evaluation. 409 session_lifetime for session workspaces (they end after their idle timeout), 409 not_supported_for_mode for file-first workspaces (never suspended), 409 workspace_deleted. Returns the workspace.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "idle_policy" ], "properties": { "idle_policy": { "anyOf": [ { "type": "string", "pattern": "^(adaptive|never|fixed:[0-9]{2,6})$", "description": "adaptive (the learned timeout, default), never, or fixed: (60..604800)." }, { "type": "null" } ] } }, "additionalProperties": false } } } }, "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "workspace_id", "required": true, "description": "UUIDv7, lowercase canonical form." } ], "security": [ { "apiKey": [] } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Workspace" } } } }, "4XX": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "examples": { "not_found": { "$ref": "#/components/examples/not_found" }, "rate_limited": { "$ref": "#/components/examples/rate_limited" }, "validation_failed": { "$ref": "#/components/examples/validation_failed" } } } } }, "5XX": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "examples": { "not_found": { "$ref": "#/components/examples/not_found" }, "rate_limited": { "$ref": "#/components/examples/rate_limited" }, "validation_failed": { "$ref": "#/components/examples/validation_failed" } } } } } } } }, "/v1/workspaces/{workspace_id}/suspend": { "post": { "operationId": "postV1WorkspacesWorkspaceIdSuspend", "summary": "Suspend a running workspace (durable full-state checkpoint; a session workspace is 409 session_lifetime)", "tags": [ "Workspaces" ], "description": "Creates a durable operation executed by the cell (Phase 8); poll GET /operations/{id}. A file-first workspace is 409 not_supported_for_mode. Supports Idempotency-Key.", "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "workspace_id", "required": true, "description": "UUIDv7, lowercase canonical form." } ], "security": [ { "apiKey": [] } ], "responses": { "202": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "required": [ "operation", "workspace" ], "properties": { "operation": { "$ref": "#/components/schemas/Operation" }, "workspace": { "$ref": "#/components/schemas/Workspace" } }, "additionalProperties": false } } } }, "4XX": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "examples": { "not_found": { "$ref": "#/components/examples/not_found" }, "rate_limited": { "$ref": "#/components/examples/rate_limited" }, "validation_failed": { "$ref": "#/components/examples/validation_failed" } } } } }, "5XX": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "examples": { "not_found": { "$ref": "#/components/examples/not_found" }, "rate_limited": { "$ref": "#/components/examples/rate_limited" }, "validation_failed": { "$ref": "#/components/examples/validation_failed" } } } } } } } }, "/v1/workspaces/{workspace_id}/resume": { "post": { "operationId": "postV1WorkspacesWorkspaceIdResume", "summary": "Resume a suspended workspace (admitted like a start)", "tags": [ "Workspaces" ], "description": "Creates a `resume` operation executed by the cell, or returns the active resume/open (concurrent wakes join one operation); 202 with it: poll GET /operations/{id}. Errors: 409 already_running or not_suspended, operation_in_progress (a suspend or another operation is active; details.active_operation_id), workspace_deleted, not_supported_for_mode (file-first); 402/403 as for open (admitted like a start). Supports Idempotency-Key. Held resume: with `Prefer: wait=` (at most 20) the response is held until the operation is terminal or the wait elapses, exactly like a held open; success answers 200 with the running workspace, the succeeded operation, `cell_endpoint` and a tool token for `agent_label`/`tools` (minted while the restore is in flight, at the new ownership epoch), `Preference-Applied: wait=`; anything else is 202 with the fresh operation. With the preference a workspace that is already running answers 200 at once (operation null, a token) instead of 409 already_running. Without `Preference-Applied` the server did not wait: poll the operation. `tools` beyond the principal’s tool permissions are 403 (nothing is created); a token the API cannot issue otherwise is `tool_token: null`.", "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "agent_label": { "type": "string", "minLength": 1, "maxLength": 100, "pattern": "^[^\\u0000-\\u001f\\u007f]+$", "description": "Attribution label; one agent session per (workspace, principal, label)." }, "tools": { "type": "array", "items": { "type": "string", "enum": [ "exec", "files", "pty", "process", "git", "browser" ] }, "uniqueItems": true, "minItems": 1, "maxItems": 6 } }, "additionalProperties": false, "description": "The tool token a held resume returns (as for open): agent label and tools (default all the principal may use)." } } }, "description": "The tool token a held resume returns (as for open): agent label and tools (default all the principal may use)." }, "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "workspace_id", "required": true, "description": "UUIDv7, lowercase canonical form." }, { "schema": { "type": "string", "maxLength": 200 }, "in": "header", "name": "prefer", "required": false, "description": "RFC 7240 preference, e.g. `wait=20` (held resume)." } ], "security": [ { "apiKey": [] } ], "responses": { "200": { "description": "Held resume (`Prefer: wait`) that ended with the workspace running: the view, the succeeded resume (or the joined open/resume; null when the workspace was already running) and a tool token for the requested tools (null when one could not be issued: request it from POST …/tool-tokens).", "content": { "application/json": { "schema": { "type": "object", "required": [ "workspace", "operation", "cell_endpoint", "tool_token" ], "properties": { "workspace": { "$ref": "#/components/schemas/Workspace" }, "operation": { "anyOf": [ { "$ref": "#/components/schemas/Operation" }, { "type": "null" } ] }, "cell_endpoint": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "tool_token": { "anyOf": [ { "$ref": "#/components/schemas/ToolToken" }, { "type": "null" } ] } }, "additionalProperties": false, "description": "Held resume (`Prefer: wait`) that ended with the workspace running: the view, the succeeded resume (or the joined open/resume; null when the workspace was already running) and a tool token for the requested tools (null when one could not be issued: request it from POST …/tool-tokens)." } } } }, "202": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "required": [ "operation", "workspace" ], "properties": { "operation": { "$ref": "#/components/schemas/Operation" }, "workspace": { "$ref": "#/components/schemas/Workspace" } }, "additionalProperties": false } } } }, "4XX": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "examples": { "not_found": { "$ref": "#/components/examples/not_found" }, "rate_limited": { "$ref": "#/components/examples/rate_limited" }, "validation_failed": { "$ref": "#/components/examples/validation_failed" } } } } }, "5XX": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "examples": { "not_found": { "$ref": "#/components/examples/not_found" }, "rate_limited": { "$ref": "#/components/examples/rate_limited" }, "validation_failed": { "$ref": "#/components/examples/validation_failed" } } } } } } } }, "/v1/workspaces/{workspace_id}/snapshot": { "post": { "operationId": "postV1WorkspacesWorkspaceIdSnapshot", "summary": "Snapshot a running or suspended workspace", "tags": [ "Workspaces" ], "description": "Creates a durable operation executed by the cell (Phase 8); poll GET /operations/{id}. A file-first workspace is 409 not_supported_for_mode. Supports Idempotency-Key.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "label": { "type": "string", "minLength": 1, "maxLength": 200, "pattern": "^[^\\u0000-\\u001f\\u007f]+$" } }, "additionalProperties": false } } } }, "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "workspace_id", "required": true, "description": "UUIDv7, lowercase canonical form." } ], "security": [ { "apiKey": [] } ], "responses": { "202": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "required": [ "operation", "workspace" ], "properties": { "operation": { "$ref": "#/components/schemas/Operation" }, "workspace": { "$ref": "#/components/schemas/Workspace" } }, "additionalProperties": false } } } }, "4XX": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "examples": { "not_found": { "$ref": "#/components/examples/not_found" }, "rate_limited": { "$ref": "#/components/examples/rate_limited" }, "validation_failed": { "$ref": "#/components/examples/validation_failed" } } } } }, "5XX": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "examples": { "not_found": { "$ref": "#/components/examples/not_found" }, "rate_limited": { "$ref": "#/components/examples/rate_limited" }, "validation_failed": { "$ref": "#/components/examples/validation_failed" } } } } } } } }, "/v1/workspaces/{workspace_id}/suspend-when-idle": { "post": { "operationId": "postV1WorkspacesWorkspaceIdSuspendWhenIdle", "summary": "Suspend the workspace if it stays idle for after_seconds from now (e.g. at the end of an agent turn)", "tags": [ "Workspaces" ], "description": "Records a deferred suspend for the cell’s idle loop: once the workspace has been idle for after_seconds (30..3600), it is suspended (within a few seconds of activity flush grace), at `not_before` (= now + after_seconds) at the earliest. A tool call after the request (the next turn) or a resume cancels it for good. Other work only defers it: a command still running, an attached exec/PTY stream or a keepalive postpones the suspend until after_seconds after it ends. It applies under every idle policy (`never` included) and only ever shortens the policy’s wait; a policy that suspends sooner still does. Repeating replaces the pending request (the new `requested_at` counts); DELETE cancels it; `idle.suspend_request` on the workspace shows it. 202 {workspace, operation: null, suspend_request}; when a suspend is already in progress, 202 {workspace, operation: that suspend, suspend_request: null} and nothing is recorded. The suspend, when it happens, is a system `suspend` operation with input.reason requested_after_idle (input.requested_at, input.after_seconds). Errors: 409 session_lifetime, workspace_deleted, operation_in_progress (another lifecycle operation is active), not_running, not_supported_for_mode (file-first). Supports Idempotency-Key.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "after_seconds" ], "properties": { "after_seconds": { "type": "integer", "minimum": 30, "maximum": 3600, "description": "Seconds from now the workspace must stay idle before it is suspended (30..3600)." } }, "additionalProperties": false } } } }, "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "workspace_id", "required": true, "description": "UUIDv7, lowercase canonical form." } ], "security": [ { "apiKey": [] } ], "responses": { "202": { "description": "suspend_request: the recorded request. operation: set (and suspend_request null) only when a suspend was already in progress.", "content": { "application/json": { "schema": { "type": "object", "required": [ "workspace", "operation", "suspend_request" ], "properties": { "workspace": { "$ref": "#/components/schemas/Workspace" }, "operation": { "anyOf": [ { "$ref": "#/components/schemas/Operation" }, { "type": "null" } ] }, "suspend_request": { "anyOf": [ { "$ref": "#/components/schemas/SuspendRequest" }, { "type": "null" } ] } }, "additionalProperties": false, "description": "suspend_request: the recorded request. operation: set (and suspend_request null) only when a suspend was already in progress." } } } }, "4XX": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "examples": { "not_found": { "$ref": "#/components/examples/not_found" }, "rate_limited": { "$ref": "#/components/examples/rate_limited" }, "validation_failed": { "$ref": "#/components/examples/validation_failed" } } } } }, "5XX": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "examples": { "not_found": { "$ref": "#/components/examples/not_found" }, "rate_limited": { "$ref": "#/components/examples/rate_limited" }, "validation_failed": { "$ref": "#/components/examples/validation_failed" } } } } } } }, "delete": { "operationId": "deleteV1WorkspacesWorkspaceIdSuspendWhenIdle", "summary": "Cancel a pending suspend-when-idle request", "tags": [ "Workspaces" ], "description": "Idempotent: 200 with the workspace whether or not a request was pending, in any workspace state (idle.suspend_request is null afterwards). A suspend the request already started is not undone: it shows as the workspace’s active_operation; resume or open the workspace instead.", "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "workspace_id", "required": true, "description": "UUIDv7, lowercase canonical form." } ], "security": [ { "apiKey": [] } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Workspace" } } } }, "4XX": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "examples": { "not_found": { "$ref": "#/components/examples/not_found" }, "rate_limited": { "$ref": "#/components/examples/rate_limited" }, "validation_failed": { "$ref": "#/components/examples/validation_failed" } } } } }, "5XX": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "examples": { "not_found": { "$ref": "#/components/examples/not_found" }, "rate_limited": { "$ref": "#/components/examples/rate_limited" }, "validation_failed": { "$ref": "#/components/examples/validation_failed" } } } } } } } }, "/v1/workspaces/{workspace_id}/fork": { "post": { "operationId": "postV1WorkspacesWorkspaceIdFork", "summary": "Fork a workspace into a new key (independent copy of its committed state)", "tags": [ "Workspaces" ], "description": "Creates the target workspace (same template version and disk layout) and a `fork` operation on it, admitted like a start. Caps default to the source’s. `lifetime` is the fork’s own (default persistent): forking a session keeps its state. A file-first source is 409 not_supported_for_mode. Supports Idempotency-Key.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "key" ], "properties": { "key": { "type": "string", "minLength": 1, "maxLength": 200, "pattern": "^[^\\u0000-\\u001f\\u007f]+$", "description": "Stable workspace key, unique per organization (e.g. `${customerId}/${projectId}`)." }, "caps": { "type": "object", "properties": { "cpu_millis": { "type": "integer", "minimum": 1, "maximum": 1000000 }, "memory_mib": { "type": "integer", "minimum": 1, "maximum": 16777216 }, "disk_gib": { "type": "integer", "minimum": 1, "maximum": 1000000 } }, "additionalProperties": false, "description": "Optional user caps; the ceiling is min(template, cap, plan). Absent fields add no restriction." }, "lifetime": { "$ref": "#/components/schemas/WorkspaceLifetime" } }, "additionalProperties": false } } } }, "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "workspace_id", "required": true, "description": "UUIDv7, lowercase canonical form." } ], "security": [ { "apiKey": [] } ], "responses": { "202": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "required": [ "operation", "workspace", "source_workspace_id" ], "properties": { "operation": { "$ref": "#/components/schemas/Operation" }, "workspace": { "$ref": "#/components/schemas/Workspace" }, "source_workspace_id": { "type": "string", "format": "uuid", "description": "UUIDv7, lowercase canonical form." } }, "additionalProperties": false } } } }, "4XX": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "examples": { "not_found": { "$ref": "#/components/examples/not_found" }, "rate_limited": { "$ref": "#/components/examples/rate_limited" }, "validation_failed": { "$ref": "#/components/examples/validation_failed" } } } } }, "5XX": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "examples": { "not_found": { "$ref": "#/components/examples/not_found" }, "rate_limited": { "$ref": "#/components/examples/rate_limited" }, "validation_failed": { "$ref": "#/components/examples/validation_failed" } } } } } } } }, "/v1/workspaces/{workspace_id}/close": { "post": { "operationId": "postV1WorkspacesWorkspaceIdClose", "summary": "Close a session workspace (ends the session: the workspace is deleted)", "tags": [ "Workspaces" ], "description": "Sessions only (409 not_session for a persistent workspace; the SDK then only closes local streams). Ends the session exactly like a delete (VM stopped without a snapshot, layer and checkpoints released) with ended_reason closed; the key then opens a NEW workspace. 202 with the `delete` operation (input.reason session_closed). Idempotent: repeating returns the active or last delete operation. Supports Idempotency-Key.", "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "workspace_id", "required": true, "description": "UUIDv7, lowercase canonical form." } ], "security": [ { "apiKey": [] } ], "responses": { "202": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "required": [ "operation", "workspace" ], "properties": { "operation": { "$ref": "#/components/schemas/Operation" }, "workspace": { "$ref": "#/components/schemas/Workspace" } }, "additionalProperties": false } } } }, "4XX": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "examples": { "not_found": { "$ref": "#/components/examples/not_found" }, "rate_limited": { "$ref": "#/components/examples/rate_limited" }, "validation_failed": { "$ref": "#/components/examples/validation_failed" } } } } }, "5XX": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "examples": { "not_found": { "$ref": "#/components/examples/not_found" }, "rate_limited": { "$ref": "#/components/examples/rate_limited" }, "validation_failed": { "$ref": "#/components/examples/validation_failed" } } } } } } } }, "/v1/workspaces/{workspace_id}/reset": { "post": { "operationId": "postV1WorkspacesWorkspaceIdReset", "summary": "Reset a layered workspace to its template (wipes the workspace layer)", "tags": [ "Workspaces" ], "description": "Keeps the key, id, template version, caps, secret bindings, volume attachments and history; wipes every change. Running: restarted on a blank layer (processes are gone, epoch + 1, old tool tokens get 409 stale_epoch). Suspended: stays suspended; the next resume boots blank. The previous checkpoint stays restorable for 7 days (result.recovery_checkpoint_id). 202 with the `reset` operation. Errors: 422 confirm_destructive_required, 409 legacy_disk_layout, not_resettable, operation_in_progress, not_supported_for_mode (file-first). Supports Idempotency-Key.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResetWorkspaceBody" } } } }, "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "workspace_id", "required": true, "description": "UUIDv7, lowercase canonical form." } ], "security": [ { "apiKey": [] } ], "responses": { "202": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "required": [ "operation", "workspace" ], "properties": { "operation": { "$ref": "#/components/schemas/Operation" }, "workspace": { "$ref": "#/components/schemas/Workspace" } }, "additionalProperties": false } } } }, "4XX": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "examples": { "not_found": { "$ref": "#/components/examples/not_found" }, "rate_limited": { "$ref": "#/components/examples/rate_limited" }, "validation_failed": { "$ref": "#/components/examples/validation_failed" } } } } }, "5XX": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "examples": { "not_found": { "$ref": "#/components/examples/not_found" }, "rate_limited": { "$ref": "#/components/examples/rate_limited" }, "validation_failed": { "$ref": "#/components/examples/validation_failed" } } } } } } } }, "/v1/workspaces/{workspace_id}/save-as-template": { "post": { "operationId": "postV1WorkspacesWorkspaceIdSaveAsTemplate", "summary": "Save a layered workspace as the next version of an organization template", "tags": [ "Workspaces" ], "description": "Everything in the workspace becomes template content (its whole filesystem, minus the sf-scrub.v1 list, the contents of /proc, /sys, /dev, /run and /tmp, and shared-volume contents), stored as one new org layer on the workspace’s template chain. A running workspace is captured briefly (`operation`, layer_snapshot); a suspended one uses its current checkpoint; `checkpoint_id` saves a committed checkpoint instead. 202 SaveAsTemplateResponse: poll the build. Owners/admins and API keys with a tool permission (403 otherwise). Errors: 409 legacy_disk_layout, workspace_not_running, operation_in_progress, not_supported_for_mode (file-first), template_archived, 422 platform_template_slug, invalid_defaults, update_policy_not_available, too_many_acknowledged_findings, invalid_path, 403 quota_exceeded (concurrent_template_builds). Supports Idempotency-Key.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SaveAsTemplateBody" } } } }, "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "workspace_id", "required": true, "description": "UUIDv7, lowercase canonical form." } ], "security": [ { "apiKey": [] } ], "responses": { "202": { "description": "operation: the capture (layer_snapshot) of a running workspace, null otherwise. build: poll GET …/template-builds/{id} until registration.state is registered.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SaveAsTemplateResponse" } } } }, "4XX": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "examples": { "not_found": { "$ref": "#/components/examples/not_found" }, "rate_limited": { "$ref": "#/components/examples/rate_limited" }, "validation_failed": { "$ref": "#/components/examples/validation_failed" } } } } }, "5XX": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "examples": { "not_found": { "$ref": "#/components/examples/not_found" }, "rate_limited": { "$ref": "#/components/examples/rate_limited" }, "validation_failed": { "$ref": "#/components/examples/validation_failed" } } } } } } } }, "/v1/operations/{operation_id}": { "get": { "operationId": "getV1OperationsOperationId", "summary": "Poll an asynchronous operation", "tags": [ "Operations" ], "description": "Stays readable after its workspace is tombstoned. Bounded wait: with `Prefer: wait=` (at most 20) and an operation that is not terminal, the response is held until its `state` or `state_reason` changes or the wait elapses, then carries the fresh operation and `Preference-Applied: wait=`. Without `Preference-Applied` the server did not wait: poll with backoff.", "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "operation_id", "required": true, "description": "UUIDv7, lowercase canonical form." }, { "schema": { "type": "string", "maxLength": 200 }, "in": "header", "name": "prefer", "required": false, "description": "RFC 7240 preference, e.g. `wait=20`." } ], "security": [ { "apiKey": [] } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "required": [ "operation" ], "properties": { "operation": { "$ref": "#/components/schemas/Operation" } }, "additionalProperties": false } } } }, "4XX": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "examples": { "not_found": { "$ref": "#/components/examples/not_found" }, "rate_limited": { "$ref": "#/components/examples/rate_limited" }, "validation_failed": { "$ref": "#/components/examples/validation_failed" } } } } }, "5XX": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "examples": { "not_found": { "$ref": "#/components/examples/not_found" }, "rate_limited": { "$ref": "#/components/examples/rate_limited" }, "validation_failed": { "$ref": "#/components/examples/validation_failed" } } } } } } } }, "/v1/workspaces/{workspace_id}/operations": { "get": { "operationId": "getV1WorkspacesWorkspaceIdOperations", "summary": "List a workspace’s operations, newest first", "tags": [ "Operations" ], "parameters": [ { "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 }, "in": "query", "name": "limit", "required": false }, { "schema": { "type": "string", "maxLength": 200 }, "in": "query", "name": "cursor", "required": false }, { "schema": { "type": "string", "enum": [ "queued", "capacity_pending", "running", "succeeded", "failed", "canceled" ] }, "in": "query", "name": "state", "required": false }, { "schema": { "type": "string", "enum": [ "open", "suspend", "resume", "fork", "snapshot", "restore", "delete", "move", "resize", "volume_create", "volume_attach", "volume_detach", "volume_delete", "reset", "layer_snapshot" ] }, "in": "query", "name": "kind", "required": false }, { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "workspace_id", "required": true, "description": "UUIDv7, lowercase canonical form." } ], "security": [ { "apiKey": [] } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "next_cursor" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Operation" } }, "next_cursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "additionalProperties": false } } } }, "4XX": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "examples": { "not_found": { "$ref": "#/components/examples/not_found" }, "rate_limited": { "$ref": "#/components/examples/rate_limited" }, "validation_failed": { "$ref": "#/components/examples/validation_failed" } } } } }, "5XX": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "examples": { "not_found": { "$ref": "#/components/examples/not_found" }, "rate_limited": { "$ref": "#/components/examples/rate_limited" }, "validation_failed": { "$ref": "#/components/examples/validation_failed" } } } } } } } }, "/v1/workspaces/{workspace_id}/tool-tokens": { "post": { "operationId": "postV1WorkspacesWorkspaceIdToolTokens", "summary": "Issue a workspace tool token (ES256, <= 15 min) for the cell gateway", "tags": [ "Tool tokens" ], "description": "Creates or reuses the agent session for (workspace, principal, agent_label) and signs a token with claims iss, aud, sub, pty, org, prj, ws, epoch, tools, sid, iat, exp, jti (verify with GET /v1/.well-known/tool-token-keys). `tools` must be a subset of the API key’s tool permissions (users: of their role). A suspended workspace gets a token too: the cell serves it only the reads of its disk (`files` read, stat, list and search, `X-Served-From: disk`) and answers every other call 409 `workspace_not_running` (wake the workspace; its resume moves the ownership epoch). 409 with the active operation when the workspace is neither running nor suspended; on 409 `stale_epoch` from the cell, request a new token.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "agent_label": { "type": "string", "minLength": 1, "maxLength": 100, "pattern": "^[^\\u0000-\\u001f\\u007f]+$", "description": "Attribution label; one agent session per (workspace, principal, label)." }, "tools": { "type": "array", "items": { "type": "string", "enum": [ "exec", "files", "pty", "process", "git", "browser" ] }, "uniqueItems": true, "minItems": 1, "maxItems": 6 } }, "additionalProperties": false } } } }, "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "workspace_id", "required": true, "description": "UUIDv7, lowercase canonical form." } ], "security": [ { "apiKey": [] } ], "responses": { "201": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ToolToken" } } } }, "4XX": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "examples": { "not_found": { "$ref": "#/components/examples/not_found" }, "rate_limited": { "$ref": "#/components/examples/rate_limited" }, "validation_failed": { "$ref": "#/components/examples/validation_failed" } } } } }, "5XX": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "examples": { "not_found": { "$ref": "#/components/examples/not_found" }, "rate_limited": { "$ref": "#/components/examples/rate_limited" }, "validation_failed": { "$ref": "#/components/examples/validation_failed" } } } } } } } }, "/v1/workspaces/{workspace_id}/agent-sessions": { "get": { "operationId": "getV1WorkspacesWorkspaceIdAgentSessions", "summary": "List the attributed agent sessions of a workspace", "tags": [ "Tool tokens" ], "parameters": [ { "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 }, "in": "query", "name": "limit", "required": false }, { "schema": { "type": "string", "maxLength": 200 }, "in": "query", "name": "cursor", "required": false }, { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "workspace_id", "required": true, "description": "UUIDv7, lowercase canonical form." } ], "security": [ { "apiKey": [] } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "next_cursor" ], "properties": { "data": { "type": "array", "items": { "type": "object", "required": [ "id", "workspace_id", "agent_label", "principal_type", "principal_id", "created_at", "last_token_issued_at", "tokens_issued", "revoked_at" ], "properties": { "id": { "type": "string", "format": "uuid", "description": "UUIDv7, lowercase canonical form." }, "workspace_id": { "type": "string", "format": "uuid", "description": "UUIDv7, lowercase canonical form." }, "agent_label": { "type": "string" }, "principal_type": { "anyOf": [ { "type": "string", "enum": [ "user" ] }, { "type": "string", "enum": [ "api_key" ] } ] }, "principal_id": { "type": "string", "format": "uuid", "description": "UUIDv7, lowercase canonical form." }, "created_at": { "type": "string", "format": "date-time", "description": "RFC 3339 UTC timestamp with Z." }, "last_token_issued_at": { "anyOf": [ { "type": "string", "format": "date-time", "description": "RFC 3339 UTC timestamp with Z." }, { "type": "null" } ] }, "tokens_issued": { "type": "integer" }, "revoked_at": { "anyOf": [ { "type": "string", "format": "date-time", "description": "RFC 3339 UTC timestamp with Z." }, { "type": "null" } ] } }, "additionalProperties": false } }, "next_cursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "additionalProperties": false } } } }, "4XX": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "examples": { "not_found": { "$ref": "#/components/examples/not_found" }, "rate_limited": { "$ref": "#/components/examples/rate_limited" }, "validation_failed": { "$ref": "#/components/examples/validation_failed" } } } } }, "5XX": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "examples": { "not_found": { "$ref": "#/components/examples/not_found" }, "rate_limited": { "$ref": "#/components/examples/rate_limited" }, "validation_failed": { "$ref": "#/components/examples/validation_failed" } } } } } } } }, "/v1/organizations/{organization_id}/entitlements": { "get": { "operationId": "getV1OrganizationsOrganizationIdEntitlements", "summary": "Resolved plan limits, allowances and policies of an organization", "tags": [ "Entitlements" ], "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "organization_id", "required": true, "description": "UUIDv7, lowercase canonical form." } ], "security": [ { "apiKey": [] } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "required": [ "organization_id", "plan", "limits", "allowances", "policies", "restrictions", "resolved_at" ], "properties": { "organization_id": { "type": "string", "format": "uuid", "description": "UUIDv7, lowercase canonical form." }, "plan": { "anyOf": [ { "type": "object", "required": [ "plan_key", "catalog_version", "source" ], "properties": { "plan_key": { "type": "string" }, "catalog_version": { "type": "string" }, "source": { "anyOf": [ { "type": "string", "enum": [ "override" ] }, { "type": "string", "enum": [ "subscription" ] }, { "type": "string", "enum": [ "trial" ] }, { "type": "string", "enum": [ "default" ] } ] } }, "additionalProperties": false }, { "type": "null" } ] }, "limits": { "type": "object", "properties": {}, "additionalProperties": true, "description": "Resolved plan limits (null = unlimited)." }, "allowances": { "type": "object", "properties": {}, "additionalProperties": true }, "policies": { "type": "object", "properties": {}, "additionalProperties": true }, "restrictions": { "type": "object", "properties": {}, "additionalProperties": true, "description": "Active admission restrictions, e.g. `new_starts` {reason, since, grace_until} after a payment grace period ended." }, "resolved_at": { "type": "string", "format": "date-time", "description": "RFC 3339 UTC timestamp with Z." } }, "additionalProperties": false } } } }, "4XX": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "examples": { "not_found": { "$ref": "#/components/examples/not_found" }, "rate_limited": { "$ref": "#/components/examples/rate_limited" }, "validation_failed": { "$ref": "#/components/examples/validation_failed" } } } } }, "5XX": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "examples": { "not_found": { "$ref": "#/components/examples/not_found" }, "rate_limited": { "$ref": "#/components/examples/rate_limited" }, "validation_failed": { "$ref": "#/components/examples/validation_failed" } } } } } } } }, "/v1/projects/{project_id}/volumes": { "get": { "operationId": "getV1ProjectsProjectIdVolumes", "summary": "List a project’s shared volumes (optionally with the organization’s org-shared volumes)", "tags": [ "Volumes" ], "parameters": [ { "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 }, "in": "query", "name": "limit", "required": false }, { "schema": { "type": "string", "maxLength": 200 }, "in": "query", "name": "cursor", "required": false }, { "schema": { "type": "boolean", "default": false }, "in": "query", "name": "include_org_shared", "required": false, "description": "Also list org-shared volumes owned by other projects of the organization (attachable here)." }, { "schema": { "type": "boolean", "default": false }, "in": "query", "name": "include_deleted", "required": false }, { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "project_id", "required": true, "description": "UUIDv7, lowercase canonical form." } ], "security": [ { "apiKey": [] } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "next_cursor" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Volume" } }, "next_cursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "additionalProperties": false } } } }, "4XX": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "examples": { "not_found": { "$ref": "#/components/examples/not_found" }, "rate_limited": { "$ref": "#/components/examples/rate_limited" }, "validation_failed": { "$ref": "#/components/examples/validation_failed" } } } } }, "5XX": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "examples": { "not_found": { "$ref": "#/components/examples/not_found" }, "rate_limited": { "$ref": "#/components/examples/rate_limited" }, "validation_failed": { "$ref": "#/components/examples/validation_failed" } } } } } } }, "post": { "operationId": "postV1ProjectsProjectIdVolumes", "summary": "Create a shared volume (EFS access point created by the cell)", "tags": [ "Volumes" ], "description": "202 with the volume (state `creating`) and its `volume_create` operation; the volume becomes `available` when the cell has created its storage (poll the operation or the volume). Quotas from the plan: limit.shared_volumes_max (live volumes per organization) and limit.shared_volume_gib_max (quota_gib of one volume) -> 403 quota_exceeded (details.limit); a plan without them -> 402 entitlement_required (details.reason limits_missing). `org_shared: true` (owners/admins only) makes it attachable from every project of the organization. 409 name_in_use. Supports Idempotency-Key.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "name", "quota_gib" ], "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 63, "pattern": "^[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?$", "description": "Unique among the project’s live volumes." }, "quota_gib": { "type": "integer", "minimum": 1, "maximum": 65536 }, "org_shared": { "type": "boolean", "default": false } }, "additionalProperties": false } } } }, "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "project_id", "required": true, "description": "UUIDv7, lowercase canonical form." } ], "security": [ { "apiKey": [] } ], "responses": { "202": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "required": [ "volume", "operation" ], "properties": { "volume": { "$ref": "#/components/schemas/Volume" }, "operation": { "$ref": "#/components/schemas/Operation" } }, "additionalProperties": false } } } }, "4XX": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "examples": { "not_found": { "$ref": "#/components/examples/not_found" }, "rate_limited": { "$ref": "#/components/examples/rate_limited" }, "validation_failed": { "$ref": "#/components/examples/validation_failed" } } } } }, "5XX": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "examples": { "not_found": { "$ref": "#/components/examples/not_found" }, "rate_limited": { "$ref": "#/components/examples/rate_limited" }, "validation_failed": { "$ref": "#/components/examples/validation_failed" } } } } } } } }, "/v1/projects/{project_id}/volumes/{volume_id}": { "get": { "operationId": "getV1ProjectsProjectIdVolumesVolumeId", "summary": "Get a shared volume (the project’s own, or an org-shared volume of its organization)", "tags": [ "Volumes" ], "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "project_id", "required": true, "description": "UUIDv7, lowercase canonical form." }, { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "volume_id", "required": true, "description": "UUIDv7, lowercase canonical form." } ], "security": [ { "apiKey": [] } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Volume" } } } }, "4XX": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "examples": { "not_found": { "$ref": "#/components/examples/not_found" }, "rate_limited": { "$ref": "#/components/examples/rate_limited" }, "validation_failed": { "$ref": "#/components/examples/validation_failed" } } } } }, "5XX": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "examples": { "not_found": { "$ref": "#/components/examples/not_found" }, "rate_limited": { "$ref": "#/components/examples/rate_limited" }, "validation_failed": { "$ref": "#/components/examples/validation_failed" } } } } } } }, "delete": { "operationId": "deleteV1ProjectsProjectIdVolumesVolumeId", "summary": "Delete a shared volume and its data (executed by the cell)", "tags": [ "Volumes" ], "description": "202 with the volume (state `deleting`) and its `volume_delete` operation; `deleted` once the cell removed the data and the access point. Refused with 409 volume_attached (details.attachments) while it is attached, unless `force=true&confirm_name=`: attachments are then detached by the delete (running guests see I/O errors on the mount). Only the owning project; org-shared volumes only by owners/admins. Idempotent (a deleting/deleted volume returns its delete operation). Supports Idempotency-Key.", "parameters": [ { "schema": { "type": "boolean", "default": false }, "in": "query", "name": "force", "required": false }, { "schema": { "type": "string", "maxLength": 63 }, "in": "query", "name": "confirm_name", "required": false }, { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "project_id", "required": true, "description": "UUIDv7, lowercase canonical form." }, { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "volume_id", "required": true, "description": "UUIDv7, lowercase canonical form." } ], "security": [ { "apiKey": [] } ], "responses": { "202": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "required": [ "volume", "operation" ], "properties": { "volume": { "$ref": "#/components/schemas/Volume" }, "operation": { "$ref": "#/components/schemas/Operation" } }, "additionalProperties": false } } } }, "4XX": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "examples": { "not_found": { "$ref": "#/components/examples/not_found" }, "rate_limited": { "$ref": "#/components/examples/rate_limited" }, "validation_failed": { "$ref": "#/components/examples/validation_failed" } } } } }, "5XX": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "examples": { "not_found": { "$ref": "#/components/examples/not_found" }, "rate_limited": { "$ref": "#/components/examples/rate_limited" }, "validation_failed": { "$ref": "#/components/examples/validation_failed" } } } } } } } }, "/v1/projects/{project_id}/volumes/{volume_id}/attachments": { "get": { "operationId": "getV1ProjectsProjectIdVolumesVolumeIdAttachments", "summary": "List a volume’s attachments (API keys: only to their project’s workspaces)", "tags": [ "Volumes" ], "parameters": [ { "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 }, "in": "query", "name": "limit", "required": false }, { "schema": { "type": "string", "maxLength": 200 }, "in": "query", "name": "cursor", "required": false }, { "schema": { "type": "boolean", "default": false }, "in": "query", "name": "include_detached", "required": false }, { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "project_id", "required": true, "description": "UUIDv7, lowercase canonical form." }, { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "volume_id", "required": true, "description": "UUIDv7, lowercase canonical form." } ], "security": [ { "apiKey": [] } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "next_cursor" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/VolumeAttachment" } }, "next_cursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "additionalProperties": false } } } }, "4XX": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "examples": { "not_found": { "$ref": "#/components/examples/not_found" }, "rate_limited": { "$ref": "#/components/examples/rate_limited" }, "validation_failed": { "$ref": "#/components/examples/validation_failed" } } } } }, "5XX": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "examples": { "not_found": { "$ref": "#/components/examples/not_found" }, "rate_limited": { "$ref": "#/components/examples/rate_limited" }, "validation_failed": { "$ref": "#/components/examples/validation_failed" } } } } } } } }, "/v1/workspaces/{workspace_id}/volumes": { "get": { "operationId": "getV1WorkspacesWorkspaceIdVolumes", "summary": "List the volumes attached to a workspace", "tags": [ "Volumes" ], "parameters": [ { "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 }, "in": "query", "name": "limit", "required": false }, { "schema": { "type": "string", "maxLength": 200 }, "in": "query", "name": "cursor", "required": false }, { "schema": { "type": "boolean", "default": false }, "in": "query", "name": "include_detached", "required": false }, { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "workspace_id", "required": true, "description": "UUIDv7, lowercase canonical form." } ], "security": [ { "apiKey": [] } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "next_cursor" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/VolumeAttachment" } }, "next_cursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "additionalProperties": false } } } }, "4XX": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "examples": { "not_found": { "$ref": "#/components/examples/not_found" }, "rate_limited": { "$ref": "#/components/examples/rate_limited" }, "validation_failed": { "$ref": "#/components/examples/validation_failed" } } } } }, "5XX": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "examples": { "not_found": { "$ref": "#/components/examples/not_found" }, "rate_limited": { "$ref": "#/components/examples/rate_limited" }, "validation_failed": { "$ref": "#/components/examples/validation_failed" } } } } } } }, "post": { "operationId": "postV1WorkspacesWorkspaceIdVolumes", "summary": "Attach a shared volume to a workspace at mount_path (ro or rw)", "tags": [ "Volumes" ], "description": "202 with the attachment (state `attaching`) and its `volume_attach` operation; the cell mounts it in the running guest (or records it for the next start when the workspace has no VM) and reports `attached`. The volume must be `available`, of the same organization and of the workspace’s project unless org-shared (409 volume_not_shared). One attachment per (volume, workspace); mount paths may not nest (409 mount_path_conflict); at most 8 per workspace (403 quota_exceeded). Attach/detach share the workspace’s single active lifecycle operation: 409 operation_in_progress while another one runs. Re-attaching an attached volume with the same mount_path/mode returns 200 without a new operation. Supports Idempotency-Key.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "volume_id", "mount_path" ], "properties": { "volume_id": { "type": "string", "format": "uuid", "description": "UUIDv7, lowercase canonical form." }, "mount_path": { "type": "string", "minLength": 2, "maxLength": 255, "description": "Absolute guest path (e.g. /mnt/data); segments of A-Z a-z 0-9 . _ - not starting with \".\"; system directories (/etc, /usr, /proc, /tmp, /var, ...) and nesting with another mount are refused." }, "mode": { "type": "string", "enum": [ "ro", "rw" ], "default": "rw" } }, "additionalProperties": false } } } }, "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "workspace_id", "required": true, "description": "UUIDv7, lowercase canonical form." } ], "security": [ { "apiKey": [] } ], "responses": { "200": { "description": "operation is null only for an idempotent re-attach of an already attached volume (200).", "content": { "application/json": { "schema": { "type": "object", "required": [ "attachment", "operation" ], "properties": { "attachment": { "$ref": "#/components/schemas/VolumeAttachment" }, "operation": { "anyOf": [ { "$ref": "#/components/schemas/Operation" }, { "type": "null" } ] } }, "additionalProperties": false, "description": "operation is null only for an idempotent re-attach of an already attached volume (200)." } } } }, "202": { "description": "operation is null only for an idempotent re-attach of an already attached volume (200).", "content": { "application/json": { "schema": { "type": "object", "required": [ "attachment", "operation" ], "properties": { "attachment": { "$ref": "#/components/schemas/VolumeAttachment" }, "operation": { "anyOf": [ { "$ref": "#/components/schemas/Operation" }, { "type": "null" } ] } }, "additionalProperties": false, "description": "operation is null only for an idempotent re-attach of an already attached volume (200)." } } } }, "4XX": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "examples": { "not_found": { "$ref": "#/components/examples/not_found" }, "rate_limited": { "$ref": "#/components/examples/rate_limited" }, "validation_failed": { "$ref": "#/components/examples/validation_failed" } } } } }, "5XX": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "examples": { "not_found": { "$ref": "#/components/examples/not_found" }, "rate_limited": { "$ref": "#/components/examples/rate_limited" }, "validation_failed": { "$ref": "#/components/examples/validation_failed" } } } } } } } }, "/v1/workspaces/{workspace_id}/volumes/{volume_id}": { "delete": { "operationId": "deleteV1WorkspacesWorkspaceIdVolumesVolumeId", "summary": "Detach a shared volume from a workspace", "tags": [ "Volumes" ], "description": "202 with the attachment (state `detaching`) and its `volume_detach` operation; the cell unmounts it (the guest sees I/O errors on the path afterwards, never stale writes) and reports `detached`. Idempotent while detaching. 404 when the volume is not attached. 409 operation_in_progress while another lifecycle operation of the workspace runs. Supports Idempotency-Key.", "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "workspace_id", "required": true, "description": "UUIDv7, lowercase canonical form." }, { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "volume_id", "required": true, "description": "UUIDv7, lowercase canonical form." } ], "security": [ { "apiKey": [] } ], "responses": { "202": { "description": "operation is null only for an idempotent re-attach of an already attached volume (200).", "content": { "application/json": { "schema": { "type": "object", "required": [ "attachment", "operation" ], "properties": { "attachment": { "$ref": "#/components/schemas/VolumeAttachment" }, "operation": { "anyOf": [ { "$ref": "#/components/schemas/Operation" }, { "type": "null" } ] } }, "additionalProperties": false, "description": "operation is null only for an idempotent re-attach of an already attached volume (200)." } } } }, "4XX": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "examples": { "not_found": { "$ref": "#/components/examples/not_found" }, "rate_limited": { "$ref": "#/components/examples/rate_limited" }, "validation_failed": { "$ref": "#/components/examples/validation_failed" } } } } }, "5XX": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "examples": { "not_found": { "$ref": "#/components/examples/not_found" }, "rate_limited": { "$ref": "#/components/examples/rate_limited" }, "validation_failed": { "$ref": "#/components/examples/validation_failed" } } } } } } } }, "/v1/organizations/{organization_id}/templates": { "get": { "operationId": "getV1OrganizationsOrganizationIdTemplates", "summary": "List the templates an organization can use (platform + its own), with the version `open` picks", "tags": [ "Templates" ], "description": "Archived templates only with include_archived=true. Ordered by id; cursor pagination.", "parameters": [ { "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 }, "in": "query", "name": "limit", "required": false }, { "schema": { "type": "string", "maxLength": 200 }, "in": "query", "name": "cursor", "required": false }, { "schema": { "type": "boolean", "default": false }, "in": "query", "name": "include_archived", "required": false, "description": "Include archived templates and versions." }, { "schema": { "type": "string", "enum": [ "platform", "organization" ] }, "in": "query", "name": "owner", "required": false }, { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "organization_id", "required": true, "description": "UUIDv7, lowercase canonical form." } ], "security": [ { "apiKey": [] } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "next_cursor" ], "properties": { "data": { "type": "array", "items": { "type": "object", "required": [ "id", "slug", "name", "owner", "organization_id", "created_at", "archived_at", "shadowed_by_organization_template", "defaults", "open_version", "draft", "update_policy", "category" ], "properties": { "id": { "type": "string", "format": "uuid", "description": "UUIDv7, lowercase canonical form." }, "slug": { "type": "string" }, "name": { "type": "string" }, "owner": { "type": "string", "enum": [ "platform", "organization" ] }, "organization_id": { "anyOf": [ { "type": "string", "format": "uuid", "description": "UUIDv7, lowercase canonical form." }, { "type": "null" } ] }, "created_at": { "type": "string", "format": "date-time", "description": "RFC 3339 UTC timestamp with Z." }, "archived_at": { "anyOf": [ { "type": "string", "format": "date-time", "description": "RFC 3339 UTC timestamp with Z." }, { "type": "null" } ] }, "shadowed_by_organization_template": { "type": "boolean", "description": "Platform template whose slug the caller’s organization template currently wins for `open` (resolution prefers the organization’s published version)." }, "defaults": { "type": "object", "required": [ "memory_mib", "idle_policy" ], "properties": { "memory_mib": { "anyOf": [ { "type": "integer", "description": "Memory of a new start without caps.memory_mib (overrides the version’s default_caps.memory_mib_base)." }, { "type": "null" } ] }, "idle_policy": { "anyOf": [ { "type": "string", "description": "Idle policy of a workspace that sets none: adaptive, never or fixed:." }, { "type": "null" } ] } }, "additionalProperties": false, "description": "Mutable template-level defaults (versions are immutable). Null fields fall back to the version and platform defaults." }, "open_version": { "anyOf": [ { "type": "object", "required": [ "id", "version", "state", "architecture", "artifact_sha256", "description", "created_at", "published_at", "archived_at", "is_open_version", "caps", "default_caps", "effective_ceilings", "plan_clamped", "compatibility", "installed_tools", "build_id", "publishable", "manifest_schema", "disk_layouts", "source", "base", "defaults", "settings", "files", "rootfs_bytes", "chain", "storage" ], "properties": { "id": { "type": "string", "format": "uuid", "description": "UUIDv7, lowercase canonical form." }, "version": { "type": "integer" }, "state": { "type": "string", "enum": [ "unpublished", "published", "archived" ] }, "architecture": { "type": "string" }, "artifact_sha256": { "type": "string", "description": "SHA-256 of the version manifest (its immutable identity)." }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "created_at": { "type": "string", "format": "date-time", "description": "RFC 3339 UTC timestamp with Z." }, "published_at": { "anyOf": [ { "type": "string", "format": "date-time", "description": "RFC 3339 UTC timestamp with Z." }, { "type": "null" } ] }, "archived_at": { "anyOf": [ { "type": "string", "format": "date-time", "description": "RFC 3339 UTC timestamp with Z." }, { "type": "null" } ] }, "is_open_version": { "type": "boolean", "description": "The version `open` picks for a new workspace of this template (latest published, not archived)." }, "caps": { "type": "object", "required": [ "cpu_millis_max", "memory_mib_max", "disk_gib_max" ], "properties": { "cpu_millis_max": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "memory_mib_max": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "disk_gib_max": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] } }, "additionalProperties": false, "description": "Template limits (null = the template adds no limit)." }, "default_caps": { "anyOf": [ { "type": "object", "required": [ "cpu_millis_ceiling", "memory_mib_base", "memory_mib_ceiling", "disk_gib" ], "properties": { "cpu_millis_ceiling": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "memory_mib_base": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "memory_mib_ceiling": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "disk_gib": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] } }, "additionalProperties": false, "description": "Defaults from the manifest (memory_mib_base = boot memory of a new workspace)." }, { "type": "null" } ] }, "effective_ceilings": { "anyOf": [ { "type": "object", "required": [ "cpu_millis", "memory_mib", "disk_gib", "sources" ], "properties": { "cpu_millis": { "type": "integer" }, "memory_mib": { "type": "integer" }, "disk_gib": { "type": "integer" }, "sources": { "type": "object", "required": [ "cpu_millis", "memory_mib", "disk_gib" ], "properties": { "cpu_millis": { "type": "string", "enum": [ "template", "user", "plan" ] }, "memory_mib": { "type": "string", "enum": [ "template", "user", "plan" ] }, "disk_gib": { "type": "string", "enum": [ "template", "user", "plan" ] } }, "additionalProperties": false } }, "additionalProperties": false, "description": "Ceilings a new workspace without user caps would get now: min(template limit, plan limit)." }, { "type": "null" } ] }, "plan_clamped": { "type": "object", "properties": { "cpu_millis": { "type": "integer" }, "memory_mib": { "type": "integer" }, "disk_gib": { "type": "integer" } }, "additionalProperties": false, "description": "Resources where the caller’s plan is below what the template states (limit, else manifest default ceiling), with the plan value. Empty = no clamping." }, "compatibility": { "type": "object", "required": [ "manifest_schema", "architecture", "kernel", "guest_agent", "rootfs", "firecracker", "runtime_class" ], "properties": { "manifest_schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "architecture": { "type": "string" }, "kernel": { "anyOf": [ { "type": "object", "required": [ "release", "sha256" ], "properties": { "release": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "sha256": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "additionalProperties": false }, { "type": "null" } ] }, "guest_agent": { "anyOf": [ { "type": "object", "required": [ "version", "sha256", "vsock_port" ], "properties": { "version": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "sha256": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "vsock_port": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] } }, "additionalProperties": false }, { "type": "null" } ] }, "rootfs": { "anyOf": [ { "type": "object", "required": [ "format", "bytes", "sha256" ], "properties": { "format": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "bytes": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "sha256": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "additionalProperties": false }, { "type": "null" } ] }, "firecracker": { "anyOf": [ { "type": "string", "description": "Required Firecracker version when the manifest states one." }, { "type": "null" } ] }, "runtime_class": { "anyOf": [ { "type": "string", "description": "Runtime class when the manifest states one." }, { "type": "null" } ] } }, "additionalProperties": false, "description": "Runtime requirements exactly as recorded in the version manifest (null = not recorded)." }, "installed_tools": { "type": "array", "items": { "type": "object", "required": [ "name", "version" ], "properties": { "name": { "type": "string" }, "version": { "type": "string" } }, "additionalProperties": false }, "description": "Tool versions recorded in the manifest at build time." }, "build_id": { "anyOf": [ { "type": "string", "format": "uuid", "description": "UUIDv7, lowercase canonical form." }, { "type": "null" } ] }, "publishable": { "type": "boolean", "description": "Unpublished, not archived and produced by a build whose scan and compatibility checks passed (a registered `published` build, or a legacy `succeeded` one)." }, "manifest_schema": { "anyOf": [ { "type": "string", "description": "shardflux.template.v1 or shardflux.template.v2." }, { "type": "null" } ] }, "disk_layouts": { "type": "array", "items": { "$ref": "#/components/schemas/DiskLayout" }, "description": "Layouts a new workspace of this version may use (a manifest without the field: legacy only)." }, "source": { "anyOf": [ { "$ref": "#/components/schemas/TemplateSource" }, { "type": "null" } ] }, "base": { "anyOf": [ { "type": "object", "required": [ "name", "version", "manifest_sha256", "rootfs_sha256" ], "properties": { "name": { "type": "string" }, "version": { "type": "string" }, "manifest_sha256": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "rootfs_sha256": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "additionalProperties": false, "description": "Lineage: the version this one was built on (manifest `base`); null for platform roots." }, { "type": "null" } ] }, "defaults": { "$ref": "#/components/schemas/TemplateDefaults" }, "settings": { "$ref": "#/components/schemas/TemplateSettings" }, "files": { "$ref": "#/components/schemas/TemplateFilesSummary" }, "rootfs_bytes": { "anyOf": [ { "type": "integer", "description": "The root image size (for layers versions: the platform base’s)." }, { "type": "null" } ] }, "chain": { "type": "array", "items": { "type": "object", "required": [ "layer_id", "bytes", "introduced_in_version" ], "properties": { "layer_id": { "type": "string", "format": "uuid", "description": "UUIDv7, lowercase canonical form." }, "bytes": { "type": "integer" }, "introduced_in_version": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] } }, "additionalProperties": false }, "description": "The org layers of this version’s chain, bottom to top (empty for images)." }, "storage": { "$ref": "#/components/schemas/TemplateStorage" } }, "additionalProperties": false }, { "type": "null" } ] }, "draft": { "anyOf": [ { "type": "object", "required": [ "workspace_id", "workspace_key", "observed_state", "base_version", "created_at" ], "properties": { "workspace_id": { "type": "string", "format": "uuid", "description": "UUIDv7, lowercase canonical form." }, "workspace_key": { "type": "string" }, "observed_state": { "type": "string" }, "base_version": { "type": "object", "required": [ "id", "template_id", "slug", "version" ], "properties": { "id": { "type": "string", "format": "uuid", "description": "UUIDv7, lowercase canonical form." }, "template_id": { "type": "string", "format": "uuid", "description": "UUIDv7, lowercase canonical form." }, "slug": { "type": "string" }, "version": { "type": "integer" } }, "additionalProperties": false, "description": "The draft base: the template version the draft (and its test instances) run on." }, "created_at": { "type": "string", "format": "date-time", "description": "RFC 3339 UTC timestamp with Z." } }, "additionalProperties": false, "description": "The template’s live draft (GET …/templates/{slug}/draft for the full view); null when there is none." }, { "type": "null" } ] }, "update_policy": { "$ref": "#/components/schemas/UpdatePolicy" }, "category": { "anyOf": [ { "type": "string", "enum": [ "os", "stack" ], "description": "Platform templates: os (a bare operating system) or stack (preinstalled tools). Organization templates: null." }, { "type": "null" } ] } }, "additionalProperties": false } }, "next_cursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "additionalProperties": false } } } }, "4XX": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "examples": { "not_found": { "$ref": "#/components/examples/not_found" }, "rate_limited": { "$ref": "#/components/examples/rate_limited" }, "validation_failed": { "$ref": "#/components/examples/validation_failed" } } } } }, "5XX": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "examples": { "not_found": { "$ref": "#/components/examples/not_found" }, "rate_limited": { "$ref": "#/components/examples/rate_limited" }, "validation_failed": { "$ref": "#/components/examples/validation_failed" } } } } } } } }, "/v1/organizations/{organization_id}/templates/{slug}": { "get": { "operationId": "getV1OrganizationsOrganizationIdTemplatesSlug", "summary": "Get a template by slug with its versions, compatibility, caps, installed tools and plan clamping", "tags": [ "Templates" ], "description": "The organization’s own template shadows a platform template of the same slug (like `open`); `open_resolves_to` is what `open` would use now. Unpublished versions appear only for owners/admins of the owning organization. 404 outside the organization.", "parameters": [ { "schema": { "type": "boolean", "default": false }, "in": "query", "name": "include_archived", "required": false, "description": "Include archived templates and versions." }, { "schema": { "type": "string", "enum": [ "platform", "organization" ] }, "in": "query", "name": "owner", "required": false, "description": "Pick the platform template even when an organization template shadows its slug." }, { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "organization_id", "required": true, "description": "UUIDv7, lowercase canonical form." }, { "schema": { "type": "string", "minLength": 1, "maxLength": 100, "pattern": "^[a-z0-9](?:[a-z0-9._-]{0,98}[a-z0-9])?$" }, "in": "path", "name": "slug", "required": true } ], "security": [ { "apiKey": [] } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "required": [ "id", "slug", "name", "owner", "organization_id", "created_at", "archived_at", "shadowed_by_organization_template", "defaults", "open_version", "draft", "update_policy", "category", "plan", "open_resolves_to", "versions", "versions_truncated" ], "properties": { "id": { "type": "string", "format": "uuid", "description": "UUIDv7, lowercase canonical form." }, "slug": { "type": "string" }, "name": { "type": "string" }, "owner": { "type": "string", "enum": [ "platform", "organization" ] }, "organization_id": { "anyOf": [ { "type": "string", "format": "uuid", "description": "UUIDv7, lowercase canonical form." }, { "type": "null" } ] }, "created_at": { "type": "string", "format": "date-time", "description": "RFC 3339 UTC timestamp with Z." }, "archived_at": { "anyOf": [ { "type": "string", "format": "date-time", "description": "RFC 3339 UTC timestamp with Z." }, { "type": "null" } ] }, "shadowed_by_organization_template": { "type": "boolean", "description": "Platform template whose slug the caller’s organization template currently wins for `open` (resolution prefers the organization’s published version)." }, "defaults": { "type": "object", "required": [ "memory_mib", "idle_policy" ], "properties": { "memory_mib": { "anyOf": [ { "type": "integer", "description": "Memory of a new start without caps.memory_mib (overrides the version’s default_caps.memory_mib_base)." }, { "type": "null" } ] }, "idle_policy": { "anyOf": [ { "type": "string", "description": "Idle policy of a workspace that sets none: adaptive, never or fixed:." }, { "type": "null" } ] } }, "additionalProperties": false, "description": "Mutable template-level defaults (versions are immutable). Null fields fall back to the version and platform defaults." }, "open_version": { "anyOf": [ { "type": "object", "required": [ "id", "version", "state", "architecture", "artifact_sha256", "description", "created_at", "published_at", "archived_at", "is_open_version", "caps", "default_caps", "effective_ceilings", "plan_clamped", "compatibility", "installed_tools", "build_id", "publishable", "manifest_schema", "disk_layouts", "source", "base", "defaults", "settings", "files", "rootfs_bytes", "chain", "storage" ], "properties": { "id": { "type": "string", "format": "uuid", "description": "UUIDv7, lowercase canonical form." }, "version": { "type": "integer" }, "state": { "type": "string", "enum": [ "unpublished", "published", "archived" ] }, "architecture": { "type": "string" }, "artifact_sha256": { "type": "string", "description": "SHA-256 of the version manifest (its immutable identity)." }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "created_at": { "type": "string", "format": "date-time", "description": "RFC 3339 UTC timestamp with Z." }, "published_at": { "anyOf": [ { "type": "string", "format": "date-time", "description": "RFC 3339 UTC timestamp with Z." }, { "type": "null" } ] }, "archived_at": { "anyOf": [ { "type": "string", "format": "date-time", "description": "RFC 3339 UTC timestamp with Z." }, { "type": "null" } ] }, "is_open_version": { "type": "boolean", "description": "The version `open` picks for a new workspace of this template (latest published, not archived)." }, "caps": { "type": "object", "required": [ "cpu_millis_max", "memory_mib_max", "disk_gib_max" ], "properties": { "cpu_millis_max": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "memory_mib_max": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "disk_gib_max": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] } }, "additionalProperties": false, "description": "Template limits (null = the template adds no limit)." }, "default_caps": { "anyOf": [ { "type": "object", "required": [ "cpu_millis_ceiling", "memory_mib_base", "memory_mib_ceiling", "disk_gib" ], "properties": { "cpu_millis_ceiling": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "memory_mib_base": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "memory_mib_ceiling": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "disk_gib": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] } }, "additionalProperties": false, "description": "Defaults from the manifest (memory_mib_base = boot memory of a new workspace)." }, { "type": "null" } ] }, "effective_ceilings": { "anyOf": [ { "type": "object", "required": [ "cpu_millis", "memory_mib", "disk_gib", "sources" ], "properties": { "cpu_millis": { "type": "integer" }, "memory_mib": { "type": "integer" }, "disk_gib": { "type": "integer" }, "sources": { "type": "object", "required": [ "cpu_millis", "memory_mib", "disk_gib" ], "properties": { "cpu_millis": { "type": "string", "enum": [ "template", "user", "plan" ] }, "memory_mib": { "type": "string", "enum": [ "template", "user", "plan" ] }, "disk_gib": { "type": "string", "enum": [ "template", "user", "plan" ] } }, "additionalProperties": false } }, "additionalProperties": false, "description": "Ceilings a new workspace without user caps would get now: min(template limit, plan limit)." }, { "type": "null" } ] }, "plan_clamped": { "type": "object", "properties": { "cpu_millis": { "type": "integer" }, "memory_mib": { "type": "integer" }, "disk_gib": { "type": "integer" } }, "additionalProperties": false, "description": "Resources where the caller’s plan is below what the template states (limit, else manifest default ceiling), with the plan value. Empty = no clamping." }, "compatibility": { "type": "object", "required": [ "manifest_schema", "architecture", "kernel", "guest_agent", "rootfs", "firecracker", "runtime_class" ], "properties": { "manifest_schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "architecture": { "type": "string" }, "kernel": { "anyOf": [ { "type": "object", "required": [ "release", "sha256" ], "properties": { "release": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "sha256": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "additionalProperties": false }, { "type": "null" } ] }, "guest_agent": { "anyOf": [ { "type": "object", "required": [ "version", "sha256", "vsock_port" ], "properties": { "version": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "sha256": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "vsock_port": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] } }, "additionalProperties": false }, { "type": "null" } ] }, "rootfs": { "anyOf": [ { "type": "object", "required": [ "format", "bytes", "sha256" ], "properties": { "format": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "bytes": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "sha256": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "additionalProperties": false }, { "type": "null" } ] }, "firecracker": { "anyOf": [ { "type": "string", "description": "Required Firecracker version when the manifest states one." }, { "type": "null" } ] }, "runtime_class": { "anyOf": [ { "type": "string", "description": "Runtime class when the manifest states one." }, { "type": "null" } ] } }, "additionalProperties": false, "description": "Runtime requirements exactly as recorded in the version manifest (null = not recorded)." }, "installed_tools": { "type": "array", "items": { "type": "object", "required": [ "name", "version" ], "properties": { "name": { "type": "string" }, "version": { "type": "string" } }, "additionalProperties": false }, "description": "Tool versions recorded in the manifest at build time." }, "build_id": { "anyOf": [ { "type": "string", "format": "uuid", "description": "UUIDv7, lowercase canonical form." }, { "type": "null" } ] }, "publishable": { "type": "boolean", "description": "Unpublished, not archived and produced by a build whose scan and compatibility checks passed (a registered `published` build, or a legacy `succeeded` one)." }, "manifest_schema": { "anyOf": [ { "type": "string", "description": "shardflux.template.v1 or shardflux.template.v2." }, { "type": "null" } ] }, "disk_layouts": { "type": "array", "items": { "$ref": "#/components/schemas/DiskLayout" }, "description": "Layouts a new workspace of this version may use (a manifest without the field: legacy only)." }, "source": { "anyOf": [ { "$ref": "#/components/schemas/TemplateSource" }, { "type": "null" } ] }, "base": { "anyOf": [ { "type": "object", "required": [ "name", "version", "manifest_sha256", "rootfs_sha256" ], "properties": { "name": { "type": "string" }, "version": { "type": "string" }, "manifest_sha256": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "rootfs_sha256": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "additionalProperties": false, "description": "Lineage: the version this one was built on (manifest `base`); null for platform roots." }, { "type": "null" } ] }, "defaults": { "$ref": "#/components/schemas/TemplateDefaults" }, "settings": { "$ref": "#/components/schemas/TemplateSettings" }, "files": { "$ref": "#/components/schemas/TemplateFilesSummary" }, "rootfs_bytes": { "anyOf": [ { "type": "integer", "description": "The root image size (for layers versions: the platform base’s)." }, { "type": "null" } ] }, "chain": { "type": "array", "items": { "type": "object", "required": [ "layer_id", "bytes", "introduced_in_version" ], "properties": { "layer_id": { "type": "string", "format": "uuid", "description": "UUIDv7, lowercase canonical form." }, "bytes": { "type": "integer" }, "introduced_in_version": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] } }, "additionalProperties": false }, "description": "The org layers of this version’s chain, bottom to top (empty for images)." }, "storage": { "$ref": "#/components/schemas/TemplateStorage" } }, "additionalProperties": false }, { "type": "null" } ] }, "draft": { "anyOf": [ { "type": "object", "required": [ "workspace_id", "workspace_key", "observed_state", "base_version", "created_at" ], "properties": { "workspace_id": { "type": "string", "format": "uuid", "description": "UUIDv7, lowercase canonical form." }, "workspace_key": { "type": "string" }, "observed_state": { "type": "string" }, "base_version": { "type": "object", "required": [ "id", "template_id", "slug", "version" ], "properties": { "id": { "type": "string", "format": "uuid", "description": "UUIDv7, lowercase canonical form." }, "template_id": { "type": "string", "format": "uuid", "description": "UUIDv7, lowercase canonical form." }, "slug": { "type": "string" }, "version": { "type": "integer" } }, "additionalProperties": false, "description": "The draft base: the template version the draft (and its test instances) run on." }, "created_at": { "type": "string", "format": "date-time", "description": "RFC 3339 UTC timestamp with Z." } }, "additionalProperties": false, "description": "The template’s live draft (GET …/templates/{slug}/draft for the full view); null when there is none." }, { "type": "null" } ] }, "update_policy": { "$ref": "#/components/schemas/UpdatePolicy" }, "category": { "anyOf": [ { "type": "string", "enum": [ "os", "stack" ], "description": "Platform templates: os (a bare operating system) or stack (preinstalled tools). Organization templates: null." }, { "type": "null" } ] }, "plan": { "anyOf": [ { "type": "object", "required": [ "plan_key", "catalog_version" ], "properties": { "plan_key": { "type": "string" }, "catalog_version": { "type": "string" } }, "additionalProperties": false }, { "type": "null" } ] }, "open_resolves_to": { "anyOf": [ { "type": "object", "required": [ "template_id", "template_version_id", "version", "owner" ], "properties": { "template_id": { "type": "string", "format": "uuid", "description": "UUIDv7, lowercase canonical form." }, "template_version_id": { "type": "string", "format": "uuid", "description": "UUIDv7, lowercase canonical form." }, "version": { "type": "integer" }, "owner": { "type": "string", "enum": [ "platform", "organization" ] } }, "additionalProperties": false, "description": "What `open({template: slug})` resolves to for this organization right now (may be the other template of the same slug)." }, { "type": "null" } ] }, "versions": { "type": "array", "items": { "type": "object", "required": [ "id", "version", "state", "architecture", "artifact_sha256", "description", "created_at", "published_at", "archived_at", "is_open_version", "caps", "default_caps", "effective_ceilings", "plan_clamped", "compatibility", "installed_tools", "build_id", "publishable", "manifest_schema", "disk_layouts", "source", "base", "defaults", "settings", "files", "rootfs_bytes", "chain", "storage" ], "properties": { "id": { "type": "string", "format": "uuid", "description": "UUIDv7, lowercase canonical form." }, "version": { "type": "integer" }, "state": { "type": "string", "enum": [ "unpublished", "published", "archived" ] }, "architecture": { "type": "string" }, "artifact_sha256": { "type": "string", "description": "SHA-256 of the version manifest (its immutable identity)." }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "created_at": { "type": "string", "format": "date-time", "description": "RFC 3339 UTC timestamp with Z." }, "published_at": { "anyOf": [ { "type": "string", "format": "date-time", "description": "RFC 3339 UTC timestamp with Z." }, { "type": "null" } ] }, "archived_at": { "anyOf": [ { "type": "string", "format": "date-time", "description": "RFC 3339 UTC timestamp with Z." }, { "type": "null" } ] }, "is_open_version": { "type": "boolean", "description": "The version `open` picks for a new workspace of this template (latest published, not archived)." }, "caps": { "type": "object", "required": [ "cpu_millis_max", "memory_mib_max", "disk_gib_max" ], "properties": { "cpu_millis_max": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "memory_mib_max": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "disk_gib_max": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] } }, "additionalProperties": false, "description": "Template limits (null = the template adds no limit)." }, "default_caps": { "anyOf": [ { "type": "object", "required": [ "cpu_millis_ceiling", "memory_mib_base", "memory_mib_ceiling", "disk_gib" ], "properties": { "cpu_millis_ceiling": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "memory_mib_base": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "memory_mib_ceiling": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "disk_gib": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] } }, "additionalProperties": false, "description": "Defaults from the manifest (memory_mib_base = boot memory of a new workspace)." }, { "type": "null" } ] }, "effective_ceilings": { "anyOf": [ { "type": "object", "required": [ "cpu_millis", "memory_mib", "disk_gib", "sources" ], "properties": { "cpu_millis": { "type": "integer" }, "memory_mib": { "type": "integer" }, "disk_gib": { "type": "integer" }, "sources": { "type": "object", "required": [ "cpu_millis", "memory_mib", "disk_gib" ], "properties": { "cpu_millis": { "type": "string", "enum": [ "template", "user", "plan" ] }, "memory_mib": { "type": "string", "enum": [ "template", "user", "plan" ] }, "disk_gib": { "type": "string", "enum": [ "template", "user", "plan" ] } }, "additionalProperties": false } }, "additionalProperties": false, "description": "Ceilings a new workspace without user caps would get now: min(template limit, plan limit)." }, { "type": "null" } ] }, "plan_clamped": { "type": "object", "properties": { "cpu_millis": { "type": "integer" }, "memory_mib": { "type": "integer" }, "disk_gib": { "type": "integer" } }, "additionalProperties": false, "description": "Resources where the caller’s plan is below what the template states (limit, else manifest default ceiling), with the plan value. Empty = no clamping." }, "compatibility": { "type": "object", "required": [ "manifest_schema", "architecture", "kernel", "guest_agent", "rootfs", "firecracker", "runtime_class" ], "properties": { "manifest_schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "architecture": { "type": "string" }, "kernel": { "anyOf": [ { "type": "object", "required": [ "release", "sha256" ], "properties": { "release": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "sha256": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "additionalProperties": false }, { "type": "null" } ] }, "guest_agent": { "anyOf": [ { "type": "object", "required": [ "version", "sha256", "vsock_port" ], "properties": { "version": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "sha256": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "vsock_port": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] } }, "additionalProperties": false }, { "type": "null" } ] }, "rootfs": { "anyOf": [ { "type": "object", "required": [ "format", "bytes", "sha256" ], "properties": { "format": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "bytes": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "sha256": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "additionalProperties": false }, { "type": "null" } ] }, "firecracker": { "anyOf": [ { "type": "string", "description": "Required Firecracker version when the manifest states one." }, { "type": "null" } ] }, "runtime_class": { "anyOf": [ { "type": "string", "description": "Runtime class when the manifest states one." }, { "type": "null" } ] } }, "additionalProperties": false, "description": "Runtime requirements exactly as recorded in the version manifest (null = not recorded)." }, "installed_tools": { "type": "array", "items": { "type": "object", "required": [ "name", "version" ], "properties": { "name": { "type": "string" }, "version": { "type": "string" } }, "additionalProperties": false }, "description": "Tool versions recorded in the manifest at build time." }, "build_id": { "anyOf": [ { "type": "string", "format": "uuid", "description": "UUIDv7, lowercase canonical form." }, { "type": "null" } ] }, "publishable": { "type": "boolean", "description": "Unpublished, not archived and produced by a build whose scan and compatibility checks passed (a registered `published` build, or a legacy `succeeded` one)." }, "manifest_schema": { "anyOf": [ { "type": "string", "description": "shardflux.template.v1 or shardflux.template.v2." }, { "type": "null" } ] }, "disk_layouts": { "type": "array", "items": { "$ref": "#/components/schemas/DiskLayout" }, "description": "Layouts a new workspace of this version may use (a manifest without the field: legacy only)." }, "source": { "anyOf": [ { "$ref": "#/components/schemas/TemplateSource" }, { "type": "null" } ] }, "base": { "anyOf": [ { "type": "object", "required": [ "name", "version", "manifest_sha256", "rootfs_sha256" ], "properties": { "name": { "type": "string" }, "version": { "type": "string" }, "manifest_sha256": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "rootfs_sha256": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "additionalProperties": false, "description": "Lineage: the version this one was built on (manifest `base`); null for platform roots." }, { "type": "null" } ] }, "defaults": { "$ref": "#/components/schemas/TemplateDefaults" }, "settings": { "$ref": "#/components/schemas/TemplateSettings" }, "files": { "$ref": "#/components/schemas/TemplateFilesSummary" }, "rootfs_bytes": { "anyOf": [ { "type": "integer", "description": "The root image size (for layers versions: the platform base’s)." }, { "type": "null" } ] }, "chain": { "type": "array", "items": { "type": "object", "required": [ "layer_id", "bytes", "introduced_in_version" ], "properties": { "layer_id": { "type": "string", "format": "uuid", "description": "UUIDv7, lowercase canonical form." }, "bytes": { "type": "integer" }, "introduced_in_version": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] } }, "additionalProperties": false }, "description": "The org layers of this version’s chain, bottom to top (empty for images)." }, "storage": { "$ref": "#/components/schemas/TemplateStorage" } }, "additionalProperties": false }, "description": "Newest first. Unpublished versions only for owners/admins of the owning organization; archived only with include_archived." }, "versions_truncated": { "type": "boolean" } }, "additionalProperties": false } } } }, "4XX": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "examples": { "not_found": { "$ref": "#/components/examples/not_found" }, "rate_limited": { "$ref": "#/components/examples/rate_limited" }, "validation_failed": { "$ref": "#/components/examples/validation_failed" } } } } }, "5XX": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "examples": { "not_found": { "$ref": "#/components/examples/not_found" }, "rate_limited": { "$ref": "#/components/examples/rate_limited" }, "validation_failed": { "$ref": "#/components/examples/validation_failed" } } } } } } } }, "/v1/templates": { "get": { "operationId": "getV1Templates", "summary": "List the templates an organization can use (platform + its own), with the version `open` picks (the API key’s organization)", "tags": [ "Templates" ], "description": "Archived templates only with include_archived=true. Ordered by id; cursor pagination.", "parameters": [ { "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 }, "in": "query", "name": "limit", "required": false }, { "schema": { "type": "string", "maxLength": 200 }, "in": "query", "name": "cursor", "required": false }, { "schema": { "type": "boolean", "default": false }, "in": "query", "name": "include_archived", "required": false, "description": "Include archived templates and versions." }, { "schema": { "type": "string", "enum": [ "platform", "organization" ] }, "in": "query", "name": "owner", "required": false } ], "security": [ { "apiKey": [] } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "next_cursor" ], "properties": { "data": { "type": "array", "items": { "type": "object", "required": [ "id", "slug", "name", "owner", "organization_id", "created_at", "archived_at", "shadowed_by_organization_template", "defaults", "open_version", "draft", "update_policy", "category" ], "properties": { "id": { "type": "string", "format": "uuid", "description": "UUIDv7, lowercase canonical form." }, "slug": { "type": "string" }, "name": { "type": "string" }, "owner": { "type": "string", "enum": [ "platform", "organization" ] }, "organization_id": { "anyOf": [ { "type": "string", "format": "uuid", "description": "UUIDv7, lowercase canonical form." }, { "type": "null" } ] }, "created_at": { "type": "string", "format": "date-time", "description": "RFC 3339 UTC timestamp with Z." }, "archived_at": { "anyOf": [ { "type": "string", "format": "date-time", "description": "RFC 3339 UTC timestamp with Z." }, { "type": "null" } ] }, "shadowed_by_organization_template": { "type": "boolean", "description": "Platform template whose slug the caller’s organization template currently wins for `open` (resolution prefers the organization’s published version)." }, "defaults": { "type": "object", "required": [ "memory_mib", "idle_policy" ], "properties": { "memory_mib": { "anyOf": [ { "type": "integer", "description": "Memory of a new start without caps.memory_mib (overrides the version’s default_caps.memory_mib_base)." }, { "type": "null" } ] }, "idle_policy": { "anyOf": [ { "type": "string", "description": "Idle policy of a workspace that sets none: adaptive, never or fixed:." }, { "type": "null" } ] } }, "additionalProperties": false, "description": "Mutable template-level defaults (versions are immutable). Null fields fall back to the version and platform defaults." }, "open_version": { "anyOf": [ { "type": "object", "required": [ "id", "version", "state", "architecture", "artifact_sha256", "description", "created_at", "published_at", "archived_at", "is_open_version", "caps", "default_caps", "effective_ceilings", "plan_clamped", "compatibility", "installed_tools", "build_id", "publishable", "manifest_schema", "disk_layouts", "source", "base", "defaults", "settings", "files", "rootfs_bytes", "chain", "storage" ], "properties": { "id": { "type": "string", "format": "uuid", "description": "UUIDv7, lowercase canonical form." }, "version": { "type": "integer" }, "state": { "type": "string", "enum": [ "unpublished", "published", "archived" ] }, "architecture": { "type": "string" }, "artifact_sha256": { "type": "string", "description": "SHA-256 of the version manifest (its immutable identity)." }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "created_at": { "type": "string", "format": "date-time", "description": "RFC 3339 UTC timestamp with Z." }, "published_at": { "anyOf": [ { "type": "string", "format": "date-time", "description": "RFC 3339 UTC timestamp with Z." }, { "type": "null" } ] }, "archived_at": { "anyOf": [ { "type": "string", "format": "date-time", "description": "RFC 3339 UTC timestamp with Z." }, { "type": "null" } ] }, "is_open_version": { "type": "boolean", "description": "The version `open` picks for a new workspace of this template (latest published, not archived)." }, "caps": { "type": "object", "required": [ "cpu_millis_max", "memory_mib_max", "disk_gib_max" ], "properties": { "cpu_millis_max": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "memory_mib_max": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "disk_gib_max": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] } }, "additionalProperties": false, "description": "Template limits (null = the template adds no limit)." }, "default_caps": { "anyOf": [ { "type": "object", "required": [ "cpu_millis_ceiling", "memory_mib_base", "memory_mib_ceiling", "disk_gib" ], "properties": { "cpu_millis_ceiling": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "memory_mib_base": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "memory_mib_ceiling": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "disk_gib": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] } }, "additionalProperties": false, "description": "Defaults from the manifest (memory_mib_base = boot memory of a new workspace)." }, { "type": "null" } ] }, "effective_ceilings": { "anyOf": [ { "type": "object", "required": [ "cpu_millis", "memory_mib", "disk_gib", "sources" ], "properties": { "cpu_millis": { "type": "integer" }, "memory_mib": { "type": "integer" }, "disk_gib": { "type": "integer" }, "sources": { "type": "object", "required": [ "cpu_millis", "memory_mib", "disk_gib" ], "properties": { "cpu_millis": { "type": "string", "enum": [ "template", "user", "plan" ] }, "memory_mib": { "type": "string", "enum": [ "template", "user", "plan" ] }, "disk_gib": { "type": "string", "enum": [ "template", "user", "plan" ] } }, "additionalProperties": false } }, "additionalProperties": false, "description": "Ceilings a new workspace without user caps would get now: min(template limit, plan limit)." }, { "type": "null" } ] }, "plan_clamped": { "type": "object", "properties": { "cpu_millis": { "type": "integer" }, "memory_mib": { "type": "integer" }, "disk_gib": { "type": "integer" } }, "additionalProperties": false, "description": "Resources where the caller’s plan is below what the template states (limit, else manifest default ceiling), with the plan value. Empty = no clamping." }, "compatibility": { "type": "object", "required": [ "manifest_schema", "architecture", "kernel", "guest_agent", "rootfs", "firecracker", "runtime_class" ], "properties": { "manifest_schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "architecture": { "type": "string" }, "kernel": { "anyOf": [ { "type": "object", "required": [ "release", "sha256" ], "properties": { "release": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "sha256": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "additionalProperties": false }, { "type": "null" } ] }, "guest_agent": { "anyOf": [ { "type": "object", "required": [ "version", "sha256", "vsock_port" ], "properties": { "version": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "sha256": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "vsock_port": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] } }, "additionalProperties": false }, { "type": "null" } ] }, "rootfs": { "anyOf": [ { "type": "object", "required": [ "format", "bytes", "sha256" ], "properties": { "format": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "bytes": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "sha256": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "additionalProperties": false }, { "type": "null" } ] }, "firecracker": { "anyOf": [ { "type": "string", "description": "Required Firecracker version when the manifest states one." }, { "type": "null" } ] }, "runtime_class": { "anyOf": [ { "type": "string", "description": "Runtime class when the manifest states one." }, { "type": "null" } ] } }, "additionalProperties": false, "description": "Runtime requirements exactly as recorded in the version manifest (null = not recorded)." }, "installed_tools": { "type": "array", "items": { "type": "object", "required": [ "name", "version" ], "properties": { "name": { "type": "string" }, "version": { "type": "string" } }, "additionalProperties": false }, "description": "Tool versions recorded in the manifest at build time." }, "build_id": { "anyOf": [ { "type": "string", "format": "uuid", "description": "UUIDv7, lowercase canonical form." }, { "type": "null" } ] }, "publishable": { "type": "boolean", "description": "Unpublished, not archived and produced by a build whose scan and compatibility checks passed (a registered `published` build, or a legacy `succeeded` one)." }, "manifest_schema": { "anyOf": [ { "type": "string", "description": "shardflux.template.v1 or shardflux.template.v2." }, { "type": "null" } ] }, "disk_layouts": { "type": "array", "items": { "$ref": "#/components/schemas/DiskLayout" }, "description": "Layouts a new workspace of this version may use (a manifest without the field: legacy only)." }, "source": { "anyOf": [ { "$ref": "#/components/schemas/TemplateSource" }, { "type": "null" } ] }, "base": { "anyOf": [ { "type": "object", "required": [ "name", "version", "manifest_sha256", "rootfs_sha256" ], "properties": { "name": { "type": "string" }, "version": { "type": "string" }, "manifest_sha256": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "rootfs_sha256": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "additionalProperties": false, "description": "Lineage: the version this one was built on (manifest `base`); null for platform roots." }, { "type": "null" } ] }, "defaults": { "$ref": "#/components/schemas/TemplateDefaults" }, "settings": { "$ref": "#/components/schemas/TemplateSettings" }, "files": { "$ref": "#/components/schemas/TemplateFilesSummary" }, "rootfs_bytes": { "anyOf": [ { "type": "integer", "description": "The root image size (for layers versions: the platform base’s)." }, { "type": "null" } ] }, "chain": { "type": "array", "items": { "type": "object", "required": [ "layer_id", "bytes", "introduced_in_version" ], "properties": { "layer_id": { "type": "string", "format": "uuid", "description": "UUIDv7, lowercase canonical form." }, "bytes": { "type": "integer" }, "introduced_in_version": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] } }, "additionalProperties": false }, "description": "The org layers of this version’s chain, bottom to top (empty for images)." }, "storage": { "$ref": "#/components/schemas/TemplateStorage" } }, "additionalProperties": false }, { "type": "null" } ] }, "draft": { "anyOf": [ { "type": "object", "required": [ "workspace_id", "workspace_key", "observed_state", "base_version", "created_at" ], "properties": { "workspace_id": { "type": "string", "format": "uuid", "description": "UUIDv7, lowercase canonical form." }, "workspace_key": { "type": "string" }, "observed_state": { "type": "string" }, "base_version": { "type": "object", "required": [ "id", "template_id", "slug", "version" ], "properties": { "id": { "type": "string", "format": "uuid", "description": "UUIDv7, lowercase canonical form." }, "template_id": { "type": "string", "format": "uuid", "description": "UUIDv7, lowercase canonical form." }, "slug": { "type": "string" }, "version": { "type": "integer" } }, "additionalProperties": false, "description": "The draft base: the template version the draft (and its test instances) run on." }, "created_at": { "type": "string", "format": "date-time", "description": "RFC 3339 UTC timestamp with Z." } }, "additionalProperties": false, "description": "The template’s live draft (GET …/templates/{slug}/draft for the full view); null when there is none." }, { "type": "null" } ] }, "update_policy": { "$ref": "#/components/schemas/UpdatePolicy" }, "category": { "anyOf": [ { "type": "string", "enum": [ "os", "stack" ], "description": "Platform templates: os (a bare operating system) or stack (preinstalled tools). Organization templates: null." }, { "type": "null" } ] } }, "additionalProperties": false } }, "next_cursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "additionalProperties": false } } } }, "4XX": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "examples": { "not_found": { "$ref": "#/components/examples/not_found" }, "rate_limited": { "$ref": "#/components/examples/rate_limited" }, "validation_failed": { "$ref": "#/components/examples/validation_failed" } } } } }, "5XX": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "examples": { "not_found": { "$ref": "#/components/examples/not_found" }, "rate_limited": { "$ref": "#/components/examples/rate_limited" }, "validation_failed": { "$ref": "#/components/examples/validation_failed" } } } } } } } }, "/v1/templates/{slug}": { "get": { "operationId": "getV1TemplatesSlug", "summary": "Get a template by slug with its versions, compatibility, caps, installed tools and plan clamping (the API key’s organization)", "tags": [ "Templates" ], "description": "The organization’s own template shadows a platform template of the same slug (like `open`); `open_resolves_to` is what `open` would use now. Unpublished versions appear only for owners/admins of the owning organization. 404 outside the organization.", "parameters": [ { "schema": { "type": "boolean", "default": false }, "in": "query", "name": "include_archived", "required": false, "description": "Include archived templates and versions." }, { "schema": { "type": "string", "enum": [ "platform", "organization" ] }, "in": "query", "name": "owner", "required": false, "description": "Pick the platform template even when an organization template shadows its slug." }, { "schema": { "type": "string", "minLength": 1, "maxLength": 100, "pattern": "^[a-z0-9](?:[a-z0-9._-]{0,98}[a-z0-9])?$" }, "in": "path", "name": "slug", "required": true } ], "security": [ { "apiKey": [] } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "required": [ "id", "slug", "name", "owner", "organization_id", "created_at", "archived_at", "shadowed_by_organization_template", "defaults", "open_version", "draft", "update_policy", "category", "plan", "open_resolves_to", "versions", "versions_truncated" ], "properties": { "id": { "type": "string", "format": "uuid", "description": "UUIDv7, lowercase canonical form." }, "slug": { "type": "string" }, "name": { "type": "string" }, "owner": { "type": "string", "enum": [ "platform", "organization" ] }, "organization_id": { "anyOf": [ { "type": "string", "format": "uuid", "description": "UUIDv7, lowercase canonical form." }, { "type": "null" } ] }, "created_at": { "type": "string", "format": "date-time", "description": "RFC 3339 UTC timestamp with Z." }, "archived_at": { "anyOf": [ { "type": "string", "format": "date-time", "description": "RFC 3339 UTC timestamp with Z." }, { "type": "null" } ] }, "shadowed_by_organization_template": { "type": "boolean", "description": "Platform template whose slug the caller’s organization template currently wins for `open` (resolution prefers the organization’s published version)." }, "defaults": { "type": "object", "required": [ "memory_mib", "idle_policy" ], "properties": { "memory_mib": { "anyOf": [ { "type": "integer", "description": "Memory of a new start without caps.memory_mib (overrides the version’s default_caps.memory_mib_base)." }, { "type": "null" } ] }, "idle_policy": { "anyOf": [ { "type": "string", "description": "Idle policy of a workspace that sets none: adaptive, never or fixed:." }, { "type": "null" } ] } }, "additionalProperties": false, "description": "Mutable template-level defaults (versions are immutable). Null fields fall back to the version and platform defaults." }, "open_version": { "anyOf": [ { "type": "object", "required": [ "id", "version", "state", "architecture", "artifact_sha256", "description", "created_at", "published_at", "archived_at", "is_open_version", "caps", "default_caps", "effective_ceilings", "plan_clamped", "compatibility", "installed_tools", "build_id", "publishable", "manifest_schema", "disk_layouts", "source", "base", "defaults", "settings", "files", "rootfs_bytes", "chain", "storage" ], "properties": { "id": { "type": "string", "format": "uuid", "description": "UUIDv7, lowercase canonical form." }, "version": { "type": "integer" }, "state": { "type": "string", "enum": [ "unpublished", "published", "archived" ] }, "architecture": { "type": "string" }, "artifact_sha256": { "type": "string", "description": "SHA-256 of the version manifest (its immutable identity)." }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "created_at": { "type": "string", "format": "date-time", "description": "RFC 3339 UTC timestamp with Z." }, "published_at": { "anyOf": [ { "type": "string", "format": "date-time", "description": "RFC 3339 UTC timestamp with Z." }, { "type": "null" } ] }, "archived_at": { "anyOf": [ { "type": "string", "format": "date-time", "description": "RFC 3339 UTC timestamp with Z." }, { "type": "null" } ] }, "is_open_version": { "type": "boolean", "description": "The version `open` picks for a new workspace of this template (latest published, not archived)." }, "caps": { "type": "object", "required": [ "cpu_millis_max", "memory_mib_max", "disk_gib_max" ], "properties": { "cpu_millis_max": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "memory_mib_max": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "disk_gib_max": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] } }, "additionalProperties": false, "description": "Template limits (null = the template adds no limit)." }, "default_caps": { "anyOf": [ { "type": "object", "required": [ "cpu_millis_ceiling", "memory_mib_base", "memory_mib_ceiling", "disk_gib" ], "properties": { "cpu_millis_ceiling": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "memory_mib_base": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "memory_mib_ceiling": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "disk_gib": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] } }, "additionalProperties": false, "description": "Defaults from the manifest (memory_mib_base = boot memory of a new workspace)." }, { "type": "null" } ] }, "effective_ceilings": { "anyOf": [ { "type": "object", "required": [ "cpu_millis", "memory_mib", "disk_gib", "sources" ], "properties": { "cpu_millis": { "type": "integer" }, "memory_mib": { "type": "integer" }, "disk_gib": { "type": "integer" }, "sources": { "type": "object", "required": [ "cpu_millis", "memory_mib", "disk_gib" ], "properties": { "cpu_millis": { "type": "string", "enum": [ "template", "user", "plan" ] }, "memory_mib": { "type": "string", "enum": [ "template", "user", "plan" ] }, "disk_gib": { "type": "string", "enum": [ "template", "user", "plan" ] } }, "additionalProperties": false } }, "additionalProperties": false, "description": "Ceilings a new workspace without user caps would get now: min(template limit, plan limit)." }, { "type": "null" } ] }, "plan_clamped": { "type": "object", "properties": { "cpu_millis": { "type": "integer" }, "memory_mib": { "type": "integer" }, "disk_gib": { "type": "integer" } }, "additionalProperties": false, "description": "Resources where the caller’s plan is below what the template states (limit, else manifest default ceiling), with the plan value. Empty = no clamping." }, "compatibility": { "type": "object", "required": [ "manifest_schema", "architecture", "kernel", "guest_agent", "rootfs", "firecracker", "runtime_class" ], "properties": { "manifest_schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "architecture": { "type": "string" }, "kernel": { "anyOf": [ { "type": "object", "required": [ "release", "sha256" ], "properties": { "release": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "sha256": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "additionalProperties": false }, { "type": "null" } ] }, "guest_agent": { "anyOf": [ { "type": "object", "required": [ "version", "sha256", "vsock_port" ], "properties": { "version": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "sha256": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "vsock_port": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] } }, "additionalProperties": false }, { "type": "null" } ] }, "rootfs": { "anyOf": [ { "type": "object", "required": [ "format", "bytes", "sha256" ], "properties": { "format": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "bytes": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "sha256": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "additionalProperties": false }, { "type": "null" } ] }, "firecracker": { "anyOf": [ { "type": "string", "description": "Required Firecracker version when the manifest states one." }, { "type": "null" } ] }, "runtime_class": { "anyOf": [ { "type": "string", "description": "Runtime class when the manifest states one." }, { "type": "null" } ] } }, "additionalProperties": false, "description": "Runtime requirements exactly as recorded in the version manifest (null = not recorded)." }, "installed_tools": { "type": "array", "items": { "type": "object", "required": [ "name", "version" ], "properties": { "name": { "type": "string" }, "version": { "type": "string" } }, "additionalProperties": false }, "description": "Tool versions recorded in the manifest at build time." }, "build_id": { "anyOf": [ { "type": "string", "format": "uuid", "description": "UUIDv7, lowercase canonical form." }, { "type": "null" } ] }, "publishable": { "type": "boolean", "description": "Unpublished, not archived and produced by a build whose scan and compatibility checks passed (a registered `published` build, or a legacy `succeeded` one)." }, "manifest_schema": { "anyOf": [ { "type": "string", "description": "shardflux.template.v1 or shardflux.template.v2." }, { "type": "null" } ] }, "disk_layouts": { "type": "array", "items": { "$ref": "#/components/schemas/DiskLayout" }, "description": "Layouts a new workspace of this version may use (a manifest without the field: legacy only)." }, "source": { "anyOf": [ { "$ref": "#/components/schemas/TemplateSource" }, { "type": "null" } ] }, "base": { "anyOf": [ { "type": "object", "required": [ "name", "version", "manifest_sha256", "rootfs_sha256" ], "properties": { "name": { "type": "string" }, "version": { "type": "string" }, "manifest_sha256": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "rootfs_sha256": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "additionalProperties": false, "description": "Lineage: the version this one was built on (manifest `base`); null for platform roots." }, { "type": "null" } ] }, "defaults": { "$ref": "#/components/schemas/TemplateDefaults" }, "settings": { "$ref": "#/components/schemas/TemplateSettings" }, "files": { "$ref": "#/components/schemas/TemplateFilesSummary" }, "rootfs_bytes": { "anyOf": [ { "type": "integer", "description": "The root image size (for layers versions: the platform base’s)." }, { "type": "null" } ] }, "chain": { "type": "array", "items": { "type": "object", "required": [ "layer_id", "bytes", "introduced_in_version" ], "properties": { "layer_id": { "type": "string", "format": "uuid", "description": "UUIDv7, lowercase canonical form." }, "bytes": { "type": "integer" }, "introduced_in_version": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] } }, "additionalProperties": false }, "description": "The org layers of this version’s chain, bottom to top (empty for images)." }, "storage": { "$ref": "#/components/schemas/TemplateStorage" } }, "additionalProperties": false }, { "type": "null" } ] }, "draft": { "anyOf": [ { "type": "object", "required": [ "workspace_id", "workspace_key", "observed_state", "base_version", "created_at" ], "properties": { "workspace_id": { "type": "string", "format": "uuid", "description": "UUIDv7, lowercase canonical form." }, "workspace_key": { "type": "string" }, "observed_state": { "type": "string" }, "base_version": { "type": "object", "required": [ "id", "template_id", "slug", "version" ], "properties": { "id": { "type": "string", "format": "uuid", "description": "UUIDv7, lowercase canonical form." }, "template_id": { "type": "string", "format": "uuid", "description": "UUIDv7, lowercase canonical form." }, "slug": { "type": "string" }, "version": { "type": "integer" } }, "additionalProperties": false, "description": "The draft base: the template version the draft (and its test instances) run on." }, "created_at": { "type": "string", "format": "date-time", "description": "RFC 3339 UTC timestamp with Z." } }, "additionalProperties": false, "description": "The template’s live draft (GET …/templates/{slug}/draft for the full view); null when there is none." }, { "type": "null" } ] }, "update_policy": { "$ref": "#/components/schemas/UpdatePolicy" }, "category": { "anyOf": [ { "type": "string", "enum": [ "os", "stack" ], "description": "Platform templates: os (a bare operating system) or stack (preinstalled tools). Organization templates: null." }, { "type": "null" } ] }, "plan": { "anyOf": [ { "type": "object", "required": [ "plan_key", "catalog_version" ], "properties": { "plan_key": { "type": "string" }, "catalog_version": { "type": "string" } }, "additionalProperties": false }, { "type": "null" } ] }, "open_resolves_to": { "anyOf": [ { "type": "object", "required": [ "template_id", "template_version_id", "version", "owner" ], "properties": { "template_id": { "type": "string", "format": "uuid", "description": "UUIDv7, lowercase canonical form." }, "template_version_id": { "type": "string", "format": "uuid", "description": "UUIDv7, lowercase canonical form." }, "version": { "type": "integer" }, "owner": { "type": "string", "enum": [ "platform", "organization" ] } }, "additionalProperties": false, "description": "What `open({template: slug})` resolves to for this organization right now (may be the other template of the same slug)." }, { "type": "null" } ] }, "versions": { "type": "array", "items": { "type": "object", "required": [ "id", "version", "state", "architecture", "artifact_sha256", "description", "created_at", "published_at", "archived_at", "is_open_version", "caps", "default_caps", "effective_ceilings", "plan_clamped", "compatibility", "installed_tools", "build_id", "publishable", "manifest_schema", "disk_layouts", "source", "base", "defaults", "settings", "files", "rootfs_bytes", "chain", "storage" ], "properties": { "id": { "type": "string", "format": "uuid", "description": "UUIDv7, lowercase canonical form." }, "version": { "type": "integer" }, "state": { "type": "string", "enum": [ "unpublished", "published", "archived" ] }, "architecture": { "type": "string" }, "artifact_sha256": { "type": "string", "description": "SHA-256 of the version manifest (its immutable identity)." }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "created_at": { "type": "string", "format": "date-time", "description": "RFC 3339 UTC timestamp with Z." }, "published_at": { "anyOf": [ { "type": "string", "format": "date-time", "description": "RFC 3339 UTC timestamp with Z." }, { "type": "null" } ] }, "archived_at": { "anyOf": [ { "type": "string", "format": "date-time", "description": "RFC 3339 UTC timestamp with Z." }, { "type": "null" } ] }, "is_open_version": { "type": "boolean", "description": "The version `open` picks for a new workspace of this template (latest published, not archived)." }, "caps": { "type": "object", "required": [ "cpu_millis_max", "memory_mib_max", "disk_gib_max" ], "properties": { "cpu_millis_max": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "memory_mib_max": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "disk_gib_max": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] } }, "additionalProperties": false, "description": "Template limits (null = the template adds no limit)." }, "default_caps": { "anyOf": [ { "type": "object", "required": [ "cpu_millis_ceiling", "memory_mib_base", "memory_mib_ceiling", "disk_gib" ], "properties": { "cpu_millis_ceiling": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "memory_mib_base": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "memory_mib_ceiling": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "disk_gib": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] } }, "additionalProperties": false, "description": "Defaults from the manifest (memory_mib_base = boot memory of a new workspace)." }, { "type": "null" } ] }, "effective_ceilings": { "anyOf": [ { "type": "object", "required": [ "cpu_millis", "memory_mib", "disk_gib", "sources" ], "properties": { "cpu_millis": { "type": "integer" }, "memory_mib": { "type": "integer" }, "disk_gib": { "type": "integer" }, "sources": { "type": "object", "required": [ "cpu_millis", "memory_mib", "disk_gib" ], "properties": { "cpu_millis": { "type": "string", "enum": [ "template", "user", "plan" ] }, "memory_mib": { "type": "string", "enum": [ "template", "user", "plan" ] }, "disk_gib": { "type": "string", "enum": [ "template", "user", "plan" ] } }, "additionalProperties": false } }, "additionalProperties": false, "description": "Ceilings a new workspace without user caps would get now: min(template limit, plan limit)." }, { "type": "null" } ] }, "plan_clamped": { "type": "object", "properties": { "cpu_millis": { "type": "integer" }, "memory_mib": { "type": "integer" }, "disk_gib": { "type": "integer" } }, "additionalProperties": false, "description": "Resources where the caller’s plan is below what the template states (limit, else manifest default ceiling), with the plan value. Empty = no clamping." }, "compatibility": { "type": "object", "required": [ "manifest_schema", "architecture", "kernel", "guest_agent", "rootfs", "firecracker", "runtime_class" ], "properties": { "manifest_schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "architecture": { "type": "string" }, "kernel": { "anyOf": [ { "type": "object", "required": [ "release", "sha256" ], "properties": { "release": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "sha256": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "additionalProperties": false }, { "type": "null" } ] }, "guest_agent": { "anyOf": [ { "type": "object", "required": [ "version", "sha256", "vsock_port" ], "properties": { "version": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "sha256": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "vsock_port": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] } }, "additionalProperties": false }, { "type": "null" } ] }, "rootfs": { "anyOf": [ { "type": "object", "required": [ "format", "bytes", "sha256" ], "properties": { "format": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "bytes": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "sha256": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "additionalProperties": false }, { "type": "null" } ] }, "firecracker": { "anyOf": [ { "type": "string", "description": "Required Firecracker version when the manifest states one." }, { "type": "null" } ] }, "runtime_class": { "anyOf": [ { "type": "string", "description": "Runtime class when the manifest states one." }, { "type": "null" } ] } }, "additionalProperties": false, "description": "Runtime requirements exactly as recorded in the version manifest (null = not recorded)." }, "installed_tools": { "type": "array", "items": { "type": "object", "required": [ "name", "version" ], "properties": { "name": { "type": "string" }, "version": { "type": "string" } }, "additionalProperties": false }, "description": "Tool versions recorded in the manifest at build time." }, "build_id": { "anyOf": [ { "type": "string", "format": "uuid", "description": "UUIDv7, lowercase canonical form." }, { "type": "null" } ] }, "publishable": { "type": "boolean", "description": "Unpublished, not archived and produced by a build whose scan and compatibility checks passed (a registered `published` build, or a legacy `succeeded` one)." }, "manifest_schema": { "anyOf": [ { "type": "string", "description": "shardflux.template.v1 or shardflux.template.v2." }, { "type": "null" } ] }, "disk_layouts": { "type": "array", "items": { "$ref": "#/components/schemas/DiskLayout" }, "description": "Layouts a new workspace of this version may use (a manifest without the field: legacy only)." }, "source": { "anyOf": [ { "$ref": "#/components/schemas/TemplateSource" }, { "type": "null" } ] }, "base": { "anyOf": [ { "type": "object", "required": [ "name", "version", "manifest_sha256", "rootfs_sha256" ], "properties": { "name": { "type": "string" }, "version": { "type": "string" }, "manifest_sha256": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "rootfs_sha256": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "additionalProperties": false, "description": "Lineage: the version this one was built on (manifest `base`); null for platform roots." }, { "type": "null" } ] }, "defaults": { "$ref": "#/components/schemas/TemplateDefaults" }, "settings": { "$ref": "#/components/schemas/TemplateSettings" }, "files": { "$ref": "#/components/schemas/TemplateFilesSummary" }, "rootfs_bytes": { "anyOf": [ { "type": "integer", "description": "The root image size (for layers versions: the platform base’s)." }, { "type": "null" } ] }, "chain": { "type": "array", "items": { "type": "object", "required": [ "layer_id", "bytes", "introduced_in_version" ], "properties": { "layer_id": { "type": "string", "format": "uuid", "description": "UUIDv7, lowercase canonical form." }, "bytes": { "type": "integer" }, "introduced_in_version": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] } }, "additionalProperties": false }, "description": "The org layers of this version’s chain, bottom to top (empty for images)." }, "storage": { "$ref": "#/components/schemas/TemplateStorage" } }, "additionalProperties": false }, "description": "Newest first. Unpublished versions only for owners/admins of the owning organization; archived only with include_archived." }, "versions_truncated": { "type": "boolean" } }, "additionalProperties": false } } } }, "4XX": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "examples": { "not_found": { "$ref": "#/components/examples/not_found" }, "rate_limited": { "$ref": "#/components/examples/rate_limited" }, "validation_failed": { "$ref": "#/components/examples/validation_failed" } } } } }, "5XX": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "examples": { "not_found": { "$ref": "#/components/examples/not_found" }, "rate_limited": { "$ref": "#/components/examples/rate_limited" }, "validation_failed": { "$ref": "#/components/examples/validation_failed" } } } } } } } }, "/v1/organizations/{organization_id}/template-builds": { "get": { "operationId": "getV1OrganizationsOrganizationIdTemplateBuilds", "summary": "List an organization’s template builds, newest first", "tags": [ "Template builds" ], "parameters": [ { "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 }, "in": "query", "name": "limit", "required": false }, { "schema": { "type": "string", "maxLength": 200 }, "in": "query", "name": "cursor", "required": false }, { "schema": { "type": "string", "enum": [ "queued", "building", "testing", "publishing", "published", "succeeded", "failed", "canceled" ] }, "in": "query", "name": "state", "required": false }, { "schema": { "type": "string", "minLength": 1, "maxLength": 100, "pattern": "^[a-z0-9](?:[a-z0-9._-]{0,98}[a-z0-9])?$" }, "in": "query", "name": "template", "required": false, "description": "Organization template slug." }, { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "organization_id", "required": true, "description": "UUIDv7, lowercase canonical form." } ], "security": [ { "apiKey": [] } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "next_cursor" ], "properties": { "data": { "type": "array", "items": { "type": "object", "required": [ "id", "organization_id", "template", "state", "target_version", "auto_publish", "published_at", "registration", "template_version", "cancel_requested_at", "created_at", "updated_at", "started_at", "completed_at", "requested_by", "base", "architecture", "bounds", "requested_bounds", "bound_sources", "network", "denied_hosts", "provenance", "result", "failure", "log", "publishable", "builder_availability", "source_kind", "source_workspace_id", "source_checkpoint_id", "scrub_result", "files", "produced_layer_id", "squashed", "org_bytes" ], "properties": { "id": { "type": "string", "format": "uuid", "description": "UUIDv7, lowercase canonical form." }, "organization_id": { "type": "string", "format": "uuid", "description": "UUIDv7, lowercase canonical form." }, "template": { "type": "object", "required": [ "id", "slug", "name" ], "properties": { "id": { "type": "string", "format": "uuid", "description": "UUIDv7, lowercase canonical form." }, "slug": { "type": "string" }, "name": { "type": "string" } }, "additionalProperties": false }, "state": { "type": "string", "enum": [ "queued", "building", "testing", "publishing", "published", "succeeded", "failed", "canceled" ], "description": "queued -> building -> testing -> publishing -> published (the cell stored the artifact; the API then registers the version, see `registration`) | failed | canceled. `succeeded` = legacy builds." }, "target_version": { "anyOf": [ { "type": "integer", "description": "Version number this build produces in its organization template (assigned at request time; never reused, so versions may have gaps). Null only for legacy builds." }, { "type": "null" } ] }, "auto_publish": { "type": "boolean", "description": "Publish the registered version at once (true), or leave it unpublished for the owner/admin publish route." }, "published_at": { "anyOf": [ { "type": "string", "format": "date-time", "description": "RFC 3339 UTC timestamp with Z." }, { "type": "null" } ] }, "registration": { "type": "object", "required": [ "state", "registered_at", "error" ], "properties": { "state": { "type": "string", "enum": [ "not_applicable", "pending", "registered", "failed" ] }, "registered_at": { "anyOf": [ { "type": "string", "format": "date-time", "description": "RFC 3339 UTC timestamp with Z." }, { "type": "null" } ] }, "error": { "anyOf": [ { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "additionalProperties": false }, { "type": "null" } ] } }, "additionalProperties": false, "description": "Creation of the immutable template version from a published build. not_applicable: not published (yet); pending: waiting for the API worker (error = last failed attempt, retried with backoff); registered; failed: retries exhausted (error says why)." }, "template_version": { "anyOf": [ { "type": "object", "required": [ "id", "version", "published" ], "properties": { "id": { "type": "string", "format": "uuid", "description": "UUIDv7, lowercase canonical form." }, "version": { "type": "integer" }, "published": { "type": "boolean" } }, "additionalProperties": false, "description": "The template version this build produced (once registered)." }, { "type": "null" } ] }, "cancel_requested_at": { "anyOf": [ { "type": "string", "format": "date-time", "description": "RFC 3339 UTC timestamp with Z." }, { "type": "null" } ] }, "created_at": { "type": "string", "format": "date-time", "description": "RFC 3339 UTC timestamp with Z." }, "updated_at": { "type": "string", "format": "date-time", "description": "RFC 3339 UTC timestamp with Z." }, "started_at": { "anyOf": [ { "type": "string", "format": "date-time", "description": "RFC 3339 UTC timestamp with Z." }, { "type": "null" } ] }, "completed_at": { "anyOf": [ { "type": "string", "format": "date-time", "description": "RFC 3339 UTC timestamp with Z." }, { "type": "null" } ] }, "requested_by": { "type": "object", "required": [ "type", "id" ], "properties": { "type": { "type": "string", "enum": [ "user", "api_key" ] }, "id": { "type": "string", "format": "uuid", "description": "UUIDv7, lowercase canonical form." } }, "additionalProperties": false }, "base": { "type": "object", "required": [ "ref", "template_id", "template_version_id", "slug", "version", "artifact_sha256" ], "properties": { "ref": { "type": "string" }, "template_id": { "type": "string", "format": "uuid", "description": "UUIDv7, lowercase canonical form." }, "template_version_id": { "type": "string", "format": "uuid", "description": "UUIDv7, lowercase canonical form." }, "slug": { "type": "string" }, "version": { "type": "integer" }, "artifact_sha256": { "type": "string" } }, "additionalProperties": false, "description": "The base template version, pinned at request time." }, "architecture": { "type": "string" }, "bounds": { "type": "object", "required": [ "cpu_millis", "memory_mib", "disk_gib", "timeout_seconds" ], "properties": { "cpu_millis": { "type": "integer" }, "memory_mib": { "type": "integer" }, "disk_gib": { "type": "integer" }, "timeout_seconds": { "type": "integer" } }, "additionalProperties": false }, "requested_bounds": { "type": "object", "required": [ "cpu_millis", "memory_mib", "disk_gib", "timeout_seconds" ], "properties": { "cpu_millis": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "memory_mib": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "disk_gib": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "timeout_seconds": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] } }, "additionalProperties": false }, "bound_sources": { "type": "object", "required": [ "cpu_millis", "memory_mib", "disk_gib", "timeout_seconds" ], "properties": { "cpu_millis": { "type": "string", "enum": [ "request", "plan", "platform" ] }, "memory_mib": { "type": "string", "enum": [ "request", "plan", "platform" ] }, "disk_gib": { "type": "string", "enum": [ "request", "plan", "platform" ] }, "timeout_seconds": { "type": "string", "enum": [ "request", "plan", "platform" ] } }, "additionalProperties": false, "description": "request: as asked; plan: clamped to (or defaulted from) the plan’s workspace limit; platform: build timeout default/maximum." }, "network": { "type": "object", "required": [ "mode", "allow_hosts" ], "properties": { "mode": { "type": "string", "enum": [ "none", "egress_allowlist" ] }, "allow_hosts": { "type": "array", "items": { "type": "string" } } }, "additionalProperties": false, "description": "The build network (recipe v2: compiled.network, derived from the recipe for `auto`)." }, "denied_hosts": { "type": "array", "items": { "type": "string" }, "description": "Host names the builder’s DNS proxy refused during the build (at most 50). Rebuild with a host in build.network.extra_hosts to allow it." }, "provenance": { "type": "object", "required": [ "recipe_schema", "recipe_sha256", "base_artifact_sha256", "builder_id", "attempt" ], "properties": { "recipe_schema": { "anyOf": [ { "type": "string", "description": "Null for workspace-source builds." }, { "type": "null" } ] }, "recipe_sha256": { "anyOf": [ { "type": "string", "description": "SHA-256 of the canonical recipe JSON (the build’s source input); null for workspace-source builds." }, { "type": "null" } ] }, "base_artifact_sha256": { "type": "string" }, "builder_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "attempt": { "type": "integer" } }, "additionalProperties": false }, "recipe": { "anyOf": [ { "type": "object", "required": [ "dockerfile" ], "properties": { "dockerfile": { "type": "string" } }, "additionalProperties": false }, { "type": "object", "required": [ "schema", "build", "settings", "compiled" ], "properties": { "schema": { "type": "string", "enum": [ "shardflux.template-recipe.v2" ] }, "build": { "type": "object", "required": [ "languages", "packages", "files", "steps", "network" ], "properties": { "languages": { "type": "array", "items": { "type": "object", "required": [ "id", "version", "source", "url", "sha256" ], "properties": { "id": { "type": "string" }, "version": { "type": "string" }, "source": { "type": "string", "enum": [ "install", "base" ] }, "url": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "sha256": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "additionalProperties": false }, "description": "Resolved languages in compile order (implied ones included); source base = the base already has it." }, "packages": { "type": "object", "required": [ "apt", "pip", "npm" ], "properties": { "apt": { "type": "array", "items": { "type": "string" } }, "pip": { "type": "object", "required": [ "packages", "requirements" ], "properties": { "packages": { "type": "array", "items": { "type": "string" } }, "requirements": { "type": "array", "items": { "type": "string" } } }, "additionalProperties": false }, "npm": { "type": "array", "items": { "type": "string" } } }, "additionalProperties": false }, "files": { "type": "array", "items": { "type": "object", "required": [ "upload", "kind", "to", "owner", "mode", "size" ], "properties": { "upload": { "type": "string" }, "kind": { "type": "string", "enum": [ "file", "tar" ] }, "to": { "type": "string" }, "owner": { "type": "string" }, "mode": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "size": { "type": "integer" } }, "additionalProperties": false } }, "steps": { "type": "array", "items": { "type": "object", "required": [ "name", "run", "user", "cwd", "env" ], "properties": { "name": { "type": "string" }, "run": { "type": "string" }, "user": { "type": "string" }, "cwd": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "env": { "type": "object", "additionalProperties": { "type": "string" } } }, "additionalProperties": false } }, "network": { "type": "object", "required": [ "build", "extra_hosts", "allow_hosts" ], "properties": { "build": { "type": "string", "enum": [ "auto", "none", "allowlist" ] }, "extra_hosts": { "type": "array", "items": { "type": "string" } }, "allow_hosts": { "type": "array", "items": { "type": "string" } } }, "additionalProperties": false } }, "additionalProperties": false }, "settings": { "$ref": "#/components/schemas/TemplateSettings" }, "compiled": { "type": "object", "required": [ "compiler", "language_table_sha256", "build_env", "steps", "tools", "network", "objects" ], "properties": { "compiler": { "type": "string" }, "language_table_sha256": { "type": "string" }, "build_env": { "type": "object", "additionalProperties": { "type": "string" } }, "steps": { "type": "array", "items": { "type": "object", "properties": {}, "additionalProperties": true, "description": "A host.v1 RecipeStep in protojson (proto field names, defaults omitted)." } }, "tools": { "type": "array", "items": { "type": "object", "required": [ "name", "argv" ], "properties": { "name": { "type": "string" }, "argv": { "type": "array", "items": { "type": "string" } } }, "additionalProperties": false } }, "network": { "type": "object", "required": [ "mode", "allow_hosts" ], "properties": { "mode": { "type": "string", "enum": [ "none", "egress_allowlist" ] }, "allow_hosts": { "type": "array", "items": { "type": "string" } } }, "additionalProperties": false }, "objects": { "type": "array", "items": { "type": "object", "required": [ "sha256", "size", "kind" ], "properties": { "sha256": { "type": "string" }, "size": { "type": "integer" }, "kind": { "type": "string", "enum": [ "file", "tar" ] } }, "additionalProperties": false } } }, "additionalProperties": false } }, "additionalProperties": false } ], "description": "Only on GET of one build: recipe v1 {dockerfile}, or recipe v2 {schema, build, settings, compiled} (the stored document)." }, "result": { "type": "object", "required": [ "artifact_sha256", "scan", "compatibility", "produced_version" ], "properties": { "artifact_sha256": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "scan": { "anyOf": [ { "type": "object", "properties": {}, "additionalProperties": true, "description": "Scanner result recorded by the builder ({passed, scanner, scanner_version, summary})." }, { "type": "null" } ] }, "compatibility": { "anyOf": [ { "type": "object", "properties": {}, "additionalProperties": true, "description": "Guest compatibility test result ({passed, runtime_class, kernel_release, firecracker_version, guest_agent_version, checks})." }, { "type": "null" } ] }, "produced_version": { "anyOf": [ { "type": "object", "required": [ "id", "version", "state", "published_at", "archived_at" ], "properties": { "id": { "type": "string", "format": "uuid", "description": "UUIDv7, lowercase canonical form." }, "version": { "type": "integer" }, "state": { "type": "string", "enum": [ "unpublished", "published", "archived" ] }, "published_at": { "anyOf": [ { "type": "string", "format": "date-time", "description": "RFC 3339 UTC timestamp with Z." }, { "type": "null" } ] }, "archived_at": { "anyOf": [ { "type": "string", "format": "date-time", "description": "RFC 3339 UTC timestamp with Z." }, { "type": "null" } ] } }, "additionalProperties": false }, { "type": "null" } ] } }, "additionalProperties": false }, "failure": { "anyOf": [ { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "additionalProperties": false }, { "type": "null" } ] }, "log": { "type": "object", "required": [ "state", "bytes", "sha256", "expires_at", "downloadable" ], "properties": { "state": { "type": "string", "enum": [ "none", "available", "expired" ] }, "bytes": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "sha256": { "anyOf": [ { "type": "string", "description": "SHA-256 of the full log object, when the builder recorded it." }, { "type": "null" } ] }, "expires_at": { "anyOf": [ { "type": "string", "format": "date-time", "description": "RFC 3339 UTC timestamp with Z." }, { "type": "null" } ] }, "downloadable": { "type": "boolean", "description": "The full log can be downloaded through GET .../template-builds/{id}/log-url (short-lived signed URL)." }, "tail": { "anyOf": [ { "type": "string", "description": "Last <= 64 KiB of the build log (GET of one build; until expires_at)." }, { "type": "null" } ] } }, "additionalProperties": false, "description": "Build log: the tail inline, the full log through a short-lived signed URL (log-url)." }, "publishable": { "type": "boolean" }, "builder_availability": { "type": "object", "required": [ "state", "reason", "active_builders", "last_heartbeat_at" ], "properties": { "state": { "type": "string", "enum": [ "available", "unavailable" ] }, "reason": { "anyOf": [ { "type": "string", "enum": [ "no_builder_registered", "no_recent_heartbeat" ] }, { "type": "null" } ] }, "active_builders": { "type": "integer" }, "last_heartbeat_at": { "anyOf": [ { "type": "string", "format": "date-time", "description": "RFC 3339 UTC timestamp with Z." }, { "type": "null" } ] } }, "additionalProperties": false, "description": "From builder heartbeats (app.template_builders, 60 s window). `unavailable`: queued builds wait until a builder runs." }, "source_kind": { "type": "string", "enum": [ "recipe", "workspace" ], "description": "recipe (recipe v1 Dockerfile dialect or recipe v2) or workspace (save-as-template, draft publish)." }, "source_workspace_id": { "anyOf": [ { "type": "string", "format": "uuid", "description": "UUIDv7, lowercase canonical form." }, { "type": "null" } ] }, "source_checkpoint_id": { "anyOf": [ { "type": "string", "description": "The saved checkpoint (filled when the capture finished and the cell claimed the build)." }, { "type": "null" } ] }, "scrub_result": { "anyOf": [ { "type": "object", "properties": {}, "additionalProperties": true, "description": "sf-scrub.v1 report ({policy, removed_count, removed_bytes, removed_paths (first 1000), emptied, reimposed}); paths only, never contents." }, { "type": "null" } ] }, "files": { "anyOf": [ { "type": "object", "properties": {}, "additionalProperties": true, "description": "The produced file list ({key, size, sha256, content_sha256, entries, total_file_bytes})." }, { "type": "null" } ] }, "produced_layer_id": { "anyOf": [ { "type": "string", "format": "uuid", "description": "UUIDv7, lowercase canonical form." }, { "type": "null" } ] }, "squashed": { "anyOf": [ { "type": "boolean", "description": "The base chain already had 4 org layers: this build squashed them into its one layer." }, { "type": "null" } ] }, "org_bytes": { "anyOf": [ { "type": "integer", "description": "The produced chain’s org bytes (limited by the plan’s workspace disk limit)." }, { "type": "null" } ] } }, "additionalProperties": false } }, "next_cursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "additionalProperties": false } } } }, "4XX": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "examples": { "not_found": { "$ref": "#/components/examples/not_found" }, "rate_limited": { "$ref": "#/components/examples/rate_limited" }, "validation_failed": { "$ref": "#/components/examples/validation_failed" } } } } }, "5XX": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "examples": { "not_found": { "$ref": "#/components/examples/not_found" }, "rate_limited": { "$ref": "#/components/examples/rate_limited" }, "validation_failed": { "$ref": "#/components/examples/validation_failed" } } } } } } }, "post": { "operationId": "postV1OrganizationsOrganizationIdTemplateBuilds", "summary": "Request a custom template build (queued for the isolated builder)", "tags": [ "Template builds" ], "description": "202 with the queued build. Takes recipe v1 (a Dockerfile) or recipe v2 (: validated against the base, compiled to the builder’s steps, uploads locked). Records the canonical recipe and its SHA-256 (provenance input), pins the base version, clamps resources to the plan and assigns `target_version`. The cell executes it (building -> testing -> publishing -> published) and the API then registers the version (published at once unless auto_publish=false); poll GET .../template-builds/{id} until `registration.state` is registered (or the build failed/was canceled). `builder_availability` says whether a builder is running. Errors: 422 when the recipe is outside the host builder Dockerfile dialect or the slug is not a builder slug (`details.reason`: multi_stage_not_supported, from_not_template_base, stage_names_not_supported, from_flags_not_supported, base_mismatch, run_flags_not_supported, heredoc_not_supported, instruction_not_supported, no_build_context, env_invalid, user_invalid, too_many_steps, recipe_too_large, slug_not_supported_by_builder, platform_template_slug, reserved_template_slug, base_not_found, base_not_published, base_archived, architecture_not_supported, ...; `line` for line errors; recipe v2: invalid_recipe (details.field, details.detail), base_not_layered, language_unavailable, language_conflict, invalid_package, too_many_files, platform_owned_path, invalid_path, upload_required, upload_missing, upload_digest_mismatch, upload_too_large, too_many_steps, recipe_too_large, allowlist_empty, allow_hosts_without_allowlist, extra_hosts_without_auto, too_many_hosts, invalid_host, ip_literal_not_allowed, host_not_allowed, invalid_settings, services_unsupported, too_many_acknowledged_findings), 503 dependency_unavailable (uploads_not_configured), 402 entitlement_required, 403 quota_exceeded (concurrent_template_builds), 409 template_archived. Supports Idempotency-Key.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "template_slug", "recipe" ], "properties": { "template_slug": { "type": "string", "minLength": 1, "maxLength": 100, "pattern": "^[a-z0-9](?:[a-z0-9._-]{0,98}[a-z0-9])?$", "description": "Organization template to build into (created by the first build). Platform slugs and the reserved slugs new and edit are refused for new templates." }, "auto_publish": { "type": "boolean", "default": true, "description": "Publish the produced version as soon as it is registered (new workspaces of the slug then use it). false: it stays unpublished until an owner/admin publishes it." }, "display_name": { "type": "string", "minLength": 1, "maxLength": 200, "pattern": "^[^\\u0000-\\u001f\\u007f]+$", "description": "Template name when this build creates the template." }, "recipe": { "anyOf": [ { "$ref": "#/components/schemas/TemplateRecipeV1" }, { "$ref": "#/components/schemas/TemplateRecipeV2" } ], "description": "Recipe v1 (TemplateRecipeV1: a Dockerfile, no `schema` field) or recipe v2 (TemplateRecipeV2, `schema: \"shardflux.template-recipe.v2\"`: languages, packages, uploaded files, build steps, auto network and settings;)." }, "description": { "type": "string", "minLength": 1, "maxLength": 2000, "description": "The version description (manifest `description`)." }, "acknowledged_scan_findings": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 4096, "pattern": "^/" }, "maxItems": 1000, "description": "Recipe v2 only: up to 200 absolute paths the credential scan may report without failing the build (recorded in the manifest)." } }, "additionalProperties": false } } } }, "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "organization_id", "required": true, "description": "UUIDv7, lowercase canonical form." } ], "security": [ { "apiKey": [] } ], "responses": { "202": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "required": [ "id", "organization_id", "template", "state", "target_version", "auto_publish", "published_at", "registration", "template_version", "cancel_requested_at", "created_at", "updated_at", "started_at", "completed_at", "requested_by", "base", "architecture", "bounds", "requested_bounds", "bound_sources", "network", "denied_hosts", "provenance", "result", "failure", "log", "publishable", "builder_availability", "source_kind", "source_workspace_id", "source_checkpoint_id", "scrub_result", "files", "produced_layer_id", "squashed", "org_bytes" ], "properties": { "id": { "type": "string", "format": "uuid", "description": "UUIDv7, lowercase canonical form." }, "organization_id": { "type": "string", "format": "uuid", "description": "UUIDv7, lowercase canonical form." }, "template": { "type": "object", "required": [ "id", "slug", "name" ], "properties": { "id": { "type": "string", "format": "uuid", "description": "UUIDv7, lowercase canonical form." }, "slug": { "type": "string" }, "name": { "type": "string" } }, "additionalProperties": false }, "state": { "type": "string", "enum": [ "queued", "building", "testing", "publishing", "published", "succeeded", "failed", "canceled" ], "description": "queued -> building -> testing -> publishing -> published (the cell stored the artifact; the API then registers the version, see `registration`) | failed | canceled. `succeeded` = legacy builds." }, "target_version": { "anyOf": [ { "type": "integer", "description": "Version number this build produces in its organization template (assigned at request time; never reused, so versions may have gaps). Null only for legacy builds." }, { "type": "null" } ] }, "auto_publish": { "type": "boolean", "description": "Publish the registered version at once (true), or leave it unpublished for the owner/admin publish route." }, "published_at": { "anyOf": [ { "type": "string", "format": "date-time", "description": "RFC 3339 UTC timestamp with Z." }, { "type": "null" } ] }, "registration": { "type": "object", "required": [ "state", "registered_at", "error" ], "properties": { "state": { "type": "string", "enum": [ "not_applicable", "pending", "registered", "failed" ] }, "registered_at": { "anyOf": [ { "type": "string", "format": "date-time", "description": "RFC 3339 UTC timestamp with Z." }, { "type": "null" } ] }, "error": { "anyOf": [ { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "additionalProperties": false }, { "type": "null" } ] } }, "additionalProperties": false, "description": "Creation of the immutable template version from a published build. not_applicable: not published (yet); pending: waiting for the API worker (error = last failed attempt, retried with backoff); registered; failed: retries exhausted (error says why)." }, "template_version": { "anyOf": [ { "type": "object", "required": [ "id", "version", "published" ], "properties": { "id": { "type": "string", "format": "uuid", "description": "UUIDv7, lowercase canonical form." }, "version": { "type": "integer" }, "published": { "type": "boolean" } }, "additionalProperties": false, "description": "The template version this build produced (once registered)." }, { "type": "null" } ] }, "cancel_requested_at": { "anyOf": [ { "type": "string", "format": "date-time", "description": "RFC 3339 UTC timestamp with Z." }, { "type": "null" } ] }, "created_at": { "type": "string", "format": "date-time", "description": "RFC 3339 UTC timestamp with Z." }, "updated_at": { "type": "string", "format": "date-time", "description": "RFC 3339 UTC timestamp with Z." }, "started_at": { "anyOf": [ { "type": "string", "format": "date-time", "description": "RFC 3339 UTC timestamp with Z." }, { "type": "null" } ] }, "completed_at": { "anyOf": [ { "type": "string", "format": "date-time", "description": "RFC 3339 UTC timestamp with Z." }, { "type": "null" } ] }, "requested_by": { "type": "object", "required": [ "type", "id" ], "properties": { "type": { "type": "string", "enum": [ "user", "api_key" ] }, "id": { "type": "string", "format": "uuid", "description": "UUIDv7, lowercase canonical form." } }, "additionalProperties": false }, "base": { "type": "object", "required": [ "ref", "template_id", "template_version_id", "slug", "version", "artifact_sha256" ], "properties": { "ref": { "type": "string" }, "template_id": { "type": "string", "format": "uuid", "description": "UUIDv7, lowercase canonical form." }, "template_version_id": { "type": "string", "format": "uuid", "description": "UUIDv7, lowercase canonical form." }, "slug": { "type": "string" }, "version": { "type": "integer" }, "artifact_sha256": { "type": "string" } }, "additionalProperties": false, "description": "The base template version, pinned at request time." }, "architecture": { "type": "string" }, "bounds": { "type": "object", "required": [ "cpu_millis", "memory_mib", "disk_gib", "timeout_seconds" ], "properties": { "cpu_millis": { "type": "integer" }, "memory_mib": { "type": "integer" }, "disk_gib": { "type": "integer" }, "timeout_seconds": { "type": "integer" } }, "additionalProperties": false }, "requested_bounds": { "type": "object", "required": [ "cpu_millis", "memory_mib", "disk_gib", "timeout_seconds" ], "properties": { "cpu_millis": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "memory_mib": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "disk_gib": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "timeout_seconds": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] } }, "additionalProperties": false }, "bound_sources": { "type": "object", "required": [ "cpu_millis", "memory_mib", "disk_gib", "timeout_seconds" ], "properties": { "cpu_millis": { "type": "string", "enum": [ "request", "plan", "platform" ] }, "memory_mib": { "type": "string", "enum": [ "request", "plan", "platform" ] }, "disk_gib": { "type": "string", "enum": [ "request", "plan", "platform" ] }, "timeout_seconds": { "type": "string", "enum": [ "request", "plan", "platform" ] } }, "additionalProperties": false, "description": "request: as asked; plan: clamped to (or defaulted from) the plan’s workspace limit; platform: build timeout default/maximum." }, "network": { "type": "object", "required": [ "mode", "allow_hosts" ], "properties": { "mode": { "type": "string", "enum": [ "none", "egress_allowlist" ] }, "allow_hosts": { "type": "array", "items": { "type": "string" } } }, "additionalProperties": false, "description": "The build network (recipe v2: compiled.network, derived from the recipe for `auto`)." }, "denied_hosts": { "type": "array", "items": { "type": "string" }, "description": "Host names the builder’s DNS proxy refused during the build (at most 50). Rebuild with a host in build.network.extra_hosts to allow it." }, "provenance": { "type": "object", "required": [ "recipe_schema", "recipe_sha256", "base_artifact_sha256", "builder_id", "attempt" ], "properties": { "recipe_schema": { "anyOf": [ { "type": "string", "description": "Null for workspace-source builds." }, { "type": "null" } ] }, "recipe_sha256": { "anyOf": [ { "type": "string", "description": "SHA-256 of the canonical recipe JSON (the build’s source input); null for workspace-source builds." }, { "type": "null" } ] }, "base_artifact_sha256": { "type": "string" }, "builder_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "attempt": { "type": "integer" } }, "additionalProperties": false }, "recipe": { "anyOf": [ { "type": "object", "required": [ "dockerfile" ], "properties": { "dockerfile": { "type": "string" } }, "additionalProperties": false }, { "type": "object", "required": [ "schema", "build", "settings", "compiled" ], "properties": { "schema": { "type": "string", "enum": [ "shardflux.template-recipe.v2" ] }, "build": { "type": "object", "required": [ "languages", "packages", "files", "steps", "network" ], "properties": { "languages": { "type": "array", "items": { "type": "object", "required": [ "id", "version", "source", "url", "sha256" ], "properties": { "id": { "type": "string" }, "version": { "type": "string" }, "source": { "type": "string", "enum": [ "install", "base" ] }, "url": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "sha256": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "additionalProperties": false }, "description": "Resolved languages in compile order (implied ones included); source base = the base already has it." }, "packages": { "type": "object", "required": [ "apt", "pip", "npm" ], "properties": { "apt": { "type": "array", "items": { "type": "string" } }, "pip": { "type": "object", "required": [ "packages", "requirements" ], "properties": { "packages": { "type": "array", "items": { "type": "string" } }, "requirements": { "type": "array", "items": { "type": "string" } } }, "additionalProperties": false }, "npm": { "type": "array", "items": { "type": "string" } } }, "additionalProperties": false }, "files": { "type": "array", "items": { "type": "object", "required": [ "upload", "kind", "to", "owner", "mode", "size" ], "properties": { "upload": { "type": "string" }, "kind": { "type": "string", "enum": [ "file", "tar" ] }, "to": { "type": "string" }, "owner": { "type": "string" }, "mode": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "size": { "type": "integer" } }, "additionalProperties": false } }, "steps": { "type": "array", "items": { "type": "object", "required": [ "name", "run", "user", "cwd", "env" ], "properties": { "name": { "type": "string" }, "run": { "type": "string" }, "user": { "type": "string" }, "cwd": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "env": { "type": "object", "additionalProperties": { "type": "string" } } }, "additionalProperties": false } }, "network": { "type": "object", "required": [ "build", "extra_hosts", "allow_hosts" ], "properties": { "build": { "type": "string", "enum": [ "auto", "none", "allowlist" ] }, "extra_hosts": { "type": "array", "items": { "type": "string" } }, "allow_hosts": { "type": "array", "items": { "type": "string" } } }, "additionalProperties": false } }, "additionalProperties": false }, "settings": { "$ref": "#/components/schemas/TemplateSettings" }, "compiled": { "type": "object", "required": [ "compiler", "language_table_sha256", "build_env", "steps", "tools", "network", "objects" ], "properties": { "compiler": { "type": "string" }, "language_table_sha256": { "type": "string" }, "build_env": { "type": "object", "additionalProperties": { "type": "string" } }, "steps": { "type": "array", "items": { "type": "object", "properties": {}, "additionalProperties": true, "description": "A host.v1 RecipeStep in protojson (proto field names, defaults omitted)." } }, "tools": { "type": "array", "items": { "type": "object", "required": [ "name", "argv" ], "properties": { "name": { "type": "string" }, "argv": { "type": "array", "items": { "type": "string" } } }, "additionalProperties": false } }, "network": { "type": "object", "required": [ "mode", "allow_hosts" ], "properties": { "mode": { "type": "string", "enum": [ "none", "egress_allowlist" ] }, "allow_hosts": { "type": "array", "items": { "type": "string" } } }, "additionalProperties": false }, "objects": { "type": "array", "items": { "type": "object", "required": [ "sha256", "size", "kind" ], "properties": { "sha256": { "type": "string" }, "size": { "type": "integer" }, "kind": { "type": "string", "enum": [ "file", "tar" ] } }, "additionalProperties": false } } }, "additionalProperties": false } }, "additionalProperties": false } ], "description": "Only on GET of one build: recipe v1 {dockerfile}, or recipe v2 {schema, build, settings, compiled} (the stored document)." }, "result": { "type": "object", "required": [ "artifact_sha256", "scan", "compatibility", "produced_version" ], "properties": { "artifact_sha256": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "scan": { "anyOf": [ { "type": "object", "properties": {}, "additionalProperties": true, "description": "Scanner result recorded by the builder ({passed, scanner, scanner_version, summary})." }, { "type": "null" } ] }, "compatibility": { "anyOf": [ { "type": "object", "properties": {}, "additionalProperties": true, "description": "Guest compatibility test result ({passed, runtime_class, kernel_release, firecracker_version, guest_agent_version, checks})." }, { "type": "null" } ] }, "produced_version": { "anyOf": [ { "type": "object", "required": [ "id", "version", "state", "published_at", "archived_at" ], "properties": { "id": { "type": "string", "format": "uuid", "description": "UUIDv7, lowercase canonical form." }, "version": { "type": "integer" }, "state": { "type": "string", "enum": [ "unpublished", "published", "archived" ] }, "published_at": { "anyOf": [ { "type": "string", "format": "date-time", "description": "RFC 3339 UTC timestamp with Z." }, { "type": "null" } ] }, "archived_at": { "anyOf": [ { "type": "string", "format": "date-time", "description": "RFC 3339 UTC timestamp with Z." }, { "type": "null" } ] } }, "additionalProperties": false }, { "type": "null" } ] } }, "additionalProperties": false }, "failure": { "anyOf": [ { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "additionalProperties": false }, { "type": "null" } ] }, "log": { "type": "object", "required": [ "state", "bytes", "sha256", "expires_at", "downloadable" ], "properties": { "state": { "type": "string", "enum": [ "none", "available", "expired" ] }, "bytes": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "sha256": { "anyOf": [ { "type": "string", "description": "SHA-256 of the full log object, when the builder recorded it." }, { "type": "null" } ] }, "expires_at": { "anyOf": [ { "type": "string", "format": "date-time", "description": "RFC 3339 UTC timestamp with Z." }, { "type": "null" } ] }, "downloadable": { "type": "boolean", "description": "The full log can be downloaded through GET .../template-builds/{id}/log-url (short-lived signed URL)." }, "tail": { "anyOf": [ { "type": "string", "description": "Last <= 64 KiB of the build log (GET of one build; until expires_at)." }, { "type": "null" } ] } }, "additionalProperties": false, "description": "Build log: the tail inline, the full log through a short-lived signed URL (log-url)." }, "publishable": { "type": "boolean" }, "builder_availability": { "type": "object", "required": [ "state", "reason", "active_builders", "last_heartbeat_at" ], "properties": { "state": { "type": "string", "enum": [ "available", "unavailable" ] }, "reason": { "anyOf": [ { "type": "string", "enum": [ "no_builder_registered", "no_recent_heartbeat" ] }, { "type": "null" } ] }, "active_builders": { "type": "integer" }, "last_heartbeat_at": { "anyOf": [ { "type": "string", "format": "date-time", "description": "RFC 3339 UTC timestamp with Z." }, { "type": "null" } ] } }, "additionalProperties": false, "description": "From builder heartbeats (app.template_builders, 60 s window). `unavailable`: queued builds wait until a builder runs." }, "source_kind": { "type": "string", "enum": [ "recipe", "workspace" ], "description": "recipe (recipe v1 Dockerfile dialect or recipe v2) or workspace (save-as-template, draft publish)." }, "source_workspace_id": { "anyOf": [ { "type": "string", "format": "uuid", "description": "UUIDv7, lowercase canonical form." }, { "type": "null" } ] }, "source_checkpoint_id": { "anyOf": [ { "type": "string", "description": "The saved checkpoint (filled when the capture finished and the cell claimed the build)." }, { "type": "null" } ] }, "scrub_result": { "anyOf": [ { "type": "object", "properties": {}, "additionalProperties": true, "description": "sf-scrub.v1 report ({policy, removed_count, removed_bytes, removed_paths (first 1000), emptied, reimposed}); paths only, never contents." }, { "type": "null" } ] }, "files": { "anyOf": [ { "type": "object", "properties": {}, "additionalProperties": true, "description": "The produced file list ({key, size, sha256, content_sha256, entries, total_file_bytes})." }, { "type": "null" } ] }, "produced_layer_id": { "anyOf": [ { "type": "string", "format": "uuid", "description": "UUIDv7, lowercase canonical form." }, { "type": "null" } ] }, "squashed": { "anyOf": [ { "type": "boolean", "description": "The base chain already had 4 org layers: this build squashed them into its one layer." }, { "type": "null" } ] }, "org_bytes": { "anyOf": [ { "type": "integer", "description": "The produced chain’s org bytes (limited by the plan’s workspace disk limit)." }, { "type": "null" } ] } }, "additionalProperties": false } } } }, "4XX": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "examples": { "not_found": { "$ref": "#/components/examples/not_found" }, "rate_limited": { "$ref": "#/components/examples/rate_limited" }, "validation_failed": { "$ref": "#/components/examples/validation_failed" } } } } }, "5XX": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "examples": { "not_found": { "$ref": "#/components/examples/not_found" }, "rate_limited": { "$ref": "#/components/examples/rate_limited" }, "validation_failed": { "$ref": "#/components/examples/validation_failed" } } } } } } } }, "/v1/organizations/{organization_id}/template-builds/{build_id}": { "get": { "operationId": "getV1OrganizationsOrganizationIdTemplateBuildsBuildId", "summary": "Get a template build: state, timestamps, bounds, provenance, results, failure, log tail and builder availability", "tags": [ "Template builds" ], "description": "Bounded wait: with `Prefer: wait=` (at most 20) and a build that is not settled (settled = failed, canceled, legacy succeeded, or published with registration registered/failed), the response is held until `state` or `registration.state` changes or the wait elapses, then carries the fresh build and `Preference-Applied: wait=`. Without `Preference-Applied` the server did not wait: poll with backoff.", "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "organization_id", "required": true, "description": "UUIDv7, lowercase canonical form." }, { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "build_id", "required": true, "description": "UUIDv7, lowercase canonical form." }, { "schema": { "type": "string", "maxLength": 200 }, "in": "header", "name": "prefer", "required": false, "description": "RFC 7240 preference, e.g. `wait=20`." } ], "security": [ { "apiKey": [] } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "required": [ "id", "organization_id", "template", "state", "target_version", "auto_publish", "published_at", "registration", "template_version", "cancel_requested_at", "created_at", "updated_at", "started_at", "completed_at", "requested_by", "base", "architecture", "bounds", "requested_bounds", "bound_sources", "network", "denied_hosts", "provenance", "result", "failure", "log", "publishable", "builder_availability", "source_kind", "source_workspace_id", "source_checkpoint_id", "scrub_result", "files", "produced_layer_id", "squashed", "org_bytes" ], "properties": { "id": { "type": "string", "format": "uuid", "description": "UUIDv7, lowercase canonical form." }, "organization_id": { "type": "string", "format": "uuid", "description": "UUIDv7, lowercase canonical form." }, "template": { "type": "object", "required": [ "id", "slug", "name" ], "properties": { "id": { "type": "string", "format": "uuid", "description": "UUIDv7, lowercase canonical form." }, "slug": { "type": "string" }, "name": { "type": "string" } }, "additionalProperties": false }, "state": { "type": "string", "enum": [ "queued", "building", "testing", "publishing", "published", "succeeded", "failed", "canceled" ], "description": "queued -> building -> testing -> publishing -> published (the cell stored the artifact; the API then registers the version, see `registration`) | failed | canceled. `succeeded` = legacy builds." }, "target_version": { "anyOf": [ { "type": "integer", "description": "Version number this build produces in its organization template (assigned at request time; never reused, so versions may have gaps). Null only for legacy builds." }, { "type": "null" } ] }, "auto_publish": { "type": "boolean", "description": "Publish the registered version at once (true), or leave it unpublished for the owner/admin publish route." }, "published_at": { "anyOf": [ { "type": "string", "format": "date-time", "description": "RFC 3339 UTC timestamp with Z." }, { "type": "null" } ] }, "registration": { "type": "object", "required": [ "state", "registered_at", "error" ], "properties": { "state": { "type": "string", "enum": [ "not_applicable", "pending", "registered", "failed" ] }, "registered_at": { "anyOf": [ { "type": "string", "format": "date-time", "description": "RFC 3339 UTC timestamp with Z." }, { "type": "null" } ] }, "error": { "anyOf": [ { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "additionalProperties": false }, { "type": "null" } ] } }, "additionalProperties": false, "description": "Creation of the immutable template version from a published build. not_applicable: not published (yet); pending: waiting for the API worker (error = last failed attempt, retried with backoff); registered; failed: retries exhausted (error says why)." }, "template_version": { "anyOf": [ { "type": "object", "required": [ "id", "version", "published" ], "properties": { "id": { "type": "string", "format": "uuid", "description": "UUIDv7, lowercase canonical form." }, "version": { "type": "integer" }, "published": { "type": "boolean" } }, "additionalProperties": false, "description": "The template version this build produced (once registered)." }, { "type": "null" } ] }, "cancel_requested_at": { "anyOf": [ { "type": "string", "format": "date-time", "description": "RFC 3339 UTC timestamp with Z." }, { "type": "null" } ] }, "created_at": { "type": "string", "format": "date-time", "description": "RFC 3339 UTC timestamp with Z." }, "updated_at": { "type": "string", "format": "date-time", "description": "RFC 3339 UTC timestamp with Z." }, "started_at": { "anyOf": [ { "type": "string", "format": "date-time", "description": "RFC 3339 UTC timestamp with Z." }, { "type": "null" } ] }, "completed_at": { "anyOf": [ { "type": "string", "format": "date-time", "description": "RFC 3339 UTC timestamp with Z." }, { "type": "null" } ] }, "requested_by": { "type": "object", "required": [ "type", "id" ], "properties": { "type": { "type": "string", "enum": [ "user", "api_key" ] }, "id": { "type": "string", "format": "uuid", "description": "UUIDv7, lowercase canonical form." } }, "additionalProperties": false }, "base": { "type": "object", "required": [ "ref", "template_id", "template_version_id", "slug", "version", "artifact_sha256" ], "properties": { "ref": { "type": "string" }, "template_id": { "type": "string", "format": "uuid", "description": "UUIDv7, lowercase canonical form." }, "template_version_id": { "type": "string", "format": "uuid", "description": "UUIDv7, lowercase canonical form." }, "slug": { "type": "string" }, "version": { "type": "integer" }, "artifact_sha256": { "type": "string" } }, "additionalProperties": false, "description": "The base template version, pinned at request time." }, "architecture": { "type": "string" }, "bounds": { "type": "object", "required": [ "cpu_millis", "memory_mib", "disk_gib", "timeout_seconds" ], "properties": { "cpu_millis": { "type": "integer" }, "memory_mib": { "type": "integer" }, "disk_gib": { "type": "integer" }, "timeout_seconds": { "type": "integer" } }, "additionalProperties": false }, "requested_bounds": { "type": "object", "required": [ "cpu_millis", "memory_mib", "disk_gib", "timeout_seconds" ], "properties": { "cpu_millis": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "memory_mib": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "disk_gib": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "timeout_seconds": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] } }, "additionalProperties": false }, "bound_sources": { "type": "object", "required": [ "cpu_millis", "memory_mib", "disk_gib", "timeout_seconds" ], "properties": { "cpu_millis": { "type": "string", "enum": [ "request", "plan", "platform" ] }, "memory_mib": { "type": "string", "enum": [ "request", "plan", "platform" ] }, "disk_gib": { "type": "string", "enum": [ "request", "plan", "platform" ] }, "timeout_seconds": { "type": "string", "enum": [ "request", "plan", "platform" ] } }, "additionalProperties": false, "description": "request: as asked; plan: clamped to (or defaulted from) the plan’s workspace limit; platform: build timeout default/maximum." }, "network": { "type": "object", "required": [ "mode", "allow_hosts" ], "properties": { "mode": { "type": "string", "enum": [ "none", "egress_allowlist" ] }, "allow_hosts": { "type": "array", "items": { "type": "string" } } }, "additionalProperties": false, "description": "The build network (recipe v2: compiled.network, derived from the recipe for `auto`)." }, "denied_hosts": { "type": "array", "items": { "type": "string" }, "description": "Host names the builder’s DNS proxy refused during the build (at most 50). Rebuild with a host in build.network.extra_hosts to allow it." }, "provenance": { "type": "object", "required": [ "recipe_schema", "recipe_sha256", "base_artifact_sha256", "builder_id", "attempt" ], "properties": { "recipe_schema": { "anyOf": [ { "type": "string", "description": "Null for workspace-source builds." }, { "type": "null" } ] }, "recipe_sha256": { "anyOf": [ { "type": "string", "description": "SHA-256 of the canonical recipe JSON (the build’s source input); null for workspace-source builds." }, { "type": "null" } ] }, "base_artifact_sha256": { "type": "string" }, "builder_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "attempt": { "type": "integer" } }, "additionalProperties": false }, "recipe": { "anyOf": [ { "type": "object", "required": [ "dockerfile" ], "properties": { "dockerfile": { "type": "string" } }, "additionalProperties": false }, { "type": "object", "required": [ "schema", "build", "settings", "compiled" ], "properties": { "schema": { "type": "string", "enum": [ "shardflux.template-recipe.v2" ] }, "build": { "type": "object", "required": [ "languages", "packages", "files", "steps", "network" ], "properties": { "languages": { "type": "array", "items": { "type": "object", "required": [ "id", "version", "source", "url", "sha256" ], "properties": { "id": { "type": "string" }, "version": { "type": "string" }, "source": { "type": "string", "enum": [ "install", "base" ] }, "url": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "sha256": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "additionalProperties": false }, "description": "Resolved languages in compile order (implied ones included); source base = the base already has it." }, "packages": { "type": "object", "required": [ "apt", "pip", "npm" ], "properties": { "apt": { "type": "array", "items": { "type": "string" } }, "pip": { "type": "object", "required": [ "packages", "requirements" ], "properties": { "packages": { "type": "array", "items": { "type": "string" } }, "requirements": { "type": "array", "items": { "type": "string" } } }, "additionalProperties": false }, "npm": { "type": "array", "items": { "type": "string" } } }, "additionalProperties": false }, "files": { "type": "array", "items": { "type": "object", "required": [ "upload", "kind", "to", "owner", "mode", "size" ], "properties": { "upload": { "type": "string" }, "kind": { "type": "string", "enum": [ "file", "tar" ] }, "to": { "type": "string" }, "owner": { "type": "string" }, "mode": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "size": { "type": "integer" } }, "additionalProperties": false } }, "steps": { "type": "array", "items": { "type": "object", "required": [ "name", "run", "user", "cwd", "env" ], "properties": { "name": { "type": "string" }, "run": { "type": "string" }, "user": { "type": "string" }, "cwd": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "env": { "type": "object", "additionalProperties": { "type": "string" } } }, "additionalProperties": false } }, "network": { "type": "object", "required": [ "build", "extra_hosts", "allow_hosts" ], "properties": { "build": { "type": "string", "enum": [ "auto", "none", "allowlist" ] }, "extra_hosts": { "type": "array", "items": { "type": "string" } }, "allow_hosts": { "type": "array", "items": { "type": "string" } } }, "additionalProperties": false } }, "additionalProperties": false }, "settings": { "$ref": "#/components/schemas/TemplateSettings" }, "compiled": { "type": "object", "required": [ "compiler", "language_table_sha256", "build_env", "steps", "tools", "network", "objects" ], "properties": { "compiler": { "type": "string" }, "language_table_sha256": { "type": "string" }, "build_env": { "type": "object", "additionalProperties": { "type": "string" } }, "steps": { "type": "array", "items": { "type": "object", "properties": {}, "additionalProperties": true, "description": "A host.v1 RecipeStep in protojson (proto field names, defaults omitted)." } }, "tools": { "type": "array", "items": { "type": "object", "required": [ "name", "argv" ], "properties": { "name": { "type": "string" }, "argv": { "type": "array", "items": { "type": "string" } } }, "additionalProperties": false } }, "network": { "type": "object", "required": [ "mode", "allow_hosts" ], "properties": { "mode": { "type": "string", "enum": [ "none", "egress_allowlist" ] }, "allow_hosts": { "type": "array", "items": { "type": "string" } } }, "additionalProperties": false }, "objects": { "type": "array", "items": { "type": "object", "required": [ "sha256", "size", "kind" ], "properties": { "sha256": { "type": "string" }, "size": { "type": "integer" }, "kind": { "type": "string", "enum": [ "file", "tar" ] } }, "additionalProperties": false } } }, "additionalProperties": false } }, "additionalProperties": false } ], "description": "Only on GET of one build: recipe v1 {dockerfile}, or recipe v2 {schema, build, settings, compiled} (the stored document)." }, "result": { "type": "object", "required": [ "artifact_sha256", "scan", "compatibility", "produced_version" ], "properties": { "artifact_sha256": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "scan": { "anyOf": [ { "type": "object", "properties": {}, "additionalProperties": true, "description": "Scanner result recorded by the builder ({passed, scanner, scanner_version, summary})." }, { "type": "null" } ] }, "compatibility": { "anyOf": [ { "type": "object", "properties": {}, "additionalProperties": true, "description": "Guest compatibility test result ({passed, runtime_class, kernel_release, firecracker_version, guest_agent_version, checks})." }, { "type": "null" } ] }, "produced_version": { "anyOf": [ { "type": "object", "required": [ "id", "version", "state", "published_at", "archived_at" ], "properties": { "id": { "type": "string", "format": "uuid", "description": "UUIDv7, lowercase canonical form." }, "version": { "type": "integer" }, "state": { "type": "string", "enum": [ "unpublished", "published", "archived" ] }, "published_at": { "anyOf": [ { "type": "string", "format": "date-time", "description": "RFC 3339 UTC timestamp with Z." }, { "type": "null" } ] }, "archived_at": { "anyOf": [ { "type": "string", "format": "date-time", "description": "RFC 3339 UTC timestamp with Z." }, { "type": "null" } ] } }, "additionalProperties": false }, { "type": "null" } ] } }, "additionalProperties": false }, "failure": { "anyOf": [ { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "additionalProperties": false }, { "type": "null" } ] }, "log": { "type": "object", "required": [ "state", "bytes", "sha256", "expires_at", "downloadable" ], "properties": { "state": { "type": "string", "enum": [ "none", "available", "expired" ] }, "bytes": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "sha256": { "anyOf": [ { "type": "string", "description": "SHA-256 of the full log object, when the builder recorded it." }, { "type": "null" } ] }, "expires_at": { "anyOf": [ { "type": "string", "format": "date-time", "description": "RFC 3339 UTC timestamp with Z." }, { "type": "null" } ] }, "downloadable": { "type": "boolean", "description": "The full log can be downloaded through GET .../template-builds/{id}/log-url (short-lived signed URL)." }, "tail": { "anyOf": [ { "type": "string", "description": "Last <= 64 KiB of the build log (GET of one build; until expires_at)." }, { "type": "null" } ] } }, "additionalProperties": false, "description": "Build log: the tail inline, the full log through a short-lived signed URL (log-url)." }, "publishable": { "type": "boolean" }, "builder_availability": { "type": "object", "required": [ "state", "reason", "active_builders", "last_heartbeat_at" ], "properties": { "state": { "type": "string", "enum": [ "available", "unavailable" ] }, "reason": { "anyOf": [ { "type": "string", "enum": [ "no_builder_registered", "no_recent_heartbeat" ] }, { "type": "null" } ] }, "active_builders": { "type": "integer" }, "last_heartbeat_at": { "anyOf": [ { "type": "string", "format": "date-time", "description": "RFC 3339 UTC timestamp with Z." }, { "type": "null" } ] } }, "additionalProperties": false, "description": "From builder heartbeats (app.template_builders, 60 s window). `unavailable`: queued builds wait until a builder runs." }, "source_kind": { "type": "string", "enum": [ "recipe", "workspace" ], "description": "recipe (recipe v1 Dockerfile dialect or recipe v2) or workspace (save-as-template, draft publish)." }, "source_workspace_id": { "anyOf": [ { "type": "string", "format": "uuid", "description": "UUIDv7, lowercase canonical form." }, { "type": "null" } ] }, "source_checkpoint_id": { "anyOf": [ { "type": "string", "description": "The saved checkpoint (filled when the capture finished and the cell claimed the build)." }, { "type": "null" } ] }, "scrub_result": { "anyOf": [ { "type": "object", "properties": {}, "additionalProperties": true, "description": "sf-scrub.v1 report ({policy, removed_count, removed_bytes, removed_paths (first 1000), emptied, reimposed}); paths only, never contents." }, { "type": "null" } ] }, "files": { "anyOf": [ { "type": "object", "properties": {}, "additionalProperties": true, "description": "The produced file list ({key, size, sha256, content_sha256, entries, total_file_bytes})." }, { "type": "null" } ] }, "produced_layer_id": { "anyOf": [ { "type": "string", "format": "uuid", "description": "UUIDv7, lowercase canonical form." }, { "type": "null" } ] }, "squashed": { "anyOf": [ { "type": "boolean", "description": "The base chain already had 4 org layers: this build squashed them into its one layer." }, { "type": "null" } ] }, "org_bytes": { "anyOf": [ { "type": "integer", "description": "The produced chain’s org bytes (limited by the plan’s workspace disk limit)." }, { "type": "null" } ] } }, "additionalProperties": false } } } }, "4XX": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "examples": { "not_found": { "$ref": "#/components/examples/not_found" }, "rate_limited": { "$ref": "#/components/examples/rate_limited" }, "validation_failed": { "$ref": "#/components/examples/validation_failed" } } } } }, "5XX": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "examples": { "not_found": { "$ref": "#/components/examples/not_found" }, "rate_limited": { "$ref": "#/components/examples/rate_limited" }, "validation_failed": { "$ref": "#/components/examples/validation_failed" } } } } } } } }, "/v1/organizations/{organization_id}/template-builds/{build_id}/cancel": { "post": { "operationId": "postV1OrganizationsOrganizationIdTemplateBuildsBuildIdCancel", "summary": "Cancel a template build", "tags": [ "Template builds" ], "description": "queued -> canceled (200); building/testing/publishing -> cancellation requested (202; honoured until the artifact upload starts, so a build in `publishing` may still end `published`); canceled -> unchanged (200); published/succeeded/failed -> 409 build_finished. API keys may cancel only builds they requested.", "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "organization_id", "required": true, "description": "UUIDv7, lowercase canonical form." }, { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "build_id", "required": true, "description": "UUIDv7, lowercase canonical form." } ], "security": [ { "apiKey": [] } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "required": [ "id", "organization_id", "template", "state", "target_version", "auto_publish", "published_at", "registration", "template_version", "cancel_requested_at", "created_at", "updated_at", "started_at", "completed_at", "requested_by", "base", "architecture", "bounds", "requested_bounds", "bound_sources", "network", "denied_hosts", "provenance", "result", "failure", "log", "publishable", "builder_availability", "source_kind", "source_workspace_id", "source_checkpoint_id", "scrub_result", "files", "produced_layer_id", "squashed", "org_bytes" ], "properties": { "id": { "type": "string", "format": "uuid", "description": "UUIDv7, lowercase canonical form." }, "organization_id": { "type": "string", "format": "uuid", "description": "UUIDv7, lowercase canonical form." }, "template": { "type": "object", "required": [ "id", "slug", "name" ], "properties": { "id": { "type": "string", "format": "uuid", "description": "UUIDv7, lowercase canonical form." }, "slug": { "type": "string" }, "name": { "type": "string" } }, "additionalProperties": false }, "state": { "type": "string", "enum": [ "queued", "building", "testing", "publishing", "published", "succeeded", "failed", "canceled" ], "description": "queued -> building -> testing -> publishing -> published (the cell stored the artifact; the API then registers the version, see `registration`) | failed | canceled. `succeeded` = legacy builds." }, "target_version": { "anyOf": [ { "type": "integer", "description": "Version number this build produces in its organization template (assigned at request time; never reused, so versions may have gaps). Null only for legacy builds." }, { "type": "null" } ] }, "auto_publish": { "type": "boolean", "description": "Publish the registered version at once (true), or leave it unpublished for the owner/admin publish route." }, "published_at": { "anyOf": [ { "type": "string", "format": "date-time", "description": "RFC 3339 UTC timestamp with Z." }, { "type": "null" } ] }, "registration": { "type": "object", "required": [ "state", "registered_at", "error" ], "properties": { "state": { "type": "string", "enum": [ "not_applicable", "pending", "registered", "failed" ] }, "registered_at": { "anyOf": [ { "type": "string", "format": "date-time", "description": "RFC 3339 UTC timestamp with Z." }, { "type": "null" } ] }, "error": { "anyOf": [ { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "additionalProperties": false }, { "type": "null" } ] } }, "additionalProperties": false, "description": "Creation of the immutable template version from a published build. not_applicable: not published (yet); pending: waiting for the API worker (error = last failed attempt, retried with backoff); registered; failed: retries exhausted (error says why)." }, "template_version": { "anyOf": [ { "type": "object", "required": [ "id", "version", "published" ], "properties": { "id": { "type": "string", "format": "uuid", "description": "UUIDv7, lowercase canonical form." }, "version": { "type": "integer" }, "published": { "type": "boolean" } }, "additionalProperties": false, "description": "The template version this build produced (once registered)." }, { "type": "null" } ] }, "cancel_requested_at": { "anyOf": [ { "type": "string", "format": "date-time", "description": "RFC 3339 UTC timestamp with Z." }, { "type": "null" } ] }, "created_at": { "type": "string", "format": "date-time", "description": "RFC 3339 UTC timestamp with Z." }, "updated_at": { "type": "string", "format": "date-time", "description": "RFC 3339 UTC timestamp with Z." }, "started_at": { "anyOf": [ { "type": "string", "format": "date-time", "description": "RFC 3339 UTC timestamp with Z." }, { "type": "null" } ] }, "completed_at": { "anyOf": [ { "type": "string", "format": "date-time", "description": "RFC 3339 UTC timestamp with Z." }, { "type": "null" } ] }, "requested_by": { "type": "object", "required": [ "type", "id" ], "properties": { "type": { "type": "string", "enum": [ "user", "api_key" ] }, "id": { "type": "string", "format": "uuid", "description": "UUIDv7, lowercase canonical form." } }, "additionalProperties": false }, "base": { "type": "object", "required": [ "ref", "template_id", "template_version_id", "slug", "version", "artifact_sha256" ], "properties": { "ref": { "type": "string" }, "template_id": { "type": "string", "format": "uuid", "description": "UUIDv7, lowercase canonical form." }, "template_version_id": { "type": "string", "format": "uuid", "description": "UUIDv7, lowercase canonical form." }, "slug": { "type": "string" }, "version": { "type": "integer" }, "artifact_sha256": { "type": "string" } }, "additionalProperties": false, "description": "The base template version, pinned at request time." }, "architecture": { "type": "string" }, "bounds": { "type": "object", "required": [ "cpu_millis", "memory_mib", "disk_gib", "timeout_seconds" ], "properties": { "cpu_millis": { "type": "integer" }, "memory_mib": { "type": "integer" }, "disk_gib": { "type": "integer" }, "timeout_seconds": { "type": "integer" } }, "additionalProperties": false }, "requested_bounds": { "type": "object", "required": [ "cpu_millis", "memory_mib", "disk_gib", "timeout_seconds" ], "properties": { "cpu_millis": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "memory_mib": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "disk_gib": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "timeout_seconds": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] } }, "additionalProperties": false }, "bound_sources": { "type": "object", "required": [ "cpu_millis", "memory_mib", "disk_gib", "timeout_seconds" ], "properties": { "cpu_millis": { "type": "string", "enum": [ "request", "plan", "platform" ] }, "memory_mib": { "type": "string", "enum": [ "request", "plan", "platform" ] }, "disk_gib": { "type": "string", "enum": [ "request", "plan", "platform" ] }, "timeout_seconds": { "type": "string", "enum": [ "request", "plan", "platform" ] } }, "additionalProperties": false, "description": "request: as asked; plan: clamped to (or defaulted from) the plan’s workspace limit; platform: build timeout default/maximum." }, "network": { "type": "object", "required": [ "mode", "allow_hosts" ], "properties": { "mode": { "type": "string", "enum": [ "none", "egress_allowlist" ] }, "allow_hosts": { "type": "array", "items": { "type": "string" } } }, "additionalProperties": false, "description": "The build network (recipe v2: compiled.network, derived from the recipe for `auto`)." }, "denied_hosts": { "type": "array", "items": { "type": "string" }, "description": "Host names the builder’s DNS proxy refused during the build (at most 50). Rebuild with a host in build.network.extra_hosts to allow it." }, "provenance": { "type": "object", "required": [ "recipe_schema", "recipe_sha256", "base_artifact_sha256", "builder_id", "attempt" ], "properties": { "recipe_schema": { "anyOf": [ { "type": "string", "description": "Null for workspace-source builds." }, { "type": "null" } ] }, "recipe_sha256": { "anyOf": [ { "type": "string", "description": "SHA-256 of the canonical recipe JSON (the build’s source input); null for workspace-source builds." }, { "type": "null" } ] }, "base_artifact_sha256": { "type": "string" }, "builder_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "attempt": { "type": "integer" } }, "additionalProperties": false }, "recipe": { "anyOf": [ { "type": "object", "required": [ "dockerfile" ], "properties": { "dockerfile": { "type": "string" } }, "additionalProperties": false }, { "type": "object", "required": [ "schema", "build", "settings", "compiled" ], "properties": { "schema": { "type": "string", "enum": [ "shardflux.template-recipe.v2" ] }, "build": { "type": "object", "required": [ "languages", "packages", "files", "steps", "network" ], "properties": { "languages": { "type": "array", "items": { "type": "object", "required": [ "id", "version", "source", "url", "sha256" ], "properties": { "id": { "type": "string" }, "version": { "type": "string" }, "source": { "type": "string", "enum": [ "install", "base" ] }, "url": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "sha256": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "additionalProperties": false }, "description": "Resolved languages in compile order (implied ones included); source base = the base already has it." }, "packages": { "type": "object", "required": [ "apt", "pip", "npm" ], "properties": { "apt": { "type": "array", "items": { "type": "string" } }, "pip": { "type": "object", "required": [ "packages", "requirements" ], "properties": { "packages": { "type": "array", "items": { "type": "string" } }, "requirements": { "type": "array", "items": { "type": "string" } } }, "additionalProperties": false }, "npm": { "type": "array", "items": { "type": "string" } } }, "additionalProperties": false }, "files": { "type": "array", "items": { "type": "object", "required": [ "upload", "kind", "to", "owner", "mode", "size" ], "properties": { "upload": { "type": "string" }, "kind": { "type": "string", "enum": [ "file", "tar" ] }, "to": { "type": "string" }, "owner": { "type": "string" }, "mode": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "size": { "type": "integer" } }, "additionalProperties": false } }, "steps": { "type": "array", "items": { "type": "object", "required": [ "name", "run", "user", "cwd", "env" ], "properties": { "name": { "type": "string" }, "run": { "type": "string" }, "user": { "type": "string" }, "cwd": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "env": { "type": "object", "additionalProperties": { "type": "string" } } }, "additionalProperties": false } }, "network": { "type": "object", "required": [ "build", "extra_hosts", "allow_hosts" ], "properties": { "build": { "type": "string", "enum": [ "auto", "none", "allowlist" ] }, "extra_hosts": { "type": "array", "items": { "type": "string" } }, "allow_hosts": { "type": "array", "items": { "type": "string" } } }, "additionalProperties": false } }, "additionalProperties": false }, "settings": { "$ref": "#/components/schemas/TemplateSettings" }, "compiled": { "type": "object", "required": [ "compiler", "language_table_sha256", "build_env", "steps", "tools", "network", "objects" ], "properties": { "compiler": { "type": "string" }, "language_table_sha256": { "type": "string" }, "build_env": { "type": "object", "additionalProperties": { "type": "string" } }, "steps": { "type": "array", "items": { "type": "object", "properties": {}, "additionalProperties": true, "description": "A host.v1 RecipeStep in protojson (proto field names, defaults omitted)." } }, "tools": { "type": "array", "items": { "type": "object", "required": [ "name", "argv" ], "properties": { "name": { "type": "string" }, "argv": { "type": "array", "items": { "type": "string" } } }, "additionalProperties": false } }, "network": { "type": "object", "required": [ "mode", "allow_hosts" ], "properties": { "mode": { "type": "string", "enum": [ "none", "egress_allowlist" ] }, "allow_hosts": { "type": "array", "items": { "type": "string" } } }, "additionalProperties": false }, "objects": { "type": "array", "items": { "type": "object", "required": [ "sha256", "size", "kind" ], "properties": { "sha256": { "type": "string" }, "size": { "type": "integer" }, "kind": { "type": "string", "enum": [ "file", "tar" ] } }, "additionalProperties": false } } }, "additionalProperties": false } }, "additionalProperties": false } ], "description": "Only on GET of one build: recipe v1 {dockerfile}, or recipe v2 {schema, build, settings, compiled} (the stored document)." }, "result": { "type": "object", "required": [ "artifact_sha256", "scan", "compatibility", "produced_version" ], "properties": { "artifact_sha256": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "scan": { "anyOf": [ { "type": "object", "properties": {}, "additionalProperties": true, "description": "Scanner result recorded by the builder ({passed, scanner, scanner_version, summary})." }, { "type": "null" } ] }, "compatibility": { "anyOf": [ { "type": "object", "properties": {}, "additionalProperties": true, "description": "Guest compatibility test result ({passed, runtime_class, kernel_release, firecracker_version, guest_agent_version, checks})." }, { "type": "null" } ] }, "produced_version": { "anyOf": [ { "type": "object", "required": [ "id", "version", "state", "published_at", "archived_at" ], "properties": { "id": { "type": "string", "format": "uuid", "description": "UUIDv7, lowercase canonical form." }, "version": { "type": "integer" }, "state": { "type": "string", "enum": [ "unpublished", "published", "archived" ] }, "published_at": { "anyOf": [ { "type": "string", "format": "date-time", "description": "RFC 3339 UTC timestamp with Z." }, { "type": "null" } ] }, "archived_at": { "anyOf": [ { "type": "string", "format": "date-time", "description": "RFC 3339 UTC timestamp with Z." }, { "type": "null" } ] } }, "additionalProperties": false }, { "type": "null" } ] } }, "additionalProperties": false }, "failure": { "anyOf": [ { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "additionalProperties": false }, { "type": "null" } ] }, "log": { "type": "object", "required": [ "state", "bytes", "sha256", "expires_at", "downloadable" ], "properties": { "state": { "type": "string", "enum": [ "none", "available", "expired" ] }, "bytes": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "sha256": { "anyOf": [ { "type": "string", "description": "SHA-256 of the full log object, when the builder recorded it." }, { "type": "null" } ] }, "expires_at": { "anyOf": [ { "type": "string", "format": "date-time", "description": "RFC 3339 UTC timestamp with Z." }, { "type": "null" } ] }, "downloadable": { "type": "boolean", "description": "The full log can be downloaded through GET .../template-builds/{id}/log-url (short-lived signed URL)." }, "tail": { "anyOf": [ { "type": "string", "description": "Last <= 64 KiB of the build log (GET of one build; until expires_at)." }, { "type": "null" } ] } }, "additionalProperties": false, "description": "Build log: the tail inline, the full log through a short-lived signed URL (log-url)." }, "publishable": { "type": "boolean" }, "builder_availability": { "type": "object", "required": [ "state", "reason", "active_builders", "last_heartbeat_at" ], "properties": { "state": { "type": "string", "enum": [ "available", "unavailable" ] }, "reason": { "anyOf": [ { "type": "string", "enum": [ "no_builder_registered", "no_recent_heartbeat" ] }, { "type": "null" } ] }, "active_builders": { "type": "integer" }, "last_heartbeat_at": { "anyOf": [ { "type": "string", "format": "date-time", "description": "RFC 3339 UTC timestamp with Z." }, { "type": "null" } ] } }, "additionalProperties": false, "description": "From builder heartbeats (app.template_builders, 60 s window). `unavailable`: queued builds wait until a builder runs." }, "source_kind": { "type": "string", "enum": [ "recipe", "workspace" ], "description": "recipe (recipe v1 Dockerfile dialect or recipe v2) or workspace (save-as-template, draft publish)." }, "source_workspace_id": { "anyOf": [ { "type": "string", "format": "uuid", "description": "UUIDv7, lowercase canonical form." }, { "type": "null" } ] }, "source_checkpoint_id": { "anyOf": [ { "type": "string", "description": "The saved checkpoint (filled when the capture finished and the cell claimed the build)." }, { "type": "null" } ] }, "scrub_result": { "anyOf": [ { "type": "object", "properties": {}, "additionalProperties": true, "description": "sf-scrub.v1 report ({policy, removed_count, removed_bytes, removed_paths (first 1000), emptied, reimposed}); paths only, never contents." }, { "type": "null" } ] }, "files": { "anyOf": [ { "type": "object", "properties": {}, "additionalProperties": true, "description": "The produced file list ({key, size, sha256, content_sha256, entries, total_file_bytes})." }, { "type": "null" } ] }, "produced_layer_id": { "anyOf": [ { "type": "string", "format": "uuid", "description": "UUIDv7, lowercase canonical form." }, { "type": "null" } ] }, "squashed": { "anyOf": [ { "type": "boolean", "description": "The base chain already had 4 org layers: this build squashed them into its one layer." }, { "type": "null" } ] }, "org_bytes": { "anyOf": [ { "type": "integer", "description": "The produced chain’s org bytes (limited by the plan’s workspace disk limit)." }, { "type": "null" } ] } }, "additionalProperties": false } } } }, "202": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "required": [ "id", "organization_id", "template", "state", "target_version", "auto_publish", "published_at", "registration", "template_version", "cancel_requested_at", "created_at", "updated_at", "started_at", "completed_at", "requested_by", "base", "architecture", "bounds", "requested_bounds", "bound_sources", "network", "denied_hosts", "provenance", "result", "failure", "log", "publishable", "builder_availability", "source_kind", "source_workspace_id", "source_checkpoint_id", "scrub_result", "files", "produced_layer_id", "squashed", "org_bytes" ], "properties": { "id": { "type": "string", "format": "uuid", "description": "UUIDv7, lowercase canonical form." }, "organization_id": { "type": "string", "format": "uuid", "description": "UUIDv7, lowercase canonical form." }, "template": { "type": "object", "required": [ "id", "slug", "name" ], "properties": { "id": { "type": "string", "format": "uuid", "description": "UUIDv7, lowercase canonical form." }, "slug": { "type": "string" }, "name": { "type": "string" } }, "additionalProperties": false }, "state": { "type": "string", "enum": [ "queued", "building", "testing", "publishing", "published", "succeeded", "failed", "canceled" ], "description": "queued -> building -> testing -> publishing -> published (the cell stored the artifact; the API then registers the version, see `registration`) | failed | canceled. `succeeded` = legacy builds." }, "target_version": { "anyOf": [ { "type": "integer", "description": "Version number this build produces in its organization template (assigned at request time; never reused, so versions may have gaps). Null only for legacy builds." }, { "type": "null" } ] }, "auto_publish": { "type": "boolean", "description": "Publish the registered version at once (true), or leave it unpublished for the owner/admin publish route." }, "published_at": { "anyOf": [ { "type": "string", "format": "date-time", "description": "RFC 3339 UTC timestamp with Z." }, { "type": "null" } ] }, "registration": { "type": "object", "required": [ "state", "registered_at", "error" ], "properties": { "state": { "type": "string", "enum": [ "not_applicable", "pending", "registered", "failed" ] }, "registered_at": { "anyOf": [ { "type": "string", "format": "date-time", "description": "RFC 3339 UTC timestamp with Z." }, { "type": "null" } ] }, "error": { "anyOf": [ { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "additionalProperties": false }, { "type": "null" } ] } }, "additionalProperties": false, "description": "Creation of the immutable template version from a published build. not_applicable: not published (yet); pending: waiting for the API worker (error = last failed attempt, retried with backoff); registered; failed: retries exhausted (error says why)." }, "template_version": { "anyOf": [ { "type": "object", "required": [ "id", "version", "published" ], "properties": { "id": { "type": "string", "format": "uuid", "description": "UUIDv7, lowercase canonical form." }, "version": { "type": "integer" }, "published": { "type": "boolean" } }, "additionalProperties": false, "description": "The template version this build produced (once registered)." }, { "type": "null" } ] }, "cancel_requested_at": { "anyOf": [ { "type": "string", "format": "date-time", "description": "RFC 3339 UTC timestamp with Z." }, { "type": "null" } ] }, "created_at": { "type": "string", "format": "date-time", "description": "RFC 3339 UTC timestamp with Z." }, "updated_at": { "type": "string", "format": "date-time", "description": "RFC 3339 UTC timestamp with Z." }, "started_at": { "anyOf": [ { "type": "string", "format": "date-time", "description": "RFC 3339 UTC timestamp with Z." }, { "type": "null" } ] }, "completed_at": { "anyOf": [ { "type": "string", "format": "date-time", "description": "RFC 3339 UTC timestamp with Z." }, { "type": "null" } ] }, "requested_by": { "type": "object", "required": [ "type", "id" ], "properties": { "type": { "type": "string", "enum": [ "user", "api_key" ] }, "id": { "type": "string", "format": "uuid", "description": "UUIDv7, lowercase canonical form." } }, "additionalProperties": false }, "base": { "type": "object", "required": [ "ref", "template_id", "template_version_id", "slug", "version", "artifact_sha256" ], "properties": { "ref": { "type": "string" }, "template_id": { "type": "string", "format": "uuid", "description": "UUIDv7, lowercase canonical form." }, "template_version_id": { "type": "string", "format": "uuid", "description": "UUIDv7, lowercase canonical form." }, "slug": { "type": "string" }, "version": { "type": "integer" }, "artifact_sha256": { "type": "string" } }, "additionalProperties": false, "description": "The base template version, pinned at request time." }, "architecture": { "type": "string" }, "bounds": { "type": "object", "required": [ "cpu_millis", "memory_mib", "disk_gib", "timeout_seconds" ], "properties": { "cpu_millis": { "type": "integer" }, "memory_mib": { "type": "integer" }, "disk_gib": { "type": "integer" }, "timeout_seconds": { "type": "integer" } }, "additionalProperties": false }, "requested_bounds": { "type": "object", "required": [ "cpu_millis", "memory_mib", "disk_gib", "timeout_seconds" ], "properties": { "cpu_millis": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "memory_mib": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "disk_gib": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "timeout_seconds": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] } }, "additionalProperties": false }, "bound_sources": { "type": "object", "required": [ "cpu_millis", "memory_mib", "disk_gib", "timeout_seconds" ], "properties": { "cpu_millis": { "type": "string", "enum": [ "request", "plan", "platform" ] }, "memory_mib": { "type": "string", "enum": [ "request", "plan", "platform" ] }, "disk_gib": { "type": "string", "enum": [ "request", "plan", "platform" ] }, "timeout_seconds": { "type": "string", "enum": [ "request", "plan", "platform" ] } }, "additionalProperties": false, "description": "request: as asked; plan: clamped to (or defaulted from) the plan’s workspace limit; platform: build timeout default/maximum." }, "network": { "type": "object", "required": [ "mode", "allow_hosts" ], "properties": { "mode": { "type": "string", "enum": [ "none", "egress_allowlist" ] }, "allow_hosts": { "type": "array", "items": { "type": "string" } } }, "additionalProperties": false, "description": "The build network (recipe v2: compiled.network, derived from the recipe for `auto`)." }, "denied_hosts": { "type": "array", "items": { "type": "string" }, "description": "Host names the builder’s DNS proxy refused during the build (at most 50). Rebuild with a host in build.network.extra_hosts to allow it." }, "provenance": { "type": "object", "required": [ "recipe_schema", "recipe_sha256", "base_artifact_sha256", "builder_id", "attempt" ], "properties": { "recipe_schema": { "anyOf": [ { "type": "string", "description": "Null for workspace-source builds." }, { "type": "null" } ] }, "recipe_sha256": { "anyOf": [ { "type": "string", "description": "SHA-256 of the canonical recipe JSON (the build’s source input); null for workspace-source builds." }, { "type": "null" } ] }, "base_artifact_sha256": { "type": "string" }, "builder_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "attempt": { "type": "integer" } }, "additionalProperties": false }, "recipe": { "anyOf": [ { "type": "object", "required": [ "dockerfile" ], "properties": { "dockerfile": { "type": "string" } }, "additionalProperties": false }, { "type": "object", "required": [ "schema", "build", "settings", "compiled" ], "properties": { "schema": { "type": "string", "enum": [ "shardflux.template-recipe.v2" ] }, "build": { "type": "object", "required": [ "languages", "packages", "files", "steps", "network" ], "properties": { "languages": { "type": "array", "items": { "type": "object", "required": [ "id", "version", "source", "url", "sha256" ], "properties": { "id": { "type": "string" }, "version": { "type": "string" }, "source": { "type": "string", "enum": [ "install", "base" ] }, "url": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "sha256": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "additionalProperties": false }, "description": "Resolved languages in compile order (implied ones included); source base = the base already has it." }, "packages": { "type": "object", "required": [ "apt", "pip", "npm" ], "properties": { "apt": { "type": "array", "items": { "type": "string" } }, "pip": { "type": "object", "required": [ "packages", "requirements" ], "properties": { "packages": { "type": "array", "items": { "type": "string" } }, "requirements": { "type": "array", "items": { "type": "string" } } }, "additionalProperties": false }, "npm": { "type": "array", "items": { "type": "string" } } }, "additionalProperties": false }, "files": { "type": "array", "items": { "type": "object", "required": [ "upload", "kind", "to", "owner", "mode", "size" ], "properties": { "upload": { "type": "string" }, "kind": { "type": "string", "enum": [ "file", "tar" ] }, "to": { "type": "string" }, "owner": { "type": "string" }, "mode": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "size": { "type": "integer" } }, "additionalProperties": false } }, "steps": { "type": "array", "items": { "type": "object", "required": [ "name", "run", "user", "cwd", "env" ], "properties": { "name": { "type": "string" }, "run": { "type": "string" }, "user": { "type": "string" }, "cwd": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "env": { "type": "object", "additionalProperties": { "type": "string" } } }, "additionalProperties": false } }, "network": { "type": "object", "required": [ "build", "extra_hosts", "allow_hosts" ], "properties": { "build": { "type": "string", "enum": [ "auto", "none", "allowlist" ] }, "extra_hosts": { "type": "array", "items": { "type": "string" } }, "allow_hosts": { "type": "array", "items": { "type": "string" } } }, "additionalProperties": false } }, "additionalProperties": false }, "settings": { "$ref": "#/components/schemas/TemplateSettings" }, "compiled": { "type": "object", "required": [ "compiler", "language_table_sha256", "build_env", "steps", "tools", "network", "objects" ], "properties": { "compiler": { "type": "string" }, "language_table_sha256": { "type": "string" }, "build_env": { "type": "object", "additionalProperties": { "type": "string" } }, "steps": { "type": "array", "items": { "type": "object", "properties": {}, "additionalProperties": true, "description": "A host.v1 RecipeStep in protojson (proto field names, defaults omitted)." } }, "tools": { "type": "array", "items": { "type": "object", "required": [ "name", "argv" ], "properties": { "name": { "type": "string" }, "argv": { "type": "array", "items": { "type": "string" } } }, "additionalProperties": false } }, "network": { "type": "object", "required": [ "mode", "allow_hosts" ], "properties": { "mode": { "type": "string", "enum": [ "none", "egress_allowlist" ] }, "allow_hosts": { "type": "array", "items": { "type": "string" } } }, "additionalProperties": false }, "objects": { "type": "array", "items": { "type": "object", "required": [ "sha256", "size", "kind" ], "properties": { "sha256": { "type": "string" }, "size": { "type": "integer" }, "kind": { "type": "string", "enum": [ "file", "tar" ] } }, "additionalProperties": false } } }, "additionalProperties": false } }, "additionalProperties": false } ], "description": "Only on GET of one build: recipe v1 {dockerfile}, or recipe v2 {schema, build, settings, compiled} (the stored document)." }, "result": { "type": "object", "required": [ "artifact_sha256", "scan", "compatibility", "produced_version" ], "properties": { "artifact_sha256": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "scan": { "anyOf": [ { "type": "object", "properties": {}, "additionalProperties": true, "description": "Scanner result recorded by the builder ({passed, scanner, scanner_version, summary})." }, { "type": "null" } ] }, "compatibility": { "anyOf": [ { "type": "object", "properties": {}, "additionalProperties": true, "description": "Guest compatibility test result ({passed, runtime_class, kernel_release, firecracker_version, guest_agent_version, checks})." }, { "type": "null" } ] }, "produced_version": { "anyOf": [ { "type": "object", "required": [ "id", "version", "state", "published_at", "archived_at" ], "properties": { "id": { "type": "string", "format": "uuid", "description": "UUIDv7, lowercase canonical form." }, "version": { "type": "integer" }, "state": { "type": "string", "enum": [ "unpublished", "published", "archived" ] }, "published_at": { "anyOf": [ { "type": "string", "format": "date-time", "description": "RFC 3339 UTC timestamp with Z." }, { "type": "null" } ] }, "archived_at": { "anyOf": [ { "type": "string", "format": "date-time", "description": "RFC 3339 UTC timestamp with Z." }, { "type": "null" } ] } }, "additionalProperties": false }, { "type": "null" } ] } }, "additionalProperties": false }, "failure": { "anyOf": [ { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "additionalProperties": false }, { "type": "null" } ] }, "log": { "type": "object", "required": [ "state", "bytes", "sha256", "expires_at", "downloadable" ], "properties": { "state": { "type": "string", "enum": [ "none", "available", "expired" ] }, "bytes": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "sha256": { "anyOf": [ { "type": "string", "description": "SHA-256 of the full log object, when the builder recorded it." }, { "type": "null" } ] }, "expires_at": { "anyOf": [ { "type": "string", "format": "date-time", "description": "RFC 3339 UTC timestamp with Z." }, { "type": "null" } ] }, "downloadable": { "type": "boolean", "description": "The full log can be downloaded through GET .../template-builds/{id}/log-url (short-lived signed URL)." }, "tail": { "anyOf": [ { "type": "string", "description": "Last <= 64 KiB of the build log (GET of one build; until expires_at)." }, { "type": "null" } ] } }, "additionalProperties": false, "description": "Build log: the tail inline, the full log through a short-lived signed URL (log-url)." }, "publishable": { "type": "boolean" }, "builder_availability": { "type": "object", "required": [ "state", "reason", "active_builders", "last_heartbeat_at" ], "properties": { "state": { "type": "string", "enum": [ "available", "unavailable" ] }, "reason": { "anyOf": [ { "type": "string", "enum": [ "no_builder_registered", "no_recent_heartbeat" ] }, { "type": "null" } ] }, "active_builders": { "type": "integer" }, "last_heartbeat_at": { "anyOf": [ { "type": "string", "format": "date-time", "description": "RFC 3339 UTC timestamp with Z." }, { "type": "null" } ] } }, "additionalProperties": false, "description": "From builder heartbeats (app.template_builders, 60 s window). `unavailable`: queued builds wait until a builder runs." }, "source_kind": { "type": "string", "enum": [ "recipe", "workspace" ], "description": "recipe (recipe v1 Dockerfile dialect or recipe v2) or workspace (save-as-template, draft publish)." }, "source_workspace_id": { "anyOf": [ { "type": "string", "format": "uuid", "description": "UUIDv7, lowercase canonical form." }, { "type": "null" } ] }, "source_checkpoint_id": { "anyOf": [ { "type": "string", "description": "The saved checkpoint (filled when the capture finished and the cell claimed the build)." }, { "type": "null" } ] }, "scrub_result": { "anyOf": [ { "type": "object", "properties": {}, "additionalProperties": true, "description": "sf-scrub.v1 report ({policy, removed_count, removed_bytes, removed_paths (first 1000), emptied, reimposed}); paths only, never contents." }, { "type": "null" } ] }, "files": { "anyOf": [ { "type": "object", "properties": {}, "additionalProperties": true, "description": "The produced file list ({key, size, sha256, content_sha256, entries, total_file_bytes})." }, { "type": "null" } ] }, "produced_layer_id": { "anyOf": [ { "type": "string", "format": "uuid", "description": "UUIDv7, lowercase canonical form." }, { "type": "null" } ] }, "squashed": { "anyOf": [ { "type": "boolean", "description": "The base chain already had 4 org layers: this build squashed them into its one layer." }, { "type": "null" } ] }, "org_bytes": { "anyOf": [ { "type": "integer", "description": "The produced chain’s org bytes (limited by the plan’s workspace disk limit)." }, { "type": "null" } ] } }, "additionalProperties": false } } } }, "4XX": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "examples": { "not_found": { "$ref": "#/components/examples/not_found" }, "rate_limited": { "$ref": "#/components/examples/rate_limited" }, "validation_failed": { "$ref": "#/components/examples/validation_failed" } } } } }, "5XX": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "examples": { "not_found": { "$ref": "#/components/examples/not_found" }, "rate_limited": { "$ref": "#/components/examples/rate_limited" }, "validation_failed": { "$ref": "#/components/examples/validation_failed" } } } } } } } }, "/v1/organizations/{organization_id}/template-builds/{build_id}/log-url": { "get": { "operationId": "getV1OrganizationsOrganizationIdTemplateBuildsBuildIdLogUrl", "summary": "Get a short-lived download URL for the full build log", "tags": [ "Template builds" ], "description": "Presigned S3 GET of `builds/.log` (served as an attachment `build-.log`, text/plain), valid until `expires_at` (at most 15 minutes). Same access as reading the build. 404 `not_found` with `details.reason` log_not_available (no full log recorded for this build, e.g. still running) or log_expired (past its retention); 503 `dependency_unavailable` when this deployment has no build-log bucket. Audited; never cached.", "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "organization_id", "required": true, "description": "UUIDv7, lowercase canonical form." }, { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "build_id", "required": true, "description": "UUIDv7, lowercase canonical form." } ], "security": [ { "apiKey": [] } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "required": [ "url", "expires_at", "object_key", "bytes", "sha256" ], "properties": { "url": { "type": "string", "description": "Presigned S3 GET URL (SigV4 query auth). A bearer credential until expires_at: do not log or share it." }, "expires_at": { "type": "string", "format": "date-time" }, "object_key": { "type": "string", "description": "`builds/.log`." }, "bytes": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "sha256": { "anyOf": [ { "type": "string", "description": "SHA-256 of the log object when the builder recorded it (verify the download)." }, { "type": "null" } ] } }, "additionalProperties": false } } } }, "4XX": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "examples": { "not_found": { "$ref": "#/components/examples/not_found" }, "rate_limited": { "$ref": "#/components/examples/rate_limited" }, "validation_failed": { "$ref": "#/components/examples/validation_failed" } } } } }, "5XX": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "examples": { "not_found": { "$ref": "#/components/examples/not_found" }, "rate_limited": { "$ref": "#/components/examples/rate_limited" }, "validation_failed": { "$ref": "#/components/examples/validation_failed" } } } } } } } }, "/v1/organizations/{organization_id}/template-uploads": { "post": { "operationId": "postV1OrganizationsOrganizationIdTemplateUploads", "summary": "Request an upload of a recipe build input (a file, or a folder as an uncompressed tar), by content", "tags": [ "Template builds" ], "description": "200 {upload, put: null} when the organization already has these bytes (a pending upload is checked in the bucket first). 201 with a presigned S3 PUT otherwise (valid 900 s): send the bytes with every header of `put.headers` (x-amz-checksum-sha256 and content-length are signed, so S3 refuses other bytes), then reference `sha256:` in the recipe’s build.files. Idempotent by content (no Idempotency-Key needed). Errors: 422 upload_too_large (details.limit upload_bytes_max: at most 5 GiB), 422 upload_digest_mismatch (the same sha256 is available with another size), 503 dependency_unavailable (uploads_not_configured). Owners/admins and API keys with a tool permission.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TemplateUploadRequest" } } } }, "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "organization_id", "required": true, "description": "UUIDv7, lowercase canonical form." } ], "security": [ { "apiKey": [] } ], "responses": { "200": { "description": "200: the bytes are already available (put null). 201: PUT the bytes with `put`, then reference `sha256:` in the recipe.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TemplateUploadResponse" } } } }, "201": { "description": "200: the bytes are already available (put null). 201: PUT the bytes with `put`, then reference `sha256:` in the recipe.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TemplateUploadResponse" } } } }, "4XX": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "examples": { "not_found": { "$ref": "#/components/examples/not_found" }, "rate_limited": { "$ref": "#/components/examples/rate_limited" }, "validation_failed": { "$ref": "#/components/examples/validation_failed" } } } } }, "5XX": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "examples": { "not_found": { "$ref": "#/components/examples/not_found" }, "rate_limited": { "$ref": "#/components/examples/rate_limited" }, "validation_failed": { "$ref": "#/components/examples/validation_failed" } } } } } } } }, "/v1/template-uploads": { "post": { "operationId": "postV1TemplateUploads", "summary": "Request an upload of a recipe build input (a file, or a folder as an uncompressed tar), by content (the API key’s organization)", "tags": [ "Template builds" ], "description": "200 {upload, put: null} when the organization already has these bytes (a pending upload is checked in the bucket first). 201 with a presigned S3 PUT otherwise (valid 900 s): send the bytes with every header of `put.headers` (x-amz-checksum-sha256 and content-length are signed, so S3 refuses other bytes), then reference `sha256:` in the recipe’s build.files. Idempotent by content (no Idempotency-Key needed). Errors: 422 upload_too_large (details.limit upload_bytes_max: at most 5 GiB), 422 upload_digest_mismatch (the same sha256 is available with another size), 503 dependency_unavailable (uploads_not_configured). Owners/admins and API keys with a tool permission.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TemplateUploadRequest" } } } }, "security": [ { "apiKey": [] } ], "responses": { "200": { "description": "200: the bytes are already available (put null). 201: PUT the bytes with `put`, then reference `sha256:` in the recipe.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TemplateUploadResponse" } } } }, "201": { "description": "200: the bytes are already available (put null). 201: PUT the bytes with `put`, then reference `sha256:` in the recipe.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TemplateUploadResponse" } } } }, "4XX": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "examples": { "not_found": { "$ref": "#/components/examples/not_found" }, "rate_limited": { "$ref": "#/components/examples/rate_limited" }, "validation_failed": { "$ref": "#/components/examples/validation_failed" } } } } }, "5XX": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "examples": { "not_found": { "$ref": "#/components/examples/not_found" }, "rate_limited": { "$ref": "#/components/examples/rate_limited" }, "validation_failed": { "$ref": "#/components/examples/validation_failed" } } } } } } } }, "/v1/organizations/{organization_id}/template-packages": { "get": { "operationId": "getV1OrganizationsOrganizationIdTemplatePackages", "summary": "Search apt, pip or npm packages for a recipe", "tags": [ "Template builds" ], "description": "apt: the base’s package index (409 package_index_unavailable when the base has none); pip: the daily PyPI name list (names only; 409 package_index_unavailable before its first refresh); npm: the registry search. Upstreams are bounded (503 dependency_unavailable, retryable, when they do not answer within 2.5 s) and each organization may make 120 lookups a minute (429 rate_limited). Owners/admins and API keys with a tool permission.", "parameters": [ { "schema": { "type": "string", "enum": [ "apt", "pip", "npm" ] }, "in": "query", "name": "ecosystem", "required": true }, { "schema": { "type": "string", "minLength": 1, "maxLength": 100 }, "in": "query", "name": "q", "required": true }, { "schema": { "type": "string", "minLength": 3, "maxLength": 120, "pattern": "^[a-z0-9](?:[a-z0-9._-]{0,98}[a-z0-9])?@[1-9][0-9]{0,8}$" }, "in": "query", "name": "base", "required": false, "description": "`@` (apt: the base whose apt index is searched)." }, { "schema": { "type": "integer", "minimum": 1, "maximum": 50, "default": 20 }, "in": "query", "name": "limit", "required": false }, { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "organization_id", "required": true, "description": "UUIDv7, lowercase canonical form." } ], "security": [ { "apiKey": [] } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TemplatePackagePage" } } } }, "4XX": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "examples": { "not_found": { "$ref": "#/components/examples/not_found" }, "rate_limited": { "$ref": "#/components/examples/rate_limited" }, "validation_failed": { "$ref": "#/components/examples/validation_failed" } } } } }, "5XX": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "examples": { "not_found": { "$ref": "#/components/examples/not_found" }, "rate_limited": { "$ref": "#/components/examples/rate_limited" }, "validation_failed": { "$ref": "#/components/examples/validation_failed" } } } } } } } }, "/v1/organizations/{organization_id}/template-packages/{ecosystem}/{name}": { "get": { "operationId": "getV1OrganizationsOrganizationIdTemplatePackagesEcosystemName", "summary": "Get one apt, pip or npm package: latest version, summary and versions", "tags": [ "Template builds" ], "description": "404 not_found (package_not_found). apt needs base=@. Same limits as the search.", "parameters": [ { "schema": { "type": "string", "minLength": 3, "maxLength": 120, "pattern": "^[a-z0-9](?:[a-z0-9._-]{0,98}[a-z0-9])?@[1-9][0-9]{0,8}$" }, "in": "query", "name": "base", "required": false, "description": "`@` (apt: the base whose apt index is searched)." }, { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "organization_id", "required": true, "description": "UUIDv7, lowercase canonical form." }, { "schema": { "type": "string", "enum": [ "apt", "pip", "npm" ] }, "in": "path", "name": "ecosystem", "required": true }, { "schema": { "type": "string", "minLength": 1, "maxLength": 214, "pattern": "^[A-Za-z0-9@][A-Za-z0-9@._/+-]{0,213}$" }, "in": "path", "name": "name", "required": true } ], "security": [ { "apiKey": [] } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TemplatePackage" } } } }, "4XX": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "examples": { "not_found": { "$ref": "#/components/examples/not_found" }, "rate_limited": { "$ref": "#/components/examples/rate_limited" }, "validation_failed": { "$ref": "#/components/examples/validation_failed" } } } } }, "5XX": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "examples": { "not_found": { "$ref": "#/components/examples/not_found" }, "rate_limited": { "$ref": "#/components/examples/rate_limited" }, "validation_failed": { "$ref": "#/components/examples/validation_failed" } } } } } } } }, "/v1/template-packages": { "get": { "operationId": "getV1TemplatePackages", "summary": "Search apt, pip or npm packages for a recipe (the API key’s organization)", "tags": [ "Template builds" ], "description": "apt: the base’s package index (409 package_index_unavailable when the base has none); pip: the daily PyPI name list (names only; 409 package_index_unavailable before its first refresh); npm: the registry search. Upstreams are bounded (503 dependency_unavailable, retryable, when they do not answer within 2.5 s) and each organization may make 120 lookups a minute (429 rate_limited). Owners/admins and API keys with a tool permission.", "parameters": [ { "schema": { "type": "string", "enum": [ "apt", "pip", "npm" ] }, "in": "query", "name": "ecosystem", "required": true }, { "schema": { "type": "string", "minLength": 1, "maxLength": 100 }, "in": "query", "name": "q", "required": true }, { "schema": { "type": "string", "minLength": 3, "maxLength": 120, "pattern": "^[a-z0-9](?:[a-z0-9._-]{0,98}[a-z0-9])?@[1-9][0-9]{0,8}$" }, "in": "query", "name": "base", "required": false, "description": "`@` (apt: the base whose apt index is searched)." }, { "schema": { "type": "integer", "minimum": 1, "maximum": 50, "default": 20 }, "in": "query", "name": "limit", "required": false } ], "security": [ { "apiKey": [] } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TemplatePackagePage" } } } }, "4XX": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "examples": { "not_found": { "$ref": "#/components/examples/not_found" }, "rate_limited": { "$ref": "#/components/examples/rate_limited" }, "validation_failed": { "$ref": "#/components/examples/validation_failed" } } } } }, "5XX": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "examples": { "not_found": { "$ref": "#/components/examples/not_found" }, "rate_limited": { "$ref": "#/components/examples/rate_limited" }, "validation_failed": { "$ref": "#/components/examples/validation_failed" } } } } } } } }, "/v1/template-packages/{ecosystem}/{name}": { "get": { "operationId": "getV1TemplatePackagesEcosystemName", "summary": "Get one apt, pip or npm package: latest version, summary and versions (the API key’s organization)", "tags": [ "Template builds" ], "description": "404 not_found (package_not_found). apt needs base=@. Same limits as the search.", "parameters": [ { "schema": { "type": "string", "minLength": 3, "maxLength": 120, "pattern": "^[a-z0-9](?:[a-z0-9._-]{0,98}[a-z0-9])?@[1-9][0-9]{0,8}$" }, "in": "query", "name": "base", "required": false, "description": "`@` (apt: the base whose apt index is searched)." }, { "schema": { "type": "string", "enum": [ "apt", "pip", "npm" ] }, "in": "path", "name": "ecosystem", "required": true }, { "schema": { "type": "string", "minLength": 1, "maxLength": 214, "pattern": "^[A-Za-z0-9@][A-Za-z0-9@._/+-]{0,213}$" }, "in": "path", "name": "name", "required": true } ], "security": [ { "apiKey": [] } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TemplatePackage" } } } }, "4XX": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "examples": { "not_found": { "$ref": "#/components/examples/not_found" }, "rate_limited": { "$ref": "#/components/examples/rate_limited" }, "validation_failed": { "$ref": "#/components/examples/validation_failed" } } } } }, "5XX": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "examples": { "not_found": { "$ref": "#/components/examples/not_found" }, "rate_limited": { "$ref": "#/components/examples/rate_limited" }, "validation_failed": { "$ref": "#/components/examples/validation_failed" } } } } } } } }, "/v1/organizations/{organization_id}/template-languages": { "get": { "operationId": "getV1OrganizationsOrganizationIdTemplateLanguages", "summary": "The recipe languages a base offers: version, default, whether the base already has it, and the hosts its install needs", "tags": [ "Template builds" ], "description": "The language table read for the chain’s platform base of `base`, resolved as a build resolves `recipe.base` (422 validation_failed with details.field \"base\" and the build’s reasons: base_not_found, base_archived, base_not_published, architecture_not_supported). `included`: the base already has that version (python-node-browser: python and node), so the build installs nothing for it. A version the base has another version of is left out (a build would refuse it with language_conflict). Owners/admins and API keys with a tool permission.", "parameters": [ { "schema": { "type": "string", "minLength": 3, "maxLength": 120, "pattern": "^[a-z0-9](?:[a-z0-9._-]{0,98}[a-z0-9])?@[1-9][0-9]{0,8}$" }, "in": "query", "name": "base", "required": true, "description": "`@` (apt: the base whose apt index is searched)." }, { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "organization_id", "required": true, "description": "UUIDv7, lowercase canonical form." } ], "security": [ { "apiKey": [] } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TemplateLanguages" } } } }, "4XX": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "examples": { "not_found": { "$ref": "#/components/examples/not_found" }, "rate_limited": { "$ref": "#/components/examples/rate_limited" }, "validation_failed": { "$ref": "#/components/examples/validation_failed" } } } } }, "5XX": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "examples": { "not_found": { "$ref": "#/components/examples/not_found" }, "rate_limited": { "$ref": "#/components/examples/rate_limited" }, "validation_failed": { "$ref": "#/components/examples/validation_failed" } } } } } } } }, "/v1/template-languages": { "get": { "operationId": "getV1TemplateLanguages", "summary": "The recipe languages a base offers: version, default, whether the base already has it, and the hosts its install needs (the API key’s organization)", "tags": [ "Template builds" ], "description": "The language table read for the chain’s platform base of `base`, resolved as a build resolves `recipe.base` (422 validation_failed with details.field \"base\" and the build’s reasons: base_not_found, base_archived, base_not_published, architecture_not_supported). `included`: the base already has that version (python-node-browser: python and node), so the build installs nothing for it. A version the base has another version of is left out (a build would refuse it with language_conflict). Owners/admins and API keys with a tool permission.", "parameters": [ { "schema": { "type": "string", "minLength": 3, "maxLength": 120, "pattern": "^[a-z0-9](?:[a-z0-9._-]{0,98}[a-z0-9])?@[1-9][0-9]{0,8}$" }, "in": "query", "name": "base", "required": true, "description": "`@` (apt: the base whose apt index is searched)." } ], "security": [ { "apiKey": [] } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TemplateLanguages" } } } }, "4XX": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "examples": { "not_found": { "$ref": "#/components/examples/not_found" }, "rate_limited": { "$ref": "#/components/examples/rate_limited" }, "validation_failed": { "$ref": "#/components/examples/validation_failed" } } } } }, "5XX": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "examples": { "not_found": { "$ref": "#/components/examples/not_found" }, "rate_limited": { "$ref": "#/components/examples/rate_limited" }, "validation_failed": { "$ref": "#/components/examples/validation_failed" } } } } } } } }, "/v1/organizations/{organization_id}/template-builder-availability": { "get": { "operationId": "getV1OrganizationsOrganizationIdTemplateBuilderAvailability", "summary": "Whether a template builder is running (heartbeat within 60 s)", "tags": [ "Template builds" ], "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "organization_id", "required": true, "description": "UUIDv7, lowercase canonical form." } ], "security": [ { "apiKey": [] } ], "responses": { "200": { "description": "From builder heartbeats (app.template_builders, 60 s window). `unavailable`: queued builds wait until a builder runs.", "content": { "application/json": { "schema": { "type": "object", "required": [ "state", "reason", "active_builders", "last_heartbeat_at" ], "properties": { "state": { "type": "string", "enum": [ "available", "unavailable" ] }, "reason": { "anyOf": [ { "type": "string", "enum": [ "no_builder_registered", "no_recent_heartbeat" ] }, { "type": "null" } ] }, "active_builders": { "type": "integer" }, "last_heartbeat_at": { "anyOf": [ { "type": "string", "format": "date-time", "description": "RFC 3339 UTC timestamp with Z." }, { "type": "null" } ] } }, "additionalProperties": false, "description": "From builder heartbeats (app.template_builders, 60 s window). `unavailable`: queued builds wait until a builder runs." } } } }, "4XX": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "examples": { "not_found": { "$ref": "#/components/examples/not_found" }, "rate_limited": { "$ref": "#/components/examples/rate_limited" }, "validation_failed": { "$ref": "#/components/examples/validation_failed" } } } } }, "5XX": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "examples": { "not_found": { "$ref": "#/components/examples/not_found" }, "rate_limited": { "$ref": "#/components/examples/rate_limited" }, "validation_failed": { "$ref": "#/components/examples/validation_failed" } } } } } } } }, "/v1/organizations/{organization_id}/templates/{slug}/draft": { "get": { "operationId": "getV1OrganizationsOrganizationIdTemplatesSlugDraft", "summary": "Get the template’s draft", "tags": [ "Template drafts" ], "description": "404 draft_not_found when the template has no live draft.", "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "organization_id", "required": true, "description": "UUIDv7, lowercase canonical form." }, { "schema": { "type": "string", "minLength": 1, "maxLength": 100, "pattern": "^[a-z0-9](?:[a-z0-9._-]{0,98}[a-z0-9])?$" }, "in": "path", "name": "slug", "required": true } ], "security": [ { "apiKey": [] } ], "responses": { "200": { "description": "The live draft of an organization template.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TemplateDraft" } } } }, "4XX": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "examples": { "not_found": { "$ref": "#/components/examples/not_found" }, "rate_limited": { "$ref": "#/components/examples/rate_limited" }, "validation_failed": { "$ref": "#/components/examples/validation_failed" } } } } }, "5XX": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "examples": { "not_found": { "$ref": "#/components/examples/not_found" }, "rate_limited": { "$ref": "#/components/examples/rate_limited" }, "validation_failed": { "$ref": "#/components/examples/validation_failed" } } } } } } }, "post": { "operationId": "postV1OrganizationsOrganizationIdTemplatesSlugDraft", "summary": "Create the template’s draft (a layered workspace on the draft base)", "tags": [ "Template drafts" ], "description": "Opens the organization template’s single live draft (key sf:draft::<8 hex>, purpose template_draft, persistent, layered) on `base` (default: the latest published version; required when the template has none, which creates the organization template named `display_name`, default the slug). 202 with the open operation and the draft. Errors: 409 template_not_layered (the base is not layered-capable, or layered opens are off), 409 draft_exists (details.workspace_id), 403 template_dev_mode_role, 422 platform_template_slug / reserved_template_slug (new, edit) / base_required. Supports Idempotency-Key.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateDraftBody" } } } }, "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "organization_id", "required": true, "description": "UUIDv7, lowercase canonical form." }, { "schema": { "type": "string", "minLength": 1, "maxLength": 100, "pattern": "^[a-z0-9](?:[a-z0-9._-]{0,98}[a-z0-9])?$" }, "in": "path", "name": "slug", "required": true } ], "security": [ { "apiKey": [] } ], "responses": { "200": { "description": "202: poll `operation`; 200: running and ready (tool_token set).", "content": { "application/json": { "schema": { "type": "object", "required": [ "workspace", "operation", "cell_endpoint", "tool_token", "draft" ], "properties": { "workspace": { "$ref": "#/components/schemas/Workspace" }, "operation": { "anyOf": [ { "$ref": "#/components/schemas/Operation" }, { "type": "null" } ] }, "cell_endpoint": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "tool_token": { "anyOf": [ { "$ref": "#/components/schemas/ToolToken" }, { "type": "null" } ] }, "draft": { "$ref": "#/components/schemas/TemplateDraft" } }, "additionalProperties": false, "description": "202: poll `operation`; 200: running and ready (tool_token set)." } } } }, "202": { "description": "202: poll `operation`; 200: running and ready (tool_token set).", "content": { "application/json": { "schema": { "type": "object", "required": [ "workspace", "operation", "cell_endpoint", "tool_token", "draft" ], "properties": { "workspace": { "$ref": "#/components/schemas/Workspace" }, "operation": { "anyOf": [ { "$ref": "#/components/schemas/Operation" }, { "type": "null" } ] }, "cell_endpoint": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "tool_token": { "anyOf": [ { "$ref": "#/components/schemas/ToolToken" }, { "type": "null" } ] }, "draft": { "$ref": "#/components/schemas/TemplateDraft" } }, "additionalProperties": false, "description": "202: poll `operation`; 200: running and ready (tool_token set)." } } } }, "4XX": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "examples": { "not_found": { "$ref": "#/components/examples/not_found" }, "rate_limited": { "$ref": "#/components/examples/rate_limited" }, "validation_failed": { "$ref": "#/components/examples/validation_failed" } } } } }, "5XX": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "examples": { "not_found": { "$ref": "#/components/examples/not_found" }, "rate_limited": { "$ref": "#/components/examples/rate_limited" }, "validation_failed": { "$ref": "#/components/examples/validation_failed" } } } } } } }, "delete": { "operationId": "deleteV1OrganizationsOrganizationIdTemplatesSlugDraft", "summary": "Discard the draft (delete it and end its live test instances)", "tags": [ "Template drafts" ], "description": "Deletes the draft (operation `delete`, input.reason draft_discarded) and ends each live test instance (ended_reason draft_discarded). 202 with the draft’s delete operation. Supports Idempotency-Key.", "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "organization_id", "required": true, "description": "UUIDv7, lowercase canonical form." }, { "schema": { "type": "string", "minLength": 1, "maxLength": 100, "pattern": "^[a-z0-9](?:[a-z0-9._-]{0,98}[a-z0-9])?$" }, "in": "path", "name": "slug", "required": true } ], "security": [ { "apiKey": [] } ], "responses": { "202": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "required": [ "operation" ], "properties": { "operation": { "$ref": "#/components/schemas/Operation" } }, "additionalProperties": false } } } }, "4XX": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "examples": { "not_found": { "$ref": "#/components/examples/not_found" }, "rate_limited": { "$ref": "#/components/examples/rate_limited" }, "validation_failed": { "$ref": "#/components/examples/validation_failed" } } } } }, "5XX": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "examples": { "not_found": { "$ref": "#/components/examples/not_found" }, "rate_limited": { "$ref": "#/components/examples/rate_limited" }, "validation_failed": { "$ref": "#/components/examples/validation_failed" } } } } } } } }, "/v1/templates/{slug}/draft": { "get": { "operationId": "getV1TemplatesSlugDraft", "summary": "Get the template’s draft", "tags": [ "Template drafts" ], "description": "404 draft_not_found when the template has no live draft.", "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 100, "pattern": "^[a-z0-9](?:[a-z0-9._-]{0,98}[a-z0-9])?$" }, "in": "path", "name": "slug", "required": true } ], "security": [ { "apiKey": [] } ], "responses": { "200": { "description": "The live draft of an organization template.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TemplateDraft" } } } }, "4XX": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "examples": { "not_found": { "$ref": "#/components/examples/not_found" }, "rate_limited": { "$ref": "#/components/examples/rate_limited" }, "validation_failed": { "$ref": "#/components/examples/validation_failed" } } } } }, "5XX": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "examples": { "not_found": { "$ref": "#/components/examples/not_found" }, "rate_limited": { "$ref": "#/components/examples/rate_limited" }, "validation_failed": { "$ref": "#/components/examples/validation_failed" } } } } } } }, "post": { "operationId": "postV1TemplatesSlugDraft", "summary": "Create the template’s draft (a layered workspace on the draft base)", "tags": [ "Template drafts" ], "description": "Opens the organization template’s single live draft (key sf:draft::<8 hex>, purpose template_draft, persistent, layered) on `base` (default: the latest published version; required when the template has none, which creates the organization template named `display_name`, default the slug). 202 with the open operation and the draft. Errors: 409 template_not_layered (the base is not layered-capable, or layered opens are off), 409 draft_exists (details.workspace_id), 403 template_dev_mode_role, 422 platform_template_slug / reserved_template_slug (new, edit) / base_required. Supports Idempotency-Key.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateDraftBody" } } } }, "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 100, "pattern": "^[a-z0-9](?:[a-z0-9._-]{0,98}[a-z0-9])?$" }, "in": "path", "name": "slug", "required": true } ], "security": [ { "apiKey": [] } ], "responses": { "200": { "description": "202: poll `operation`; 200: running and ready (tool_token set).", "content": { "application/json": { "schema": { "type": "object", "required": [ "workspace", "operation", "cell_endpoint", "tool_token", "draft" ], "properties": { "workspace": { "$ref": "#/components/schemas/Workspace" }, "operation": { "anyOf": [ { "$ref": "#/components/schemas/Operation" }, { "type": "null" } ] }, "cell_endpoint": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "tool_token": { "anyOf": [ { "$ref": "#/components/schemas/ToolToken" }, { "type": "null" } ] }, "draft": { "$ref": "#/components/schemas/TemplateDraft" } }, "additionalProperties": false, "description": "202: poll `operation`; 200: running and ready (tool_token set)." } } } }, "202": { "description": "202: poll `operation`; 200: running and ready (tool_token set).", "content": { "application/json": { "schema": { "type": "object", "required": [ "workspace", "operation", "cell_endpoint", "tool_token", "draft" ], "properties": { "workspace": { "$ref": "#/components/schemas/Workspace" }, "operation": { "anyOf": [ { "$ref": "#/components/schemas/Operation" }, { "type": "null" } ] }, "cell_endpoint": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "tool_token": { "anyOf": [ { "$ref": "#/components/schemas/ToolToken" }, { "type": "null" } ] }, "draft": { "$ref": "#/components/schemas/TemplateDraft" } }, "additionalProperties": false, "description": "202: poll `operation`; 200: running and ready (tool_token set)." } } } }, "4XX": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "examples": { "not_found": { "$ref": "#/components/examples/not_found" }, "rate_limited": { "$ref": "#/components/examples/rate_limited" }, "validation_failed": { "$ref": "#/components/examples/validation_failed" } } } } }, "5XX": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "examples": { "not_found": { "$ref": "#/components/examples/not_found" }, "rate_limited": { "$ref": "#/components/examples/rate_limited" }, "validation_failed": { "$ref": "#/components/examples/validation_failed" } } } } } } }, "delete": { "operationId": "deleteV1TemplatesSlugDraft", "summary": "Discard the draft (delete it and end its live test instances)", "tags": [ "Template drafts" ], "description": "Deletes the draft (operation `delete`, input.reason draft_discarded) and ends each live test instance (ended_reason draft_discarded). 202 with the draft’s delete operation. Supports Idempotency-Key.", "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 100, "pattern": "^[a-z0-9](?:[a-z0-9._-]{0,98}[a-z0-9])?$" }, "in": "path", "name": "slug", "required": true } ], "security": [ { "apiKey": [] } ], "responses": { "202": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "required": [ "operation" ], "properties": { "operation": { "$ref": "#/components/schemas/Operation" } }, "additionalProperties": false } } } }, "4XX": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "examples": { "not_found": { "$ref": "#/components/examples/not_found" }, "rate_limited": { "$ref": "#/components/examples/rate_limited" }, "validation_failed": { "$ref": "#/components/examples/validation_failed" } } } } }, "5XX": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "examples": { "not_found": { "$ref": "#/components/examples/not_found" }, "rate_limited": { "$ref": "#/components/examples/rate_limited" }, "validation_failed": { "$ref": "#/components/examples/validation_failed" } } } } } } } }, "/v1/organizations/{organization_id}/templates/{slug}/draft/states": { "get": { "operationId": "getV1OrganizationsOrganizationIdTemplatesSlugDraftStates", "summary": "List the draft’s states, newest first", "tags": [ "Template drafts" ], "parameters": [ { "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 }, "in": "query", "name": "limit", "required": false }, { "schema": { "type": "string", "maxLength": 200 }, "in": "query", "name": "cursor", "required": false }, { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "organization_id", "required": true, "description": "UUIDv7, lowercase canonical form." }, { "schema": { "type": "string", "minLength": 1, "maxLength": 100, "pattern": "^[a-z0-9](?:[a-z0-9._-]{0,98}[a-z0-9])?$" }, "in": "path", "name": "slug", "required": true } ], "security": [ { "apiKey": [] } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "next_cursor" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/DraftState" } }, "next_cursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "additionalProperties": false } } } }, "4XX": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "examples": { "not_found": { "$ref": "#/components/examples/not_found" }, "rate_limited": { "$ref": "#/components/examples/rate_limited" }, "validation_failed": { "$ref": "#/components/examples/validation_failed" } } } } }, "5XX": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "examples": { "not_found": { "$ref": "#/components/examples/not_found" }, "rate_limited": { "$ref": "#/components/examples/rate_limited" }, "validation_failed": { "$ref": "#/components/examples/validation_failed" } } } } } } }, "post": { "operationId": "postV1OrganizationsOrganizationIdTemplatesSlugDraftStates", "summary": "Capture a draft state (disk-only layer_snapshot of the running draft)", "tags": [ "Template drafts" ], "description": "202 with the `layer_snapshot` operation; its result carries checkpoint_id. A suspended draft is 409 workspace_not_running (its current checkpoint already serves as a state). Supports Idempotency-Key.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "label": { "type": "string", "minLength": 1, "maxLength": 200, "pattern": "^[^\\u0000-\\u001f\\u007f]+$" } }, "additionalProperties": false } } } }, "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "organization_id", "required": true, "description": "UUIDv7, lowercase canonical form." }, { "schema": { "type": "string", "minLength": 1, "maxLength": 100, "pattern": "^[a-z0-9](?:[a-z0-9._-]{0,98}[a-z0-9])?$" }, "in": "path", "name": "slug", "required": true } ], "security": [ { "apiKey": [] } ], "responses": { "202": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "required": [ "operation" ], "properties": { "operation": { "$ref": "#/components/schemas/Operation" } }, "additionalProperties": false } } } }, "4XX": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "examples": { "not_found": { "$ref": "#/components/examples/not_found" }, "rate_limited": { "$ref": "#/components/examples/rate_limited" }, "validation_failed": { "$ref": "#/components/examples/validation_failed" } } } } }, "5XX": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "examples": { "not_found": { "$ref": "#/components/examples/not_found" }, "rate_limited": { "$ref": "#/components/examples/rate_limited" }, "validation_failed": { "$ref": "#/components/examples/validation_failed" } } } } } } } }, "/v1/templates/{slug}/draft/states": { "get": { "operationId": "getV1TemplatesSlugDraftStates", "summary": "List the draft’s states, newest first", "tags": [ "Template drafts" ], "parameters": [ { "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 }, "in": "query", "name": "limit", "required": false }, { "schema": { "type": "string", "maxLength": 200 }, "in": "query", "name": "cursor", "required": false }, { "schema": { "type": "string", "minLength": 1, "maxLength": 100, "pattern": "^[a-z0-9](?:[a-z0-9._-]{0,98}[a-z0-9])?$" }, "in": "path", "name": "slug", "required": true } ], "security": [ { "apiKey": [] } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "next_cursor" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/DraftState" } }, "next_cursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "additionalProperties": false } } } }, "4XX": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "examples": { "not_found": { "$ref": "#/components/examples/not_found" }, "rate_limited": { "$ref": "#/components/examples/rate_limited" }, "validation_failed": { "$ref": "#/components/examples/validation_failed" } } } } }, "5XX": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "examples": { "not_found": { "$ref": "#/components/examples/not_found" }, "rate_limited": { "$ref": "#/components/examples/rate_limited" }, "validation_failed": { "$ref": "#/components/examples/validation_failed" } } } } } } }, "post": { "operationId": "postV1TemplatesSlugDraftStates", "summary": "Capture a draft state (disk-only layer_snapshot of the running draft)", "tags": [ "Template drafts" ], "description": "202 with the `layer_snapshot` operation; its result carries checkpoint_id. A suspended draft is 409 workspace_not_running (its current checkpoint already serves as a state). Supports Idempotency-Key.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "label": { "type": "string", "minLength": 1, "maxLength": 200, "pattern": "^[^\\u0000-\\u001f\\u007f]+$" } }, "additionalProperties": false } } } }, "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 100, "pattern": "^[a-z0-9](?:[a-z0-9._-]{0,98}[a-z0-9])?$" }, "in": "path", "name": "slug", "required": true } ], "security": [ { "apiKey": [] } ], "responses": { "202": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "required": [ "operation" ], "properties": { "operation": { "$ref": "#/components/schemas/Operation" } }, "additionalProperties": false } } } }, "4XX": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "examples": { "not_found": { "$ref": "#/components/examples/not_found" }, "rate_limited": { "$ref": "#/components/examples/rate_limited" }, "validation_failed": { "$ref": "#/components/examples/validation_failed" } } } } }, "5XX": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "examples": { "not_found": { "$ref": "#/components/examples/not_found" }, "rate_limited": { "$ref": "#/components/examples/rate_limited" }, "validation_failed": { "$ref": "#/components/examples/validation_failed" } } } } } } } }, "/v1/organizations/{organization_id}/templates/{slug}/draft/test-instances": { "get": { "operationId": "getV1OrganizationsOrganizationIdTemplatesSlugDraftTestInstances", "summary": "List the draft’s test instances", "tags": [ "Template drafts" ], "description": "Live instances; include_ended=true adds ended ones (tombstones with ended_reason). API keys see only their own project’s instances.", "parameters": [ { "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 }, "in": "query", "name": "limit", "required": false }, { "schema": { "type": "string", "maxLength": 200 }, "in": "query", "name": "cursor", "required": false }, { "schema": { "type": "boolean", "default": false }, "in": "query", "name": "include_ended", "required": false }, { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "organization_id", "required": true, "description": "UUIDv7, lowercase canonical form." }, { "schema": { "type": "string", "minLength": 1, "maxLength": 100, "pattern": "^[a-z0-9](?:[a-z0-9._-]{0,98}[a-z0-9])?$" }, "in": "path", "name": "slug", "required": true } ], "security": [ { "apiKey": [] } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "next_cursor" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Workspace" } }, "next_cursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "additionalProperties": false } } } }, "4XX": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "examples": { "not_found": { "$ref": "#/components/examples/not_found" }, "rate_limited": { "$ref": "#/components/examples/rate_limited" }, "validation_failed": { "$ref": "#/components/examples/validation_failed" } } } } }, "5XX": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "examples": { "not_found": { "$ref": "#/components/examples/not_found" }, "rate_limited": { "$ref": "#/components/examples/rate_limited" }, "validation_failed": { "$ref": "#/components/examples/validation_failed" } } } } } } }, "post": { "operationId": "postV1OrganizationsOrganizationIdTemplatesSlugDraftTestInstances", "summary": "Open a test instance of a draft state (a disposable session workspace)", "tags": [ "Template drafts" ], "description": "Opens a layered session workspace (purpose template_test) on the draft base whose layer is a copy of the draft state; its own writes never reach the draft. Without state_id the running draft is captured first (the instance’s open depends on that layer_snapshot; origin.checkpoint_id is filled when the cell places it); a suspended draft’s current checkpoint is used instead. The instance ends on close(), idle or draft discard. 202 OpenResponse. Supports Idempotency-Key.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateTestInstanceBody" } } } }, "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "organization_id", "required": true, "description": "UUIDv7, lowercase canonical form." }, { "schema": { "type": "string", "minLength": 1, "maxLength": 100, "pattern": "^[a-z0-9](?:[a-z0-9._-]{0,98}[a-z0-9])?$" }, "in": "path", "name": "slug", "required": true } ], "security": [ { "apiKey": [] } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "required": [ "workspace", "operation", "cell_endpoint", "tool_token" ], "properties": { "workspace": { "$ref": "#/components/schemas/Workspace" }, "operation": { "anyOf": [ { "$ref": "#/components/schemas/Operation" }, { "type": "null" } ] }, "cell_endpoint": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "tool_token": { "anyOf": [ { "$ref": "#/components/schemas/ToolToken" }, { "type": "null" } ] } }, "additionalProperties": false } } } }, "202": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "required": [ "workspace", "operation", "cell_endpoint", "tool_token" ], "properties": { "workspace": { "$ref": "#/components/schemas/Workspace" }, "operation": { "anyOf": [ { "$ref": "#/components/schemas/Operation" }, { "type": "null" } ] }, "cell_endpoint": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "tool_token": { "anyOf": [ { "$ref": "#/components/schemas/ToolToken" }, { "type": "null" } ] } }, "additionalProperties": false } } } }, "4XX": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "examples": { "not_found": { "$ref": "#/components/examples/not_found" }, "rate_limited": { "$ref": "#/components/examples/rate_limited" }, "validation_failed": { "$ref": "#/components/examples/validation_failed" } } } } }, "5XX": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "examples": { "not_found": { "$ref": "#/components/examples/not_found" }, "rate_limited": { "$ref": "#/components/examples/rate_limited" }, "validation_failed": { "$ref": "#/components/examples/validation_failed" } } } } } } } }, "/v1/templates/{slug}/draft/test-instances": { "get": { "operationId": "getV1TemplatesSlugDraftTestInstances", "summary": "List the draft’s test instances", "tags": [ "Template drafts" ], "description": "Live instances; include_ended=true adds ended ones (tombstones with ended_reason). API keys see only their own project’s instances.", "parameters": [ { "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 }, "in": "query", "name": "limit", "required": false }, { "schema": { "type": "string", "maxLength": 200 }, "in": "query", "name": "cursor", "required": false }, { "schema": { "type": "boolean", "default": false }, "in": "query", "name": "include_ended", "required": false }, { "schema": { "type": "string", "minLength": 1, "maxLength": 100, "pattern": "^[a-z0-9](?:[a-z0-9._-]{0,98}[a-z0-9])?$" }, "in": "path", "name": "slug", "required": true } ], "security": [ { "apiKey": [] } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "next_cursor" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Workspace" } }, "next_cursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "additionalProperties": false } } } }, "4XX": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "examples": { "not_found": { "$ref": "#/components/examples/not_found" }, "rate_limited": { "$ref": "#/components/examples/rate_limited" }, "validation_failed": { "$ref": "#/components/examples/validation_failed" } } } } }, "5XX": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "examples": { "not_found": { "$ref": "#/components/examples/not_found" }, "rate_limited": { "$ref": "#/components/examples/rate_limited" }, "validation_failed": { "$ref": "#/components/examples/validation_failed" } } } } } } }, "post": { "operationId": "postV1TemplatesSlugDraftTestInstances", "summary": "Open a test instance of a draft state (a disposable session workspace)", "tags": [ "Template drafts" ], "description": "Opens a layered session workspace (purpose template_test) on the draft base whose layer is a copy of the draft state; its own writes never reach the draft. Without state_id the running draft is captured first (the instance’s open depends on that layer_snapshot; origin.checkpoint_id is filled when the cell places it); a suspended draft’s current checkpoint is used instead. The instance ends on close(), idle or draft discard. 202 OpenResponse. Supports Idempotency-Key.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateTestInstanceBody" } } } }, "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 100, "pattern": "^[a-z0-9](?:[a-z0-9._-]{0,98}[a-z0-9])?$" }, "in": "path", "name": "slug", "required": true } ], "security": [ { "apiKey": [] } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "required": [ "workspace", "operation", "cell_endpoint", "tool_token" ], "properties": { "workspace": { "$ref": "#/components/schemas/Workspace" }, "operation": { "anyOf": [ { "$ref": "#/components/schemas/Operation" }, { "type": "null" } ] }, "cell_endpoint": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "tool_token": { "anyOf": [ { "$ref": "#/components/schemas/ToolToken" }, { "type": "null" } ] } }, "additionalProperties": false } } } }, "202": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "required": [ "workspace", "operation", "cell_endpoint", "tool_token" ], "properties": { "workspace": { "$ref": "#/components/schemas/Workspace" }, "operation": { "anyOf": [ { "$ref": "#/components/schemas/Operation" }, { "type": "null" } ] }, "cell_endpoint": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "tool_token": { "anyOf": [ { "$ref": "#/components/schemas/ToolToken" }, { "type": "null" } ] } }, "additionalProperties": false } } } }, "4XX": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "examples": { "not_found": { "$ref": "#/components/examples/not_found" }, "rate_limited": { "$ref": "#/components/examples/rate_limited" }, "validation_failed": { "$ref": "#/components/examples/validation_failed" } } } } }, "5XX": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "examples": { "not_found": { "$ref": "#/components/examples/not_found" }, "rate_limited": { "$ref": "#/components/examples/rate_limited" }, "validation_failed": { "$ref": "#/components/examples/validation_failed" } } } } } } } }, "/v1/organizations/{organization_id}/templates/{slug}/draft/publish": { "post": { "operationId": "postV1OrganizationsOrganizationIdTemplatesSlugDraftPublish", "summary": "Publish the draft as the template’s next version (save-as-template from the draft)", "tags": [ "Template drafts" ], "description": "Builds one new org layer holding every change since the draft base, from `state_id` or the draft’s current state (a fresh capture when running). `settings` (TemplateSettingsInput): each given field replaces that field of the draft base’s settings, each absent one is carried forward (settings.defaults and defaults together: 422 invalid_settings). Refused with 409 draft_stale (details latest_version, draft_base_version) when the template has a version newer than the draft base that this draft did not produce, and 409 build_in_progress while a build from another source is unfinished. 202 SaveAsTemplateResponse. Supports Idempotency-Key.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublishDraftBody" } } } }, "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "organization_id", "required": true, "description": "UUIDv7, lowercase canonical form." }, { "schema": { "type": "string", "minLength": 1, "maxLength": 100, "pattern": "^[a-z0-9](?:[a-z0-9._-]{0,98}[a-z0-9])?$" }, "in": "path", "name": "slug", "required": true } ], "security": [ { "apiKey": [] } ], "responses": { "202": { "description": "operation: the capture (layer_snapshot) of a running workspace, null otherwise. build: poll GET …/template-builds/{id} until registration.state is registered.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SaveAsTemplateResponse" } } } }, "4XX": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "examples": { "not_found": { "$ref": "#/components/examples/not_found" }, "rate_limited": { "$ref": "#/components/examples/rate_limited" }, "validation_failed": { "$ref": "#/components/examples/validation_failed" } } } } }, "5XX": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "examples": { "not_found": { "$ref": "#/components/examples/not_found" }, "rate_limited": { "$ref": "#/components/examples/rate_limited" }, "validation_failed": { "$ref": "#/components/examples/validation_failed" } } } } } } } }, "/v1/templates/{slug}/draft/publish": { "post": { "operationId": "postV1TemplatesSlugDraftPublish", "summary": "Publish the draft as the template’s next version (save-as-template from the draft)", "tags": [ "Template drafts" ], "description": "Builds one new org layer holding every change since the draft base, from `state_id` or the draft’s current state (a fresh capture when running). `settings` (TemplateSettingsInput): each given field replaces that field of the draft base’s settings, each absent one is carried forward (settings.defaults and defaults together: 422 invalid_settings). Refused with 409 draft_stale (details latest_version, draft_base_version) when the template has a version newer than the draft base that this draft did not produce, and 409 build_in_progress while a build from another source is unfinished. 202 SaveAsTemplateResponse. Supports Idempotency-Key.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublishDraftBody" } } } }, "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 100, "pattern": "^[a-z0-9](?:[a-z0-9._-]{0,98}[a-z0-9])?$" }, "in": "path", "name": "slug", "required": true } ], "security": [ { "apiKey": [] } ], "responses": { "202": { "description": "operation: the capture (layer_snapshot) of a running workspace, null otherwise. build: poll GET …/template-builds/{id} until registration.state is registered.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SaveAsTemplateResponse" } } } }, "4XX": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "examples": { "not_found": { "$ref": "#/components/examples/not_found" }, "rate_limited": { "$ref": "#/components/examples/rate_limited" }, "validation_failed": { "$ref": "#/components/examples/validation_failed" } } } } }, "5XX": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "examples": { "not_found": { "$ref": "#/components/examples/not_found" }, "rate_limited": { "$ref": "#/components/examples/rate_limited" }, "validation_failed": { "$ref": "#/components/examples/validation_failed" } } } } } } } }, "/v1/organizations/{organization_id}/templates/{slug}/versions/{version}/test-instances": { "post": { "operationId": "postV1OrganizationsOrganizationIdTemplatesSlugVersionsVersionTestInstances", "summary": "Open a test instance of a template version, published or not", "tags": [ "Template drafts" ], "description": "Opens a layered session workspace (purpose template_test) on that version of the organization’s template: registered and not archived, published or not. It is a fresh workspace (a `create` startup run) with origin {kind: template_version, template_id, version}; it ends on close() or idle. `inputs` as for open (422 input_unknown, input_invalid, input_required). 202 OpenResponse (200 when an existing key is running and ready). Errors: 403 template_dev_mode_role (owners, admins and API keys with a tool permission only), 404 version_not_found, 409 template_not_layered, template_archived, 422 reserved_key_prefix. Supports Idempotency-Key.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateVersionTestInstanceBody" } } } }, "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "organization_id", "required": true, "description": "UUIDv7, lowercase canonical form." }, { "schema": { "type": "string", "minLength": 1, "maxLength": 100, "pattern": "^[a-z0-9](?:[a-z0-9._-]{0,98}[a-z0-9])?$" }, "in": "path", "name": "slug", "required": true }, { "schema": { "type": "integer", "minimum": 1, "maximum": 999999999 }, "in": "path", "name": "version", "required": true } ], "security": [ { "apiKey": [] } ], "responses": { "200": { "description": "202: poll `operation`; 200: an existing instance that is running and ready (tool_token set).", "content": { "application/json": { "schema": { "type": "object", "required": [ "workspace", "operation", "cell_endpoint", "tool_token" ], "properties": { "workspace": { "$ref": "#/components/schemas/Workspace" }, "operation": { "anyOf": [ { "$ref": "#/components/schemas/Operation" }, { "type": "null" } ] }, "cell_endpoint": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "tool_token": { "anyOf": [ { "$ref": "#/components/schemas/ToolToken" }, { "type": "null" } ] } }, "additionalProperties": false, "description": "202: poll `operation`; 200: an existing instance that is running and ready (tool_token set)." } } } }, "202": { "description": "202: poll `operation`; 200: an existing instance that is running and ready (tool_token set).", "content": { "application/json": { "schema": { "type": "object", "required": [ "workspace", "operation", "cell_endpoint", "tool_token" ], "properties": { "workspace": { "$ref": "#/components/schemas/Workspace" }, "operation": { "anyOf": [ { "$ref": "#/components/schemas/Operation" }, { "type": "null" } ] }, "cell_endpoint": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "tool_token": { "anyOf": [ { "$ref": "#/components/schemas/ToolToken" }, { "type": "null" } ] } }, "additionalProperties": false, "description": "202: poll `operation`; 200: an existing instance that is running and ready (tool_token set)." } } } }, "4XX": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "examples": { "not_found": { "$ref": "#/components/examples/not_found" }, "rate_limited": { "$ref": "#/components/examples/rate_limited" }, "validation_failed": { "$ref": "#/components/examples/validation_failed" } } } } }, "5XX": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "examples": { "not_found": { "$ref": "#/components/examples/not_found" }, "rate_limited": { "$ref": "#/components/examples/rate_limited" }, "validation_failed": { "$ref": "#/components/examples/validation_failed" } } } } } } } }, "/v1/templates/{slug}/versions/{version}/test-instances": { "post": { "operationId": "postV1TemplatesSlugVersionsVersionTestInstances", "summary": "Open a test instance of a template version, published or not", "tags": [ "Template drafts" ], "description": "Opens a layered session workspace (purpose template_test) on that version of the organization’s template: registered and not archived, published or not. It is a fresh workspace (a `create` startup run) with origin {kind: template_version, template_id, version}; it ends on close() or idle. `inputs` as for open (422 input_unknown, input_invalid, input_required). 202 OpenResponse (200 when an existing key is running and ready). Errors: 403 template_dev_mode_role (owners, admins and API keys with a tool permission only), 404 version_not_found, 409 template_not_layered, template_archived, 422 reserved_key_prefix. Supports Idempotency-Key.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateVersionTestInstanceBody" } } } }, "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 100, "pattern": "^[a-z0-9](?:[a-z0-9._-]{0,98}[a-z0-9])?$" }, "in": "path", "name": "slug", "required": true }, { "schema": { "type": "integer", "minimum": 1, "maximum": 999999999 }, "in": "path", "name": "version", "required": true } ], "security": [ { "apiKey": [] } ], "responses": { "200": { "description": "202: poll `operation`; 200: an existing instance that is running and ready (tool_token set).", "content": { "application/json": { "schema": { "type": "object", "required": [ "workspace", "operation", "cell_endpoint", "tool_token" ], "properties": { "workspace": { "$ref": "#/components/schemas/Workspace" }, "operation": { "anyOf": [ { "$ref": "#/components/schemas/Operation" }, { "type": "null" } ] }, "cell_endpoint": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "tool_token": { "anyOf": [ { "$ref": "#/components/schemas/ToolToken" }, { "type": "null" } ] } }, "additionalProperties": false, "description": "202: poll `operation`; 200: an existing instance that is running and ready (tool_token set)." } } } }, "202": { "description": "202: poll `operation`; 200: an existing instance that is running and ready (tool_token set).", "content": { "application/json": { "schema": { "type": "object", "required": [ "workspace", "operation", "cell_endpoint", "tool_token" ], "properties": { "workspace": { "$ref": "#/components/schemas/Workspace" }, "operation": { "anyOf": [ { "$ref": "#/components/schemas/Operation" }, { "type": "null" } ] }, "cell_endpoint": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "tool_token": { "anyOf": [ { "$ref": "#/components/schemas/ToolToken" }, { "type": "null" } ] } }, "additionalProperties": false, "description": "202: poll `operation`; 200: an existing instance that is running and ready (tool_token set)." } } } }, "4XX": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "examples": { "not_found": { "$ref": "#/components/examples/not_found" }, "rate_limited": { "$ref": "#/components/examples/rate_limited" }, "validation_failed": { "$ref": "#/components/examples/validation_failed" } } } } }, "5XX": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "examples": { "not_found": { "$ref": "#/components/examples/not_found" }, "rate_limited": { "$ref": "#/components/examples/rate_limited" }, "validation_failed": { "$ref": "#/components/examples/validation_failed" } } } } } } } }, "/v1/organizations/{organization_id}/templates/{slug}/versions/{version}/files": { "get": { "operationId": "getV1OrganizationsOrganizationIdTemplatesSlugVersionsVersionFiles", "summary": "List one directory of a template version’s file tree", "tags": [ "Templates" ], "description": "Entries directly inside `path` (default `/`), sorted by name bytes, keyset-paginated. The tree covers the whole filesystem (only the contents of /proc, /sys, /dev, /run and /tmp are left out). 409 file_list_unavailable (no file list) or file_list_indexing (retryable); 404 path_not_found; 422 invalid_path.", "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 4096 }, "in": "query", "name": "path", "required": false, "description": "Absolute path (`/`, `/home/user`, no trailing slash)." }, { "schema": { "type": "integer", "minimum": 1, "maximum": 1000, "default": 200 }, "in": "query", "name": "limit", "required": false }, { "schema": { "type": "string", "maxLength": 8192 }, "in": "query", "name": "cursor", "required": false }, { "schema": { "type": "string", "enum": [ "platform", "organization" ] }, "in": "query", "name": "owner", "required": false, "description": "Pick the platform template even when an organization template shadows its slug." }, { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "organization_id", "required": true, "description": "UUIDv7, lowercase canonical form." }, { "schema": { "type": "string", "minLength": 1, "maxLength": 100, "pattern": "^[a-z0-9](?:[a-z0-9._-]{0,98}[a-z0-9])?$" }, "in": "path", "name": "slug", "required": true }, { "schema": { "type": "integer", "minimum": 1, "maximum": 2147483647 }, "in": "path", "name": "version", "required": true } ], "security": [ { "apiKey": [] } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TemplateFilePage" } } } }, "4XX": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "examples": { "not_found": { "$ref": "#/components/examples/not_found" }, "rate_limited": { "$ref": "#/components/examples/rate_limited" }, "validation_failed": { "$ref": "#/components/examples/validation_failed" } } } } }, "5XX": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "examples": { "not_found": { "$ref": "#/components/examples/not_found" }, "rate_limited": { "$ref": "#/components/examples/rate_limited" }, "validation_failed": { "$ref": "#/components/examples/validation_failed" } } } } } } } }, "/v1/templates/{slug}/versions/{version}/files": { "get": { "operationId": "getV1TemplatesSlugVersionsVersionFiles", "summary": "List one directory of a template version’s file tree", "tags": [ "Templates" ], "description": "Entries directly inside `path` (default `/`), sorted by name bytes, keyset-paginated. The tree covers the whole filesystem (only the contents of /proc, /sys, /dev, /run and /tmp are left out). 409 file_list_unavailable (no file list) or file_list_indexing (retryable); 404 path_not_found; 422 invalid_path.", "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 4096 }, "in": "query", "name": "path", "required": false, "description": "Absolute path (`/`, `/home/user`, no trailing slash)." }, { "schema": { "type": "integer", "minimum": 1, "maximum": 1000, "default": 200 }, "in": "query", "name": "limit", "required": false }, { "schema": { "type": "string", "maxLength": 8192 }, "in": "query", "name": "cursor", "required": false }, { "schema": { "type": "string", "enum": [ "platform", "organization" ] }, "in": "query", "name": "owner", "required": false, "description": "Pick the platform template even when an organization template shadows its slug." }, { "schema": { "type": "string", "minLength": 1, "maxLength": 100, "pattern": "^[a-z0-9](?:[a-z0-9._-]{0,98}[a-z0-9])?$" }, "in": "path", "name": "slug", "required": true }, { "schema": { "type": "integer", "minimum": 1, "maximum": 2147483647 }, "in": "path", "name": "version", "required": true } ], "security": [ { "apiKey": [] } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TemplateFilePage" } } } }, "4XX": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "examples": { "not_found": { "$ref": "#/components/examples/not_found" }, "rate_limited": { "$ref": "#/components/examples/rate_limited" }, "validation_failed": { "$ref": "#/components/examples/validation_failed" } } } } }, "5XX": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "examples": { "not_found": { "$ref": "#/components/examples/not_found" }, "rate_limited": { "$ref": "#/components/examples/rate_limited" }, "validation_failed": { "$ref": "#/components/examples/validation_failed" } } } } } } } }, "/v1/organizations/{organization_id}/templates/{slug}/versions/{version}/files/entry": { "get": { "operationId": "getV1OrganizationsOrganizationIdTemplatesSlugVersionsVersionFilesEntry", "summary": "Get one entry of a template version’s file tree", "tags": [ "Templates" ], "description": "404 path_not_found; 409 file_list_unavailable / file_list_indexing; 422 invalid_path.", "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 4096 }, "in": "query", "name": "path", "required": true, "description": "Absolute path (`/`, `/home/user`, no trailing slash)." }, { "schema": { "type": "string", "enum": [ "platform", "organization" ] }, "in": "query", "name": "owner", "required": false, "description": "Pick the platform template even when an organization template shadows its slug." }, { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "organization_id", "required": true, "description": "UUIDv7, lowercase canonical form." }, { "schema": { "type": "string", "minLength": 1, "maxLength": 100, "pattern": "^[a-z0-9](?:[a-z0-9._-]{0,98}[a-z0-9])?$" }, "in": "path", "name": "slug", "required": true }, { "schema": { "type": "integer", "minimum": 1, "maximum": 2147483647 }, "in": "path", "name": "version", "required": true } ], "security": [ { "apiKey": [] } ], "responses": { "200": { "description": "One inode path of a template version. A path that is not valid UTF-8 shows each invalid byte as \\xNN.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TemplateFileEntry" } } } }, "4XX": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "examples": { "not_found": { "$ref": "#/components/examples/not_found" }, "rate_limited": { "$ref": "#/components/examples/rate_limited" }, "validation_failed": { "$ref": "#/components/examples/validation_failed" } } } } }, "5XX": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "examples": { "not_found": { "$ref": "#/components/examples/not_found" }, "rate_limited": { "$ref": "#/components/examples/rate_limited" }, "validation_failed": { "$ref": "#/components/examples/validation_failed" } } } } } } } }, "/v1/templates/{slug}/versions/{version}/files/entry": { "get": { "operationId": "getV1TemplatesSlugVersionsVersionFilesEntry", "summary": "Get one entry of a template version’s file tree", "tags": [ "Templates" ], "description": "404 path_not_found; 409 file_list_unavailable / file_list_indexing; 422 invalid_path.", "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 4096 }, "in": "query", "name": "path", "required": true, "description": "Absolute path (`/`, `/home/user`, no trailing slash)." }, { "schema": { "type": "string", "enum": [ "platform", "organization" ] }, "in": "query", "name": "owner", "required": false, "description": "Pick the platform template even when an organization template shadows its slug." }, { "schema": { "type": "string", "minLength": 1, "maxLength": 100, "pattern": "^[a-z0-9](?:[a-z0-9._-]{0,98}[a-z0-9])?$" }, "in": "path", "name": "slug", "required": true }, { "schema": { "type": "integer", "minimum": 1, "maximum": 2147483647 }, "in": "path", "name": "version", "required": true } ], "security": [ { "apiKey": [] } ], "responses": { "200": { "description": "One inode path of a template version. A path that is not valid UTF-8 shows each invalid byte as \\xNN.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TemplateFileEntry" } } } }, "4XX": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "examples": { "not_found": { "$ref": "#/components/examples/not_found" }, "rate_limited": { "$ref": "#/components/examples/rate_limited" }, "validation_failed": { "$ref": "#/components/examples/validation_failed" } } } } }, "5XX": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "examples": { "not_found": { "$ref": "#/components/examples/not_found" }, "rate_limited": { "$ref": "#/components/examples/rate_limited" }, "validation_failed": { "$ref": "#/components/examples/validation_failed" } } } } } } } }, "/v1/organizations/{organization_id}/templates/{slug}/diff": { "get": { "operationId": "getV1OrganizationsOrganizationIdTemplatesSlugDiff", "summary": "Diff two versions of a template (path, change, before, after)", "tags": [ "Templates" ], "description": "`from` is a version number of this template or `base` (the `to` version’s build base, which may be a platform version). Keyset-paginated by path; `path_prefix` narrows it (string prefix), `change` filters one kind. The first page (no cursor) carries `summary`. 409 file_list_unavailable / file_list_indexing when either version has no loaded file list.", "parameters": [ { "schema": { "type": "string", "pattern": "^(base|[1-9][0-9]{0,9})$" }, "in": "query", "name": "from", "required": true, "description": "A version number, or `base`." }, { "schema": { "type": "integer", "minimum": 1, "maximum": 2147483647 }, "in": "query", "name": "to", "required": true }, { "schema": { "type": "string", "minLength": 1, "maxLength": 4096, "pattern": "^/" }, "in": "query", "name": "path_prefix", "required": false }, { "schema": { "type": "string", "enum": [ "added", "removed", "changed", "type_changed", "metadata" ] }, "in": "query", "name": "change", "required": false }, { "schema": { "type": "integer", "minimum": 1, "maximum": 1000, "default": 200 }, "in": "query", "name": "limit", "required": false }, { "schema": { "type": "string", "maxLength": 8192 }, "in": "query", "name": "cursor", "required": false }, { "schema": { "type": "string", "enum": [ "platform", "organization" ] }, "in": "query", "name": "owner", "required": false, "description": "Pick the platform template even when an organization template shadows its slug." }, { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "organization_id", "required": true, "description": "UUIDv7, lowercase canonical form." }, { "schema": { "type": "string", "minLength": 1, "maxLength": 100, "pattern": "^[a-z0-9](?:[a-z0-9._-]{0,98}[a-z0-9])?$" }, "in": "path", "name": "slug", "required": true } ], "security": [ { "apiKey": [] } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TemplateDiffPage" } } } }, "4XX": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "examples": { "not_found": { "$ref": "#/components/examples/not_found" }, "rate_limited": { "$ref": "#/components/examples/rate_limited" }, "validation_failed": { "$ref": "#/components/examples/validation_failed" } } } } }, "5XX": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "examples": { "not_found": { "$ref": "#/components/examples/not_found" }, "rate_limited": { "$ref": "#/components/examples/rate_limited" }, "validation_failed": { "$ref": "#/components/examples/validation_failed" } } } } } } } }, "/v1/templates/{slug}/diff": { "get": { "operationId": "getV1TemplatesSlugDiff", "summary": "Diff two versions of a template (path, change, before, after)", "tags": [ "Templates" ], "description": "`from` is a version number of this template or `base` (the `to` version’s build base, which may be a platform version). Keyset-paginated by path; `path_prefix` narrows it (string prefix), `change` filters one kind. The first page (no cursor) carries `summary`. 409 file_list_unavailable / file_list_indexing when either version has no loaded file list.", "parameters": [ { "schema": { "type": "string", "pattern": "^(base|[1-9][0-9]{0,9})$" }, "in": "query", "name": "from", "required": true, "description": "A version number, or `base`." }, { "schema": { "type": "integer", "minimum": 1, "maximum": 2147483647 }, "in": "query", "name": "to", "required": true }, { "schema": { "type": "string", "minLength": 1, "maxLength": 4096, "pattern": "^/" }, "in": "query", "name": "path_prefix", "required": false }, { "schema": { "type": "string", "enum": [ "added", "removed", "changed", "type_changed", "metadata" ] }, "in": "query", "name": "change", "required": false }, { "schema": { "type": "integer", "minimum": 1, "maximum": 1000, "default": 200 }, "in": "query", "name": "limit", "required": false }, { "schema": { "type": "string", "maxLength": 8192 }, "in": "query", "name": "cursor", "required": false }, { "schema": { "type": "string", "enum": [ "platform", "organization" ] }, "in": "query", "name": "owner", "required": false, "description": "Pick the platform template even when an organization template shadows its slug." }, { "schema": { "type": "string", "minLength": 1, "maxLength": 100, "pattern": "^[a-z0-9](?:[a-z0-9._-]{0,98}[a-z0-9])?$" }, "in": "path", "name": "slug", "required": true } ], "security": [ { "apiKey": [] } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TemplateDiffPage" } } } }, "4XX": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "examples": { "not_found": { "$ref": "#/components/examples/not_found" }, "rate_limited": { "$ref": "#/components/examples/rate_limited" }, "validation_failed": { "$ref": "#/components/examples/validation_failed" } } } } }, "5XX": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "examples": { "not_found": { "$ref": "#/components/examples/not_found" }, "rate_limited": { "$ref": "#/components/examples/rate_limited" }, "validation_failed": { "$ref": "#/components/examples/validation_failed" } } } } } } } }, "/v1/organizations/{organization_id}/templates/{slug}/versions/{version}/recipe": { "get": { "operationId": "getV1OrganizationsOrganizationIdTemplatesSlugVersionsVersionRecipe", "summary": "Export the recipe and settings of a template version (request form, ready to build again)", "tags": [ "Templates" ], "description": "recipe: v1 {base, dockerfile, network} or the recipe v2 document (base as @, languages as {id, version}, files without size, settings as stored); building it again from the same base with the same API release, while its uploads exist, gives the same recipe_sha256. null for versions saved from a workspace or published by the platform. settings: the version’s TemplateSettings. Same visibility as the version (unpublished only for owners/admins of the owning organization).", "parameters": [ { "schema": { "type": "string", "enum": [ "platform", "organization" ] }, "in": "query", "name": "owner", "required": false, "description": "Pick the platform template even when an organization template shadows its slug." }, { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "organization_id", "required": true, "description": "UUIDv7, lowercase canonical form." }, { "schema": { "type": "string", "minLength": 1, "maxLength": 100, "pattern": "^[a-z0-9](?:[a-z0-9._-]{0,98}[a-z0-9])?$" }, "in": "path", "name": "slug", "required": true }, { "schema": { "type": "integer", "minimum": 1, "maximum": 2147483647 }, "in": "path", "name": "version", "required": true } ], "security": [ { "apiKey": [] } ], "responses": { "200": { "description": "The recipe and settings a version was built from (feeds \"Edit template\" and `shard templates export`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TemplateVersionRecipe" } } } }, "4XX": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "examples": { "not_found": { "$ref": "#/components/examples/not_found" }, "rate_limited": { "$ref": "#/components/examples/rate_limited" }, "validation_failed": { "$ref": "#/components/examples/validation_failed" } } } } }, "5XX": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "examples": { "not_found": { "$ref": "#/components/examples/not_found" }, "rate_limited": { "$ref": "#/components/examples/rate_limited" }, "validation_failed": { "$ref": "#/components/examples/validation_failed" } } } } } } } }, "/v1/templates/{slug}/versions/{version}/recipe": { "get": { "operationId": "getV1TemplatesSlugVersionsVersionRecipe", "summary": "Export the recipe and settings of a template version (request form, ready to build again)", "tags": [ "Templates" ], "description": "recipe: v1 {base, dockerfile, network} or the recipe v2 document (base as @, languages as {id, version}, files without size, settings as stored); building it again from the same base with the same API release, while its uploads exist, gives the same recipe_sha256. null for versions saved from a workspace or published by the platform. settings: the version’s TemplateSettings. Same visibility as the version (unpublished only for owners/admins of the owning organization).", "parameters": [ { "schema": { "type": "string", "enum": [ "platform", "organization" ] }, "in": "query", "name": "owner", "required": false, "description": "Pick the platform template even when an organization template shadows its slug." }, { "schema": { "type": "string", "minLength": 1, "maxLength": 100, "pattern": "^[a-z0-9](?:[a-z0-9._-]{0,98}[a-z0-9])?$" }, "in": "path", "name": "slug", "required": true }, { "schema": { "type": "integer", "minimum": 1, "maximum": 2147483647 }, "in": "path", "name": "version", "required": true } ], "security": [ { "apiKey": [] } ], "responses": { "200": { "description": "The recipe and settings a version was built from (feeds \"Edit template\" and `shard templates export`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TemplateVersionRecipe" } } } }, "4XX": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "examples": { "not_found": { "$ref": "#/components/examples/not_found" }, "rate_limited": { "$ref": "#/components/examples/rate_limited" }, "validation_failed": { "$ref": "#/components/examples/validation_failed" } } } } }, "5XX": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "examples": { "not_found": { "$ref": "#/components/examples/not_found" }, "rate_limited": { "$ref": "#/components/examples/rate_limited" }, "validation_failed": { "$ref": "#/components/examples/validation_failed" } } } } } } } }, "/v1/projects/{project_id}/secrets": { "get": { "operationId": "getV1ProjectsProjectIdSecrets", "summary": "List a project’s secrets (metadata only)", "tags": [ "Secrets" ], "description": "Project-scoped secrets only; organization secrets are listed under the organization.", "parameters": [ { "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 }, "in": "query", "name": "limit", "required": false }, { "schema": { "type": "string", "maxLength": 200 }, "in": "query", "name": "cursor", "required": false }, { "schema": { "type": "boolean", "default": false }, "in": "query", "name": "include_deleted", "required": false }, { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "project_id", "required": true, "description": "UUIDv7, lowercase canonical form." } ], "security": [ { "apiKey": [] } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "next_cursor" ], "properties": { "data": { "type": "array", "items": { "type": "object", "required": [ "id", "organization_id", "project_id", "scope", "name", "description", "current_version", "permissions", "created_by", "created_at", "updated_at", "rotated_at", "deleted_at" ], "properties": { "id": { "type": "string", "format": "uuid", "description": "UUIDv7, lowercase canonical form." }, "organization_id": { "type": "string", "format": "uuid", "description": "UUIDv7, lowercase canonical form." }, "project_id": { "anyOf": [ { "type": "string", "format": "uuid", "description": "UUIDv7, lowercase canonical form." }, { "type": "null" } ] }, "scope": { "anyOf": [ { "type": "string", "enum": [ "organization" ] }, { "type": "string", "enum": [ "project" ] } ] }, "name": { "type": "string", "description": "Environment variable name the value is injected as." }, "description": { "type": "string" }, "current_version": { "type": "integer", "minimum": 1 }, "permissions": { "type": "object", "required": [ "allowed_project_ids", "allowed_workspace_ids", "allowed_tools" ], "properties": { "allowed_project_ids": { "anyOf": [ { "type": "array", "items": { "type": "string", "format": "uuid", "description": "UUIDv7, lowercase canonical form." }, "description": "Organization secrets: projects whose workspaces may use it (null = every project of the organization, [] = none). Always null for project secrets." }, { "type": "null" } ] }, "allowed_workspace_ids": { "anyOf": [ { "type": "array", "items": { "type": "string", "format": "uuid", "description": "UUIDv7, lowercase canonical form." }, "description": "Only these workspaces (null = any workspace of the allowed projects). Not inherited by forks." }, { "type": "null" } ] }, "allowed_tools": { "type": "array", "items": { "type": "string", "enum": [ "exec", "files", "pty", "process", "git", "browser" ] }, "description": "Tools that may receive the value at session start (the tool token must carry the tool too)." } }, "additionalProperties": false }, "created_by": { "type": "object", "required": [ "type", "id" ], "properties": { "type": { "anyOf": [ { "type": "string", "enum": [ "user" ] }, { "type": "string", "enum": [ "api_key" ] } ] }, "id": { "type": "string", "format": "uuid", "description": "UUIDv7, lowercase canonical form." } }, "additionalProperties": false }, "created_at": { "type": "string", "format": "date-time", "description": "RFC 3339 UTC timestamp with Z." }, "updated_at": { "type": "string", "format": "date-time", "description": "RFC 3339 UTC timestamp with Z." }, "rotated_at": { "anyOf": [ { "type": "string", "format": "date-time", "description": "RFC 3339 UTC timestamp with Z." }, { "type": "null" } ] }, "deleted_at": { "anyOf": [ { "type": "string", "format": "date-time", "description": "RFC 3339 UTC timestamp with Z." }, { "type": "null" } ] } }, "additionalProperties": false, "description": "Secret metadata. Values are write-only: no API returns them except the cell resolution endpoint." } }, "next_cursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "additionalProperties": false } } } }, "4XX": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "examples": { "not_found": { "$ref": "#/components/examples/not_found" }, "rate_limited": { "$ref": "#/components/examples/rate_limited" }, "validation_failed": { "$ref": "#/components/examples/validation_failed" } } } } }, "5XX": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "examples": { "not_found": { "$ref": "#/components/examples/not_found" }, "rate_limited": { "$ref": "#/components/examples/rate_limited" }, "validation_failed": { "$ref": "#/components/examples/validation_failed" } } } } } } }, "post": { "operationId": "postV1ProjectsProjectIdSecrets", "summary": "Create a project secret (owner/admin, or an API key of this project)", "tags": [ "Secrets" ], "description": "The value is encrypted (KMS envelope) and never returned. `allowed_tools` defaults to [exec, pty]. 409 when the name exists in this project. Supports Idempotency-Key.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "name", "value" ], "properties": { "name": { "type": "string", "pattern": "^[A-Z_][A-Z0-9_]{0,127}$", "description": "Environment-variable-safe name, unique per scope (`SHARDFLUX_` prefix reserved)." }, "description": { "type": "string", "maxLength": 500, "pattern": "^[^\\u0000-\\u001f\\u007f]*$" }, "value": { "type": "string", "minLength": 1, "maxLength": 65536, "description": "UTF-8 text, at most 65536 bytes, no NUL characters. Write-only: never returned by any management API." }, "allowed_workspace_ids": { "anyOf": [ { "type": "array", "items": { "type": "string", "format": "uuid", "description": "UUIDv7, lowercase canonical form." }, "uniqueItems": true, "maxItems": 100 }, { "type": "null" } ], "description": "Default null (any workspace of the project)." }, "allowed_tools": { "type": "array", "items": { "type": "string", "enum": [ "exec", "files", "pty", "process", "git", "browser" ] }, "uniqueItems": true, "minItems": 1, "maxItems": 6 } }, "additionalProperties": false } } } }, "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "project_id", "required": true, "description": "UUIDv7, lowercase canonical form." } ], "security": [ { "apiKey": [] } ], "responses": { "201": { "description": "Secret metadata. Values are write-only: no API returns them except the cell resolution endpoint.", "content": { "application/json": { "schema": { "type": "object", "required": [ "id", "organization_id", "project_id", "scope", "name", "description", "current_version", "permissions", "created_by", "created_at", "updated_at", "rotated_at", "deleted_at" ], "properties": { "id": { "type": "string", "format": "uuid", "description": "UUIDv7, lowercase canonical form." }, "organization_id": { "type": "string", "format": "uuid", "description": "UUIDv7, lowercase canonical form." }, "project_id": { "anyOf": [ { "type": "string", "format": "uuid", "description": "UUIDv7, lowercase canonical form." }, { "type": "null" } ] }, "scope": { "anyOf": [ { "type": "string", "enum": [ "organization" ] }, { "type": "string", "enum": [ "project" ] } ] }, "name": { "type": "string", "description": "Environment variable name the value is injected as." }, "description": { "type": "string" }, "current_version": { "type": "integer", "minimum": 1 }, "permissions": { "type": "object", "required": [ "allowed_project_ids", "allowed_workspace_ids", "allowed_tools" ], "properties": { "allowed_project_ids": { "anyOf": [ { "type": "array", "items": { "type": "string", "format": "uuid", "description": "UUIDv7, lowercase canonical form." }, "description": "Organization secrets: projects whose workspaces may use it (null = every project of the organization, [] = none). Always null for project secrets." }, { "type": "null" } ] }, "allowed_workspace_ids": { "anyOf": [ { "type": "array", "items": { "type": "string", "format": "uuid", "description": "UUIDv7, lowercase canonical form." }, "description": "Only these workspaces (null = any workspace of the allowed projects). Not inherited by forks." }, { "type": "null" } ] }, "allowed_tools": { "type": "array", "items": { "type": "string", "enum": [ "exec", "files", "pty", "process", "git", "browser" ] }, "description": "Tools that may receive the value at session start (the tool token must carry the tool too)." } }, "additionalProperties": false }, "created_by": { "type": "object", "required": [ "type", "id" ], "properties": { "type": { "anyOf": [ { "type": "string", "enum": [ "user" ] }, { "type": "string", "enum": [ "api_key" ] } ] }, "id": { "type": "string", "format": "uuid", "description": "UUIDv7, lowercase canonical form." } }, "additionalProperties": false }, "created_at": { "type": "string", "format": "date-time", "description": "RFC 3339 UTC timestamp with Z." }, "updated_at": { "type": "string", "format": "date-time", "description": "RFC 3339 UTC timestamp with Z." }, "rotated_at": { "anyOf": [ { "type": "string", "format": "date-time", "description": "RFC 3339 UTC timestamp with Z." }, { "type": "null" } ] }, "deleted_at": { "anyOf": [ { "type": "string", "format": "date-time", "description": "RFC 3339 UTC timestamp with Z." }, { "type": "null" } ] } }, "additionalProperties": false, "description": "Secret metadata. Values are write-only: no API returns them except the cell resolution endpoint." } } } }, "4XX": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "examples": { "not_found": { "$ref": "#/components/examples/not_found" }, "rate_limited": { "$ref": "#/components/examples/rate_limited" }, "validation_failed": { "$ref": "#/components/examples/validation_failed" } } } } }, "5XX": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "examples": { "not_found": { "$ref": "#/components/examples/not_found" }, "rate_limited": { "$ref": "#/components/examples/rate_limited" }, "validation_failed": { "$ref": "#/components/examples/validation_failed" } } } } } } } }, "/v1/secrets/{secret_id}": { "get": { "operationId": "getV1SecretsSecretId", "summary": "Get secret metadata (never the value)", "tags": [ "Secrets" ], "description": "Deleted secrets stay readable (deleted_at set).", "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "secret_id", "required": true, "description": "UUIDv7, lowercase canonical form." } ], "security": [ { "apiKey": [] } ], "responses": { "200": { "description": "Secret metadata. Values are write-only: no API returns them except the cell resolution endpoint.", "content": { "application/json": { "schema": { "type": "object", "required": [ "id", "organization_id", "project_id", "scope", "name", "description", "current_version", "permissions", "created_by", "created_at", "updated_at", "rotated_at", "deleted_at" ], "properties": { "id": { "type": "string", "format": "uuid", "description": "UUIDv7, lowercase canonical form." }, "organization_id": { "type": "string", "format": "uuid", "description": "UUIDv7, lowercase canonical form." }, "project_id": { "anyOf": [ { "type": "string", "format": "uuid", "description": "UUIDv7, lowercase canonical form." }, { "type": "null" } ] }, "scope": { "anyOf": [ { "type": "string", "enum": [ "organization" ] }, { "type": "string", "enum": [ "project" ] } ] }, "name": { "type": "string", "description": "Environment variable name the value is injected as." }, "description": { "type": "string" }, "current_version": { "type": "integer", "minimum": 1 }, "permissions": { "type": "object", "required": [ "allowed_project_ids", "allowed_workspace_ids", "allowed_tools" ], "properties": { "allowed_project_ids": { "anyOf": [ { "type": "array", "items": { "type": "string", "format": "uuid", "description": "UUIDv7, lowercase canonical form." }, "description": "Organization secrets: projects whose workspaces may use it (null = every project of the organization, [] = none). Always null for project secrets." }, { "type": "null" } ] }, "allowed_workspace_ids": { "anyOf": [ { "type": "array", "items": { "type": "string", "format": "uuid", "description": "UUIDv7, lowercase canonical form." }, "description": "Only these workspaces (null = any workspace of the allowed projects). Not inherited by forks." }, { "type": "null" } ] }, "allowed_tools": { "type": "array", "items": { "type": "string", "enum": [ "exec", "files", "pty", "process", "git", "browser" ] }, "description": "Tools that may receive the value at session start (the tool token must carry the tool too)." } }, "additionalProperties": false }, "created_by": { "type": "object", "required": [ "type", "id" ], "properties": { "type": { "anyOf": [ { "type": "string", "enum": [ "user" ] }, { "type": "string", "enum": [ "api_key" ] } ] }, "id": { "type": "string", "format": "uuid", "description": "UUIDv7, lowercase canonical form." } }, "additionalProperties": false }, "created_at": { "type": "string", "format": "date-time", "description": "RFC 3339 UTC timestamp with Z." }, "updated_at": { "type": "string", "format": "date-time", "description": "RFC 3339 UTC timestamp with Z." }, "rotated_at": { "anyOf": [ { "type": "string", "format": "date-time", "description": "RFC 3339 UTC timestamp with Z." }, { "type": "null" } ] }, "deleted_at": { "anyOf": [ { "type": "string", "format": "date-time", "description": "RFC 3339 UTC timestamp with Z." }, { "type": "null" } ] } }, "additionalProperties": false, "description": "Secret metadata. Values are write-only: no API returns them except the cell resolution endpoint." } } } }, "4XX": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "examples": { "not_found": { "$ref": "#/components/examples/not_found" }, "rate_limited": { "$ref": "#/components/examples/rate_limited" }, "validation_failed": { "$ref": "#/components/examples/validation_failed" } } } } }, "5XX": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "examples": { "not_found": { "$ref": "#/components/examples/not_found" }, "rate_limited": { "$ref": "#/components/examples/rate_limited" }, "validation_failed": { "$ref": "#/components/examples/validation_failed" } } } } } } }, "delete": { "operationId": "deleteV1SecretsSecretId", "summary": "Delete a secret (tombstone; erases every stored value; resolution stops immediately)", "tags": [ "Secrets" ], "description": "Any session start after this returns it as denied. The name becomes reusable. The name is removed from every workspace binding that referred to this secret (same transaction, one audit event per workspace). Values already injected into running processes cannot be recalled. Repeating returns 204.", "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "secret_id", "required": true, "description": "UUIDv7, lowercase canonical form." } ], "security": [ { "apiKey": [] } ], "responses": { "204": { "description": "No content." }, "4XX": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "examples": { "not_found": { "$ref": "#/components/examples/not_found" }, "rate_limited": { "$ref": "#/components/examples/rate_limited" }, "validation_failed": { "$ref": "#/components/examples/validation_failed" } } } } }, "5XX": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "examples": { "not_found": { "$ref": "#/components/examples/not_found" }, "rate_limited": { "$ref": "#/components/examples/rate_limited" }, "validation_failed": { "$ref": "#/components/examples/validation_failed" } } } } } } }, "patch": { "operationId": "patchV1SecretsSecretId", "summary": "Update a secret’s description or usage permissions", "tags": [ "Secrets" ], "description": "Takes effect for the next session start that resolves it. Names are immutable (delete and recreate).", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "description": { "type": "string", "maxLength": 500, "pattern": "^[^\\u0000-\\u001f\\u007f]*$" }, "allowed_project_ids": { "anyOf": [ { "type": "array", "items": { "type": "string", "format": "uuid", "description": "UUIDv7, lowercase canonical form." }, "uniqueItems": true, "maxItems": 100 }, { "type": "null" } ] }, "allowed_workspace_ids": { "anyOf": [ { "type": "array", "items": { "type": "string", "format": "uuid", "description": "UUIDv7, lowercase canonical form." }, "uniqueItems": true, "maxItems": 100 }, { "type": "null" } ] }, "allowed_tools": { "type": "array", "items": { "type": "string", "enum": [ "exec", "files", "pty", "process", "git", "browser" ] }, "uniqueItems": true, "minItems": 1, "maxItems": 6 } }, "additionalProperties": false, "minProperties": 1 } } } }, "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "secret_id", "required": true, "description": "UUIDv7, lowercase canonical form." } ], "security": [ { "apiKey": [] } ], "responses": { "200": { "description": "Secret metadata. Values are write-only: no API returns them except the cell resolution endpoint.", "content": { "application/json": { "schema": { "type": "object", "required": [ "id", "organization_id", "project_id", "scope", "name", "description", "current_version", "permissions", "created_by", "created_at", "updated_at", "rotated_at", "deleted_at" ], "properties": { "id": { "type": "string", "format": "uuid", "description": "UUIDv7, lowercase canonical form." }, "organization_id": { "type": "string", "format": "uuid", "description": "UUIDv7, lowercase canonical form." }, "project_id": { "anyOf": [ { "type": "string", "format": "uuid", "description": "UUIDv7, lowercase canonical form." }, { "type": "null" } ] }, "scope": { "anyOf": [ { "type": "string", "enum": [ "organization" ] }, { "type": "string", "enum": [ "project" ] } ] }, "name": { "type": "string", "description": "Environment variable name the value is injected as." }, "description": { "type": "string" }, "current_version": { "type": "integer", "minimum": 1 }, "permissions": { "type": "object", "required": [ "allowed_project_ids", "allowed_workspace_ids", "allowed_tools" ], "properties": { "allowed_project_ids": { "anyOf": [ { "type": "array", "items": { "type": "string", "format": "uuid", "description": "UUIDv7, lowercase canonical form." }, "description": "Organization secrets: projects whose workspaces may use it (null = every project of the organization, [] = none). Always null for project secrets." }, { "type": "null" } ] }, "allowed_workspace_ids": { "anyOf": [ { "type": "array", "items": { "type": "string", "format": "uuid", "description": "UUIDv7, lowercase canonical form." }, "description": "Only these workspaces (null = any workspace of the allowed projects). Not inherited by forks." }, { "type": "null" } ] }, "allowed_tools": { "type": "array", "items": { "type": "string", "enum": [ "exec", "files", "pty", "process", "git", "browser" ] }, "description": "Tools that may receive the value at session start (the tool token must carry the tool too)." } }, "additionalProperties": false }, "created_by": { "type": "object", "required": [ "type", "id" ], "properties": { "type": { "anyOf": [ { "type": "string", "enum": [ "user" ] }, { "type": "string", "enum": [ "api_key" ] } ] }, "id": { "type": "string", "format": "uuid", "description": "UUIDv7, lowercase canonical form." } }, "additionalProperties": false }, "created_at": { "type": "string", "format": "date-time", "description": "RFC 3339 UTC timestamp with Z." }, "updated_at": { "type": "string", "format": "date-time", "description": "RFC 3339 UTC timestamp with Z." }, "rotated_at": { "anyOf": [ { "type": "string", "format": "date-time", "description": "RFC 3339 UTC timestamp with Z." }, { "type": "null" } ] }, "deleted_at": { "anyOf": [ { "type": "string", "format": "date-time", "description": "RFC 3339 UTC timestamp with Z." }, { "type": "null" } ] } }, "additionalProperties": false, "description": "Secret metadata. Values are write-only: no API returns them except the cell resolution endpoint." } } } }, "4XX": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "examples": { "not_found": { "$ref": "#/components/examples/not_found" }, "rate_limited": { "$ref": "#/components/examples/rate_limited" }, "validation_failed": { "$ref": "#/components/examples/validation_failed" } } } } }, "5XX": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "examples": { "not_found": { "$ref": "#/components/examples/not_found" }, "rate_limited": { "$ref": "#/components/examples/rate_limited" }, "validation_failed": { "$ref": "#/components/examples/validation_failed" } } } } } } } }, "/v1/secrets/{secret_id}/versions": { "get": { "operationId": "getV1SecretsSecretIdVersions", "summary": "List a secret’s versions, newest first (metadata only)", "tags": [ "Secrets" ], "parameters": [ { "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 }, "in": "query", "name": "limit", "required": false }, { "schema": { "type": "string", "maxLength": 200 }, "in": "query", "name": "cursor", "required": false }, { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "secret_id", "required": true, "description": "UUIDv7, lowercase canonical form." } ], "security": [ { "apiKey": [] } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "next_cursor" ], "properties": { "data": { "type": "array", "items": { "type": "object", "required": [ "secret_id", "version", "state", "created_by", "created_at", "destroyed_at", "destroyed_reason" ], "properties": { "secret_id": { "type": "string", "format": "uuid", "description": "UUIDv7, lowercase canonical form." }, "version": { "type": "integer", "minimum": 1 }, "state": { "anyOf": [ { "type": "string", "enum": [ "current" ] }, { "type": "string", "enum": [ "destroyed" ] } ], "description": "current: the value resolved at session start. destroyed: value erased (rotated or deleted); metadata kept for audit." }, "created_by": { "type": "object", "required": [ "type", "id" ], "properties": { "type": { "anyOf": [ { "type": "string", "enum": [ "user" ] }, { "type": "string", "enum": [ "api_key" ] } ] }, "id": { "type": "string", "format": "uuid", "description": "UUIDv7, lowercase canonical form." } }, "additionalProperties": false }, "created_at": { "type": "string", "format": "date-time", "description": "RFC 3339 UTC timestamp with Z." }, "destroyed_at": { "anyOf": [ { "type": "string", "format": "date-time", "description": "RFC 3339 UTC timestamp with Z." }, { "type": "null" } ] }, "destroyed_reason": { "anyOf": [ { "anyOf": [ { "type": "string", "enum": [ "rotated" ] }, { "type": "string", "enum": [ "deleted" ] } ] }, { "type": "null" } ] } }, "additionalProperties": false } }, "next_cursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "additionalProperties": false } } } }, "4XX": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "examples": { "not_found": { "$ref": "#/components/examples/not_found" }, "rate_limited": { "$ref": "#/components/examples/rate_limited" }, "validation_failed": { "$ref": "#/components/examples/validation_failed" } } } } }, "5XX": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "examples": { "not_found": { "$ref": "#/components/examples/not_found" }, "rate_limited": { "$ref": "#/components/examples/rate_limited" }, "validation_failed": { "$ref": "#/components/examples/validation_failed" } } } } } } }, "post": { "operationId": "postV1SecretsSecretIdVersions", "summary": "Rotate: store a new value as the next version", "tags": [ "Secrets" ], "description": "The new version is used from the next session start; every older version’s value is erased in the same transaction (metadata kept). Values already injected into running processes are not recalled. Supports Idempotency-Key.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "value" ], "properties": { "value": { "type": "string", "minLength": 1, "maxLength": 65536, "description": "UTF-8 text, at most 65536 bytes, no NUL characters. Write-only: never returned by any management API." } }, "additionalProperties": false } } } }, "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "secret_id", "required": true, "description": "UUIDv7, lowercase canonical form." } ], "security": [ { "apiKey": [] } ], "responses": { "201": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "required": [ "secret", "version" ], "properties": { "secret": { "type": "object", "required": [ "id", "organization_id", "project_id", "scope", "name", "description", "current_version", "permissions", "created_by", "created_at", "updated_at", "rotated_at", "deleted_at" ], "properties": { "id": { "type": "string", "format": "uuid", "description": "UUIDv7, lowercase canonical form." }, "organization_id": { "type": "string", "format": "uuid", "description": "UUIDv7, lowercase canonical form." }, "project_id": { "anyOf": [ { "type": "string", "format": "uuid", "description": "UUIDv7, lowercase canonical form." }, { "type": "null" } ] }, "scope": { "anyOf": [ { "type": "string", "enum": [ "organization" ] }, { "type": "string", "enum": [ "project" ] } ] }, "name": { "type": "string", "description": "Environment variable name the value is injected as." }, "description": { "type": "string" }, "current_version": { "type": "integer", "minimum": 1 }, "permissions": { "type": "object", "required": [ "allowed_project_ids", "allowed_workspace_ids", "allowed_tools" ], "properties": { "allowed_project_ids": { "anyOf": [ { "type": "array", "items": { "type": "string", "format": "uuid", "description": "UUIDv7, lowercase canonical form." }, "description": "Organization secrets: projects whose workspaces may use it (null = every project of the organization, [] = none). Always null for project secrets." }, { "type": "null" } ] }, "allowed_workspace_ids": { "anyOf": [ { "type": "array", "items": { "type": "string", "format": "uuid", "description": "UUIDv7, lowercase canonical form." }, "description": "Only these workspaces (null = any workspace of the allowed projects). Not inherited by forks." }, { "type": "null" } ] }, "allowed_tools": { "type": "array", "items": { "type": "string", "enum": [ "exec", "files", "pty", "process", "git", "browser" ] }, "description": "Tools that may receive the value at session start (the tool token must carry the tool too)." } }, "additionalProperties": false }, "created_by": { "type": "object", "required": [ "type", "id" ], "properties": { "type": { "anyOf": [ { "type": "string", "enum": [ "user" ] }, { "type": "string", "enum": [ "api_key" ] } ] }, "id": { "type": "string", "format": "uuid", "description": "UUIDv7, lowercase canonical form." } }, "additionalProperties": false }, "created_at": { "type": "string", "format": "date-time", "description": "RFC 3339 UTC timestamp with Z." }, "updated_at": { "type": "string", "format": "date-time", "description": "RFC 3339 UTC timestamp with Z." }, "rotated_at": { "anyOf": [ { "type": "string", "format": "date-time", "description": "RFC 3339 UTC timestamp with Z." }, { "type": "null" } ] }, "deleted_at": { "anyOf": [ { "type": "string", "format": "date-time", "description": "RFC 3339 UTC timestamp with Z." }, { "type": "null" } ] } }, "additionalProperties": false, "description": "Secret metadata. Values are write-only: no API returns them except the cell resolution endpoint." }, "version": { "type": "object", "required": [ "secret_id", "version", "state", "created_by", "created_at", "destroyed_at", "destroyed_reason" ], "properties": { "secret_id": { "type": "string", "format": "uuid", "description": "UUIDv7, lowercase canonical form." }, "version": { "type": "integer", "minimum": 1 }, "state": { "anyOf": [ { "type": "string", "enum": [ "current" ] }, { "type": "string", "enum": [ "destroyed" ] } ], "description": "current: the value resolved at session start. destroyed: value erased (rotated or deleted); metadata kept for audit." }, "created_by": { "type": "object", "required": [ "type", "id" ], "properties": { "type": { "anyOf": [ { "type": "string", "enum": [ "user" ] }, { "type": "string", "enum": [ "api_key" ] } ] }, "id": { "type": "string", "format": "uuid", "description": "UUIDv7, lowercase canonical form." } }, "additionalProperties": false }, "created_at": { "type": "string", "format": "date-time", "description": "RFC 3339 UTC timestamp with Z." }, "destroyed_at": { "anyOf": [ { "type": "string", "format": "date-time", "description": "RFC 3339 UTC timestamp with Z." }, { "type": "null" } ] }, "destroyed_reason": { "anyOf": [ { "anyOf": [ { "type": "string", "enum": [ "rotated" ] }, { "type": "string", "enum": [ "deleted" ] } ] }, { "type": "null" } ] } }, "additionalProperties": false } }, "additionalProperties": false } } } }, "4XX": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "examples": { "not_found": { "$ref": "#/components/examples/not_found" }, "rate_limited": { "$ref": "#/components/examples/rate_limited" }, "validation_failed": { "$ref": "#/components/examples/validation_failed" } } } } }, "5XX": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "examples": { "not_found": { "$ref": "#/components/examples/not_found" }, "rate_limited": { "$ref": "#/components/examples/rate_limited" }, "validation_failed": { "$ref": "#/components/examples/validation_failed" } } } } } } } }, "/v1/workspaces/{workspace_id}/secrets": { "get": { "operationId": "getV1WorkspacesWorkspaceIdSecrets", "summary": "Secret names bound to a workspace, with per-name status (never values)", "tags": [ "Workspaces" ], "description": "Bound secrets are injected into every exec and PTY start of the workspace together with the call’s `secret_refs`. status: available | not_allowed | deleted. Deleted workspaces stay readable.", "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "workspace_id", "required": true, "description": "UUIDv7, lowercase canonical form." } ], "security": [ { "apiKey": [] } ], "responses": { "200": { "description": "Secret names bound to a workspace and their current status. Never values.", "content": { "application/json": { "schema": { "type": "object", "required": [ "workspace_id", "names", "secrets" ], "properties": { "workspace_id": { "type": "string", "format": "uuid", "description": "UUIDv7, lowercase canonical form." }, "names": { "type": "array", "items": { "type": "string" }, "description": "The bound names, in the order they were given." }, "secrets": { "type": "array", "items": { "type": "object", "required": [ "name", "status", "secret_id", "scope" ], "properties": { "name": { "type": "string" }, "status": { "anyOf": [ { "type": "string", "enum": [ "available" ] }, { "type": "string", "enum": [ "not_allowed" ] }, { "type": "string", "enum": [ "deleted" ] } ], "description": "available: injected at the next exec/PTY start. not_allowed: a live secret exists but its permissions no longer allow this workspace (project, workspace id, or exec+pty); exec/PTY starts are refused with 403 secret_not_available until fixed. deleted: no live secret of this name is visible to the workspace." }, "secret_id": { "anyOf": [ { "type": "string", "format": "uuid", "description": "UUIDv7, lowercase canonical form." }, { "type": "null" } ] }, "scope": { "anyOf": [ { "anyOf": [ { "type": "string", "enum": [ "organization" ] }, { "type": "string", "enum": [ "project" ] } ] }, { "type": "null" } ] } }, "additionalProperties": false } } }, "additionalProperties": false, "description": "Secret names bound to a workspace and their current status. Never values." } } } }, "4XX": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "examples": { "not_found": { "$ref": "#/components/examples/not_found" }, "rate_limited": { "$ref": "#/components/examples/rate_limited" }, "validation_failed": { "$ref": "#/components/examples/validation_failed" } } } } }, "5XX": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "examples": { "not_found": { "$ref": "#/components/examples/not_found" }, "rate_limited": { "$ref": "#/components/examples/rate_limited" }, "validation_failed": { "$ref": "#/components/examples/validation_failed" } } } } } } }, "put": { "operationId": "putV1WorkspacesWorkspaceIdSecrets", "summary": "Replace the secret names bound to a workspace", "tags": [ "Workspaces" ], "description": "Replaces the whole binding (`names: []` clears it); applies from the next exec/PTY start (running processes keep their environment). Every name must be a live secret this workspace may use (its project, its id, and allowed_tools including exec and pty), else 422 details.reason secret_not_available with details.names and nothing changes. A name equal to a key of the template version’s env or one of its text inputs is 422 env_collision (details.name;). Exactly the given names are bound (the version’s secret inputs join the binding only through open). Audited when the binding changes. 409 workspace_deleted.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "names" ], "properties": { "names": { "type": "array", "items": { "type": "string", "pattern": "^[A-Z_][A-Z0-9_]{0,127}$" }, "maxItems": 50, "uniqueItems": true, "description": "Secret names bound to the workspace (max 50, unique): injected as environment variables into every exec and PTY start (terminal sessions included), together with the call’s own `secret_refs`. Each must name a live secret this workspace may use (its project, its id, and allowed_tools including exec and pty), else 422 details.reason secret_not_available with details.names." } }, "additionalProperties": false } } } }, "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "workspace_id", "required": true, "description": "UUIDv7, lowercase canonical form." } ], "security": [ { "apiKey": [] } ], "responses": { "200": { "description": "Secret names bound to a workspace and their current status. Never values.", "content": { "application/json": { "schema": { "type": "object", "required": [ "workspace_id", "names", "secrets" ], "properties": { "workspace_id": { "type": "string", "format": "uuid", "description": "UUIDv7, lowercase canonical form." }, "names": { "type": "array", "items": { "type": "string" }, "description": "The bound names, in the order they were given." }, "secrets": { "type": "array", "items": { "type": "object", "required": [ "name", "status", "secret_id", "scope" ], "properties": { "name": { "type": "string" }, "status": { "anyOf": [ { "type": "string", "enum": [ "available" ] }, { "type": "string", "enum": [ "not_allowed" ] }, { "type": "string", "enum": [ "deleted" ] } ], "description": "available: injected at the next exec/PTY start. not_allowed: a live secret exists but its permissions no longer allow this workspace (project, workspace id, or exec+pty); exec/PTY starts are refused with 403 secret_not_available until fixed. deleted: no live secret of this name is visible to the workspace." }, "secret_id": { "anyOf": [ { "type": "string", "format": "uuid", "description": "UUIDv7, lowercase canonical form." }, { "type": "null" } ] }, "scope": { "anyOf": [ { "anyOf": [ { "type": "string", "enum": [ "organization" ] }, { "type": "string", "enum": [ "project" ] } ] }, { "type": "null" } ] } }, "additionalProperties": false } } }, "additionalProperties": false, "description": "Secret names bound to a workspace and their current status. Never values." } } } }, "4XX": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "examples": { "not_found": { "$ref": "#/components/examples/not_found" }, "rate_limited": { "$ref": "#/components/examples/rate_limited" }, "validation_failed": { "$ref": "#/components/examples/validation_failed" } } } } }, "5XX": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "examples": { "not_found": { "$ref": "#/components/examples/not_found" }, "rate_limited": { "$ref": "#/components/examples/rate_limited" }, "validation_failed": { "$ref": "#/components/examples/validation_failed" } } } } } } } }, "/v1/projects/{project_id}/egress-policy": { "get": { "operationId": "getV1ProjectsProjectIdEgressPolicy", "summary": "Get a project’s egress policy (default for its workspaces)", "tags": [ "Egress policy" ], "description": "`version` (also the ETag) is the value to send as If-Match. Without a project policy the effective policy is the platform default (allow_all).", "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "project_id", "required": true, "description": "UUIDv7, lowercase canonical form." } ], "security": [ { "apiKey": [] } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "required": [ "organization_id", "project_id", "version", "policy", "effective", "organization_override", "propagation" ], "properties": { "organization_id": { "type": "string", "format": "uuid", "description": "UUIDv7, lowercase canonical form." }, "project_id": { "type": "string", "format": "uuid", "description": "UUIDv7, lowercase canonical form." }, "version": { "type": "integer", "minimum": 0, "description": "Current version number of the project policy (0 = none); send as If-Match." }, "policy": { "anyOf": [ { "type": "object", "required": [ "id", "scope", "project_id", "workspace_id", "version", "kind", "mode", "rules", "cidrs", "policy_sha256", "created_by", "created_at" ], "properties": { "id": { "type": "string", "format": "uuid", "description": "UUIDv7, lowercase canonical form." }, "scope": { "anyOf": [ { "type": "string", "enum": [ "project" ] }, { "type": "string", "enum": [ "workspace" ] } ] }, "project_id": { "type": "string", "format": "uuid", "description": "UUIDv7, lowercase canonical form." }, "workspace_id": { "anyOf": [ { "type": "string", "format": "uuid", "description": "UUIDv7, lowercase canonical form." }, { "type": "null" } ] }, "version": { "type": "integer", "minimum": 1 }, "kind": { "anyOf": [ { "type": "string", "enum": [ "policy" ] }, { "type": "string", "enum": [ "cleared" ] } ], "description": "cleared: the workspace override was removed (falls back to the project policy)." }, "mode": { "anyOf": [ { "type": "string", "enum": [ "allow_all", "allowlist", "deny_all" ] }, { "type": "null" } ] }, "rules": { "type": "array", "items": { "type": "object", "required": [ "host", "ports", "protocols" ], "properties": { "host": { "type": "string", "description": "Lower-case IDNA A-label FQDN, or `*.` + FQDN (matches exactly one extra label)." }, "ports": { "type": "array", "items": { "type": "integer", "minimum": 1, "maximum": 65535 } }, "protocols": { "type": "array", "items": { "type": "string", "enum": [ "tcp" ] } } }, "additionalProperties": false } }, "cidrs": { "type": "array", "items": { "type": "string" } }, "policy_sha256": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "created_by": { "type": "object", "required": [ "type", "id" ], "properties": { "type": { "anyOf": [ { "type": "string", "enum": [ "user" ] }, { "type": "string", "enum": [ "api_key" ] } ] }, "id": { "type": "string", "format": "uuid", "description": "UUIDv7, lowercase canonical form." } }, "additionalProperties": false }, "created_at": { "type": "string", "format": "date-time", "description": "RFC 3339 UTC timestamp with Z." } }, "additionalProperties": false }, { "type": "null" } ] }, "effective": { "type": "object", "required": [ "source", "policy_version_id", "policy_version", "mode", "rules", "cidrs", "policy_sha256" ], "properties": { "source": { "anyOf": [ { "type": "string", "enum": [ "organization" ] }, { "type": "string", "enum": [ "workspace" ] }, { "type": "string", "enum": [ "project" ] }, { "type": "string", "enum": [ "platform_default" ] } ], "description": "organization: an organization egress override (deny_all, e.g. outbound transfer allowance used up;) wins over every policy until it lifts." }, "policy_version_id": { "anyOf": [ { "type": "string", "format": "uuid", "description": "UUIDv7, lowercase canonical form." }, { "type": "null" } ] }, "policy_version": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "mode": { "type": "string", "enum": [ "allow_all", "allowlist", "deny_all" ] }, "rules": { "type": "array", "items": { "type": "object", "required": [ "host", "ports", "protocols" ], "properties": { "host": { "type": "string", "description": "Lower-case IDNA A-label FQDN, or `*.` + FQDN (matches exactly one extra label)." }, "ports": { "type": "array", "items": { "type": "integer", "minimum": 1, "maximum": 65535 } }, "protocols": { "type": "array", "items": { "type": "string", "enum": [ "tcp" ] } } }, "additionalProperties": false } }, "cidrs": { "type": "array", "items": { "type": "string" } }, "policy_sha256": { "type": "string", "description": "SHA-256 of the canonical policy document; what the host acknowledges." } }, "additionalProperties": false }, "organization_override": { "anyOf": [ { "type": "object", "required": [ "mode", "reason", "set_at", "lifts_at" ], "properties": { "mode": { "type": "string", "enum": [ "deny_all" ] }, "reason": { "type": "string", "enum": [ "transfer_allowance_exhausted" ] }, "set_at": { "type": "string", "format": "date-time", "description": "RFC 3339 UTC timestamp with Z." }, "lifts_at": { "type": "string", "format": "date-time", "description": "RFC 3339 UTC timestamp with Z." } }, "additionalProperties": false, "description": "Active organization egress override; policies stay stored and apply again when it lifts." }, { "type": "null" } ] }, "propagation": { "type": "object", "required": [ "workspaces", "enforced", "pending", "failed", "not_enforced", "truncated" ], "properties": { "workspaces": { "type": "integer", "description": "Live workspaces (not deleted, with a VM or starting) whose effective policy is this project policy." }, "enforced": { "type": "integer" }, "pending": { "type": "integer" }, "failed": { "type": "integer" }, "not_enforced": { "type": "integer", "description": "Not yet acknowledged for the current version and ownership epoch." }, "truncated": { "type": "boolean", "description": "Counted over at most 5000 workspaces." } }, "additionalProperties": false, "description": "Where the cell stands applying the current project policy (from its acknowledgements)." } }, "additionalProperties": false } } } }, "4XX": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "examples": { "not_found": { "$ref": "#/components/examples/not_found" }, "rate_limited": { "$ref": "#/components/examples/rate_limited" }, "validation_failed": { "$ref": "#/components/examples/validation_failed" } } } } }, "5XX": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "examples": { "not_found": { "$ref": "#/components/examples/not_found" }, "rate_limited": { "$ref": "#/components/examples/rate_limited" }, "validation_failed": { "$ref": "#/components/examples/validation_failed" } } } } } } }, "put": { "operationId": "putV1ProjectsProjectIdEgressPolicy", "summary": "Replace a project’s egress policy (creates a new immutable version)", "tags": [ "Egress policy" ], "description": "mode allow_all | allowlist | deny_all; rules/cidrs only with allowlist. Hosts: exact FQDN or `*.` single-label wildcard (IDNA-normalized, lower-case); IP literals and localhost-like names are rejected. Ports 1-65535 (default [443]); protocols tcp only. cidrs: public ranges only. Optional If-Match: (409 conflict with details.reason version_mismatch). Owner/admin or an API key of this project with tool permissions.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "mode" ], "properties": { "mode": { "type": "string", "enum": [ "allow_all", "allowlist", "deny_all" ] }, "rules": { "type": "array", "items": { "type": "object", "required": [ "host" ], "properties": { "host": { "type": "string", "minLength": 1, "maxLength": 300 }, "ports": { "type": "array", "items": { "type": "integer" }, "maxItems": 64, "description": "Default [443]." }, "protocols": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 16 }, "maxItems": 4, "description": "Only \"tcp\" (default); udp/quic are rejected." } }, "additionalProperties": false }, "maxItems": 1024, "description": "allowlist only; at most 256." }, "cidrs": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 64 }, "maxItems": 256, "description": "allowlist only; public ranges; at most 64." } }, "additionalProperties": false } } } }, "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "project_id", "required": true, "description": "UUIDv7, lowercase canonical form." }, { "schema": { "type": "string", "maxLength": 40 }, "in": "header", "name": "if-match", "required": false } ], "security": [ { "apiKey": [] } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "required": [ "organization_id", "project_id", "version", "policy", "effective", "organization_override", "propagation" ], "properties": { "organization_id": { "type": "string", "format": "uuid", "description": "UUIDv7, lowercase canonical form." }, "project_id": { "type": "string", "format": "uuid", "description": "UUIDv7, lowercase canonical form." }, "version": { "type": "integer", "minimum": 0, "description": "Current version number of the project policy (0 = none); send as If-Match." }, "policy": { "anyOf": [ { "type": "object", "required": [ "id", "scope", "project_id", "workspace_id", "version", "kind", "mode", "rules", "cidrs", "policy_sha256", "created_by", "created_at" ], "properties": { "id": { "type": "string", "format": "uuid", "description": "UUIDv7, lowercase canonical form." }, "scope": { "anyOf": [ { "type": "string", "enum": [ "project" ] }, { "type": "string", "enum": [ "workspace" ] } ] }, "project_id": { "type": "string", "format": "uuid", "description": "UUIDv7, lowercase canonical form." }, "workspace_id": { "anyOf": [ { "type": "string", "format": "uuid", "description": "UUIDv7, lowercase canonical form." }, { "type": "null" } ] }, "version": { "type": "integer", "minimum": 1 }, "kind": { "anyOf": [ { "type": "string", "enum": [ "policy" ] }, { "type": "string", "enum": [ "cleared" ] } ], "description": "cleared: the workspace override was removed (falls back to the project policy)." }, "mode": { "anyOf": [ { "type": "string", "enum": [ "allow_all", "allowlist", "deny_all" ] }, { "type": "null" } ] }, "rules": { "type": "array", "items": { "type": "object", "required": [ "host", "ports", "protocols" ], "properties": { "host": { "type": "string", "description": "Lower-case IDNA A-label FQDN, or `*.` + FQDN (matches exactly one extra label)." }, "ports": { "type": "array", "items": { "type": "integer", "minimum": 1, "maximum": 65535 } }, "protocols": { "type": "array", "items": { "type": "string", "enum": [ "tcp" ] } } }, "additionalProperties": false } }, "cidrs": { "type": "array", "items": { "type": "string" } }, "policy_sha256": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "created_by": { "type": "object", "required": [ "type", "id" ], "properties": { "type": { "anyOf": [ { "type": "string", "enum": [ "user" ] }, { "type": "string", "enum": [ "api_key" ] } ] }, "id": { "type": "string", "format": "uuid", "description": "UUIDv7, lowercase canonical form." } }, "additionalProperties": false }, "created_at": { "type": "string", "format": "date-time", "description": "RFC 3339 UTC timestamp with Z." } }, "additionalProperties": false }, { "type": "null" } ] }, "effective": { "type": "object", "required": [ "source", "policy_version_id", "policy_version", "mode", "rules", "cidrs", "policy_sha256" ], "properties": { "source": { "anyOf": [ { "type": "string", "enum": [ "organization" ] }, { "type": "string", "enum": [ "workspace" ] }, { "type": "string", "enum": [ "project" ] }, { "type": "string", "enum": [ "platform_default" ] } ], "description": "organization: an organization egress override (deny_all, e.g. outbound transfer allowance used up;) wins over every policy until it lifts." }, "policy_version_id": { "anyOf": [ { "type": "string", "format": "uuid", "description": "UUIDv7, lowercase canonical form." }, { "type": "null" } ] }, "policy_version": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "mode": { "type": "string", "enum": [ "allow_all", "allowlist", "deny_all" ] }, "rules": { "type": "array", "items": { "type": "object", "required": [ "host", "ports", "protocols" ], "properties": { "host": { "type": "string", "description": "Lower-case IDNA A-label FQDN, or `*.` + FQDN (matches exactly one extra label)." }, "ports": { "type": "array", "items": { "type": "integer", "minimum": 1, "maximum": 65535 } }, "protocols": { "type": "array", "items": { "type": "string", "enum": [ "tcp" ] } } }, "additionalProperties": false } }, "cidrs": { "type": "array", "items": { "type": "string" } }, "policy_sha256": { "type": "string", "description": "SHA-256 of the canonical policy document; what the host acknowledges." } }, "additionalProperties": false }, "organization_override": { "anyOf": [ { "type": "object", "required": [ "mode", "reason", "set_at", "lifts_at" ], "properties": { "mode": { "type": "string", "enum": [ "deny_all" ] }, "reason": { "type": "string", "enum": [ "transfer_allowance_exhausted" ] }, "set_at": { "type": "string", "format": "date-time", "description": "RFC 3339 UTC timestamp with Z." }, "lifts_at": { "type": "string", "format": "date-time", "description": "RFC 3339 UTC timestamp with Z." } }, "additionalProperties": false, "description": "Active organization egress override; policies stay stored and apply again when it lifts." }, { "type": "null" } ] }, "propagation": { "type": "object", "required": [ "workspaces", "enforced", "pending", "failed", "not_enforced", "truncated" ], "properties": { "workspaces": { "type": "integer", "description": "Live workspaces (not deleted, with a VM or starting) whose effective policy is this project policy." }, "enforced": { "type": "integer" }, "pending": { "type": "integer" }, "failed": { "type": "integer" }, "not_enforced": { "type": "integer", "description": "Not yet acknowledged for the current version and ownership epoch." }, "truncated": { "type": "boolean", "description": "Counted over at most 5000 workspaces." } }, "additionalProperties": false, "description": "Where the cell stands applying the current project policy (from its acknowledgements)." } }, "additionalProperties": false } } } }, "4XX": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "examples": { "not_found": { "$ref": "#/components/examples/not_found" }, "rate_limited": { "$ref": "#/components/examples/rate_limited" }, "validation_failed": { "$ref": "#/components/examples/validation_failed" } } } } }, "5XX": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "examples": { "not_found": { "$ref": "#/components/examples/not_found" }, "rate_limited": { "$ref": "#/components/examples/rate_limited" }, "validation_failed": { "$ref": "#/components/examples/validation_failed" } } } } } } } }, "/v1/projects/{project_id}/egress-policy/versions": { "get": { "operationId": "getV1ProjectsProjectIdEgressPolicyVersions", "summary": "Version history of a project’s egress policy, newest first", "tags": [ "Egress policy" ], "parameters": [ { "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 }, "in": "query", "name": "limit", "required": false }, { "schema": { "type": "string", "maxLength": 200 }, "in": "query", "name": "cursor", "required": false }, { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "project_id", "required": true, "description": "UUIDv7, lowercase canonical form." } ], "security": [ { "apiKey": [] } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "next_cursor" ], "properties": { "data": { "type": "array", "items": { "type": "object", "required": [ "id", "scope", "project_id", "workspace_id", "version", "kind", "mode", "rules", "cidrs", "policy_sha256", "created_by", "created_at" ], "properties": { "id": { "type": "string", "format": "uuid", "description": "UUIDv7, lowercase canonical form." }, "scope": { "anyOf": [ { "type": "string", "enum": [ "project" ] }, { "type": "string", "enum": [ "workspace" ] } ] }, "project_id": { "type": "string", "format": "uuid", "description": "UUIDv7, lowercase canonical form." }, "workspace_id": { "anyOf": [ { "type": "string", "format": "uuid", "description": "UUIDv7, lowercase canonical form." }, { "type": "null" } ] }, "version": { "type": "integer", "minimum": 1 }, "kind": { "anyOf": [ { "type": "string", "enum": [ "policy" ] }, { "type": "string", "enum": [ "cleared" ] } ], "description": "cleared: the workspace override was removed (falls back to the project policy)." }, "mode": { "anyOf": [ { "type": "string", "enum": [ "allow_all", "allowlist", "deny_all" ] }, { "type": "null" } ] }, "rules": { "type": "array", "items": { "type": "object", "required": [ "host", "ports", "protocols" ], "properties": { "host": { "type": "string", "description": "Lower-case IDNA A-label FQDN, or `*.` + FQDN (matches exactly one extra label)." }, "ports": { "type": "array", "items": { "type": "integer", "minimum": 1, "maximum": 65535 } }, "protocols": { "type": "array", "items": { "type": "string", "enum": [ "tcp" ] } } }, "additionalProperties": false } }, "cidrs": { "type": "array", "items": { "type": "string" } }, "policy_sha256": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "created_by": { "type": "object", "required": [ "type", "id" ], "properties": { "type": { "anyOf": [ { "type": "string", "enum": [ "user" ] }, { "type": "string", "enum": [ "api_key" ] } ] }, "id": { "type": "string", "format": "uuid", "description": "UUIDv7, lowercase canonical form." } }, "additionalProperties": false }, "created_at": { "type": "string", "format": "date-time", "description": "RFC 3339 UTC timestamp with Z." } }, "additionalProperties": false } }, "next_cursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "additionalProperties": false } } } }, "4XX": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "examples": { "not_found": { "$ref": "#/components/examples/not_found" }, "rate_limited": { "$ref": "#/components/examples/rate_limited" }, "validation_failed": { "$ref": "#/components/examples/validation_failed" } } } } }, "5XX": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "examples": { "not_found": { "$ref": "#/components/examples/not_found" }, "rate_limited": { "$ref": "#/components/examples/rate_limited" }, "validation_failed": { "$ref": "#/components/examples/validation_failed" } } } } } } } }, "/v1/workspaces/{workspace_id}/egress-policy": { "get": { "operationId": "getV1WorkspacesWorkspaceIdEgressPolicy", "summary": "Effective egress policy of a workspace and its enforcement state", "tags": [ "Egress policy" ], "description": "effective = workspace override > project policy > platform default (allow_all). enforcement.state is not_enforced until the cell/host acknowledges the current effective policy for the workspace’s current ownership epoch, then pending | enforced | failed. `version` (ETag) is the override history version for If-Match. template_egress: the template version’s egress ceiling (, null = none); effective_policy: what the host enforces, effective intersected with that ceiling.", "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "workspace_id", "required": true, "description": "UUIDv7, lowercase canonical form." } ], "security": [ { "apiKey": [] } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "required": [ "organization_id", "project_id", "workspace_id", "version", "override", "project_policy", "effective", "organization_override", "enforcement", "template_egress", "effective_policy" ], "properties": { "organization_id": { "type": "string", "format": "uuid", "description": "UUIDv7, lowercase canonical form." }, "project_id": { "type": "string", "format": "uuid", "description": "UUIDv7, lowercase canonical form." }, "workspace_id": { "type": "string", "format": "uuid", "description": "UUIDv7, lowercase canonical form." }, "version": { "type": "integer", "minimum": 0, "description": "Current version number of the workspace override history (0 = none); send as If-Match." }, "override": { "anyOf": [ { "type": "object", "required": [ "id", "scope", "project_id", "workspace_id", "version", "kind", "mode", "rules", "cidrs", "policy_sha256", "created_by", "created_at" ], "properties": { "id": { "type": "string", "format": "uuid", "description": "UUIDv7, lowercase canonical form." }, "scope": { "anyOf": [ { "type": "string", "enum": [ "project" ] }, { "type": "string", "enum": [ "workspace" ] } ] }, "project_id": { "type": "string", "format": "uuid", "description": "UUIDv7, lowercase canonical form." }, "workspace_id": { "anyOf": [ { "type": "string", "format": "uuid", "description": "UUIDv7, lowercase canonical form." }, { "type": "null" } ] }, "version": { "type": "integer", "minimum": 1 }, "kind": { "anyOf": [ { "type": "string", "enum": [ "policy" ] }, { "type": "string", "enum": [ "cleared" ] } ], "description": "cleared: the workspace override was removed (falls back to the project policy)." }, "mode": { "anyOf": [ { "type": "string", "enum": [ "allow_all", "allowlist", "deny_all" ] }, { "type": "null" } ] }, "rules": { "type": "array", "items": { "type": "object", "required": [ "host", "ports", "protocols" ], "properties": { "host": { "type": "string", "description": "Lower-case IDNA A-label FQDN, or `*.` + FQDN (matches exactly one extra label)." }, "ports": { "type": "array", "items": { "type": "integer", "minimum": 1, "maximum": 65535 } }, "protocols": { "type": "array", "items": { "type": "string", "enum": [ "tcp" ] } } }, "additionalProperties": false } }, "cidrs": { "type": "array", "items": { "type": "string" } }, "policy_sha256": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "created_by": { "type": "object", "required": [ "type", "id" ], "properties": { "type": { "anyOf": [ { "type": "string", "enum": [ "user" ] }, { "type": "string", "enum": [ "api_key" ] } ] }, "id": { "type": "string", "format": "uuid", "description": "UUIDv7, lowercase canonical form." } }, "additionalProperties": false }, "created_at": { "type": "string", "format": "date-time", "description": "RFC 3339 UTC timestamp with Z." } }, "additionalProperties": false }, { "type": "null" } ] }, "project_policy": { "anyOf": [ { "type": "object", "required": [ "id", "scope", "project_id", "workspace_id", "version", "kind", "mode", "rules", "cidrs", "policy_sha256", "created_by", "created_at" ], "properties": { "id": { "type": "string", "format": "uuid", "description": "UUIDv7, lowercase canonical form." }, "scope": { "anyOf": [ { "type": "string", "enum": [ "project" ] }, { "type": "string", "enum": [ "workspace" ] } ] }, "project_id": { "type": "string", "format": "uuid", "description": "UUIDv7, lowercase canonical form." }, "workspace_id": { "anyOf": [ { "type": "string", "format": "uuid", "description": "UUIDv7, lowercase canonical form." }, { "type": "null" } ] }, "version": { "type": "integer", "minimum": 1 }, "kind": { "anyOf": [ { "type": "string", "enum": [ "policy" ] }, { "type": "string", "enum": [ "cleared" ] } ], "description": "cleared: the workspace override was removed (falls back to the project policy)." }, "mode": { "anyOf": [ { "type": "string", "enum": [ "allow_all", "allowlist", "deny_all" ] }, { "type": "null" } ] }, "rules": { "type": "array", "items": { "type": "object", "required": [ "host", "ports", "protocols" ], "properties": { "host": { "type": "string", "description": "Lower-case IDNA A-label FQDN, or `*.` + FQDN (matches exactly one extra label)." }, "ports": { "type": "array", "items": { "type": "integer", "minimum": 1, "maximum": 65535 } }, "protocols": { "type": "array", "items": { "type": "string", "enum": [ "tcp" ] } } }, "additionalProperties": false } }, "cidrs": { "type": "array", "items": { "type": "string" } }, "policy_sha256": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "created_by": { "type": "object", "required": [ "type", "id" ], "properties": { "type": { "anyOf": [ { "type": "string", "enum": [ "user" ] }, { "type": "string", "enum": [ "api_key" ] } ] }, "id": { "type": "string", "format": "uuid", "description": "UUIDv7, lowercase canonical form." } }, "additionalProperties": false }, "created_at": { "type": "string", "format": "date-time", "description": "RFC 3339 UTC timestamp with Z." } }, "additionalProperties": false }, { "type": "null" } ] }, "effective": { "type": "object", "required": [ "source", "policy_version_id", "policy_version", "mode", "rules", "cidrs", "policy_sha256" ], "properties": { "source": { "anyOf": [ { "type": "string", "enum": [ "organization" ] }, { "type": "string", "enum": [ "workspace" ] }, { "type": "string", "enum": [ "project" ] }, { "type": "string", "enum": [ "platform_default" ] } ], "description": "organization: an organization egress override (deny_all, e.g. outbound transfer allowance used up;) wins over every policy until it lifts." }, "policy_version_id": { "anyOf": [ { "type": "string", "format": "uuid", "description": "UUIDv7, lowercase canonical form." }, { "type": "null" } ] }, "policy_version": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "mode": { "type": "string", "enum": [ "allow_all", "allowlist", "deny_all" ] }, "rules": { "type": "array", "items": { "type": "object", "required": [ "host", "ports", "protocols" ], "properties": { "host": { "type": "string", "description": "Lower-case IDNA A-label FQDN, or `*.` + FQDN (matches exactly one extra label)." }, "ports": { "type": "array", "items": { "type": "integer", "minimum": 1, "maximum": 65535 } }, "protocols": { "type": "array", "items": { "type": "string", "enum": [ "tcp" ] } } }, "additionalProperties": false } }, "cidrs": { "type": "array", "items": { "type": "string" } }, "policy_sha256": { "type": "string", "description": "SHA-256 of the canonical policy document; what the host acknowledges." } }, "additionalProperties": false }, "organization_override": { "anyOf": [ { "type": "object", "required": [ "mode", "reason", "set_at", "lifts_at" ], "properties": { "mode": { "type": "string", "enum": [ "deny_all" ] }, "reason": { "type": "string", "enum": [ "transfer_allowance_exhausted" ] }, "set_at": { "type": "string", "format": "date-time", "description": "RFC 3339 UTC timestamp with Z." }, "lifts_at": { "type": "string", "format": "date-time", "description": "RFC 3339 UTC timestamp with Z." } }, "additionalProperties": false, "description": "Active organization egress override; policies stay stored and apply again when it lifts." }, { "type": "null" } ] }, "enforcement": { "type": "object", "required": [ "state", "reason", "applied_version", "effective_version", "acknowledged" ], "properties": { "state": { "anyOf": [ { "type": "string", "enum": [ "not_enforced" ] }, { "type": "string", "enum": [ "pending" ] }, { "type": "string", "enum": [ "enforced" ] }, { "type": "string", "enum": [ "failed" ] } ], "description": "not_enforced until the cell/host acknowledges the current effective policy for the current ownership epoch." }, "reason": { "anyOf": [ { "anyOf": [ { "type": "string", "enum": [ "not_acknowledged" ] }, { "type": "string", "enum": [ "other_version_acknowledged" ] }, { "type": "string", "enum": [ "stale_epoch" ] } ], "description": "Why the state is not_enforced (null otherwise)." }, { "type": "null" } ] }, "applied_version": { "anyOf": [ { "type": "integer", "description": "Version number of the policy the cell/host last acknowledged for this workspace (null: none, or the platform default)." }, { "type": "null" } ] }, "effective_version": { "anyOf": [ { "type": "integer", "description": "Version number of the current effective policy (null: platform default)." }, { "type": "null" } ] }, "acknowledged": { "anyOf": [ { "type": "object", "required": [ "policy_version_id", "policy_version", "policy_sha256", "ownership_epoch", "state", "host_id", "error_code", "result", "acknowledged_at", "applied_at", "updated_at" ], "properties": { "policy_version_id": { "anyOf": [ { "type": "string", "format": "uuid", "description": "UUIDv7, lowercase canonical form." }, { "type": "null" } ] }, "policy_version": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "policy_sha256": { "type": "string" }, "ownership_epoch": { "type": "integer" }, "state": { "anyOf": [ { "type": "string", "enum": [ "pending" ] }, { "type": "string", "enum": [ "enforced" ] }, { "type": "string", "enum": [ "failed" ] } ] }, "host_id": { "anyOf": [ { "type": "string", "format": "uuid", "description": "UUIDv7, lowercase canonical form." }, { "type": "null" } ] }, "error_code": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "result": { "type": "object", "properties": {}, "additionalProperties": true, "description": "Host enforcement result as reported by the cell." }, "acknowledged_at": { "type": "string", "format": "date-time", "description": "RFC 3339 UTC timestamp with Z." }, "applied_at": { "anyOf": [ { "type": "string", "format": "date-time", "description": "RFC 3339 UTC timestamp with Z." }, { "type": "null" } ] }, "updated_at": { "type": "string", "format": "date-time", "description": "RFC 3339 UTC timestamp with Z." } }, "additionalProperties": false }, { "type": "null" } ] } }, "additionalProperties": false }, "template_egress": { "anyOf": [ { "$ref": "#/components/schemas/TemplateEgressDefault" }, { "type": "null" } ] }, "effective_policy": { "type": "object", "required": [ "mode", "rules", "cidrs" ], "properties": { "mode": { "anyOf": [ { "type": "string", "enum": [ "allow_all" ] }, { "type": "string", "enum": [ "allowlist" ] }, { "type": "string", "enum": [ "deny_all" ] } ] }, "rules": { "type": "array", "items": { "type": "object", "required": [ "host", "ports", "protocols" ], "properties": { "host": { "type": "string" }, "ports": { "type": "array", "items": { "type": "integer", "minimum": 1, "maximum": 65535 }, "description": "[] = any port (a ceiling host)." }, "protocols": { "type": "array", "items": { "type": "string", "enum": [ "tcp" ] } } }, "additionalProperties": false } }, "cidrs": { "type": "array", "items": { "type": "string" } } }, "additionalProperties": false, "description": "What the host enforces: the effective policy intersected with the template egress ceiling (equal to `effective` without a ceiling)." } }, "additionalProperties": false } } } }, "4XX": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "examples": { "not_found": { "$ref": "#/components/examples/not_found" }, "rate_limited": { "$ref": "#/components/examples/rate_limited" }, "validation_failed": { "$ref": "#/components/examples/validation_failed" } } } } }, "5XX": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "examples": { "not_found": { "$ref": "#/components/examples/not_found" }, "rate_limited": { "$ref": "#/components/examples/rate_limited" }, "validation_failed": { "$ref": "#/components/examples/validation_failed" } } } } } } }, "put": { "operationId": "putV1WorkspacesWorkspaceIdEgressPolicy", "summary": "Set a workspace override of the egress policy (new immutable version)", "tags": [ "Egress policy" ], "description": "Same body and validation as the project policy. Optional If-Match. 409 conflict (details.reason workspace_deleted) for deleted workspaces. 422 egress_widening (details {template_egress, outside: [hosts] | [\"cidrs\"] | [\"allow_all\"]}) when the workspace’s template egress ceiling would narrow the policy.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "mode" ], "properties": { "mode": { "type": "string", "enum": [ "allow_all", "allowlist", "deny_all" ] }, "rules": { "type": "array", "items": { "type": "object", "required": [ "host" ], "properties": { "host": { "type": "string", "minLength": 1, "maxLength": 300 }, "ports": { "type": "array", "items": { "type": "integer" }, "maxItems": 64, "description": "Default [443]." }, "protocols": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 16 }, "maxItems": 4, "description": "Only \"tcp\" (default); udp/quic are rejected." } }, "additionalProperties": false }, "maxItems": 1024, "description": "allowlist only; at most 256." }, "cidrs": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 64 }, "maxItems": 256, "description": "allowlist only; public ranges; at most 64." } }, "additionalProperties": false } } } }, "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "workspace_id", "required": true, "description": "UUIDv7, lowercase canonical form." }, { "schema": { "type": "string", "maxLength": 40 }, "in": "header", "name": "if-match", "required": false } ], "security": [ { "apiKey": [] } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "required": [ "organization_id", "project_id", "workspace_id", "version", "override", "project_policy", "effective", "organization_override", "enforcement", "template_egress", "effective_policy" ], "properties": { "organization_id": { "type": "string", "format": "uuid", "description": "UUIDv7, lowercase canonical form." }, "project_id": { "type": "string", "format": "uuid", "description": "UUIDv7, lowercase canonical form." }, "workspace_id": { "type": "string", "format": "uuid", "description": "UUIDv7, lowercase canonical form." }, "version": { "type": "integer", "minimum": 0, "description": "Current version number of the workspace override history (0 = none); send as If-Match." }, "override": { "anyOf": [ { "type": "object", "required": [ "id", "scope", "project_id", "workspace_id", "version", "kind", "mode", "rules", "cidrs", "policy_sha256", "created_by", "created_at" ], "properties": { "id": { "type": "string", "format": "uuid", "description": "UUIDv7, lowercase canonical form." }, "scope": { "anyOf": [ { "type": "string", "enum": [ "project" ] }, { "type": "string", "enum": [ "workspace" ] } ] }, "project_id": { "type": "string", "format": "uuid", "description": "UUIDv7, lowercase canonical form." }, "workspace_id": { "anyOf": [ { "type": "string", "format": "uuid", "description": "UUIDv7, lowercase canonical form." }, { "type": "null" } ] }, "version": { "type": "integer", "minimum": 1 }, "kind": { "anyOf": [ { "type": "string", "enum": [ "policy" ] }, { "type": "string", "enum": [ "cleared" ] } ], "description": "cleared: the workspace override was removed (falls back to the project policy)." }, "mode": { "anyOf": [ { "type": "string", "enum": [ "allow_all", "allowlist", "deny_all" ] }, { "type": "null" } ] }, "rules": { "type": "array", "items": { "type": "object", "required": [ "host", "ports", "protocols" ], "properties": { "host": { "type": "string", "description": "Lower-case IDNA A-label FQDN, or `*.` + FQDN (matches exactly one extra label)." }, "ports": { "type": "array", "items": { "type": "integer", "minimum": 1, "maximum": 65535 } }, "protocols": { "type": "array", "items": { "type": "string", "enum": [ "tcp" ] } } }, "additionalProperties": false } }, "cidrs": { "type": "array", "items": { "type": "string" } }, "policy_sha256": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "created_by": { "type": "object", "required": [ "type", "id" ], "properties": { "type": { "anyOf": [ { "type": "string", "enum": [ "user" ] }, { "type": "string", "enum": [ "api_key" ] } ] }, "id": { "type": "string", "format": "uuid", "description": "UUIDv7, lowercase canonical form." } }, "additionalProperties": false }, "created_at": { "type": "string", "format": "date-time", "description": "RFC 3339 UTC timestamp with Z." } }, "additionalProperties": false }, { "type": "null" } ] }, "project_policy": { "anyOf": [ { "type": "object", "required": [ "id", "scope", "project_id", "workspace_id", "version", "kind", "mode", "rules", "cidrs", "policy_sha256", "created_by", "created_at" ], "properties": { "id": { "type": "string", "format": "uuid", "description": "UUIDv7, lowercase canonical form." }, "scope": { "anyOf": [ { "type": "string", "enum": [ "project" ] }, { "type": "string", "enum": [ "workspace" ] } ] }, "project_id": { "type": "string", "format": "uuid", "description": "UUIDv7, lowercase canonical form." }, "workspace_id": { "anyOf": [ { "type": "string", "format": "uuid", "description": "UUIDv7, lowercase canonical form." }, { "type": "null" } ] }, "version": { "type": "integer", "minimum": 1 }, "kind": { "anyOf": [ { "type": "string", "enum": [ "policy" ] }, { "type": "string", "enum": [ "cleared" ] } ], "description": "cleared: the workspace override was removed (falls back to the project policy)." }, "mode": { "anyOf": [ { "type": "string", "enum": [ "allow_all", "allowlist", "deny_all" ] }, { "type": "null" } ] }, "rules": { "type": "array", "items": { "type": "object", "required": [ "host", "ports", "protocols" ], "properties": { "host": { "type": "string", "description": "Lower-case IDNA A-label FQDN, or `*.` + FQDN (matches exactly one extra label)." }, "ports": { "type": "array", "items": { "type": "integer", "minimum": 1, "maximum": 65535 } }, "protocols": { "type": "array", "items": { "type": "string", "enum": [ "tcp" ] } } }, "additionalProperties": false } }, "cidrs": { "type": "array", "items": { "type": "string" } }, "policy_sha256": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "created_by": { "type": "object", "required": [ "type", "id" ], "properties": { "type": { "anyOf": [ { "type": "string", "enum": [ "user" ] }, { "type": "string", "enum": [ "api_key" ] } ] }, "id": { "type": "string", "format": "uuid", "description": "UUIDv7, lowercase canonical form." } }, "additionalProperties": false }, "created_at": { "type": "string", "format": "date-time", "description": "RFC 3339 UTC timestamp with Z." } }, "additionalProperties": false }, { "type": "null" } ] }, "effective": { "type": "object", "required": [ "source", "policy_version_id", "policy_version", "mode", "rules", "cidrs", "policy_sha256" ], "properties": { "source": { "anyOf": [ { "type": "string", "enum": [ "organization" ] }, { "type": "string", "enum": [ "workspace" ] }, { "type": "string", "enum": [ "project" ] }, { "type": "string", "enum": [ "platform_default" ] } ], "description": "organization: an organization egress override (deny_all, e.g. outbound transfer allowance used up;) wins over every policy until it lifts." }, "policy_version_id": { "anyOf": [ { "type": "string", "format": "uuid", "description": "UUIDv7, lowercase canonical form." }, { "type": "null" } ] }, "policy_version": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "mode": { "type": "string", "enum": [ "allow_all", "allowlist", "deny_all" ] }, "rules": { "type": "array", "items": { "type": "object", "required": [ "host", "ports", "protocols" ], "properties": { "host": { "type": "string", "description": "Lower-case IDNA A-label FQDN, or `*.` + FQDN (matches exactly one extra label)." }, "ports": { "type": "array", "items": { "type": "integer", "minimum": 1, "maximum": 65535 } }, "protocols": { "type": "array", "items": { "type": "string", "enum": [ "tcp" ] } } }, "additionalProperties": false } }, "cidrs": { "type": "array", "items": { "type": "string" } }, "policy_sha256": { "type": "string", "description": "SHA-256 of the canonical policy document; what the host acknowledges." } }, "additionalProperties": false }, "organization_override": { "anyOf": [ { "type": "object", "required": [ "mode", "reason", "set_at", "lifts_at" ], "properties": { "mode": { "type": "string", "enum": [ "deny_all" ] }, "reason": { "type": "string", "enum": [ "transfer_allowance_exhausted" ] }, "set_at": { "type": "string", "format": "date-time", "description": "RFC 3339 UTC timestamp with Z." }, "lifts_at": { "type": "string", "format": "date-time", "description": "RFC 3339 UTC timestamp with Z." } }, "additionalProperties": false, "description": "Active organization egress override; policies stay stored and apply again when it lifts." }, { "type": "null" } ] }, "enforcement": { "type": "object", "required": [ "state", "reason", "applied_version", "effective_version", "acknowledged" ], "properties": { "state": { "anyOf": [ { "type": "string", "enum": [ "not_enforced" ] }, { "type": "string", "enum": [ "pending" ] }, { "type": "string", "enum": [ "enforced" ] }, { "type": "string", "enum": [ "failed" ] } ], "description": "not_enforced until the cell/host acknowledges the current effective policy for the current ownership epoch." }, "reason": { "anyOf": [ { "anyOf": [ { "type": "string", "enum": [ "not_acknowledged" ] }, { "type": "string", "enum": [ "other_version_acknowledged" ] }, { "type": "string", "enum": [ "stale_epoch" ] } ], "description": "Why the state is not_enforced (null otherwise)." }, { "type": "null" } ] }, "applied_version": { "anyOf": [ { "type": "integer", "description": "Version number of the policy the cell/host last acknowledged for this workspace (null: none, or the platform default)." }, { "type": "null" } ] }, "effective_version": { "anyOf": [ { "type": "integer", "description": "Version number of the current effective policy (null: platform default)." }, { "type": "null" } ] }, "acknowledged": { "anyOf": [ { "type": "object", "required": [ "policy_version_id", "policy_version", "policy_sha256", "ownership_epoch", "state", "host_id", "error_code", "result", "acknowledged_at", "applied_at", "updated_at" ], "properties": { "policy_version_id": { "anyOf": [ { "type": "string", "format": "uuid", "description": "UUIDv7, lowercase canonical form." }, { "type": "null" } ] }, "policy_version": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "policy_sha256": { "type": "string" }, "ownership_epoch": { "type": "integer" }, "state": { "anyOf": [ { "type": "string", "enum": [ "pending" ] }, { "type": "string", "enum": [ "enforced" ] }, { "type": "string", "enum": [ "failed" ] } ] }, "host_id": { "anyOf": [ { "type": "string", "format": "uuid", "description": "UUIDv7, lowercase canonical form." }, { "type": "null" } ] }, "error_code": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "result": { "type": "object", "properties": {}, "additionalProperties": true, "description": "Host enforcement result as reported by the cell." }, "acknowledged_at": { "type": "string", "format": "date-time", "description": "RFC 3339 UTC timestamp with Z." }, "applied_at": { "anyOf": [ { "type": "string", "format": "date-time", "description": "RFC 3339 UTC timestamp with Z." }, { "type": "null" } ] }, "updated_at": { "type": "string", "format": "date-time", "description": "RFC 3339 UTC timestamp with Z." } }, "additionalProperties": false }, { "type": "null" } ] } }, "additionalProperties": false }, "template_egress": { "anyOf": [ { "$ref": "#/components/schemas/TemplateEgressDefault" }, { "type": "null" } ] }, "effective_policy": { "type": "object", "required": [ "mode", "rules", "cidrs" ], "properties": { "mode": { "anyOf": [ { "type": "string", "enum": [ "allow_all" ] }, { "type": "string", "enum": [ "allowlist" ] }, { "type": "string", "enum": [ "deny_all" ] } ] }, "rules": { "type": "array", "items": { "type": "object", "required": [ "host", "ports", "protocols" ], "properties": { "host": { "type": "string" }, "ports": { "type": "array", "items": { "type": "integer", "minimum": 1, "maximum": 65535 }, "description": "[] = any port (a ceiling host)." }, "protocols": { "type": "array", "items": { "type": "string", "enum": [ "tcp" ] } } }, "additionalProperties": false } }, "cidrs": { "type": "array", "items": { "type": "string" } } }, "additionalProperties": false, "description": "What the host enforces: the effective policy intersected with the template egress ceiling (equal to `effective` without a ceiling)." } }, "additionalProperties": false } } } }, "4XX": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "examples": { "not_found": { "$ref": "#/components/examples/not_found" }, "rate_limited": { "$ref": "#/components/examples/rate_limited" }, "validation_failed": { "$ref": "#/components/examples/validation_failed" } } } } }, "5XX": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "examples": { "not_found": { "$ref": "#/components/examples/not_found" }, "rate_limited": { "$ref": "#/components/examples/rate_limited" }, "validation_failed": { "$ref": "#/components/examples/validation_failed" } } } } } } }, "delete": { "operationId": "deleteV1WorkspacesWorkspaceIdEgressPolicy", "summary": "Remove the workspace override (fall back to the project policy)", "tags": [ "Egress policy" ], "description": "Records a `cleared` version. 204 without a new version when there is no active override. Optional If-Match.", "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "workspace_id", "required": true, "description": "UUIDv7, lowercase canonical form." }, { "schema": { "type": "string", "maxLength": 40 }, "in": "header", "name": "if-match", "required": false } ], "security": [ { "apiKey": [] } ], "responses": { "204": { "description": "No content." }, "4XX": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "examples": { "not_found": { "$ref": "#/components/examples/not_found" }, "rate_limited": { "$ref": "#/components/examples/rate_limited" }, "validation_failed": { "$ref": "#/components/examples/validation_failed" } } } } }, "5XX": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "examples": { "not_found": { "$ref": "#/components/examples/not_found" }, "rate_limited": { "$ref": "#/components/examples/rate_limited" }, "validation_failed": { "$ref": "#/components/examples/validation_failed" } } } } } } } }, "/v1/workspaces/{workspace_id}/egress-policy/versions": { "get": { "operationId": "getV1WorkspacesWorkspaceIdEgressPolicyVersions", "summary": "Version history of a workspace’s egress override (including cleared versions), newest first", "tags": [ "Egress policy" ], "parameters": [ { "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 }, "in": "query", "name": "limit", "required": false }, { "schema": { "type": "string", "maxLength": 200 }, "in": "query", "name": "cursor", "required": false }, { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "workspace_id", "required": true, "description": "UUIDv7, lowercase canonical form." } ], "security": [ { "apiKey": [] } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "next_cursor" ], "properties": { "data": { "type": "array", "items": { "type": "object", "required": [ "id", "scope", "project_id", "workspace_id", "version", "kind", "mode", "rules", "cidrs", "policy_sha256", "created_by", "created_at" ], "properties": { "id": { "type": "string", "format": "uuid", "description": "UUIDv7, lowercase canonical form." }, "scope": { "anyOf": [ { "type": "string", "enum": [ "project" ] }, { "type": "string", "enum": [ "workspace" ] } ] }, "project_id": { "type": "string", "format": "uuid", "description": "UUIDv7, lowercase canonical form." }, "workspace_id": { "anyOf": [ { "type": "string", "format": "uuid", "description": "UUIDv7, lowercase canonical form." }, { "type": "null" } ] }, "version": { "type": "integer", "minimum": 1 }, "kind": { "anyOf": [ { "type": "string", "enum": [ "policy" ] }, { "type": "string", "enum": [ "cleared" ] } ], "description": "cleared: the workspace override was removed (falls back to the project policy)." }, "mode": { "anyOf": [ { "type": "string", "enum": [ "allow_all", "allowlist", "deny_all" ] }, { "type": "null" } ] }, "rules": { "type": "array", "items": { "type": "object", "required": [ "host", "ports", "protocols" ], "properties": { "host": { "type": "string", "description": "Lower-case IDNA A-label FQDN, or `*.` + FQDN (matches exactly one extra label)." }, "ports": { "type": "array", "items": { "type": "integer", "minimum": 1, "maximum": 65535 } }, "protocols": { "type": "array", "items": { "type": "string", "enum": [ "tcp" ] } } }, "additionalProperties": false } }, "cidrs": { "type": "array", "items": { "type": "string" } }, "policy_sha256": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "created_by": { "type": "object", "required": [ "type", "id" ], "properties": { "type": { "anyOf": [ { "type": "string", "enum": [ "user" ] }, { "type": "string", "enum": [ "api_key" ] } ] }, "id": { "type": "string", "format": "uuid", "description": "UUIDv7, lowercase canonical form." } }, "additionalProperties": false }, "created_at": { "type": "string", "format": "date-time", "description": "RFC 3339 UTC timestamp with Z." } }, "additionalProperties": false } }, "next_cursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "additionalProperties": false } } } }, "4XX": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "examples": { "not_found": { "$ref": "#/components/examples/not_found" }, "rate_limited": { "$ref": "#/components/examples/rate_limited" }, "validation_failed": { "$ref": "#/components/examples/validation_failed" } } } } }, "5XX": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "examples": { "not_found": { "$ref": "#/components/examples/not_found" }, "rate_limited": { "$ref": "#/components/examples/rate_limited" }, "validation_failed": { "$ref": "#/components/examples/validation_failed" } } } } } } } }, "/v1/organizations/{organization_id}/usage/summary": { "get": { "operationId": "getV1OrganizationsOrganizationIdUsageSummary", "summary": "Current-period usage, included allowances and cap state of an organization", "tags": [ "Usage and spend" ], "description": "Totals come from the usage ledger (hourly, finalized after the lateness window); `measurement.measured_through` says how far usage is complete. Billable units are whole units (floor per workspace-hour); allowance usage counts billable units. `allowance_exhausted` true means new opens/resumes answer 402 `allowance_exhausted` with `exhausted_reason` as details.reason. `spend_cap` is opt-in overage this period: while it is on, a CPU-hours or RAM GiB-hours allowance past `included` is in cap state `overage` (starts admitted, usage past it charged) until the spend cap is reached.", "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "organization_id", "required": true, "description": "UUIDv7, lowercase canonical form." } ], "security": [ { "apiKey": [] } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "required": [ "organization_id", "plan", "period", "measurement", "allowance_exhausted", "exhausted", "exhausted_reason", "egress_override", "allowances", "meters", "alert_thresholds", "spend_cap", "template_storage" ], "properties": { "organization_id": { "type": "string", "format": "uuid", "description": "UUIDv7, lowercase canonical form." }, "plan": { "anyOf": [ { "type": "object", "required": [ "plan_key", "catalog_version", "priority", "overage" ], "properties": { "plan_key": { "type": "string" }, "catalog_version": { "type": "string" }, "priority": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "overage": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "additionalProperties": false }, { "type": "null" } ] }, "period": { "type": "object", "required": [ "start", "end", "resets_at", "source", "counted_from" ], "properties": { "start": { "type": "string", "format": "date-time", "description": "RFC 3339 UTC timestamp with Z." }, "end": { "type": "string", "format": "date-time", "description": "RFC 3339 UTC timestamp with Z." }, "resets_at": { "type": "string", "format": "date-time", "description": "RFC 3339 UTC timestamp with Z." }, "source": { "anyOf": [ { "type": "string", "enum": [ "subscription" ] }, { "type": "string", "enum": [ "calendar_month" ] } ], "description": "The entitling subscription period, else the calendar month (UTC)." }, "counted_from": { "type": "string", "format": "date-time", "description": "First hour whose usage counts in this period (RFC 3339 UTC). Usage is metered per UTC hour, and each hour belongs to the period that contains its start (the hour's ledger rows keep the plan in force at that instant and are sent to Stripe with that timestamp). When the period starts inside an hour (after a plan change, or a subscription created mid-hour), that hour's usage counts toward the previous period, so counted_from is `start` rounded up to the next full hour; on a full hour it equals `start`. Before counted_from passes, the period has no counted usage (`estimate_status` no_data) even while workspaces run: their usage is in the usage series under the hour containing `start`." } }, "additionalProperties": false }, "measurement": { "type": "object", "required": [ "measured_through", "finalized_through", "estimate_status", "running_workspaces", "unmeasured_running_workspaces", "live_volumes", "unmeasured_live_volumes", "measurement_gaps", "source_status", "last_rollup_at" ], "properties": { "measured_through": { "anyOf": [ { "type": "string", "format": "date-time", "description": "RFC 3339 UTC timestamp with Z." }, { "type": "null" } ] }, "finalized_through": { "anyOf": [ { "type": "string", "format": "date-time", "description": "RFC 3339 UTC timestamp with Z." }, { "type": "null" } ] }, "estimate_status": { "anyOf": [ { "type": "string", "enum": [ "no_data" ] }, { "type": "string", "enum": [ "provisional" ] }, { "type": "string", "enum": [ "final" ] }, { "type": "string", "enum": [ "incomplete" ] } ], "description": "provisional: includes hours not yet finalized (lateness window); incomplete: measurement gaps in the period (never zero-filled); final: every hour of the range is finalized." }, "running_workspaces": { "type": "integer" }, "unmeasured_running_workspaces": { "type": "integer", "description": "Running workspaces without any usage record yet." }, "live_volumes": { "type": "integer", "description": "Shared volumes in state available (storage accrues); their last measurement bounds measured_through." }, "unmeasured_live_volumes": { "type": "integer", "description": "Live shared volumes without any storage measurement yet." }, "measurement_gaps": { "type": "object", "required": [ "count", "seconds", "last_at" ], "properties": { "count": { "type": "integer" }, "seconds": { "type": "number" }, "last_at": { "anyOf": [ { "type": "string", "format": "date-time", "description": "RFC 3339 UTC timestamp with Z." }, { "type": "null" } ] } }, "additionalProperties": false, "description": "Unmeasured intervals (workspace usage records and shared-volume storage measurements): never zero-filled, never billed." }, "source_status": { "type": "string", "description": "Usage source (cell ingestion) status: available | unavailable | incompatible | unknown." }, "last_rollup_at": { "anyOf": [ { "type": "string", "format": "date-time", "description": "RFC 3339 UTC timestamp with Z." }, { "type": "null" } ] } }, "additionalProperties": false, "description": "Measurement freshness: estimates are complete up to measured_through." }, "allowance_exhausted": { "type": "boolean" }, "exhausted": { "type": "array", "items": { "type": "object", "required": [ "allowance", "meter", "used", "included", "unit" ], "properties": { "allowance": { "type": "string" }, "meter": { "type": "string", "enum": [ "cpu_seconds", "memory_gib_seconds", "storage_gib_seconds", "egress_bytes", "ingress_bytes", "volume_storage_gib_seconds" ] }, "used": { "type": "number" }, "included": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "unit": { "type": "string" } }, "additionalProperties": false } }, "exhausted_reason": { "anyOf": [ { "anyOf": [ { "type": "string", "enum": [ "allowance_used" ] }, { "type": "string", "enum": [ "overage_paused" ] }, { "type": "string", "enum": [ "spend_cap_reached" ] } ], "description": "Why new starts are refused (the details.reason of 402 allowance_exhausted). allowance_used: a hard-cap allowance is used up and overage is off or not available on the plan. overage_paused: overage is on but paused while a plan invoice is past due. spend_cap_reached: overage reached the spend cap for this period." }, { "type": "null" } ] }, "egress_override": { "anyOf": [ { "type": "object", "required": [ "mode", "reason", "allowance", "set_at", "lifts_at" ], "properties": { "mode": { "type": "string", "enum": [ "deny_all" ] }, "reason": { "type": "string", "enum": [ "transfer_allowance_exhausted" ] }, "allowance": { "type": "string" }, "set_at": { "type": "string", "format": "date-time", "description": "RFC 3339 UTC timestamp with Z." }, "lifts_at": { "type": "string", "format": "date-time", "description": "RFC 3339 UTC timestamp with Z." } }, "additionalProperties": false, "description": "Active organization egress override: outbound internet traffic of every workspace is blocked until an upgrade/purchase raises the allowance or the period ends (lifts_at)." }, { "type": "null" } ] }, "allowances": { "type": "array", "items": { "type": "object", "required": [ "key", "display_name", "unit", "meters", "enforcement", "included", "used", "remaining", "percent_used", "included_meter_units", "used_meter_units", "remaining_meter_units", "cap_state" ], "properties": { "key": { "type": "string" }, "display_name": { "type": "string" }, "unit": { "type": "string" }, "meters": { "type": "array", "items": { "type": "string", "enum": [ "cpu_seconds", "memory_gib_seconds", "storage_gib_seconds", "egress_bytes", "ingress_bytes", "volume_storage_gib_seconds" ] } }, "enforcement": { "anyOf": [ { "type": "string", "enum": [ "hard_cap" ] }, { "type": "string", "enum": [ "spare_capacity" ] }, { "type": "string", "enum": [ "reported" ] }, { "type": "string", "enum": [ "egress_block" ] } ], "description": "hard_cap: exhausting it refuses opens/resumes (402 allowance_exhausted) and running workspaces are suspended; spare_capacity: no allowance cap (runs on reclaimable spare capacity); reported: shown and notified, never enforced by refusing access; egress_block (outbound_transfer_gb): at 100% outbound internet traffic is blocked by an organization egress override until upgrade, purchase or the next period (workspaces keep running, starts are not refused)." }, "included": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "used": { "type": "number" }, "remaining": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "percent_used": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "included_meter_units": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "used_meter_units": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "remaining_meter_units": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "cap_state": { "anyOf": [ { "type": "string", "enum": [ "ok" ] }, { "type": "string", "enum": [ "warning" ] }, { "type": "string", "enum": [ "exhausted" ] }, { "type": "string", "enum": [ "overage" ] }, { "type": "string", "enum": [ "over_allowance" ] }, { "type": "string", "enum": [ "egress_blocked" ] }, { "type": "string", "enum": [ "uncapped" ] }, { "type": "string", "enum": [ "not_included" ] } ], "description": "ok: below 80 %. warning: 80 % or more of the allowance. exhausted: a hard cap is used up and starts are refused (402 allowance_exhausted; see exhausted_reason). overage: a CPU-hours or RAM GiB-hours allowance is used up while opt-in overage is on and below its spend cap, so starts are admitted and the usage past it is charged (spend_cap). over_allowance: a reported allowance is exceeded (never refused). egress_blocked: the outbound transfer allowance is used up and outbound traffic is blocked. uncapped: runs on spare capacity. not_included: the plan does not define it." } }, "additionalProperties": false } }, "meters": { "type": "array", "items": { "type": "object", "required": [ "meter", "unit", "display_name", "raw_quantity", "billable_quantity", "stripe_event_name" ], "properties": { "meter": { "type": "string", "enum": [ "cpu_seconds", "memory_gib_seconds", "storage_gib_seconds", "egress_bytes", "ingress_bytes", "volume_storage_gib_seconds" ] }, "unit": { "type": "string" }, "display_name": { "type": "string" }, "raw_quantity": { "type": "number", "description": "Measured quantity in meter units (fractional)." }, "billable_quantity": { "type": "integer", "description": "Whole units billed: floor of the raw quantity per workspace-hour." }, "stripe_event_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "additionalProperties": false } }, "alert_thresholds": { "type": "array", "items": { "type": "integer" } }, "spend_cap": { "$ref": "#/components/schemas/SpendCap" }, "template_storage": { "$ref": "#/components/schemas/OrgTemplateStorage" } }, "additionalProperties": false } } } }, "4XX": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "examples": { "not_found": { "$ref": "#/components/examples/not_found" }, "rate_limited": { "$ref": "#/components/examples/rate_limited" }, "validation_failed": { "$ref": "#/components/examples/validation_failed" } } } } }, "5XX": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "examples": { "not_found": { "$ref": "#/components/examples/not_found" }, "rate_limited": { "$ref": "#/components/examples/rate_limited" }, "validation_failed": { "$ref": "#/components/examples/validation_failed" } } } } } } } }, "/v1/organizations/{organization_id}/usage": { "get": { "operationId": "getV1OrganizationsOrganizationIdUsage", "summary": "Usage time series (hour or day buckets) from the ledger", "tags": [ "Usage and spend" ], "description": "Defaults to the current period at day granularity; hour granularity covers at most 31 days, day at most 400. `workspace_id` / `volume_id` (mutually exclusive) narrow it to one workspace or one shared volume (meter volume_storage_gib_seconds). API keys see only their own project.", "parameters": [ { "schema": { "type": "string", "format": "date-time" }, "in": "query", "name": "from", "required": false, "description": "RFC 3339 UTC timestamp with Z." }, { "schema": { "type": "string", "format": "date-time" }, "in": "query", "name": "to", "required": false, "description": "RFC 3339 UTC timestamp with Z." }, { "schema": { "anyOf": [ { "type": "string", "enum": [ "hour" ] }, { "type": "string", "enum": [ "day" ] } ], "default": "day" }, "in": "query", "name": "granularity", "required": false }, { "schema": { "type": "string", "enum": [ "cpu_seconds", "memory_gib_seconds", "storage_gib_seconds", "egress_bytes", "ingress_bytes", "volume_storage_gib_seconds" ] }, "in": "query", "name": "meter", "required": false }, { "schema": { "type": "string", "format": "uuid" }, "in": "query", "name": "workspace_id", "required": false, "description": "UUIDv7, lowercase canonical form." }, { "schema": { "type": "string", "format": "uuid" }, "in": "query", "name": "volume_id", "required": false, "description": "UUIDv7, lowercase canonical form." }, { "schema": { "type": "string", "format": "uuid" }, "in": "query", "name": "project_id", "required": false, "description": "UUIDv7, lowercase canonical form." }, { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "organization_id", "required": true, "description": "UUIDv7, lowercase canonical form." } ], "security": [ { "apiKey": [] } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "required": [ "organization_id", "workspace_id", "volume_id", "project_id", "granularity", "from", "to", "measurement", "data", "template_storage" ], "properties": { "organization_id": { "type": "string", "format": "uuid", "description": "UUIDv7, lowercase canonical form." }, "workspace_id": { "anyOf": [ { "type": "string", "format": "uuid", "description": "UUIDv7, lowercase canonical form." }, { "type": "null" } ] }, "volume_id": { "anyOf": [ { "type": "string", "format": "uuid", "description": "UUIDv7, lowercase canonical form." }, { "type": "null" } ] }, "project_id": { "anyOf": [ { "type": "string", "format": "uuid", "description": "UUIDv7, lowercase canonical form." }, { "type": "null" } ] }, "granularity": { "anyOf": [ { "type": "string", "enum": [ "hour" ] }, { "type": "string", "enum": [ "day" ] } ] }, "from": { "type": "string", "format": "date-time", "description": "RFC 3339 UTC timestamp with Z." }, "to": { "type": "string", "format": "date-time", "description": "RFC 3339 UTC timestamp with Z." }, "measurement": { "type": "object", "required": [ "measured_through", "finalized_through", "estimate_status", "running_workspaces", "unmeasured_running_workspaces", "live_volumes", "unmeasured_live_volumes", "measurement_gaps", "source_status", "last_rollup_at" ], "properties": { "measured_through": { "anyOf": [ { "type": "string", "format": "date-time", "description": "RFC 3339 UTC timestamp with Z." }, { "type": "null" } ] }, "finalized_through": { "anyOf": [ { "type": "string", "format": "date-time", "description": "RFC 3339 UTC timestamp with Z." }, { "type": "null" } ] }, "estimate_status": { "anyOf": [ { "type": "string", "enum": [ "no_data" ] }, { "type": "string", "enum": [ "provisional" ] }, { "type": "string", "enum": [ "final" ] }, { "type": "string", "enum": [ "incomplete" ] } ], "description": "provisional: includes hours not yet finalized (lateness window); incomplete: measurement gaps in the period (never zero-filled); final: every hour of the range is finalized." }, "running_workspaces": { "type": "integer" }, "unmeasured_running_workspaces": { "type": "integer", "description": "Running workspaces without any usage record yet." }, "live_volumes": { "type": "integer", "description": "Shared volumes in state available (storage accrues); their last measurement bounds measured_through." }, "unmeasured_live_volumes": { "type": "integer", "description": "Live shared volumes without any storage measurement yet." }, "measurement_gaps": { "type": "object", "required": [ "count", "seconds", "last_at" ], "properties": { "count": { "type": "integer" }, "seconds": { "type": "number" }, "last_at": { "anyOf": [ { "type": "string", "format": "date-time", "description": "RFC 3339 UTC timestamp with Z." }, { "type": "null" } ] } }, "additionalProperties": false, "description": "Unmeasured intervals (workspace usage records and shared-volume storage measurements): never zero-filled, never billed." }, "source_status": { "type": "string", "description": "Usage source (cell ingestion) status: available | unavailable | incompatible | unknown." }, "last_rollup_at": { "anyOf": [ { "type": "string", "format": "date-time", "description": "RFC 3339 UTC timestamp with Z." }, { "type": "null" } ] } }, "additionalProperties": false, "description": "Measurement freshness: estimates are complete up to measured_through." }, "data": { "type": "array", "items": { "type": "object", "required": [ "start", "end", "meter", "raw_quantity", "billable_quantity", "finalized" ], "properties": { "start": { "type": "string", "format": "date-time", "description": "RFC 3339 UTC timestamp with Z." }, "end": { "type": "string", "format": "date-time", "description": "RFC 3339 UTC timestamp with Z." }, "meter": { "type": "string", "enum": [ "cpu_seconds", "memory_gib_seconds", "storage_gib_seconds", "egress_bytes", "ingress_bytes", "volume_storage_gib_seconds" ] }, "raw_quantity": { "type": "number" }, "billable_quantity": { "type": "integer" }, "finalized": { "type": "boolean", "description": "Every hour of the bucket is past the lateness window (later corrections are still possible and are separate ledger rows)." } }, "additionalProperties": false } }, "template_storage": { "anyOf": [ { "$ref": "#/components/schemas/OrgTemplateStorage" }, { "type": "null" } ] } }, "additionalProperties": false } } } }, "4XX": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "examples": { "not_found": { "$ref": "#/components/examples/not_found" }, "rate_limited": { "$ref": "#/components/examples/rate_limited" }, "validation_failed": { "$ref": "#/components/examples/validation_failed" } } } } }, "5XX": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "examples": { "not_found": { "$ref": "#/components/examples/not_found" }, "rate_limited": { "$ref": "#/components/examples/rate_limited" }, "validation_failed": { "$ref": "#/components/examples/validation_failed" } } } } } } } }, "/v1/workspaces/{workspace_id}/usage": { "get": { "operationId": "getV1WorkspacesWorkspaceIdUsage", "summary": "Usage of one workspace (time series and totals)", "tags": [ "Usage and spend" ], "parameters": [ { "schema": { "type": "string", "format": "date-time" }, "in": "query", "name": "from", "required": false, "description": "RFC 3339 UTC timestamp with Z." }, { "schema": { "type": "string", "format": "date-time" }, "in": "query", "name": "to", "required": false, "description": "RFC 3339 UTC timestamp with Z." }, { "schema": { "anyOf": [ { "type": "string", "enum": [ "hour" ] }, { "type": "string", "enum": [ "day" ] } ], "default": "day" }, "in": "query", "name": "granularity", "required": false }, { "schema": { "type": "string", "enum": [ "cpu_seconds", "memory_gib_seconds", "storage_gib_seconds", "egress_bytes", "ingress_bytes", "volume_storage_gib_seconds" ] }, "in": "query", "name": "meter", "required": false }, { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "workspace_id", "required": true, "description": "UUIDv7, lowercase canonical form." } ], "security": [ { "apiKey": [] } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "required": [ "organization_id", "workspace_id", "volume_id", "project_id", "granularity", "from", "to", "measurement", "data", "template_storage" ], "properties": { "organization_id": { "type": "string", "format": "uuid", "description": "UUIDv7, lowercase canonical form." }, "workspace_id": { "anyOf": [ { "type": "string", "format": "uuid", "description": "UUIDv7, lowercase canonical form." }, { "type": "null" } ] }, "volume_id": { "anyOf": [ { "type": "string", "format": "uuid", "description": "UUIDv7, lowercase canonical form." }, { "type": "null" } ] }, "project_id": { "anyOf": [ { "type": "string", "format": "uuid", "description": "UUIDv7, lowercase canonical form." }, { "type": "null" } ] }, "granularity": { "anyOf": [ { "type": "string", "enum": [ "hour" ] }, { "type": "string", "enum": [ "day" ] } ] }, "from": { "type": "string", "format": "date-time", "description": "RFC 3339 UTC timestamp with Z." }, "to": { "type": "string", "format": "date-time", "description": "RFC 3339 UTC timestamp with Z." }, "measurement": { "type": "object", "required": [ "measured_through", "finalized_through", "estimate_status", "running_workspaces", "unmeasured_running_workspaces", "live_volumes", "unmeasured_live_volumes", "measurement_gaps", "source_status", "last_rollup_at" ], "properties": { "measured_through": { "anyOf": [ { "type": "string", "format": "date-time", "description": "RFC 3339 UTC timestamp with Z." }, { "type": "null" } ] }, "finalized_through": { "anyOf": [ { "type": "string", "format": "date-time", "description": "RFC 3339 UTC timestamp with Z." }, { "type": "null" } ] }, "estimate_status": { "anyOf": [ { "type": "string", "enum": [ "no_data" ] }, { "type": "string", "enum": [ "provisional" ] }, { "type": "string", "enum": [ "final" ] }, { "type": "string", "enum": [ "incomplete" ] } ], "description": "provisional: includes hours not yet finalized (lateness window); incomplete: measurement gaps in the period (never zero-filled); final: every hour of the range is finalized." }, "running_workspaces": { "type": "integer" }, "unmeasured_running_workspaces": { "type": "integer", "description": "Running workspaces without any usage record yet." }, "live_volumes": { "type": "integer", "description": "Shared volumes in state available (storage accrues); their last measurement bounds measured_through." }, "unmeasured_live_volumes": { "type": "integer", "description": "Live shared volumes without any storage measurement yet." }, "measurement_gaps": { "type": "object", "required": [ "count", "seconds", "last_at" ], "properties": { "count": { "type": "integer" }, "seconds": { "type": "number" }, "last_at": { "anyOf": [ { "type": "string", "format": "date-time", "description": "RFC 3339 UTC timestamp with Z." }, { "type": "null" } ] } }, "additionalProperties": false, "description": "Unmeasured intervals (workspace usage records and shared-volume storage measurements): never zero-filled, never billed." }, "source_status": { "type": "string", "description": "Usage source (cell ingestion) status: available | unavailable | incompatible | unknown." }, "last_rollup_at": { "anyOf": [ { "type": "string", "format": "date-time", "description": "RFC 3339 UTC timestamp with Z." }, { "type": "null" } ] } }, "additionalProperties": false, "description": "Measurement freshness: estimates are complete up to measured_through." }, "data": { "type": "array", "items": { "type": "object", "required": [ "start", "end", "meter", "raw_quantity", "billable_quantity", "finalized" ], "properties": { "start": { "type": "string", "format": "date-time", "description": "RFC 3339 UTC timestamp with Z." }, "end": { "type": "string", "format": "date-time", "description": "RFC 3339 UTC timestamp with Z." }, "meter": { "type": "string", "enum": [ "cpu_seconds", "memory_gib_seconds", "storage_gib_seconds", "egress_bytes", "ingress_bytes", "volume_storage_gib_seconds" ] }, "raw_quantity": { "type": "number" }, "billable_quantity": { "type": "integer" }, "finalized": { "type": "boolean", "description": "Every hour of the bucket is past the lateness window (later corrections are still possible and are separate ledger rows)." } }, "additionalProperties": false } }, "template_storage": { "anyOf": [ { "$ref": "#/components/schemas/OrgTemplateStorage" }, { "type": "null" } ] } }, "additionalProperties": false } } } }, "4XX": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "examples": { "not_found": { "$ref": "#/components/examples/not_found" }, "rate_limited": { "$ref": "#/components/examples/rate_limited" }, "validation_failed": { "$ref": "#/components/examples/validation_failed" } } } } }, "5XX": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "examples": { "not_found": { "$ref": "#/components/examples/not_found" }, "rate_limited": { "$ref": "#/components/examples/rate_limited" }, "validation_failed": { "$ref": "#/components/examples/validation_failed" } } } } } } } }, "/v1/organizations/{organization_id}/usage/estimate": { "get": { "operationId": "getV1OrganizationsOrganizationIdUsageEstimate", "summary": "Period cost estimate: subscription fee, usage charges and projected allowance use", "tags": [ "Usage and spend" ], "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "organization_id", "required": true, "description": "UUIDv7, lowercase canonical form." } ], "security": [ { "apiKey": [] } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "required": [ "organization_id", "plan", "period", "measurement", "currency", "subscription_fee", "usage_charges_minor", "estimated_total_minor", "overage", "spend_cap", "usage_lines", "projections", "notes" ], "properties": { "organization_id": { "type": "string", "format": "uuid", "description": "UUIDv7, lowercase canonical form." }, "plan": { "anyOf": [ { "type": "object", "required": [ "plan_key", "catalog_version", "priority", "overage" ], "properties": { "plan_key": { "type": "string" }, "catalog_version": { "type": "string" }, "priority": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "overage": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "additionalProperties": false }, { "type": "null" } ] }, "period": { "type": "object", "required": [ "start", "end", "resets_at", "source", "counted_from" ], "properties": { "start": { "type": "string", "format": "date-time", "description": "RFC 3339 UTC timestamp with Z." }, "end": { "type": "string", "format": "date-time", "description": "RFC 3339 UTC timestamp with Z." }, "resets_at": { "type": "string", "format": "date-time", "description": "RFC 3339 UTC timestamp with Z." }, "source": { "anyOf": [ { "type": "string", "enum": [ "subscription" ] }, { "type": "string", "enum": [ "calendar_month" ] } ], "description": "The entitling subscription period, else the calendar month (UTC)." }, "counted_from": { "type": "string", "format": "date-time", "description": "First hour whose usage counts in this period (RFC 3339 UTC). Usage is metered per UTC hour, and each hour belongs to the period that contains its start (the hour's ledger rows keep the plan in force at that instant and are sent to Stripe with that timestamp). When the period starts inside an hour (after a plan change, or a subscription created mid-hour), that hour's usage counts toward the previous period, so counted_from is `start` rounded up to the next full hour; on a full hour it equals `start`. Before counted_from passes, the period has no counted usage (`estimate_status` no_data) even while workspaces run: their usage is in the usage series under the hour containing `start`." } }, "additionalProperties": false }, "measurement": { "type": "object", "required": [ "measured_through", "finalized_through", "estimate_status", "running_workspaces", "unmeasured_running_workspaces", "live_volumes", "unmeasured_live_volumes", "measurement_gaps", "source_status", "last_rollup_at" ], "properties": { "measured_through": { "anyOf": [ { "type": "string", "format": "date-time", "description": "RFC 3339 UTC timestamp with Z." }, { "type": "null" } ] }, "finalized_through": { "anyOf": [ { "type": "string", "format": "date-time", "description": "RFC 3339 UTC timestamp with Z." }, { "type": "null" } ] }, "estimate_status": { "anyOf": [ { "type": "string", "enum": [ "no_data" ] }, { "type": "string", "enum": [ "provisional" ] }, { "type": "string", "enum": [ "final" ] }, { "type": "string", "enum": [ "incomplete" ] } ], "description": "provisional: includes hours not yet finalized (lateness window); incomplete: measurement gaps in the period (never zero-filled); final: every hour of the range is finalized." }, "running_workspaces": { "type": "integer" }, "unmeasured_running_workspaces": { "type": "integer", "description": "Running workspaces without any usage record yet." }, "live_volumes": { "type": "integer", "description": "Shared volumes in state available (storage accrues); their last measurement bounds measured_through." }, "unmeasured_live_volumes": { "type": "integer", "description": "Live shared volumes without any storage measurement yet." }, "measurement_gaps": { "type": "object", "required": [ "count", "seconds", "last_at" ], "properties": { "count": { "type": "integer" }, "seconds": { "type": "number" }, "last_at": { "anyOf": [ { "type": "string", "format": "date-time", "description": "RFC 3339 UTC timestamp with Z." }, { "type": "null" } ] } }, "additionalProperties": false, "description": "Unmeasured intervals (workspace usage records and shared-volume storage measurements): never zero-filled, never billed." }, "source_status": { "type": "string", "description": "Usage source (cell ingestion) status: available | unavailable | incompatible | unknown." }, "last_rollup_at": { "anyOf": [ { "type": "string", "format": "date-time", "description": "RFC 3339 UTC timestamp with Z." }, { "type": "null" } ] } }, "additionalProperties": false, "description": "Measurement freshness: estimates are complete up to measured_through." }, "currency": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "subscription_fee": { "anyOf": [ { "type": "object", "required": [ "amount_minor", "currency", "interval" ], "properties": { "amount_minor": { "type": "integer" }, "currency": { "type": "string" }, "interval": { "type": "string" } }, "additionalProperties": false }, { "type": "null" } ] }, "usage_charges_minor": { "type": "integer", "description": "Overage charged this period so far, whole minor units (floor; spend_cap.charges_minor). 0 while overage is off or unavailable and nothing was charged this period." }, "estimated_total_minor": { "anyOf": [ { "type": "integer", "description": "subscription_fee.amount_minor + usage_charges_minor; null without a subscription price." }, { "type": "null" } ] }, "overage": { "anyOf": [ { "type": "string", "description": "The plan's overage policy: disabled | opt_in | enabled." }, { "type": "null" } ] }, "spend_cap": { "$ref": "#/components/schemas/SpendCap" }, "usage_lines": { "type": "array", "items": { "type": "object", "required": [ "meter", "unit", "display_name", "raw_quantity", "billable_quantity", "allowance", "unit_price_minor", "amount_minor" ], "properties": { "meter": { "type": "string", "enum": [ "cpu_seconds", "memory_gib_seconds", "storage_gib_seconds", "egress_bytes", "ingress_bytes", "volume_storage_gib_seconds" ] }, "unit": { "type": "string" }, "display_name": { "type": "string" }, "raw_quantity": { "type": "number" }, "billable_quantity": { "type": "integer" }, "allowance": { "anyOf": [ { "type": "string", "description": "Allowance that includes this meter; null = no allowance (e.g. shared volume storage)." }, { "type": "null" } ] }, "unit_price_minor": { "anyOf": [ { "type": "number", "description": "Overage price per billable unit past the allowance, minor units (fractional): the overage rate per unit-hour ÷ 3600, e.g. 4 cents per RAM GiB-hour = 0.00111… per GiB-second on memory_gib_seconds, 12 cents per CPU-hour on cpu_seconds. Null for meters overage never covers and when the plan has no opt-in overage." }, { "type": "null" } ] }, "amount_minor": { "type": "integer", "description": "Overage charged on this meter this period, whole minor units (floor; the matching spend_cap line). 0 for meters overage never covers and when nothing was charged." } }, "additionalProperties": false }, "description": "Period-to-date usage per meter with its overage price and charge (included in usage_charges_minor)." }, "projections": { "type": "array", "items": { "type": "object", "required": [ "allowance", "unit", "enforcement", "included", "used", "projected_at_period_end", "projected_exhaustion_at" ], "properties": { "allowance": { "type": "string" }, "unit": { "type": "string" }, "enforcement": { "type": "string" }, "included": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "used": { "type": "number" }, "projected_at_period_end": { "type": "number", "description": "Linear projection of the period-to-date rate (informational)." }, "projected_exhaustion_at": { "anyOf": [ { "type": "string", "format": "date-time", "description": "RFC 3339 UTC timestamp with Z." }, { "type": "null" } ] } }, "additionalProperties": false } }, "notes": { "type": "array", "items": { "type": "string" } } }, "additionalProperties": false } } } }, "4XX": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "examples": { "not_found": { "$ref": "#/components/examples/not_found" }, "rate_limited": { "$ref": "#/components/examples/rate_limited" }, "validation_failed": { "$ref": "#/components/examples/validation_failed" } } } } }, "5XX": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "examples": { "not_found": { "$ref": "#/components/examples/not_found" }, "rate_limited": { "$ref": "#/components/examples/rate_limited" }, "validation_failed": { "$ref": "#/components/examples/validation_failed" } } } } } } } }, "/v1/organizations/{organization_id}/grants": { "get": { "operationId": "getV1OrganizationsOrganizationIdGrants", "summary": "Quotas, per-workspace ceilings/reservations/grants and compute budget leases", "tags": [ "Usage and spend" ], "description": "Ceiling = min(template, user cap, plan cap). Reservations are organization-level (pending starts count). Leases are the compute budgets granted to the cell (<= 15 min). API keys see only their own project’s workspaces.", "parameters": [ { "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 }, "in": "query", "name": "limit", "required": false }, { "schema": { "type": "string", "maxLength": 200 }, "in": "query", "name": "cursor", "required": false }, { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "organization_id", "required": true, "description": "UUIDv7, lowercase canonical form." } ], "security": [ { "apiKey": [] } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "required": [ "organization_id", "plan", "limits", "reserved", "workspaces", "next_cursor", "leases", "lease_policy", "delegations" ], "properties": { "organization_id": { "type": "string", "format": "uuid", "description": "UUIDv7, lowercase canonical form." }, "plan": { "anyOf": [ { "type": "object", "required": [ "plan_key", "catalog_version", "priority", "overage" ], "properties": { "plan_key": { "type": "string" }, "catalog_version": { "type": "string" }, "priority": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "overage": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "additionalProperties": false }, { "type": "null" } ] }, "limits": { "type": "object", "properties": {}, "additionalProperties": true, "description": "Organization quotas and per-workspace caps from the plan (null = unlimited)." }, "reserved": { "type": "object", "required": [ "pending", "committed" ], "properties": { "pending": { "type": "object", "required": [ "count", "cpu_millis", "memory_mib", "disk_gib" ], "properties": { "count": { "type": "integer" }, "cpu_millis": { "type": "integer" }, "memory_mib": { "type": "integer" }, "disk_gib": { "type": "integer" } }, "additionalProperties": false }, "committed": { "type": "object", "required": [ "count", "cpu_millis", "memory_mib", "disk_gib" ], "properties": { "count": { "type": "integer" }, "cpu_millis": { "type": "integer" }, "memory_mib": { "type": "integer" }, "disk_gib": { "type": "integer" } }, "additionalProperties": false } }, "additionalProperties": false, "description": "Organization-level reservations (pending starts count against quotas)." }, "workspaces": { "type": "array", "items": { "type": "object", "required": [ "id", "workspace_key", "project_id", "observed_state", "desired_state", "ceilings", "user_caps", "reservation", "grants", "pending_operation" ], "properties": { "id": { "type": "string", "format": "uuid", "description": "UUIDv7, lowercase canonical form." }, "workspace_key": { "type": "string" }, "project_id": { "type": "string", "format": "uuid", "description": "UUIDv7, lowercase canonical form." }, "observed_state": { "type": "string" }, "desired_state": { "type": "string" }, "ceilings": { "anyOf": [ { "type": "object", "required": [ "cpu_millis", "memory_mib", "disk_gib", "sources" ], "properties": { "cpu_millis": { "type": "integer" }, "memory_mib": { "type": "integer" }, "disk_gib": { "type": "integer" }, "sources": { "type": "object", "properties": {}, "additionalProperties": true } }, "additionalProperties": false }, { "type": "null" } ] }, "user_caps": { "type": "object", "required": [ "cpu_millis", "memory_mib", "disk_gib" ], "properties": { "cpu_millis": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "memory_mib": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "disk_gib": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] } }, "additionalProperties": false }, "reservation": { "anyOf": [ { "type": "object", "required": [ "state", "cpu_millis", "memory_mib", "disk_gib" ], "properties": { "state": { "type": "string" }, "cpu_millis": { "type": "integer" }, "memory_mib": { "type": "integer" }, "disk_gib": { "type": "integer" } }, "additionalProperties": false }, { "type": "null" } ] }, "grants": { "anyOf": [ { "type": "object", "properties": {}, "additionalProperties": true, "description": "Actual grants reported by the cell for the last start." }, { "type": "null" } ] }, "pending_operation": { "anyOf": [ { "type": "object", "required": [ "id", "kind", "state", "state_reason" ], "properties": { "id": { "type": "string", "format": "uuid", "description": "UUIDv7, lowercase canonical form." }, "kind": { "type": "string" }, "state": { "type": "string" }, "state_reason": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "additionalProperties": false }, { "type": "null" } ] } }, "additionalProperties": false } }, "next_cursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "leases": { "type": "array", "items": { "type": "object", "required": [ "id", "cell_id", "sequence", "state", "capped", "cpu_seconds", "memory_gib_seconds", "transfer_bytes", "usage_from", "issued_at", "expires_at", "end_reason", "burn_rate", "overshoot_bound", "cell_consumed_cpu_seconds", "cell_consumed_memory_gib_seconds", "cell_acknowledged_at" ], "properties": { "id": { "type": "string", "format": "uuid", "description": "UUIDv7, lowercase canonical form." }, "cell_id": { "type": "string" }, "sequence": { "type": "integer" }, "state": { "type": "string" }, "capped": { "type": "boolean" }, "cpu_seconds": { "type": "number" }, "memory_gib_seconds": { "type": "number" }, "transfer_bytes": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "usage_from": { "type": "string", "format": "date-time", "description": "RFC 3339 UTC timestamp with Z." }, "issued_at": { "type": "string", "format": "date-time", "description": "RFC 3339 UTC timestamp with Z." }, "expires_at": { "type": "string", "format": "date-time", "description": "RFC 3339 UTC timestamp with Z." }, "end_reason": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "burn_rate": { "type": "object", "required": [ "cpu_seconds_per_second", "memory_gib", "workspaces" ], "properties": { "cpu_seconds_per_second": { "type": "number" }, "memory_gib": { "type": "number" }, "workspaces": { "type": "integer" } }, "additionalProperties": false }, "overshoot_bound": { "type": "object", "required": [ "cpu_seconds", "memory_gib_seconds" ], "properties": { "cpu_seconds": { "type": "number" }, "memory_gib_seconds": { "type": "number" } }, "additionalProperties": false }, "cell_consumed_cpu_seconds": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "cell_consumed_memory_gib_seconds": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "cell_acknowledged_at": { "anyOf": [ { "type": "string", "format": "date-time", "description": "RFC 3339 UTC timestamp with Z." }, { "type": "null" } ] } }, "additionalProperties": false } }, "lease_policy": { "type": "object", "required": [ "ttl_seconds", "renew_before_seconds", "metering_interval_seconds" ], "properties": { "ttl_seconds": { "type": "integer" }, "renew_before_seconds": { "type": "integer" }, "metering_interval_seconds": { "type": "integer" } }, "additionalProperties": false }, "delegations": { "type": "array", "items": { "type": "object", "required": [ "lease_id", "host_id", "state", "cpu_seconds", "memory_gib_seconds", "consumed_cpu_seconds", "consumed_memory_gib_seconds", "expires_at" ], "properties": { "lease_id": { "type": "string", "format": "uuid", "description": "UUIDv7, lowercase canonical form." }, "host_id": { "type": "string", "format": "uuid", "description": "UUIDv7, lowercase canonical form." }, "state": { "type": "string" }, "cpu_seconds": { "type": "number" }, "memory_gib_seconds": { "type": "number" }, "consumed_cpu_seconds": { "type": "number" }, "consumed_memory_gib_seconds": { "type": "number" }, "expires_at": { "type": "string", "format": "date-time", "description": "RFC 3339 UTC timestamp with Z." } }, "additionalProperties": false, "description": "Per-host sub-budgets the cell delegated from the active leases (cell.budget_delegations)." } } }, "additionalProperties": false } } } }, "4XX": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "examples": { "not_found": { "$ref": "#/components/examples/not_found" }, "rate_limited": { "$ref": "#/components/examples/rate_limited" }, "validation_failed": { "$ref": "#/components/examples/validation_failed" } } } } }, "5XX": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "examples": { "not_found": { "$ref": "#/components/examples/not_found" }, "rate_limited": { "$ref": "#/components/examples/rate_limited" }, "validation_failed": { "$ref": "#/components/examples/validation_failed" } } } } } } } }, "/v1/organizations/{organization_id}/spend": { "get": { "operationId": "getV1OrganizationsOrganizationIdSpend", "summary": "Spend policy, charges this period, cap state and enforcement (leases, overshoot bound)", "tags": [ "Usage and spend" ], "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "organization_id", "required": true, "description": "UUIDv7, lowercase canonical form." } ], "security": [ { "apiKey": [] } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "required": [ "organization_id", "plan", "period", "measurement", "currency", "overage", "alert_thresholds", "subscription_fee_minor", "usage_charges_minor", "estimated_period_total_minor", "cap_state", "exhausted", "exhausted_reason", "spend_cap", "enforcement", "meter_submissions", "cell_enforcement" ], "properties": { "organization_id": { "type": "string", "format": "uuid", "description": "UUIDv7, lowercase canonical form." }, "plan": { "anyOf": [ { "type": "object", "required": [ "plan_key", "catalog_version", "priority", "overage" ], "properties": { "plan_key": { "type": "string" }, "catalog_version": { "type": "string" }, "priority": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "overage": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "additionalProperties": false }, { "type": "null" } ] }, "period": { "type": "object", "required": [ "start", "end", "resets_at", "source", "counted_from" ], "properties": { "start": { "type": "string", "format": "date-time", "description": "RFC 3339 UTC timestamp with Z." }, "end": { "type": "string", "format": "date-time", "description": "RFC 3339 UTC timestamp with Z." }, "resets_at": { "type": "string", "format": "date-time", "description": "RFC 3339 UTC timestamp with Z." }, "source": { "anyOf": [ { "type": "string", "enum": [ "subscription" ] }, { "type": "string", "enum": [ "calendar_month" ] } ], "description": "The entitling subscription period, else the calendar month (UTC)." }, "counted_from": { "type": "string", "format": "date-time", "description": "First hour whose usage counts in this period (RFC 3339 UTC). Usage is metered per UTC hour, and each hour belongs to the period that contains its start (the hour's ledger rows keep the plan in force at that instant and are sent to Stripe with that timestamp). When the period starts inside an hour (after a plan change, or a subscription created mid-hour), that hour's usage counts toward the previous period, so counted_from is `start` rounded up to the next full hour; on a full hour it equals `start`. Before counted_from passes, the period has no counted usage (`estimate_status` no_data) even while workspaces run: their usage is in the usage series under the hour containing `start`." } }, "additionalProperties": false }, "measurement": { "type": "object", "required": [ "measured_through", "finalized_through", "estimate_status", "running_workspaces", "unmeasured_running_workspaces", "live_volumes", "unmeasured_live_volumes", "measurement_gaps", "source_status", "last_rollup_at" ], "properties": { "measured_through": { "anyOf": [ { "type": "string", "format": "date-time", "description": "RFC 3339 UTC timestamp with Z." }, { "type": "null" } ] }, "finalized_through": { "anyOf": [ { "type": "string", "format": "date-time", "description": "RFC 3339 UTC timestamp with Z." }, { "type": "null" } ] }, "estimate_status": { "anyOf": [ { "type": "string", "enum": [ "no_data" ] }, { "type": "string", "enum": [ "provisional" ] }, { "type": "string", "enum": [ "final" ] }, { "type": "string", "enum": [ "incomplete" ] } ], "description": "provisional: includes hours not yet finalized (lateness window); incomplete: measurement gaps in the period (never zero-filled); final: every hour of the range is finalized." }, "running_workspaces": { "type": "integer" }, "unmeasured_running_workspaces": { "type": "integer", "description": "Running workspaces without any usage record yet." }, "live_volumes": { "type": "integer", "description": "Shared volumes in state available (storage accrues); their last measurement bounds measured_through." }, "unmeasured_live_volumes": { "type": "integer", "description": "Live shared volumes without any storage measurement yet." }, "measurement_gaps": { "type": "object", "required": [ "count", "seconds", "last_at" ], "properties": { "count": { "type": "integer" }, "seconds": { "type": "number" }, "last_at": { "anyOf": [ { "type": "string", "format": "date-time", "description": "RFC 3339 UTC timestamp with Z." }, { "type": "null" } ] } }, "additionalProperties": false, "description": "Unmeasured intervals (workspace usage records and shared-volume storage measurements): never zero-filled, never billed." }, "source_status": { "type": "string", "description": "Usage source (cell ingestion) status: available | unavailable | incompatible | unknown." }, "last_rollup_at": { "anyOf": [ { "type": "string", "format": "date-time", "description": "RFC 3339 UTC timestamp with Z." }, { "type": "null" } ] } }, "additionalProperties": false, "description": "Measurement freshness: estimates are complete up to measured_through." }, "currency": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "overage": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "alert_thresholds": { "type": "array", "items": { "type": "integer" } }, "subscription_fee_minor": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "usage_charges_minor": { "type": "integer", "description": "Overage charged this period so far, whole minor units (floor; spend_cap.charges_minor)." }, "estimated_period_total_minor": { "anyOf": [ { "type": "integer", "description": "subscription_fee_minor + usage_charges_minor; null without a subscription price." }, { "type": "null" } ] }, "cap_state": { "anyOf": [ { "type": "string", "enum": [ "ok" ] }, { "type": "string", "enum": [ "warning" ] }, { "type": "string", "enum": [ "overage" ] }, { "type": "string", "enum": [ "exhausted" ] } ], "description": "Worst state over hard-cap allowances: exhausted (starts refused, see exhausted_reason) > overage (past an allowance, charged under the spend cap) > warning (80 % or more) > ok." }, "exhausted": { "type": "array", "items": { "type": "string" } }, "exhausted_reason": { "anyOf": [ { "anyOf": [ { "type": "string", "enum": [ "allowance_used" ] }, { "type": "string", "enum": [ "overage_paused" ] }, { "type": "string", "enum": [ "spend_cap_reached" ] } ], "description": "Why new starts are refused (the details.reason of 402 allowance_exhausted). allowance_used: a hard-cap allowance is used up and overage is off or not available on the plan. overage_paused: overage is on but paused while a plan invoice is past due. spend_cap_reached: overage reached the spend cap for this period." }, { "type": "null" } ] }, "spend_cap": { "$ref": "#/components/schemas/SpendCap" }, "enforcement": { "type": "object", "required": [ "new_starts", "running_workspaces", "suspension", "leases", "overshoot_bound" ], "properties": { "new_starts": { "anyOf": [ { "type": "string", "enum": [ "allowed" ] }, { "type": "string", "enum": [ "refused" ] } ], "description": "refused while any hard-cap allowance is exhausted (402 allowance_exhausted with exhausted_reason as details.reason)." }, "running_workspaces": { "type": "integer" }, "suspension": { "type": "string", "description": "How running workspaces are stopped when a hard cap is reached." }, "leases": { "type": "array", "items": { "type": "object", "required": [ "id", "cell_id", "sequence", "state", "capped", "cpu_seconds", "memory_gib_seconds", "transfer_bytes", "usage_from", "issued_at", "expires_at", "end_reason", "burn_rate", "overshoot_bound", "cell_consumed_cpu_seconds", "cell_consumed_memory_gib_seconds", "cell_acknowledged_at" ], "properties": { "id": { "type": "string", "format": "uuid", "description": "UUIDv7, lowercase canonical form." }, "cell_id": { "type": "string" }, "sequence": { "type": "integer" }, "state": { "type": "string" }, "capped": { "type": "boolean" }, "cpu_seconds": { "type": "number" }, "memory_gib_seconds": { "type": "number" }, "transfer_bytes": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "usage_from": { "type": "string", "format": "date-time", "description": "RFC 3339 UTC timestamp with Z." }, "issued_at": { "type": "string", "format": "date-time", "description": "RFC 3339 UTC timestamp with Z." }, "expires_at": { "type": "string", "format": "date-time", "description": "RFC 3339 UTC timestamp with Z." }, "end_reason": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "burn_rate": { "type": "object", "required": [ "cpu_seconds_per_second", "memory_gib", "workspaces" ], "properties": { "cpu_seconds_per_second": { "type": "number" }, "memory_gib": { "type": "number" }, "workspaces": { "type": "integer" } }, "additionalProperties": false }, "overshoot_bound": { "type": "object", "required": [ "cpu_seconds", "memory_gib_seconds" ], "properties": { "cpu_seconds": { "type": "number" }, "memory_gib_seconds": { "type": "number" } }, "additionalProperties": false }, "cell_consumed_cpu_seconds": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "cell_consumed_memory_gib_seconds": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "cell_acknowledged_at": { "anyOf": [ { "type": "string", "format": "date-time", "description": "RFC 3339 UTC timestamp with Z." }, { "type": "null" } ] } }, "additionalProperties": false } }, "overshoot_bound": { "type": "object", "required": [ "cpu_seconds", "memory_gib_seconds", "note" ], "properties": { "cpu_seconds": { "type": "number" }, "memory_gib_seconds": { "type": "number" }, "note": { "type": "string" } }, "additionalProperties": false } }, "additionalProperties": false }, "meter_submissions": { "anyOf": [ { "type": "object", "properties": {}, "additionalProperties": true, "description": "Stripe meter submission states (owner/billing only; null otherwise)." }, { "type": "null" } ] }, "cell_enforcement": { "anyOf": [ { "type": "object", "required": [ "state", "meter", "reason", "since", "details" ], "properties": { "state": { "anyOf": [ { "type": "string", "enum": [ "ok" ] }, { "type": "string", "enum": [ "exhausted" ] } ] }, "meter": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "reason": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "since": { "type": "string", "format": "date-time", "description": "RFC 3339 UTC timestamp with Z." }, "details": { "type": "object", "properties": {}, "additionalProperties": true } }, "additionalProperties": false, "description": "What the cell enforces from the leases (cell.org_spend_state): exhausted = hosts paused billable execution and the cell refuses queued starts. Null until the cell has evaluated a lease of this organization." }, { "type": "null" } ] } }, "additionalProperties": false } } } }, "4XX": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "examples": { "not_found": { "$ref": "#/components/examples/not_found" }, "rate_limited": { "$ref": "#/components/examples/rate_limited" }, "validation_failed": { "$ref": "#/components/examples/validation_failed" } } } } }, "5XX": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "examples": { "not_found": { "$ref": "#/components/examples/not_found" }, "rate_limited": { "$ref": "#/components/examples/rate_limited" }, "validation_failed": { "$ref": "#/components/examples/validation_failed" } } } } } } } }, "/v1/organizations/{organization_id}/spend-policy": { "get": { "operationId": "getV1OrganizationsOrganizationIdSpendPolicy", "summary": "Usage alert thresholds and opt-in overage with its spend cap", "tags": [ "Usage and spend" ], "description": "Alert thresholds, and whether overage is available, on, off or paused, with the spend cap, its bounds and the rates. Overage is off by default; owners and billing members change it with the PUT (the console on /api/v1, or a CLI session on /v1; project API keys are refused).", "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "organization_id", "required": true, "description": "UUIDv7, lowercase canonical form." } ], "security": [ { "apiKey": [] } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "required": [ "organization_id", "alert_thresholds", "overage", "overage_available", "overage_enabled", "overage_state", "spend_cap_minor", "spend_cap_max_minor", "spend_cap_min_minor", "rates", "currency", "updated_at", "version" ], "properties": { "organization_id": { "type": "string", "format": "uuid", "description": "UUIDv7, lowercase canonical form." }, "alert_thresholds": { "type": "array", "items": { "type": "integer" }, "description": "Percentages of each allowance that send a usage email to owners and billing members." }, "overage": { "anyOf": [ { "type": "string", "description": "The plan's overage policy: disabled | opt_in | enabled; null without a plan." }, { "type": "null" } ] }, "overage_available": { "type": "boolean", "description": "The plan offers opt-in overage and the organization pays for it with a subscription, so overage can be turned on." }, "overage_enabled": { "type": "boolean", "description": "Overage is turned on (off by default)." }, "overage_state": { "anyOf": [ { "type": "string", "enum": [ "unavailable" ] }, { "type": "string", "enum": [ "off" ] }, { "type": "string", "enum": [ "on" ] }, { "type": "string", "enum": [ "paused" ] } ], "description": "unavailable: overage_available is false. off: available, not turned on. on: in effect up to the spend cap. paused: turned on, but a plan invoice is past due, so it behaves as off until the invoice is paid." }, "spend_cap_minor": { "anyOf": [ { "type": "integer", "description": "The configured spend cap per billing period, minor units of `currency`. Null: never set." }, { "type": "null" } ] }, "spend_cap_max_minor": { "anyOf": [ { "type": "integer", "description": "The largest cap that can be set: the current plan price. Null when overage is unavailable." }, { "type": "null" } ] }, "spend_cap_min_minor": { "type": "integer", "description": "The smallest cap that can be set (100 = $1)." }, "rates": { "type": "array", "items": { "type": "object", "required": [ "allowance", "unit", "amount_minor_per_unit" ], "properties": { "allowance": { "anyOf": [ { "type": "string", "enum": [ "ram_gib_hours" ] }, { "type": "string", "enum": [ "cpu_hours" ] } ], "description": "The allowances overage covers. Storage and transfer never accrue overage." }, "unit": { "anyOf": [ { "type": "string", "enum": [ "gib_hours" ] }, { "type": "string", "enum": [ "hours" ] } ], "description": "gib_hours for ram_gib_hours, hours (CPU-hours) for cpu_hours." }, "amount_minor_per_unit": { "type": "number", "description": "Minor units per unit-hour past the allowance (4 = $0.04 per RAM GiB-hour, 12 = $0.12 per CPU-hour)." } }, "additionalProperties": false }, "description": "Overage rates of the organization's plan grant. Empty when the plan has none." }, "currency": { "type": "string", "description": "ISO 4217 code, lower case, of the cap and the rates." }, "updated_at": { "anyOf": [ { "type": "string", "format": "date-time", "description": "RFC 3339 UTC timestamp with Z." }, { "type": "null" } ] }, "version": { "type": "integer", "description": "Send it as If-Match on PUT to detect a concurrent change (409 conflict, reason version_mismatch)." } }, "additionalProperties": false } } } }, "4XX": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "examples": { "not_found": { "$ref": "#/components/examples/not_found" }, "rate_limited": { "$ref": "#/components/examples/rate_limited" }, "validation_failed": { "$ref": "#/components/examples/validation_failed" } } } } }, "5XX": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "examples": { "not_found": { "$ref": "#/components/examples/not_found" }, "rate_limited": { "$ref": "#/components/examples/rate_limited" }, "validation_failed": { "$ref": "#/components/examples/validation_failed" } } } } } } } }, "/v1/feedback": { "post": { "operationId": "postV1Feedback", "summary": "Send product feedback to the Shardflux team", "tags": [ "Feedback" ], "description": "Delivered by email to the Shardflux team. Any valid project API key may send (no tool permission needed); the key's organization and project are recorded, so `organization_id` is rejected (422). A CLI session (`sfu_`) may send too, with an optional `organization_id` of the user's. Coding agents: send feedback whenever something fails, is confusing or missing, and include `context` (`agent`, `client`, `workspace`, `request_id` and `error_code` of the error response, `command`). Rate limited per sender (10 per 10 minutes, 50 per day) and per organization (200 per day): 429 `rate_limited` with a `retry-after` header and `details.retry_after_seconds`. The same message from the same sender within 24 hours is a duplicate: 200 with the original `id` and `duplicate: true` (it still counts against the rate limits). The body is limited to 32 KiB (413).", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "message" ], "properties": { "message": { "type": "string", "minLength": 1, "description": "The feedback, 1-8000 characters after trimming surrounding whitespace (must contain a non-whitespace character). Control characters other than newline and tab are stripped; API keys, bearer tokens, JWTs, AWS access key ids and private key blocks are redacted before it is stored or emailed." }, "category": { "type": "string", "enum": [ "bug", "confusing", "missing", "idea", "praise", "other" ], "default": "other", "description": "Default `other`. `bug`: something failed or behaved wrongly; `confusing`: an error, doc, name or output was unclear or misleading; `missing`: a capability, option or template you needed does not exist; `idea`: a suggestion or improvement; `praise`: something worked well; `other`: anything else." }, "organization_id": { "type": "string", "format": "uuid", "description": "Sessions (browser, or a CLI session on /v1): the organization the user is looking at, one they belong to (404 otherwise). Refused (422) with a project API key, whose organization is used." }, "context": { "type": "object", "properties": { "agent": { "type": "string", "maxLength": 100, "description": "Who is reporting, e.g. `claude-code`, `codex`, `cursor`, or a human. At most 100 characters." }, "client": { "type": "string", "maxLength": 200, "description": "Client and version, e.g. `shard-cli/0.5.0`, `shardflux-sdk-ts/0.9.0`, `shardflux-py/0.5.0`, `shardflux-mcp/0.4.0`, `dashboard`. At most 200 characters." }, "workspace": { "type": "string", "maxLength": 200, "description": "Workspace id or key the feedback is about. At most 200 characters." }, "request_id": { "type": "string", "maxLength": 200, "description": "`request_id` of an error response, so the logs can be found. At most 200 characters." }, "error_code": { "type": "string", "maxLength": 100, "description": "API error code seen, e.g. `capacity_unavailable`. At most 100 characters." }, "command": { "type": "string", "maxLength": 2000, "description": "The command, SDK call or tool call that led to it. At most 2000 characters." }, "page": { "type": "string", "maxLength": 300, "description": "Dashboard route path (browser). At most 300 characters." } }, "additionalProperties": false, "description": "Optional, every field optional. Control characters are stripped and anything shaped like a secret is redacted before storing." } }, "additionalProperties": false } } } }, "security": [ { "apiKey": [] } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "required": [ "id", "received_at", "duplicate" ], "properties": { "id": { "type": "string", "format": "uuid", "description": "UUIDv7, lowercase canonical form." }, "received_at": { "type": "string", "format": "date-time", "description": "RFC 3339 UTC timestamp with Z." }, "duplicate": { "type": "boolean", "description": "true when the same sender sent the same message within 24 hours: the original feedback is returned and nothing new is stored or emailed." } }, "additionalProperties": false } } } }, "201": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "required": [ "id", "received_at", "duplicate" ], "properties": { "id": { "type": "string", "format": "uuid", "description": "UUIDv7, lowercase canonical form." }, "received_at": { "type": "string", "format": "date-time", "description": "RFC 3339 UTC timestamp with Z." }, "duplicate": { "type": "boolean", "description": "true when the same sender sent the same message within 24 hours: the original feedback is returned and nothing new is stored or emailed." } }, "additionalProperties": false } } } }, "4XX": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "examples": { "not_found": { "$ref": "#/components/examples/not_found" }, "rate_limited": { "$ref": "#/components/examples/rate_limited" }, "validation_failed": { "$ref": "#/components/examples/validation_failed" } } } } }, "5XX": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "examples": { "not_found": { "$ref": "#/components/examples/not_found" }, "rate_limited": { "$ref": "#/components/examples/rate_limited" }, "validation_failed": { "$ref": "#/components/examples/validation_failed" } } } } } } } }, "/v1/billing/catalog": { "get": { "operationId": "getV1BillingCatalog", "summary": "The active plan catalog (the same versioned catalog admission enforces)", "tags": [ "Billing" ], "description": "Public, cacheable. Prices are in minor units; `purchasable` plans can be bought with POST .../organizations/{id}/billing/checkout-sessions (a browser or CLI session; `shard billing upgrade `).", "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "required": [ "catalog_version", "mode", "currency", "activation_at", "approved_commercial", "plans", "policies", "units" ], "properties": { "catalog_version": { "type": "string" }, "mode": { "anyOf": [ { "type": "string", "enum": [ "test" ] }, { "type": "string", "enum": [ "live" ] } ] }, "currency": { "type": "string" }, "activation_at": { "type": "string", "format": "date-time", "description": "RFC 3339 UTC timestamp with Z." }, "approved_commercial": { "type": "boolean" }, "plans": { "type": "array", "items": { "type": "object", "required": [ "plan_key", "name", "priority", "overage", "limits", "allowances", "prices" ], "properties": { "plan_key": { "type": "string" }, "name": { "type": "string" }, "priority": { "type": "string" }, "overage": { "type": "string" }, "limits": { "type": "object", "properties": {}, "additionalProperties": true, "description": "Admission limits (null = unlimited)." }, "allowances": { "type": "object", "properties": {}, "additionalProperties": true }, "prices": { "type": "array", "items": { "type": "object", "required": [ "interval", "amount_minor", "currency", "purchasable" ], "properties": { "interval": { "anyOf": [ { "type": "string", "enum": [ "month" ] }, { "type": "string", "enum": [ "year" ] } ] }, "amount_minor": { "type": "integer", "description": "Price in the currency’s minor unit (cents)." }, "currency": { "type": "string" }, "purchasable": { "type": "boolean", "description": "Bound to a Stripe price of this environment’s mode (checkout accepts it)." } }, "additionalProperties": false } } }, "additionalProperties": false } }, "policies": { "type": "object", "properties": {}, "additionalProperties": true, "description": "Grace, cancellation, overage and retention policies of this catalog version." }, "units": { "type": "object", "properties": {}, "additionalProperties": true } }, "additionalProperties": false } } } }, "4XX": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "examples": { "not_found": { "$ref": "#/components/examples/not_found" }, "rate_limited": { "$ref": "#/components/examples/rate_limited" }, "validation_failed": { "$ref": "#/components/examples/validation_failed" } } } } }, "5XX": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "examples": { "not_found": { "$ref": "#/components/examples/not_found" }, "rate_limited": { "$ref": "#/components/examples/rate_limited" }, "validation_failed": { "$ref": "#/components/examples/validation_failed" } } } } } } } }, "/v1/organizations/{organization_id}/billing/subscription": { "get": { "operationId": "getV1OrganizationsOrganizationIdBillingSubscription", "summary": "Subscription, billing state and effective plan of an organization", "tags": [ "Billing" ], "description": "Owner/billing members (browser) or any API key of the organization (read-only). `billing_state`: free (no paid subscription), active, canceling (ends at period end, then free limits), grace (payment overdue, workspaces unaffected), restricted (grace ended: new opens/resumes answer 402 entitlement_required).", "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "organization_id", "required": true, "description": "UUIDv7, lowercase canonical form." } ], "security": [ { "apiKey": [] } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "required": [ "organization_id", "mode", "billing_state", "plan", "subscription", "restrictions", "pending_checkout", "purchase_available" ], "properties": { "organization_id": { "type": "string", "format": "uuid", "description": "UUIDv7, lowercase canonical form." }, "mode": { "anyOf": [ { "type": "string", "enum": [ "test" ] }, { "type": "string", "enum": [ "live" ] } ] }, "billing_state": { "anyOf": [ { "type": "string", "enum": [ "free" ] }, { "type": "string", "enum": [ "active" ] }, { "type": "string", "enum": [ "canceling" ] }, { "type": "string", "enum": [ "grace" ] }, { "type": "string", "enum": [ "restricted" ] } ] }, "plan": { "anyOf": [ { "type": "object", "required": [ "plan_key", "catalog_version", "source" ], "properties": { "plan_key": { "type": "string" }, "catalog_version": { "type": "string" }, "source": { "anyOf": [ { "type": "string", "enum": [ "override" ] }, { "type": "string", "enum": [ "subscription" ] }, { "type": "string", "enum": [ "trial" ] }, { "type": "string", "enum": [ "default" ] } ] } }, "additionalProperties": false, "description": "The plan whose limits admission enforces now." }, { "type": "null" } ] }, "subscription": { "anyOf": [ { "type": "object", "required": [ "id", "status", "plan_key", "catalog_version", "current_period_start", "current_period_end", "cancel_at_period_end", "cancel_at", "canceled_at", "ended_at", "past_due_since", "grace_until", "restricted", "restriction_reason", "entitlement_state", "synced_at" ], "properties": { "id": { "type": "string", "format": "uuid", "description": "UUIDv7, lowercase canonical form." }, "status": { "type": "string", "description": "Stripe status: incomplete, incomplete_expired, trialing, active, past_due, canceled, unpaid, paused." }, "plan_key": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "catalog_version": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "current_period_start": { "anyOf": [ { "type": "string", "format": "date-time", "description": "RFC 3339 UTC timestamp with Z." }, { "type": "null" } ] }, "current_period_end": { "anyOf": [ { "type": "string", "format": "date-time", "description": "RFC 3339 UTC timestamp with Z." }, { "type": "null" } ] }, "cancel_at_period_end": { "type": "boolean" }, "cancel_at": { "anyOf": [ { "type": "string", "format": "date-time", "description": "RFC 3339 UTC timestamp with Z." }, { "type": "null" } ] }, "canceled_at": { "anyOf": [ { "type": "string", "format": "date-time", "description": "RFC 3339 UTC timestamp with Z." }, { "type": "null" } ] }, "ended_at": { "anyOf": [ { "type": "string", "format": "date-time", "description": "RFC 3339 UTC timestamp with Z." }, { "type": "null" } ] }, "past_due_since": { "anyOf": [ { "type": "string", "format": "date-time", "description": "RFC 3339 UTC timestamp with Z." }, { "type": "null" } ] }, "grace_until": { "anyOf": [ { "type": "string", "format": "date-time", "description": "RFC 3339 UTC timestamp with Z." }, { "type": "null" } ] }, "restricted": { "type": "boolean" }, "restriction_reason": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "entitlement_state": { "anyOf": [ { "type": "string", "enum": [ "none" ] }, { "type": "string", "enum": [ "active" ] }, { "type": "string", "enum": [ "grace" ] }, { "type": "string", "enum": [ "restricted" ] } ] }, "synced_at": { "type": "string", "format": "date-time", "description": "RFC 3339 UTC timestamp with Z." } }, "additionalProperties": false }, { "type": "null" } ] }, "restrictions": { "type": "object", "properties": {}, "additionalProperties": true }, "pending_checkout": { "anyOf": [ { "type": "object", "required": [ "id", "plan_key", "status", "expires_at" ], "properties": { "id": { "type": "string", "format": "uuid", "description": "UUIDv7, lowercase canonical form." }, "plan_key": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "status": { "type": "string" }, "expires_at": { "anyOf": [ { "type": "string", "format": "date-time", "description": "RFC 3339 UTC timestamp with Z." }, { "type": "null" } ] } }, "additionalProperties": false }, { "type": "null" } ] }, "purchase_available": { "type": "boolean", "description": "Checkout/portal are configured in this environment." } }, "additionalProperties": false } } } }, "4XX": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "examples": { "not_found": { "$ref": "#/components/examples/not_found" }, "rate_limited": { "$ref": "#/components/examples/rate_limited" }, "validation_failed": { "$ref": "#/components/examples/validation_failed" } } } } }, "5XX": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" }, "examples": { "not_found": { "$ref": "#/components/examples/not_found" }, "rate_limited": { "$ref": "#/components/examples/rate_limited" }, "validation_failed": { "$ref": "#/components/examples/validation_failed" } } } } } } } } }, "components": { "securitySchemes": { "apiKey": { "type": "http", "scheme": "bearer", "bearerFormat": "sfk__" } }, "schemas": { "ErrorBody": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "request_id", "retryable" ], "properties": { "code": { "type": "string", "enum": [ "bad_request", "token_invalid", "unauthenticated", "invalid_credentials", "entitlement_required", "allowance_exhausted", "quota_exceeded", "forbidden", "mfa_required", "email_unverified", "csrf_failed", "step_up_required", "not_found", "conflict", "stale_epoch", "payload_too_large", "unsupported_media_type", "validation_failed", "idempotency_mismatch", "rate_limited", "internal_error", "capacity_pending", "dependency_unavailable" ], "description": "Closed set of error codes (docs/INTEGRATION_CONTRACTS.md)." }, "message": { "type": "string", "description": "Safe, human-readable text." }, "request_id": { "type": "string" }, "retryable": { "type": "boolean" }, "operation_id": { "type": "string", "format": "uuid", "description": "UUIDv7, lowercase canonical form." }, "details": { "type": "object", "properties": {}, "additionalProperties": true } }, "additionalProperties": false } }, "additionalProperties": false }, "Operation": { "type": "object", "required": [ "id", "kind", "state", "workspace_id", "created_at", "updated_at" ], "properties": { "id": { "type": "string", "format": "uuid", "description": "UUIDv7, lowercase canonical form." }, "kind": { "type": "string", "enum": [ "open", "suspend", "resume", "fork", "snapshot", "restore", "delete", "move", "resize", "volume_create", "volume_attach", "volume_detach", "volume_delete", "reset", "layer_snapshot" ] }, "state": { "type": "string", "enum": [ "queued", "capacity_pending", "running", "succeeded", "failed", "canceled" ] }, "workspace_id": { "anyOf": [ { "type": "string", "format": "uuid", "description": "UUIDv7, lowercase canonical form." }, { "type": "null" } ] }, "volume_id": { "anyOf": [ { "type": "string", "format": "uuid", "description": "UUIDv7, lowercase canonical form." }, { "type": "null" } ] }, "created_at": { "type": "string", "format": "date-time", "description": "RFC 3339 UTC timestamp with Z." }, "updated_at": { "type": "string", "format": "date-time", "description": "RFC 3339 UTC timestamp with Z." }, "started_at": { "anyOf": [ { "type": "string", "format": "date-time", "description": "RFC 3339 UTC timestamp with Z." }, { "type": "null" } ], "description": "When the cell started executing the operation: set once, in the transaction that first moves it to `running`, and never changed afterwards (it stays set if the operation later returns to `capacity_pending`, e.g. when a host rejects the start). null while the operation is `queued`, or `capacity_pending` before it ever ran, and on an operation canceled before it started. An operation the cell finishes without running it (e.g. `dependency_failed`) gets started_at = completed_at. created_at to started_at is the time queued; started_at to completed_at the time running." }, "completed_at": { "anyOf": [ { "type": "string", "format": "date-time", "description": "RFC 3339 UTC timestamp with Z." }, { "type": "null" } ] }, "state_reason": { "anyOf": [ { "type": "string", "description": "Closed reason code while waiting (e.g. capacity_pending: no_ready_host)." }, { "type": "null" } ] }, "input": { "type": "object", "properties": {}, "additionalProperties": true }, "error": { "type": "object", "properties": {}, "additionalProperties": true }, "result": { "type": "object", "properties": {}, "additionalProperties": true } }, "additionalProperties": false }, "WorkspaceLifetime": { "type": "string", "enum": [ "persistent", "session" ], "description": "persistent: kept until deleted (default). session: discarded when the session ends (close(), idle timeout or draft discard;)." }, "DiskLayout": { "type": "string", "enum": [ "legacy", "layered" ], "description": "legacy: one disk (template copy + changes). layered: the template chain read-only plus a workspace layer holding only the changes. Immutable." }, "WorkspacePurpose": { "type": "string", "enum": [ "standard", "template_draft", "template_test" ], "description": "standard, template_draft (a template’s dev-mode draft) or template_test (a test instance of a draft state;)." }, "UpdatePolicy": { "type": "string", "enum": [ "pinned", "auto" ], "description": "Reserved (T2). Always `pinned` in T1: a workspace stays on its template version; `auto` is refused with 422 update_policy_not_available." }, "WorkspaceOrigin": { "anyOf": [ { "type": "object", "required": [ "kind", "workspace_id" ], "properties": { "kind": { "type": "string", "enum": [ "fork" ] }, "workspace_id": { "type": "string", "format": "uuid", "description": "UUIDv7, lowercase canonical form." } }, "additionalProperties": false, "description": "Forked from workspace_id." }, { "type": "object", "required": [ "kind", "template_id", "draft_workspace_id", "checkpoint_id", "captured_at" ], "properties": { "kind": { "type": "string", "enum": [ "draft_state" ] }, "template_id": { "type": "string", "format": "uuid", "description": "UUIDv7, lowercase canonical form." }, "draft_workspace_id": { "type": "string", "format": "uuid", "description": "UUIDv7, lowercase canonical form." }, "checkpoint_id": { "anyOf": [ { "type": "string", "format": "uuid", "description": "UUIDv7, lowercase canonical form." }, { "type": "null" } ] }, "captured_at": { "anyOf": [ { "type": "string", "format": "date-time", "description": "RFC 3339 UTC timestamp with Z." }, { "type": "null" } ] } }, "additionalProperties": false, "description": "A test instance of a draft state: the draft and the captured state (checkpoint_id is null until the cell placed an instance whose state is being captured)." }, { "type": "object", "required": [ "kind", "template_id", "version" ], "properties": { "kind": { "type": "string", "enum": [ "template_version" ] }, "template_id": { "type": "string", "format": "uuid", "description": "UUIDv7, lowercase canonical form." }, "version": { "type": "integer", "minimum": 1 } }, "additionalProperties": false, "description": "A test instance of a template version, published or not: a fresh workspace on that version." } ], "description": "Where the workspace’s disk came from; null for a workspace opened from its template." }, "WorkspaceMode": { "type": "string", "enum": [ "processful", "file_first" ], "description": "processful (default): one VM keeps processes, memory and files between calls; it can be suspended, resumed and forked. file_first: the state is a versioned file tree (tree_revision); there is no VM between executions, each exec runs in a fresh VM and publishes the changed files as the next revision, nothing but files survives an execution. A file-first workspace is ready (running) from creation and is never suspended; suspend, resume, snapshot, fork, reset, save-as-template, volumes and idle policies are 409 not_supported_for_mode. Immutable." }, "TemplateDefaults": { "type": "object", "required": [ "lifetime", "idle_timeout_seconds", "limits", "egress", "agent_tools", "update_policy" ], "properties": { "lifetime": { "$ref": "#/components/schemas/WorkspaceLifetime" }, "idle_timeout_seconds": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "limits": { "anyOf": [ { "type": "object", "required": [ "cpu_millis_ceiling", "memory_mib_ceiling", "disk_gib" ], "properties": { "cpu_millis_ceiling": { "type": "integer", "minimum": 1, "maximum": 1000000 }, "memory_mib_ceiling": { "type": "integer", "minimum": 1, "maximum": 16777216 }, "disk_gib": { "type": "integer", "minimum": 1, "maximum": 1000000 } }, "additionalProperties": false, "description": "Ceilings of every admission of a workspace of the version (clamped, never refused;)." }, { "type": "null" } ] }, "egress": { "anyOf": [ { "$ref": "#/components/schemas/TemplateEgressDefault" }, { "type": "null" } ] }, "agent_tools": { "type": "null" }, "update_policy": { "type": "null" } }, "additionalProperties": false, "description": "Manifest v2 `defaults`. Versions without them report the T1 defaults." }, "TemplateEgressDefault": { "type": "object", "required": [ "mode", "allow_hosts" ], "properties": { "mode": { "type": "string", "enum": [ "allowlist", "none" ] }, "allow_hosts": { "type": "array", "items": { "type": "string" }, "description": "Normalized (lowercase, sorted); empty for none." } }, "additionalProperties": false, "description": "The template’s workspace network ceiling: the cell intersects it with the effective egress policy." }, "TemplateInput": { "type": "object", "required": [ "kind", "required", "default", "description" ], "properties": { "kind": { "type": "string", "enum": [ "text", "secret" ] }, "required": { "type": "boolean" }, "default": { "anyOf": [ { "type": "string", "description": "Text inputs only." }, { "type": "null" } ] }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "additionalProperties": false, "description": "An open-time input: text (a value passed to open) or secret (a stored secret of the same name, bound to the workspace)." }, "TemplateStartCommand": { "type": "object", "required": [ "name", "when", "run", "user", "cwd", "timeout_seconds" ], "properties": { "name": { "type": "string" }, "when": { "type": "string", "enum": [ "create", "boot", "resume" ] }, "run": { "type": "string" }, "user": { "anyOf": [ { "type": "string", "description": "null: the template’s default user." }, { "type": "null" } ] }, "cwd": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "timeout_seconds": { "type": "integer" } }, "additionalProperties": false, "description": "A start command: create = new workspace layer, boot = every cold boot, resume = every memory restore." }, "TemplateService": { "type": "object", "required": [ "run", "user", "cwd", "restart", "ready", "ready_timeout_seconds" ], "properties": { "run": { "type": "string" }, "user": { "anyOf": [ { "type": "string", "description": "null: the template’s default user." }, { "type": "null" } ] }, "cwd": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "restart": { "type": "string", "enum": [ "always", "on_failure", "never" ] }, "ready": { "anyOf": [ { "anyOf": [ { "type": "object", "required": [ "port" ], "properties": { "port": { "type": "integer" } }, "additionalProperties": false }, { "type": "object", "required": [ "command" ], "properties": { "command": { "type": "string" } }, "additionalProperties": false } ] }, { "type": "null" } ] }, "ready_timeout_seconds": { "type": "integer" } }, "additionalProperties": false, "description": "A process the guest keeps running; ready before open() returns." }, "TemplateSettings": { "type": "object", "required": [ "env", "inputs", "start", "services", "defaults" ], "properties": { "env": { "type": "object", "additionalProperties": { "type": "string" } }, "inputs": { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/TemplateInput" } }, "start": { "type": "array", "items": { "$ref": "#/components/schemas/TemplateStartCommand" } }, "services": { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/TemplateService" } }, "defaults": { "$ref": "#/components/schemas/TemplateDefaults" } }, "additionalProperties": false, "description": "What a workspace of the version gets when it opens, every key present. `env` is the effective template env (a recipe v2 version: its languages’ build env, then its own env)." }, "TemplateSettingsInput": { "description": "What a workspace of the version gets when it opens (). Omitted fields are empty (recipes do not carry settings forward).", "type": "object", "additionalProperties": false, "properties": { "env": { "description": "Template environment for every exec, PTY, start command and service (below text inputs and the call's env).", "type": "object", "maxProperties": 128, "propertyNames": { "description": "POSIX-style environment name; the SHARDFLUX_ prefix is reserved.", "type": "string", "pattern": "^[A-Za-z_][A-Za-z0-9_]{0,127}$" }, "additionalProperties": { "description": "At most 4096 bytes (UTF-8), no NUL, CR or LF.", "type": "string", "maxLength": 4096, "pattern": "^[^\\x00\\r\\n]*$" } }, "inputs": { "description": "Open-time inputs. text: a value passed to open({inputs}); secret: a stored secret of the same name, bound to the workspace.", "type": "object", "maxProperties": 32, "propertyNames": { "description": "POSIX-style environment name; the SHARDFLUX_ prefix is reserved.", "type": "string", "pattern": "^[A-Za-z_][A-Za-z0-9_]{0,127}$" }, "additionalProperties": { "type": "object", "required": [ "kind" ], "additionalProperties": false, "properties": { "kind": { "enum": [ "text", "secret" ] }, "required": { "type": "boolean", "description": "Default: false." }, "default": { "description": "text inputs only.", "oneOf": [ { "type": "null" }, { "description": "At most 4096 bytes (UTF-8), no NUL, CR or LF.", "type": "string", "maxLength": 4096, "pattern": "^[^\\x00\\r\\n]*$" } ] }, "description": { "oneOf": [ { "type": "null" }, { "type": "string", "maxLength": 500 } ] } } } }, "start": { "description": "Start commands: create = on a new workspace layer, boot = every cold boot, resume = every memory restore.", "type": "array", "maxItems": 32, "items": { "type": "object", "required": [ "name", "when", "run" ], "additionalProperties": false, "properties": { "name": { "type": "string", "pattern": "^[a-z0-9][a-z0-9._-]{0,62}$" }, "when": { "enum": [ "create", "boot", "resume" ] }, "run": { "description": "Shell script run by /bin/bash -euo pipefail -c; 1..65536 bytes, no NUL.", "type": "string", "minLength": 1, "maxLength": 65536, "pattern": "^[^\\x00]+$" }, "user": { "oneOf": [ { "type": "null" }, { "description": "A user name or numeric uid of the template (the builder's userRE without a group).", "type": "string", "pattern": "^([a-z_][a-z0-9_-]{0,31}|[0-9]{1,10})$" } ], "description": "Absent or null: the template's default user." }, "cwd": { "oneOf": [ { "type": "null" }, { "description": "Absolute, clean (no '.', '..', '//' or trailing '/'), at most 1024 bytes.", "type": "string", "minLength": 2, "maxLength": 1024, "pattern": "^(/[^/\\x00\\r\\n]+)+$" } ] }, "timeout_seconds": { "type": "integer", "minimum": 1, "maximum": 1800, "description": "Default: 300." } } } }, "services": { "description": "Processes kept running by the guest; ready before open() returns.", "type": "object", "maxProperties": 16, "propertyNames": { "type": "string", "pattern": "^[a-z][a-z0-9-]{0,62}$" }, "additionalProperties": { "type": "object", "required": [ "run" ], "additionalProperties": false, "properties": { "run": { "description": "Shell script run by /bin/bash -euo pipefail -c; 1..65536 bytes, no NUL.", "type": "string", "minLength": 1, "maxLength": 65536, "pattern": "^[^\\x00]+$" }, "user": { "oneOf": [ { "type": "null" }, { "description": "A user name or numeric uid of the template (the builder's userRE without a group).", "type": "string", "pattern": "^([a-z_][a-z0-9_-]{0,31}|[0-9]{1,10})$" } ], "description": "Absent or null: the template's default user." }, "cwd": { "oneOf": [ { "type": "null" }, { "description": "Absolute, clean (no '.', '..', '//' or trailing '/'), at most 1024 bytes.", "type": "string", "minLength": 2, "maxLength": 1024, "pattern": "^(/[^/\\x00\\r\\n]+)+$" } ] }, "restart": { "enum": [ "always", "on_failure", "never" ], "description": "Default: \"on_failure\"." }, "ready": { "oneOf": [ { "type": "null" }, { "type": "object", "required": [ "port" ], "additionalProperties": false, "properties": { "port": { "type": "integer", "minimum": 1, "maximum": 65535 } } }, { "type": "object", "required": [ "command" ], "additionalProperties": false, "properties": { "command": { "description": "Shell script run by /bin/bash -euo pipefail -c; 1..65536 bytes, no NUL.", "type": "string", "minLength": 1, "maxLength": 65536, "pattern": "^[^\\x00]+$" } } } ] }, "ready_timeout_seconds": { "type": "integer", "minimum": 1, "maximum": 600, "description": "Default: 60." } } } }, "defaults": { "description": "Manifest defaults (). agent_tools and update_policy stay reserved (null).", "type": "object", "additionalProperties": false, "properties": { "lifetime": { "enum": [ "persistent", "session" ] }, "idle_timeout_seconds": { "oneOf": [ { "type": "null" }, { "type": "integer", "minimum": 60, "maximum": 86400 } ] }, "limits": { "description": "Ceilings enforced at admission (clamped).", "oneOf": [ { "type": "null" }, { "type": "object", "required": [ "cpu_millis_ceiling", "memory_mib_ceiling", "disk_gib" ], "additionalProperties": false, "properties": { "cpu_millis_ceiling": { "type": "integer", "minimum": 1, "maximum": 1000000 }, "memory_mib_ceiling": { "type": "integer", "minimum": 1, "maximum": 16777216 }, "disk_gib": { "type": "integer", "minimum": 1, "maximum": 1000000 } } } ] }, "egress": { "description": "Workspace network ceiling: internet = no ceiling (stored as null), allowlist = only allow_hosts (TCP, any port), none = no egress.", "oneOf": [ { "type": "null" }, { "type": "object", "required": [ "mode" ], "additionalProperties": false, "properties": { "mode": { "enum": [ "internet", "allowlist", "none" ] }, "allow_hosts": { "type": "array", "maxItems": 50, "items": { "description": "A public DNS name (example.com) or one-label wildcard (*.example.com); no IP literals, no localhost/.local/.internal.", "type": "string", "minLength": 1, "maxLength": 255, "pattern": "^(\\*\\.)?[A-Za-z0-9](?:[A-Za-z0-9-]{0,61}[A-Za-z0-9])?(?:\\.[A-Za-z0-9](?:[A-Za-z0-9-]{0,61}[A-Za-z0-9])?)+\\.?$" } } } } ] }, "agent_tools": { "type": "null" }, "update_policy": { "type": "null" } } } } }, "TemplateRecipeV1": { "type": "object", "required": [ "base", "dockerfile" ], "properties": { "base": { "type": "string", "minLength": 3, "maxLength": 120, "pattern": "^[a-z0-9](?:[a-z0-9._-]{0,98}[a-z0-9])?@[1-9][0-9]{0,8}$", "description": "`