diff --git a/openapi/public.json b/openapi/public.json index b433ecd..f72e024 100644 --- a/openapi/public.json +++ b/openapi/public.json @@ -63,7 +63,7 @@ }, { "name": "Installs", - "description": "Product installation and render operations." + "description": "Installation and render operations." }, { "name": "Machines", @@ -151,26 +151,923 @@ } }, "schemas": { - "ComputeMachine": { + "SnippetList": { "type": "object", "properties": { - "provider_id": { - "type": "string", - "example": "compute://abc123" + "data": { + "type": "array", + "items": { + "$ref": "#/components/schemas/Snippet" + } }, - "node_name": { - "type": "string", - "example": "worker-xl8r2" + "has_more": { + "type": "boolean", + "description": "True if more items exist after this page." }, - "status": { + "next_cursor": { "type": "string", - "example": "provisioning" + "nullable": true, + "description": "Opaque cursor for the next page, or null if no more pages." } }, "required": [ - "provider_id", - "node_name", - "status" + "data", + "has_more", + "next_cursor" + ] + }, + "Snippet": { + "oneOf": [ + { + "type": "object", + "properties": { + "id": { + "type": "string", + "minLength": 1, + "maxLength": 54, + "example": "snp_j572abc123def456" + }, + "html_url": { + "type": "string", + "maxLength": 2048, + "format": "uri", + "description": "Absolute dashboard URL for this resource. OUTPUT_ONLY.", + "example": "https://akua.dev/dashboards/snippets/snp_j572abc123def456" + }, + "name": { + "type": "string", + "example": "Cluster Resource Audit" + }, + "description": { + "type": "string", + "nullable": true, + "example": "Checks resource requests and limits" + }, + "code": { + "type": "string", + "example": "async () => { ... }", + "description": "Async JavaScript function body executed in a sandboxed runtime. Has access to platform.request() for API calls." + }, + "display_type": { + "type": "string", + "enum": [ + "table", + "stat", + "json", + "logs", + "timeseries" + ], + "description": "Controls how the snippet result is rendered in dashboard widgets", + "example": "table" + }, + "inputs": { + "type": "array", + "items": { + "oneOf": [ + { + "type": "object", + "properties": { + "key": { + "type": "string", + "pattern": "^[a-z][a-z0-9_]{0,31}$" + }, + "label": { + "type": "string", + "minLength": 1, + "maxLength": 100 + }, + "description": { + "type": "string", + "maxLength": 500 + }, + "required": { + "type": "boolean" + }, + "kind": { + "type": "string", + "enum": [ + "time_range" + ] + }, + "default": { + "type": "object", + "properties": { + "from": { + "type": "integer" + }, + "to": { + "type": "integer" + } + }, + "required": [ + "from", + "to" + ], + "additionalProperties": false + } + }, + "required": [ + "key", + "label", + "kind" + ], + "additionalProperties": false + }, + { + "type": "object", + "properties": { + "key": { + "type": "string", + "pattern": "^[a-z][a-z0-9_]{0,31}$" + }, + "label": { + "type": "string", + "minLength": 1, + "maxLength": 100 + }, + "description": { + "type": "string", + "maxLength": 500 + }, + "required": { + "type": "boolean" + }, + "kind": { + "type": "string", + "enum": [ + "resource" + ] + }, + "resource": { + "type": "string", + "enum": [ + "cluster", + "install", + "product", + "package", + "region" + ] + }, + "default": { + "anyOf": [ + { + "type": "string", + "maxLength": 255 + }, + { + "type": "array", + "items": { + "type": "string", + "maxLength": 255 + }, + "minItems": 1, + "maxItems": 100 + } + ] + }, + "multiple": { + "type": "boolean" + } + }, + "required": [ + "key", + "label", + "kind", + "resource" + ], + "additionalProperties": false + }, + { + "type": "object", + "properties": { + "key": { + "type": "string", + "pattern": "^[a-z][a-z0-9_]{0,31}$" + }, + "label": { + "type": "string", + "minLength": 1, + "maxLength": 100 + }, + "description": { + "type": "string", + "maxLength": 500 + }, + "required": { + "type": "boolean" + }, + "kind": { + "type": "string", + "enum": [ + "enum" + ] + }, + "options": { + "type": "array", + "items": { + "type": "string", + "minLength": 1, + "maxLength": 100 + }, + "minItems": 1, + "maxItems": 100 + }, + "default": { + "type": "string", + "minLength": 1, + "maxLength": 100 + } + }, + "required": [ + "key", + "label", + "kind", + "options" + ], + "additionalProperties": false + }, + { + "type": "object", + "properties": { + "key": { + "type": "string", + "pattern": "^[a-z][a-z0-9_]{0,31}$" + }, + "label": { + "type": "string", + "minLength": 1, + "maxLength": 100 + }, + "description": { + "type": "string", + "maxLength": 500 + }, + "required": { + "type": "boolean" + }, + "kind": { + "type": "string", + "enum": [ + "boolean" + ] + }, + "default": { + "type": "boolean" + } + }, + "required": [ + "key", + "label", + "kind" + ], + "additionalProperties": false + }, + { + "type": "object", + "properties": { + "key": { + "type": "string", + "pattern": "^[a-z][a-z0-9_]{0,31}$" + }, + "label": { + "type": "string", + "minLength": 1, + "maxLength": 100 + }, + "description": { + "type": "string", + "maxLength": 500 + }, + "required": { + "type": "boolean" + }, + "kind": { + "type": "string", + "enum": [ + "number" + ] + }, + "min": { + "type": "number" + }, + "max": { + "type": "number" + }, + "default": { + "type": "number" + } + }, + "required": [ + "key", + "label", + "kind" + ], + "additionalProperties": false + }, + { + "type": "object", + "properties": { + "key": { + "type": "string", + "pattern": "^[a-z][a-z0-9_]{0,31}$" + }, + "label": { + "type": "string", + "minLength": 1, + "maxLength": 100 + }, + "description": { + "type": "string", + "maxLength": 500 + }, + "required": { + "type": "boolean" + }, + "kind": { + "type": "string", + "enum": [ + "text" + ] + }, + "default": { + "type": "string", + "maxLength": 500 + }, + "max_length": { + "type": "integer", + "minimum": 1, + "maximum": 500 + } + }, + "required": [ + "key", + "label", + "kind" + ], + "additionalProperties": false + } + ] + }, + "maxItems": 16 + }, + "visibility": { + "type": "string", + "enum": [ + "workspace", + "session" + ], + "description": "Whether the snippet is reusable workspace state or scoped to an agent session." + }, + "origin": { + "type": "string", + "enum": [ + "user", + "agent", + "system" + ], + "description": "Who authored the snippet descriptor." + }, + "agent_session_id": { + "type": "string", + "nullable": true, + "minLength": 1, + "maxLength": 54 + }, + "agent_turn_id": { + "type": "string", + "nullable": true, + "minLength": 1, + "maxLength": 54 + }, + "purpose": { + "type": "string", + "enum": [ + "general", + "prepared_action", + "reactive_read", + "widget" + ] + }, + "workspace_id": { + "type": "string", + "minLength": 1, + "maxLength": 53, + "example": "ws_j572abc123def456" + }, + "created_by": { + "type": "string", + "description": "User ID of the snippet creator" + }, + "created_at": { + "type": "integer", + "minimum": 0, + "description": "Unix timestamp (seconds)" + }, + "updated_at": { + "type": "integer", + "minimum": 0, + "description": "Unix timestamp (seconds)" + }, + "archived_at": { + "type": "integer", + "nullable": true, + "minimum": 0, + "description": "Unix timestamp (seconds) when this snippet was archived, or null while active" + }, + "etag": { + "type": "string" + }, + "result_contract_version": { + "nullable": true + }, + "result_type": { + "nullable": true + }, + "default_visualization": { + "nullable": true + } + }, + "required": [ + "id", + "html_url", + "name", + "description", + "code", + "display_type", + "inputs", + "visibility", + "origin", + "agent_session_id", + "agent_turn_id", + "purpose", + "workspace_id", + "created_by", + "created_at", + "updated_at", + "archived_at", + "etag", + "result_contract_version", + "result_type", + "default_visualization" + ] + }, + { + "type": "object", + "properties": { + "id": { + "type": "string", + "minLength": 1, + "maxLength": 54, + "example": "snp_j572abc123def456" + }, + "html_url": { + "type": "string", + "maxLength": 2048, + "format": "uri", + "description": "Absolute dashboard URL for this resource. OUTPUT_ONLY.", + "example": "https://akua.dev/dashboards/snippets/snp_j572abc123def456" + }, + "name": { + "type": "string", + "example": "Cluster Resource Audit" + }, + "description": { + "type": "string", + "nullable": true, + "example": "Checks resource requests and limits" + }, + "code": { + "type": "string", + "example": "async () => { ... }", + "description": "Async JavaScript function body executed in a sandboxed runtime. Has access to platform.request() for API calls." + }, + "display_type": { + "type": "string", + "enum": [ + "table", + "stat", + "json", + "logs", + "timeseries" + ], + "description": "Controls how the snippet result is rendered in dashboard widgets", + "example": "table" + }, + "inputs": { + "type": "array", + "items": { + "oneOf": [ + { + "type": "object", + "properties": { + "key": { + "type": "string", + "pattern": "^[a-z][a-z0-9_]{0,31}$" + }, + "label": { + "type": "string", + "minLength": 1, + "maxLength": 100 + }, + "description": { + "type": "string", + "maxLength": 500 + }, + "required": { + "type": "boolean" + }, + "kind": { + "type": "string", + "enum": [ + "time_range" + ] + }, + "default": { + "type": "object", + "properties": { + "from": { + "type": "integer" + }, + "to": { + "type": "integer" + } + }, + "required": [ + "from", + "to" + ], + "additionalProperties": false + } + }, + "required": [ + "key", + "label", + "kind" + ], + "additionalProperties": false + }, + { + "type": "object", + "properties": { + "key": { + "type": "string", + "pattern": "^[a-z][a-z0-9_]{0,31}$" + }, + "label": { + "type": "string", + "minLength": 1, + "maxLength": 100 + }, + "description": { + "type": "string", + "maxLength": 500 + }, + "required": { + "type": "boolean" + }, + "kind": { + "type": "string", + "enum": [ + "resource" + ] + }, + "resource": { + "type": "string", + "enum": [ + "cluster", + "install", + "product", + "package", + "region" + ] + }, + "default": { + "anyOf": [ + { + "type": "string", + "maxLength": 255 + }, + { + "type": "array", + "items": { + "type": "string", + "maxLength": 255 + }, + "minItems": 1, + "maxItems": 100 + } + ] + }, + "multiple": { + "type": "boolean" + } + }, + "required": [ + "key", + "label", + "kind", + "resource" + ], + "additionalProperties": false + }, + { + "type": "object", + "properties": { + "key": { + "type": "string", + "pattern": "^[a-z][a-z0-9_]{0,31}$" + }, + "label": { + "type": "string", + "minLength": 1, + "maxLength": 100 + }, + "description": { + "type": "string", + "maxLength": 500 + }, + "required": { + "type": "boolean" + }, + "kind": { + "type": "string", + "enum": [ + "enum" + ] + }, + "options": { + "type": "array", + "items": { + "type": "string", + "minLength": 1, + "maxLength": 100 + }, + "minItems": 1, + "maxItems": 100 + }, + "default": { + "type": "string", + "minLength": 1, + "maxLength": 100 + } + }, + "required": [ + "key", + "label", + "kind", + "options" + ], + "additionalProperties": false + }, + { + "type": "object", + "properties": { + "key": { + "type": "string", + "pattern": "^[a-z][a-z0-9_]{0,31}$" + }, + "label": { + "type": "string", + "minLength": 1, + "maxLength": 100 + }, + "description": { + "type": "string", + "maxLength": 500 + }, + "required": { + "type": "boolean" + }, + "kind": { + "type": "string", + "enum": [ + "boolean" + ] + }, + "default": { + "type": "boolean" + } + }, + "required": [ + "key", + "label", + "kind" + ], + "additionalProperties": false + }, + { + "type": "object", + "properties": { + "key": { + "type": "string", + "pattern": "^[a-z][a-z0-9_]{0,31}$" + }, + "label": { + "type": "string", + "minLength": 1, + "maxLength": 100 + }, + "description": { + "type": "string", + "maxLength": 500 + }, + "required": { + "type": "boolean" + }, + "kind": { + "type": "string", + "enum": [ + "number" + ] + }, + "min": { + "type": "number" + }, + "max": { + "type": "number" + }, + "default": { + "type": "number" + } + }, + "required": [ + "key", + "label", + "kind" + ], + "additionalProperties": false + }, + { + "type": "object", + "properties": { + "key": { + "type": "string", + "pattern": "^[a-z][a-z0-9_]{0,31}$" + }, + "label": { + "type": "string", + "minLength": 1, + "maxLength": 100 + }, + "description": { + "type": "string", + "maxLength": 500 + }, + "required": { + "type": "boolean" + }, + "kind": { + "type": "string", + "enum": [ + "text" + ] + }, + "default": { + "type": "string", + "maxLength": 500 + }, + "max_length": { + "type": "integer", + "minimum": 1, + "maximum": 500 + } + }, + "required": [ + "key", + "label", + "kind" + ], + "additionalProperties": false + } + ] + }, + "maxItems": 16 + }, + "visibility": { + "type": "string", + "enum": [ + "workspace", + "session" + ], + "description": "Whether the snippet is reusable workspace state or scoped to an agent session." + }, + "origin": { + "type": "string", + "enum": [ + "user", + "agent", + "system" + ], + "description": "Who authored the snippet descriptor." + }, + "agent_session_id": { + "type": "string", + "nullable": true, + "minLength": 1, + "maxLength": 54 + }, + "agent_turn_id": { + "type": "string", + "nullable": true, + "minLength": 1, + "maxLength": 54 + }, + "purpose": { + "type": "string", + "enum": [ + "general", + "prepared_action", + "reactive_read", + "widget" + ] + }, + "workspace_id": { + "type": "string", + "minLength": 1, + "maxLength": 53, + "example": "ws_j572abc123def456" + }, + "created_by": { + "type": "string", + "description": "User ID of the snippet creator" + }, + "created_at": { + "type": "integer", + "minimum": 0, + "description": "Unix timestamp (seconds)" + }, + "updated_at": { + "type": "integer", + "minimum": 0, + "description": "Unix timestamp (seconds)" + }, + "archived_at": { + "type": "integer", + "nullable": true, + "minimum": 0, + "description": "Unix timestamp (seconds) when this snippet was archived, or null while active" + }, + "etag": { + "type": "string" + }, + "result_contract_version": { + "type": "number", + "enum": [ + 1 + ] + }, + "result_type": { + "type": "string", + "enum": [ + "scalar", + "timeseries", + "categorical", + "table", + "status_list", + "logs", + "json" + ] + }, + "default_visualization": { + "type": "string", + "enum": [ + "stat", + "sparkline", + "line", + "area", + "bar", + "donut", + "table", + "status_list", + "logs", + "json" + ] + } + }, + "required": [ + "id", + "html_url", + "name", + "description", + "code", + "display_type", + "inputs", + "visibility", + "origin", + "agent_session_id", + "agent_turn_id", + "purpose", + "workspace_id", + "created_by", + "created_at", + "updated_at", + "archived_at", + "etag", + "result_contract_version", + "result_type", + "default_visualization" + ] + } ] }, "ApiErrorResponse": { @@ -236,423 +1133,29 @@ "message" ] }, - "ComputeError": { + "SnippetUsageList": { "type": "object", "properties": { - "type": { - "type": "string", - "example": "InsufficientCapacity", - "description": "Machine-readable error type (e.g., InsufficientCapacity, NodeClaimNotFound)" + "data": { + "type": "array", + "items": { + "$ref": "#/components/schemas/SnippetUsage" + } }, - "message": { + "has_more": { + "type": "boolean", + "description": "True if more items exist after this page." + }, + "next_cursor": { "type": "string", - "example": "cpx31 out of stock in fsn1" + "nullable": true, + "description": "Opaque cursor for the next page, or null if no more pages." } }, "required": [ - "type", - "message" - ] - }, - "InstanceType": { - "type": "object", - "properties": { - "name": { - "type": "string", - "example": "cpx31" - }, - "arch": { - "type": "string", - "example": "amd64" - }, - "cpu": { - "type": "number", - "example": 4 - }, - "memory_mib": { - "type": "number", - "example": 8192 - }, - "storage_mib": { - "type": "number", - "example": 163840 - }, - "price_per_hour": { - "type": "number", - "example": 0.0208 - }, - "available": { - "type": "boolean", - "example": true - }, - "zone": { - "type": "string", - "example": "fsn1" - }, - "capacity_type": { - "type": "string", - "example": "on-demand" - } - }, - "required": [ - "name", - "arch", - "cpu", - "memory_mib", - "storage_mib", - "price_per_hour", - "available" - ] - }, - "DriftResult": { - "type": "object", - "properties": { - "drifted": { - "type": "boolean" - }, - "reason": { - "type": "string" - } - }, - "required": [ - "drifted" - ] - }, - "Suspension": { - "type": "object", - "properties": { - "id": { - "type": "string" - }, - "workspace_id": { - "type": "string" - }, - "cluster_id": { - "type": "string" - }, - "server_type": { - "type": "string", - "example": "cpx31" - }, - "location": { - "type": "string", - "example": "fsn1" - }, - "hostname": { - "type": "string", - "example": "node-xl8r2abc" - }, - "reason": { - "type": "string", - "enum": [ - "manual", - "downgrade" - ] - }, - "provider_suspend_data": { - "type": "object", - "properties": { - "provider": { - "type": "string" - }, - "snapshot_id": { - "type": "number" - }, - "size_gb": { - "type": "number" - } - }, - "required": [ - "provider", - "snapshot_id", - "size_gb" - ] - }, - "monthly_cost_cents": { - "type": "number" - }, - "expires_at": { - "type": "number" - }, - "created_at": { - "type": "number" - } - }, - "required": [ - "id", - "workspace_id", - "cluster_id", - "server_type", - "location", - "hostname", - "reason", - "provider_suspend_data", - "monthly_cost_cents", - "expires_at", - "created_at" - ] - }, - "ComputeConfigList": { - "type": "object", - "properties": { - "data": { - "type": "array", - "items": { - "$ref": "#/components/schemas/ComputeConfig" - } - }, - "has_more": { - "type": "boolean", - "description": "True if more items exist after this page." - }, - "next_cursor": { - "type": "string", - "nullable": true, - "description": "Opaque cursor for the next page, or null if no more pages." - } - }, - "required": [ - "data", - "has_more", - "next_cursor" - ] - }, - "ComputeConfig": { - "type": "object", - "properties": { - "id": { - "type": "string" - }, - "name": { - "type": "string" - }, - "provider": { - "type": "string", - "example": "hcloud" - }, - "provider_config": { - "type": "object", - "properties": { - "provider": { - "type": "string" - }, - "region": { - "type": "string" - }, - "image": { - "type": "string" - }, - "machine_type_filter": { - "type": "string", - "nullable": true, - "description": "Glob pattern to filter instance types (e.g., \"cx*\", \"cpx*\")" - } - }, - "required": [ - "provider", - "region", - "image", - "machine_type_filter" - ] - }, - "secret_id": { - "type": "string", - "nullable": true - }, - "created_at": { - "type": "number" - } - }, - "required": [ - "id", - "name", - "provider", - "provider_config", - "secret_id", - "created_at" - ] - }, - "CreatedComputeConfig": { - "type": "object", - "properties": { - "id": { - "type": "string" - } - }, - "required": [ - "id" - ] - }, - "SnippetList": { - "type": "object", - "properties": { - "data": { - "type": "array", - "items": { - "$ref": "#/components/schemas/Snippet" - } - }, - "has_more": { - "type": "boolean", - "description": "True if more items exist after this page." - }, - "next_cursor": { - "type": "string", - "nullable": true, - "description": "Opaque cursor for the next page, or null if no more pages." - } - }, - "required": [ - "data", - "has_more", - "next_cursor" - ] - }, - "Snippet": { - "type": "object", - "properties": { - "id": { - "type": "string", - "minLength": 1, - "maxLength": 54, - "example": "snp_j572abc123def456" - }, - "html_url": { - "type": "string", - "maxLength": 2048, - "format": "uri", - "description": "Absolute dashboard URL for this resource. OUTPUT_ONLY.", - "example": "https://akua.dev/dashboards/snippets/snp_j572abc123def456" - }, - "name": { - "type": "string", - "example": "Cluster Resource Audit" - }, - "description": { - "type": "string", - "nullable": true, - "example": "Checks resource requests and limits" - }, - "code": { - "type": "string", - "example": "async () => { ... }", - "description": "Async JavaScript function body executed in a sandboxed runtime. Has access to platform.request() for API calls." - }, - "display_type": { - "type": "string", - "enum": [ - "table", - "stat", - "json", - "logs" - ], - "description": "Controls how the snippet result is rendered in dashboard widgets", - "example": "table" - }, - "visibility": { - "type": "string", - "enum": [ - "workspace", - "session" - ], - "description": "Whether the snippet is reusable workspace state or scoped to an agent session." - }, - "origin": { - "type": "string", - "enum": [ - "user", - "agent", - "system" - ], - "description": "Who authored the snippet descriptor." - }, - "agent_session_id": { - "type": "string", - "nullable": true, - "minLength": 1, - "maxLength": 54 - }, - "agent_turn_id": { - "type": "string", - "nullable": true, - "minLength": 1, - "maxLength": 54 - }, - "purpose": { - "type": "string", - "enum": [ - "general", - "prepared_action", - "reactive_read", - "widget" - ] - }, - "workspace_id": { - "type": "string", - "minLength": 1, - "maxLength": 53, - "example": "ws_j572abc123def456" - }, - "created_by": { - "type": "string", - "description": "User ID of the snippet creator" - }, - "created_at": { - "type": "integer", - "minimum": 0, - "description": "Unix timestamp (seconds)" - }, - "updated_at": { - "type": "integer", - "minimum": 0, - "description": "Unix timestamp (seconds)" - }, - "etag": { - "type": "string" - } - }, - "required": [ - "id", - "html_url", - "name", - "description", - "code", - "display_type", - "visibility", - "origin", - "agent_session_id", - "agent_turn_id", - "purpose", - "workspace_id", - "created_by", - "created_at", - "updated_at", - "etag" - ] - }, - "SnippetUsageList": { - "type": "object", - "properties": { - "data": { - "type": "array", - "items": { - "$ref": "#/components/schemas/SnippetUsage" - } - }, - "has_more": { - "type": "boolean", - "description": "True if more items exist after this page." - }, - "next_cursor": { - "type": "string", - "nullable": true, - "description": "Opaque cursor for the next page, or null if no more pages." - } - }, - "required": [ - "data", - "has_more", - "next_cursor" + "data", + "has_more", + "next_cursor" ] }, "SnippetUsage": { @@ -709,1172 +1212,11656 @@ ] }, "ExecuteSnippetResponse": { - "type": "object", - "properties": { - "result": { - "nullable": true - }, - "error": { - "type": "string" - }, - "stats": { + "anyOf": [ + { "type": "object", "properties": { - "cpu_time_ms": { - "type": "number" + "result": { + "nullable": true }, - "wall_time_ms": { - "type": "number" + "error": { + "type": "string" }, - "heap_used_bytes": { - "type": "number" + "stats": { + "type": "object", + "properties": { + "cpu_time_ms": { + "type": "number" + }, + "wall_time_ms": { + "type": "number" + }, + "heap_used_bytes": { + "type": "number" + } + }, + "required": [ + "cpu_time_ms", + "wall_time_ms", + "heap_used_bytes" + ] } }, "required": [ - "cpu_time_ms", - "wall_time_ms", - "heap_used_bytes" - ] - } - }, - "required": [ - "stats" - ] - }, - "ExecuteSnippetBody": { - "type": "object", - "properties": { - "code": { - "type": "string", - "minLength": 1, - "maxLength": 50000, - "description": "Async JavaScript function body. Executed in a sandboxed runtime with access to platform.request()." - } - }, - "required": [ - "code" - ], - "additionalProperties": false - }, - "SnippetRun": { - "type": "object", - "properties": { - "id": { - "type": "string", - "minLength": 1, - "maxLength": 54 - }, - "snippet_id": { - "type": "string", - "minLength": 1, - "maxLength": 54 - }, - "agent_session_id": { - "type": "string", - "nullable": true, - "minLength": 1, - "maxLength": 54 - }, - "agent_turn_id": { - "type": "string", - "nullable": true, - "minLength": 1, - "maxLength": 54 - }, - "state": { - "type": "string", - "enum": [ - "succeeded", - "failed", - "timed_out" + "stats" ], - "description": "Terminal run state in past participle form." - }, - "overrides": { - "type": "object", - "additionalProperties": { - "nullable": true - } - }, - "output": { - "nullable": true - }, - "error": { - "$ref": "#/components/schemas/SnippetRunError" - }, - "duration_ms": { - "type": "number" - }, - "created_at": { - "type": "integer", - "minimum": 0, - "description": "Unix timestamp (seconds)" - }, - "etag": { - "type": "string" - } - }, - "required": [ - "id", - "snippet_id", - "agent_session_id", - "agent_turn_id", - "state", - "duration_ms", - "created_at", - "etag" - ] - }, - "SnippetRunError": { - "type": "object", - "properties": { - "code": { - "type": "string" - }, - "message": { - "type": "string" + "additionalProperties": false }, - "details": { - "nullable": true - } - }, - "required": [ - "code", - "message" - ] - }, - "CreateSnippetRunBody": { - "type": "object", - "properties": { - "overrides": { + { "type": "object", - "additionalProperties": { - "nullable": true - } - }, - "agent_turn_id": { - "type": "string", - "minLength": 1, - "maxLength": 54 - } - }, - "additionalProperties": false - }, - "SnippetRunList": { - "type": "object", - "properties": { - "data": { - "type": "array", - "items": { - "$ref": "#/components/schemas/SnippetRun" - } - }, - "has_more": { - "type": "boolean", - "description": "True if more items exist after this page." - }, - "next_cursor": { - "type": "string", - "nullable": true, - "description": "Opaque cursor for the next page, or null if no more pages." - } - }, - "required": [ - "data", - "has_more", - "next_cursor" - ] - }, - "DashboardList": { - "type": "object", - "properties": { - "data": { - "type": "array", - "items": { - "$ref": "#/components/schemas/Dashboard" - } - }, - "has_more": { - "type": "boolean", - "description": "True if more items exist after this page." - }, - "next_cursor": { - "type": "string", - "nullable": true, - "description": "Opaque cursor for the next page, or null if no more pages." - } - }, - "required": [ - "data", - "has_more", - "next_cursor" - ] - }, - "Dashboard": { - "type": "object", - "properties": { - "id": { - "type": "string", - "example": "j572abc123def456" - }, - "html_url": { - "type": "string", - "maxLength": 2048, - "format": "uri", - "description": "Absolute dashboard URL for this resource. OUTPUT_ONLY.", - "example": "https://akua.dev/dashboards/dash_j572abc123def456" - }, - "name": { - "type": "string", - "example": "Cluster Overview" - }, - "description": { - "type": "string", - "nullable": true, - "description": "Optional dashboard description" - }, - "workspace_id": { - "type": "string" - }, - "widgets": { - "type": "array", - "items": { - "$ref": "#/components/schemas/Widget" - }, - "description": "Output-only denormalized widget list for dashboard read models." - }, - "created_by": { - "type": "string", - "description": "User ID of the dashboard creator" - }, - "created_at": { - "type": "integer", - "minimum": 0, - "description": "Unix timestamp (seconds)" - }, - "updated_at": { - "type": "integer", - "minimum": 0, - "description": "Unix timestamp (seconds)" - }, - "etag": { - "type": "string" - } - }, - "required": [ - "id", - "html_url", - "name", - "description", - "workspace_id", - "widgets", - "created_by", - "created_at", - "updated_at", - "etag" - ] - }, - "Widget": { - "type": "object", - "properties": { - "id": { - "type": "string", - "minLength": 1, - "maxLength": 54 - }, - "dashboard_id": { - "type": "string", - "minLength": 1, - "maxLength": 55 - }, - "widget_type": { - "type": "string", - "enum": [ - "snippet" - ], - "description": "Dashboard widget descriptor type. `snippet` is the first concrete type; future agent-authored widgets extend this field." - }, - "snippet_id": { - "type": "string", - "minLength": 1, - "maxLength": 54 - }, - "position": { - "type": "integer" - }, - "col_span": { - "anyOf": [ - { + "properties": { + "result_contract_version": { "type": "number", "enum": [ 1 ] }, - { - "type": "number", - "enum": [ - 2 - ] - }, - { - "type": "number", + "result_type": { + "type": "string", "enum": [ - 3 + "scalar", + "timeseries", + "categorical", + "table", + "status_list", + "logs", + "json" ] }, - { - "type": "number", - "enum": [ - 4 - ] - } - ] - }, - "display_type": { - "type": "string", - "nullable": true, - "enum": [ - "table", - "stat", - "json", - "logs", - null - ], - "description": "Controls how the snippet result is rendered in dashboard widgets" - }, - "created_at": { - "type": "integer", - "minimum": 0, - "description": "Unix timestamp (seconds)" - }, - "updated_at": { - "type": "integer", - "minimum": 0, - "description": "Unix timestamp (seconds)" - }, - "etag": { - "type": "string" - } - }, - "required": [ - "id", - "dashboard_id", - "widget_type", - "snippet_id", - "position", - "col_span", - "display_type", - "created_at", - "updated_at", - "etag" - ] - }, - "WidgetList": { - "type": "object", - "properties": { - "data": { - "type": "array", - "items": { - "$ref": "#/components/schemas/Widget" - } - }, - "has_more": { - "type": "boolean", - "description": "True if more items exist after this page." - }, - "next_cursor": { - "type": "string", - "nullable": true, - "description": "Opaque cursor for the next page, or null if no more pages." - } - }, - "required": [ - "data", - "has_more", - "next_cursor" - ] - }, - "OperationEnvelope": { - "type": "object", - "properties": { - "operation_id": { - "type": "string", - "minLength": 1, - "maxLength": 53 - } - }, - "required": [ - "operation_id" - ] - }, - "MachineList": { - "type": "object", - "properties": { - "data": { - "type": "array", - "items": { - "$ref": "#/components/schemas/Machine" - } - }, - "has_more": { - "type": "boolean", - "description": "True if more items exist after this page." - }, - "next_cursor": { - "type": "string", - "nullable": true, - "description": "Opaque cursor for the next page, or null if no more pages." - } - }, - "required": [ - "data", - "has_more", - "next_cursor" - ] - }, - "Machine": { - "type": "object", - "properties": { - "id": { - "type": "string", - "minLength": 1, - "maxLength": 54 - }, - "workspace_id": { - "type": "string", - "minLength": 1, - "maxLength": 53 - }, - "cluster_id": { - "type": "string", - "minLength": 1, - "maxLength": 54 - }, - "compute_config_id": { - "type": "string", - "minLength": 1, - "maxLength": 54 - }, - "provider_id": { - "type": "string", - "description": "Provider URI identifier in canonical form (for example, compute://hcloud/server-1234).", - "example": "compute://hcloud/server-1234" - }, - "provider_resource": { - "type": "object", - "properties": { - "identity_kind": { + "default_visualization": { "type": "string", "enum": [ - "recyclable", - "persistent" + "stat", + "sparkline", + "line", + "area", + "bar", + "donut", + "table", + "status_list", + "logs", + "json" ] }, - "public_ip": { - "type": "string", - "nullable": true - }, - "floating_ip": { - "type": "object", - "properties": { - "id": { - "type": "string" + "result": { + "oneOf": [ + { + "type": "object", + "properties": { + "contract_version": { + "type": "number", + "enum": [ + 1 + ] + }, + "type": { + "type": "string", + "enum": [ + "scalar" + ] + }, + "value": { + "anyOf": [ + { + "type": "string", + "maxLength": 16384 + }, + { + "type": "number" + }, + { + "type": "boolean" + }, + { + "nullable": true + } + ] + }, + "unit": { + "type": "string", + "minLength": 1, + "maxLength": 64 + }, + "definition": { + "type": "string", + "minLength": 1, + "maxLength": 500 + }, + "timestamp": { + "type": "integer", + "minimum": 0 + }, + "history": { + "type": "array", + "items": { + "type": "object", + "properties": { + "timestamp": { + "type": "integer", + "minimum": 0 + }, + "value": { + "type": "number", + "nullable": true + } + }, + "required": [ + "timestamp", + "value" + ], + "additionalProperties": false + }, + "maxItems": 2000 + } + }, + "required": [ + "contract_version", + "type", + "value" + ], + "additionalProperties": false }, - "ipv4": { - "type": "string" - } - }, - "required": [ - "id", - "ipv4" - ] - } - }, - "required": [ - "identity_kind", - "public_ip" - ] - }, - "name": { - "type": "string" - }, - "state": { - "type": "string", - "enum": [ - "ACTIVE", - "PROVISIONING", - "SUSPENDING", - "SUSPENDED", - "RESUMING", - "DELETING" - ], - "description": "Machine lifecycle state." - }, - "reconciling": { - "type": "boolean" - }, - "current_suspension": { - "type": "object", - "properties": { - "event_id": { - "type": "string", - "minLength": 1, - "maxLength": 54 - }, - "snapshot_ref": { - "type": "object", - "properties": { - "provider": { - "type": "string", - "enum": [ - "hcloud" - ] + { + "type": "object", + "properties": { + "contract_version": { + "type": "number", + "enum": [ + 1 + ] + }, + "type": { + "type": "string", + "enum": [ + "timeseries" + ] + }, + "series": { + "type": "array", + "items": { + "type": "object", + "properties": { + "key": { + "type": "string", + "minLength": 1, + "maxLength": 64, + "pattern": "^[a-z][a-z0-9]*(?:_[a-z0-9]+)*$" + }, + "label": { + "type": "string", + "minLength": 1, + "maxLength": 200 + }, + "unit": { + "type": "string", + "minLength": 1, + "maxLength": 64 + }, + "definition": { + "type": "string", + "minLength": 1, + "maxLength": 500 + } + }, + "required": [ + "key", + "label" + ], + "additionalProperties": false + }, + "minItems": 1, + "maxItems": 8 + }, + "points": { + "type": "array", + "items": { + "type": "object", + "properties": { + "timestamp": { + "type": "integer", + "minimum": 0 + }, + "values": { + "type": "array", + "items": { + "type": "number", + "nullable": true + }, + "maxItems": 8 + } + }, + "required": [ + "timestamp", + "values" + ], + "additionalProperties": false + }, + "maxItems": 2000 + } + }, + "required": [ + "contract_version", + "type", + "series", + "points" + ], + "additionalProperties": false }, - "snapshot_id": { - "type": "integer" + { + "type": "object", + "properties": { + "contract_version": { + "type": "number", + "enum": [ + 1 + ] + }, + "type": { + "type": "string", + "enum": [ + "categorical" + ] + }, + "series": { + "type": "array", + "items": { + "type": "object", + "properties": { + "key": { + "type": "string", + "minLength": 1, + "maxLength": 64, + "pattern": "^[a-z][a-z0-9]*(?:_[a-z0-9]+)*$" + }, + "label": { + "type": "string", + "minLength": 1, + "maxLength": 200 + }, + "unit": { + "type": "string", + "minLength": 1, + "maxLength": 64 + }, + "definition": { + "type": "string", + "minLength": 1, + "maxLength": 500 + } + }, + "required": [ + "key", + "label" + ], + "additionalProperties": false + }, + "minItems": 1, + "maxItems": 8 + }, + "categories": { + "type": "array", + "items": { + "type": "object", + "properties": { + "key": { + "type": "string", + "minLength": 1, + "maxLength": 64, + "pattern": "^[a-z][a-z0-9]*(?:_[a-z0-9]+)*$" + }, + "label": { + "type": "string", + "minLength": 1, + "maxLength": 200 + } + }, + "required": [ + "key", + "label" + ], + "additionalProperties": false + }, + "maxItems": 100 + }, + "values": { + "type": "array", + "items": { + "type": "array", + "items": { + "type": "number", + "nullable": true + }, + "maxItems": 8 + }, + "maxItems": 100 + } + }, + "required": [ + "contract_version", + "type", + "series", + "categories", + "values" + ], + "additionalProperties": false }, - "size_gb": { - "type": "number" - } - }, - "required": [ - "provider", - "snapshot_id", - "size_gb" - ] - }, - "expires_at": { - "type": "integer", - "minimum": 0, - "description": "Unix timestamp (seconds)" - }, - "monthly_cost_cents": { - "type": "integer" - }, - "reason": { - "type": "string", - "enum": [ - "manual", - "downgrade" - ] - } - }, - "required": [ - "event_id", - "snapshot_ref", - "expires_at", - "monthly_cost_cents", - "reason" - ] - }, - "created_at": { - "type": "integer", - "minimum": 0, - "description": "Unix timestamp (seconds)" - }, - "updated_at": { - "type": "integer", - "minimum": 0, - "description": "Unix timestamp (seconds)" - }, - "etag": { - "type": "string" - } - }, - "required": [ - "id", - "workspace_id", - "cluster_id", - "compute_config_id", - "provider_id", - "provider_resource", - "state", - "reconciling", - "created_at", - "updated_at", - "etag" - ] - }, - "SuspendMachineBody": { - "type": "object", - "properties": { - "reason": { - "type": "string", - "enum": [ - "manual", - "downgrade" - ] - } - }, - "additionalProperties": false - }, - "ResumeMachineBody": { - "type": "object", - "properties": {}, - "additionalProperties": false - }, - "DriftReport": { - "type": "object", - "properties": { - "id": { - "type": "string", - "description": "Drift report ID." - }, - "machine_id": { - "type": "string", - "minLength": 1, - "maxLength": 54 - }, - "state": { - "type": "string", - "enum": [ - "in_sync", - "drifted" - ], - "description": "Machine drift comparison state." - }, - "delta": { - "type": "object", - "additionalProperties": { - "nullable": true - } - }, - "provider_snapshot": { - "type": "object", - "properties": { - "provider": { + { + "type": "object", + "properties": { + "contract_version": { + "type": "number", + "enum": [ + 1 + ] + }, + "type": { + "type": "string", + "enum": [ + "table" + ] + }, + "columns": { + "type": "array", + "items": { + "oneOf": [ + { + "type": "object", + "properties": { + "key": { + "type": "string", + "minLength": 1, + "maxLength": 64, + "pattern": "^[a-z][a-z0-9]*(?:_[a-z0-9]+)*$" + }, + "label": { + "type": "string", + "minLength": 1, + "maxLength": 200 + }, + "definition": { + "type": "string", + "minLength": 1, + "maxLength": 500 + }, + "kind": { + "type": "string", + "enum": [ + "text" + ] + } + }, + "required": [ + "key", + "label", + "kind" + ], + "additionalProperties": false + }, + { + "type": "object", + "properties": { + "key": { + "type": "string", + "minLength": 1, + "maxLength": 64, + "pattern": "^[a-z][a-z0-9]*(?:_[a-z0-9]+)*$" + }, + "label": { + "type": "string", + "minLength": 1, + "maxLength": 200 + }, + "definition": { + "type": "string", + "minLength": 1, + "maxLength": 500 + }, + "kind": { + "type": "string", + "enum": [ + "number" + ] + }, + "unit": { + "type": "string", + "minLength": 1, + "maxLength": 64 + } + }, + "required": [ + "key", + "label", + "kind" + ], + "additionalProperties": false + }, + { + "type": "object", + "properties": { + "key": { + "type": "string", + "minLength": 1, + "maxLength": 64, + "pattern": "^[a-z][a-z0-9]*(?:_[a-z0-9]+)*$" + }, + "label": { + "type": "string", + "minLength": 1, + "maxLength": 200 + }, + "definition": { + "type": "string", + "minLength": 1, + "maxLength": 500 + }, + "kind": { + "type": "string", + "enum": [ + "boolean" + ] + } + }, + "required": [ + "key", + "label", + "kind" + ], + "additionalProperties": false + }, + { + "type": "object", + "properties": { + "key": { + "type": "string", + "minLength": 1, + "maxLength": 64, + "pattern": "^[a-z][a-z0-9]*(?:_[a-z0-9]+)*$" + }, + "label": { + "type": "string", + "minLength": 1, + "maxLength": 200 + }, + "definition": { + "type": "string", + "minLength": 1, + "maxLength": 500 + }, + "kind": { + "type": "string", + "enum": [ + "timestamp" + ] + } + }, + "required": [ + "key", + "label", + "kind" + ], + "additionalProperties": false + }, + { + "type": "object", + "properties": { + "key": { + "type": "string", + "minLength": 1, + "maxLength": 64, + "pattern": "^[a-z][a-z0-9]*(?:_[a-z0-9]+)*$" + }, + "label": { + "type": "string", + "minLength": 1, + "maxLength": 200 + }, + "definition": { + "type": "string", + "minLength": 1, + "maxLength": 500 + }, + "kind": { + "type": "string", + "enum": [ + "link" + ] + } + }, + "required": [ + "key", + "label", + "kind" + ], + "additionalProperties": false + } + ] + }, + "minItems": 1, + "maxItems": 32 + }, + "rows": { + "type": "array", + "items": { + "type": "array", + "items": { + "anyOf": [ + { + "type": "string", + "maxLength": 16384 + }, + { + "type": "number" + }, + { + "type": "boolean" + }, + { + "nullable": true + } + ] + }, + "maxItems": 32 + }, + "maxItems": 500 + } + }, + "required": [ + "contract_version", + "type", + "columns", + "rows" + ], + "additionalProperties": false + }, + { + "type": "object", + "properties": { + "contract_version": { + "type": "number", + "enum": [ + 1 + ] + }, + "type": { + "type": "string", + "enum": [ + "status_list" + ] + }, + "items": { + "type": "array", + "items": { + "type": "object", + "properties": { + "key": { + "type": "string", + "minLength": 1, + "maxLength": 64, + "pattern": "^[a-z][a-z0-9]*(?:_[a-z0-9]+)*$" + }, + "label": { + "type": "string", + "minLength": 1, + "maxLength": 200 + }, + "severity": { + "type": "string", + "enum": [ + "info", + "success", + "warning", + "critical", + "unknown" + ] + }, + "detail": { + "type": "string", + "maxLength": 16384 + }, + "timestamp": { + "type": "integer", + "minimum": 0 + }, + "link": { + "type": "string", + "minLength": 1, + "maxLength": 2048 + } + }, + "required": [ + "key", + "label", + "severity" + ], + "additionalProperties": false + }, + "maxItems": 200 + } + }, + "required": [ + "contract_version", + "type", + "items" + ], + "additionalProperties": false + }, + { + "type": "object", + "properties": { + "contract_version": { + "type": "number", + "enum": [ + 1 + ] + }, + "type": { + "type": "string", + "enum": [ + "logs" + ] + }, + "entries": { + "type": "array", + "items": { + "type": "object", + "properties": { + "message": { + "type": "string", + "minLength": 1, + "maxLength": 4096 + }, + "timestamp": { + "type": "integer", + "minimum": 0 + }, + "level": { + "type": "string", + "minLength": 1, + "maxLength": 32 + } + }, + "required": [ + "message" + ], + "additionalProperties": false + }, + "maxItems": 1000 + } + }, + "required": [ + "contract_version", + "type", + "entries" + ], + "additionalProperties": false + }, + { + "type": "object", + "properties": { + "contract_version": { + "type": "number", + "enum": [ + 1 + ] + }, + "type": { + "type": "string", + "enum": [ + "json" + ] + }, + "value": { + "nullable": true + } + }, + "required": [ + "contract_version", + "type", + "value" + ], + "additionalProperties": false + } + ] + }, + "error": { "type": "string" }, - "raw_attrs": { + "stats": { "type": "object", - "additionalProperties": { - "nullable": true - } + "properties": { + "cpu_time_ms": { + "type": "number" + }, + "wall_time_ms": { + "type": "number" + }, + "heap_used_bytes": { + "type": "number" + } + }, + "required": [ + "cpu_time_ms", + "wall_time_ms", + "heap_used_bytes" + ] } }, "required": [ - "provider", - "raw_attrs" - ] - }, - "etag": { - "type": "string" - }, - "created_at": { - "type": "integer", - "minimum": 0, - "description": "Unix timestamp (seconds)" - }, - "started_at": { - "type": "integer", - "minimum": 0, - "description": "Unix timestamp (seconds)" - }, - "expires_at": { - "type": "integer", - "minimum": 0, - "description": "Unix timestamp (seconds)" + "result_contract_version", + "result_type", + "default_visualization", + "stats" + ], + "additionalProperties": false } - }, - "required": [ - "id", - "machine_id", - "state", - "etag", - "created_at", - "started_at", - "expires_at" ] }, - "DriftReportList": { + "ExecuteSnippetBody": { "type": "object", "properties": { - "data": { - "type": "array", - "items": { - "$ref": "#/components/schemas/DriftReport" - } - }, - "has_more": { - "type": "boolean", - "description": "True if more items exist after this page." - }, - "next_cursor": { + "code": { "type": "string", - "nullable": true, - "description": "Opaque cursor for the next page, or null if no more pages." - } - }, - "required": [ - "data", - "has_more", - "next_cursor" - ] - }, - "SuspensionEventList": { - "type": "object", - "properties": { - "data": { - "type": "array", - "items": { - "$ref": "#/components/schemas/SuspensionEvent" - } - }, - "has_more": { - "type": "boolean", - "description": "True if more items exist after this page." + "minLength": 1, + "maxLength": 50000, + "description": "Async JavaScript function body. Executed in a sandboxed runtime with access to platform.request()." }, - "next_cursor": { - "type": "string", - "nullable": true, - "description": "Opaque cursor for the next page, or null if no more pages." + "inputs": { + "type": "object", + "additionalProperties": { + "nullable": true + } } }, "required": [ - "data", - "has_more", - "next_cursor" - ] + "code" + ], + "additionalProperties": false }, - "SuspensionEvent": { + "ExecuteStoredSnippetBody": { "type": "object", "properties": { - "id": { - "type": "string", - "minLength": 1, - "maxLength": 54 - }, - "machine_id": { - "type": "string", - "minLength": 1, - "maxLength": 54 - }, - "state": { - "type": "string", - "enum": [ - "in_progress", - "completed", - "resumed", - "expired" - ], - "description": "Suspension-event lifecycle state." - }, - "started_at": { - "type": "integer", - "minimum": 0, - "description": "Unix timestamp (seconds)" - }, - "resumed_at": { - "type": "integer", - "minimum": 0, - "description": "Unix timestamp (seconds)" - }, - "expires_at": { - "type": "integer", - "minimum": 0, - "description": "Unix timestamp (seconds)" - }, - "snapshot_ref": { + "inputs": { "type": "object", - "properties": { - "provider": { - "type": "string", - "enum": [ - "hcloud" - ] - }, - "snapshot_id": { - "type": "integer" - }, - "size_gb": { - "type": "number" - } - }, - "required": [ - "provider", - "snapshot_id", - "size_gb" - ] - }, - "monthly_cost_cents": { - "type": "integer" - }, - "total_cost_cents": { - "type": "integer" - }, - "reason": { - "type": "string", - "enum": [ - "manual", - "downgrade" - ] - }, - "etag": { - "type": "string" + "additionalProperties": { + "nullable": true + } } }, - "required": [ - "id", - "machine_id", - "state", - "started_at", - "expires_at", - "snapshot_ref", - "monthly_cost_cents", - "reason", - "etag" - ] + "additionalProperties": false }, - "CredentialScope": { + "CreateSnippetBody": { "oneOf": [ { "type": "object", "properties": { - "kind": { + "name": { "type": "string", - "enum": [ - "system" - ], - "description": "Use system-managed provider credentials." - } - }, - "required": [ - "kind" - ], - "additionalProperties": false - }, - { - "type": "object", - "properties": { - "kind": { + "minLength": 1, + "maxLength": 100, + "example": "Cluster Resource Audit" + }, + "description": { "type": "string", - "enum": [ - "byom" - ] + "maxLength": 500, + "description": "Optional human-readable description" }, - "secret_id": { + "code": { "type": "string", "minLength": 1, - "maxLength": 54 + "maxLength": 50000, + "description": "Async JavaScript function body. Executed in a sandboxed runtime with access to platform.request()." }, - "secret_version_id": { + "display_type": { "type": "string", - "minLength": 1, - "maxLength": 55 - } - }, - "required": [ - "kind", - "secret_id" - ], - "additionalProperties": false - } - ] - }, - "ProductList": { - "type": "object", - "properties": { - "data": { - "type": "array", - "items": { - "$ref": "#/components/schemas/Product" - } - }, - "has_more": { - "type": "boolean", - "description": "True if more items exist after this page." - }, - "next_cursor": { - "type": "string", - "nullable": true, - "description": "Opaque cursor for the next page, or null if no more pages." - } - }, - "required": [ - "data", - "has_more", - "next_cursor" - ] - }, - "Product": { - "type": "object", - "properties": { - "id": { - "type": "string", - "minLength": 1, - "maxLength": 55, - "example": "prod_j572abc123def456" - }, - "html_url": { - "type": "string", - "maxLength": 2048, - "format": "uri", - "description": "Absolute dashboard URL for this resource. OUTPUT_ONLY.", - "example": "https://akua.dev/products/prod_j572abc123def456" - }, - "name": { - "type": "string", - "example": "PostgreSQL Managed" - }, - "workspace_id": { - "type": "string", - "minLength": 1, - "maxLength": 53 - }, - "package": { - "type": "object", - "properties": { - "id": { + "enum": [ + "table", + "stat", + "json", + "logs", + "timeseries" + ], + "description": "Controls how the snippet result is rendered in dashboard widgets" + }, + "inputs": { + "type": "array", + "items": { + "oneOf": [ + { + "type": "object", + "properties": { + "key": { + "type": "string", + "pattern": "^[a-z][a-z0-9_]{0,31}$" + }, + "label": { + "type": "string", + "minLength": 1, + "maxLength": 100 + }, + "description": { + "type": "string", + "maxLength": 500 + }, + "required": { + "type": "boolean" + }, + "kind": { + "type": "string", + "enum": [ + "time_range" + ] + }, + "default": { + "type": "object", + "properties": { + "from": { + "type": "integer" + }, + "to": { + "type": "integer" + } + }, + "required": [ + "from", + "to" + ], + "additionalProperties": false + } + }, + "required": [ + "key", + "label", + "kind" + ], + "additionalProperties": false + }, + { + "type": "object", + "properties": { + "key": { + "type": "string", + "pattern": "^[a-z][a-z0-9_]{0,31}$" + }, + "label": { + "type": "string", + "minLength": 1, + "maxLength": 100 + }, + "description": { + "type": "string", + "maxLength": 500 + }, + "required": { + "type": "boolean" + }, + "kind": { + "type": "string", + "enum": [ + "resource" + ] + }, + "resource": { + "type": "string", + "enum": [ + "cluster", + "install", + "product", + "package", + "region" + ] + }, + "default": { + "anyOf": [ + { + "type": "string", + "maxLength": 255 + }, + { + "type": "array", + "items": { + "type": "string", + "maxLength": 255 + }, + "minItems": 1, + "maxItems": 100 + } + ] + }, + "multiple": { + "type": "boolean" + } + }, + "required": [ + "key", + "label", + "kind", + "resource" + ], + "additionalProperties": false + }, + { + "type": "object", + "properties": { + "key": { + "type": "string", + "pattern": "^[a-z][a-z0-9_]{0,31}$" + }, + "label": { + "type": "string", + "minLength": 1, + "maxLength": 100 + }, + "description": { + "type": "string", + "maxLength": 500 + }, + "required": { + "type": "boolean" + }, + "kind": { + "type": "string", + "enum": [ + "enum" + ] + }, + "options": { + "type": "array", + "items": { + "type": "string", + "minLength": 1, + "maxLength": 100 + }, + "minItems": 1, + "maxItems": 100 + }, + "default": { + "type": "string", + "minLength": 1, + "maxLength": 100 + } + }, + "required": [ + "key", + "label", + "kind", + "options" + ], + "additionalProperties": false + }, + { + "type": "object", + "properties": { + "key": { + "type": "string", + "pattern": "^[a-z][a-z0-9_]{0,31}$" + }, + "label": { + "type": "string", + "minLength": 1, + "maxLength": 100 + }, + "description": { + "type": "string", + "maxLength": 500 + }, + "required": { + "type": "boolean" + }, + "kind": { + "type": "string", + "enum": [ + "boolean" + ] + }, + "default": { + "type": "boolean" + } + }, + "required": [ + "key", + "label", + "kind" + ], + "additionalProperties": false + }, + { + "type": "object", + "properties": { + "key": { + "type": "string", + "pattern": "^[a-z][a-z0-9_]{0,31}$" + }, + "label": { + "type": "string", + "minLength": 1, + "maxLength": 100 + }, + "description": { + "type": "string", + "maxLength": 500 + }, + "required": { + "type": "boolean" + }, + "kind": { + "type": "string", + "enum": [ + "number" + ] + }, + "min": { + "type": "number" + }, + "max": { + "type": "number" + }, + "default": { + "type": "number" + } + }, + "required": [ + "key", + "label", + "kind" + ], + "additionalProperties": false + }, + { + "type": "object", + "properties": { + "key": { + "type": "string", + "pattern": "^[a-z][a-z0-9_]{0,31}$" + }, + "label": { + "type": "string", + "minLength": 1, + "maxLength": 100 + }, + "description": { + "type": "string", + "maxLength": 500 + }, + "required": { + "type": "boolean" + }, + "kind": { + "type": "string", + "enum": [ + "text" + ] + }, + "default": { + "type": "string", + "maxLength": 500 + }, + "max_length": { + "type": "integer", + "minimum": 1, + "maximum": 500 + } + }, + "required": [ + "key", + "label", + "kind" + ], + "additionalProperties": false + } + ] + }, + "maxItems": 16 + }, + "visibility": { "type": "string", - "minLength": 1, - "maxLength": 54, - "example": "pkg_j572abc123def456" + "enum": [ + "workspace", + "session" + ], + "description": "Whether the snippet is reusable workspace state or scoped to an agent session." }, - "version_pin": { - "$ref": "#/components/schemas/PackageVersionPin" + "origin": { + "type": "string", + "enum": [ + "user", + "agent", + "system" + ], + "description": "Who authored the snippet descriptor." }, - "default_version_id": { + "agent_session_id": { "type": "string", - "nullable": true, "minLength": 1, - "maxLength": 55, - "description": "Concrete PackageVersion currently resolved by the version pin, or null when latest has no published version yet." - } - }, - "required": [ - "id", - "version_pin", - "default_version_id" - ], - "additionalProperties": false, - "description": "Reference to the Package backing this product. Fetch full details via `GET /v1/packages/{id}`." - }, - "custom_image": { - "type": "string", - "description": "Custom display image URL — overrides the package logo on customer-facing pages" - }, - "custom_description": { - "type": "string", - "description": "Custom display description — overrides the package description" - }, - "marketplace": { - "$ref": "#/components/schemas/ProductMarketplaceState" - }, - "created_at": { - "type": "integer", - "minimum": 0, - "description": "Unix timestamp (seconds)" - }, - "updated_at": { - "type": "integer", - "minimum": 0, - "description": "Unix timestamp (seconds)" - }, - "etag": { - "type": "string" - }, - "state": { - "type": "string", - "enum": [ - "active", - "archived" - ], - "description": "Product lifecycle state." - }, - "archived_at": { - "type": "integer", - "minimum": 0, - "description": "When the product was archived, expressed as Unix seconds since epoch." - }, - "archive_reason": { - "type": "string", - "description": "Reason supplied by the seller when archiving." - } - }, - "required": [ - "id", - "html_url", - "name", - "workspace_id", - "package", - "marketplace", - "created_at", - "updated_at", - "etag", - "state" - ] - }, - "PackageVersionPin": { - "oneOf": [ - { - "type": "object", - "properties": { - "kind": { + "maxLength": 54 + }, + "agent_turn_id": { + "type": "string", + "minLength": 1, + "maxLength": 54 + }, + "purpose": { "type": "string", "enum": [ - "latest" + "general", + "prepared_action", + "reactive_read", + "widget" ] } }, "required": [ - "kind" + "name", + "code", + "display_type" ], "additionalProperties": false }, { "type": "object", "properties": { - "kind": { + "name": { + "type": "string", + "minLength": 1, + "maxLength": 100, + "example": "Cluster Resource Audit" + }, + "description": { + "type": "string", + "maxLength": 500, + "description": "Optional human-readable description" + }, + "code": { + "type": "string", + "minLength": 1, + "maxLength": 50000, + "description": "Async JavaScript function body. Executed in a sandboxed runtime with access to platform.request()." + }, + "display_type": { "type": "string", "enum": [ - "pinned" - ] + "table", + "stat", + "json", + "logs", + "timeseries" + ], + "description": "Controls how the snippet result is rendered in dashboard widgets" }, - "version": { + "inputs": { + "type": "array", + "items": { + "oneOf": [ + { + "type": "object", + "properties": { + "key": { + "type": "string", + "pattern": "^[a-z][a-z0-9_]{0,31}$" + }, + "label": { + "type": "string", + "minLength": 1, + "maxLength": 100 + }, + "description": { + "type": "string", + "maxLength": 500 + }, + "required": { + "type": "boolean" + }, + "kind": { + "type": "string", + "enum": [ + "time_range" + ] + }, + "default": { + "type": "object", + "properties": { + "from": { + "type": "integer" + }, + "to": { + "type": "integer" + } + }, + "required": [ + "from", + "to" + ], + "additionalProperties": false + } + }, + "required": [ + "key", + "label", + "kind" + ], + "additionalProperties": false + }, + { + "type": "object", + "properties": { + "key": { + "type": "string", + "pattern": "^[a-z][a-z0-9_]{0,31}$" + }, + "label": { + "type": "string", + "minLength": 1, + "maxLength": 100 + }, + "description": { + "type": "string", + "maxLength": 500 + }, + "required": { + "type": "boolean" + }, + "kind": { + "type": "string", + "enum": [ + "resource" + ] + }, + "resource": { + "type": "string", + "enum": [ + "cluster", + "install", + "product", + "package", + "region" + ] + }, + "default": { + "anyOf": [ + { + "type": "string", + "maxLength": 255 + }, + { + "type": "array", + "items": { + "type": "string", + "maxLength": 255 + }, + "minItems": 1, + "maxItems": 100 + } + ] + }, + "multiple": { + "type": "boolean" + } + }, + "required": [ + "key", + "label", + "kind", + "resource" + ], + "additionalProperties": false + }, + { + "type": "object", + "properties": { + "key": { + "type": "string", + "pattern": "^[a-z][a-z0-9_]{0,31}$" + }, + "label": { + "type": "string", + "minLength": 1, + "maxLength": 100 + }, + "description": { + "type": "string", + "maxLength": 500 + }, + "required": { + "type": "boolean" + }, + "kind": { + "type": "string", + "enum": [ + "enum" + ] + }, + "options": { + "type": "array", + "items": { + "type": "string", + "minLength": 1, + "maxLength": 100 + }, + "minItems": 1, + "maxItems": 100 + }, + "default": { + "type": "string", + "minLength": 1, + "maxLength": 100 + } + }, + "required": [ + "key", + "label", + "kind", + "options" + ], + "additionalProperties": false + }, + { + "type": "object", + "properties": { + "key": { + "type": "string", + "pattern": "^[a-z][a-z0-9_]{0,31}$" + }, + "label": { + "type": "string", + "minLength": 1, + "maxLength": 100 + }, + "description": { + "type": "string", + "maxLength": 500 + }, + "required": { + "type": "boolean" + }, + "kind": { + "type": "string", + "enum": [ + "boolean" + ] + }, + "default": { + "type": "boolean" + } + }, + "required": [ + "key", + "label", + "kind" + ], + "additionalProperties": false + }, + { + "type": "object", + "properties": { + "key": { + "type": "string", + "pattern": "^[a-z][a-z0-9_]{0,31}$" + }, + "label": { + "type": "string", + "minLength": 1, + "maxLength": 100 + }, + "description": { + "type": "string", + "maxLength": 500 + }, + "required": { + "type": "boolean" + }, + "kind": { + "type": "string", + "enum": [ + "number" + ] + }, + "min": { + "type": "number" + }, + "max": { + "type": "number" + }, + "default": { + "type": "number" + } + }, + "required": [ + "key", + "label", + "kind" + ], + "additionalProperties": false + }, + { + "type": "object", + "properties": { + "key": { + "type": "string", + "pattern": "^[a-z][a-z0-9_]{0,31}$" + }, + "label": { + "type": "string", + "minLength": 1, + "maxLength": 100 + }, + "description": { + "type": "string", + "maxLength": 500 + }, + "required": { + "type": "boolean" + }, + "kind": { + "type": "string", + "enum": [ + "text" + ] + }, + "default": { + "type": "string", + "maxLength": 500 + }, + "max_length": { + "type": "integer", + "minimum": 1, + "maximum": 500 + } + }, + "required": [ + "key", + "label", + "kind" + ], + "additionalProperties": false + } + ] + }, + "maxItems": 16 + }, + "visibility": { + "type": "string", + "enum": [ + "workspace", + "session" + ], + "description": "Whether the snippet is reusable workspace state or scoped to an agent session." + }, + "origin": { + "type": "string", + "enum": [ + "user", + "agent", + "system" + ], + "description": "Who authored the snippet descriptor." + }, + "agent_session_id": { "type": "string", "minLength": 1, - "maxLength": 128, - "pattern": "^(0|[1-9]\\d*)\\.(0|[1-9]\\d*)\\.(0|[1-9]\\d*)(?:-((?:0|[1-9]\\d*|[0-9A-Za-z-]*[A-Za-z-][0-9A-Za-z-]*)(?:\\.(?:0|[1-9]\\d*|[0-9A-Za-z-]*[A-Za-z-][0-9A-Za-z-]*))*))?(?:\\+([0-9A-Za-z-]+(?:\\.[0-9A-Za-z-]+)*))?$", - "example": "1.2.3" + "maxLength": 54 + }, + "agent_turn_id": { + "type": "string", + "minLength": 1, + "maxLength": 54 + }, + "purpose": { + "type": "string", + "enum": [ + "general", + "prepared_action", + "reactive_read", + "widget" + ] + }, + "result_contract_version": { + "type": "number", + "enum": [ + 1 + ] + }, + "result_type": { + "type": "string", + "enum": [ + "scalar", + "timeseries", + "categorical", + "table", + "status_list", + "logs", + "json" + ] + }, + "default_visualization": { + "type": "string", + "enum": [ + "stat", + "sparkline", + "line", + "area", + "bar", + "donut", + "table", + "status_list", + "logs", + "json" + ] } }, "required": [ - "kind", - "version" + "name", + "code", + "display_type", + "result_contract_version", + "result_type", + "default_visualization" ], "additionalProperties": false } - ] - }, - "ProductMarketplaceState": { - "type": "object", - "nullable": true, - "properties": { - "published": { - "type": "boolean", - "description": "Whether the product is publicly visible on the marketplace" - } - }, - "required": [ - "published" ], - "additionalProperties": false, - "description": "Marketplace listing configuration. When null the product is not listed." + "x-platform-exact-union": true }, - "DashboardProductList": { - "type": "object", - "properties": { - "data": { - "type": "array", - "items": { - "$ref": "#/components/schemas/DashboardProduct" - } - }, - "has_more": { - "type": "boolean", - "description": "True if more items exist after this page." - }, - "next_cursor": { - "type": "string", - "nullable": true, - "description": "Opaque cursor for the next page, or null if no more pages." - } - }, - "required": [ - "data", - "has_more", - "next_cursor" - ] - }, - "DashboardProduct": { - "type": "object", - "properties": { - "id": { - "type": "string", - "minLength": 1, - "maxLength": 55, - "example": "prod_j572abc123def456" - }, - "html_url": { - "type": "string", - "maxLength": 2048, - "format": "uri", - "description": "Absolute dashboard URL for this resource. OUTPUT_ONLY.", - "example": "https://akua.dev/products/prod_j572abc123def456" - }, - "name": { - "type": "string", - "example": "PostgreSQL Managed" - }, - "workspace_id": { - "type": "string", - "minLength": 1, - "maxLength": 53 + "UpdateSnippetBody": { + "oneOf": [ + { + "type": "object", + "properties": { + "name": { + "type": "string", + "minLength": 1, + "maxLength": 100 + }, + "description": { + "type": "string", + "maxLength": 500 + }, + "code": { + "type": "string", + "minLength": 1, + "maxLength": 50000 + }, + "display_type": { + "type": "string", + "enum": [ + "table", + "stat", + "json", + "logs", + "timeseries" + ], + "description": "Controls how the snippet result is rendered in dashboard widgets" + }, + "inputs": { + "type": "array", + "items": { + "oneOf": [ + { + "type": "object", + "properties": { + "key": { + "type": "string", + "pattern": "^[a-z][a-z0-9_]{0,31}$" + }, + "label": { + "type": "string", + "minLength": 1, + "maxLength": 100 + }, + "description": { + "type": "string", + "maxLength": 500 + }, + "required": { + "type": "boolean" + }, + "kind": { + "type": "string", + "enum": [ + "time_range" + ] + }, + "default": { + "type": "object", + "properties": { + "from": { + "type": "integer" + }, + "to": { + "type": "integer" + } + }, + "required": [ + "from", + "to" + ], + "additionalProperties": false + } + }, + "required": [ + "key", + "label", + "kind" + ], + "additionalProperties": false + }, + { + "type": "object", + "properties": { + "key": { + "type": "string", + "pattern": "^[a-z][a-z0-9_]{0,31}$" + }, + "label": { + "type": "string", + "minLength": 1, + "maxLength": 100 + }, + "description": { + "type": "string", + "maxLength": 500 + }, + "required": { + "type": "boolean" + }, + "kind": { + "type": "string", + "enum": [ + "resource" + ] + }, + "resource": { + "type": "string", + "enum": [ + "cluster", + "install", + "product", + "package", + "region" + ] + }, + "default": { + "anyOf": [ + { + "type": "string", + "maxLength": 255 + }, + { + "type": "array", + "items": { + "type": "string", + "maxLength": 255 + }, + "minItems": 1, + "maxItems": 100 + } + ] + }, + "multiple": { + "type": "boolean" + } + }, + "required": [ + "key", + "label", + "kind", + "resource" + ], + "additionalProperties": false + }, + { + "type": "object", + "properties": { + "key": { + "type": "string", + "pattern": "^[a-z][a-z0-9_]{0,31}$" + }, + "label": { + "type": "string", + "minLength": 1, + "maxLength": 100 + }, + "description": { + "type": "string", + "maxLength": 500 + }, + "required": { + "type": "boolean" + }, + "kind": { + "type": "string", + "enum": [ + "enum" + ] + }, + "options": { + "type": "array", + "items": { + "type": "string", + "minLength": 1, + "maxLength": 100 + }, + "minItems": 1, + "maxItems": 100 + }, + "default": { + "type": "string", + "minLength": 1, + "maxLength": 100 + } + }, + "required": [ + "key", + "label", + "kind", + "options" + ], + "additionalProperties": false + }, + { + "type": "object", + "properties": { + "key": { + "type": "string", + "pattern": "^[a-z][a-z0-9_]{0,31}$" + }, + "label": { + "type": "string", + "minLength": 1, + "maxLength": 100 + }, + "description": { + "type": "string", + "maxLength": 500 + }, + "required": { + "type": "boolean" + }, + "kind": { + "type": "string", + "enum": [ + "boolean" + ] + }, + "default": { + "type": "boolean" + } + }, + "required": [ + "key", + "label", + "kind" + ], + "additionalProperties": false + }, + { + "type": "object", + "properties": { + "key": { + "type": "string", + "pattern": "^[a-z][a-z0-9_]{0,31}$" + }, + "label": { + "type": "string", + "minLength": 1, + "maxLength": 100 + }, + "description": { + "type": "string", + "maxLength": 500 + }, + "required": { + "type": "boolean" + }, + "kind": { + "type": "string", + "enum": [ + "number" + ] + }, + "min": { + "type": "number" + }, + "max": { + "type": "number" + }, + "default": { + "type": "number" + } + }, + "required": [ + "key", + "label", + "kind" + ], + "additionalProperties": false + }, + { + "type": "object", + "properties": { + "key": { + "type": "string", + "pattern": "^[a-z][a-z0-9_]{0,31}$" + }, + "label": { + "type": "string", + "minLength": 1, + "maxLength": 100 + }, + "description": { + "type": "string", + "maxLength": 500 + }, + "required": { + "type": "boolean" + }, + "kind": { + "type": "string", + "enum": [ + "text" + ] + }, + "default": { + "type": "string", + "maxLength": 500 + }, + "max_length": { + "type": "integer", + "minimum": 1, + "maximum": 500 + } + }, + "required": [ + "key", + "label", + "kind" + ], + "additionalProperties": false + } + ] + }, + "maxItems": 16 + }, + "visibility": { + "type": "string", + "enum": [ + "workspace", + "session" + ], + "description": "Whether the snippet is reusable workspace state or scoped to an agent session." + }, + "purpose": { + "type": "string", + "enum": [ + "general", + "prepared_action", + "reactive_read", + "widget" + ] + }, + "result_type": { + "type": "string", + "enum": [ + "scalar", + "timeseries", + "categorical", + "table", + "status_list", + "logs", + "json" + ] + }, + "default_visualization": { + "type": "string", + "enum": [ + "stat", + "sparkline", + "line", + "area", + "bar", + "donut", + "table", + "status_list", + "logs", + "json" + ] + } + }, + "additionalProperties": false }, - "package": { + { + "type": "object", + "properties": { + "name": { + "type": "string", + "minLength": 1, + "maxLength": 100 + }, + "description": { + "type": "string", + "maxLength": 500 + }, + "code": { + "type": "string", + "minLength": 1, + "maxLength": 50000 + }, + "display_type": { + "type": "string", + "enum": [ + "table", + "stat", + "json", + "logs", + "timeseries" + ], + "description": "Controls how the snippet result is rendered in dashboard widgets" + }, + "inputs": { + "type": "array", + "items": { + "oneOf": [ + { + "type": "object", + "properties": { + "key": { + "type": "string", + "pattern": "^[a-z][a-z0-9_]{0,31}$" + }, + "label": { + "type": "string", + "minLength": 1, + "maxLength": 100 + }, + "description": { + "type": "string", + "maxLength": 500 + }, + "required": { + "type": "boolean" + }, + "kind": { + "type": "string", + "enum": [ + "time_range" + ] + }, + "default": { + "type": "object", + "properties": { + "from": { + "type": "integer" + }, + "to": { + "type": "integer" + } + }, + "required": [ + "from", + "to" + ], + "additionalProperties": false + } + }, + "required": [ + "key", + "label", + "kind" + ], + "additionalProperties": false + }, + { + "type": "object", + "properties": { + "key": { + "type": "string", + "pattern": "^[a-z][a-z0-9_]{0,31}$" + }, + "label": { + "type": "string", + "minLength": 1, + "maxLength": 100 + }, + "description": { + "type": "string", + "maxLength": 500 + }, + "required": { + "type": "boolean" + }, + "kind": { + "type": "string", + "enum": [ + "resource" + ] + }, + "resource": { + "type": "string", + "enum": [ + "cluster", + "install", + "product", + "package", + "region" + ] + }, + "default": { + "anyOf": [ + { + "type": "string", + "maxLength": 255 + }, + { + "type": "array", + "items": { + "type": "string", + "maxLength": 255 + }, + "minItems": 1, + "maxItems": 100 + } + ] + }, + "multiple": { + "type": "boolean" + } + }, + "required": [ + "key", + "label", + "kind", + "resource" + ], + "additionalProperties": false + }, + { + "type": "object", + "properties": { + "key": { + "type": "string", + "pattern": "^[a-z][a-z0-9_]{0,31}$" + }, + "label": { + "type": "string", + "minLength": 1, + "maxLength": 100 + }, + "description": { + "type": "string", + "maxLength": 500 + }, + "required": { + "type": "boolean" + }, + "kind": { + "type": "string", + "enum": [ + "enum" + ] + }, + "options": { + "type": "array", + "items": { + "type": "string", + "minLength": 1, + "maxLength": 100 + }, + "minItems": 1, + "maxItems": 100 + }, + "default": { + "type": "string", + "minLength": 1, + "maxLength": 100 + } + }, + "required": [ + "key", + "label", + "kind", + "options" + ], + "additionalProperties": false + }, + { + "type": "object", + "properties": { + "key": { + "type": "string", + "pattern": "^[a-z][a-z0-9_]{0,31}$" + }, + "label": { + "type": "string", + "minLength": 1, + "maxLength": 100 + }, + "description": { + "type": "string", + "maxLength": 500 + }, + "required": { + "type": "boolean" + }, + "kind": { + "type": "string", + "enum": [ + "boolean" + ] + }, + "default": { + "type": "boolean" + } + }, + "required": [ + "key", + "label", + "kind" + ], + "additionalProperties": false + }, + { + "type": "object", + "properties": { + "key": { + "type": "string", + "pattern": "^[a-z][a-z0-9_]{0,31}$" + }, + "label": { + "type": "string", + "minLength": 1, + "maxLength": 100 + }, + "description": { + "type": "string", + "maxLength": 500 + }, + "required": { + "type": "boolean" + }, + "kind": { + "type": "string", + "enum": [ + "number" + ] + }, + "min": { + "type": "number" + }, + "max": { + "type": "number" + }, + "default": { + "type": "number" + } + }, + "required": [ + "key", + "label", + "kind" + ], + "additionalProperties": false + }, + { + "type": "object", + "properties": { + "key": { + "type": "string", + "pattern": "^[a-z][a-z0-9_]{0,31}$" + }, + "label": { + "type": "string", + "minLength": 1, + "maxLength": 100 + }, + "description": { + "type": "string", + "maxLength": 500 + }, + "required": { + "type": "boolean" + }, + "kind": { + "type": "string", + "enum": [ + "text" + ] + }, + "default": { + "type": "string", + "maxLength": 500 + }, + "max_length": { + "type": "integer", + "minimum": 1, + "maximum": 500 + } + }, + "required": [ + "key", + "label", + "kind" + ], + "additionalProperties": false + } + ] + }, + "maxItems": 16 + }, + "visibility": { + "type": "string", + "enum": [ + "workspace", + "session" + ], + "description": "Whether the snippet is reusable workspace state or scoped to an agent session." + }, + "purpose": { + "type": "string", + "enum": [ + "general", + "prepared_action", + "reactive_read", + "widget" + ] + }, + "result_contract_version": { + "type": "number", + "enum": [ + 1 + ] + }, + "result_type": { + "type": "string", + "enum": [ + "scalar", + "timeseries", + "categorical", + "table", + "status_list", + "logs", + "json" + ] + }, + "default_visualization": { + "type": "string", + "enum": [ + "stat", + "sparkline", + "line", + "area", + "bar", + "donut", + "table", + "status_list", + "logs", + "json" + ] + } + }, + "required": [ + "result_contract_version", + "result_type", + "default_visualization" + ], + "additionalProperties": false + } + ], + "x-platform-exact-union": true + }, + "SnippetRun": { + "oneOf": [ + { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, - "maxLength": 54, - "example": "pkg_j572abc123def456" + "maxLength": 54 }, - "version_pin": { - "$ref": "#/components/schemas/PackageVersionPin" + "snippet_id": { + "type": "string", + "minLength": 1, + "maxLength": 54 }, - "default_version_id": { + "source": { + "type": "string", + "enum": [ + "manual", + "dashboard_open", + "dashboard_refresh", + "agent" + ], + "description": "Origin that initiated the persisted snippet run." + }, + "snippet_name": { + "type": "string" + }, + "snippet_etag": { + "type": "string" + }, + "dashboard_id": { "type": "string", "nullable": true, "minLength": 1, - "maxLength": 55, - "description": "Concrete PackageVersion currently resolved by the version pin, or null when latest has no published version yet." + "maxLength": 55 + }, + "dashboard_name": { + "type": "string", + "nullable": true + }, + "widget_id": { + "type": "string", + "nullable": true, + "minLength": 1, + "maxLength": 54 + }, + "widget_title": { + "type": "string", + "nullable": true + }, + "run_by": { + "type": "string" + }, + "agent_session_id": { + "type": "string", + "nullable": true, + "minLength": 1, + "maxLength": 54 + }, + "agent_turn_id": { + "type": "string", + "nullable": true, + "minLength": 1, + "maxLength": 54 + }, + "state": { + "type": "string", + "enum": [ + "succeeded", + "failed", + "timed_out" + ], + "description": "Terminal run state in past participle form." + }, + "inputs": { + "type": "object", + "additionalProperties": { + "nullable": true + } + }, + "overrides": { + "type": "object", + "additionalProperties": { + "nullable": true + }, + "description": "Legacy execution metadata retained for compatibility. It is not applied as runtime input." + }, + "error": { + "$ref": "#/components/schemas/SnippetRunError" + }, + "duration_ms": { + "type": "number" + }, + "stats": { + "type": "object", + "properties": { + "cpu_time_ms": { + "type": "number" + }, + "wall_time_ms": { + "type": "number" + }, + "heap_used_bytes": { + "type": "number" + } + }, + "required": [ + "cpu_time_ms", + "wall_time_ms", + "heap_used_bytes" + ] + }, + "created_at": { + "type": "integer", + "minimum": 0, + "description": "Unix timestamp (seconds)" + }, + "etag": { + "type": "string" + }, + "result_contract_version": { + "nullable": true + }, + "result_type": { + "nullable": true + }, + "default_visualization": { + "nullable": true + }, + "output": { + "nullable": true } }, "required": [ "id", - "version_pin", - "default_version_id" - ], - "additionalProperties": false, - "description": "Reference to the Package backing this product. Fetch full details via `GET /v1/packages/{id}`." - }, - "custom_image": { - "type": "string", - "description": "Custom display image URL — overrides the package logo on dashboard catalog rows" - }, - "marketplace": { - "$ref": "#/components/schemas/ProductMarketplaceState" - }, - "created_at": { - "type": "integer", - "minimum": 0, - "description": "Unix timestamp (seconds)" - }, - "updated_at": { - "type": "integer", - "minimum": 0, - "description": "Unix timestamp (seconds)" - }, - "etag": { - "type": "string" - }, - "state": { - "type": "string", - "enum": [ - "active", - "archived" - ], - "description": "Product lifecycle state." - }, - "archived_at": { - "type": "integer", - "minimum": 0, - "description": "When the product was archived, expressed as Unix seconds since epoch." + "snippet_id", + "source", + "snippet_name", + "snippet_etag", + "dashboard_id", + "dashboard_name", + "widget_id", + "widget_title", + "run_by", + "agent_session_id", + "agent_turn_id", + "state", + "inputs", + "duration_ms", + "stats", + "created_at", + "etag", + "result_contract_version", + "result_type", + "default_visualization" + ] }, - "archive_reason": { - "type": "string", - "description": "Reason supplied by the seller when archiving." + { + "type": "object", + "properties": { + "id": { + "type": "string", + "minLength": 1, + "maxLength": 54 + }, + "snippet_id": { + "type": "string", + "minLength": 1, + "maxLength": 54 + }, + "source": { + "type": "string", + "enum": [ + "manual", + "dashboard_open", + "dashboard_refresh", + "agent" + ], + "description": "Origin that initiated the persisted snippet run." + }, + "snippet_name": { + "type": "string" + }, + "snippet_etag": { + "type": "string" + }, + "dashboard_id": { + "type": "string", + "nullable": true, + "minLength": 1, + "maxLength": 55 + }, + "dashboard_name": { + "type": "string", + "nullable": true + }, + "widget_id": { + "type": "string", + "nullable": true, + "minLength": 1, + "maxLength": 54 + }, + "widget_title": { + "type": "string", + "nullable": true + }, + "run_by": { + "type": "string" + }, + "agent_session_id": { + "type": "string", + "nullable": true, + "minLength": 1, + "maxLength": 54 + }, + "agent_turn_id": { + "type": "string", + "nullable": true, + "minLength": 1, + "maxLength": 54 + }, + "state": { + "type": "string", + "enum": [ + "succeeded", + "failed", + "timed_out" + ], + "description": "Terminal run state in past participle form." + }, + "inputs": { + "type": "object", + "additionalProperties": { + "nullable": true + } + }, + "overrides": { + "type": "object", + "additionalProperties": { + "nullable": true + }, + "description": "Legacy execution metadata retained for compatibility. It is not applied as runtime input." + }, + "error": { + "$ref": "#/components/schemas/SnippetRunError" + }, + "duration_ms": { + "type": "number" + }, + "stats": { + "type": "object", + "properties": { + "cpu_time_ms": { + "type": "number" + }, + "wall_time_ms": { + "type": "number" + }, + "heap_used_bytes": { + "type": "number" + } + }, + "required": [ + "cpu_time_ms", + "wall_time_ms", + "heap_used_bytes" + ] + }, + "created_at": { + "type": "integer", + "minimum": 0, + "description": "Unix timestamp (seconds)" + }, + "etag": { + "type": "string" + }, + "result_contract_version": { + "type": "number", + "enum": [ + 1 + ] + }, + "result_type": { + "type": "string", + "enum": [ + "scalar", + "timeseries", + "categorical", + "table", + "status_list", + "logs", + "json" + ] + }, + "default_visualization": { + "type": "string", + "enum": [ + "stat", + "sparkline", + "line", + "area", + "bar", + "donut", + "table", + "status_list", + "logs", + "json" + ] + }, + "output": { + "oneOf": [ + { + "type": "object", + "properties": { + "contract_version": { + "type": "number", + "enum": [ + 1 + ] + }, + "type": { + "type": "string", + "enum": [ + "scalar" + ] + }, + "value": { + "anyOf": [ + { + "type": "string", + "maxLength": 16384 + }, + { + "type": "number" + }, + { + "type": "boolean" + }, + { + "nullable": true + } + ] + }, + "unit": { + "type": "string", + "minLength": 1, + "maxLength": 64 + }, + "definition": { + "type": "string", + "minLength": 1, + "maxLength": 500 + }, + "timestamp": { + "type": "integer", + "minimum": 0 + }, + "history": { + "type": "array", + "items": { + "type": "object", + "properties": { + "timestamp": { + "type": "integer", + "minimum": 0 + }, + "value": { + "type": "number", + "nullable": true + } + }, + "required": [ + "timestamp", + "value" + ], + "additionalProperties": false + }, + "maxItems": 2000 + } + }, + "required": [ + "contract_version", + "type", + "value" + ], + "additionalProperties": false + }, + { + "type": "object", + "properties": { + "contract_version": { + "type": "number", + "enum": [ + 1 + ] + }, + "type": { + "type": "string", + "enum": [ + "timeseries" + ] + }, + "series": { + "type": "array", + "items": { + "type": "object", + "properties": { + "key": { + "type": "string", + "minLength": 1, + "maxLength": 64, + "pattern": "^[a-z][a-z0-9]*(?:_[a-z0-9]+)*$" + }, + "label": { + "type": "string", + "minLength": 1, + "maxLength": 200 + }, + "unit": { + "type": "string", + "minLength": 1, + "maxLength": 64 + }, + "definition": { + "type": "string", + "minLength": 1, + "maxLength": 500 + } + }, + "required": [ + "key", + "label" + ], + "additionalProperties": false + }, + "minItems": 1, + "maxItems": 8 + }, + "points": { + "type": "array", + "items": { + "type": "object", + "properties": { + "timestamp": { + "type": "integer", + "minimum": 0 + }, + "values": { + "type": "array", + "items": { + "type": "number", + "nullable": true + }, + "maxItems": 8 + } + }, + "required": [ + "timestamp", + "values" + ], + "additionalProperties": false + }, + "maxItems": 2000 + } + }, + "required": [ + "contract_version", + "type", + "series", + "points" + ], + "additionalProperties": false + }, + { + "type": "object", + "properties": { + "contract_version": { + "type": "number", + "enum": [ + 1 + ] + }, + "type": { + "type": "string", + "enum": [ + "categorical" + ] + }, + "series": { + "type": "array", + "items": { + "type": "object", + "properties": { + "key": { + "type": "string", + "minLength": 1, + "maxLength": 64, + "pattern": "^[a-z][a-z0-9]*(?:_[a-z0-9]+)*$" + }, + "label": { + "type": "string", + "minLength": 1, + "maxLength": 200 + }, + "unit": { + "type": "string", + "minLength": 1, + "maxLength": 64 + }, + "definition": { + "type": "string", + "minLength": 1, + "maxLength": 500 + } + }, + "required": [ + "key", + "label" + ], + "additionalProperties": false + }, + "minItems": 1, + "maxItems": 8 + }, + "categories": { + "type": "array", + "items": { + "type": "object", + "properties": { + "key": { + "type": "string", + "minLength": 1, + "maxLength": 64, + "pattern": "^[a-z][a-z0-9]*(?:_[a-z0-9]+)*$" + }, + "label": { + "type": "string", + "minLength": 1, + "maxLength": 200 + } + }, + "required": [ + "key", + "label" + ], + "additionalProperties": false + }, + "maxItems": 100 + }, + "values": { + "type": "array", + "items": { + "type": "array", + "items": { + "type": "number", + "nullable": true + }, + "maxItems": 8 + }, + "maxItems": 100 + } + }, + "required": [ + "contract_version", + "type", + "series", + "categories", + "values" + ], + "additionalProperties": false + }, + { + "type": "object", + "properties": { + "contract_version": { + "type": "number", + "enum": [ + 1 + ] + }, + "type": { + "type": "string", + "enum": [ + "table" + ] + }, + "columns": { + "type": "array", + "items": { + "oneOf": [ + { + "type": "object", + "properties": { + "key": { + "type": "string", + "minLength": 1, + "maxLength": 64, + "pattern": "^[a-z][a-z0-9]*(?:_[a-z0-9]+)*$" + }, + "label": { + "type": "string", + "minLength": 1, + "maxLength": 200 + }, + "definition": { + "type": "string", + "minLength": 1, + "maxLength": 500 + }, + "kind": { + "type": "string", + "enum": [ + "text" + ] + } + }, + "required": [ + "key", + "label", + "kind" + ], + "additionalProperties": false + }, + { + "type": "object", + "properties": { + "key": { + "type": "string", + "minLength": 1, + "maxLength": 64, + "pattern": "^[a-z][a-z0-9]*(?:_[a-z0-9]+)*$" + }, + "label": { + "type": "string", + "minLength": 1, + "maxLength": 200 + }, + "definition": { + "type": "string", + "minLength": 1, + "maxLength": 500 + }, + "kind": { + "type": "string", + "enum": [ + "number" + ] + }, + "unit": { + "type": "string", + "minLength": 1, + "maxLength": 64 + } + }, + "required": [ + "key", + "label", + "kind" + ], + "additionalProperties": false + }, + { + "type": "object", + "properties": { + "key": { + "type": "string", + "minLength": 1, + "maxLength": 64, + "pattern": "^[a-z][a-z0-9]*(?:_[a-z0-9]+)*$" + }, + "label": { + "type": "string", + "minLength": 1, + "maxLength": 200 + }, + "definition": { + "type": "string", + "minLength": 1, + "maxLength": 500 + }, + "kind": { + "type": "string", + "enum": [ + "boolean" + ] + } + }, + "required": [ + "key", + "label", + "kind" + ], + "additionalProperties": false + }, + { + "type": "object", + "properties": { + "key": { + "type": "string", + "minLength": 1, + "maxLength": 64, + "pattern": "^[a-z][a-z0-9]*(?:_[a-z0-9]+)*$" + }, + "label": { + "type": "string", + "minLength": 1, + "maxLength": 200 + }, + "definition": { + "type": "string", + "minLength": 1, + "maxLength": 500 + }, + "kind": { + "type": "string", + "enum": [ + "timestamp" + ] + } + }, + "required": [ + "key", + "label", + "kind" + ], + "additionalProperties": false + }, + { + "type": "object", + "properties": { + "key": { + "type": "string", + "minLength": 1, + "maxLength": 64, + "pattern": "^[a-z][a-z0-9]*(?:_[a-z0-9]+)*$" + }, + "label": { + "type": "string", + "minLength": 1, + "maxLength": 200 + }, + "definition": { + "type": "string", + "minLength": 1, + "maxLength": 500 + }, + "kind": { + "type": "string", + "enum": [ + "link" + ] + } + }, + "required": [ + "key", + "label", + "kind" + ], + "additionalProperties": false + } + ] + }, + "minItems": 1, + "maxItems": 32 + }, + "rows": { + "type": "array", + "items": { + "type": "array", + "items": { + "anyOf": [ + { + "type": "string", + "maxLength": 16384 + }, + { + "type": "number" + }, + { + "type": "boolean" + }, + { + "nullable": true + } + ] + }, + "maxItems": 32 + }, + "maxItems": 500 + } + }, + "required": [ + "contract_version", + "type", + "columns", + "rows" + ], + "additionalProperties": false + }, + { + "type": "object", + "properties": { + "contract_version": { + "type": "number", + "enum": [ + 1 + ] + }, + "type": { + "type": "string", + "enum": [ + "status_list" + ] + }, + "items": { + "type": "array", + "items": { + "type": "object", + "properties": { + "key": { + "type": "string", + "minLength": 1, + "maxLength": 64, + "pattern": "^[a-z][a-z0-9]*(?:_[a-z0-9]+)*$" + }, + "label": { + "type": "string", + "minLength": 1, + "maxLength": 200 + }, + "severity": { + "type": "string", + "enum": [ + "info", + "success", + "warning", + "critical", + "unknown" + ] + }, + "detail": { + "type": "string", + "maxLength": 16384 + }, + "timestamp": { + "type": "integer", + "minimum": 0 + }, + "link": { + "type": "string", + "minLength": 1, + "maxLength": 2048 + } + }, + "required": [ + "key", + "label", + "severity" + ], + "additionalProperties": false + }, + "maxItems": 200 + } + }, + "required": [ + "contract_version", + "type", + "items" + ], + "additionalProperties": false + }, + { + "type": "object", + "properties": { + "contract_version": { + "type": "number", + "enum": [ + 1 + ] + }, + "type": { + "type": "string", + "enum": [ + "logs" + ] + }, + "entries": { + "type": "array", + "items": { + "type": "object", + "properties": { + "message": { + "type": "string", + "minLength": 1, + "maxLength": 4096 + }, + "timestamp": { + "type": "integer", + "minimum": 0 + }, + "level": { + "type": "string", + "minLength": 1, + "maxLength": 32 + } + }, + "required": [ + "message" + ], + "additionalProperties": false + }, + "maxItems": 1000 + } + }, + "required": [ + "contract_version", + "type", + "entries" + ], + "additionalProperties": false + }, + { + "type": "object", + "properties": { + "contract_version": { + "type": "number", + "enum": [ + 1 + ] + }, + "type": { + "type": "string", + "enum": [ + "json" + ] + }, + "value": { + "nullable": true + } + }, + "required": [ + "contract_version", + "type", + "value" + ], + "additionalProperties": false + } + ] + } + }, + "required": [ + "id", + "snippet_id", + "source", + "snippet_name", + "snippet_etag", + "dashboard_id", + "dashboard_name", + "widget_id", + "widget_title", + "run_by", + "agent_session_id", + "agent_turn_id", + "state", + "inputs", + "duration_ms", + "stats", + "created_at", + "etag", + "result_contract_version", + "result_type", + "default_visualization" + ] + } + ] + }, + "SnippetRunError": { + "type": "object", + "properties": { + "code": { + "type": "string" + }, + "message": { + "type": "string" + }, + "details": { + "nullable": true + } + }, + "required": [ + "code", + "message" + ] + }, + "CreateSnippetRunBody": { + "type": "object", + "properties": { + "inputs": { + "type": "object", + "additionalProperties": { + "nullable": true + } + }, + "overrides": { + "type": "object", + "additionalProperties": { + "nullable": true + }, + "description": "Legacy execution metadata retained for compatibility. It is not applied as runtime input." + }, + "agent_turn_id": { + "type": "string", + "minLength": 1, + "maxLength": 54 + }, + "context": { + "oneOf": [ + { + "type": "object", + "properties": { + "source": { + "type": "string", + "enum": [ + "manual" + ] + } + }, + "required": [ + "source" + ], + "additionalProperties": false + }, + { + "type": "object", + "properties": { + "source": { + "type": "string", + "enum": [ + "agent" + ] + }, + "agent_turn_id": { + "type": "string", + "minLength": 1, + "maxLength": 54 + } + }, + "required": [ + "source" + ], + "additionalProperties": false + }, + { + "type": "object", + "properties": { + "source": { + "type": "string", + "enum": [ + "dashboard_open" + ] + }, + "dashboard_id": { + "type": "string", + "minLength": 1, + "maxLength": 55 + }, + "widget_id": { + "type": "string", + "minLength": 1, + "maxLength": 54 + } + }, + "required": [ + "source", + "dashboard_id", + "widget_id" + ], + "additionalProperties": false + }, + { + "type": "object", + "properties": { + "source": { + "type": "string", + "enum": [ + "dashboard_refresh" + ] + }, + "dashboard_id": { + "type": "string", + "minLength": 1, + "maxLength": 55 + }, + "widget_id": { + "type": "string", + "minLength": 1, + "maxLength": 54 + } + }, + "required": [ + "source", + "dashboard_id", + "widget_id" + ], + "additionalProperties": false + } + ] + } + }, + "additionalProperties": false + }, + "SnippetRunList": { + "type": "object", + "properties": { + "data": { + "type": "array", + "items": { + "$ref": "#/components/schemas/SnippetRun" + } + }, + "has_more": { + "type": "boolean", + "description": "True if more items exist after this page." + }, + "next_cursor": { + "type": "string", + "nullable": true, + "description": "Opaque cursor for the next page, or null if no more pages." + } + }, + "required": [ + "data", + "has_more", + "next_cursor" + ] + }, + "DashboardWidgetResultResolution": { + "type": "object", + "properties": { + "widget_id": { + "type": "string", + "minLength": 1, + "maxLength": 54 + }, + "snippet_etag": { + "type": "string" + }, + "inputs": { + "type": "object", + "additionalProperties": { + "nullable": true + } + }, + "input_hash": { + "type": "string", + "pattern": "^[a-f0-9]{64}$" + }, + "cache_key": { + "type": "string", + "pattern": "^[a-f0-9]{64}$", + "description": "Opaque cache identity scoped to the widget, normalized inputs, snippet revision, and authenticated viewer." + }, + "result": { + "anyOf": [ + { + "type": "object", + "properties": { + "id": { + "type": "string", + "minLength": 1, + "maxLength": 54 + }, + "snippet_id": { + "type": "string", + "minLength": 1, + "maxLength": 54 + }, + "source": { + "type": "string", + "enum": [ + "manual", + "dashboard_open", + "dashboard_refresh", + "agent" + ], + "description": "Origin that initiated the persisted snippet run." + }, + "snippet_name": { + "type": "string" + }, + "snippet_etag": { + "type": "string" + }, + "dashboard_id": { + "type": "string", + "nullable": true, + "minLength": 1, + "maxLength": 55 + }, + "dashboard_name": { + "type": "string", + "nullable": true + }, + "widget_id": { + "type": "string", + "nullable": true, + "minLength": 1, + "maxLength": 54 + }, + "widget_title": { + "type": "string", + "nullable": true + }, + "run_by": { + "type": "string" + }, + "agent_session_id": { + "type": "string", + "nullable": true, + "minLength": 1, + "maxLength": 54 + }, + "agent_turn_id": { + "type": "string", + "nullable": true, + "minLength": 1, + "maxLength": 54 + }, + "state": { + "type": "string", + "enum": [ + "succeeded", + "failed", + "timed_out" + ], + "description": "Terminal run state in past participle form." + }, + "inputs": { + "type": "object", + "additionalProperties": { + "nullable": true + } + }, + "overrides": { + "type": "object", + "additionalProperties": { + "nullable": true + }, + "description": "Legacy execution metadata retained for compatibility. It is not applied as runtime input." + }, + "error": { + "$ref": "#/components/schemas/SnippetRunError" + }, + "duration_ms": { + "type": "number" + }, + "stats": { + "type": "object", + "properties": { + "cpu_time_ms": { + "type": "number" + }, + "wall_time_ms": { + "type": "number" + }, + "heap_used_bytes": { + "type": "number" + } + }, + "required": [ + "cpu_time_ms", + "wall_time_ms", + "heap_used_bytes" + ] + }, + "created_at": { + "type": "integer", + "minimum": 0, + "description": "Unix timestamp (seconds)" + }, + "etag": { + "type": "string" + }, + "result_contract_version": { + "nullable": true + }, + "result_type": { + "nullable": true + }, + "default_visualization": { + "nullable": true + }, + "output": { + "nullable": true + } + }, + "required": [ + "id", + "snippet_id", + "source", + "snippet_name", + "snippet_etag", + "dashboard_id", + "dashboard_name", + "widget_id", + "widget_title", + "run_by", + "agent_session_id", + "agent_turn_id", + "state", + "inputs", + "duration_ms", + "stats", + "created_at", + "etag", + "result_contract_version", + "result_type", + "default_visualization" + ] + }, + { + "type": "object", + "properties": { + "id": { + "type": "string", + "minLength": 1, + "maxLength": 54 + }, + "snippet_id": { + "type": "string", + "minLength": 1, + "maxLength": 54 + }, + "source": { + "type": "string", + "enum": [ + "manual", + "dashboard_open", + "dashboard_refresh", + "agent" + ], + "description": "Origin that initiated the persisted snippet run." + }, + "snippet_name": { + "type": "string" + }, + "snippet_etag": { + "type": "string" + }, + "dashboard_id": { + "type": "string", + "nullable": true, + "minLength": 1, + "maxLength": 55 + }, + "dashboard_name": { + "type": "string", + "nullable": true + }, + "widget_id": { + "type": "string", + "nullable": true, + "minLength": 1, + "maxLength": 54 + }, + "widget_title": { + "type": "string", + "nullable": true + }, + "run_by": { + "type": "string" + }, + "agent_session_id": { + "type": "string", + "nullable": true, + "minLength": 1, + "maxLength": 54 + }, + "agent_turn_id": { + "type": "string", + "nullable": true, + "minLength": 1, + "maxLength": 54 + }, + "state": { + "type": "string", + "enum": [ + "succeeded", + "failed", + "timed_out" + ], + "description": "Terminal run state in past participle form." + }, + "inputs": { + "type": "object", + "additionalProperties": { + "nullable": true + } + }, + "overrides": { + "type": "object", + "additionalProperties": { + "nullable": true + }, + "description": "Legacy execution metadata retained for compatibility. It is not applied as runtime input." + }, + "error": { + "$ref": "#/components/schemas/SnippetRunError" + }, + "duration_ms": { + "type": "number" + }, + "stats": { + "type": "object", + "properties": { + "cpu_time_ms": { + "type": "number" + }, + "wall_time_ms": { + "type": "number" + }, + "heap_used_bytes": { + "type": "number" + } + }, + "required": [ + "cpu_time_ms", + "wall_time_ms", + "heap_used_bytes" + ] + }, + "created_at": { + "type": "integer", + "minimum": 0, + "description": "Unix timestamp (seconds)" + }, + "etag": { + "type": "string" + }, + "result_contract_version": { + "type": "number", + "enum": [ + 1 + ] + }, + "result_type": { + "type": "string", + "enum": [ + "scalar", + "timeseries", + "categorical", + "table", + "status_list", + "logs", + "json" + ] + }, + "default_visualization": { + "type": "string", + "enum": [ + "stat", + "sparkline", + "line", + "area", + "bar", + "donut", + "table", + "status_list", + "logs", + "json" + ] + }, + "output": { + "oneOf": [ + { + "type": "object", + "properties": { + "contract_version": { + "type": "number", + "enum": [ + 1 + ] + }, + "type": { + "type": "string", + "enum": [ + "scalar" + ] + }, + "value": { + "anyOf": [ + { + "type": "string", + "maxLength": 16384 + }, + { + "type": "number" + }, + { + "type": "boolean" + }, + { + "nullable": true + } + ] + }, + "unit": { + "type": "string", + "minLength": 1, + "maxLength": 64 + }, + "definition": { + "type": "string", + "minLength": 1, + "maxLength": 500 + }, + "timestamp": { + "type": "integer", + "minimum": 0 + }, + "history": { + "type": "array", + "items": { + "type": "object", + "properties": { + "timestamp": { + "type": "integer", + "minimum": 0 + }, + "value": { + "type": "number", + "nullable": true + } + }, + "required": [ + "timestamp", + "value" + ], + "additionalProperties": false + }, + "maxItems": 2000 + } + }, + "required": [ + "contract_version", + "type", + "value" + ], + "additionalProperties": false + }, + { + "type": "object", + "properties": { + "contract_version": { + "type": "number", + "enum": [ + 1 + ] + }, + "type": { + "type": "string", + "enum": [ + "timeseries" + ] + }, + "series": { + "type": "array", + "items": { + "type": "object", + "properties": { + "key": { + "type": "string", + "minLength": 1, + "maxLength": 64, + "pattern": "^[a-z][a-z0-9]*(?:_[a-z0-9]+)*$" + }, + "label": { + "type": "string", + "minLength": 1, + "maxLength": 200 + }, + "unit": { + "type": "string", + "minLength": 1, + "maxLength": 64 + }, + "definition": { + "type": "string", + "minLength": 1, + "maxLength": 500 + } + }, + "required": [ + "key", + "label" + ], + "additionalProperties": false + }, + "minItems": 1, + "maxItems": 8 + }, + "points": { + "type": "array", + "items": { + "type": "object", + "properties": { + "timestamp": { + "type": "integer", + "minimum": 0 + }, + "values": { + "type": "array", + "items": { + "type": "number", + "nullable": true + }, + "maxItems": 8 + } + }, + "required": [ + "timestamp", + "values" + ], + "additionalProperties": false + }, + "maxItems": 2000 + } + }, + "required": [ + "contract_version", + "type", + "series", + "points" + ], + "additionalProperties": false + }, + { + "type": "object", + "properties": { + "contract_version": { + "type": "number", + "enum": [ + 1 + ] + }, + "type": { + "type": "string", + "enum": [ + "categorical" + ] + }, + "series": { + "type": "array", + "items": { + "type": "object", + "properties": { + "key": { + "type": "string", + "minLength": 1, + "maxLength": 64, + "pattern": "^[a-z][a-z0-9]*(?:_[a-z0-9]+)*$" + }, + "label": { + "type": "string", + "minLength": 1, + "maxLength": 200 + }, + "unit": { + "type": "string", + "minLength": 1, + "maxLength": 64 + }, + "definition": { + "type": "string", + "minLength": 1, + "maxLength": 500 + } + }, + "required": [ + "key", + "label" + ], + "additionalProperties": false + }, + "minItems": 1, + "maxItems": 8 + }, + "categories": { + "type": "array", + "items": { + "type": "object", + "properties": { + "key": { + "type": "string", + "minLength": 1, + "maxLength": 64, + "pattern": "^[a-z][a-z0-9]*(?:_[a-z0-9]+)*$" + }, + "label": { + "type": "string", + "minLength": 1, + "maxLength": 200 + } + }, + "required": [ + "key", + "label" + ], + "additionalProperties": false + }, + "maxItems": 100 + }, + "values": { + "type": "array", + "items": { + "type": "array", + "items": { + "type": "number", + "nullable": true + }, + "maxItems": 8 + }, + "maxItems": 100 + } + }, + "required": [ + "contract_version", + "type", + "series", + "categories", + "values" + ], + "additionalProperties": false + }, + { + "type": "object", + "properties": { + "contract_version": { + "type": "number", + "enum": [ + 1 + ] + }, + "type": { + "type": "string", + "enum": [ + "table" + ] + }, + "columns": { + "type": "array", + "items": { + "oneOf": [ + { + "type": "object", + "properties": { + "key": { + "type": "string", + "minLength": 1, + "maxLength": 64, + "pattern": "^[a-z][a-z0-9]*(?:_[a-z0-9]+)*$" + }, + "label": { + "type": "string", + "minLength": 1, + "maxLength": 200 + }, + "definition": { + "type": "string", + "minLength": 1, + "maxLength": 500 + }, + "kind": { + "type": "string", + "enum": [ + "text" + ] + } + }, + "required": [ + "key", + "label", + "kind" + ], + "additionalProperties": false + }, + { + "type": "object", + "properties": { + "key": { + "type": "string", + "minLength": 1, + "maxLength": 64, + "pattern": "^[a-z][a-z0-9]*(?:_[a-z0-9]+)*$" + }, + "label": { + "type": "string", + "minLength": 1, + "maxLength": 200 + }, + "definition": { + "type": "string", + "minLength": 1, + "maxLength": 500 + }, + "kind": { + "type": "string", + "enum": [ + "number" + ] + }, + "unit": { + "type": "string", + "minLength": 1, + "maxLength": 64 + } + }, + "required": [ + "key", + "label", + "kind" + ], + "additionalProperties": false + }, + { + "type": "object", + "properties": { + "key": { + "type": "string", + "minLength": 1, + "maxLength": 64, + "pattern": "^[a-z][a-z0-9]*(?:_[a-z0-9]+)*$" + }, + "label": { + "type": "string", + "minLength": 1, + "maxLength": 200 + }, + "definition": { + "type": "string", + "minLength": 1, + "maxLength": 500 + }, + "kind": { + "type": "string", + "enum": [ + "boolean" + ] + } + }, + "required": [ + "key", + "label", + "kind" + ], + "additionalProperties": false + }, + { + "type": "object", + "properties": { + "key": { + "type": "string", + "minLength": 1, + "maxLength": 64, + "pattern": "^[a-z][a-z0-9]*(?:_[a-z0-9]+)*$" + }, + "label": { + "type": "string", + "minLength": 1, + "maxLength": 200 + }, + "definition": { + "type": "string", + "minLength": 1, + "maxLength": 500 + }, + "kind": { + "type": "string", + "enum": [ + "timestamp" + ] + } + }, + "required": [ + "key", + "label", + "kind" + ], + "additionalProperties": false + }, + { + "type": "object", + "properties": { + "key": { + "type": "string", + "minLength": 1, + "maxLength": 64, + "pattern": "^[a-z][a-z0-9]*(?:_[a-z0-9]+)*$" + }, + "label": { + "type": "string", + "minLength": 1, + "maxLength": 200 + }, + "definition": { + "type": "string", + "minLength": 1, + "maxLength": 500 + }, + "kind": { + "type": "string", + "enum": [ + "link" + ] + } + }, + "required": [ + "key", + "label", + "kind" + ], + "additionalProperties": false + } + ] + }, + "minItems": 1, + "maxItems": 32 + }, + "rows": { + "type": "array", + "items": { + "type": "array", + "items": { + "anyOf": [ + { + "type": "string", + "maxLength": 16384 + }, + { + "type": "number" + }, + { + "type": "boolean" + }, + { + "nullable": true + } + ] + }, + "maxItems": 32 + }, + "maxItems": 500 + } + }, + "required": [ + "contract_version", + "type", + "columns", + "rows" + ], + "additionalProperties": false + }, + { + "type": "object", + "properties": { + "contract_version": { + "type": "number", + "enum": [ + 1 + ] + }, + "type": { + "type": "string", + "enum": [ + "status_list" + ] + }, + "items": { + "type": "array", + "items": { + "type": "object", + "properties": { + "key": { + "type": "string", + "minLength": 1, + "maxLength": 64, + "pattern": "^[a-z][a-z0-9]*(?:_[a-z0-9]+)*$" + }, + "label": { + "type": "string", + "minLength": 1, + "maxLength": 200 + }, + "severity": { + "type": "string", + "enum": [ + "info", + "success", + "warning", + "critical", + "unknown" + ] + }, + "detail": { + "type": "string", + "maxLength": 16384 + }, + "timestamp": { + "type": "integer", + "minimum": 0 + }, + "link": { + "type": "string", + "minLength": 1, + "maxLength": 2048 + } + }, + "required": [ + "key", + "label", + "severity" + ], + "additionalProperties": false + }, + "maxItems": 200 + } + }, + "required": [ + "contract_version", + "type", + "items" + ], + "additionalProperties": false + }, + { + "type": "object", + "properties": { + "contract_version": { + "type": "number", + "enum": [ + 1 + ] + }, + "type": { + "type": "string", + "enum": [ + "logs" + ] + }, + "entries": { + "type": "array", + "items": { + "type": "object", + "properties": { + "message": { + "type": "string", + "minLength": 1, + "maxLength": 4096 + }, + "timestamp": { + "type": "integer", + "minimum": 0 + }, + "level": { + "type": "string", + "minLength": 1, + "maxLength": 32 + } + }, + "required": [ + "message" + ], + "additionalProperties": false + }, + "maxItems": 1000 + } + }, + "required": [ + "contract_version", + "type", + "entries" + ], + "additionalProperties": false + }, + { + "type": "object", + "properties": { + "contract_version": { + "type": "number", + "enum": [ + 1 + ] + }, + "type": { + "type": "string", + "enum": [ + "json" + ] + }, + "value": { + "nullable": true + } + }, + "required": [ + "contract_version", + "type", + "value" + ], + "additionalProperties": false + } + ] + } + }, + "required": [ + "id", + "snippet_id", + "source", + "snippet_name", + "snippet_etag", + "dashboard_id", + "dashboard_name", + "widget_id", + "widget_title", + "run_by", + "agent_session_id", + "agent_turn_id", + "state", + "inputs", + "duration_ms", + "stats", + "created_at", + "etag", + "result_contract_version", + "result_type", + "default_visualization" + ] + }, + { + "nullable": true + } + ] + }, + "freshness": { + "type": "object", + "properties": { + "state": { + "type": "string", + "enum": [ + "missing", + "fresh", + "stale" + ] + }, + "observed_at": { + "type": "integer", + "nullable": true, + "minimum": 0, + "description": "Unix timestamp (seconds)" + }, + "age_seconds": { + "type": "integer", + "nullable": true, + "minimum": 0 + }, + "max_age_seconds": { + "type": "integer", + "minimum": 0, + "exclusiveMinimum": true + } + }, + "required": [ + "state", + "observed_at", + "age_seconds", + "max_age_seconds" + ], + "additionalProperties": false + }, + "revalidation": { + "type": "object", + "properties": { + "required": { + "type": "boolean" + }, + "after": { + "type": "integer", + "nullable": true, + "minimum": 0, + "description": "Unix timestamp (seconds)" + } + }, + "required": [ + "required", + "after" + ], + "additionalProperties": false + } + }, + "required": [ + "widget_id", + "snippet_etag", + "inputs", + "input_hash", + "cache_key", + "result", + "freshness", + "revalidation" + ], + "additionalProperties": false + }, + "ResolveDashboardWidgetResultBody": { + "type": "object", + "properties": { + "widget": { + "type": "object", + "properties": { + "id": { + "type": "string", + "minLength": 1, + "maxLength": 54 + }, + "dashboard_id": { + "type": "string", + "minLength": 1, + "maxLength": 55 + } + }, + "required": [ + "id", + "dashboard_id" + ], + "additionalProperties": false + }, + "snippet_etag": { + "type": "string", + "minLength": 1, + "maxLength": 200 + }, + "inputs": { + "type": "object", + "additionalProperties": { + "nullable": true + } + } + }, + "required": [ + "widget", + "snippet_etag", + "inputs" + ], + "additionalProperties": false + }, + "DashboardList": { + "type": "object", + "properties": { + "data": { + "type": "array", + "items": { + "$ref": "#/components/schemas/Dashboard" + } + }, + "has_more": { + "type": "boolean", + "description": "True if more items exist after this page." + }, + "next_cursor": { + "type": "string", + "nullable": true, + "description": "Opaque cursor for the next page, or null if no more pages." + } + }, + "required": [ + "data", + "has_more", + "next_cursor" + ] + }, + "Dashboard": { + "type": "object", + "properties": { + "id": { + "type": "string", + "minLength": 1, + "maxLength": 55, + "example": "dash_j572abc123def456" + }, + "html_url": { + "type": "string", + "maxLength": 2048, + "format": "uri", + "description": "Absolute dashboard URL for this resource. OUTPUT_ONLY.", + "example": "https://akua.dev/dashboards/dash_j572abc123def456" + }, + "name": { + "type": "string", + "example": "Cluster Overview" + }, + "description": { + "type": "string", + "nullable": true, + "description": "Optional dashboard description" + }, + "workspace_id": { + "type": "string", + "minLength": 1, + "maxLength": 53 + }, + "purpose": { + "type": "string", + "enum": [ + "workspace_overview", + "custom" + ] + }, + "filter_definitions": { + "type": "array", + "items": { + "oneOf": [ + { + "type": "object", + "properties": { + "kind": { + "type": "string", + "enum": [ + "time" + ] + }, + "key": { + "type": "string", + "enum": [ + "time" + ] + }, + "label": { + "type": "string", + "minLength": 1, + "maxLength": 100 + } + }, + "required": [ + "kind", + "key", + "label" + ], + "additionalProperties": false + }, + { + "type": "object", + "properties": { + "kind": { + "type": "string", + "enum": [ + "comparison" + ] + }, + "key": { + "type": "string", + "enum": [ + "comparison" + ] + }, + "label": { + "type": "string", + "minLength": 1, + "maxLength": 100 + } + }, + "required": [ + "kind", + "key", + "label" + ], + "additionalProperties": false + }, + { + "type": "object", + "properties": { + "kind": { + "type": "string", + "enum": [ + "resource" + ] + }, + "key": { + "type": "string", + "enum": [ + "cluster", + "install", + "product", + "package", + "region" + ] + }, + "resource": { + "type": "string", + "enum": [ + "cluster", + "install", + "product", + "package", + "region" + ] + }, + "label": { + "type": "string", + "minLength": 1, + "maxLength": 100 + } + }, + "required": [ + "kind", + "key", + "resource", + "label" + ], + "additionalProperties": false + }, + { + "type": "object", + "properties": { + "kind": { + "type": "string", + "enum": [ + "status" + ] + }, + "key": { + "type": "string", + "enum": [ + "status" + ] + }, + "label": { + "type": "string", + "minLength": 1, + "maxLength": 100 + }, + "options": { + "type": "array", + "items": { + "type": "string", + "minLength": 1, + "maxLength": 100 + }, + "minItems": 1, + "maxItems": 100 + } + }, + "required": [ + "kind", + "key", + "label", + "options" + ], + "additionalProperties": false + }, + { + "type": "object", + "properties": { + "kind": { + "type": "string", + "enum": [ + "variable" + ] + }, + "key": { + "type": "string", + "pattern": "^var\\.[a-z][a-z0-9_]{0,31}$" + }, + "input": { + "oneOf": [ + { + "type": "object", + "properties": { + "key": { + "type": "string", + "pattern": "^[a-z][a-z0-9_]{0,31}$" + }, + "label": { + "type": "string", + "minLength": 1, + "maxLength": 100 + }, + "description": { + "type": "string", + "maxLength": 500 + }, + "required": { + "type": "boolean" + }, + "kind": { + "type": "string", + "enum": [ + "time_range" + ] + }, + "default": { + "type": "object", + "properties": { + "from": { + "type": "integer" + }, + "to": { + "type": "integer" + } + }, + "required": [ + "from", + "to" + ], + "additionalProperties": false + } + }, + "required": [ + "key", + "label", + "kind" + ], + "additionalProperties": false + }, + { + "type": "object", + "properties": { + "key": { + "type": "string", + "pattern": "^[a-z][a-z0-9_]{0,31}$" + }, + "label": { + "type": "string", + "minLength": 1, + "maxLength": 100 + }, + "description": { + "type": "string", + "maxLength": 500 + }, + "required": { + "type": "boolean" + }, + "kind": { + "type": "string", + "enum": [ + "resource" + ] + }, + "resource": { + "type": "string", + "enum": [ + "cluster", + "install", + "product", + "package", + "region" + ] + }, + "default": { + "anyOf": [ + { + "type": "string", + "maxLength": 255 + }, + { + "type": "array", + "items": { + "type": "string", + "maxLength": 255 + }, + "minItems": 1, + "maxItems": 100 + } + ] + }, + "multiple": { + "type": "boolean" + } + }, + "required": [ + "key", + "label", + "kind", + "resource" + ], + "additionalProperties": false + }, + { + "type": "object", + "properties": { + "key": { + "type": "string", + "pattern": "^[a-z][a-z0-9_]{0,31}$" + }, + "label": { + "type": "string", + "minLength": 1, + "maxLength": 100 + }, + "description": { + "type": "string", + "maxLength": 500 + }, + "required": { + "type": "boolean" + }, + "kind": { + "type": "string", + "enum": [ + "enum" + ] + }, + "options": { + "type": "array", + "items": { + "type": "string", + "minLength": 1, + "maxLength": 100 + }, + "minItems": 1, + "maxItems": 100 + }, + "default": { + "type": "string", + "minLength": 1, + "maxLength": 100 + } + }, + "required": [ + "key", + "label", + "kind", + "options" + ], + "additionalProperties": false + }, + { + "type": "object", + "properties": { + "key": { + "type": "string", + "pattern": "^[a-z][a-z0-9_]{0,31}$" + }, + "label": { + "type": "string", + "minLength": 1, + "maxLength": 100 + }, + "description": { + "type": "string", + "maxLength": 500 + }, + "required": { + "type": "boolean" + }, + "kind": { + "type": "string", + "enum": [ + "boolean" + ] + }, + "default": { + "type": "boolean" + } + }, + "required": [ + "key", + "label", + "kind" + ], + "additionalProperties": false + }, + { + "type": "object", + "properties": { + "key": { + "type": "string", + "pattern": "^[a-z][a-z0-9_]{0,31}$" + }, + "label": { + "type": "string", + "minLength": 1, + "maxLength": 100 + }, + "description": { + "type": "string", + "maxLength": 500 + }, + "required": { + "type": "boolean" + }, + "kind": { + "type": "string", + "enum": [ + "number" + ] + }, + "min": { + "type": "number" + }, + "max": { + "type": "number" + }, + "default": { + "type": "number" + } + }, + "required": [ + "key", + "label", + "kind" + ], + "additionalProperties": false + }, + { + "type": "object", + "properties": { + "key": { + "type": "string", + "pattern": "^[a-z][a-z0-9_]{0,31}$" + }, + "label": { + "type": "string", + "minLength": 1, + "maxLength": 100 + }, + "description": { + "type": "string", + "maxLength": 500 + }, + "required": { + "type": "boolean" + }, + "kind": { + "type": "string", + "enum": [ + "text" + ] + }, + "default": { + "type": "string", + "maxLength": 500 + }, + "max_length": { + "type": "integer", + "minimum": 1, + "maximum": 500 + } + }, + "required": [ + "key", + "label", + "kind" + ], + "additionalProperties": false + } + ] + } + }, + "required": [ + "kind", + "key", + "input" + ], + "additionalProperties": false + } + ] + }, + "maxItems": 24 + }, + "default_filter_values": { + "type": "object", + "additionalProperties": { + "nullable": true + } + }, + "active_revision_id": { + "type": "string", + "nullable": true, + "minLength": 1, + "maxLength": 55 + }, + "widgets": { + "type": "array", + "items": { + "$ref": "#/components/schemas/Widget" + }, + "description": "Output-only denormalized widget list for dashboard read models." + }, + "created_by": { + "type": "string", + "description": "User ID of the dashboard creator" + }, + "created_at": { + "type": "integer", + "minimum": 0, + "description": "Unix timestamp (seconds)" + }, + "updated_at": { + "type": "integer", + "minimum": 0, + "description": "Unix timestamp (seconds)" + }, + "etag": { + "type": "string" + } + }, + "required": [ + "id", + "html_url", + "name", + "description", + "workspace_id", + "purpose", + "filter_definitions", + "default_filter_values", + "active_revision_id", + "widgets", + "created_by", + "created_at", + "updated_at", + "etag" + ] + }, + "Widget": { + "oneOf": [ + { + "type": "object", + "properties": { + "id": { + "type": "string", + "minLength": 1, + "maxLength": 54 + }, + "dashboard_id": { + "type": "string", + "minLength": 1, + "maxLength": 55 + }, + "title": { + "type": "string", + "nullable": true, + "maxLength": 100 + }, + "position": { + "type": "integer" + }, + "col_span": { + "anyOf": [ + { + "type": "number", + "enum": [ + 1 + ] + }, + { + "type": "number", + "enum": [ + 2 + ] + }, + { + "type": "number", + "enum": [ + 3 + ] + }, + { + "type": "number", + "enum": [ + 4 + ] + } + ] + }, + "height": { + "type": "string", + "enum": [ + "compact", + "standard", + "tall" + ] + }, + "drill_down": { + "type": "string", + "nullable": true, + "minLength": 1, + "maxLength": 2048 + }, + "visualization_options": { + "type": "object", + "additionalProperties": { + "nullable": true + } + }, + "freshness_policy": { + "oneOf": [ + { + "type": "object", + "properties": { + "mode": { + "type": "string", + "enum": [ + "provider_default" + ] + } + }, + "required": [ + "mode" + ], + "additionalProperties": false + }, + { + "type": "object", + "properties": { + "mode": { + "type": "string", + "enum": [ + "max_age" + ] + }, + "max_age_seconds": { + "type": "integer", + "minimum": 30, + "maximum": 86400 + } + }, + "required": [ + "mode", + "max_age_seconds" + ], + "additionalProperties": false + } + ] + }, + "created_at": { + "type": "integer", + "minimum": 0, + "description": "Unix timestamp (seconds)" + }, + "updated_at": { + "type": "integer", + "minimum": 0, + "description": "Unix timestamp (seconds)" + }, + "etag": { + "type": "string" + }, + "widget_type": { + "type": "string", + "enum": [ + "platform_metric" + ] + }, + "metric_key": { + "type": "string", + "minLength": 1, + "maxLength": 100, + "pattern": "^[a-z][a-z0-9_]*$" + }, + "metric_version": { + "type": "integer", + "minimum": 0, + "exclusiveMinimum": true + }, + "filter_bindings": { + "type": "object", + "additionalProperties": { + "oneOf": [ + { + "type": "object", + "properties": { + "mode": { + "type": "string", + "enum": [ + "inherit" + ] + }, + "filter_key": { + "anyOf": [ + { + "type": "string", + "enum": [ + "time", + "comparison", + "cluster", + "install", + "product", + "package", + "region", + "status" + ] + }, + { + "type": "string", + "pattern": "^var\\.[a-z][a-z0-9_]{0,31}$" + } + ] + } + }, + "required": [ + "mode", + "filter_key" + ], + "additionalProperties": false + }, + { + "type": "object", + "properties": { + "mode": { + "type": "string", + "enum": [ + "fixed" + ] + }, + "value": { + "nullable": true + } + }, + "required": [ + "mode", + "value" + ], + "additionalProperties": false + }, + { + "type": "object", + "properties": { + "mode": { + "type": "string", + "enum": [ + "unbound" + ] + } + }, + "required": [ + "mode" + ], + "additionalProperties": false + } + ] + } + } + }, + "required": [ + "id", + "dashboard_id", + "title", + "position", + "col_span", + "height", + "drill_down", + "visualization_options", + "freshness_policy", + "created_at", + "updated_at", + "etag", + "widget_type", + "metric_key", + "metric_version", + "filter_bindings" + ], + "additionalProperties": false + }, + { + "type": "object", + "properties": { + "id": { + "type": "string", + "minLength": 1, + "maxLength": 54 + }, + "dashboard_id": { + "type": "string", + "minLength": 1, + "maxLength": 55 + }, + "title": { + "type": "string", + "nullable": true, + "maxLength": 100 + }, + "position": { + "type": "integer" + }, + "col_span": { + "anyOf": [ + { + "type": "number", + "enum": [ + 1 + ] + }, + { + "type": "number", + "enum": [ + 2 + ] + }, + { + "type": "number", + "enum": [ + 3 + ] + }, + { + "type": "number", + "enum": [ + 4 + ] + } + ] + }, + "height": { + "type": "string", + "enum": [ + "compact", + "standard", + "tall" + ] + }, + "drill_down": { + "type": "string", + "nullable": true, + "minLength": 1, + "maxLength": 2048 + }, + "visualization_options": { + "type": "object", + "additionalProperties": { + "nullable": true + } + }, + "freshness_policy": { + "oneOf": [ + { + "type": "object", + "properties": { + "mode": { + "type": "string", + "enum": [ + "provider_default" + ] + } + }, + "required": [ + "mode" + ], + "additionalProperties": false + }, + { + "type": "object", + "properties": { + "mode": { + "type": "string", + "enum": [ + "max_age" + ] + }, + "max_age_seconds": { + "type": "integer", + "minimum": 30, + "maximum": 86400 + } + }, + "required": [ + "mode", + "max_age_seconds" + ], + "additionalProperties": false + } + ] + }, + "created_at": { + "type": "integer", + "minimum": 0, + "description": "Unix timestamp (seconds)" + }, + "updated_at": { + "type": "integer", + "minimum": 0, + "description": "Unix timestamp (seconds)" + }, + "etag": { + "type": "string" + }, + "widget_type": { + "type": "string", + "enum": [ + "snippet" + ] + }, + "snippet_id": { + "type": "string", + "minLength": 1, + "maxLength": 54 + }, + "snippet_etag": { + "type": "string", + "nullable": true + }, + "input_bindings": { + "type": "object", + "additionalProperties": { + "oneOf": [ + { + "type": "object", + "properties": { + "mode": { + "type": "string", + "enum": [ + "inherit" + ] + }, + "filter_key": { + "anyOf": [ + { + "type": "string", + "enum": [ + "time", + "comparison", + "cluster", + "install", + "product", + "package", + "region", + "status" + ] + }, + { + "type": "string", + "pattern": "^var\\.[a-z][a-z0-9_]{0,31}$" + } + ] + } + }, + "required": [ + "mode", + "filter_key" + ], + "additionalProperties": false + }, + { + "type": "object", + "properties": { + "mode": { + "type": "string", + "enum": [ + "fixed" + ] + }, + "value": { + "nullable": true + } + }, + "required": [ + "mode", + "value" + ], + "additionalProperties": false + }, + { + "type": "object", + "properties": { + "mode": { + "type": "string", + "enum": [ + "unbound" + ] + } + }, + "required": [ + "mode" + ], + "additionalProperties": false + } + ] + } + }, + "visualization": { + "type": "string", + "nullable": true, + "enum": [ + "stat", + "sparkline", + "line", + "area", + "bar", + "donut", + "table", + "status_list", + "logs", + "json", + null + ] + }, + "refresh_policy": { + "oneOf": [ + { + "type": "object", + "properties": { + "mode": { + "type": "string", + "enum": [ + "on_load" + ] + } + }, + "required": [ + "mode" + ], + "additionalProperties": false + }, + { + "type": "object", + "properties": { + "mode": { + "type": "string", + "enum": [ + "manual" + ] + } + }, + "required": [ + "mode" + ], + "additionalProperties": false + }, + { + "type": "object", + "properties": { + "mode": { + "type": "string", + "enum": [ + "interval" + ] + }, + "interval_seconds": { + "type": "integer", + "minimum": 60, + "maximum": 86400 + } + }, + "required": [ + "mode", + "interval_seconds" + ], + "additionalProperties": false + } + ] + }, + "display_type": { + "type": "string", + "nullable": true, + "enum": [ + "table", + "stat", + "json", + "logs", + "timeseries", + null + ], + "description": "Controls how the snippet result is rendered in dashboard widgets" + } + }, + "required": [ + "id", + "dashboard_id", + "title", + "position", + "col_span", + "height", + "drill_down", + "visualization_options", + "freshness_policy", + "created_at", + "updated_at", + "etag", + "widget_type", + "snippet_id", + "snippet_etag", + "input_bindings", + "visualization", + "refresh_policy", + "display_type" + ], + "additionalProperties": false + } + ], + "x-platform-exact-union": true + }, + "DashboardRevisionList": { + "type": "object", + "properties": { + "data": { + "type": "array", + "items": { + "$ref": "#/components/schemas/DashboardRevision" + } + }, + "has_more": { + "type": "boolean", + "description": "True if more items exist after this page." + }, + "next_cursor": { + "type": "string", + "nullable": true, + "description": "Opaque cursor for the next page, or null if no more pages." + } + }, + "required": [ + "data", + "has_more", + "next_cursor" + ] + }, + "DashboardRevision": { + "type": "object", + "properties": { + "id": { + "type": "string", + "minLength": 1, + "maxLength": 55 + }, + "dashboard_id": { + "type": "string", + "minLength": 1, + "maxLength": 55 + }, + "workspace_id": { + "type": "string", + "minLength": 1, + "maxLength": 53 + }, + "parent_revision_id": { + "type": "string", + "nullable": true, + "minLength": 1, + "maxLength": 55 + }, + "restored_from_revision_id": { + "type": "string", + "nullable": true, + "minLength": 1, + "maxLength": 55 + }, + "source": { + "type": "string", + "enum": [ + "manual", + "automatic", + "restore", + "reset", + "backfill" + ] + }, + "author_id": { + "type": "string" + }, + "summary": { + "type": "string", + "nullable": true + }, + "name": { + "type": "string" + }, + "description": { + "type": "string", + "nullable": true + }, + "purpose": { + "type": "string", + "enum": [ + "workspace_overview", + "custom" + ] + }, + "filter_definitions": { + "type": "array", + "items": { + "oneOf": [ + { + "type": "object", + "properties": { + "kind": { + "type": "string", + "enum": [ + "time" + ] + }, + "key": { + "type": "string", + "enum": [ + "time" + ] + }, + "label": { + "type": "string", + "minLength": 1, + "maxLength": 100 + } + }, + "required": [ + "kind", + "key", + "label" + ], + "additionalProperties": false + }, + { + "type": "object", + "properties": { + "kind": { + "type": "string", + "enum": [ + "comparison" + ] + }, + "key": { + "type": "string", + "enum": [ + "comparison" + ] + }, + "label": { + "type": "string", + "minLength": 1, + "maxLength": 100 + } + }, + "required": [ + "kind", + "key", + "label" + ], + "additionalProperties": false + }, + { + "type": "object", + "properties": { + "kind": { + "type": "string", + "enum": [ + "resource" + ] + }, + "key": { + "type": "string", + "enum": [ + "cluster", + "install", + "product", + "package", + "region" + ] + }, + "resource": { + "type": "string", + "enum": [ + "cluster", + "install", + "product", + "package", + "region" + ] + }, + "label": { + "type": "string", + "minLength": 1, + "maxLength": 100 + } + }, + "required": [ + "kind", + "key", + "resource", + "label" + ], + "additionalProperties": false + }, + { + "type": "object", + "properties": { + "kind": { + "type": "string", + "enum": [ + "status" + ] + }, + "key": { + "type": "string", + "enum": [ + "status" + ] + }, + "label": { + "type": "string", + "minLength": 1, + "maxLength": 100 + }, + "options": { + "type": "array", + "items": { + "type": "string", + "minLength": 1, + "maxLength": 100 + }, + "minItems": 1, + "maxItems": 100 + } + }, + "required": [ + "kind", + "key", + "label", + "options" + ], + "additionalProperties": false + }, + { + "type": "object", + "properties": { + "kind": { + "type": "string", + "enum": [ + "variable" + ] + }, + "key": { + "type": "string", + "pattern": "^var\\.[a-z][a-z0-9_]{0,31}$" + }, + "input": { + "oneOf": [ + { + "type": "object", + "properties": { + "key": { + "type": "string", + "pattern": "^[a-z][a-z0-9_]{0,31}$" + }, + "label": { + "type": "string", + "minLength": 1, + "maxLength": 100 + }, + "description": { + "type": "string", + "maxLength": 500 + }, + "required": { + "type": "boolean" + }, + "kind": { + "type": "string", + "enum": [ + "time_range" + ] + }, + "default": { + "type": "object", + "properties": { + "from": { + "type": "integer" + }, + "to": { + "type": "integer" + } + }, + "required": [ + "from", + "to" + ], + "additionalProperties": false + } + }, + "required": [ + "key", + "label", + "kind" + ], + "additionalProperties": false + }, + { + "type": "object", + "properties": { + "key": { + "type": "string", + "pattern": "^[a-z][a-z0-9_]{0,31}$" + }, + "label": { + "type": "string", + "minLength": 1, + "maxLength": 100 + }, + "description": { + "type": "string", + "maxLength": 500 + }, + "required": { + "type": "boolean" + }, + "kind": { + "type": "string", + "enum": [ + "resource" + ] + }, + "resource": { + "type": "string", + "enum": [ + "cluster", + "install", + "product", + "package", + "region" + ] + }, + "default": { + "anyOf": [ + { + "type": "string", + "maxLength": 255 + }, + { + "type": "array", + "items": { + "type": "string", + "maxLength": 255 + }, + "minItems": 1, + "maxItems": 100 + } + ] + }, + "multiple": { + "type": "boolean" + } + }, + "required": [ + "key", + "label", + "kind", + "resource" + ], + "additionalProperties": false + }, + { + "type": "object", + "properties": { + "key": { + "type": "string", + "pattern": "^[a-z][a-z0-9_]{0,31}$" + }, + "label": { + "type": "string", + "minLength": 1, + "maxLength": 100 + }, + "description": { + "type": "string", + "maxLength": 500 + }, + "required": { + "type": "boolean" + }, + "kind": { + "type": "string", + "enum": [ + "enum" + ] + }, + "options": { + "type": "array", + "items": { + "type": "string", + "minLength": 1, + "maxLength": 100 + }, + "minItems": 1, + "maxItems": 100 + }, + "default": { + "type": "string", + "minLength": 1, + "maxLength": 100 + } + }, + "required": [ + "key", + "label", + "kind", + "options" + ], + "additionalProperties": false + }, + { + "type": "object", + "properties": { + "key": { + "type": "string", + "pattern": "^[a-z][a-z0-9_]{0,31}$" + }, + "label": { + "type": "string", + "minLength": 1, + "maxLength": 100 + }, + "description": { + "type": "string", + "maxLength": 500 + }, + "required": { + "type": "boolean" + }, + "kind": { + "type": "string", + "enum": [ + "boolean" + ] + }, + "default": { + "type": "boolean" + } + }, + "required": [ + "key", + "label", + "kind" + ], + "additionalProperties": false + }, + { + "type": "object", + "properties": { + "key": { + "type": "string", + "pattern": "^[a-z][a-z0-9_]{0,31}$" + }, + "label": { + "type": "string", + "minLength": 1, + "maxLength": 100 + }, + "description": { + "type": "string", + "maxLength": 500 + }, + "required": { + "type": "boolean" + }, + "kind": { + "type": "string", + "enum": [ + "number" + ] + }, + "min": { + "type": "number" + }, + "max": { + "type": "number" + }, + "default": { + "type": "number" + } + }, + "required": [ + "key", + "label", + "kind" + ], + "additionalProperties": false + }, + { + "type": "object", + "properties": { + "key": { + "type": "string", + "pattern": "^[a-z][a-z0-9_]{0,31}$" + }, + "label": { + "type": "string", + "minLength": 1, + "maxLength": 100 + }, + "description": { + "type": "string", + "maxLength": 500 + }, + "required": { + "type": "boolean" + }, + "kind": { + "type": "string", + "enum": [ + "text" + ] + }, + "default": { + "type": "string", + "maxLength": 500 + }, + "max_length": { + "type": "integer", + "minimum": 1, + "maximum": 500 + } + }, + "required": [ + "key", + "label", + "kind" + ], + "additionalProperties": false + } + ] + } + }, + "required": [ + "kind", + "key", + "input" + ], + "additionalProperties": false + } + ] + }, + "maxItems": 24 + }, + "default_filter_values": { + "type": "object", + "additionalProperties": { + "nullable": true + } + }, + "widgets": { + "type": "array", + "items": { + "oneOf": [ + { + "type": "object", + "properties": { + "widget_id": { + "type": "string", + "minLength": 1, + "maxLength": 54 + }, + "position": { + "type": "integer", + "minimum": 0 + }, + "title": { + "type": "string", + "nullable": true, + "maxLength": 100 + }, + "col_span": { + "anyOf": [ + { + "type": "number", + "enum": [ + 1 + ] + }, + { + "type": "number", + "enum": [ + 2 + ] + }, + { + "type": "number", + "enum": [ + 3 + ] + }, + { + "type": "number", + "enum": [ + 4 + ] + } + ] + }, + "height": { + "type": "string", + "enum": [ + "compact", + "standard", + "tall" + ] + }, + "drill_down": { + "type": "string", + "nullable": true, + "minLength": 1, + "maxLength": 2048 + }, + "visualization_options": { + "type": "object", + "additionalProperties": { + "nullable": true + } + }, + "freshness_policy": { + "oneOf": [ + { + "type": "object", + "properties": { + "mode": { + "type": "string", + "enum": [ + "provider_default" + ] + } + }, + "required": [ + "mode" + ], + "additionalProperties": false + }, + { + "type": "object", + "properties": { + "mode": { + "type": "string", + "enum": [ + "max_age" + ] + }, + "max_age_seconds": { + "type": "integer", + "minimum": 30, + "maximum": 86400 + } + }, + "required": [ + "mode", + "max_age_seconds" + ], + "additionalProperties": false + } + ] + }, + "widget_type": { + "type": "string", + "enum": [ + "snippet" + ] + }, + "snippet_id": { + "type": "string", + "minLength": 1, + "maxLength": 54 + }, + "snippet_etag": { + "type": "string" + }, + "input_bindings": { + "type": "object", + "additionalProperties": { + "oneOf": [ + { + "type": "object", + "properties": { + "mode": { + "type": "string", + "enum": [ + "inherit" + ] + }, + "filter_key": { + "anyOf": [ + { + "type": "string", + "enum": [ + "time", + "comparison", + "cluster", + "install", + "product", + "package", + "region", + "status" + ] + }, + { + "type": "string", + "pattern": "^var\\.[a-z][a-z0-9_]{0,31}$" + } + ] + } + }, + "required": [ + "mode", + "filter_key" + ], + "additionalProperties": false + }, + { + "type": "object", + "properties": { + "mode": { + "type": "string", + "enum": [ + "fixed" + ] + }, + "value": { + "nullable": true + } + }, + "required": [ + "mode", + "value" + ], + "additionalProperties": false + }, + { + "type": "object", + "properties": { + "mode": { + "type": "string", + "enum": [ + "unbound" + ] + } + }, + "required": [ + "mode" + ], + "additionalProperties": false + } + ] + } + }, + "visualization": { + "type": "string", + "nullable": true, + "enum": [ + "stat", + "sparkline", + "line", + "area", + "bar", + "donut", + "table", + "status_list", + "logs", + "json", + null + ] + }, + "refresh_policy": { + "oneOf": [ + { + "type": "object", + "properties": { + "mode": { + "type": "string", + "enum": [ + "on_load" + ] + } + }, + "required": [ + "mode" + ], + "additionalProperties": false + }, + { + "type": "object", + "properties": { + "mode": { + "type": "string", + "enum": [ + "manual" + ] + } + }, + "required": [ + "mode" + ], + "additionalProperties": false + }, + { + "type": "object", + "properties": { + "mode": { + "type": "string", + "enum": [ + "interval" + ] + }, + "interval_seconds": { + "type": "integer", + "minimum": 60, + "maximum": 86400 + } + }, + "required": [ + "mode", + "interval_seconds" + ], + "additionalProperties": false + } + ] + }, + "display_type": { + "type": "string", + "nullable": true, + "enum": [ + "table", + "stat", + "json", + "logs", + "timeseries", + null + ], + "description": "Controls how the snippet result is rendered in dashboard widgets" + } + }, + "required": [ + "widget_id", + "position", + "title", + "col_span", + "height", + "drill_down", + "visualization_options", + "freshness_policy", + "widget_type", + "snippet_id", + "snippet_etag", + "input_bindings", + "visualization", + "refresh_policy", + "display_type" + ], + "additionalProperties": false + }, + { + "type": "object", + "properties": { + "widget_id": { + "type": "string", + "minLength": 1, + "maxLength": 54 + }, + "position": { + "type": "integer", + "minimum": 0 + }, + "title": { + "type": "string", + "nullable": true, + "maxLength": 100 + }, + "col_span": { + "anyOf": [ + { + "type": "number", + "enum": [ + 1 + ] + }, + { + "type": "number", + "enum": [ + 2 + ] + }, + { + "type": "number", + "enum": [ + 3 + ] + }, + { + "type": "number", + "enum": [ + 4 + ] + } + ] + }, + "height": { + "type": "string", + "enum": [ + "compact", + "standard", + "tall" + ] + }, + "drill_down": { + "type": "string", + "nullable": true, + "minLength": 1, + "maxLength": 2048 + }, + "visualization_options": { + "type": "object", + "additionalProperties": { + "nullable": true + } + }, + "freshness_policy": { + "oneOf": [ + { + "type": "object", + "properties": { + "mode": { + "type": "string", + "enum": [ + "provider_default" + ] + } + }, + "required": [ + "mode" + ], + "additionalProperties": false + }, + { + "type": "object", + "properties": { + "mode": { + "type": "string", + "enum": [ + "max_age" + ] + }, + "max_age_seconds": { + "type": "integer", + "minimum": 30, + "maximum": 86400 + } + }, + "required": [ + "mode", + "max_age_seconds" + ], + "additionalProperties": false + } + ] + }, + "widget_type": { + "type": "string", + "enum": [ + "platform_metric" + ] + }, + "metric_key": { + "type": "string", + "minLength": 1, + "maxLength": 100, + "pattern": "^[a-z][a-z0-9_]*$" + }, + "metric_version": { + "type": "integer", + "minimum": 0, + "exclusiveMinimum": true + }, + "filter_bindings": { + "type": "object", + "additionalProperties": { + "oneOf": [ + { + "type": "object", + "properties": { + "mode": { + "type": "string", + "enum": [ + "inherit" + ] + }, + "filter_key": { + "anyOf": [ + { + "type": "string", + "enum": [ + "time", + "comparison", + "cluster", + "install", + "product", + "package", + "region", + "status" + ] + }, + { + "type": "string", + "pattern": "^var\\.[a-z][a-z0-9_]{0,31}$" + } + ] + } + }, + "required": [ + "mode", + "filter_key" + ], + "additionalProperties": false + }, + { + "type": "object", + "properties": { + "mode": { + "type": "string", + "enum": [ + "fixed" + ] + }, + "value": { + "nullable": true + } + }, + "required": [ + "mode", + "value" + ], + "additionalProperties": false + }, + { + "type": "object", + "properties": { + "mode": { + "type": "string", + "enum": [ + "unbound" + ] + } + }, + "required": [ + "mode" + ], + "additionalProperties": false + } + ] + } + } + }, + "required": [ + "widget_id", + "position", + "title", + "col_span", + "height", + "drill_down", + "visualization_options", + "freshness_policy", + "widget_type", + "metric_key", + "metric_version", + "filter_bindings" + ], + "additionalProperties": false + } + ] + } + }, + "structural_diff": { + "type": "object", + "nullable": true, + "properties": { + "version": { + "type": "number", + "enum": [ + 1 + ] + }, + "dashboard_fields": { + "type": "array", + "items": { + "type": "string", + "enum": [ + "name", + "description", + "purpose", + "filter_definitions", + "default_filter_values" + ] + } + }, + "widgets": { + "type": "object", + "properties": { + "added": { + "type": "object", + "properties": { + "count": { + "type": "integer", + "minimum": 0 + }, + "widget_ids": { + "type": "array", + "items": { + "type": "string", + "minLength": 1, + "maxLength": 54 + } + } + }, + "required": [ + "count", + "widget_ids" + ], + "additionalProperties": false + }, + "removed": { + "type": "object", + "properties": { + "count": { + "type": "integer", + "minimum": 0 + }, + "widget_ids": { + "type": "array", + "items": { + "type": "string", + "minLength": 1, + "maxLength": 54 + } + } + }, + "required": [ + "count", + "widget_ids" + ], + "additionalProperties": false + }, + "changed": { + "type": "object", + "properties": { + "count": { + "type": "integer", + "minimum": 0 + }, + "widgets": { + "type": "array", + "items": { + "type": "object", + "properties": { + "widget_id": { + "type": "string", + "minLength": 1, + "maxLength": 54 + }, + "fields": { + "type": "array", + "items": { + "type": "string", + "enum": [ + "position", + "title", + "col_span", + "height", + "drill_down", + "visualization_options", + "freshness_policy", + "widget_type", + "snippet_id", + "input_bindings", + "visualization", + "refresh_policy", + "display_type", + "metric_key", + "metric_version", + "filter_bindings" + ] + } + } + }, + "required": [ + "widget_id", + "fields" + ], + "additionalProperties": false + } + } + }, + "required": [ + "count", + "widgets" + ], + "additionalProperties": false + } + }, + "required": [ + "added", + "removed", + "changed" + ], + "additionalProperties": false + } + }, + "required": [ + "version", + "dashboard_fields", + "widgets" + ], + "additionalProperties": false + }, + "snippet_etag_drift": { + "type": "array", + "items": { + "type": "object", + "properties": { + "widget_id": { + "type": "string", + "minLength": 1, + "maxLength": 54 + }, + "snippet_id": { + "type": "string", + "minLength": 1, + "maxLength": 54 + }, + "snapshot_etag": { + "type": "string" + }, + "current_etag": { + "type": "string", + "nullable": true + }, + "current_state": { + "type": "string", + "enum": [ + "active", + "archived", + "missing" + ] + }, + "restore_action": { + "type": "string", + "enum": [ + "none", + "reactivate", + "blocked" + ] + } + }, + "required": [ + "widget_id", + "snippet_id", + "snapshot_etag", + "current_etag", + "current_state", + "restore_action" + ], + "additionalProperties": false + } + }, + "created_at": { + "type": "integer", + "minimum": 0, + "description": "Unix timestamp (seconds)" + } + }, + "required": [ + "id", + "dashboard_id", + "workspace_id", + "parent_revision_id", + "restored_from_revision_id", + "source", + "author_id", + "summary", + "name", + "description", + "purpose", + "filter_definitions", + "default_filter_values", + "widgets", + "structural_diff", + "snippet_etag_drift", + "created_at" + ], + "additionalProperties": false + }, + "DashboardRevisionMutationResponse": { + "allOf": [ + { + "$ref": "#/components/schemas/DashboardRevision" + }, + { + "type": "object", + "properties": { + "dashboard_etag": { + "type": "string" + } + }, + "required": [ + "dashboard_etag" + ], + "additionalProperties": false + } + ] + }, + "CreateDashboardWidgetBody": { + "oneOf": [ + { + "type": "object", + "properties": { + "snippet_id": { + "type": "string", + "minLength": 1, + "maxLength": 54 + }, + "title": { + "type": "string", + "maxLength": 100 + }, + "col_span": { + "anyOf": [ + { + "type": "number", + "enum": [ + 1 + ] + }, + { + "type": "number", + "enum": [ + 2 + ] + }, + { + "type": "number", + "enum": [ + 3 + ] + }, + { + "type": "number", + "enum": [ + 4 + ] + } + ] + }, + "display_type": { + "type": "string", + "nullable": true, + "enum": [ + "table", + "stat", + "json", + "logs", + "timeseries", + null + ], + "description": "Controls how the snippet result is rendered in dashboard widgets" + }, + "position": { + "type": "integer" + } + }, + "required": [ + "snippet_id", + "col_span" + ], + "additionalProperties": false + }, + { + "type": "object", + "properties": { + "title": { + "type": "string", + "maxLength": 100 + }, + "col_span": { + "anyOf": [ + { + "type": "number", + "enum": [ + 1 + ] + }, + { + "type": "number", + "enum": [ + 2 + ] + }, + { + "type": "number", + "enum": [ + 3 + ] + }, + { + "type": "number", + "enum": [ + 4 + ] + } + ] + }, + "position": { + "type": "integer" + }, + "height": { + "type": "string", + "enum": [ + "compact", + "standard", + "tall" + ], + "default": "standard" + }, + "drill_down": { + "type": "string", + "nullable": true, + "minLength": 1, + "maxLength": 2048, + "default": null + }, + "visualization_options": { + "type": "object", + "additionalProperties": { + "nullable": true + }, + "default": {} + }, + "freshness_policy": { + "oneOf": [ + { + "type": "object", + "properties": { + "mode": { + "type": "string", + "enum": [ + "provider_default" + ] + } + }, + "required": [ + "mode" + ], + "additionalProperties": false + }, + { + "type": "object", + "properties": { + "mode": { + "type": "string", + "enum": [ + "max_age" + ] + }, + "max_age_seconds": { + "type": "integer", + "minimum": 30, + "maximum": 86400 + } + }, + "required": [ + "mode", + "max_age_seconds" + ], + "additionalProperties": false + } + ], + "default": { + "mode": "provider_default" + } + }, + "widget_type": { + "type": "string", + "enum": [ + "snippet" + ] + }, + "snippet_id": { + "type": "string", + "minLength": 1, + "maxLength": 54 + }, + "snippet_etag": { + "type": "string", + "nullable": true, + "default": null + }, + "input_bindings": { + "type": "object", + "additionalProperties": { + "oneOf": [ + { + "type": "object", + "properties": { + "mode": { + "type": "string", + "enum": [ + "inherit" + ] + }, + "filter_key": { + "anyOf": [ + { + "type": "string", + "enum": [ + "time", + "comparison", + "cluster", + "install", + "product", + "package", + "region", + "status" + ] + }, + { + "type": "string", + "pattern": "^var\\.[a-z][a-z0-9_]{0,31}$" + } + ] + } + }, + "required": [ + "mode", + "filter_key" + ], + "additionalProperties": false + }, + { + "type": "object", + "properties": { + "mode": { + "type": "string", + "enum": [ + "fixed" + ] + }, + "value": { + "nullable": true + } + }, + "required": [ + "mode", + "value" + ], + "additionalProperties": false + }, + { + "type": "object", + "properties": { + "mode": { + "type": "string", + "enum": [ + "unbound" + ] + } + }, + "required": [ + "mode" + ], + "additionalProperties": false + } + ] + }, + "default": {} + }, + "visualization": { + "type": "string", + "nullable": true, + "enum": [ + "stat", + "sparkline", + "line", + "area", + "bar", + "donut", + "table", + "status_list", + "logs", + "json", + null + ], + "default": null + }, + "refresh_policy": { + "oneOf": [ + { + "type": "object", + "properties": { + "mode": { + "type": "string", + "enum": [ + "on_load" + ] + } + }, + "required": [ + "mode" + ], + "additionalProperties": false + }, + { + "type": "object", + "properties": { + "mode": { + "type": "string", + "enum": [ + "manual" + ] + } + }, + "required": [ + "mode" + ], + "additionalProperties": false + }, + { + "type": "object", + "properties": { + "mode": { + "type": "string", + "enum": [ + "interval" + ] + }, + "interval_seconds": { + "type": "integer", + "minimum": 60, + "maximum": 86400 + } + }, + "required": [ + "mode", + "interval_seconds" + ], + "additionalProperties": false + } + ], + "default": { + "mode": "on_load" + } + }, + "display_type": { + "type": "string", + "nullable": true, + "enum": [ + "table", + "stat", + "json", + "logs", + "timeseries", + null + ], + "default": null, + "description": "Controls how the snippet result is rendered in dashboard widgets" + } + }, + "required": [ + "col_span", + "widget_type", + "snippet_id" + ], + "additionalProperties": false + }, + { + "type": "object", + "properties": { + "title": { + "type": "string", + "maxLength": 100 + }, + "col_span": { + "anyOf": [ + { + "type": "number", + "enum": [ + 1 + ] + }, + { + "type": "number", + "enum": [ + 2 + ] + }, + { + "type": "number", + "enum": [ + 3 + ] + }, + { + "type": "number", + "enum": [ + 4 + ] + } + ] + }, + "position": { + "type": "integer" + }, + "height": { + "type": "string", + "enum": [ + "compact", + "standard", + "tall" + ], + "default": "standard" + }, + "drill_down": { + "type": "string", + "nullable": true, + "minLength": 1, + "maxLength": 2048, + "default": null + }, + "visualization_options": { + "type": "object", + "additionalProperties": { + "nullable": true + }, + "default": {} + }, + "freshness_policy": { + "oneOf": [ + { + "type": "object", + "properties": { + "mode": { + "type": "string", + "enum": [ + "provider_default" + ] + } + }, + "required": [ + "mode" + ], + "additionalProperties": false + }, + { + "type": "object", + "properties": { + "mode": { + "type": "string", + "enum": [ + "max_age" + ] + }, + "max_age_seconds": { + "type": "integer", + "minimum": 30, + "maximum": 86400 + } + }, + "required": [ + "mode", + "max_age_seconds" + ], + "additionalProperties": false + } + ], + "default": { + "mode": "provider_default" + } + }, + "widget_type": { + "type": "string", + "enum": [ + "platform_metric" + ] + }, + "metric_key": { + "type": "string", + "minLength": 1, + "maxLength": 100, + "pattern": "^[a-z][a-z0-9_]*$" + }, + "metric_version": { + "type": "integer", + "minimum": 0, + "exclusiveMinimum": true + }, + "filter_bindings": { + "type": "object", + "additionalProperties": { + "oneOf": [ + { + "type": "object", + "properties": { + "mode": { + "type": "string", + "enum": [ + "inherit" + ] + }, + "filter_key": { + "anyOf": [ + { + "type": "string", + "enum": [ + "time", + "comparison", + "cluster", + "install", + "product", + "package", + "region", + "status" + ] + }, + { + "type": "string", + "pattern": "^var\\.[a-z][a-z0-9_]{0,31}$" + } + ] + } + }, + "required": [ + "mode", + "filter_key" + ], + "additionalProperties": false + }, + { + "type": "object", + "properties": { + "mode": { + "type": "string", + "enum": [ + "fixed" + ] + }, + "value": { + "nullable": true + } + }, + "required": [ + "mode", + "value" + ], + "additionalProperties": false + }, + { + "type": "object", + "properties": { + "mode": { + "type": "string", + "enum": [ + "unbound" + ] + } + }, + "required": [ + "mode" + ], + "additionalProperties": false + } + ] + }, + "default": {} + } + }, + "required": [ + "col_span", + "widget_type", + "metric_key", + "metric_version" + ], + "additionalProperties": false + } + ], + "x-platform-exact-union": true + }, + "WidgetList": { + "type": "object", + "properties": { + "data": { + "type": "array", + "items": { + "$ref": "#/components/schemas/Widget" + } + }, + "has_more": { + "type": "boolean", + "description": "True if more items exist after this page." + }, + "next_cursor": { + "type": "string", + "nullable": true, + "description": "Opaque cursor for the next page, or null if no more pages." + } + }, + "required": [ + "data", + "has_more", + "next_cursor" + ] + }, + "UpdateDashboardWidgetBody": { + "oneOf": [ + { + "type": "object", + "properties": { + "title": { + "type": "string", + "nullable": true, + "maxLength": 100 + }, + "col_span": { + "anyOf": [ + { + "type": "number", + "enum": [ + 1 + ] + }, + { + "type": "number", + "enum": [ + 2 + ] + }, + { + "type": "number", + "enum": [ + 3 + ] + }, + { + "type": "number", + "enum": [ + 4 + ] + } + ] + }, + "position": { + "type": "integer" + }, + "display_type": { + "type": "string", + "nullable": true, + "enum": [ + "table", + "stat", + "json", + "logs", + "timeseries", + null + ], + "description": "Controls how the snippet result is rendered in dashboard widgets" + } + }, + "additionalProperties": false + }, + { + "type": "object", + "properties": { + "title": { + "type": "string", + "nullable": true, + "maxLength": 100 + }, + "col_span": { + "anyOf": [ + { + "type": "number", + "enum": [ + 1 + ] + }, + { + "type": "number", + "enum": [ + 2 + ] + }, + { + "type": "number", + "enum": [ + 3 + ] + }, + { + "type": "number", + "enum": [ + 4 + ] + } + ] + }, + "position": { + "type": "integer" + }, + "height": { + "type": "string", + "enum": [ + "compact", + "standard", + "tall" + ] + }, + "drill_down": { + "type": "string", + "nullable": true, + "minLength": 1, + "maxLength": 2048 + }, + "visualization_options": { + "type": "object", + "additionalProperties": { + "nullable": true + } + }, + "freshness_policy": { + "oneOf": [ + { + "type": "object", + "properties": { + "mode": { + "type": "string", + "enum": [ + "provider_default" + ] + } + }, + "required": [ + "mode" + ], + "additionalProperties": false + }, + { + "type": "object", + "properties": { + "mode": { + "type": "string", + "enum": [ + "max_age" + ] + }, + "max_age_seconds": { + "type": "integer", + "minimum": 30, + "maximum": 86400 + } + }, + "required": [ + "mode", + "max_age_seconds" + ], + "additionalProperties": false + } + ] + }, + "widget_type": { + "type": "string", + "enum": [ + "snippet" + ] + }, + "snippet_etag": { + "type": "string", + "nullable": true + }, + "input_bindings": { + "type": "object", + "additionalProperties": { + "oneOf": [ + { + "type": "object", + "properties": { + "mode": { + "type": "string", + "enum": [ + "inherit" + ] + }, + "filter_key": { + "anyOf": [ + { + "type": "string", + "enum": [ + "time", + "comparison", + "cluster", + "install", + "product", + "package", + "region", + "status" + ] + }, + { + "type": "string", + "pattern": "^var\\.[a-z][a-z0-9_]{0,31}$" + } + ] + } + }, + "required": [ + "mode", + "filter_key" + ], + "additionalProperties": false + }, + { + "type": "object", + "properties": { + "mode": { + "type": "string", + "enum": [ + "fixed" + ] + }, + "value": { + "nullable": true + } + }, + "required": [ + "mode", + "value" + ], + "additionalProperties": false + }, + { + "type": "object", + "properties": { + "mode": { + "type": "string", + "enum": [ + "unbound" + ] + } + }, + "required": [ + "mode" + ], + "additionalProperties": false + } + ] + } + }, + "visualization": { + "type": "string", + "nullable": true, + "enum": [ + "stat", + "sparkline", + "line", + "area", + "bar", + "donut", + "table", + "status_list", + "logs", + "json", + null + ] + }, + "refresh_policy": { + "oneOf": [ + { + "type": "object", + "properties": { + "mode": { + "type": "string", + "enum": [ + "on_load" + ] + } + }, + "required": [ + "mode" + ], + "additionalProperties": false + }, + { + "type": "object", + "properties": { + "mode": { + "type": "string", + "enum": [ + "manual" + ] + } + }, + "required": [ + "mode" + ], + "additionalProperties": false + }, + { + "type": "object", + "properties": { + "mode": { + "type": "string", + "enum": [ + "interval" + ] + }, + "interval_seconds": { + "type": "integer", + "minimum": 60, + "maximum": 86400 + } + }, + "required": [ + "mode", + "interval_seconds" + ], + "additionalProperties": false + } + ] + }, + "display_type": { + "type": "string", + "nullable": true, + "enum": [ + "table", + "stat", + "json", + "logs", + "timeseries", + null + ], + "description": "Controls how the snippet result is rendered in dashboard widgets" + } + }, + "required": [ + "widget_type" + ], + "additionalProperties": false + }, + { + "type": "object", + "properties": { + "title": { + "type": "string", + "nullable": true, + "maxLength": 100 + }, + "col_span": { + "anyOf": [ + { + "type": "number", + "enum": [ + 1 + ] + }, + { + "type": "number", + "enum": [ + 2 + ] + }, + { + "type": "number", + "enum": [ + 3 + ] + }, + { + "type": "number", + "enum": [ + 4 + ] + } + ] + }, + "position": { + "type": "integer" + }, + "height": { + "type": "string", + "enum": [ + "compact", + "standard", + "tall" + ] + }, + "drill_down": { + "type": "string", + "nullable": true, + "minLength": 1, + "maxLength": 2048 + }, + "visualization_options": { + "type": "object", + "additionalProperties": { + "nullable": true + } + }, + "freshness_policy": { + "oneOf": [ + { + "type": "object", + "properties": { + "mode": { + "type": "string", + "enum": [ + "provider_default" + ] + } + }, + "required": [ + "mode" + ], + "additionalProperties": false + }, + { + "type": "object", + "properties": { + "mode": { + "type": "string", + "enum": [ + "max_age" + ] + }, + "max_age_seconds": { + "type": "integer", + "minimum": 30, + "maximum": 86400 + } + }, + "required": [ + "mode", + "max_age_seconds" + ], + "additionalProperties": false + } + ] + }, + "widget_type": { + "type": "string", + "enum": [ + "platform_metric" + ] + }, + "metric_key": { + "type": "string", + "minLength": 1, + "maxLength": 100, + "pattern": "^[a-z][a-z0-9_]*$" + }, + "metric_version": { + "type": "integer", + "minimum": 0, + "exclusiveMinimum": true + }, + "filter_bindings": { + "type": "object", + "additionalProperties": { + "oneOf": [ + { + "type": "object", + "properties": { + "mode": { + "type": "string", + "enum": [ + "inherit" + ] + }, + "filter_key": { + "anyOf": [ + { + "type": "string", + "enum": [ + "time", + "comparison", + "cluster", + "install", + "product", + "package", + "region", + "status" + ] + }, + { + "type": "string", + "pattern": "^var\\.[a-z][a-z0-9_]{0,31}$" + } + ] + } + }, + "required": [ + "mode", + "filter_key" + ], + "additionalProperties": false + }, + { + "type": "object", + "properties": { + "mode": { + "type": "string", + "enum": [ + "fixed" + ] + }, + "value": { + "nullable": true + } + }, + "required": [ + "mode", + "value" + ], + "additionalProperties": false + }, + { + "type": "object", + "properties": { + "mode": { + "type": "string", + "enum": [ + "unbound" + ] + } + }, + "required": [ + "mode" + ], + "additionalProperties": false + } + ] + } + } + }, + "required": [ + "widget_type" + ], + "additionalProperties": false + } + ], + "x-platform-exact-union": true + }, + "ClusterRuntimeMachine": { + "type": "object", + "properties": { + "provider_id": { + "type": "string", + "example": "compute://abc123" + }, + "node_name": { + "type": "string", + "example": "worker-xl8r2" + }, + "status": { + "type": "string", + "example": "provisioning" + } + }, + "required": [ + "provider_id", + "node_name", + "status" + ], + "x-platform-visibility": "INTERNAL" + }, + "ClusterRuntimeError": { + "type": "object", + "properties": { + "type": { + "type": "string", + "example": "InsufficientCapacity" + }, + "message": { + "type": "string", + "example": "cpx31 is unavailable in fsn1" + }, + "metadata": { + "type": "object", + "additionalProperties": { + "type": "string" + } + } + }, + "required": [ + "type", + "message" + ], + "x-platform-visibility": "INTERNAL" + }, + "ClusterRuntimeDrift": { + "type": "object", + "properties": { + "drifted": { + "type": "boolean" + }, + "reason": { + "type": "string" + } + }, + "required": [ + "drifted" + ], + "x-platform-visibility": "INTERNAL" + }, + "ClusterRuntimeInstanceType": { + "type": "object", + "properties": { + "name": { + "type": "string", + "example": "cpx31" + }, + "arch": { + "type": "string", + "example": "amd64" + }, + "cpu": { + "type": "number", + "example": 4 + }, + "memory_mib": { + "type": "number", + "example": 8192 + }, + "storage_mib": { + "type": "number", + "example": 163840 + }, + "price_per_hour": { + "type": "number", + "example": 0.0208 + }, + "available": { + "type": "boolean", + "example": true + } + }, + "required": [ + "name", + "arch", + "cpu", + "memory_mib", + "storage_mib", + "price_per_hour", + "available" + ], + "x-platform-visibility": "INTERNAL" + }, + "ClusterRuntimeComputeStatus": { + "type": "object", + "properties": { + "auto_scaling": { + "type": "string", + "enum": [ + "active", + "paused" + ] + }, + "machines": { + "type": "number" + }, + "max_machines": { + "type": "number" + }, + "updated_at": { + "type": "integer" + }, + "etag": { + "type": "string" + } + }, + "required": [ + "auto_scaling", + "machines", + "max_machines", + "updated_at", + "etag" + ], + "x-platform-visibility": "INTERNAL" + }, + "ClusterComputeSettings": { + "type": "object", + "properties": { + "auto_scaling": { + "type": "string", + "enum": [ + "active", + "paused" + ] + }, + "machines": { + "type": "integer", + "minimum": 0 + }, + "max_machines": { + "type": "integer", + "minimum": 0 + }, + "updated_at": { + "type": "integer", + "minimum": 0, + "description": "Unix timestamp (seconds)" + }, + "etag": { + "type": "string" + } + }, + "required": [ + "auto_scaling", + "machines", + "max_machines", + "updated_at", + "etag" + ] + }, + "UpdateClusterComputeSettingsBody": { + "anyOf": [ + { + "type": "object", + "properties": { + "auto_scaling_enabled": { + "type": "boolean" + }, + "max_machines": { + "type": "integer", + "minimum": 0, + "maximum": 100 + } + }, + "required": [ + "auto_scaling_enabled" + ], + "additionalProperties": false + }, + { + "type": "object", + "properties": { + "auto_scaling_enabled": { + "type": "boolean" + }, + "max_machines": { + "type": "integer", + "minimum": 0, + "maximum": 100 + } + }, + "required": [ + "max_machines" + ], + "additionalProperties": false + } + ] + }, + "MachineOperation": { + "type": "object", + "properties": { + "id": { + "type": "string", + "minLength": 1, + "maxLength": 53 + }, + "workspace_id": { + "type": "string", + "nullable": true, + "minLength": 1, + "maxLength": 53 + }, + "organization_id": { + "type": "string", + "nullable": true, + "minLength": 1, + "maxLength": 54 + }, + "owner_type": { + "type": "string", + "enum": [ + "install", + "repository_change_request", + "repository", + "workspace", + "machine", + "cluster", + "package" + ], + "description": "Domain entity collection the operation acts on." + }, + "owner_id": { + "type": "string", + "description": "Prefixed ID of the entity this operation acts on. Prefix matches `owner_type` (`ws_`, `mch_`, `clu_`, `pkg_`, `inst_`, `rcr_`, `repo_`)." + }, + "parent_operation_id": { + "type": "string", + "nullable": true, + "minLength": 1, + "maxLength": 53, + "description": "ID of the chained parent operation, when present." + }, + "state": { + "type": "string", + "enum": [ + "RUNNING", + "SUCCEEDED", + "FAILED", + "CANCELLED" + ], + "description": "Lifecycle state. Past-participle terminal states per AIP-216." + }, + "done": { + "type": "boolean", + "description": "True iff state is a terminal value." + }, + "html_url": { + "type": "string", + "maxLength": 2048, + "format": "uri", + "description": "Deep link to the dashboard view of this operation's owning resource when available, otherwise the operation detail page.", + "example": "https://akua.dev/installs/inst_j572abc123def456?tab=operations" + }, + "metadata": { + "$ref": "#/components/schemas/OperationMetadata" + }, + "response": { + "$ref": "#/components/schemas/OperationResponse" + }, + "error": { + "type": "object", + "nullable": true, + "properties": { + "message": { + "type": "string" + } + }, + "required": [ + "message" + ], + "description": "Populated when `state` is `FAILED` or `CANCELLED`." + }, + "last_error": { + "type": "object", + "nullable": true, + "properties": { + "message": { + "type": "string" + }, + "step_name": { + "type": "string" + } + }, + "required": [ + "message" + ], + "description": "Latest error from any failed step. Populated even mid-flight; cleared when the step succeeds on retry." + }, + "started_at": { + "type": "integer", + "minimum": 0, + "description": "Unix timestamp (seconds)" + }, + "completed_at": { + "type": "integer", + "nullable": true, + "minimum": 0, + "description": "Unix timestamp (seconds)" + }, + "steps": { + "type": "array", + "items": { + "$ref": "#/components/schemas/OperationStep" + } + }, + "operation_id": { + "type": "string", + "minLength": 1, + "maxLength": 53, + "description": "Compatibility alias for `id`." + } + }, + "required": [ + "id", + "workspace_id", + "organization_id", + "owner_type", + "owner_id", + "parent_operation_id", + "state", + "done", + "html_url", + "metadata", + "response", + "error", + "last_error", + "started_at", + "completed_at", + "operation_id" + ] + }, + "OperationMetadata": { + "oneOf": [ + { + "type": "object", + "properties": { + "type": { + "type": "string", + "enum": [ + "machine.create" + ] + }, + "workspace_id": { + "type": "string", + "minLength": 1, + "maxLength": 53 + }, + "cluster_id": { + "type": "string", + "minLength": 1, + "maxLength": 54 + }, + "compute_config_id": { + "type": "string", + "minLength": 1, + "maxLength": 54 + }, + "instance_type": { + "type": "string" + }, + "managed": { + "type": "boolean" + }, + "request_fingerprint": { + "type": "string", + "minLength": 1 + } + }, + "required": [ + "type", + "workspace_id", + "cluster_id", + "instance_type", + "managed", + "request_fingerprint" + ] + }, + { + "type": "object", + "properties": { + "type": { + "type": "string", + "enum": [ + "machine.delete" + ] + }, + "workspace_id": { + "type": "string", + "minLength": 1, + "maxLength": 53 + }, + "machine_id": { + "type": "string", + "minLength": 1, + "maxLength": 54 + }, + "request_fingerprint": { + "type": "string", + "minLength": 1 + } + }, + "required": [ + "type", + "workspace_id", + "machine_id", + "request_fingerprint" + ] + }, + { + "type": "object", + "properties": { + "type": { + "type": "string", + "enum": [ + "machine.suspend" + ] + }, + "workspace_id": { + "type": "string", + "minLength": 1, + "maxLength": 53 + }, + "machine_id": { + "type": "string", + "minLength": 1, + "maxLength": 54 + }, + "request_fingerprint": { + "type": "string", + "minLength": 1 + } + }, + "required": [ + "type", + "workspace_id", + "machine_id", + "request_fingerprint" + ] + }, + { + "type": "object", + "properties": { + "type": { + "type": "string", + "enum": [ + "machine.resume" + ] + }, + "workspace_id": { + "type": "string", + "minLength": 1, + "maxLength": 53 + }, + "machine_id": { + "type": "string", + "minLength": 1, + "maxLength": 54 + }, + "request_fingerprint": { + "type": "string", + "minLength": 1 + } + }, + "required": [ + "type", + "workspace_id", + "machine_id", + "request_fingerprint" + ] + }, + { + "type": "object", + "properties": { + "type": { + "type": "string", + "enum": [ + "cluster.delete" + ] + }, + "cluster_id": { + "type": "string", + "minLength": 1, + "maxLength": 54 + } + }, + "required": [ + "type", + "cluster_id" + ] + }, + { + "type": "object", + "properties": { + "type": { + "type": "string", + "enum": [ + "cluster.create" + ] + }, + "workspace_id": { + "type": "string", + "minLength": 1, + "maxLength": 53 + }, + "region_id": { + "type": "string", + "minLength": 1, + "maxLength": 54 + }, + "name": { + "type": "string" + } + }, + "required": [ + "type", + "workspace_id", + "region_id", + "name" + ] + }, + { + "type": "object", + "properties": { + "type": { + "type": "string", + "enum": [ + "cluster.suspend" + ] + }, + "cluster_id": { + "type": "string", + "minLength": 1, + "maxLength": 54 + } + }, + "required": [ + "type", + "cluster_id" + ] + }, + { + "type": "object", + "properties": { + "type": { + "type": "string", + "enum": [ + "cluster.resume" + ] + }, + "cluster_id": { + "type": "string", + "minLength": 1, + "maxLength": 54 + } + }, + "required": [ + "type", + "cluster_id" + ] + }, + { + "type": "object", + "properties": { + "type": { + "type": "string", + "enum": [ + "cluster.capabilities.refresh" + ] + }, + "cluster_id": { + "type": "string", + "minLength": 1, + "maxLength": 54 + } + }, + "required": [ + "type", + "cluster_id" + ] + }, + { + "type": "object", + "properties": { + "type": { + "type": "string", + "enum": [ + "cluster.capability.ensure" + ] + }, + "cluster_id": { + "type": "string", + "minLength": 1, + "maxLength": 54 + }, + "capability": { + "type": "string", + "minLength": 1 + } + }, + "required": [ + "type", + "cluster_id", + "capability" + ] + }, + { + "type": "object", + "properties": { + "type": { + "type": "string", + "enum": [ + "cluster.worker_bootstrap.revoke" + ] + }, + "cluster_id": { + "type": "string", + "minLength": 1, + "maxLength": 54 + }, + "worker_bootstrap_id": { + "type": "string", + "minLength": 1, + "maxLength": 54 + } + }, + "required": [ + "type", + "cluster_id", + "worker_bootstrap_id" + ] + }, + { + "type": "object", + "properties": { + "type": { + "type": "string", + "enum": [ + "install.create" + ] + }, + "idempotency_key": { + "type": "string" + }, + "workspace_id": { + "type": "string", + "minLength": 1, + "maxLength": 53 + }, + "product_id": { + "type": "string", + "minLength": 1, + "maxLength": 55 + } + }, + "required": [ + "type", + "idempotency_key", + "workspace_id" + ] + }, + { + "type": "object", + "properties": { + "type": { + "type": "string", + "enum": [ + "install.render" + ] + }, + "install_id": { + "type": "string", + "minLength": 1, + "maxLength": 55 + }, + "trigger_commit_sha": { + "type": "string" + } + }, + "required": [ + "type", + "install_id" + ] + }, + { + "type": "object", + "properties": { + "type": { + "type": "string", + "enum": [ + "install.delete" + ] + }, + "install_id": { + "type": "string", + "minLength": 1, + "maxLength": 55 + } + }, + "required": [ + "type", + "install_id" + ] + }, + { + "type": "object", + "properties": { + "type": { + "type": "string", + "enum": [ + "preview_hostname.bind_pinned" + ] + }, + "install_id": { + "type": "string", + "minLength": 1, + "maxLength": 55 + }, + "render_id": { + "type": "string", + "minLength": 1, + "maxLength": 54 + }, + "protocol": { + "type": "string", + "enum": [ + "http", + "websocket", + "grpc" + ] + }, + "routing_mode": { + "type": "string", + "enum": [ + "through_dispatcher", + "bypass_dispatcher" + ] + }, + "idempotency_key": { + "type": "string" + } + }, + "required": [ + "type", + "install_id", + "render_id", + "protocol", + "routing_mode", + "idempotency_key" + ] + }, + { + "type": "object", + "properties": { + "type": { + "type": "string", + "enum": [ + "preview_hostname.bind_floating" + ] + }, + "install_id": { + "type": "string", + "minLength": 1, + "maxLength": 55 + }, + "track": { + "type": "string", + "minLength": 1, + "maxLength": 100 + }, + "render_id": { + "type": "string", + "minLength": 1, + "maxLength": 54 + }, + "protocol": { + "type": "string", + "enum": [ + "http", + "websocket", + "grpc" + ] + }, + "routing_mode": { + "type": "string", + "enum": [ + "through_dispatcher", + "bypass_dispatcher" + ] + }, + "idempotency_key": { + "type": "string" + } + }, + "required": [ + "type", + "install_id", + "track", + "render_id", + "protocol", + "routing_mode", + "idempotency_key" + ] + }, + { + "type": "object", + "properties": { + "type": { + "type": "string", + "enum": [ + "preview_hostname.delete" + ] + }, + "install_id": { + "type": "string", + "minLength": 1, + "maxLength": 55 + }, + "preview_hostname_id": { + "type": "string", + "minLength": 1, + "maxLength": 54 + }, + "if_match": { + "type": "string" + }, + "idempotency_key": { + "type": "string" + } + }, + "required": [ + "type", + "install_id", + "preview_hostname_id", + "if_match", + "idempotency_key" + ] + }, + { + "type": "object", + "properties": { + "type": { + "type": "string", + "enum": [ + "workspace.delete" + ] + }, + "workspace_id": { + "type": "string", + "minLength": 1, + "maxLength": 53 + } + }, + "required": [ + "type", + "workspace_id" + ] + }, + { + "type": "object", + "properties": { + "type": { + "type": "string", + "enum": [ + "workspace.subscription.cancel" + ] + }, + "workspace_id": { + "type": "string", + "minLength": 1, + "maxLength": 53 + }, + "mode": { + "type": "string", + "enum": [ + "period_end" + ] + } + }, + "required": [ + "type", + "workspace_id", + "mode" + ] + }, + { + "type": "object", + "properties": { + "type": { + "type": "string", + "enum": [ + "workspace.subdomain.set_name" + ] + }, + "workspace_id": { + "type": "string", + "minLength": 1, + "maxLength": 53 + }, + "name": { + "type": "string", + "minLength": 1, + "maxLength": 63 + }, + "idempotency_key": { + "type": "string" + } + }, + "required": [ + "type", + "workspace_id", + "name", + "idempotency_key" + ] + }, + { + "type": "object", + "properties": { + "type": { + "type": "string", + "enum": [ + "custom_domain.create" + ] + }, + "workspace_id": { + "type": "string", + "minLength": 1, + "maxLength": 53 + }, + "hostname": { + "type": "string", + "minLength": 1, + "maxLength": 253 + }, + "target": { + "oneOf": [ + { + "type": "object", + "properties": { + "kind": { + "type": "string", + "enum": [ + "install" + ] + }, + "install_id": { + "type": "string", + "minLength": 1, + "maxLength": 55 + } + }, + "required": [ + "kind", + "install_id" + ] + }, + { + "type": "object", + "properties": { + "kind": { + "type": "string", + "enum": [ + "cluster" + ] + }, + "cluster_id": { + "type": "string", + "minLength": 1, + "maxLength": 54 + } + }, + "required": [ + "kind", + "cluster_id" + ] + }, + { + "type": "object", + "properties": { + "kind": { + "type": "string", + "enum": [ + "external" + ] + }, + "endpoint": { + "type": "string", + "format": "uri" + }, + "mtls_secret_id": { + "type": "string", + "minLength": 1, + "maxLength": 54 + } + }, + "required": [ + "kind", + "endpoint" + ] + } + ] + }, + "protocol": { + "type": "string", + "enum": [ + "http", + "websocket", + "grpc" + ] + }, + "routing_mode": { + "type": "string", + "enum": [ + "through_dispatcher", + "bypass_dispatcher" + ] + }, + "idempotency_key": { + "type": "string" + } + }, + "required": [ + "type", + "workspace_id", + "hostname", + "target", + "protocol", + "routing_mode", + "idempotency_key" + ] + }, + { + "type": "object", + "properties": { + "type": { + "type": "string", + "enum": [ + "custom_domain.update" + ] + }, + "workspace_id": { + "type": "string", + "minLength": 1, + "maxLength": 53 + }, + "custom_domain_id": { + "type": "string", + "minLength": 1, + "maxLength": 54 + }, + "target": { + "oneOf": [ + { + "type": "object", + "properties": { + "kind": { + "type": "string", + "enum": [ + "install" + ] + }, + "install_id": { + "type": "string", + "minLength": 1, + "maxLength": 55 + } + }, + "required": [ + "kind", + "install_id" + ] + }, + { + "type": "object", + "properties": { + "kind": { + "type": "string", + "enum": [ + "cluster" + ] + }, + "cluster_id": { + "type": "string", + "minLength": 1, + "maxLength": 54 + } + }, + "required": [ + "kind", + "cluster_id" + ] + }, + { + "type": "object", + "properties": { + "kind": { + "type": "string", + "enum": [ + "external" + ] + }, + "endpoint": { + "type": "string", + "format": "uri" + }, + "mtls_secret_id": { + "type": "string", + "minLength": 1, + "maxLength": 54 + } + }, + "required": [ + "kind", + "endpoint" + ] + } + ] + }, + "protocol": { + "type": "string", + "enum": [ + "http", + "websocket", + "grpc" + ] + }, + "routing_mode": { + "type": "string", + "enum": [ + "through_dispatcher", + "bypass_dispatcher" + ] + }, + "if_match": { + "type": "string" + }, + "idempotency_key": { + "type": "string" + } + }, + "required": [ + "type", + "workspace_id", + "custom_domain_id", + "if_match", + "idempotency_key" + ] + }, + { + "type": "object", + "properties": { + "type": { + "type": "string", + "enum": [ + "custom_domain.delete" + ] + }, + "workspace_id": { + "type": "string", + "minLength": 1, + "maxLength": 53 + }, + "custom_domain_id": { + "type": "string", + "minLength": 1, + "maxLength": 54 + }, + "if_match": { + "type": "string" + }, + "idempotency_key": { + "type": "string" + } + }, + "required": [ + "type", + "workspace_id", + "custom_domain_id", + "if_match", + "idempotency_key" + ] + }, + { + "type": "object", + "properties": { + "type": { + "type": "string", + "enum": [ + "cloudflare.private_origin_route.prepare" + ] + }, + "workspace_id": { + "type": "string", + "minLength": 1, + "maxLength": 53 + }, + "cluster_id": { + "type": "string", + "minLength": 1, + "maxLength": 54 + }, + "route_intent_id": { + "type": "string", + "minLength": 1, + "maxLength": 54 + } + }, + "required": [ + "type", + "workspace_id", + "cluster_id", + "route_intent_id" + ] + }, + { + "type": "object", + "properties": { + "type": { + "type": "string", + "enum": [ + "cloudflare.private_origin_route.release" + ] + }, + "workspace_id": { + "type": "string", + "minLength": 1, + "maxLength": 53 + }, + "route_intent_id": { + "type": "string", + "minLength": 1, + "maxLength": 54 + } + }, + "required": [ + "type", + "workspace_id", + "route_intent_id" + ] + }, + { + "type": "object", + "properties": { + "type": { + "type": "string", + "enum": [ + "package.create" + ] + }, + "idempotency_key": { + "type": "string" + }, + "workspace_id": { + "type": "string", + "minLength": 1, + "maxLength": 53 + }, + "name": { + "type": "string" + } + }, + "required": [ + "type", + "idempotency_key", + "workspace_id", + "name" + ] + }, + { + "type": "object", + "properties": { + "type": { + "type": "string", + "enum": [ + "repository_change_request.create" + ] + }, + "workspace_id": { + "type": "string", + "minLength": 1, + "maxLength": 53 + }, + "parent_repository_id": { + "type": "string", + "minLength": 1, + "maxLength": 55 + }, + "created_by_kind": { + "type": "string", + "enum": [ + "agent", + "wizard", + "user" + ] + } + }, + "required": [ + "type", + "workspace_id", + "parent_repository_id", + "created_by_kind" + ] + }, + { + "type": "object", + "properties": { + "type": { + "type": "string", + "enum": [ + "repository_change_request.accept" + ] + }, + "repository_change_request_id": { + "type": "string", + "minLength": 1, + "maxLength": 54 + }, + "user_id": { + "type": "string" + } + }, + "required": [ + "type", + "repository_change_request_id", + "user_id" + ] + }, + { + "type": "object", + "properties": { + "type": { + "type": "string", + "enum": [ + "repository_change_request.reject" + ] + }, + "repository_change_request_id": { + "type": "string", + "minLength": 1, + "maxLength": 54 + }, + "user_id": { + "type": "string" + }, + "reason": { + "type": "string" + } + }, + "required": [ + "type", + "repository_change_request_id", + "user_id", + "reason" + ] + }, + { + "type": "object", + "properties": { + "type": { + "type": "string", + "enum": [ + "repository_change_request.withdraw" + ] + }, + "repository_change_request_id": { + "type": "string", + "minLength": 1, + "maxLength": 54 + }, + "user_id": { + "type": "string" + } + }, + "required": [ + "type", + "repository_change_request_id", + "user_id" + ] + }, + { + "type": "object", + "properties": { + "type": { + "type": "string", + "enum": [ + "repository_change_request.expire" + ] + }, + "repository_change_request_id": { + "type": "string", + "minLength": 1, + "maxLength": 54 + } + }, + "required": [ + "type", + "repository_change_request_id" + ] + }, + { + "type": "object", + "properties": { + "type": { + "type": "string", + "enum": [ + "repository.delete" + ] + }, + "repository_id": { + "type": "string", + "minLength": 1, + "maxLength": 55 + } + }, + "required": [ + "type", + "repository_id" + ] + } + ] + }, + "OperationResponse": { + "anyOf": [ + { + "type": "object", + "properties": { + "type": { + "type": "string", + "enum": [ + "machine.create" + ] + }, + "machine_id": { + "type": "string", + "minLength": 1, + "maxLength": 54 + }, + "provider_id": { + "type": "string" + } + }, + "required": [ + "type", + "machine_id", + "provider_id" + ] + }, + { + "type": "object", + "properties": { + "type": { + "type": "string", + "enum": [ + "machine.delete" + ] + }, + "machine_id": { + "type": "string", + "minLength": 1, + "maxLength": 54 + } + }, + "required": [ + "type", + "machine_id" + ] + }, + { + "type": "object", + "properties": { + "type": { + "type": "string", + "enum": [ + "machine.suspend" + ] + }, + "machine_id": { + "type": "string", + "minLength": 1, + "maxLength": 54 + }, + "suspension_id": { + "type": "string", + "minLength": 1, + "maxLength": 54 + } + }, + "required": [ + "type", + "machine_id", + "suspension_id" + ] + }, + { + "type": "object", + "properties": { + "type": { + "type": "string", + "enum": [ + "machine.resume" + ] + }, + "machine_id": { + "type": "string", + "minLength": 1, + "maxLength": 54 + } + }, + "required": [ + "type", + "machine_id" + ] + }, + { + "type": "object", + "properties": { + "type": { + "type": "string", + "enum": [ + "cluster.delete" + ] + }, + "cluster_id": { + "type": "string", + "minLength": 1, + "maxLength": 54 + } + }, + "required": [ + "type", + "cluster_id" + ] + }, + { + "type": "object", + "properties": { + "type": { + "type": "string", + "enum": [ + "cluster.create" + ] + }, + "cluster_id": { + "type": "string", + "minLength": 1, + "maxLength": 54 + } + }, + "required": [ + "type", + "cluster_id" + ] + }, + { + "type": "object", + "properties": { + "type": { + "type": "string", + "enum": [ + "cluster.suspend" + ] + }, + "cluster_id": { + "type": "string", + "minLength": 1, + "maxLength": 54 + } + }, + "required": [ + "type", + "cluster_id" + ] + }, + { + "type": "object", + "properties": { + "type": { + "type": "string", + "enum": [ + "cluster.resume" + ] + }, + "cluster_id": { + "type": "string", + "minLength": 1, + "maxLength": 54 + } + }, + "required": [ + "type", + "cluster_id" + ] + }, + { + "type": "object", + "properties": { + "type": { + "type": "string", + "enum": [ + "cluster.capabilities.refresh" + ] + }, + "cluster_id": { + "type": "string", + "minLength": 1, + "maxLength": 54 + } + }, + "required": [ + "type", + "cluster_id" + ] + }, + { + "type": "object", + "properties": { + "type": { + "type": "string", + "enum": [ + "cluster.capability.ensure" + ] + }, + "cluster_id": { + "type": "string", + "minLength": 1, + "maxLength": 54 + }, + "capability": { + "type": "string", + "minLength": 1 + } + }, + "required": [ + "type", + "cluster_id", + "capability" + ] + }, + { + "type": "object", + "properties": { + "type": { + "type": "string", + "enum": [ + "cluster.worker_bootstrap.revoke" + ] + }, + "note": { + "type": "string" + } + }, + "required": [ + "type" + ] + }, + { + "type": "object", + "properties": { + "type": { + "type": "string", + "enum": [ + "install.create" + ] + }, + "install_id": { + "type": "string", + "minLength": 1, + "maxLength": 55 + }, + "argo_app_name": { + "type": "string" + }, + "argo_app_namespace": { + "type": "string" + } + }, + "required": [ + "type", + "install_id", + "argo_app_name", + "argo_app_namespace" + ], + "additionalProperties": false + }, + { + "type": "object", + "properties": { + "type": { + "type": "string", + "enum": [ + "install.create" + ] + }, + "install_id": { + "type": "string", + "minLength": 1, + "maxLength": 55 + }, + "sandbox_skipped": { + "type": "boolean", + "enum": [ + true + ] + } + }, + "required": [ + "type", + "install_id", + "sandbox_skipped" + ], + "additionalProperties": false + }, + { + "type": "object", + "properties": { + "type": { + "type": "string", + "enum": [ + "install.render" + ] + }, + "install_render_id": { + "type": "string", + "minLength": 1, + "maxLength": 54 + }, + "repository_id": { + "type": "string", + "minLength": 1, + "maxLength": 55 + }, + "commit_sha": { + "type": "string" + }, + "render_hash": { + "type": "string" + }, + "skipped": { + "type": "boolean" + } + }, + "required": [ + "type", + "install_render_id", + "repository_id", + "render_hash", + "skipped" + ] + }, + { + "type": "object", + "properties": { + "type": { + "type": "string", + "enum": [ + "install.delete" + ] + }, + "argo_app_deleted": { + "type": "boolean" + }, + "repo_purged": { + "type": "boolean" + } + }, + "required": [ + "type", + "argo_app_deleted", + "repo_purged" + ] + }, + { + "type": "object", + "properties": { + "type": { + "type": "string", + "enum": [ + "preview_hostname.bind_pinned" + ] + }, + "install_id": { + "type": "string", + "minLength": 1, + "maxLength": 55 + }, + "preview_hostname_id": { + "type": "string", + "minLength": 1, + "maxLength": 54 + }, + "hostname": { + "type": "string", + "minLength": 1, + "maxLength": 253 + } + }, + "required": [ + "type", + "install_id", + "preview_hostname_id", + "hostname" + ] + }, + { + "type": "object", + "properties": { + "type": { + "type": "string", + "enum": [ + "preview_hostname.bind_floating" + ] + }, + "install_id": { + "type": "string", + "minLength": 1, + "maxLength": 55 + }, + "preview_hostname_id": { + "type": "string", + "minLength": 1, + "maxLength": 54 + }, + "hostname": { + "type": "string", + "minLength": 1, + "maxLength": 253 + } + }, + "required": [ + "type", + "install_id", + "preview_hostname_id", + "hostname" + ] + }, + { + "type": "object", + "properties": { + "type": { + "type": "string", + "enum": [ + "preview_hostname.delete" + ] + }, + "install_id": { + "type": "string", + "minLength": 1, + "maxLength": 55 + }, + "preview_hostname_id": { + "type": "string", + "minLength": 1, + "maxLength": 54 + }, + "hostname": { + "type": "string", + "minLength": 1, + "maxLength": 253 + } + }, + "required": [ + "type", + "install_id", + "preview_hostname_id", + "hostname" + ] + }, + { + "type": "object", + "properties": { + "type": { + "type": "string", + "enum": [ + "workspace.delete" + ] + }, + "workspace_id": { + "type": "string", + "minLength": 1, + "maxLength": 53 + } + }, + "required": [ + "type", + "workspace_id" + ] + }, + { + "type": "object", + "properties": { + "type": { + "type": "string", + "enum": [ + "workspace.subscription.cancel" + ] + }, + "subscription_id": { + "type": "string" + }, + "cancel_at": { + "type": "integer", + "minimum": 0, + "description": "Unix timestamp (seconds)" + } + }, + "required": [ + "type", + "subscription_id", + "cancel_at" + ] + }, + { + "type": "object", + "properties": { + "type": { + "type": "string", + "enum": [ + "workspace.subdomain.set_name" + ] + }, + "workspace_id": { + "type": "string", + "minLength": 1, + "maxLength": 53 + }, + "workspace_subdomain_id": { + "type": "string", + "minLength": 1, + "maxLength": 54 + }, + "fqdn": { + "type": "string", + "minLength": 1, + "maxLength": 253 + } + }, + "required": [ + "type", + "workspace_id", + "workspace_subdomain_id", + "fqdn" + ] + }, + { + "type": "object", + "properties": { + "type": { + "type": "string", + "enum": [ + "custom_domain.create" + ] + }, + "workspace_id": { + "type": "string", + "minLength": 1, + "maxLength": 53 + }, + "custom_domain_id": { + "type": "string", + "minLength": 1, + "maxLength": 54 + }, + "hostname": { + "type": "string", + "minLength": 1, + "maxLength": 253 + } + }, + "required": [ + "type", + "workspace_id", + "custom_domain_id", + "hostname" + ] + }, + { + "type": "object", + "properties": { + "type": { + "type": "string", + "enum": [ + "custom_domain.update" + ] + }, + "workspace_id": { + "type": "string", + "minLength": 1, + "maxLength": 53 + }, + "custom_domain_id": { + "type": "string", + "minLength": 1, + "maxLength": 54 + }, + "hostname": { + "type": "string", + "minLength": 1, + "maxLength": 253 + } + }, + "required": [ + "type", + "workspace_id", + "custom_domain_id", + "hostname" + ] + }, + { + "type": "object", + "properties": { + "type": { + "type": "string", + "enum": [ + "custom_domain.delete" + ] + }, + "workspace_id": { + "type": "string", + "minLength": 1, + "maxLength": 53 + }, + "custom_domain_id": { + "type": "string", + "minLength": 1, + "maxLength": 54 + }, + "hostname": { + "type": "string", + "minLength": 1, + "maxLength": 253 + } + }, + "required": [ + "type", + "workspace_id", + "custom_domain_id", + "hostname" + ] + }, + { + "type": "object", + "properties": { + "type": { + "type": "string", + "enum": [ + "cloudflare.private_origin_route.prepare" + ] + }, + "origin_route_id": { + "type": "string", + "minLength": 1, + "maxLength": 54 + } + }, + "required": [ + "type", + "origin_route_id" + ] + }, + { + "type": "object", + "properties": { + "type": { + "type": "string", + "enum": [ + "cloudflare.private_origin_route.release" + ] + }, + "route_intent_id": { + "type": "string", + "minLength": 1, + "maxLength": 54 + } + }, + "required": [ + "type", + "route_intent_id" + ] + }, + { + "type": "object", + "properties": { + "type": { + "type": "string", + "enum": [ + "package.create" + ] + }, + "package_id": { + "type": "string", + "minLength": 1, + "maxLength": 54 + }, + "package_version_id": { + "type": "string", + "minLength": 1, + "maxLength": 55 + }, + "repository_id": { + "type": "string", + "minLength": 1, + "maxLength": 55 + } + }, + "required": [ + "type", + "package_id", + "package_version_id", + "repository_id" + ] + }, + { + "type": "object", + "properties": { + "type": { + "type": "string", + "enum": [ + "repository_change_request.create" + ] + }, + "repository_change_request_id": { + "type": "string", + "minLength": 1, + "maxLength": 54 + }, + "fork_repository_id": { + "type": "string", + "minLength": 1, + "maxLength": 55 + }, + "expires_at": { + "type": "integer", + "minimum": 0, + "description": "Unix timestamp (seconds)" + } + }, + "required": [ + "type", + "repository_change_request_id", + "fork_repository_id", + "expires_at" + ] + }, + { + "type": "object", + "properties": { + "type": { + "type": "string", + "enum": [ + "repository_change_request.accept" + ] + }, + "merged_at": { + "type": "integer", + "minimum": 0, + "description": "Unix timestamp (seconds)" + }, + "triggered_install_render": { + "type": "boolean" + } + }, + "required": [ + "type", + "merged_at", + "triggered_install_render" + ] + }, + { + "type": "object", + "properties": { + "type": { + "type": "string", + "enum": [ + "repository_change_request.reject" + ] + }, + "rejected_at": { + "type": "integer", + "minimum": 0, + "description": "Unix timestamp (seconds)" + } + }, + "required": [ + "type", + "rejected_at" + ] + }, + { + "type": "object", + "properties": { + "type": { + "type": "string", + "enum": [ + "repository_change_request.withdraw" + ] + }, + "withdrawn_at": { + "type": "integer", + "minimum": 0, + "description": "Unix timestamp (seconds)" + } + }, + "required": [ + "type", + "withdrawn_at" + ] + }, + { + "type": "object", + "properties": { + "type": { + "type": "string", + "enum": [ + "repository_change_request.expire" + ] + }, + "expired": { + "type": "boolean" + } + }, + "required": [ + "type", + "expired" + ] + }, + { + "type": "object", + "properties": { + "type": { + "type": "string", + "enum": [ + "repository.delete" + ] + }, + "purged_at": { + "type": "integer", + "minimum": 0, + "description": "Unix timestamp (seconds)" + } + }, + "required": [ + "type", + "purged_at" + ] + }, + { + "nullable": true + } + ], + "description": "Populated only when `done && state === \"SUCCEEDED\"`. Discriminated by `type`." + }, + "OperationStep": { + "type": "object", + "properties": { + "name": { + "type": "string", + "description": "User-visible milestone name." + }, + "status": { + "type": "string", + "enum": [ + "pending", + "running", + "completed", + "failed", + "skipped" + ], + "description": "Step lifecycle state." + }, + "execution_type": { + "type": "string", + "enum": [ + "system", + "user", + "approval", + "skipped" + ], + "description": "Step execution kind. `user`/`approval` mean the workflow is blocked on a human action. Internal bookkeeping steps are filtered from public responses." + }, + "started_at": { + "type": "integer", + "minimum": 0, + "description": "Unix timestamp (seconds)" + }, + "completed_at": { + "type": "integer", + "nullable": true, + "minimum": 0, + "description": "Unix timestamp (seconds)" + }, + "error_message": { + "type": "string", + "nullable": true + }, + "retryable": { + "type": "boolean" + }, + "skippable": { + "type": "boolean" + } + }, + "required": [ + "name", + "status", + "execution_type", + "started_at", + "completed_at", + "error_message", + "retryable", + "skippable" + ] + }, + "DashboardClusterWorkerList": { + "type": "object", + "properties": { + "data": { + "type": "array", + "items": { + "$ref": "#/components/schemas/DashboardClusterWorker" + } + }, + "has_more": { + "type": "boolean", + "description": "True if more items exist after this page." + }, + "next_cursor": { + "type": "string", + "nullable": true, + "description": "Opaque cursor for the next page, or null if no more pages." + } + }, + "required": [ + "data", + "has_more", + "next_cursor" + ] + }, + "DashboardClusterWorker": { + "oneOf": [ + { + "type": "object", + "properties": { + "kind": { + "type": "string", + "enum": [ + "managed" + ] + }, + "machine": { + "$ref": "#/components/schemas/DashboardClusterManagedMachine" + }, + "node": { + "anyOf": [ + { + "$ref": "#/components/schemas/DashboardClusterObservedNode" + }, + { + "nullable": true + } + ] + } + }, + "required": [ + "kind", + "machine", + "node" + ] + }, + { + "type": "object", + "properties": { + "kind": { + "type": "string", + "enum": [ + "observed" + ] + }, + "node": { + "$ref": "#/components/schemas/DashboardClusterObservedNode" + } + }, + "required": [ + "kind", + "node" + ] + } + ] + }, + "DashboardClusterManagedMachine": { + "type": "object", + "properties": { + "id": { + "type": "string", + "minLength": 1, + "maxLength": 54 + }, + "workspace_id": { + "type": "string", + "minLength": 1, + "maxLength": 53 + }, + "cluster_id": { + "type": "string", + "minLength": 1, + "maxLength": 54 + }, + "compute_config_id": { + "type": "string", + "minLength": 1, + "maxLength": 54 + }, + "provider_id": { + "type": "string", + "description": "Provider URI identifier in canonical form (for example, compute://hcloud/server-1234).", + "example": "compute://hcloud/server-1234" + }, + "provider_resource": { + "type": "object", + "properties": { + "identity_kind": { + "type": "string", + "enum": [ + "recyclable", + "persistent" + ] + }, + "public_ip": { + "type": "string", + "nullable": true + }, + "floating_ip": { + "type": "object", + "properties": { + "id": { + "type": "string" + }, + "ipv4": { + "type": "string" + } + }, + "required": [ + "id", + "ipv4" + ] + } + }, + "required": [ + "identity_kind", + "public_ip" + ] + }, + "name": { + "type": "string" + }, + "node_name": { + "type": "string", + "nullable": true + }, + "state": { + "type": "string", + "enum": [ + "ACTIVE", + "PROVISIONING", + "SUSPENDING", + "SUSPENDED", + "RESUMING", + "DELETING" + ], + "description": "Machine lifecycle state." + }, + "reconciling": { + "type": "boolean" + }, + "current_suspension": { + "type": "object", + "properties": { + "event_id": { + "type": "string", + "minLength": 1, + "maxLength": 54 + }, + "snapshot_ref": { + "type": "object", + "properties": { + "provider": { + "type": "string", + "enum": [ + "hcloud" + ] + }, + "snapshot_id": { + "type": "integer" + }, + "size_gb": { + "type": "number" + } + }, + "required": [ + "provider", + "snapshot_id", + "size_gb" + ] + }, + "expires_at": { + "type": "integer", + "minimum": 0, + "description": "Unix timestamp (seconds)" + }, + "monthly_cost_cents": { + "type": "integer" + }, + "reason": { + "type": "string", + "enum": [ + "manual", + "downgrade" + ] + } + }, + "required": [ + "event_id", + "snapshot_ref", + "expires_at", + "monthly_cost_cents", + "reason" + ] + }, + "created_at": { + "type": "integer", + "minimum": 0, + "description": "Unix timestamp (seconds)" + }, + "updated_at": { + "type": "integer", + "minimum": 0, + "description": "Unix timestamp (seconds)" + }, + "etag": { + "type": "string" + } + }, + "required": [ + "id", + "workspace_id", + "cluster_id", + "provider_id", + "provider_resource", + "node_name", + "state", + "reconciling", + "created_at", + "updated_at", + "etag" + ] + }, + "DashboardClusterObservedNode": { + "type": "object", + "properties": { + "name": { + "type": "string" + }, + "ready": { + "type": "boolean" + }, + "worker_capacity": { + "type": "boolean" + }, + "schedulable": { + "type": "boolean" + }, + "addresses": { + "type": "array", + "items": { + "type": "object", + "properties": { + "type": { + "type": "string" + }, + "value": { + "type": "string" + } + }, + "required": [ + "type", + "value" + ] + } + }, + "status_message": { + "type": "string" + }, + "roles": { + "type": "array", + "items": { + "type": "string" + } + }, + "created_at": { + "type": "string" + }, + "version": { + "type": "string" + }, + "cpu_capacity": { + "type": "string" + }, + "memory_capacity": { + "type": "string" + }, + "os_image": { + "type": "string" + }, + "operating_system": { + "type": "string" + }, + "architecture": { + "type": "string" + } + }, + "required": [ + "name", + "roles", + "version", + "cpu_capacity", + "memory_capacity", + "os_image", + "architecture" + ] + }, + "MachineList": { + "type": "object", + "properties": { + "data": { + "type": "array", + "items": { + "$ref": "#/components/schemas/Machine" + } + }, + "has_more": { + "type": "boolean", + "description": "True if more items exist after this page." + }, + "next_cursor": { + "type": "string", + "nullable": true, + "description": "Opaque cursor for the next page, or null if no more pages." + } + }, + "required": [ + "data", + "has_more", + "next_cursor" + ] + }, + "Machine": { + "type": "object", + "properties": { + "id": { + "type": "string", + "minLength": 1, + "maxLength": 54 + }, + "workspace_id": { + "type": "string", + "minLength": 1, + "maxLength": 53 + }, + "cluster_id": { + "type": "string", + "minLength": 1, + "maxLength": 54 + }, + "compute_config_id": { + "type": "string", + "minLength": 1, + "maxLength": 54 + }, + "provider_id": { + "type": "string", + "description": "Provider URI identifier in canonical form (for example, compute://hcloud/server-1234).", + "example": "compute://hcloud/server-1234" + }, + "provider_resource": { + "type": "object", + "properties": { + "identity_kind": { + "type": "string", + "enum": [ + "recyclable", + "persistent" + ] + }, + "public_ip": { + "type": "string", + "nullable": true + }, + "floating_ip": { + "type": "object", + "properties": { + "id": { + "type": "string" + }, + "ipv4": { + "type": "string" + } + }, + "required": [ + "id", + "ipv4" + ] + } + }, + "required": [ + "identity_kind", + "public_ip" + ] + }, + "name": { + "type": "string" + }, + "node_name": { + "type": "string", + "nullable": true + }, + "state": { + "type": "string", + "enum": [ + "ACTIVE", + "PROVISIONING", + "SUSPENDING", + "SUSPENDED", + "RESUMING", + "DELETING" + ], + "description": "Machine lifecycle state." + }, + "reconciling": { + "type": "boolean" + }, + "current_suspension": { + "type": "object", + "properties": { + "event_id": { + "type": "string", + "minLength": 1, + "maxLength": 54 + }, + "snapshot_ref": { + "type": "object", + "properties": { + "provider": { + "type": "string", + "enum": [ + "hcloud" + ] + }, + "snapshot_id": { + "type": "integer" + }, + "size_gb": { + "type": "number" + } + }, + "required": [ + "provider", + "snapshot_id", + "size_gb" + ] + }, + "expires_at": { + "type": "integer", + "minimum": 0, + "description": "Unix timestamp (seconds)" + }, + "monthly_cost_cents": { + "type": "integer" + }, + "reason": { + "type": "string", + "enum": [ + "manual", + "downgrade" + ] + } + }, + "required": [ + "event_id", + "snapshot_ref", + "expires_at", + "monthly_cost_cents", + "reason" + ] + }, + "created_at": { + "type": "integer", + "minimum": 0, + "description": "Unix timestamp (seconds)" + }, + "updated_at": { + "type": "integer", + "minimum": 0, + "description": "Unix timestamp (seconds)" + }, + "etag": { + "type": "string" + } + }, + "required": [ + "id", + "workspace_id", + "cluster_id", + "compute_config_id", + "provider_id", + "provider_resource", + "node_name", + "state", + "reconciling", + "created_at", + "updated_at", + "etag" + ] + }, + "SuspendMachineBody": { + "type": "object", + "properties": { + "reason": { + "type": "string", + "enum": [ + "manual", + "downgrade" + ] + } + }, + "additionalProperties": false + }, + "ResumeMachineBody": { + "type": "object", + "properties": {}, + "additionalProperties": false + }, + "DriftReport": { + "type": "object", + "properties": { + "id": { + "type": "string", + "description": "Drift report ID." + }, + "machine_id": { + "type": "string", + "minLength": 1, + "maxLength": 54 + }, + "state": { + "type": "string", + "enum": [ + "in_sync", + "drifted" + ], + "description": "Machine drift comparison state." + }, + "delta": { + "type": "object", + "additionalProperties": { + "nullable": true + } + }, + "provider_snapshot": { + "type": "object", + "properties": { + "provider": { + "type": "string" + }, + "raw_attrs": { + "type": "object", + "additionalProperties": { + "nullable": true + } + } + }, + "required": [ + "provider", + "raw_attrs" + ] + }, + "etag": { + "type": "string" + }, + "created_at": { + "type": "integer", + "minimum": 0, + "description": "Unix timestamp (seconds)" + }, + "started_at": { + "type": "integer", + "minimum": 0, + "description": "Unix timestamp (seconds)" + }, + "expires_at": { + "type": "integer", + "minimum": 0, + "description": "Unix timestamp (seconds)" + } + }, + "required": [ + "id", + "machine_id", + "state", + "etag", + "created_at", + "started_at", + "expires_at" + ] + }, + "DriftReportList": { + "type": "object", + "properties": { + "data": { + "type": "array", + "items": { + "$ref": "#/components/schemas/DriftReport" + } + }, + "has_more": { + "type": "boolean", + "description": "True if more items exist after this page." + }, + "next_cursor": { + "type": "string", + "nullable": true, + "description": "Opaque cursor for the next page, or null if no more pages." + } + }, + "required": [ + "data", + "has_more", + "next_cursor" + ] + }, + "SuspensionEventList": { + "type": "object", + "properties": { + "data": { + "type": "array", + "items": { + "$ref": "#/components/schemas/SuspensionEvent" + } + }, + "has_more": { + "type": "boolean", + "description": "True if more items exist after this page." + }, + "next_cursor": { + "type": "string", + "nullable": true, + "description": "Opaque cursor for the next page, or null if no more pages." + } + }, + "required": [ + "data", + "has_more", + "next_cursor" + ] + }, + "SuspensionEvent": { + "type": "object", + "properties": { + "id": { + "type": "string", + "minLength": 1, + "maxLength": 54 + }, + "machine_id": { + "type": "string", + "minLength": 1, + "maxLength": 54 + }, + "state": { + "type": "string", + "enum": [ + "in_progress", + "completed", + "resumed", + "expired" + ], + "description": "Suspension-event lifecycle state." + }, + "started_at": { + "type": "integer", + "minimum": 0, + "description": "Unix timestamp (seconds)" + }, + "resumed_at": { + "type": "integer", + "minimum": 0, + "description": "Unix timestamp (seconds)" + }, + "expires_at": { + "type": "integer", + "minimum": 0, + "description": "Unix timestamp (seconds)" + }, + "snapshot_ref": { + "type": "object", + "properties": { + "provider": { + "type": "string", + "enum": [ + "hcloud" + ] + }, + "snapshot_id": { + "type": "integer" + }, + "size_gb": { + "type": "number" + } + }, + "required": [ + "provider", + "snapshot_id", + "size_gb" + ] + }, + "monthly_cost_cents": { + "type": "integer" + }, + "total_cost_cents": { + "type": "integer" + }, + "reason": { + "type": "string", + "enum": [ + "manual", + "downgrade" + ] + }, + "etag": { + "type": "string" + } + }, + "required": [ + "id", + "machine_id", + "state", + "started_at", + "expires_at", + "snapshot_ref", + "monthly_cost_cents", + "reason", + "etag" + ] + }, + "ComputeConfig": { + "type": "object", + "properties": { + "id": { + "type": "string", + "minLength": 1, + "maxLength": 54 + }, + "workspace_id": { + "type": "string", + "minLength": 1, + "maxLength": 53 + }, + "name": { + "type": "string", + "minLength": 1, + "maxLength": 100 + }, + "provider": { + "type": "string", + "enum": [ + "hcloud" + ] + }, + "provider_config": { + "type": "object", + "properties": { + "region": { + "type": "string", + "minLength": 1 + }, + "image": { + "type": "string", + "minLength": 1 + }, + "machine_type_filter": { + "type": "string" + } + }, + "required": [ + "region", + "image" + ] + }, + "credential_scope": { + "$ref": "#/components/schemas/CredentialScope" + }, + "created_at": { + "type": "integer", + "minimum": 0, + "description": "Unix timestamp (seconds)" + }, + "updated_at": { + "type": "integer", + "minimum": 0, + "description": "Unix timestamp (seconds)" + }, + "etag": { + "type": "string" + } + }, + "required": [ + "id", + "workspace_id", + "name", + "provider", + "provider_config", + "credential_scope", + "created_at", + "updated_at", + "etag" + ] + }, + "CredentialScope": { + "oneOf": [ + { + "type": "object", + "properties": { + "kind": { + "type": "string", + "enum": [ + "system" + ], + "description": "Use system-managed provider credentials." + } + }, + "required": [ + "kind" + ], + "additionalProperties": false + }, + { + "type": "object", + "properties": { + "kind": { + "type": "string", + "enum": [ + "byom" + ] + }, + "secret_id": { + "type": "string", + "minLength": 1, + "maxLength": 54 + }, + "secret_version_id": { + "type": "string", + "minLength": 1, + "maxLength": 55 + } + }, + "required": [ + "kind", + "secret_id" + ], + "additionalProperties": false + } + ] + }, + "ComputeConfigList": { + "type": "object", + "properties": { + "data": { + "type": "array", + "items": { + "$ref": "#/components/schemas/ComputeConfig" + } + }, + "has_more": { + "type": "boolean", + "description": "True if more items exist after this page." + }, + "next_cursor": { + "type": "string", + "nullable": true, + "description": "Opaque cursor for the next page, or null if no more pages." + } + }, + "required": [ + "data", + "has_more", + "next_cursor" + ] + }, + "ProductList": { + "type": "object", + "properties": { + "data": { + "type": "array", + "items": { + "$ref": "#/components/schemas/Product" + } + }, + "has_more": { + "type": "boolean", + "description": "True if more items exist after this page." + }, + "next_cursor": { + "type": "string", + "nullable": true, + "description": "Opaque cursor for the next page, or null if no more pages." + } + }, + "required": [ + "data", + "has_more", + "next_cursor" + ] + }, + "Product": { + "type": "object", + "properties": { + "id": { + "type": "string", + "minLength": 1, + "maxLength": 55, + "example": "prod_j572abc123def456" + }, + "html_url": { + "type": "string", + "maxLength": 2048, + "format": "uri", + "description": "Absolute dashboard URL for this resource. OUTPUT_ONLY.", + "example": "https://akua.dev/products/prod_j572abc123def456" + }, + "name": { + "type": "string", + "example": "PostgreSQL Managed" + }, + "workspace_id": { + "type": "string", + "minLength": 1, + "maxLength": 53 + }, + "package": { + "type": "object", + "properties": { + "id": { + "type": "string", + "minLength": 1, + "maxLength": 54, + "example": "pkg_j572abc123def456" + }, + "version_pin": { + "$ref": "#/components/schemas/PackageVersionPin" + }, + "default_version_id": { + "type": "string", + "nullable": true, + "minLength": 1, + "maxLength": 55, + "description": "Concrete PackageVersion currently resolved by the version pin, or null when latest has no published version yet." + } + }, + "required": [ + "id", + "version_pin", + "default_version_id" + ], + "additionalProperties": false, + "description": "Reference to the Package backing this product. Fetch full details via `GET /v1/packages/{id}`." + }, + "custom_image": { + "type": "string", + "description": "Custom display image URL — overrides the package logo on customer-facing pages" + }, + "custom_description": { + "type": "string", + "description": "Custom display description — overrides the package description" + }, + "marketplace": { + "$ref": "#/components/schemas/ProductMarketplaceState" + }, + "created_at": { + "type": "integer", + "minimum": 0, + "description": "Unix timestamp (seconds)" + }, + "updated_at": { + "type": "integer", + "minimum": 0, + "description": "Unix timestamp (seconds)" + }, + "etag": { + "type": "string" + }, + "state": { + "type": "string", + "enum": [ + "active", + "archived" + ], + "description": "Product lifecycle state." + }, + "archived_at": { + "type": "integer", + "minimum": 0, + "description": "When the product was archived, expressed as Unix seconds since epoch." + }, + "archive_reason": { + "type": "string", + "description": "Reason supplied by the seller when archiving." + } + }, + "required": [ + "id", + "html_url", + "name", + "workspace_id", + "package", + "marketplace", + "created_at", + "updated_at", + "etag", + "state" + ] + }, + "PackageVersionPin": { + "oneOf": [ + { + "type": "object", + "properties": { + "kind": { + "type": "string", + "enum": [ + "latest" + ] + } + }, + "required": [ + "kind" + ], + "additionalProperties": false + }, + { + "type": "object", + "properties": { + "kind": { + "type": "string", + "enum": [ + "pinned" + ] + }, + "version": { + "type": "string", + "minLength": 1, + "maxLength": 128, + "pattern": "^(0|[1-9]\\d*)\\.(0|[1-9]\\d*)\\.(0|[1-9]\\d*)(?:-((?:0|[1-9]\\d*|[0-9A-Za-z-]*[A-Za-z-][0-9A-Za-z-]*)(?:\\.(?:0|[1-9]\\d*|[0-9A-Za-z-]*[A-Za-z-][0-9A-Za-z-]*))*))?(?:\\+([0-9A-Za-z-]+(?:\\.[0-9A-Za-z-]+)*))?$", + "example": "1.2.3" + } + }, + "required": [ + "kind", + "version" + ], + "additionalProperties": false + } + ] + }, + "ProductMarketplaceState": { + "type": "object", + "nullable": true, + "properties": { + "published": { + "type": "boolean", + "description": "Whether the product is publicly visible on the marketplace" + } + }, + "required": [ + "published" + ], + "additionalProperties": false, + "description": "Marketplace listing configuration. When null the product is not listed." + }, + "DashboardProductList": { + "type": "object", + "properties": { + "data": { + "type": "array", + "items": { + "$ref": "#/components/schemas/DashboardProduct" + } + }, + "has_more": { + "type": "boolean", + "description": "True if more items exist after this page." + }, + "next_cursor": { + "type": "string", + "nullable": true, + "description": "Opaque cursor for the next page, or null if no more pages." + } + }, + "required": [ + "data", + "has_more", + "next_cursor" + ] + }, + "DashboardProduct": { + "type": "object", + "properties": { + "id": { + "type": "string", + "minLength": 1, + "maxLength": 55, + "example": "prod_j572abc123def456" + }, + "html_url": { + "type": "string", + "maxLength": 2048, + "format": "uri", + "description": "Absolute dashboard URL for this resource. OUTPUT_ONLY.", + "example": "https://akua.dev/products/prod_j572abc123def456" + }, + "name": { + "type": "string", + "example": "PostgreSQL Managed" + }, + "workspace_id": { + "type": "string", + "minLength": 1, + "maxLength": 53 + }, + "package": { + "type": "object", + "properties": { + "id": { + "type": "string", + "minLength": 1, + "maxLength": 54, + "example": "pkg_j572abc123def456" + }, + "version_pin": { + "$ref": "#/components/schemas/PackageVersionPin" + }, + "default_version_id": { + "type": "string", + "nullable": true, + "minLength": 1, + "maxLength": 55, + "description": "Concrete PackageVersion currently resolved by the version pin, or null when latest has no published version yet." + } + }, + "required": [ + "id", + "version_pin", + "default_version_id" + ], + "additionalProperties": false, + "description": "Reference to the Package backing this product. Fetch full details via `GET /v1/packages/{id}`." + }, + "custom_image": { + "type": "string", + "description": "Custom display image URL — overrides the package logo on dashboard catalog rows" + }, + "marketplace": { + "$ref": "#/components/schemas/ProductMarketplaceState" + }, + "created_at": { + "type": "integer", + "minimum": 0, + "description": "Unix timestamp (seconds)" + }, + "updated_at": { + "type": "integer", + "minimum": 0, + "description": "Unix timestamp (seconds)" + }, + "etag": { + "type": "string" + }, + "state": { + "type": "string", + "enum": [ + "active", + "archived" + ], + "description": "Product lifecycle state." + }, + "archived_at": { + "type": "integer", + "minimum": 0, + "description": "When the product was archived, expressed as Unix seconds since epoch." + }, + "archive_reason": { + "type": "string", + "description": "Reason supplied by the seller when archiving." }, "cluster_count": { "type": "integer", @@ -2022,6 +13009,177 @@ "shortHash" ] }, + "ProductDashboard": { + "type": "object", + "properties": { + "product_id": { + "type": "string", + "minLength": 1, + "maxLength": 55, + "example": "prod_j572abc123def456" + }, + "summary": { + "$ref": "#/components/schemas/ProductDashboardSummary" + } + }, + "required": [ + "product_id", + "summary" + ], + "additionalProperties": false, + "x-platform-visibility": "INTERNAL" + }, + "ProductDashboardSummary": { + "oneOf": [ + { + "type": "object", + "properties": { + "status": { + "type": "string", + "enum": [ + "backfilling" + ] + } + }, + "required": [ + "status" + ], + "additionalProperties": false + }, + { + "type": "object", + "properties": { + "status": { + "type": "string", + "enum": [ + "ready" + ] + }, + "customer_count": { + "type": "integer", + "minimum": 0 + }, + "install_count": { + "type": "integer", + "minimum": 0 + }, + "install_status_counts": { + "type": "object", + "properties": { + "healthy": { + "type": "integer", + "minimum": 0 + }, + "pending": { + "type": "integer", + "minimum": 0 + }, + "degraded": { + "type": "integer", + "minimum": 0 + }, + "failed": { + "type": "integer", + "minimum": 0 + } + }, + "required": [ + "healthy", + "pending", + "degraded", + "failed" + ], + "additionalProperties": false + }, + "offer_count": { + "type": "integer", + "minimum": 0 + }, + "redemption_count": { + "type": "integer", + "minimum": 0 + }, + "version_exposure": { + "oneOf": [ + { + "type": "object", + "properties": { + "status": { + "type": "string", + "enum": [ + "backfilling" + ] + } + }, + "required": [ + "status" + ], + "additionalProperties": false + }, + { + "type": "object", + "properties": { + "status": { + "type": "string", + "enum": [ + "unavailable" + ] + }, + "reason": { + "type": "string", + "enum": [ + "no_resolved_default_version" + ] + } + }, + "required": [ + "status", + "reason" + ], + "additionalProperties": false + }, + { + "type": "object", + "properties": { + "status": { + "type": "string", + "enum": [ + "ready" + ] + }, + "default_version_install_count": { + "type": "integer", + "minimum": 0 + }, + "other_version_install_count": { + "type": "integer", + "minimum": 0 + } + }, + "required": [ + "status", + "default_version_install_count", + "other_version_install_count" + ], + "additionalProperties": false + } + ] + } + }, + "required": [ + "status", + "customer_count", + "install_count", + "install_status_counts", + "offer_count", + "redemption_count", + "version_exposure" + ], + "additionalProperties": false + } + ], + "x-platform-visibility": "INTERNAL" + }, "MarketplaceProductDetail": { "type": "object", "properties": { @@ -2189,6 +13347,429 @@ }, "additionalProperties": false }, + "ProductRolloutList": { + "type": "object", + "properties": { + "data": { + "type": "array", + "items": { + "$ref": "#/components/schemas/ProductRollout" + } + }, + "has_more": { + "type": "boolean", + "description": "True if more items exist after this page." + }, + "next_cursor": { + "type": "string", + "nullable": true, + "description": "Opaque cursor for the next page, or null if no more pages." + } + }, + "required": [ + "data", + "has_more", + "next_cursor" + ], + "x-platform-visibility": "INTERNAL" + }, + "ProductRollout": { + "type": "object", + "properties": { + "id": { + "type": "string", + "minLength": 1, + "maxLength": 55 + }, + "workspace_id": { + "type": "string", + "minLength": 1, + "maxLength": 53 + }, + "product_id": { + "type": "string", + "minLength": 1, + "maxLength": 55 + }, + "target_package_version_id": { + "type": "string", + "minLength": 1, + "maxLength": 55 + }, + "audience": { + "$ref": "#/components/schemas/ProductRolloutAudience" + }, + "pause_policy": { + "$ref": "#/components/schemas/ProductRolloutPausePolicy" + }, + "state": { + "$ref": "#/components/schemas/ProductRolloutState" + }, + "pause_reason": { + "oneOf": [ + { + "type": "object", + "properties": { + "type": { + "type": "string", + "enum": [ + "manual" + ] + } + }, + "required": [ + "type" + ] + }, + { + "type": "object", + "properties": { + "type": { + "type": "string", + "enum": [ + "first_failure" + ] + }, + "install_id": { + "type": "string", + "minLength": 1, + "maxLength": 55 + }, + "failure_code": { + "type": "string" + } + }, + "required": [ + "type", + "install_id", + "failure_code" + ] + } + ] + }, + "paused_at": { + "type": "integer", + "minimum": 0, + "description": "Unix timestamp (seconds)" + }, + "progress": { + "type": "object", + "properties": { + "materialization_complete": { + "type": "boolean" + }, + "total": { + "type": "integer", + "minimum": 0 + }, + "pending": { + "type": "integer", + "minimum": 0 + }, + "in_progress": { + "type": "integer", + "minimum": 0 + }, + "succeeded": { + "type": "integer", + "minimum": 0 + }, + "failed": { + "type": "integer", + "minimum": 0 + } + }, + "required": [ + "materialization_complete", + "total", + "pending", + "in_progress", + "succeeded", + "failed" + ] + }, + "created_by": { + "type": "string" + }, + "created_at": { + "type": "integer", + "minimum": 0, + "description": "Unix timestamp (seconds)" + }, + "updated_at": { + "type": "integer", + "minimum": 0, + "description": "Unix timestamp (seconds)" + }, + "etag": { + "type": "string" + } + }, + "required": [ + "id", + "workspace_id", + "product_id", + "target_package_version_id", + "audience", + "pause_policy", + "state", + "progress", + "created_by", + "created_at", + "updated_at", + "etag" + ], + "x-platform-visibility": "INTERNAL" + }, + "ProductRolloutAudience": { + "oneOf": [ + { + "type": "object", + "properties": { + "type": { + "type": "string", + "enum": [ + "test" + ] + } + }, + "required": [ + "type" + ], + "additionalProperties": false + }, + { + "type": "object", + "properties": { + "type": { + "type": "string", + "enum": [ + "specified" + ] + }, + "install_ids": { + "type": "array", + "items": { + "type": "string", + "minLength": 1, + "maxLength": 55 + }, + "minItems": 1, + "maxItems": 100 + } + }, + "required": [ + "type", + "install_ids" + ], + "additionalProperties": false + }, + { + "type": "object", + "properties": { + "type": { + "type": "string", + "enum": [ + "all_managed_installs" + ] + } + }, + "required": [ + "type" + ], + "additionalProperties": false + } + ], + "x-platform-visibility": "INTERNAL" + }, + "ProductRolloutPausePolicy": { + "type": "string", + "enum": [ + "manual", + "first_failure" + ], + "x-platform-visibility": "INTERNAL", + "description": "first_failure pauses automatically after the first failed customer target; manual continues until explicitly paused." + }, + "ProductRolloutState": { + "type": "string", + "enum": [ + "running", + "paused", + "completed" + ], + "x-platform-visibility": "INTERNAL" + }, + "ProductRolloutTargetList": { + "type": "object", + "properties": { + "data": { + "type": "array", + "items": { + "$ref": "#/components/schemas/ProductRolloutTarget" + } + }, + "has_more": { + "type": "boolean", + "description": "True if more items exist after this page." + }, + "next_cursor": { + "type": "string", + "nullable": true, + "description": "Opaque cursor for the next page, or null if no more pages." + } + }, + "required": [ + "data", + "has_more", + "next_cursor" + ], + "x-platform-visibility": "INTERNAL" + }, + "ProductRolloutTarget": { + "type": "object", + "properties": { + "id": { + "type": "string", + "minLength": 1, + "maxLength": 56 + }, + "rollout_id": { + "type": "string", + "minLength": 1, + "maxLength": 55 + }, + "install_id": { + "type": "string", + "minLength": 1, + "maxLength": 55 + }, + "customer": { + "type": "object", + "properties": { + "workspace_id": { + "type": "string", + "minLength": 1, + "maxLength": 53 + }, + "display_name": { + "type": "string" + } + }, + "required": [ + "workspace_id", + "display_name" + ] + }, + "source_package_version_id": { + "type": "string", + "minLength": 1, + "maxLength": 55 + }, + "target_package_version_id": { + "type": "string", + "minLength": 1, + "maxLength": 55 + }, + "state": { + "$ref": "#/components/schemas/ProductRolloutTargetState" + }, + "failure": { + "type": "object", + "properties": { + "code": { + "type": "string", + "minLength": 1, + "maxLength": 64 + }, + "message": { + "type": "string", + "minLength": 1, + "maxLength": 500 + } + }, + "required": [ + "code", + "message" + ] + }, + "attempt_count": { + "type": "integer", + "minimum": 0 + }, + "started_at": { + "type": "integer", + "minimum": 0, + "description": "Unix timestamp (seconds)" + }, + "completed_at": { + "type": "integer", + "minimum": 0, + "description": "Unix timestamp (seconds)" + }, + "created_at": { + "type": "integer", + "minimum": 0, + "description": "Unix timestamp (seconds)" + }, + "updated_at": { + "type": "integer", + "minimum": 0, + "description": "Unix timestamp (seconds)" + } + }, + "required": [ + "id", + "rollout_id", + "install_id", + "customer", + "target_package_version_id", + "state", + "attempt_count", + "created_at", + "updated_at" + ], + "x-platform-visibility": "INTERNAL" + }, + "ProductRolloutTargetState": { + "type": "string", + "enum": [ + "pending", + "in_progress", + "succeeded", + "failed" + ], + "x-platform-visibility": "INTERNAL" + }, + "CreateProductRolloutBody": { + "type": "object", + "properties": { + "product_id": { + "type": "string", + "minLength": 1, + "maxLength": 55 + }, + "target_package_version_id": { + "type": "string", + "minLength": 1, + "maxLength": 55 + }, + "audience": { + "$ref": "#/components/schemas/ProductRolloutAudience" + }, + "pause_policy": { + "$ref": "#/components/schemas/ProductRolloutPausePolicy" + } + }, + "required": [ + "product_id", + "target_package_version_id", + "audience" + ], + "additionalProperties": false, + "x-platform-visibility": "INTERNAL", + "description": "Starts a durable Product rollout using a published PackageVersion as the release primitive." + }, "OfferChannel": { "type": "object", "properties": { @@ -2739,7 +14320,7 @@ "items": { "type": "string" }, - "description": "Empty / omitted = anyone authed can claim. Non-empty = the customer's verified email must match. Only returned to authed callers." + "description": "Empty / omitted = anyone authed can claim. Non-empty = the customer's verified email must match. Returned on seller-authorized reads, never on customer resolve." }, "field_values": { "type": "object", @@ -2753,6 +14334,13 @@ "locked": { "type": "boolean", "description": "When true the customer cannot override; submit ignores client value" + }, + "redacted": { + "type": "boolean", + "enum": [ + true + ], + "description": "True when a configured sensitive value was removed from this response" } }, "required": [ @@ -2760,7 +14348,14 @@ "locked" ] }, - "description": "Seller pre-fills keyed by package input-schema property name. Only returned to authed callers whose email matches the allowlist." + "description": "Seller pre-fills keyed by package input-schema property name. Customer resolve returns them only to authenticated authorized callers; values marked x-ui.sensitive are returned as redacted markers, never plaintext." + }, + "customer": { + "$ref": "#/components/schemas/OfferCustomerSnapshot" + }, + "internal_note": { + "type": "string", + "description": "Seller-only internal context. Never returned by customer resolve." }, "tier": { "type": "string", @@ -2863,6 +14458,26 @@ "created_at" ] }, + "OfferCustomerSnapshot": { + "type": "object", + "properties": { + "display_name": { + "type": "string", + "minLength": 1, + "maxLength": 200 + }, + "external_id": { + "type": "string", + "minLength": 1, + "maxLength": 200 + } + }, + "required": [ + "display_name" + ], + "additionalProperties": false, + "description": "Seller-maintained customer context captured when the offer is created. Never returned by customer resolve." + }, "OfferApprovalState": { "type": "string", "enum": [ @@ -3171,7 +14786,7 @@ ] }, "CreateOfferBody": { - "anyOf": [ + "oneOf": [ { "type": "object", "properties": { @@ -3239,16 +14854,13 @@ }, "description": "Package input pre-fills keyed by input-schema property name. Values are validated against the resolved package version input schema before the offer is created." }, - "tier": { - "type": "string", - "maxLength": 32, - "description": "Legacy advisory billing tier for non-channel offers. Do not send this with `offer_channel_id`; channel-backed offers use `commercial_mode` and `pricing_request`." + "customer": { + "$ref": "#/components/schemas/OfferCustomerSnapshot" }, - "offer_channel_id": { + "internal_note": { "type": "string", - "minLength": 1, - "maxLength": 54, - "description": "Offer Channel whose active policy resolves approval, checkout, support, and pricing terms. Requires `product_id`." + "maxLength": 500, + "description": "Seller-only internal context for this offer. Never returned by customer resolve." }, "commercial_mode": { "allOf": [ @@ -3266,7 +14878,7 @@ "notes": { "type": "string", "maxLength": 500, - "description": "Seller-private note for operators reviewing or supporting the offer. Not shown to the customer." + "description": "Seller-authored offer note. Customer resolve returns it only to authenticated callers authorized through an open allowlist or a verified-email match." }, "expires_at": { "type": "integer", @@ -3276,10 +14888,11 @@ }, "max_uses": { "type": "integer", + "nullable": true, "minimum": 0, "exclusiveMinimum": true, "maximum": 10000, - "description": "Maximum number of successful redemptions allowed for this offer. Omit for the default single-use behavior." + "description": "Maximum number of successful redemptions allowed for this offer. Omit for the default single-use behavior; send null for unlimited redemptions." }, "order_ttl_minutes": { "type": "integer", @@ -3287,6 +14900,11 @@ "exclusiveMinimum": true, "maximum": 1440, "description": "Per-redemption order TTL in minutes. Defaults to 120; capped at 1440 (24h)." + }, + "tier": { + "type": "string", + "maxLength": 32, + "description": "Legacy advisory billing tier for non-channel offers. Channel-backed offers use `commercial_mode` and `pricing_request`." } }, "required": [ @@ -3303,12 +14921,131 @@ "maxLength": 55, "description": "Package version ID to pin explicitly at create time. Optional when `product_id` is supplied; if both are supplied, this value overrides the product’s current package version pin." }, + "target_workspace_id": { + "type": "string", + "minLength": 1, + "maxLength": 53, + "description": "Trusted-partner delivery target. When supplied, the redeemed order is created for this existing customer workspace instead of selecting or creating a workspace during checkout. Requires the target-existing-workspace entitlement and customer workspace membership.", + "x-platform-visibility": "TRUSTED_PARTNER" + }, + "region_id": { + "type": "string", + "minLength": 1, + "maxLength": 54, + "description": "Trusted-partner delivery region pin. Requires a fixed delivery workspace or pinned cluster and the target-managed-workspace entitlement.", + "x-platform-visibility": "TRUSTED_PARTNER" + }, + "cluster_id": { + "type": "string", + "minLength": 1, + "maxLength": 54, + "description": "Trusted-partner delivery cluster pin. The cluster must belong to the delivery workspace and requires the target-managed-workspace entitlement.", + "x-platform-visibility": "TRUSTED_PARTNER" + }, + "allowed_emails": { + "type": "array", + "items": { + "type": "string", + "maxLength": 254, + "format": "email" + }, + "maxItems": 50, + "description": "Verified customer email allowlist. Empty or omitted means any authenticated customer can redeem the offer." + }, + "field_values": { + "type": "object", + "additionalProperties": { + "type": "object", + "properties": { + "value": { + "nullable": true, + "description": "Pre-fill value for this schema property" + }, + "locked": { + "type": "boolean", + "description": "When true the customer cannot override; submit ignores client value" + } + }, + "required": [ + "value", + "locked" + ] + }, + "description": "Package input pre-fills keyed by input-schema property name. Values are validated against the resolved package version input schema before the offer is created." + }, + "customer": { + "$ref": "#/components/schemas/OfferCustomerSnapshot" + }, + "internal_note": { + "type": "string", + "maxLength": 500, + "description": "Seller-only internal context for this offer. Never returned by customer resolve." + }, + "commercial_mode": { + "allOf": [ + { + "$ref": "#/components/schemas/CommercialMode" + }, + { + "description": "Requested customer path for channel policy resolution. This is not settlement authority; the active channel policy decides the final terms." + } + ] + }, + "pricing_request": { + "$ref": "#/components/schemas/OfferPricingRequest" + }, + "notes": { + "type": "string", + "maxLength": 500, + "description": "Seller-authored offer note. Customer resolve returns it only to authenticated callers authorized through an open allowlist or a verified-email match." + }, + "expires_at": { + "type": "integer", + "minimum": 0, + "exclusiveMinimum": true, + "description": "Unix timestamp in seconds after which the offer can no longer be redeemed. Omit for no explicit expiration." + }, + "max_uses": { + "type": "integer", + "nullable": true, + "minimum": 0, + "exclusiveMinimum": true, + "maximum": 10000, + "description": "Maximum number of successful redemptions allowed for this offer. Omit for the default single-use behavior; send null for unlimited redemptions." + }, + "order_ttl_minutes": { + "type": "integer", + "minimum": 0, + "exclusiveMinimum": true, + "maximum": 1440, + "description": "Per-redemption order TTL in minutes. Defaults to 120; capped at 1440 (24h)." + }, + "tier": { + "type": "string", + "maxLength": 32, + "description": "Legacy advisory billing tier for non-channel offers. Channel-backed offers use `commercial_mode` and `pricing_request`." + } + }, + "required": [ + "package_version_id" + ], + "additionalProperties": false + }, + { + "type": "object", + "properties": { "product_id": { "type": "string", "minLength": 1, "maxLength": 55, "description": "Product ID for attribution and package-version resolution. Required for channel-backed offers. When `package_version_id` is omitted, the server uses the product’s current package version pin." }, + "package_version_id": { + "type": "string", + "minLength": 1, + "maxLength": 55, + "description": "Package version ID to pin explicitly at create time. Optional when `product_id` is supplied; if both are supplied, this value overrides the product’s current package version pin." + }, "target_workspace_id": { "type": "string", "minLength": 1, @@ -3361,16 +15098,13 @@ }, "description": "Package input pre-fills keyed by input-schema property name. Values are validated against the resolved package version input schema before the offer is created." }, - "tier": { - "type": "string", - "maxLength": 32, - "description": "Legacy advisory billing tier for non-channel offers. Do not send this with `offer_channel_id`; channel-backed offers use `commercial_mode` and `pricing_request`." + "customer": { + "$ref": "#/components/schemas/OfferCustomerSnapshot" }, - "offer_channel_id": { + "internal_note": { "type": "string", - "minLength": 1, - "maxLength": 54, - "description": "Offer Channel whose active policy resolves approval, checkout, support, and pricing terms. Requires `product_id`." + "maxLength": 500, + "description": "Seller-only internal context for this offer. Never returned by customer resolve." }, "commercial_mode": { "allOf": [ @@ -3388,7 +15122,7 @@ "notes": { "type": "string", "maxLength": 500, - "description": "Seller-private note for operators reviewing or supporting the offer. Not shown to the customer." + "description": "Seller-authored offer note. Customer resolve returns it only to authenticated callers authorized through an open allowlist or a verified-email match." }, "expires_at": { "type": "integer", @@ -3398,10 +15132,11 @@ }, "max_uses": { "type": "integer", + "nullable": true, "minimum": 0, "exclusiveMinimum": true, "maximum": 10000, - "description": "Maximum number of successful redemptions allowed for this offer. Omit for the default single-use behavior." + "description": "Maximum number of successful redemptions allowed for this offer. Omit for the default single-use behavior; send null for unlimited redemptions." }, "order_ttl_minutes": { "type": "integer", @@ -3409,15 +15144,23 @@ "exclusiveMinimum": true, "maximum": 1440, "description": "Per-redemption order TTL in minutes. Defaults to 120; capped at 1440 (24h)." + }, + "offer_channel_id": { + "type": "string", + "minLength": 1, + "maxLength": 54, + "description": "Offer Channel whose active policy resolves approval, checkout, support, and pricing terms." } }, "required": [ - "package_version_id" + "product_id", + "offer_channel_id" ], "additionalProperties": false } ], - "description": "Provide either `product_id` or `package_version_id`. Product-backed requests may omit `package_version_id`; the server resolves the product’s current package version pin at create time, validates `field_values` against the resolved package version input schema, and stores the resolved package version on the offer." + "description": "Provide either `product_id` or `package_version_id`. Product-backed requests may omit `package_version_id`; the server resolves the product’s current package version pin at create time, validates `field_values` against the resolved package version input schema, and stores the resolved package version on the offer.", + "x-platform-exact-union": true }, "OrderDraft": { "type": "object", @@ -3914,6 +15657,10 @@ "type": "string", "minLength": 1, "maxLength": 100 + }, + "allow_seller_management": { + "type": "boolean", + "description": "Whether the seller organization may manage this customer-owned workspace. Defaults to true when omitted." } }, "required": [ @@ -4508,1834 +16255,2666 @@ "completed_at" ] }, - "OperationMetadata": { + "DashboardInstallList": { + "type": "object", + "properties": { + "data": { + "type": "array", + "items": { + "$ref": "#/components/schemas/DashboardInstall" + } + }, + "has_more": { + "type": "boolean", + "description": "True if more items exist after this page." + }, + "next_cursor": { + "type": "string", + "nullable": true, + "description": "Opaque cursor for the next page, or null if no more pages." + } + }, + "required": [ + "data", + "has_more", + "next_cursor" + ] + }, + "DashboardInstall": { + "type": "object", + "properties": { + "id": { + "type": "string", + "minLength": 1, + "maxLength": 55 + }, + "html_url": { + "type": "string", + "maxLength": 2048, + "format": "uri", + "description": "Absolute dashboard URL for this resource. OUTPUT_ONLY.", + "example": "https://akua.dev/installs/inst_j572abc123def456" + }, + "name": { + "type": "string", + "nullable": true, + "description": "Authoritative install display name for this projection. Null when unavailable." + }, + "workspace_id": { + "type": "string", + "minLength": 1, + "maxLength": 53 + }, + "cluster_id": { + "type": "string", + "minLength": 1, + "maxLength": 54 + }, + "cluster_name": { + "type": "string" + }, + "region_name": { + "type": "string" + }, + "region_icon": { + "type": "string", + "nullable": true + }, + "display_image_url": { + "type": "string", + "nullable": true, + "maxLength": 2048, + "format": "uri" + }, + "source": { + "$ref": "#/components/schemas/DashboardInstallSource" + }, + "application_access": { + "$ref": "#/components/schemas/DashboardInstallApplicationAccess" + }, + "state": { + "type": "string", + "enum": [ + "pending", + "rendering", + "syncing", + "healthy", + "degraded", + "failed" + ], + "description": "Lifecycle state for an extant dashboard install. Deleted installs are excluded before list pagination." + }, + "reconciling": { + "type": "boolean" + }, + "created_at": { + "type": "integer", + "minimum": 0, + "description": "Unix timestamp (seconds)" + }, + "updated_at": { + "type": "integer", + "minimum": 0, + "description": "Unix timestamp (seconds)" + }, + "etag": { + "type": "string" + } + }, + "required": [ + "id", + "html_url", + "name", + "workspace_id", + "cluster_id", + "cluster_name", + "region_name", + "region_icon", + "display_image_url", + "source", + "application_access", + "state", + "reconciling", + "created_at", + "updated_at", + "etag" + ] + }, + "DashboardInstallSource": { "oneOf": [ { "type": "object", "properties": { - "type": { + "kind": { "type": "string", "enum": [ - "machine.create" + "product" ] }, - "workspace_id": { - "type": "string", - "minLength": 1, - "maxLength": 53 - }, - "cluster_id": { - "type": "string", - "minLength": 1, - "maxLength": 54 - }, - "compute_config_id": { + "id": { "type": "string", "minLength": 1, - "maxLength": 54 + "maxLength": 55 }, - "instance_type": { + "name": { "type": "string" }, - "managed": { - "type": "boolean" - }, - "request_fingerprint": { - "type": "string", - "minLength": 1 - } - }, - "required": [ - "type", - "workspace_id", - "cluster_id", - "instance_type", - "managed", - "request_fingerprint" - ] - }, - { - "type": "object", - "properties": { - "type": { - "type": "string", - "enum": [ - "cluster.delete" - ] - }, - "cluster_id": { - "type": "string", - "minLength": 1, - "maxLength": 54 + "version": { + "$ref": "#/components/schemas/PackageVersionSummary" } }, "required": [ - "type", - "cluster_id" - ] + "kind", + "id", + "name", + "version" + ], + "additionalProperties": false }, { "type": "object", "properties": { - "type": { + "kind": { "type": "string", "enum": [ - "cluster.create" + "package" ] }, - "workspace_id": { - "type": "string", - "minLength": 1, - "maxLength": 53 - }, - "region_id": { + "id": { "type": "string", "minLength": 1, "maxLength": 54 }, "name": { "type": "string" + }, + "version": { + "$ref": "#/components/schemas/PackageVersionSummary" } }, "required": [ - "type", - "workspace_id", - "region_id", - "name" - ] + "kind", + "id", + "name", + "version" + ], + "additionalProperties": false }, { - "type": "object", - "properties": { - "type": { - "type": "string", - "enum": [ - "cluster.suspend" - ] - }, - "cluster_id": { - "type": "string", - "minLength": 1, - "maxLength": 54 - } - }, - "required": [ - "type", - "cluster_id" - ] + "nullable": true + } + ], + "description": "Null only for legacy or incomplete persisted lineage; source identity and version are never fabricated." + }, + "PackageVersionSummary": { + "type": "object", + "properties": { + "id": { + "type": "string", + "minLength": 1, + "maxLength": 55 }, + "semver": { + "type": "string", + "minLength": 1, + "maxLength": 128, + "pattern": "^(0|[1-9]\\d*)\\.(0|[1-9]\\d*)\\.(0|[1-9]\\d*)(?:-((?:0|[1-9]\\d*|[0-9A-Za-z-]*[A-Za-z-][0-9A-Za-z-]*)(?:\\.(?:0|[1-9]\\d*|[0-9A-Za-z-]*[A-Za-z-][0-9A-Za-z-]*))*))?(?:\\+([0-9A-Za-z-]+(?:\\.[0-9A-Za-z-]+)*))?$" + } + }, + "required": [ + "id", + "semver" + ] + }, + "DashboardInstallApplicationAccess": { + "oneOf": [ { "type": "object", "properties": { - "type": { + "state": { "type": "string", "enum": [ - "cluster.resume" + "loading" ] - }, - "cluster_id": { - "type": "string", - "minLength": 1, - "maxLength": 54 } }, "required": [ - "type", - "cluster_id" - ] + "state" + ], + "additionalProperties": false }, { "type": "object", "properties": { - "type": { + "state": { "type": "string", "enum": [ - "cluster.capabilities.refresh" + "available" ] }, - "cluster_id": { + "hostname": { + "type": "string" + }, + "url": { "type": "string", - "minLength": 1, - "maxLength": 54 + "format": "uri" } }, "required": [ - "type", - "cluster_id" - ] + "state", + "hostname", + "url" + ], + "additionalProperties": false }, { "type": "object", "properties": { - "type": { + "state": { "type": "string", "enum": [ - "cluster.capability.ensure" + "unavailable" ] - }, - "cluster_id": { - "type": "string", - "minLength": 1, - "maxLength": 54 - }, - "capability": { - "type": "string", - "minLength": 1 } }, "required": [ - "type", - "cluster_id", - "capability" - ] + "state" + ], + "additionalProperties": false + } + ], + "description": "Public application access derived from persisted route state. Available URLs are authoritative; loading and unavailable states never fabricate a hostname." + }, + "DashboardInstallDetail": { + "type": "object", + "properties": { + "id": { + "type": "string", + "minLength": 1, + "maxLength": 55 }, - { + "html_url": { + "type": "string", + "maxLength": 2048, + "format": "uri", + "description": "Absolute dashboard URL for this resource. OUTPUT_ONLY.", + "example": "https://akua.dev/installs/inst_j572abc123def456" + }, + "workspace_id": { + "type": "string", + "minLength": 1, + "maxLength": 53 + }, + "cluster_id": { + "type": "string", + "minLength": 1, + "maxLength": 54 + }, + "deploy_repository_id": { + "type": "string", + "nullable": true, + "minLength": 1, + "maxLength": 55 + }, + "name": { + "type": "string", + "nullable": true, + "description": "Authoritative install display name for this projection. Null when unavailable." + }, + "is_standalone": { + "type": "boolean" + }, + "argo_app_namespace": { + "type": "string" + }, + "public_urls": { + "type": "array", + "items": { + "$ref": "#/components/schemas/InstallUrl" + } + }, + "argo_status": { + "$ref": "#/components/schemas/DashboardInstallArgoStatus" + }, + "cluster": { "type": "object", "properties": { - "type": { - "type": "string", - "enum": [ - "cluster.worker_bootstrap.revoke" - ] - }, - "cluster_id": { + "id": { "type": "string", "minLength": 1, "maxLength": 54 }, - "worker_bootstrap_id": { - "type": "string", - "minLength": 1, - "maxLength": 54 + "name": { + "type": "string" + }, + "region": { + "type": "object", + "properties": { + "name": { + "type": "string" + }, + "icon": { + "type": "string", + "nullable": true + } + }, + "required": [ + "name", + "icon" + ] } }, "required": [ - "type", - "cluster_id", - "worker_bootstrap_id" + "id", + "name", + "region" ] }, - { + "display_image_url": { + "type": "string", + "nullable": true, + "maxLength": 2048, + "format": "uri" + }, + "product": { "type": "object", + "nullable": true, "properties": { - "type": { + "id": { "type": "string", - "enum": [ - "install.create" - ] + "minLength": 1, + "maxLength": 55 }, - "idempotency_key": { + "name": { "type": "string" }, - "workspace_id": { - "type": "string", - "minLength": 1, - "maxLength": 53 - }, - "product_id": { - "type": "string", - "minLength": 1, - "maxLength": 55 + "is_owner": { + "type": "boolean" } }, "required": [ - "type", - "idempotency_key", - "workspace_id" + "id", + "name", + "is_owner" ] }, - { + "package": { "type": "object", + "nullable": true, "properties": { - "type": { - "type": "string", - "enum": [ - "install.render" - ] - }, - "install_id": { + "id": { "type": "string", "minLength": 1, - "maxLength": 55 + "maxLength": 54 }, - "trigger_commit_sha": { + "name": { "type": "string" - } - }, - "required": [ - "type", - "install_id" - ] - }, - { - "type": "object", - "properties": { - "type": { + }, + "source_kind": { "type": "string", "enum": [ - "install.delete" + "hosted", + "oci" ] }, - "install_id": { - "type": "string", - "minLength": 1, - "maxLength": 55 + "version": { + "$ref": "#/components/schemas/PackageVersionSummary" } }, "required": [ - "type", - "install_id" + "id", + "name", + "source_kind", + "version" ] }, - { + "target_revision": { + "type": "string", + "nullable": true + }, + "demo_cleanup": { + "$ref": "#/components/schemas/InstallDemoCleanup" + }, + "created_at": { + "type": "integer", + "minimum": 0, + "description": "Unix timestamp (seconds)" + }, + "updated_at": { + "type": "integer", + "minimum": 0, + "description": "Unix timestamp (seconds)" + }, + "etag": { + "type": "string" + } + }, + "required": [ + "id", + "html_url", + "workspace_id", + "cluster_id", + "deploy_repository_id", + "name", + "is_standalone", + "argo_app_namespace", + "public_urls", + "argo_status", + "cluster", + "display_image_url", + "product", + "package", + "target_revision", + "created_at", + "updated_at", + "etag" + ] + }, + "InstallUrl": { + "type": "object", + "properties": { + "route_key": { + "type": "string" + }, + "hostname": { + "type": "string" + }, + "url": { + "type": "string", + "format": "uri" + }, + "protocol": { + "type": "string", + "enum": [ + "http", + "websocket", + "grpc" + ], + "description": "Transport class for route forwarding." + }, + "routing_mode": { + "type": "string", + "enum": [ + "through_dispatcher", + "bypass_dispatcher" + ], + "description": "Whether traffic uses the dispatcher Worker or bypasses it." + }, + "status": { + "type": "string", + "enum": [ + "pending", + "provisioning", + "active", + "not_ready", + "failed" + ], + "description": "Customer-facing install URL routing state." + }, + "error": { + "type": "string" + }, + "last_observed_at": { + "type": "integer", + "minimum": 0, + "description": "Unix timestamp (seconds)" + }, + "updated_at": { + "type": "integer", + "minimum": 0, + "description": "Unix timestamp (seconds)" + } + }, + "required": [ + "route_key", + "hostname", + "url", + "protocol", + "routing_mode", + "status", + "updated_at" + ] + }, + "DashboardInstallArgoStatus": { + "type": "object", + "nullable": true, + "properties": { + "status": { "type": "object", "properties": { - "type": { - "type": "string", - "enum": [ - "preview_hostname.bind_pinned" - ] - }, - "install_id": { - "type": "string", - "minLength": 1, - "maxLength": 55 - }, - "render_id": { - "type": "string", - "minLength": 1, - "maxLength": 54 + "health": { + "type": "object", + "properties": { + "status": { + "type": "string" + } + }, + "required": [ + "status" + ], + "additionalProperties": { + "nullable": true + } }, - "protocol": { - "type": "string", - "enum": [ - "http", - "websocket", - "grpc" - ] + "sync": { + "type": "object", + "properties": { + "status": { + "type": "string" + }, + "revision": { + "type": "string" + } + }, + "required": [ + "status" + ], + "additionalProperties": { + "nullable": true + } }, - "routing_mode": { - "type": "string", - "enum": [ - "through_dispatcher", - "bypass_dispatcher" - ] + "operation_state": { + "type": "object", + "properties": { + "phase": { + "type": "string" + } + }, + "required": [ + "phase" + ], + "additionalProperties": { + "nullable": true + } }, - "idempotency_key": { - "type": "string" + "resources": { + "type": "array", + "items": { + "$ref": "#/components/schemas/ResourceStatus" + } } }, "required": [ - "type", - "install_id", - "render_id", - "protocol", - "routing_mode", - "idempotency_key" - ] + "health", + "sync", + "resources" + ], + "additionalProperties": { + "nullable": true + } }, - { + "updated_at": { + "type": "integer", + "minimum": 0, + "description": "Unix timestamp (seconds)" + } + }, + "required": [ + "status", + "updated_at" + ] + }, + "ResourceStatus": { + "type": "object", + "properties": { + "group": { + "type": "string" + }, + "kind": { + "type": "string" + }, + "name": { + "type": "string" + }, + "message": { + "type": "string" + }, + "namespace": { + "type": "string" + }, + "version": { + "type": "string" + }, + "status": { + "type": "string" + }, + "health": { "type": "object", "properties": { - "type": { - "type": "string", - "enum": [ - "preview_hostname.bind_floating" - ] - }, - "install_id": { - "type": "string", - "minLength": 1, - "maxLength": 55 - }, - "track": { - "type": "string", - "minLength": 1, - "maxLength": 100 - }, - "render_id": { - "type": "string", - "minLength": 1, - "maxLength": 54 - }, - "protocol": { - "type": "string", - "enum": [ - "http", - "websocket", - "grpc" - ] - }, - "routing_mode": { - "type": "string", - "enum": [ - "through_dispatcher", - "bypass_dispatcher" - ] + "status": { + "type": "string" }, - "idempotency_key": { + "message": { "type": "string" } }, "required": [ - "type", - "install_id", - "track", - "render_id", - "protocol", - "routing_mode", - "idempotency_key" + "status" ] - }, + } + }, + "required": [ + "kind", + "name" + ], + "additionalProperties": { + "nullable": true + } + }, + "InstallDemoCleanup": { + "oneOf": [ { "type": "object", "properties": { - "type": { + "kind": { "type": "string", "enum": [ - "preview_hostname.delete" + "scheduled" ] }, - "install_id": { - "type": "string", - "minLength": 1, - "maxLength": 55 + "cleanup_at": { + "type": "integer", + "minimum": 0, + "description": "Unix timestamp when the non-billable demo install is scheduled for cleanup." }, - "preview_hostname_id": { + "removable_by": { "type": "string", - "minLength": 1, - "maxLength": 54 - }, - "if_match": { - "type": "string" + "enum": [ + "platform_policy", + "platform_admin" + ], + "description": "Authority that may remove the scheduled cleanup policy." }, - "idempotency_key": { - "type": "string" - } - }, - "required": [ - "type", - "install_id", - "preview_hostname_id", - "if_match", - "idempotency_key" - ] - }, - { - "type": "object", - "properties": { - "type": { + "conversion_required": { "type": "string", "enum": [ - "workspace.delete" - ] + "paid_order", + "platform_approval" + ], + "description": "Required approval path before the demo install can continue without cleanup." }, - "workspace_id": { + "delivery_status": { "type": "string", - "minLength": 1, - "maxLength": 53 + "enum": [ + "pending", + "running", + "succeeded", + "failed" + ], + "description": "Order delivery status for the install that owns this cleanup policy." } }, "required": [ - "type", - "workspace_id" - ] + "kind", + "cleanup_at", + "removable_by", + "conversion_required", + "delivery_status" + ], + "additionalProperties": false }, { "type": "object", "properties": { - "type": { + "kind": { "type": "string", "enum": [ - "workspace.subscription.cancel" + "removed" ] }, - "workspace_id": { - "type": "string", - "minLength": 1, - "maxLength": 53 - }, - "mode": { + "delivery_status": { "type": "string", "enum": [ - "period_end" - ] + "pending", + "running", + "succeeded", + "failed" + ], + "description": "Order delivery status for the demo install whose cleanup was removed." } }, "required": [ - "type", - "workspace_id", - "mode" - ] + "kind", + "delivery_status" + ], + "additionalProperties": false + } + ], + "description": "Visible cleanup state for non-billable demo installs. Temporal workflow IDs and internal cleanup evidence are intentionally omitted." + }, + "ManagedInstallList": { + "type": "object", + "properties": { + "data": { + "type": "array", + "items": { + "$ref": "#/components/schemas/ManagedInstall" + } }, - { + "has_more": { + "type": "boolean", + "description": "True if more items exist after this page." + }, + "next_cursor": { + "type": "string", + "nullable": true, + "description": "Opaque cursor for the next page, or null if no more pages." + } + }, + "required": [ + "data", + "has_more", + "next_cursor" + ] + }, + "ManagedInstall": { + "type": "object", + "properties": { + "id": { + "type": "string", + "minLength": 1, + "maxLength": 55 + }, + "name": { + "type": "string", + "nullable": true, + "description": "Authoritative install display name for this projection. Null when unavailable." + }, + "customer": { "type": "object", "properties": { - "type": { - "type": "string", - "enum": [ - "workspace.subdomain.set_name" - ] - }, "workspace_id": { "type": "string", "minLength": 1, "maxLength": 53 }, "name": { - "type": "string", - "minLength": 1, - "maxLength": 63 - }, - "idempotency_key": { "type": "string" + }, + "icon": { + "type": "string", + "nullable": true } }, "required": [ - "type", "workspace_id", "name", - "idempotency_key" + "icon" ] }, - { + "can_manage": { + "type": "boolean" + }, + "product": { "type": "object", + "nullable": true, "properties": { - "type": { - "type": "string", - "enum": [ - "custom_domain.create" - ] - }, - "workspace_id": { - "type": "string", - "minLength": 1, - "maxLength": 53 - }, - "hostname": { + "id": { "type": "string", "minLength": 1, - "maxLength": 253 - }, - "target": { - "oneOf": [ - { - "type": "object", - "properties": { - "kind": { - "type": "string", - "enum": [ - "install" - ] - }, - "install_id": { - "type": "string", - "minLength": 1, - "maxLength": 55 - } - }, - "required": [ - "kind", - "install_id" - ] - }, - { - "type": "object", - "properties": { - "kind": { - "type": "string", - "enum": [ - "cluster" - ] - }, - "cluster_id": { - "type": "string", - "minLength": 1, - "maxLength": 54 - } - }, - "required": [ - "kind", - "cluster_id" - ] - }, - { - "type": "object", - "properties": { - "kind": { - "type": "string", - "enum": [ - "external" - ] - }, - "endpoint": { - "type": "string", - "format": "uri" - }, - "mtls_secret_id": { - "type": "string", - "minLength": 1, - "maxLength": 54 - } - }, - "required": [ - "kind", - "endpoint" - ] - } - ] - }, - "protocol": { - "type": "string", - "enum": [ - "http", - "websocket", - "grpc" - ] - }, - "routing_mode": { - "type": "string", - "enum": [ - "through_dispatcher", - "bypass_dispatcher" - ] + "maxLength": 55 }, - "idempotency_key": { + "name": { "type": "string" } }, "required": [ - "type", - "workspace_id", - "hostname", - "target", - "protocol", - "routing_mode", - "idempotency_key" + "id", + "name" ] }, - { - "type": "object", - "properties": { - "type": { - "type": "string", - "enum": [ - "custom_domain.update" - ] - }, - "workspace_id": { - "type": "string", - "minLength": 1, - "maxLength": 53 - }, - "custom_domain_id": { - "type": "string", - "minLength": 1, - "maxLength": 54 + "version": { + "anyOf": [ + { + "$ref": "#/components/schemas/PackageVersionSummary" }, - "target": { - "oneOf": [ - { - "type": "object", - "properties": { - "kind": { - "type": "string", - "enum": [ - "install" - ] - }, - "install_id": { - "type": "string", - "minLength": 1, - "maxLength": 55 - } - }, - "required": [ - "kind", - "install_id" - ] - }, - { - "type": "object", - "properties": { - "kind": { - "type": "string", - "enum": [ - "cluster" - ] - }, - "cluster_id": { - "type": "string", - "minLength": 1, - "maxLength": 54 - } - }, - "required": [ - "kind", - "cluster_id" - ] - }, - { - "type": "object", - "properties": { - "kind": { - "type": "string", - "enum": [ - "external" - ] - }, - "endpoint": { - "type": "string", - "format": "uri" - }, - "mtls_secret_id": { - "type": "string", - "minLength": 1, - "maxLength": 54 - } - }, - "required": [ - "kind", - "endpoint" - ] - } - ] + { + "nullable": true + } + ] + }, + "current_version": { + "anyOf": [ + { + "$ref": "#/components/schemas/PackageVersionSummary" }, - "protocol": { - "type": "string", - "enum": [ - "http", - "websocket", - "grpc" - ] + { + "nullable": true + } + ] + }, + "desired_version": { + "anyOf": [ + { + "$ref": "#/components/schemas/PackageVersionSummary" }, - "routing_mode": { - "type": "string", - "enum": [ - "through_dispatcher", - "bypass_dispatcher" - ] + { + "nullable": true + } + ] + }, + "available_version": { + "anyOf": [ + { + "$ref": "#/components/schemas/PackageVersionSummary" }, - "if_match": { - "type": "string" + { + "nullable": true + } + ] + }, + "automatic_updates_enabled": { + "type": "boolean" + }, + "lifecycle_revision": { + "type": "integer", + "minimum": 0 + }, + "etag": { + "type": "string" + }, + "rollback_target": { + "anyOf": [ + { + "$ref": "#/components/schemas/ManagedInstallRollbackTarget" }, - "idempotency_key": { - "type": "string" + { + "nullable": true } - }, - "required": [ - "type", - "workspace_id", - "custom_domain_id", - "if_match", - "idempotency_key" ] }, - { + "cluster": { "type": "object", + "nullable": true, "properties": { - "type": { - "type": "string", - "enum": [ - "custom_domain.delete" - ] - }, - "workspace_id": { - "type": "string", - "minLength": 1, - "maxLength": 53 - }, - "custom_domain_id": { + "id": { "type": "string", "minLength": 1, "maxLength": 54 }, - "if_match": { - "type": "string" - }, - "idempotency_key": { + "name": { "type": "string" } }, "required": [ - "type", - "workspace_id", - "custom_domain_id", - "if_match", - "idempotency_key" + "id", + "name" ] }, - { + "region": { "type": "object", + "nullable": true, "properties": { - "type": { - "type": "string", - "enum": [ - "cloudflare.private_origin_route.prepare" - ] - }, - "workspace_id": { - "type": "string", - "minLength": 1, - "maxLength": 53 - }, - "cluster_id": { + "id": { "type": "string", "minLength": 1, "maxLength": 54 }, - "route_intent_id": { + "name": { + "type": "string" + }, + "icon": { "type": "string", - "minLength": 1, - "maxLength": 54 + "nullable": true } }, "required": [ - "type", - "workspace_id", - "cluster_id", - "route_intent_id" + "id", + "name", + "icon" + ] + }, + "health": { + "type": "string", + "nullable": true, + "enum": [ + "Unknown", + "Progressing", + "Healthy", + "Suspended", + "Degraded", + "Missing", + null ] }, + "state": { + "type": "string", + "enum": [ + "pending", + "rendering", + "syncing", + "healthy", + "degraded", + "failed", + "deleted" + ], + "description": "Install lifecycle state from the control plane perspective." + }, + "reconciling": { + "type": "boolean" + }, + "urls": { + "type": "array", + "items": { + "$ref": "#/components/schemas/InstallUrl" + } + }, + "update_available": { + "type": "boolean" + }, + "attention_reasons": { + "type": "array", + "items": { + "type": "string", + "enum": [ + "deployment_failed", + "deployment_degraded", + "reconciling", + "url_failed", + "update_available", + "lineage_incomplete" + ] + } + }, + "created_at": { + "type": "integer", + "minimum": 0, + "description": "Unix timestamp (seconds)" + }, + "updated_at": { + "type": "integer", + "minimum": 0, + "description": "Unix timestamp (seconds)" + } + }, + "required": [ + "id", + "name", + "customer", + "can_manage", + "product", + "version", + "current_version", + "desired_version", + "available_version", + "automatic_updates_enabled", + "lifecycle_revision", + "etag", + "rollback_target", + "cluster", + "region", + "health", + "state", + "reconciling", + "urls", + "update_available", + "attention_reasons", + "created_at", + "updated_at" + ], + "description": "A bounded operations projection for an install in a workspace managed by the requesting organization." + }, + "ManagedInstallRollbackTarget": { + "type": "object", + "properties": { + "render_id": { + "type": "string", + "minLength": 1, + "maxLength": 54 + }, + "version": { + "$ref": "#/components/schemas/PackageVersionSummary" + }, + "commit_sha": { + "type": "string" + }, + "created_at": { + "type": "integer", + "minimum": 0, + "description": "Unix timestamp (seconds)" + } + }, + "required": [ + "render_id", + "version", + "commit_sha", + "created_at" + ] + }, + "ProductAttentionResponse": { + "oneOf": [ { "type": "object", "properties": { - "type": { - "type": "string", - "enum": [ - "cloudflare.private_origin_route.release" - ] - }, - "workspace_id": { + "product_id": { "type": "string", "minLength": 1, - "maxLength": 53 + "maxLength": 55 }, - "route_intent_id": { + "status": { "type": "string", - "minLength": 1, - "maxLength": 54 + "enum": [ + "backfilling" + ] } }, "required": [ - "type", - "workspace_id", - "route_intent_id" - ] + "product_id", + "status" + ], + "additionalProperties": false }, { "type": "object", "properties": { - "type": { + "product_id": { + "type": "string", + "minLength": 1, + "maxLength": 55 + }, + "status": { "type": "string", "enum": [ - "package.create" + "ready" ] }, - "idempotency_key": { - "type": "string" + "data": { + "type": "array", + "items": { + "$ref": "#/components/schemas/ProductAttentionInstall" + } }, - "workspace_id": { - "type": "string", - "minLength": 1, - "maxLength": 53 + "has_more": { + "type": "boolean" }, - "name": { - "type": "string" + "next_cursor": { + "type": "string", + "nullable": true } }, "required": [ - "type", - "idempotency_key", - "workspace_id", - "name" - ] + "product_id", + "status", + "data", + "has_more", + "next_cursor" + ], + "additionalProperties": false + } + ], + "x-platform-visibility": "INTERNAL" + }, + "ProductAttentionInstall": { + "allOf": [ + { + "$ref": "#/components/schemas/Install" }, { "type": "object", "properties": { - "type": { + "attention_status": { "type": "string", "enum": [ - "repository_change_request.create" + "degraded", + "failed" ] }, - "workspace_id": { - "type": "string", - "minLength": 1, - "maxLength": 53 - }, - "parent_repository_id": { - "type": "string", - "minLength": 1, - "maxLength": 55 - }, - "created_by_kind": { - "type": "string", - "enum": [ - "agent", - "wizard", - "user" - ] + "status_updated_at": { + "type": "integer", + "minimum": 0, + "description": "Unix timestamp (seconds)" } }, "required": [ - "type", - "workspace_id", - "parent_repository_id", - "created_by_kind" + "attention_status", + "status_updated_at" + ] + } + ], + "x-platform-visibility": "INTERNAL" + }, + "InstallCustomerWorkspace": { + "type": "object", + "properties": { + "id": { + "type": "string", + "minLength": 1, + "maxLength": 53 + }, + "name": { + "type": "string", + "minLength": 1, + "maxLength": 100 + } + }, + "required": [ + "id", + "name" + ] + }, + "Install": { + "type": "object", + "properties": { + "id": { + "type": "string", + "minLength": 1, + "maxLength": 55 + }, + "html_url": { + "type": "string", + "maxLength": 2048, + "format": "uri", + "description": "Absolute dashboard URL for this resource. OUTPUT_ONLY.", + "example": "https://akua.dev/installs/inst_j572abc123def456" + }, + "workspace_id": { + "type": "string", + "minLength": 1, + "maxLength": 53 + }, + "customer_workspace": { + "$ref": "#/components/schemas/InstallCustomerWorkspace" + }, + "cluster_id": { + "type": "string", + "minLength": 1, + "maxLength": 54, + "description": "Cluster ID. Omitted from product-owner support projections for customer-owned installs." + }, + "product_id": { + "type": "string", + "minLength": 1, + "maxLength": 55, + "description": "Product ID for product-based installations. Omitted for direct installations." + }, + "package_version_id": { + "type": "string", + "minLength": 1, + "maxLength": 55 + }, + "state": { + "type": "string", + "enum": [ + "pending", + "rendering", + "syncing", + "healthy", + "degraded", + "failed", + "deleted" + ], + "description": "Install lifecycle state from the control plane perspective." + }, + "reconciling": { + "type": "boolean" + }, + "urls": { + "type": "array", + "items": { + "$ref": "#/components/schemas/InstallUrl" + } + }, + "demo_cleanup": { + "$ref": "#/components/schemas/InstallDemoCleanup" + }, + "created_at": { + "type": "integer", + "minimum": 0, + "description": "Unix timestamp (seconds)" + }, + "updated_at": { + "type": "integer", + "minimum": 0, + "description": "Unix timestamp (seconds)" + }, + "etag": { + "type": "string" + } + }, + "required": [ + "id", + "html_url", + "workspace_id", + "customer_workspace", + "package_version_id", + "state", + "reconciling", + "urls", + "created_at", + "updated_at", + "etag" + ] + }, + "InstallList": { + "type": "object", + "properties": { + "data": { + "type": "array", + "items": { + "$ref": "#/components/schemas/Install" + } + }, + "has_more": { + "type": "boolean", + "description": "True if more items exist after this page." + }, + "next_cursor": { + "type": "string", + "nullable": true, + "description": "Opaque cursor for the next page, or null if no more pages." + } + }, + "required": [ + "data", + "has_more", + "next_cursor" + ] + }, + "InstallDomainSettings": { + "type": "object", + "properties": { + "workspace_subdomain": { + "$ref": "#/components/schemas/InstallDomainSettingsWorkspaceSubdomain" + }, + "preview_hostnames": { + "type": "array", + "items": { + "$ref": "#/components/schemas/InstallDomainSettingsPreviewHostname" + } + }, + "custom_domains": { + "type": "array", + "items": { + "$ref": "#/components/schemas/InstallDomainSettingsCustomDomain" + } + } + }, + "required": [ + "workspace_subdomain", + "preview_hostnames", + "custom_domains" + ] + }, + "InstallDomainSettingsWorkspaceSubdomain": { + "type": "object", + "nullable": true, + "properties": { + "id": { + "type": "string", + "minLength": 1, + "maxLength": 54 + }, + "workspace_id": { + "type": "string", + "minLength": 1, + "maxLength": 53 + }, + "name": { + "type": "string", + "minLength": 1, + "maxLength": 63 + }, + "fqdn": { + "type": "string", + "minLength": 1, + "maxLength": 253 + }, + "status": { + "type": "string", + "enum": [ + "active", + "propagating", + "reserved" ] }, - { - "type": "object", - "properties": { - "type": { - "type": "string", - "enum": [ - "repository_change_request.accept" - ] - }, - "repository_change_request_id": { - "type": "string", - "minLength": 1, - "maxLength": 54 - }, - "user_id": { - "type": "string" - } - }, - "required": [ - "type", - "repository_change_request_id", - "user_id" - ] + "name_changed_at": { + "type": "integer", + "nullable": true, + "minimum": 0, + "description": "Unix timestamp (seconds)" + }, + "created_at": { + "type": "integer", + "minimum": 0, + "description": "Unix timestamp (seconds)" + }, + "updated_at": { + "type": "integer", + "minimum": 0, + "description": "Unix timestamp (seconds)" + }, + "etag": { + "type": "string" + } + }, + "required": [ + "id", + "workspace_id", + "name", + "fqdn", + "status", + "name_changed_at", + "created_at", + "updated_at", + "etag" + ] + }, + "InstallDomainSettingsPreviewHostname": { + "type": "object", + "properties": { + "id": { + "type": "string", + "minLength": 1, + "maxLength": 54 + }, + "workspace_id": { + "type": "string", + "minLength": 1, + "maxLength": 53 + }, + "install_id": { + "type": "string", + "minLength": 1, + "maxLength": 55 + }, + "hostname": { + "type": "string", + "minLength": 1, + "maxLength": 253 + }, + "protocol": { + "type": "string", + "enum": [ + "http", + "websocket", + "grpc" + ], + "description": "Transport class for route forwarding." + }, + "routing_mode": { + "type": "string", + "enum": [ + "through_dispatcher", + "bypass_dispatcher" + ], + "description": "Whether traffic uses the dispatcher Worker or bypasses it." }, - { - "type": "object", - "properties": { - "type": { - "type": "string", - "enum": [ - "repository_change_request.reject" - ] - }, - "repository_change_request_id": { - "type": "string", - "minLength": 1, - "maxLength": 54 - }, - "user_id": { - "type": "string" - }, - "reason": { - "type": "string" - } - }, - "required": [ - "type", - "repository_change_request_id", - "user_id", - "reason" + "binding_kind": { + "type": "string", + "enum": [ + "pinned", + "floating" ] }, - { - "type": "object", - "properties": { - "type": { - "type": "string", - "enum": [ - "repository_change_request.withdraw" - ] - }, - "repository_change_request_id": { - "type": "string", - "minLength": 1, - "maxLength": 54 - }, - "user_id": { - "type": "string" - } - }, - "required": [ - "type", - "repository_change_request_id", - "user_id" - ] + "track": { + "type": "string", + "nullable": true, + "minLength": 1, + "maxLength": 100 }, - { - "type": "object", - "properties": { - "type": { - "type": "string", - "enum": [ - "repository_change_request.expire" - ] + "binding": { + "oneOf": [ + { + "type": "object", + "properties": { + "kind": { + "type": "string", + "enum": [ + "pinned" + ] + }, + "render_id": { + "type": "string", + "minLength": 1, + "maxLength": 54 + } + }, + "required": [ + "kind", + "render_id" + ], + "additionalProperties": false }, - "repository_change_request_id": { - "type": "string", - "minLength": 1, - "maxLength": 54 + { + "type": "object", + "properties": { + "kind": { + "type": "string", + "enum": [ + "floating" + ] + }, + "track": { + "type": "string", + "minLength": 1, + "maxLength": 100 + }, + "render_id": { + "type": "string", + "minLength": 1, + "maxLength": 54 + } + }, + "required": [ + "kind", + "track", + "render_id" + ], + "additionalProperties": false } - }, - "required": [ - "type", - "repository_change_request_id" ] }, - { - "type": "object", - "properties": { - "type": { - "type": "string", - "enum": [ - "repository.delete" - ] - }, - "repository_id": { - "type": "string", - "minLength": 1, - "maxLength": 55 - } - }, - "required": [ - "type", - "repository_id" + "status": { + "type": "string", + "enum": [ + "provisioning", + "active", + "evicted", + "releasing" ] + }, + "last_seen_at": { + "type": "integer", + "nullable": true, + "minimum": 0, + "description": "Unix timestamp (seconds)" + }, + "observed_url": { + "type": "string", + "nullable": true + }, + "error": { + "type": "string", + "nullable": true + }, + "created_at": { + "type": "integer", + "minimum": 0, + "description": "Unix timestamp (seconds)" + }, + "updated_at": { + "type": "integer", + "minimum": 0, + "description": "Unix timestamp (seconds)" + }, + "etag": { + "type": "string" } + }, + "required": [ + "id", + "workspace_id", + "install_id", + "hostname", + "protocol", + "routing_mode", + "binding_kind", + "track", + "binding", + "status", + "last_seen_at", + "observed_url", + "error", + "created_at", + "updated_at", + "etag" ] }, - "OperationResponse": { - "anyOf": [ - { - "type": "object", - "properties": { - "type": { - "type": "string", - "enum": [ - "machine.create" - ] + "InstallDomainSettingsCustomDomain": { + "type": "object", + "properties": { + "id": { + "type": "string", + "minLength": 1, + "maxLength": 54 + }, + "workspace_id": { + "type": "string", + "minLength": 1, + "maxLength": 53 + }, + "hostname": { + "type": "string", + "minLength": 1, + "maxLength": 253 + }, + "target": { + "oneOf": [ + { + "type": "object", + "properties": { + "kind": { + "type": "string", + "enum": [ + "install" + ] + }, + "install_id": { + "type": "string", + "minLength": 1, + "maxLength": 55 + } + }, + "required": [ + "kind", + "install_id" + ], + "additionalProperties": false }, - "machine_id": { - "type": "string", - "minLength": 1, - "maxLength": 54 + { + "type": "object", + "properties": { + "kind": { + "type": "string", + "enum": [ + "cluster" + ] + }, + "cluster_id": { + "type": "string", + "minLength": 1, + "maxLength": 54 + } + }, + "required": [ + "kind", + "cluster_id" + ], + "additionalProperties": false }, - "provider_id": { - "type": "string" + { + "type": "object", + "properties": { + "kind": { + "type": "string", + "enum": [ + "external" + ] + }, + "endpoint": { + "type": "string", + "format": "uri" + }, + "mtls_secret_id": { + "type": "string", + "minLength": 1, + "maxLength": 54 + } + }, + "required": [ + "kind", + "endpoint" + ], + "additionalProperties": false } - }, - "required": [ - "type", - "machine_id", - "provider_id" ] }, - { - "type": "object", - "properties": { - "type": { - "type": "string", - "enum": [ - "cluster.delete" - ] - }, - "cluster_id": { - "type": "string", - "minLength": 1, - "maxLength": 54 - } - }, - "required": [ - "type", - "cluster_id" - ] + "protocol": { + "type": "string", + "enum": [ + "http", + "websocket", + "grpc" + ], + "description": "Transport class for route forwarding." }, - { - "type": "object", - "properties": { - "type": { - "type": "string", - "enum": [ - "cluster.create" - ] - }, - "cluster_id": { - "type": "string", - "minLength": 1, - "maxLength": 54 - } - }, - "required": [ - "type", - "cluster_id" - ] + "routing_mode": { + "type": "string", + "enum": [ + "through_dispatcher", + "bypass_dispatcher" + ], + "description": "Whether traffic uses the dispatcher Worker or bypasses it." }, - { - "type": "object", - "properties": { - "type": { - "type": "string", - "enum": [ - "cluster.suspend" - ] - }, - "cluster_id": { - "type": "string", - "minLength": 1, - "maxLength": 54 - } - }, - "required": [ - "type", - "cluster_id" + "target_kind": { + "type": "string", + "enum": [ + "install", + "cluster", + "external" ] }, - { - "type": "object", - "properties": { - "type": { - "type": "string", - "enum": [ - "cluster.resume" - ] - }, - "cluster_id": { - "type": "string", - "minLength": 1, - "maxLength": 54 - } - }, - "required": [ - "type", - "cluster_id" - ] + "cloudflare_custom_hostname_id": { + "type": "string", + "nullable": true }, - { + "ssl": { "type": "object", "properties": { - "type": { + "status": { "type": "string", "enum": [ - "cluster.capabilities.refresh" + "pending_validation", + "active", + "failed" ] }, - "cluster_id": { - "type": "string", - "minLength": 1, - "maxLength": 54 + "validation_records": { + "type": "array", + "items": { + "type": "object", + "additionalProperties": { + "type": "string" + } + } } }, "required": [ - "type", - "cluster_id" + "status" ] }, - { - "type": "object", - "properties": { - "type": { - "type": "string", - "enum": [ - "cluster.capability.ensure" - ] - }, - "cluster_id": { - "type": "string", - "minLength": 1, - "maxLength": 54 - }, - "capability": { - "type": "string", - "minLength": 1 - } - }, - "required": [ - "type", - "cluster_id", - "capability" + "status": { + "type": "string", + "enum": [ + "provisioning", + "active", + "failed", + "releasing" ] }, - { - "type": "object", - "properties": { - "type": { - "type": "string", - "enum": [ - "cluster.worker_bootstrap.revoke" - ] - }, - "note": { - "type": "string" - } - }, - "required": [ - "type" - ] + "error": { + "type": "string", + "nullable": true + }, + "created_at": { + "type": "integer", + "minimum": 0, + "description": "Unix timestamp (seconds)" }, + "updated_at": { + "type": "integer", + "minimum": 0, + "description": "Unix timestamp (seconds)" + }, + "etag": { + "type": "string" + } + }, + "required": [ + "id", + "workspace_id", + "hostname", + "target", + "protocol", + "routing_mode", + "target_kind", + "cloudflare_custom_hostname_id", + "ssl", + "status", + "error", + "created_at", + "updated_at", + "etag" + ] + }, + "CreateInstallBody": { + "anyOf": [ { "type": "object", "properties": { - "type": { - "type": "string", - "enum": [ - "install.create" - ] - }, - "install_id": { + "product_id": { "type": "string", "minLength": 1, "maxLength": 55 }, - "argo_app_name": { - "type": "string" - }, - "argo_app_namespace": { - "type": "string" - } - }, - "required": [ - "type", - "install_id", - "argo_app_name", - "argo_app_namespace" - ], - "additionalProperties": false - }, - { - "type": "object", - "properties": { - "type": { + "region_id": { "type": "string", - "enum": [ - "install.create" - ] + "minLength": 1, + "maxLength": 54 }, - "install_id": { + "cluster_id": { "type": "string", "minLength": 1, - "maxLength": 55 + "maxLength": 54 }, - "sandbox_skipped": { - "type": "boolean", - "enum": [ - true - ] + "initial_values": { + "type": "object", + "additionalProperties": { + "nullable": true + } } }, "required": [ - "type", - "install_id", - "sandbox_skipped" + "product_id", + "region_id" ], "additionalProperties": false }, { "type": "object", "properties": { - "type": { + "package_id": { "type": "string", - "enum": [ - "install.render" - ] + "minLength": 1, + "maxLength": 54 }, - "install_render_id": { + "package_version_pin": { + "$ref": "#/components/schemas/InstallPackageVersionPin" + }, + "region_id": { "type": "string", "minLength": 1, "maxLength": 54 }, - "repository_id": { + "cluster_id": { "type": "string", "minLength": 1, - "maxLength": 55 - }, - "commit_sha": { - "type": "string" - }, - "render_hash": { - "type": "string" + "maxLength": 54 }, - "skipped": { - "type": "boolean" + "initial_values": { + "type": "object", + "additionalProperties": { + "nullable": true + } } }, "required": [ - "type", - "install_render_id", - "repository_id", - "render_hash", - "skipped" - ] - }, + "package_id", + "package_version_pin", + "region_id" + ], + "additionalProperties": false + } + ], + "description": "Provide either `product_id` for product-based installations or `package_id` with `package_version_pin` for direct package installations." + }, + "InstallPackageVersionPin": { + "oneOf": [ { "type": "object", "properties": { - "type": { + "kind": { "type": "string", "enum": [ - "install.delete" + "latest" ] - }, - "argo_app_deleted": { - "type": "boolean" - }, - "repo_purged": { - "type": "boolean" } }, "required": [ - "type", - "argo_app_deleted", - "repo_purged" - ] + "kind" + ], + "additionalProperties": false }, { "type": "object", "properties": { - "type": { + "kind": { "type": "string", "enum": [ - "preview_hostname.bind_pinned" + "pinned" ] }, - "install_id": { - "type": "string", - "minLength": 1, - "maxLength": 55 - }, - "preview_hostname_id": { - "type": "string", - "minLength": 1, - "maxLength": 54 - }, - "hostname": { + "version": { "type": "string", "minLength": 1, - "maxLength": 253 + "maxLength": 128, + "pattern": "^(0|[1-9]\\d*)\\.(0|[1-9]\\d*)\\.(0|[1-9]\\d*)(?:-((?:0|[1-9]\\d*|[0-9A-Za-z-]*[A-Za-z-][0-9A-Za-z-]*)(?:\\.(?:0|[1-9]\\d*|[0-9A-Za-z-]*[A-Za-z-][0-9A-Za-z-]*))*))?(?:\\+([0-9A-Za-z-]+(?:\\.[0-9A-Za-z-]+)*))?$", + "example": "1.2.3" } }, "required": [ - "type", - "install_id", - "preview_hostname_id", - "hostname" - ] + "kind", + "version" + ], + "additionalProperties": false + } + ] + }, + "InstallLifecycleMutation": { + "type": "object", + "properties": { + "install": { + "$ref": "#/components/schemas/InstallLifecycleState" }, - { - "type": "object", - "properties": { - "type": { - "type": "string", - "enum": [ - "preview_hostname.bind_floating" - ] + "render": { + "anyOf": [ + { + "$ref": "#/components/schemas/InstallRender" }, - "install_id": { - "type": "string", - "minLength": 1, - "maxLength": 55 + { + "nullable": true + } + ] + } + }, + "required": [ + "install", + "render" + ] + }, + "InstallLifecycleState": { + "type": "object", + "properties": { + "id": { + "type": "string", + "minLength": 1, + "maxLength": 55 + }, + "current_version": { + "anyOf": [ + { + "$ref": "#/components/schemas/PackageVersionSummary" }, - "preview_hostname_id": { - "type": "string", - "minLength": 1, - "maxLength": 54 + { + "nullable": true + } + ], + "description": "Last PackageVersion whose render completed successfully." + }, + "desired_version": { + "anyOf": [ + { + "$ref": "#/components/schemas/PackageVersionSummary" }, - "hostname": { - "type": "string", - "minLength": 1, - "maxLength": 253 + { + "nullable": true } - }, - "required": [ - "type", - "install_id", - "preview_hostname_id", - "hostname" + ], + "description": "Requested PackageVersion while an update or restore is pending or has failed. Null when desired and current match." + }, + "automatic_updates_enabled": { + "type": "boolean" + }, + "updated_at": { + "type": "integer", + "minimum": 0, + "description": "Unix timestamp (seconds)" + }, + "etag": { + "type": "string" + } + }, + "required": [ + "id", + "current_version", + "desired_version", + "automatic_updates_enabled", + "updated_at", + "etag" + ] + }, + "InstallRender": { + "type": "object", + "properties": { + "id": { + "type": "string", + "minLength": 1, + "maxLength": 54 + }, + "workspace_id": { + "type": "string", + "minLength": 1, + "maxLength": 53 + }, + "install_id": { + "type": "string", + "minLength": 1, + "maxLength": 55 + }, + "operation_id": { + "type": "string", + "nullable": true, + "minLength": 1, + "maxLength": 53 + }, + "repository_change_request_id": { + "type": "string", + "nullable": true, + "minLength": 1, + "maxLength": 54 + }, + "render_hash": { + "type": "string", + "nullable": true + }, + "commit_sha": { + "type": "string", + "nullable": true + }, + "package_version_id": { + "type": "string", + "nullable": true, + "minLength": 1, + "maxLength": 55 + }, + "restored_from_render_id": { + "type": "string", + "nullable": true, + "minLength": 1, + "maxLength": 54 + }, + "state": { + "type": "string", + "enum": [ + "running", + "deployed", + "skipped", + "failed" ] }, - { - "type": "object", - "properties": { - "type": { - "type": "string", - "enum": [ - "preview_hostname.delete" - ] - }, - "install_id": { - "type": "string", - "minLength": 1, - "maxLength": 55 - }, - "preview_hostname_id": { - "type": "string", - "minLength": 1, - "maxLength": 54 - }, - "hostname": { - "type": "string", - "minLength": 1, - "maxLength": 253 - } - }, - "required": [ - "type", - "install_id", - "preview_hostname_id", - "hostname" - ] + "message": { + "type": "string", + "nullable": true + }, + "created_at": { + "type": "integer", + "minimum": 0, + "description": "Unix timestamp (seconds)" + }, + "updated_at": { + "type": "integer", + "minimum": 0, + "description": "Unix timestamp (seconds)" + } + }, + "required": [ + "id", + "workspace_id", + "install_id", + "render_hash", + "state", + "created_at", + "updated_at" + ] + }, + "UpdateInstallVersionBody": { + "type": "object", + "properties": { + "package_version_id": { + "type": "string", + "minLength": 1, + "maxLength": 55 + } + }, + "required": [ + "package_version_id" + ], + "additionalProperties": false + }, + "RestoreInstallBody": { + "type": "object", + "properties": { + "render_id": { + "type": "string", + "minLength": 1, + "maxLength": 54 + } + }, + "required": [ + "render_id" + ], + "additionalProperties": false + }, + "SetInstallAutomaticUpdatesBody": { + "type": "object", + "properties": { + "automatic_updates_enabled": { + "type": "boolean" + } + }, + "required": [ + "automatic_updates_enabled" + ], + "additionalProperties": false + }, + "CreateInstallRenderBody": { + "type": "object", + "properties": { + "message": { + "type": "string", + "maxLength": 255 + }, + "skip_unchanged": { + "type": "boolean", + "nullable": true, + "default": true + }, + "extra_annotations": { + "type": "object", + "additionalProperties": { + "type": "string" + } + } + }, + "additionalProperties": false + }, + "InstallRenderList": { + "type": "object", + "properties": { + "data": { + "type": "array", + "items": { + "$ref": "#/components/schemas/InstallRender" + } + }, + "has_more": { + "type": "boolean", + "description": "True if more items exist after this page." + }, + "next_cursor": { + "type": "string", + "nullable": true, + "description": "Opaque cursor for the next page, or null if no more pages." + } + }, + "required": [ + "data", + "has_more", + "next_cursor" + ] + }, + "InstallStatus": { + "type": "object", + "properties": { + "install_id": { + "type": "string", + "minLength": 1, + "maxLength": 55 + }, + "health": { + "type": "string", + "nullable": true + }, + "sync": { + "type": "string", + "nullable": true + }, + "revision": { + "type": "string", + "nullable": true + }, + "resources": { + "type": "array", + "nullable": true, + "items": { + "$ref": "#/components/schemas/ResourceStatus" + } + }, + "operation_phase": { + "type": "string", + "nullable": true + }, + "updated_at": { + "type": "integer", + "nullable": true, + "minimum": 0, + "description": "Unix timestamp (seconds)" + }, + "state": { + "type": "string", + "enum": [ + "pending", + "rendering", + "syncing", + "healthy", + "degraded", + "failed", + "deleted" + ], + "description": "Install lifecycle state from the control plane perspective." + }, + "reconciling": { + "type": "boolean" + } + }, + "required": [ + "install_id", + "health", + "sync", + "revision", + "resources", + "operation_phase", + "updated_at", + "state", + "reconciling" + ] + }, + "PodList": { + "type": "object", + "properties": { + "data": { + "type": "array", + "items": { + "$ref": "#/components/schemas/Pod" + } + } + }, + "required": [ + "data" + ] + }, + "Pod": { + "type": "object", + "properties": { + "name": { + "type": "string" + }, + "containers": { + "type": "array", + "items": { + "type": "string" + } + } + }, + "required": [ + "name", + "containers" + ] + }, + "PackageList": { + "type": "object", + "properties": { + "data": { + "type": "array", + "items": { + "$ref": "#/components/schemas/Package" + } + }, + "has_more": { + "type": "boolean", + "description": "True if more items exist after this page." + }, + "next_cursor": { + "type": "string", + "nullable": true, + "description": "Opaque cursor for the next page, or null if no more pages." + } + }, + "required": [ + "data", + "has_more", + "next_cursor" + ] + }, + "Package": { + "type": "object", + "properties": { + "id": { + "type": "string", + "minLength": 1, + "maxLength": 54 + }, + "html_url": { + "type": "string", + "maxLength": 2048, + "format": "uri", + "description": "Absolute dashboard URL for this resource. OUTPUT_ONLY.", + "example": "https://akua.dev/packages/pkg_j572abc123def456" }, - { - "type": "object", - "properties": { - "type": { - "type": "string", - "enum": [ - "workspace.delete" - ] - }, - "workspace_id": { - "type": "string", - "minLength": 1, - "maxLength": 53 - } - }, - "required": [ - "type", - "workspace_id" - ] + "workspace_id": { + "type": "string", + "minLength": 1, + "maxLength": 53 }, - { - "type": "object", - "properties": { - "type": { - "type": "string", - "enum": [ - "workspace.subscription.cancel" - ] - }, - "subscription_id": { - "type": "string" - }, - "cancel_at": { - "type": "integer", - "minimum": 0, - "description": "Unix timestamp (seconds)" - } - }, - "required": [ - "type", - "subscription_id", - "cancel_at" - ] + "name": { + "type": "string" }, - { - "type": "object", - "properties": { - "type": { - "type": "string", - "enum": [ - "workspace.subdomain.set_name" - ] - }, - "workspace_id": { - "type": "string", - "minLength": 1, - "maxLength": 53 - }, - "workspace_subdomain_id": { - "type": "string", - "minLength": 1, - "maxLength": 54 - }, - "fqdn": { - "type": "string", - "minLength": 1, - "maxLength": 253 - } - }, - "required": [ - "type", - "workspace_id", - "workspace_subdomain_id", - "fqdn" - ] + "latest_version_id": { + "type": "string", + "minLength": 1, + "maxLength": 55 }, - { - "type": "object", - "properties": { - "type": { - "type": "string", - "enum": [ - "custom_domain.create" - ] - }, - "workspace_id": { - "type": "string", - "minLength": 1, - "maxLength": 53 - }, - "custom_domain_id": { - "type": "string", - "minLength": 1, - "maxLength": 54 - }, - "hostname": { - "type": "string", - "minLength": 1, - "maxLength": 253 - } - }, - "required": [ - "type", - "workspace_id", - "custom_domain_id", - "hostname" - ] + "description": { + "type": "string", + "nullable": true }, - { - "type": "object", - "properties": { - "type": { - "type": "string", - "enum": [ - "custom_domain.update" - ] - }, - "workspace_id": { - "type": "string", - "minLength": 1, - "maxLength": 53 - }, - "custom_domain_id": { - "type": "string", - "minLength": 1, - "maxLength": 54 - }, - "hostname": { - "type": "string", - "minLength": 1, - "maxLength": 253 - } - }, - "required": [ - "type", - "workspace_id", - "custom_domain_id", - "hostname" - ] + "display_image_url": { + "type": "string", + "nullable": true, + "maxLength": 2048, + "format": "uri" }, - { - "type": "object", - "properties": { - "type": { - "type": "string", - "enum": [ - "custom_domain.delete" - ] - }, - "workspace_id": { - "type": "string", - "minLength": 1, - "maxLength": 53 - }, - "custom_domain_id": { - "type": "string", - "minLength": 1, - "maxLength": 54 - }, - "hostname": { - "type": "string", - "minLength": 1, - "maxLength": 253 - } - }, - "required": [ - "type", - "workspace_id", - "custom_domain_id", - "hostname" - ] + "source": { + "$ref": "#/components/schemas/PackageSource" }, - { - "type": "object", - "properties": { - "type": { - "type": "string", - "enum": [ - "cloudflare.private_origin_route.prepare" - ] - }, - "origin_route_id": { - "type": "string", - "minLength": 1, - "maxLength": 54 + "composed_from_sources": { + "type": "array", + "nullable": true, + "items": { + "type": "object", + "additionalProperties": { + "nullable": true } }, - "required": [ - "type", - "origin_route_id" - ] + "description": "Source provenance used to create this Package (helm URLs, OCI refs, git source details). Only visible in `view=full`." }, - { - "type": "object", - "properties": { - "type": { - "type": "string", - "enum": [ - "cloudflare.private_origin_route.release" - ] - }, - "route_intent_id": { - "type": "string", - "minLength": 1, - "maxLength": 54 - } - }, - "required": [ - "type", - "route_intent_id" - ] + "created_at": { + "type": "integer", + "minimum": 0, + "description": "Unix timestamp (seconds)" }, + "etag": { + "type": "string" + } + }, + "required": [ + "id", + "html_url", + "workspace_id", + "name", + "latest_version_id", + "description", + "display_image_url", + "source", + "created_at" + ] + }, + "PackageSource": { + "oneOf": [ { "type": "object", "properties": { - "type": { + "kind": { "type": "string", "enum": [ - "package.create" + "hosted" ] }, - "package_id": { - "type": "string", - "minLength": 1, - "maxLength": 54 - }, - "package_version_id": { - "type": "string", - "minLength": 1, - "maxLength": 55 - }, "repository_id": { "type": "string", "minLength": 1, - "maxLength": 55 + "maxLength": 55, + "description": "platform-hosted repository that contains the package source" } }, "required": [ - "type", - "package_id", - "package_version_id", + "kind", "repository_id" ] }, { "type": "object", "properties": { - "type": { + "kind": { "type": "string", "enum": [ - "repository_change_request.create" + "oci" ] }, - "repository_change_request_id": { - "type": "string", - "minLength": 1, - "maxLength": 54 - }, - "fork_repository_id": { + "oci_ref": { "type": "string", - "minLength": 1, - "maxLength": 55 - }, - "expires_at": { - "type": "integer", - "minimum": 0, - "description": "Unix timestamp (seconds)" + "description": "OCI reference to the package source (no digest)" } }, "required": [ - "type", - "repository_change_request_id", - "fork_repository_id", - "expires_at" + "kind", + "oci_ref" ] + } + ] + }, + "PackageWithVersionsList": { + "type": "object", + "properties": { + "data": { + "type": "array", + "items": { + "$ref": "#/components/schemas/PackageWithVersions" + } }, - { - "type": "object", - "properties": { - "type": { - "type": "string", - "enum": [ - "repository_change_request.accept" - ] - }, - "merged_at": { - "type": "integer", - "minimum": 0, - "description": "Unix timestamp (seconds)" - }, - "triggered_install_render": { - "type": "boolean" + "has_more": { + "type": "boolean", + "description": "True if more items exist after this page." + }, + "next_cursor": { + "type": "string", + "nullable": true, + "description": "Opaque cursor for the next page, or null if no more pages." + } + }, + "required": [ + "data", + "has_more", + "next_cursor" + ] + }, + "PackageWithVersions": { + "type": "object", + "properties": { + "id": { + "type": "string", + "minLength": 1, + "maxLength": 54 + }, + "name": { + "type": "string" + }, + "display_image_url": { + "type": "string", + "nullable": true, + "maxLength": 2048, + "format": "uri" + }, + "versions": { + "type": "array", + "items": { + "$ref": "#/components/schemas/PackageVersionSummary" + } + } + }, + "required": [ + "id", + "name", + "display_image_url", + "versions" + ] + }, + "PackageInventoryList": { + "type": "object", + "properties": { + "data": { + "type": "array", + "items": { + "$ref": "#/components/schemas/PackageInventoryRow" + } + }, + "has_more": { + "type": "boolean", + "description": "True if more items exist after this page." + }, + "next_cursor": { + "type": "string", + "nullable": true, + "description": "Opaque cursor for the next page, or null if no more pages." + } + }, + "required": [ + "data", + "has_more", + "next_cursor" + ] + }, + "PackageInventoryRow": { + "type": "object", + "properties": { + "id": { + "type": "string", + "minLength": 1, + "maxLength": 54 + }, + "workspace_id": { + "type": "string", + "minLength": 1, + "maxLength": 53 + }, + "name": { + "type": "string" + }, + "description": { + "type": "string", + "nullable": true + }, + "display_image_url": { + "type": "string", + "nullable": true, + "maxLength": 2048, + "format": "uri" + }, + "source": { + "$ref": "#/components/schemas/PackageSource" + }, + "composed_from_sources": { + "type": "array", + "nullable": true, + "items": { + "type": "object", + "additionalProperties": { + "nullable": true } - }, - "required": [ - "type", - "merged_at", - "triggered_install_render" - ] + } }, - { + "versions": { + "type": "array", + "items": { + "$ref": "#/components/schemas/PackageVersionSummary" + } + }, + "has_more_versions": { + "type": "boolean" + }, + "created_at": { + "type": "integer", + "minimum": 0, + "description": "Unix timestamp (seconds)" + }, + "etag": { + "type": "string" + } + }, + "required": [ + "id", + "workspace_id", + "name", + "description", + "display_image_url", + "source", + "versions", + "has_more_versions", + "created_at", + "etag" + ] + }, + "PackageDetailResponse": { + "type": "object", + "nullable": true, + "properties": { + "package": { "type": "object", "properties": { - "type": { + "id": { "type": "string", - "enum": [ - "repository_change_request.reject" - ] + "minLength": 1, + "maxLength": 54 }, - "rejected_at": { - "type": "integer", - "minimum": 0, - "description": "Unix timestamp (seconds)" - } - }, - "required": [ - "type", - "rejected_at" - ] - }, - { - "type": "object", - "properties": { - "type": { + "workspace_id": { "type": "string", - "enum": [ - "repository_change_request.withdraw" - ] + "minLength": 1, + "maxLength": 53 }, - "withdrawn_at": { - "type": "integer", - "minimum": 0, - "description": "Unix timestamp (seconds)" - } - }, - "required": [ - "type", - "withdrawn_at" - ] - }, - { - "type": "object", - "properties": { - "type": { + "name": { + "type": "string" + }, + "description": { "type": "string", - "enum": [ - "repository_change_request.expire" - ] + "nullable": true }, - "expired": { - "type": "boolean" - } - }, - "required": [ - "type", - "expired" - ] - }, - { - "type": "object", - "properties": { - "type": { + "display_image_url": { "type": "string", - "enum": [ - "repository.delete" - ] + "nullable": true, + "maxLength": 2048, + "format": "uri" }, - "purged_at": { + "source": { + "$ref": "#/components/schemas/PackageSource" + }, + "composed_from_sources": { + "type": "array", + "nullable": true, + "items": { + "type": "object", + "additionalProperties": { + "nullable": true + } + } + }, + "created_at": { "type": "integer", "minimum": 0, "description": "Unix timestamp (seconds)" + }, + "etag": { + "type": "string" } }, "required": [ - "type", - "purged_at" + "id", + "workspace_id", + "name", + "description", + "display_image_url", + "source", + "created_at", + "etag" ] }, - { - "nullable": true + "versions": { + "type": "array", + "items": { + "$ref": "#/components/schemas/PackageDetailVersion" + } } - ], - "description": "Populated only when `done && state === \"SUCCEEDED\"`. Discriminated by `type`." + }, + "required": [ + "package", + "versions" + ] }, - "OperationStep": { + "PackageDetailVersion": { "type": "object", "properties": { - "name": { + "id": { "type": "string", - "description": "User-visible milestone name." + "minLength": 1, + "maxLength": 55 }, - "status": { + "package_id": { "type": "string", - "enum": [ - "pending", - "running", - "completed", - "failed", - "skipped" - ], - "description": "Step lifecycle state." + "minLength": 1, + "maxLength": 54 }, - "execution_type": { + "semver": { "type": "string", - "enum": [ - "system", - "user", - "approval", - "skipped" - ], - "description": "Step execution kind. `user`/`approval` mean the workflow is blocked on a human action. Internal bookkeeping steps are filtered from public responses." + "minLength": 1, + "maxLength": 128, + "pattern": "^(0|[1-9]\\d*)\\.(0|[1-9]\\d*)\\.(0|[1-9]\\d*)(?:-((?:0|[1-9]\\d*|[0-9A-Za-z-]*[A-Za-z-][0-9A-Za-z-]*)(?:\\.(?:0|[1-9]\\d*|[0-9A-Za-z-]*[A-Za-z-][0-9A-Za-z-]*))*))?(?:\\+([0-9A-Za-z-]+(?:\\.[0-9A-Za-z-]+)*))?$" }, - "started_at": { + "ref": { + "type": "string" + }, + "input_schema": { + "$ref": "#/components/schemas/PackageVersionInputs" + }, + "compatibility": { + "type": "object", + "properties": { + "clusterTypes": { + "type": "array", + "items": { + "type": "string" + } + }, + "kubernetes": { + "type": "object", + "properties": { + "minVersion": { + "type": "string" + }, + "maxVersion": { + "type": "string" + } + } + }, + "placement": { + "type": "object", + "properties": { + "providers": { + "anyOf": [ + { + "type": "string", + "enum": [ + "any" + ] + }, + { + "type": "array", + "items": { + "type": "string" + } + } + ] + }, + "regions": { + "anyOf": [ + { + "type": "string", + "enum": [ + "any" + ] + }, + { + "type": "array", + "items": { + "type": "string" + } + } + ] + } + }, + "required": [ + "providers", + "regions" + ] + }, + "kaas": { + "type": "object", + "properties": { + "networkProfile": { + "type": "string", + "enum": [ + "linux_cilium", + "mixed_os_calico" + ] + } + }, + "required": [ + "networkProfile" + ] + } + }, + "required": [ + "clusterTypes", + "kubernetes", + "placement" + ] + }, + "published_at": { "type": "integer", "minimum": 0, "description": "Unix timestamp (seconds)" }, - "completed_at": { + "created_at": { "type": "integer", - "nullable": true, "minimum": 0, "description": "Unix timestamp (seconds)" }, - "error_message": { - "type": "string", - "nullable": true - }, - "retryable": { - "type": "boolean" - }, - "skippable": { - "type": "boolean" + "etag": { + "type": "string" } }, "required": [ - "name", - "status", - "execution_type", - "started_at", - "completed_at", - "error_message", - "retryable", - "skippable" + "id", + "package_id", + "semver", + "ref", + "input_schema", + "published_at", + "created_at", + "etag" ] }, - "DashboardInstallList": { + "PackageVersionInputs": { + "type": "object", + "additionalProperties": { + "nullable": true + } + }, + "PackageVersionList": { "type": "object", "properties": { "data": { "type": "array", "items": { - "$ref": "#/components/schemas/DashboardInstall" + "$ref": "#/components/schemas/PackageVersion" } }, "has_more": { @@ -6354,7 +18933,7 @@ "next_cursor" ] }, - "DashboardInstall": { + "PackageVersion": { "type": "object", "properties": { "id": { @@ -6362,42 +18941,32 @@ "minLength": 1, "maxLength": 55 }, - "html_url": { - "type": "string", - "maxLength": 2048, - "format": "uri", - "description": "Absolute dashboard URL for this resource. OUTPUT_ONLY.", - "example": "https://akua.dev/installs/inst_j572abc123def456" - }, - "name": { - "type": "string" - }, - "workspace_id": { + "package_id": { "type": "string", "minLength": 1, - "maxLength": 53 + "maxLength": 54 }, - "cluster_id": { + "semver": { "type": "string", "minLength": 1, - "maxLength": 54 - }, - "cluster_name": { - "type": "string" + "maxLength": 128, + "pattern": "^(0|[1-9]\\d*)\\.(0|[1-9]\\d*)\\.(0|[1-9]\\d*)(?:-((?:0|[1-9]\\d*|[0-9A-Za-z-]*[A-Za-z-][0-9A-Za-z-]*)(?:\\.(?:0|[1-9]\\d*|[0-9A-Za-z-]*[A-Za-z-][0-9A-Za-z-]*))*))?(?:\\+([0-9A-Za-z-]+(?:\\.[0-9A-Za-z-]+)*))?$" }, - "region_name": { + "ref": { "type": "string" }, - "region_icon": { - "type": "string", - "nullable": true + "input_schema": { + "type": "object", + "additionalProperties": { + "nullable": true + } }, - "created_at": { + "published_at": { "type": "integer", "minimum": 0, "description": "Unix timestamp (seconds)" }, - "updated_at": { + "created_at": { "type": "integer", "minimum": 0, "description": "Unix timestamp (seconds)" @@ -6408,419 +18977,532 @@ }, "required": [ "id", - "html_url", - "name", - "workspace_id", - "cluster_id", - "cluster_name", - "region_name", - "region_icon", - "created_at", - "updated_at", - "etag" + "package_id", + "semver", + "ref", + "input_schema", + "published_at", + "created_at" + ] + }, + "PackageArtifacthubValuesSchema": { + "type": "object", + "properties": { + "values": { + "type": "object", + "additionalProperties": { + "nullable": true + }, + "description": "Parsed chart values object" + }, + "schema": { + "type": "object", + "nullable": true, + "additionalProperties": { + "nullable": true + }, + "description": "JSON Schema for the values (null when the values cannot be parsed)" + }, + "values_yaml": { + "type": "string", + "description": "Raw chart values YAML" + } + }, + "required": [ + "values", + "schema", + "values_yaml" ] }, - "DashboardInstallDetail": { + "ImportPackageBody": { + "type": "object", + "properties": { + "name": { + "type": "string", + "minLength": 1, + "maxLength": 120 + }, + "description": { + "type": "string", + "nullable": true, + "maxLength": 1000 + }, + "display_image_url": { + "type": "string", + "maxLength": 2048, + "format": "uri" + }, + "oci_ref": { + "type": "string", + "minLength": 1, + "maxLength": 2048, + "pattern": "^oci:\\/\\/", + "description": "OCI reference for the published Akua Package repository. If this registry matches an active workspace registry credential, Akua uses that credential to inspect the artifact." + }, + "version": { + "$ref": "#/components/schemas/CreatePackageVersionBody" + } + }, + "required": [ + "name", + "oci_ref", + "version" + ], + "additionalProperties": false + }, + "CreatePackageVersionBody": { + "type": "object", + "properties": { + "semver": { + "type": "string", + "minLength": 1, + "maxLength": 128, + "pattern": "^(0|[1-9]\\d*)\\.(0|[1-9]\\d*)\\.(0|[1-9]\\d*)(?:-((?:0|[1-9]\\d*|[0-9A-Za-z-]*[A-Za-z-][0-9A-Za-z-]*)(?:\\.(?:0|[1-9]\\d*|[0-9A-Za-z-]*[A-Za-z-][0-9A-Za-z-]*))*))?(?:\\+([0-9A-Za-z-]+(?:\\.[0-9A-Za-z-]+)*))?$", + "example": "1.2.3" + }, + "ref": { + "type": "string", + "minLength": 1, + "maxLength": 512, + "description": "Immutable package content reference. For OCI-backed packages this is normally the digest returned by `akua publish`; Akua verifies it against the published artifact before registering the version." + }, + "input_schema": { + "allOf": [ + { + "$ref": "#/components/schemas/PackageVersionInputs" + }, + { + "description": "JSON Schema exported from the Akua package version. Used to render future install forms; Akua verifies it against the published artifact before registering the version." + } + ] + }, + "compatibility": { + "type": "object", + "properties": { + "clusterTypes": { + "type": "array", + "items": { + "type": "string" + } + }, + "kubernetes": { + "type": "object", + "properties": { + "minVersion": { + "type": "string" + }, + "maxVersion": { + "type": "string" + } + } + }, + "placement": { + "type": "object", + "properties": { + "providers": { + "anyOf": [ + { + "type": "string", + "enum": [ + "any" + ] + }, + { + "type": "array", + "items": { + "type": "string" + } + } + ] + }, + "regions": { + "anyOf": [ + { + "type": "string", + "enum": [ + "any" + ] + }, + { + "type": "array", + "items": { + "type": "string" + } + } + ] + } + }, + "required": [ + "providers", + "regions" + ] + }, + "kaas": { + "type": "object", + "properties": { + "networkProfile": { + "type": "string", + "enum": [ + "linux_cilium", + "mixed_os_calico" + ] + } + }, + "required": [ + "networkProfile" + ] + } + }, + "required": [ + "clusterTypes", + "kubernetes", + "placement" + ] + } + }, + "required": [ + "semver", + "ref", + "input_schema" + ], + "additionalProperties": false + }, + "PackageOperationEnvelope": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, - "maxLength": 55 - }, - "html_url": { - "type": "string", - "maxLength": 2048, - "format": "uri", - "description": "Absolute dashboard URL for this resource. OUTPUT_ONLY.", - "example": "https://akua.dev/installs/inst_j572abc123def456" + "maxLength": 53 }, "workspace_id": { "type": "string", + "nullable": true, "minLength": 1, "maxLength": 53 }, - "cluster_id": { + "organization_id": { "type": "string", + "nullable": true, "minLength": 1, "maxLength": 54 }, - "name": { + "owner_type": { "type": "string", - "nullable": true + "enum": [ + "install", + "repository_change_request", + "repository", + "workspace", + "machine", + "cluster", + "package" + ], + "description": "Domain entity collection the operation acts on." }, - "is_standalone": { - "type": "boolean" + "owner_id": { + "type": "string", + "description": "Prefixed ID of the entity this operation acts on. Prefix matches `owner_type` (`ws_`, `mch_`, `clu_`, `pkg_`, `inst_`, `rcr_`, `repo_`)." }, - "argo_app_namespace": { - "type": "string" + "parent_operation_id": { + "type": "string", + "nullable": true, + "minLength": 1, + "maxLength": 53, + "description": "ID of the chained parent operation, when present." }, - "public_urls": { - "type": "array", - "items": { - "$ref": "#/components/schemas/InstallUrl" - } + "state": { + "type": "string", + "enum": [ + "RUNNING", + "SUCCEEDED", + "FAILED", + "CANCELLED" + ], + "description": "Lifecycle state. Past-participle terminal states per AIP-216." }, - "argo_status": { - "$ref": "#/components/schemas/DashboardInstallArgoStatus" + "done": { + "type": "boolean", + "description": "True iff state is a terminal value." }, - "cluster": { + "html_url": { + "type": "string", + "maxLength": 2048, + "format": "uri", + "description": "Deep link to the dashboard view of this operation.", + "example": "https://akua.dev/packages/pkg_j572abc123def456?tab=operations" + }, + "metadata": { + "$ref": "#/components/schemas/PackageOperationMetadata" + }, + "response": { + "$ref": "#/components/schemas/PackageOperationResponse" + }, + "error": { "type": "object", + "nullable": true, "properties": { - "id": { - "type": "string", - "minLength": 1, - "maxLength": 54 - }, - "name": { + "message": { "type": "string" - }, - "region": { - "type": "object", - "properties": { - "name": { - "type": "string" - }, - "icon": { - "type": "string", - "nullable": true - } - }, - "required": [ - "name", - "icon" - ] } }, "required": [ - "id", - "name", - "region" - ] + "message" + ], + "description": "Populated when `state` is `FAILED` or `CANCELLED`." }, - "product": { + "last_error": { "type": "object", "nullable": true, "properties": { - "name": { + "message": { "type": "string" }, - "is_owner": { - "type": "boolean" + "step_name": { + "type": "string" } }, "required": [ - "name", - "is_owner" - ] - }, - "demo_cleanup": { - "$ref": "#/components/schemas/InstallDemoCleanup" + "message" + ], + "description": "Latest error from any failed step. Populated even mid-flight; cleared when the step succeeds on retry." }, - "created_at": { + "started_at": { "type": "integer", "minimum": 0, "description": "Unix timestamp (seconds)" }, - "updated_at": { + "completed_at": { "type": "integer", + "nullable": true, "minimum": 0, "description": "Unix timestamp (seconds)" }, - "etag": { - "type": "string" + "steps": { + "type": "array", + "items": { + "$ref": "#/components/schemas/PackageOperationStep" + } } }, "required": [ "id", - "html_url", "workspace_id", - "cluster_id", - "name", - "is_standalone", - "argo_app_namespace", - "public_urls", - "argo_status", - "cluster", - "product", - "created_at", - "updated_at", - "etag" + "organization_id", + "owner_type", + "owner_id", + "parent_operation_id", + "state", + "done", + "html_url", + "metadata", + "response", + "error", + "last_error", + "started_at", + "completed_at" ] }, - "InstallUrl": { + "PackageOperationMetadata": { "type": "object", "properties": { - "route_key": { - "type": "string" + "type": { + "type": "string", + "enum": [ + "package.create" + ] }, - "hostname": { + "idempotency_key": { "type": "string" }, - "url": { + "workspace_id": { "type": "string", - "format": "uri" + "minLength": 1, + "maxLength": 53 }, - "protocol": { + "name": { + "type": "string" + } + }, + "required": [ + "type", + "idempotency_key", + "workspace_id", + "name" + ] + }, + "PackageOperationResponse": { + "type": "object", + "nullable": true, + "properties": { + "type": { "type": "string", "enum": [ - "http", - "websocket", - "grpc" - ], - "description": "Transport class for route forwarding." + "package.create" + ] }, - "routing_mode": { + "package_id": { "type": "string", - "enum": [ - "through_dispatcher", - "bypass_dispatcher" - ], - "description": "Whether traffic uses the dispatcher Worker or bypasses it." + "minLength": 1, + "maxLength": 54 + }, + "package_version_id": { + "type": "string", + "minLength": 1, + "maxLength": 55 + }, + "repository_id": { + "type": "string", + "minLength": 1, + "maxLength": 55 + } + }, + "required": [ + "type", + "package_id", + "package_version_id", + "repository_id" + ], + "description": "Populated only when `done && state === \"SUCCEEDED\"`." + }, + "PackageOperationStep": { + "type": "object", + "properties": { + "name": { + "type": "string", + "description": "User-visible milestone name." }, "status": { "type": "string", "enum": [ "pending", - "provisioning", - "active", - "not_ready", - "failed" + "running", + "completed", + "failed", + "skipped" ], - "description": "Customer-facing install URL routing state." + "description": "Step lifecycle state." }, - "error": { - "type": "string" + "execution_type": { + "type": "string", + "enum": [ + "system", + "user", + "approval", + "skipped" + ], + "description": "Step execution kind. `user`/`approval` mean the workflow is blocked on a human action. Internal bookkeeping steps are filtered from public responses." }, - "last_observed_at": { + "started_at": { "type": "integer", "minimum": 0, "description": "Unix timestamp (seconds)" }, - "updated_at": { + "completed_at": { "type": "integer", + "nullable": true, "minimum": 0, "description": "Unix timestamp (seconds)" + }, + "error_message": { + "type": "string", + "nullable": true + }, + "retryable": { + "type": "boolean" + }, + "skippable": { + "type": "boolean" } }, "required": [ - "route_key", - "hostname", - "url", - "protocol", - "routing_mode", + "name", "status", - "updated_at" + "execution_type", + "started_at", + "completed_at", + "error_message", + "retryable", + "skippable" ] }, - "DashboardInstallArgoStatus": { + "CreatePackageBody": { "type": "object", - "nullable": true, "properties": { - "status": { - "type": "object", - "properties": { - "health": { - "type": "object", - "properties": { - "status": { - "type": "string" - } - }, - "required": [ - "status" - ], - "additionalProperties": { - "nullable": true - } - }, - "sync": { - "type": "object", - "properties": { - "status": { - "type": "string" - }, - "revision": { - "type": "string" - } - }, - "required": [ - "status" - ], - "additionalProperties": { - "nullable": true - } - }, - "operation_state": { - "type": "object", - "properties": { - "phase": { - "type": "string" - } - }, - "required": [ - "phase" - ], - "additionalProperties": { - "nullable": true - } - }, - "resources": { - "type": "array", - "items": { - "$ref": "#/components/schemas/ResourceStatus" - } - } - }, - "required": [ - "health", - "sync", - "resources" - ], - "additionalProperties": { - "nullable": true - } + "name": { + "type": "string", + "minLength": 1, + "maxLength": 120 }, - "updated_at": { - "type": "integer", - "minimum": 0, - "description": "Unix timestamp (seconds)" + "display_image_url": { + "type": "string", + "maxLength": 2048, + "format": "uri" + }, + "sources": { + "type": "array", + "items": { + "$ref": "#/components/schemas/CreatePackageHelmSource" + }, + "minItems": 1, + "maxItems": 1 } }, "required": [ - "status", - "updated_at" - ] + "name", + "sources" + ], + "additionalProperties": false }, - "ResourceStatus": { + "CreatePackageHelmSource": { "type": "object", "properties": { - "group": { - "type": "string" - }, "kind": { - "type": "string" - }, - "name": { - "type": "string" + "type": "string", + "enum": [ + "helm" + ] }, - "namespace": { - "type": "string" + "repo_url": { + "type": "string", + "minLength": 1, + "maxLength": 2048, + "pattern": "^oci:\\/\\/" }, - "version": { - "type": "string" + "chart": { + "type": "string", + "maxLength": 255 }, - "status": { - "type": "string" + "target_revision": { + "type": "string", + "minLength": 1, + "maxLength": 256 }, - "health": { - "type": "object", - "properties": { - "status": { - "type": "string" - } - }, - "required": [ - "status" - ] - } - }, - "required": [ - "kind", - "name" - ], - "additionalProperties": { - "nullable": true - } - }, - "InstallDemoCleanup": { - "oneOf": [ - { - "type": "object", - "properties": { - "kind": { - "type": "string", - "enum": [ - "scheduled" - ] - }, - "cleanup_at": { - "type": "integer", - "minimum": 0, - "description": "Unix timestamp when the non-billable demo install is scheduled for cleanup." - }, - "removable_by": { - "type": "string", - "enum": [ - "platform_policy", - "platform_admin" - ], - "description": "Authority that may remove the scheduled cleanup policy." - }, - "conversion_required": { - "type": "string", - "enum": [ - "paid_order", - "platform_approval" - ], - "description": "Required approval path before the demo install can continue without cleanup." - }, - "delivery_status": { - "type": "string", - "enum": [ - "pending", - "running", - "succeeded", - "failed" - ], - "description": "Order delivery status for the install that owns this cleanup policy." - } - }, - "required": [ - "kind", - "cleanup_at", - "removable_by", - "conversion_required", - "delivery_status" - ], - "additionalProperties": false + "path": { + "type": "string", + "maxLength": 2048 }, - { - "type": "object", - "properties": { - "kind": { - "type": "string", - "enum": [ - "removed" - ] - }, - "delivery_status": { - "type": "string", - "enum": [ - "pending", - "running", - "succeeded", - "failed" - ], - "description": "Order delivery status for the demo install whose cleanup was removed." - } - }, - "required": [ - "kind", - "delivery_status" - ], - "additionalProperties": false + "values": { + "type": "object", + "additionalProperties": { + "nullable": true + } } + }, + "required": [ + "kind", + "repo_url", + "target_revision" ], - "description": "Visible cleanup state for non-billable demo installs. Temporal workflow IDs and internal cleanup evidence are intentionally omitted." + "additionalProperties": false }, - "InstallList": { + "WorkspaceList": { "type": "object", "properties": { "data": { "type": "array", "items": { - "$ref": "#/components/schemas/Install" + "$ref": "#/components/schemas/Workspace" } }, "has_more": { @@ -6839,68 +19521,57 @@ "next_cursor" ] }, - "Install": { + "Workspace": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, - "maxLength": 55 - }, - "html_url": { - "type": "string", - "maxLength": 2048, - "format": "uri", - "description": "Absolute dashboard URL for this resource. OUTPUT_ONLY.", - "example": "https://akua.dev/installs/inst_j572abc123def456" + "maxLength": 53, + "description": "Workspace ID", + "example": "ws_j572abc123def456" }, - "workspace_id": { + "name": { "type": "string", - "minLength": 1, - "maxLength": 53 - }, - "customer_workspace": { - "$ref": "#/components/schemas/InstallCustomerWorkspace" + "description": "Display name", + "example": "Acme Research" }, - "cluster_id": { + "slug": { "type": "string", - "minLength": 1, - "maxLength": 54 + "description": "URL-safe workspace slug" }, - "product_id": { + "icon": { "type": "string", - "minLength": 1, - "maxLength": 55 + "maxLength": 256, + "format": "uri", + "x-platform-visibility": "INTERNAL" }, - "package_version_id": { - "type": "string", - "minLength": 1, - "maxLength": 55 + "plan": { + "type": "object", + "properties": { + "tier": { + "type": "string" + }, + "billed_by": { + "type": "string", + "enum": [ + "platform", + "seller" + ] + } + }, + "required": [ + "tier", + "billed_by" + ] }, - "state": { + "workspace_class": { "type": "string", "enum": [ - "pending", - "rendering", - "syncing", - "healthy", - "degraded", - "failed", - "deleted" - ], - "description": "Install lifecycle state from the control plane perspective." - }, - "reconciling": { - "type": "boolean" - }, - "urls": { - "type": "array", - "items": { - "$ref": "#/components/schemas/InstallUrl" - } - }, - "demo_cleanup": { - "$ref": "#/components/schemas/InstallDemoCleanup" + "standard", + "platform", + "sandbox" + ] }, "created_at": { "type": "integer", @@ -6918,503 +19589,335 @@ }, "required": [ "id", - "html_url", - "workspace_id", - "customer_workspace", - "cluster_id", - "product_id", - "package_version_id", - "state", - "reconciling", - "urls", + "name", + "slug", + "plan", + "workspace_class", "created_at", "updated_at", "etag" ] }, - "InstallCustomerWorkspace": { - "type": "object", - "properties": { - "id": { - "type": "string", - "minLength": 1, - "maxLength": 53 - }, - "name": { - "type": "string", - "minLength": 1, - "maxLength": 100 - } - }, - "required": [ - "id", - "name" - ] - }, - "InstallDomainSettings": { + "WorkspaceMemberList": { "type": "object", "properties": { - "workspace_subdomain": { - "$ref": "#/components/schemas/InstallDomainSettingsWorkspaceSubdomain" - }, - "preview_hostnames": { + "data": { "type": "array", "items": { - "$ref": "#/components/schemas/InstallDomainSettingsPreviewHostname" + "$ref": "#/components/schemas/WorkspaceMember" } }, - "custom_domains": { - "type": "array", - "items": { - "$ref": "#/components/schemas/InstallDomainSettingsCustomDomain" - } + "has_more": { + "type": "boolean", + "description": "True if more items exist after this page." + }, + "next_cursor": { + "type": "string", + "nullable": true, + "description": "Opaque cursor for the next page, or null if no more pages." } }, "required": [ - "workspace_subdomain", - "preview_hostnames", - "custom_domains" + "data", + "has_more", + "next_cursor" ] }, - "InstallDomainSettingsWorkspaceSubdomain": { + "WorkspaceMember": { "type": "object", - "nullable": true, "properties": { "id": { "type": "string", "minLength": 1, - "maxLength": 54 - }, - "workspace_id": { - "type": "string", - "minLength": 1, - "maxLength": 53 - }, - "name": { - "type": "string", - "minLength": 1, - "maxLength": 63 + "maxLength": 54, + "description": "Workspace member ID", + "example": "wsm_j572abc123def456" }, - "fqdn": { + "user_id": { "type": "string", - "minLength": 1, - "maxLength": 253 + "description": "Member user ID", + "example": "usr_j572abc123def456" }, - "status": { + "role": { "type": "string", "enum": [ - "active", - "propagating", - "reserved" + "owner", + "admin", + "member" ] }, - "name_changed_at": { - "type": "integer", - "nullable": true, - "minimum": 0, - "description": "Unix timestamp (seconds)" - }, - "created_at": { - "type": "integer", - "minimum": 0, - "description": "Unix timestamp (seconds)" - }, - "updated_at": { - "type": "integer", - "minimum": 0, - "description": "Unix timestamp (seconds)" - }, - "etag": { - "type": "string" + "joined_at": { + "type": "string", + "format": "date-time", + "description": "ISO 8601 join timestamp" } }, "required": [ "id", - "workspace_id", - "name", - "fqdn", - "status", - "name_changed_at", - "created_at", - "updated_at", - "etag" + "user_id", + "role", + "joined_at" ] }, - "InstallDomainSettingsPreviewHostname": { + "WorkspaceSubscription": { "type": "object", "properties": { "id": { - "type": "string", - "minLength": 1, - "maxLength": 54 + "type": "string" }, "workspace_id": { "type": "string", "minLength": 1, "maxLength": 53 }, - "install_id": { - "type": "string", - "minLength": 1, - "maxLength": 55 - }, - "hostname": { - "type": "string", - "minLength": 1, - "maxLength": 253 - }, - "protocol": { - "type": "string", - "enum": [ - "http", - "websocket", - "grpc" - ], - "description": "Transport class for route forwarding." - }, - "routing_mode": { - "type": "string", - "enum": [ - "through_dispatcher", - "bypass_dispatcher" - ], - "description": "Whether traffic uses the dispatcher Worker or bypasses it." - }, - "binding_kind": { - "type": "string", - "enum": [ - "pinned", - "floating" - ] - }, - "track": { - "type": "string", - "nullable": true, - "minLength": 1, - "maxLength": 100 - }, - "binding": { - "oneOf": [ - { - "type": "object", - "properties": { - "kind": { - "type": "string", - "enum": [ - "pinned" - ] - }, - "render_id": { - "type": "string", - "minLength": 1, - "maxLength": 54 - } - }, - "required": [ - "kind", - "render_id" - ], - "additionalProperties": false - }, - { - "type": "object", - "properties": { - "kind": { - "type": "string", - "enum": [ - "floating" - ] - }, - "track": { - "type": "string", - "minLength": 1, - "maxLength": 100 - }, - "render_id": { - "type": "string", - "minLength": 1, - "maxLength": 54 - } - }, - "required": [ - "kind", - "track", - "render_id" - ], - "additionalProperties": false - } - ] + "tier": { + "type": "string" }, "status": { - "type": "string", - "enum": [ - "provisioning", - "active", - "evicted", - "releasing" - ] + "type": "string" }, - "last_seen_at": { - "type": "integer", - "nullable": true, - "minimum": 0, - "description": "Unix timestamp (seconds)" + "cancellation_scheduled": { + "type": "boolean" }, - "observed_url": { + "current_period_end": { "type": "string", "nullable": true }, - "error": { + "billed_by": { "type": "string", - "nullable": true + "enum": [ + "platform", + "seller" + ] }, "created_at": { "type": "integer", "minimum": 0, "description": "Unix timestamp (seconds)" - }, - "updated_at": { - "type": "integer", - "minimum": 0, - "description": "Unix timestamp (seconds)" - }, - "etag": { - "type": "string" } }, "required": [ "id", "workspace_id", - "install_id", - "hostname", - "protocol", - "routing_mode", - "binding_kind", - "track", - "binding", + "tier", "status", - "last_seen_at", - "observed_url", - "error", - "created_at", - "updated_at", - "etag" + "cancellation_scheduled", + "current_period_end", + "billed_by", + "created_at" ] }, - "InstallDomainSettingsCustomDomain": { + "WorkspaceAccessState": { "type": "object", "properties": { - "id": { - "type": "string", - "minLength": 1, - "maxLength": 54 - }, "workspace_id": { "type": "string", "minLength": 1, "maxLength": 53 }, - "hostname": { - "type": "string", - "minLength": 1, - "maxLength": 253 - }, - "target": { - "oneOf": [ - { - "type": "object", - "properties": { - "kind": { - "type": "string", - "enum": [ - "install" - ] - }, - "install_id": { - "type": "string", - "minLength": 1, - "maxLength": 55 - } - }, - "required": [ - "kind", - "install_id" - ], - "additionalProperties": false - }, - { - "type": "object", - "properties": { - "kind": { - "type": "string", - "enum": [ - "cluster" - ] - }, - "cluster_id": { - "type": "string", - "minLength": 1, - "maxLength": 54 - } - }, - "required": [ - "kind", - "cluster_id" - ], - "additionalProperties": false - }, - { - "type": "object", - "properties": { - "kind": { - "type": "string", - "enum": [ - "external" - ] - }, - "endpoint": { - "type": "string", - "format": "uri" - }, - "mtls_secret_id": { - "type": "string", - "minLength": 1, - "maxLength": 54 - } - }, - "required": [ - "kind", - "endpoint" - ], - "additionalProperties": false - } - ] - }, - "protocol": { - "type": "string", - "enum": [ - "http", - "websocket", - "grpc" - ], - "description": "Transport class for route forwarding." - }, - "routing_mode": { - "type": "string", - "enum": [ - "through_dispatcher", - "bypass_dispatcher" - ], - "description": "Whether traffic uses the dispatcher Worker or bypasses it." - }, - "target_kind": { + "status": { "type": "string", "enum": [ - "install", - "cluster", - "external" + "active", + "payment_grace", + "restricted", + "suspended", + "ended", + "reactivating" ] }, - "cloudflare_custom_hostname_id": { - "type": "string", - "nullable": true - }, - "ssl": { - "type": "object", - "properties": { - "status": { - "type": "string", - "enum": [ - "pending_validation", - "active", - "failed" - ] - }, - "validation_records": { - "type": "array", - "items": { - "type": "object", - "additionalProperties": { - "type": "string" - } - } - } - }, - "required": [ - "status" - ] + "access_version": { + "type": "integer", + "minimum": 0 }, - "status": { + "accessible": { + "type": "boolean" + }, + "reason": { "type": "string", + "nullable": true, "enum": [ - "provisioning", - "active", - "failed", - "releasing" + "payment_grace", + "restricted", + "suspended", + "ended", + "reactivating", + null ] }, - "error": { + "reconciliation_status": { "type": "string", - "nullable": true + "enum": [ + "pending", + "reconciled", + "failed" + ] }, - "created_at": { + "payment_grace_ends_at": { "type": "integer", + "nullable": true, "minimum": 0, "description": "Unix timestamp (seconds)" }, - "updated_at": { + "restricted_at": { + "type": "integer", + "nullable": true, + "minimum": 0, + "description": "Unix timestamp (seconds)" + }, + "suspend_at": { + "type": "integer", + "nullable": true, + "minimum": 0, + "description": "Unix timestamp (seconds)" + }, + "ended_at": { "type": "integer", + "nullable": true, "minimum": 0, "description": "Unix timestamp (seconds)" + } + }, + "required": [ + "workspace_id", + "status", + "access_version", + "accessible", + "reason", + "reconciliation_status", + "payment_grace_ends_at", + "restricted_at", + "suspend_at", + "ended_at" + ] + }, + "WorkspaceManagement": { + "type": "object", + "properties": { + "workspace_id": { + "type": "string", + "minLength": 1, + "maxLength": 53 + }, + "management": { + "type": "object", + "nullable": true, + "properties": { + "organization": { + "type": "object", + "properties": { + "id": { + "type": "string", + "minLength": 1, + "maxLength": 54 + }, + "name": { + "type": "string" + } + }, + "required": [ + "id", + "name" + ] + }, + "granted_at": { + "type": "integer", + "minimum": 0, + "description": "Unix timestamp (seconds)" + } + }, + "required": [ + "organization", + "granted_at" + ] }, "etag": { "type": "string" } }, "required": [ - "id", "workspace_id", - "hostname", - "target", - "protocol", - "routing_mode", - "target_kind", - "cloudflare_custom_hostname_id", - "ssl", - "status", - "error", - "created_at", - "updated_at", + "management", "etag" ] }, - "CreateInstallBody": { + "OperationEnvelope": { "type": "object", "properties": { - "product_id": { + "operation_id": { + "type": "string", + "minLength": 1, + "maxLength": 53 + } + }, + "required": [ + "operation_id" + ] + }, + "SubscriptionChangeRequestList": { + "type": "object", + "properties": { + "data": { + "type": "array", + "items": { + "$ref": "#/components/schemas/SubscriptionChangeRequest" + } + }, + "has_more": { + "type": "boolean", + "description": "True if more items exist after this page." + }, + "next_cursor": { + "type": "string", + "nullable": true, + "description": "Opaque cursor for the next page, or null if no more pages." + } + }, + "required": [ + "data", + "has_more", + "next_cursor" + ] + }, + "SubscriptionChangeRequest": { + "type": "object", + "properties": { + "id": { "type": "string", "minLength": 1, "maxLength": 55 }, - "region_id": { + "workspace_id": { "type": "string", "minLength": 1, - "maxLength": 54 + "maxLength": 53 }, - "initial_values": { - "type": "object", - "additionalProperties": { - "nullable": true - } + "requested_tier": { + "type": "string" + }, + "status": { + "type": "string" + }, + "effective_at": { + "type": "string", + "nullable": true + }, + "created_at": { + "type": "integer", + "minimum": 0, + "description": "Unix timestamp (seconds)" } }, "required": [ - "product_id", - "region_id" - ], - "additionalProperties": false + "id", + "workspace_id", + "requested_tier", + "status", + "effective_at", + "created_at" + ] }, - "InstallRender": { + "CreatedApiToken": { "type": "object", "properties": { "id": { @@ -7427,216 +19930,528 @@ "minLength": 1, "maxLength": 53 }, - "install_id": { + "name": { + "type": "string" + }, + "token": { + "type": "string", + "description": "The full token. This is shown only once - store it securely.", + "example": "sk_akua_a3b2c4d5e6f7g8h9i0j1k2l3m4n5o6p7" + } + }, + "required": [ + "id", + "workspace_id", + "name", + "token" + ] + }, + "CreateApiTokenRequest": { + "type": "object", + "properties": { + "name": { "type": "string", "minLength": 1, - "maxLength": 55 + "maxLength": 100, + "description": "Human-readable name for the token", + "example": "My CLI token" }, - "operation_id": { - "type": "string", + "expires_at": { + "type": "integer", "nullable": true, - "minLength": 1, - "maxLength": 53 + "minimum": 0, + "description": "Unix timestamp (seconds) when the token expires. Omit or pass null for no expiry.", + "example": 1742169600 + } + }, + "required": [ + "name" + ], + "additionalProperties": false + }, + "ApiTokenList": { + "type": "object", + "properties": { + "data": { + "type": "array", + "items": { + "$ref": "#/components/schemas/ApiToken" + } }, - "repository_change_request_id": { + "has_more": { + "type": "boolean", + "description": "True if more items exist after this page." + }, + "next_cursor": { "type": "string", "nullable": true, + "description": "Opaque cursor for the next page, or null if no more pages." + } + }, + "required": [ + "data", + "has_more", + "next_cursor" + ] + }, + "ApiToken": { + "type": "object", + "properties": { + "id": { + "type": "string", "minLength": 1, "maxLength": 54 }, - "render_hash": { - "type": "string", - "nullable": true - }, - "commit_sha": { + "workspace_id": { "type": "string", - "nullable": true + "minLength": 1, + "maxLength": 53 }, - "state": { + "name": { "type": "string", - "enum": [ - "running", - "deployed", - "skipped", - "failed" - ] + "example": "My CLI token" }, - "message": { + "prefix": { "type": "string", - "nullable": true + "example": "sk_akua_a3b2", + "description": "Short identifier prefix of the full token, for display only." }, "created_at": { "type": "integer", "minimum": 0, "description": "Unix timestamp (seconds)" }, - "updated_at": { + "last_used_at": { "type": "integer", + "nullable": true, "minimum": 0, - "description": "Unix timestamp (seconds)" + "description": "Unix timestamp (seconds) of last use, or null if never used" + }, + "expires_at": { + "type": "integer", + "nullable": true, + "minimum": 0, + "description": "Unix timestamp (seconds) when the token expires, or null if never" } }, "required": [ "id", "workspace_id", - "install_id", - "render_hash", - "state", + "name", + "prefix", "created_at", - "updated_at" + "last_used_at", + "expires_at" ] }, - "CreateInstallRenderBody": { + "RepositoryList": { "type": "object", "properties": { - "message": { - "type": "string", - "maxLength": 255 + "data": { + "type": "array", + "items": { + "$ref": "#/components/schemas/Repository" + } }, - "skip_unchanged": { + "has_more": { "type": "boolean", + "description": "True if more items exist after this page." + }, + "next_cursor": { + "type": "string", "nullable": true, - "default": true + "description": "Opaque cursor for the next page, or null if no more pages." + } + }, + "required": [ + "data", + "has_more", + "next_cursor" + ] + }, + "Repository": { + "oneOf": [ + { + "type": "object", + "properties": { + "id": { + "type": "string", + "minLength": 1, + "maxLength": 55 + }, + "name": { + "type": "string" + }, + "workspace_id": { + "type": "string", + "minLength": 1, + "maxLength": 53 + }, + "created_at": { + "type": "integer", + "minimum": 0, + "description": "Unix timestamp (seconds)" + }, + "updated_at": { + "type": "integer", + "minimum": 0, + "description": "Unix timestamp (seconds)" + }, + "etag": { + "type": "string" + }, + "reconciling": { + "type": "boolean" + }, + "purpose": { + "type": "string", + "enum": [ + "deploy" + ] + }, + "cluster_id": { + "type": "string", + "minLength": 1, + "maxLength": 54 + }, + "last_deploy_sha": { + "type": "string", + "nullable": true + }, + "last_render_hash": { + "type": "string", + "nullable": true + } + }, + "required": [ + "id", + "name", + "workspace_id", + "created_at", + "updated_at", + "etag", + "reconciling", + "purpose", + "cluster_id" + ] }, - "extra_annotations": { + { "type": "object", - "additionalProperties": { - "type": "string" - } + "properties": { + "id": { + "type": "string", + "minLength": 1, + "maxLength": 55 + }, + "name": { + "type": "string" + }, + "workspace_id": { + "type": "string", + "minLength": 1, + "maxLength": 53 + }, + "created_at": { + "type": "integer", + "minimum": 0, + "description": "Unix timestamp (seconds)" + }, + "updated_at": { + "type": "integer", + "minimum": 0, + "description": "Unix timestamp (seconds)" + }, + "etag": { + "type": "string" + }, + "reconciling": { + "type": "boolean" + }, + "purpose": { + "type": "string", + "enum": [ + "package" + ] + }, + "package_id": { + "type": "string", + "minLength": 1, + "maxLength": 54 + } + }, + "required": [ + "id", + "name", + "workspace_id", + "created_at", + "updated_at", + "etag", + "reconciling", + "purpose", + "package_id" + ] + }, + { + "type": "object", + "properties": { + "id": { + "type": "string", + "minLength": 1, + "maxLength": 55 + }, + "name": { + "type": "string" + }, + "workspace_id": { + "type": "string", + "minLength": 1, + "maxLength": 53 + }, + "created_at": { + "type": "integer", + "minimum": 0, + "description": "Unix timestamp (seconds)" + }, + "updated_at": { + "type": "integer", + "minimum": 0, + "description": "Unix timestamp (seconds)" + }, + "etag": { + "type": "string" + }, + "reconciling": { + "type": "boolean" + }, + "purpose": { + "type": "string", + "enum": [ + "repository_change_request" + ] + }, + "repository_change_request_id": { + "type": "string", + "minLength": 1, + "maxLength": 54 + } + }, + "required": [ + "id", + "name", + "workspace_id", + "created_at", + "updated_at", + "etag", + "reconciling", + "purpose", + "repository_change_request_id" + ] + } + ] + }, + "GithubInstallationUrl": { + "type": "object", + "properties": { + "url": { + "type": "string", + "format": "uri" + } + }, + "required": [ + "url" + ] + }, + "GithubCreateInstallationUrlBody": { + "type": "object", + "properties": { + "redirect_url": { + "type": "string", + "format": "uri" } }, "additionalProperties": false }, - "InstallRenderList": { + "GithubRepoList": { "type": "object", "properties": { "data": { "type": "array", "items": { - "$ref": "#/components/schemas/InstallRender" + "$ref": "#/components/schemas/GithubRepo" } - }, - "has_more": { - "type": "boolean", - "description": "True if more items exist after this page." - }, - "next_cursor": { - "type": "string", - "nullable": true, - "description": "Opaque cursor for the next page, or null if no more pages." } }, "required": [ - "data", - "has_more", - "next_cursor" + "data" ] }, - "InstallStatus": { + "GithubRepo": { "type": "object", "properties": { - "install_id": { - "type": "string", - "minLength": 1, - "maxLength": 55 + "id": { + "type": "number" }, - "health": { - "type": "string", - "nullable": true + "name": { + "type": "string" }, - "sync": { - "type": "string", - "nullable": true + "full_name": { + "type": "string" }, - "revision": { - "type": "string", - "nullable": true + "archived": { + "type": "boolean" }, - "resources": { + "disabled": { + "type": "boolean" + }, + "default_branch": { + "type": "string" + }, + "html_url": { + "type": "string" + }, + "owner": { + "type": "object", + "properties": { + "id": { + "type": "number" + }, + "login": { + "type": "string" + }, + "type": { + "type": "string" + }, + "avatar_url": { + "type": "string" + }, + "html_url": { + "type": "string" + } + }, + "required": [ + "id", + "login", + "type", + "avatar_url", + "html_url" + ] + } + }, + "required": [ + "id", + "name", + "full_name", + "archived", + "disabled", + "default_branch", + "html_url", + "owner" + ] + }, + "GithubAppInstallationList": { + "type": "object", + "properties": { + "data": { "type": "array", - "nullable": true, "items": { - "$ref": "#/components/schemas/ResourceStatus" + "$ref": "#/components/schemas/GithubAppInstallation" } - }, - "operation_phase": { - "type": "string", - "nullable": true - }, - "updated_at": { + } + }, + "required": [ + "data" + ] + }, + "GithubAppInstallation": { + "type": "object", + "properties": { + "installation_id": { "type": "integer", - "nullable": true, "minimum": 0, - "description": "Unix timestamp (seconds)" + "exclusiveMinimum": true }, - "state": { + "workspace_id": { "type": "string", - "enum": [ - "pending", - "rendering", - "syncing", - "healthy", - "degraded", - "failed", - "deleted" - ], - "description": "Install lifecycle state from the control plane perspective." + "minLength": 1, + "maxLength": 53 }, - "reconciling": { - "type": "boolean" + "account": { + "type": "object", + "properties": { + "type": { + "type": "string", + "enum": [ + "User", + "Organization" + ] + }, + "login": { + "type": "string" + }, + "id": { + "type": "number" + } + }, + "required": [ + "type", + "login", + "id" + ] } }, "required": [ - "install_id", - "health", - "sync", - "revision", - "resources", - "operation_phase", - "updated_at", - "state", - "reconciling" + "installation_id", + "workspace_id", + "account" ] }, - "PodList": { + "GithubWorkflowPrGet": { "type": "object", "properties": { "data": { - "type": "array", - "items": { - "$ref": "#/components/schemas/Pod" - } + "$ref": "#/components/schemas/GithubWorkflowPr" } }, "required": [ "data" ] }, - "Pod": { + "GithubWorkflowPr": { "type": "object", + "nullable": true, "properties": { - "name": { - "type": "string" + "pr_id": { + "type": "integer", + "minimum": 0, + "exclusiveMinimum": true }, - "containers": { - "type": "array", - "items": { - "type": "string" - } + "pr_url": { + "type": "string", + "format": "uri" + }, + "status": { + "type": "string", + "enum": [ + "open", + "merged", + "closed", + "draft" + ] } }, "required": [ - "name", - "containers" + "pr_id", + "pr_url", + "status" ] }, - "PackageList": { + "GithubWorkflowRunList": { "type": "object", "properties": { "data": { "type": "array", "items": { - "$ref": "#/components/schemas/Package" + "$ref": "#/components/schemas/GithubWorkflowRun" } }, "has_more": { @@ -7655,7 +20470,7 @@ "next_cursor" ] }, - "Package": { + "GithubWorkflowRun": { "type": "object", "properties": { "id": { @@ -7663,531 +20478,546 @@ "minLength": 1, "maxLength": 54 }, - "html_url": { - "type": "string", - "maxLength": 2048, - "format": "uri", - "description": "Absolute dashboard URL for this resource. OUTPUT_ONLY.", - "example": "https://akua.dev/packages/pkg_j572abc123def456" - }, - "workspace_id": { - "type": "string", - "minLength": 1, - "maxLength": 53 - }, - "name": { - "type": "string" - }, - "latest_version_id": { - "type": "string", - "minLength": 1, - "maxLength": 55 - }, - "description": { - "type": "string", - "nullable": true - }, - "source": { - "$ref": "#/components/schemas/PackageSource" - }, - "composed_from_sources": { - "type": "array", - "nullable": true, - "items": { - "type": "object", - "additionalProperties": { - "nullable": true + "custom": { + "type": "object", + "properties": { + "image": { + "type": "string" + }, + "sent_at": { + "type": "number" } }, - "description": "Source provenance used to create this Package (helm URLs, OCI refs, git source details). Only visible in `view=full`." + "required": [ + "image", + "sent_at" + ] }, - "created_at": { - "type": "integer", - "minimum": 0, - "description": "Unix timestamp (seconds)" + "installation": { + "type": "object", + "properties": { + "id": { + "type": "number" + } + }, + "required": [ + "id" + ] }, - "etag": { - "type": "string" - } - }, - "required": [ - "id", - "html_url", - "workspace_id", - "name", - "latest_version_id", - "description", - "source", - "created_at" - ] - }, - "PackageSource": { - "oneOf": [ - { + "workflow_run": { "type": "object", "properties": { - "kind": { + "id": { + "type": "number" + }, + "name": { + "type": "string" + }, + "path": { + "type": "string" + }, + "workflow_id": { + "type": "number" + }, + "run_number": { + "type": "number" + }, + "html_url": { + "type": "string", + "format": "uri" + }, + "created_at": { + "type": "string" + }, + "updated_at": { + "type": "string" + }, + "run_started_at": { + "type": "string" + }, + "event": { + "type": "string" + }, + "head_branch": { + "type": "string" + }, + "head_sha": { + "type": "string" + }, + "status": { "type": "string", "enum": [ - "hosted" + "queued", + "in_progress", + "completed", + "action_required", + "cancelled", + "failure", + "neutral", + "skipped", + "stale", + "success", + "timed_out", + "requested", + "waiting", + "pending" ] }, - "repository_id": { + "conclusion": { "type": "string", - "minLength": 1, - "maxLength": 55, - "description": "platform-hosted repository that contains the package source" + "nullable": true, + "enum": [ + "success", + "failure", + "cancelled", + "timed_out", + "action_required", + "neutral", + "skipped", + "stale", + "startup_failure", + null + ] + }, + "actor": { + "type": "object", + "properties": { + "login": { + "type": "string" + }, + "id": { + "type": "number" + }, + "avatar_url": { + "type": "string" + }, + "html_url": { + "type": "string", + "format": "uri" + } + }, + "required": [ + "login", + "id" + ] + }, + "referenced_workflows": { + "type": "array", + "items": { + "type": "object", + "properties": { + "path": { + "type": "string" + }, + "sha": { + "type": "string" + }, + "ref": { + "type": "string" + } + }, + "required": [ + "path", + "sha" + ] + } + }, + "head_commit": { + "type": "object", + "properties": { + "id": { + "type": "string" + }, + "tree_id": { + "type": "string" + }, + "timestamp": { + "type": "string" + }, + "message": { + "type": "string" + }, + "author": { + "type": "object", + "properties": { + "name": { + "type": "string" + }, + "email": { + "type": "string" + } + }, + "required": [ + "name" + ] + }, + "committer": { + "type": "object", + "properties": { + "name": { + "type": "string" + }, + "email": { + "type": "string" + } + }, + "required": [ + "name" + ] + } + }, + "required": [ + "id", + "tree_id", + "timestamp", + "message", + "author", + "committer" + ] } }, "required": [ - "kind", - "repository_id" + "id", + "name", + "path", + "workflow_id", + "run_number", + "html_url", + "created_at", + "updated_at", + "run_started_at", + "event", + "head_branch", + "head_sha", + "status", + "conclusion", + "head_commit" ] }, - { + "repository": { "type": "object", "properties": { - "kind": { - "type": "string", - "enum": [ - "oci" + "id": { + "type": "number" + }, + "owner": { + "type": "object", + "properties": { + "login": { + "type": "string" + }, + "id": { + "type": "number" + }, + "avatar_url": { + "type": "string", + "format": "uri" + }, + "html_url": { + "type": "string", + "format": "uri" + } + }, + "required": [ + "login", + "id", + "avatar_url", + "html_url" ] }, - "oci_ref": { + "name": { + "type": "string" + }, + "full_name": { + "type": "string" + }, + "html_url": { "type": "string", - "description": "OCI reference to the package source (no digest)" + "format": "uri" } }, "required": [ - "kind", - "oci_ref" + "id", + "owner", + "name", + "full_name", + "html_url" ] } - ] - }, - "PackageWithVersionsList": { - "type": "object", - "properties": { - "data": { - "type": "array", - "items": { - "$ref": "#/components/schemas/PackageWithVersions" - } - }, - "has_more": { - "type": "boolean", - "description": "True if more items exist after this page." - }, - "next_cursor": { - "type": "string", - "nullable": true, - "description": "Opaque cursor for the next page, or null if no more pages." - } }, "required": [ - "data", - "has_more", - "next_cursor" + "id", + "installation", + "workflow_run", + "repository" ] }, - "PackageWithVersions": { + "GithubPackagePermissions": { "type": "object", "properties": { - "id": { - "type": "string", - "minLength": 1, - "maxLength": 54 + "has_warning": { + "type": "boolean" }, - "name": { + "warning": { "type": "string" }, - "versions": { - "type": "array", - "items": { - "$ref": "#/components/schemas/PackageVersionSummary" - } - } - }, - "required": [ - "id", - "name", - "versions" - ] - }, - "PackageVersionSummary": { - "type": "object", - "properties": { - "id": { - "type": "string", - "minLength": 1, - "maxLength": 55 - }, - "semver": { - "type": "string", - "minLength": 1, - "maxLength": 128, - "pattern": "^(0|[1-9]\\d*)\\.(0|[1-9]\\d*)\\.(0|[1-9]\\d*)(?:-((?:0|[1-9]\\d*|[0-9A-Za-z-]*[A-Za-z-][0-9A-Za-z-]*)(?:\\.(?:0|[1-9]\\d*|[0-9A-Za-z-]*[A-Za-z-][0-9A-Za-z-]*))*))?(?:\\+([0-9A-Za-z-]+(?:\\.[0-9A-Za-z-]+)*))?$" + "fix_url": { + "type": "string" } }, "required": [ - "id", - "semver" + "has_warning" ] }, - "PackageInventoryList": { + "GithubCheckPackagePermissionsBody": { "type": "object", "properties": { - "data": { - "type": "array", - "items": { - "$ref": "#/components/schemas/PackageInventoryRow" - } - }, - "has_more": { - "type": "boolean", - "description": "True if more items exist after this page." + "repository": { + "type": "object", + "properties": { + "id": { + "type": "number" + }, + "owner": { + "type": "string" + }, + "name": { + "type": "string" + } + }, + "required": [ + "id", + "owner", + "name" + ] }, - "next_cursor": { - "type": "string", - "nullable": true, - "description": "Opaque cursor for the next page, or null if no more pages." + "installation_id": { + "type": "integer", + "minimum": 0, + "exclusiveMinimum": true } }, "required": [ - "data", - "has_more", - "next_cursor" - ] + "repository", + "installation_id" + ], + "additionalProperties": false }, - "PackageInventoryRow": { + "GithubWorkflowPrCreated": { "type": "object", "properties": { - "id": { - "type": "string", - "minLength": 1, - "maxLength": 54 + "pr_id": { + "type": "integer", + "minimum": 0, + "exclusiveMinimum": true }, - "workspace_id": { + "pr_url": { "type": "string", - "minLength": 1, - "maxLength": 53 - }, - "name": { - "type": "string" + "format": "uri" }, - "description": { + "status": { "type": "string", - "nullable": true - }, - "source": { - "$ref": "#/components/schemas/PackageSource" - }, - "composed_from_sources": { - "type": "array", - "nullable": true, - "items": { - "type": "object", - "additionalProperties": { - "nullable": true - } - } - }, - "versions": { - "type": "array", - "items": { - "$ref": "#/components/schemas/PackageVersionSummary" - } - }, - "has_more_versions": { - "type": "boolean" - }, - "created_at": { - "type": "integer", - "minimum": 0, - "description": "Unix timestamp (seconds)" - }, - "etag": { - "type": "string" + "enum": [ + "open" + ] } }, "required": [ - "id", - "workspace_id", - "name", - "description", - "source", - "versions", - "has_more_versions", - "created_at", - "etag" + "pr_id", + "pr_url", + "status" ] }, - "PackageDetailResponse": { + "GithubCreateWorkflowPrBody": { "type": "object", - "nullable": true, "properties": { - "package": { + "repository": { "type": "object", "properties": { "id": { - "type": "string", - "minLength": 1, - "maxLength": 54 + "type": "number" }, - "workspace_id": { - "type": "string", - "minLength": 1, - "maxLength": 53 + "owner": { + "type": "string" }, "name": { "type": "string" }, - "description": { - "type": "string", - "nullable": true - }, - "source": { - "$ref": "#/components/schemas/PackageSource" - }, - "composed_from_sources": { - "type": "array", - "nullable": true, - "items": { - "type": "object", - "additionalProperties": { - "nullable": true - } - } - }, - "created_at": { - "type": "integer", - "minimum": 0, - "description": "Unix timestamp (seconds)" - }, - "etag": { + "default_branch": { "type": "string" } }, "required": [ "id", - "workspace_id", + "owner", "name", - "description", - "source", - "created_at", - "etag" + "default_branch" ] }, - "versions": { - "type": "array", - "items": { - "$ref": "#/components/schemas/PackageDetailVersion" - } - } - }, - "required": [ - "package", - "versions" - ] - }, - "PackageDetailVersion": { - "type": "object", - "properties": { - "id": { - "type": "string", - "minLength": 1, - "maxLength": 55 - }, - "package_id": { - "type": "string", - "minLength": 1, - "maxLength": 54 - }, - "semver": { - "type": "string", - "minLength": 1, - "maxLength": 128, - "pattern": "^(0|[1-9]\\d*)\\.(0|[1-9]\\d*)\\.(0|[1-9]\\d*)(?:-((?:0|[1-9]\\d*|[0-9A-Za-z-]*[A-Za-z-][0-9A-Za-z-]*)(?:\\.(?:0|[1-9]\\d*|[0-9A-Za-z-]*[A-Za-z-][0-9A-Za-z-]*))*))?(?:\\+([0-9A-Za-z-]+(?:\\.[0-9A-Za-z-]+)*))?$" - }, - "ref": { - "type": "string" - }, - "input_schema": { - "$ref": "#/components/schemas/PackageVersionInputs" - }, - "compatibility": { + "build_settings": { "type": "object", "properties": { - "clusterTypes": { - "type": "array", - "items": { - "type": "string" - } + "buildContext": { + "type": "string", + "default": "./" }, - "kubernetes": { - "type": "object", - "properties": { - "minVersion": { - "type": "string" - }, - "maxVersion": { - "type": "string" - } - } + "buildCommand": { + "type": "string" }, - "placement": { - "type": "object", - "properties": { - "providers": { - "anyOf": [ - { - "type": "string", - "enum": [ - "any" - ] - }, - { - "type": "array", - "items": { - "type": "string" - } - } - ] - }, - "regions": { - "anyOf": [ - { - "type": "string", - "enum": [ - "any" - ] - }, - { - "type": "array", - "items": { - "type": "string" - } - } - ] - } - }, - "required": [ - "providers", - "regions" - ] + "startCommand": { + "type": "string" }, - "kaas": { - "type": "object", - "properties": { - "networkProfile": { - "type": "string", - "enum": [ - "linux_cilium", - "mixed_os_calico" - ] - } - }, - "required": [ - "networkProfile" - ] + "installCommand": { + "type": "string" + }, + "buildAptPackages": { + "type": "string" + }, + "runtimeAptPackages": { + "type": "string" } - }, - "required": [ - "clusterTypes", - "kubernetes", - "placement" - ] - }, - "published_at": { - "type": "integer", - "minimum": 0, - "description": "Unix timestamp (seconds)" + } }, - "created_at": { + "installation_id": { "type": "integer", "minimum": 0, - "description": "Unix timestamp (seconds)" - }, - "etag": { - "type": "string" + "exclusiveMinimum": true } }, "required": [ - "id", - "package_id", - "semver", - "ref", - "input_schema", - "published_at", - "created_at", - "etag" - ] + "repository", + "build_settings", + "installation_id" + ], + "additionalProperties": false }, - "PackageVersionInputs": { + "GithubVerifyInstallationResponse": { "type": "object", - "additionalProperties": { - "nullable": true - } + "properties": { + "redirect_url": { + "type": "string" + } + }, + "required": [ + "redirect_url" + ] }, - "PackageVersionList": { + "GithubVerifyInstallationBody": { "type": "object", "properties": { - "data": { - "type": "array", - "items": { - "$ref": "#/components/schemas/PackageVersion" - } + "installation_id": { + "type": "integer", + "minimum": 0, + "exclusiveMinimum": true }, - "has_more": { - "type": "boolean", - "description": "True if more items exist after this page." + "code": { + "type": "string", + "minLength": 1 }, - "next_cursor": { + "state": { "type": "string", - "nullable": true, - "description": "Opaque cursor for the next page, or null if no more pages." + "minLength": 1 } }, "required": [ - "data", - "has_more", - "next_cursor" - ] + "installation_id", + "code", + "state" + ], + "additionalProperties": false }, - "PackageVersion": { + "Secret": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, - "maxLength": 55 + "maxLength": 54 }, - "package_id": { + "html_url": { + "type": "string", + "maxLength": 2048, + "format": "uri", + "description": "Absolute dashboard URL for this resource. OUTPUT_ONLY.", + "example": "https://akua.dev/secrets/sec_j572abc123def456" + }, + "workspace_id": { "type": "string", "minLength": 1, - "maxLength": 54 + "maxLength": 53 }, - "semver": { + "name": { "type": "string", "minLength": 1, - "maxLength": 128, - "pattern": "^(0|[1-9]\\d*)\\.(0|[1-9]\\d*)\\.(0|[1-9]\\d*)(?:-((?:0|[1-9]\\d*|[0-9A-Za-z-]*[A-Za-z-][0-9A-Za-z-]*)(?:\\.(?:0|[1-9]\\d*|[0-9A-Za-z-]*[A-Za-z-][0-9A-Za-z-]*))*))?(?:\\+([0-9A-Za-z-]+(?:\\.[0-9A-Za-z-]+)*))?$" + "maxLength": 200 }, - "ref": { - "type": "string" + "kind": { + "type": "string", + "description": "Secret kind. Current public create values: cloud_provider/hcloud, cloud_provider/aws, cloud_provider/gcp, cloud_provider/azure, oci_registry, cloudflare_api, webhook_signing, generic. cloud_credential is migration-only metadata and cannot be used for new public creates.", + "example": "generic" + }, + "description": { + "type": "string", + "maxLength": 500 + }, + "labels": { + "type": "object", + "additionalProperties": { + "type": "string", + "maxLength": 200 + } + }, + "state": { + "type": "string", + "enum": [ + "active", + "soft_deleted" + ] + }, + "validation": { + "$ref": "#/components/schemas/SecretValidation" + }, + "mime_type": { + "type": "string", + "maxLength": 100 + }, + "version_aliases": { + "type": "object", + "additionalProperties": { + "type": "integer", + "minimum": 0, + "exclusiveMinimum": true + } + }, + "version_count": { + "type": "integer", + "minimum": 0 + }, + "enabled_version_count": { + "type": "integer", + "minimum": 0 + }, + "created_at": { + "type": "integer", + "minimum": 0, + "description": "Unix timestamp (seconds)" }, - "input_schema": { - "type": "object", - "additionalProperties": { - "nullable": true - } + "updated_at": { + "type": "integer", + "minimum": 0, + "description": "Unix timestamp (seconds)" }, - "published_at": { + "deleted_at": { "type": "integer", "minimum": 0, "description": "Unix timestamp (seconds)" }, - "created_at": { + "purge_at": { + "type": "integer", + "minimum": 0, + "description": "Unix timestamp (seconds)" + }, + "expire_time": { "type": "integer", "minimum": 0, "description": "Unix timestamp (seconds)" @@ -8198,592 +21028,484 @@ }, "required": [ "id", - "package_id", - "semver", - "ref", - "input_schema", - "published_at", - "created_at" - ] - }, - "PackageArtifacthubValuesSchema": { - "type": "object", - "properties": { - "values": { - "type": "object", - "additionalProperties": { - "nullable": true - }, - "description": "Parsed chart values object" - }, - "schema": { - "type": "object", - "nullable": true, - "additionalProperties": { - "nullable": true - }, - "description": "JSON Schema for the values (null when the values cannot be parsed)" - }, - "values_yaml": { - "type": "string", - "description": "Raw chart values YAML" - } - }, - "required": [ - "values", - "schema", - "values_yaml" + "html_url", + "workspace_id", + "name", + "kind", + "state", + "validation", + "version_count", + "enabled_version_count", + "created_at", + "updated_at", + "etag" ] }, - "ImportPackageBody": { + "SecretValidation": { "type": "object", + "nullable": true, "properties": { - "name": { - "type": "string", - "minLength": 1, - "maxLength": 120 - }, - "description": { + "state": { "type": "string", - "nullable": true, - "maxLength": 1000 + "enum": [ + "unspecified", + "valid", + "invalid" + ] }, - "oci_ref": { - "type": "string", - "minLength": 1, - "maxLength": 2048, - "pattern": "^oci:\\/\\/", - "description": "OCI reference for the published Akua Package repository. If this registry matches an active workspace registry credential, Akua uses that credential to inspect the artifact." + "validated_at": { + "type": "integer", + "minimum": 0, + "description": "Unix timestamp (seconds)" }, - "version": { - "$ref": "#/components/schemas/CreatePackageVersionBody" + "error": { + "type": "string" } }, "required": [ - "name", - "oci_ref", - "version" + "state", + "validated_at" ], - "additionalProperties": false + "description": "Server-managed validation telemetry. Populated for credential-typed secrets; null otherwise. OUTPUT_ONLY — clients cannot set this on create/update." }, - "CreatePackageVersionBody": { - "type": "object", - "properties": { - "semver": { - "type": "string", - "minLength": 1, - "maxLength": 128, - "pattern": "^(0|[1-9]\\d*)\\.(0|[1-9]\\d*)\\.(0|[1-9]\\d*)(?:-((?:0|[1-9]\\d*|[0-9A-Za-z-]*[A-Za-z-][0-9A-Za-z-]*)(?:\\.(?:0|[1-9]\\d*|[0-9A-Za-z-]*[A-Za-z-][0-9A-Za-z-]*))*))?(?:\\+([0-9A-Za-z-]+(?:\\.[0-9A-Za-z-]+)*))?$", - "example": "1.2.3" - }, - "ref": { - "type": "string", - "minLength": 1, - "maxLength": 512, - "description": "Immutable package content reference. For OCI-backed packages this is normally the digest returned by `akua publish`; Akua verifies it against the published artifact before registering the version." - }, - "input_schema": { - "allOf": [ - { - "$ref": "#/components/schemas/PackageVersionInputs" + "CreateSecretBody": { + "oneOf": [ + { + "type": "object", + "properties": { + "name": { + "type": "string", + "minLength": 1, + "maxLength": 200 }, - { - "description": "JSON Schema exported from the Akua package version. Used to render future install forms; Akua verifies it against the published artifact before registering the version." + "description": { + "type": "string", + "maxLength": 500 + }, + "labels": { + "type": "object", + "additionalProperties": { + "type": "string", + "maxLength": 200 + } + }, + "kind": { + "type": "string", + "enum": [ + "cloud_provider/hcloud" + ] + }, + "value": { + "type": "string", + "minLength": 1 } - ] + }, + "required": [ + "name", + "kind", + "value" + ], + "additionalProperties": false }, - "compatibility": { + { "type": "object", "properties": { - "clusterTypes": { - "type": "array", - "items": { - "type": "string" - } + "name": { + "type": "string", + "minLength": 1, + "maxLength": 200 }, - "kubernetes": { + "description": { + "type": "string", + "maxLength": 500 + }, + "labels": { "type": "object", - "properties": { - "minVersion": { - "type": "string" - }, - "maxVersion": { - "type": "string" - } + "additionalProperties": { + "type": "string", + "maxLength": 200 } }, - "placement": { - "type": "object", - "properties": { - "providers": { - "anyOf": [ - { - "type": "string", - "enum": [ - "any" - ] - }, - { - "type": "array", - "items": { - "type": "string" - } - } - ] - }, - "regions": { - "anyOf": [ - { - "type": "string", - "enum": [ - "any" - ] - }, - { - "type": "array", - "items": { - "type": "string" - } - } - ] - } - }, - "required": [ - "providers", - "regions" + "kind": { + "type": "string", + "enum": [ + "cloud_provider/aws" ] }, - "kaas": { + "value": { + "type": "string", + "minLength": 1 + }, + "aws_access_key_id": { + "type": "string" + } + }, + "required": [ + "name", + "kind", + "value" + ], + "additionalProperties": false + }, + { + "type": "object", + "properties": { + "name": { + "type": "string", + "minLength": 1, + "maxLength": 200 + }, + "description": { + "type": "string", + "maxLength": 500 + }, + "labels": { "type": "object", - "properties": { - "networkProfile": { - "type": "string", - "enum": [ - "linux_cilium", - "mixed_os_calico" - ] - } - }, - "required": [ - "networkProfile" + "additionalProperties": { + "type": "string", + "maxLength": 200 + } + }, + "kind": { + "type": "string", + "enum": [ + "cloud_provider/gcp" ] + }, + "value": { + "type": "string", + "minLength": 1 } }, "required": [ - "clusterTypes", - "kubernetes", - "placement" - ] - } - }, - "required": [ - "semver", - "ref", - "input_schema" - ], - "additionalProperties": false - }, - "PackageOperationEnvelope": { - "type": "object", - "properties": { - "id": { - "type": "string", - "minLength": 1, - "maxLength": 53 - }, - "workspace_id": { - "type": "string", - "nullable": true, - "minLength": 1, - "maxLength": 53 - }, - "organization_id": { - "type": "string", - "nullable": true, - "minLength": 1, - "maxLength": 54 - }, - "owner_type": { - "type": "string", - "enum": [ - "install", - "repository_change_request", - "repository", - "workspace", - "machine", - "cluster", - "package" + "name", + "kind", + "value" ], - "description": "Domain entity collection the operation acts on." - }, - "owner_id": { - "type": "string", - "description": "Prefixed ID of the entity this operation acts on. Prefix matches `owner_type` (`ws_`, `mch_`, `clu_`, `pkg_`, `inst_`, `rcr_`, `repo_`)." - }, - "parent_operation_id": { - "type": "string", - "nullable": true, - "minLength": 1, - "maxLength": 53, - "description": "ID of the chained parent operation, when present." + "additionalProperties": false }, - "state": { - "type": "string", - "enum": [ - "RUNNING", - "SUCCEEDED", - "FAILED", - "CANCELLED" + { + "type": "object", + "properties": { + "name": { + "type": "string", + "minLength": 1, + "maxLength": 200 + }, + "description": { + "type": "string", + "maxLength": 500 + }, + "labels": { + "type": "object", + "additionalProperties": { + "type": "string", + "maxLength": 200 + } + }, + "kind": { + "type": "string", + "enum": [ + "cloud_provider/azure" + ] + }, + "value": { + "type": "string", + "minLength": 1 + } + }, + "required": [ + "name", + "kind", + "value" ], - "description": "Lifecycle state. Past-participle terminal states per AIP-216." - }, - "done": { - "type": "boolean", - "description": "True iff state is a terminal value." - }, - "html_url": { - "type": "string", - "maxLength": 2048, - "format": "uri", - "description": "Deep link to the dashboard view of this operation.", - "example": "https://akua.dev/packages/pkg_j572abc123def456?tab=operations" + "additionalProperties": false }, - "metadata": { - "$ref": "#/components/schemas/PackageOperationMetadata" + { + "type": "object", + "properties": { + "name": { + "type": "string", + "minLength": 1, + "maxLength": 200 + }, + "description": { + "type": "string", + "maxLength": 500 + }, + "labels": { + "type": "object", + "additionalProperties": { + "type": "string", + "maxLength": 200 + } + }, + "kind": { + "type": "string", + "enum": [ + "oci_registry" + ] + }, + "value": { + "type": "string", + "minLength": 1 + }, + "username": { + "type": "string" + } + }, + "required": [ + "name", + "kind", + "value" + ], + "additionalProperties": false }, - "response": { - "$ref": "#/components/schemas/PackageOperationResponse" + { + "type": "object", + "properties": { + "name": { + "type": "string", + "minLength": 1, + "maxLength": 200 + }, + "description": { + "type": "string", + "maxLength": 500 + }, + "labels": { + "type": "object", + "additionalProperties": { + "type": "string", + "maxLength": 200 + } + }, + "kind": { + "type": "string", + "enum": [ + "cloudflare_api" + ] + }, + "value": { + "type": "string", + "minLength": 1 + } + }, + "required": [ + "name", + "kind", + "value" + ], + "additionalProperties": false }, - "error": { + { "type": "object", - "nullable": true, "properties": { - "message": { - "type": "string" + "name": { + "type": "string", + "minLength": 1, + "maxLength": 200 + }, + "description": { + "type": "string", + "maxLength": 500 + }, + "labels": { + "type": "object", + "additionalProperties": { + "type": "string", + "maxLength": 200 + } + }, + "kind": { + "type": "string", + "enum": [ + "webhook_signing" + ] + }, + "value": { + "type": "string", + "minLength": 16 } }, "required": [ - "message" + "name", + "kind", + "value" ], - "description": "Populated when `state` is `FAILED` or `CANCELLED`." + "additionalProperties": false }, - "last_error": { + { "type": "object", - "nullable": true, "properties": { - "message": { - "type": "string" + "name": { + "type": "string", + "minLength": 1, + "maxLength": 200 }, - "step_name": { - "type": "string" + "description": { + "type": "string", + "maxLength": 500 + }, + "labels": { + "type": "object", + "additionalProperties": { + "type": "string", + "maxLength": 200 + } + }, + "kind": { + "type": "string", + "enum": [ + "generic" + ] + }, + "value": { + "type": "string", + "minLength": 1 } }, "required": [ - "message" + "name", + "kind", + "value" ], - "description": "Latest error from any failed step. Populated even mid-flight; cleared when the step succeeds on retry." - }, - "started_at": { - "type": "integer", - "minimum": 0, - "description": "Unix timestamp (seconds)" - }, - "completed_at": { - "type": "integer", - "nullable": true, - "minimum": 0, - "description": "Unix timestamp (seconds)" - }, - "steps": { - "type": "array", - "items": { - "$ref": "#/components/schemas/PackageOperationStep" - } + "additionalProperties": false } - }, - "required": [ - "id", - "workspace_id", - "organization_id", - "owner_type", - "owner_id", - "parent_operation_id", - "state", - "done", - "html_url", - "metadata", - "response", - "error", - "last_error", - "started_at", - "completed_at" ] }, - "PackageOperationMetadata": { + "SecretList": { "type": "object", "properties": { - "type": { - "type": "string", - "enum": [ - "package.create" - ] + "data": { + "type": "array", + "items": { + "$ref": "#/components/schemas/Secret" + } }, - "idempotency_key": { - "type": "string" + "has_more": { + "type": "boolean", + "description": "True if more items exist after this page." }, - "workspace_id": { + "next_cursor": { "type": "string", - "minLength": 1, - "maxLength": 53 - }, - "name": { - "type": "string" + "nullable": true, + "description": "Opaque cursor for the next page, or null if no more pages." } }, "required": [ - "type", - "idempotency_key", - "workspace_id", - "name" + "data", + "has_more", + "next_cursor" ] }, - "PackageOperationResponse": { - "type": "object", - "nullable": true, - "properties": { - "type": { - "type": "string", - "enum": [ - "package.create" - ] - }, - "package_id": { - "type": "string", - "minLength": 1, - "maxLength": 54 - }, - "package_version_id": { - "type": "string", - "minLength": 1, - "maxLength": 55 - }, - "repository_id": { - "type": "string", - "minLength": 1, - "maxLength": 55 - } - }, - "required": [ - "type", - "package_id", - "package_version_id", - "repository_id" - ], - "description": "Populated only when `done && state === \"SUCCEEDED\"`." - }, - "PackageOperationStep": { + "UpdateSecretBody": { "type": "object", "properties": { "name": { "type": "string", - "description": "User-visible milestone name." - }, - "status": { - "type": "string", - "enum": [ - "pending", - "running", - "completed", - "failed", - "skipped" - ], - "description": "Step lifecycle state." + "minLength": 1, + "maxLength": 200 }, - "execution_type": { + "description": { "type": "string", - "enum": [ - "system", - "user", - "approval", - "skipped" - ], - "description": "Step execution kind. `user`/`approval` mean the workflow is blocked on a human action. Internal bookkeeping steps are filtered from public responses." - }, - "started_at": { - "type": "integer", - "minimum": 0, - "description": "Unix timestamp (seconds)" + "maxLength": 500 }, - "completed_at": { - "type": "integer", - "nullable": true, - "minimum": 0, - "description": "Unix timestamp (seconds)" + "labels": { + "type": "object", + "additionalProperties": { + "type": "string", + "maxLength": 200 + } }, - "error_message": { + "mime_type": { "type": "string", - "nullable": true - }, - "retryable": { - "type": "boolean" + "maxLength": 100 }, - "skippable": { - "type": "boolean" + "version_aliases": { + "type": "object", + "additionalProperties": { + "type": "integer", + "minimum": 0, + "exclusiveMinimum": true + } } }, - "required": [ - "name", - "status", - "execution_type", - "started_at", - "completed_at", - "error_message", - "retryable", - "skippable" - ] + "additionalProperties": false }, - "CreatePackageBody": { + "ValidateProviderTokenResult": { "type": "object", "properties": { - "name": { - "type": "string", - "minLength": 1, - "maxLength": 120 + "valid": { + "type": "boolean", + "description": "Whether the token authenticated successfully." }, - "sources": { - "type": "array", - "items": { - "$ref": "#/components/schemas/CreatePackageHelmSource" - }, - "minItems": 1, - "maxItems": 1 + "error": { + "type": "string", + "description": "Human-readable reason when `valid` is false." } }, "required": [ - "name", - "sources" - ], - "additionalProperties": false + "valid" + ] }, - "CreatePackageHelmSource": { + "ValidateProviderTokenBody": { "type": "object", "properties": { - "kind": { + "provider": { "type": "string", "enum": [ - "helm" - ] - }, - "repo_url": { - "type": "string", - "minLength": 1, - "maxLength": 2048, - "pattern": "^oci:\\/\\/" - }, - "chart": { - "type": "string", - "maxLength": 255 + "hcloud" + ], + "description": "Cloud provider to validate the token against." }, - "target_revision": { + "value": { "type": "string", "minLength": 1, - "maxLength": 256 - }, - "path": { - "type": "string", - "maxLength": 2048 - }, - "values": { - "type": "object", - "additionalProperties": { - "nullable": true - } - } - }, - "required": [ - "kind", - "repo_url", - "target_revision" - ], - "additionalProperties": false - }, - "WorkspaceList": { - "type": "object", - "properties": { - "data": { - "type": "array", - "items": { - "$ref": "#/components/schemas/Workspace" - } - }, - "has_more": { - "type": "boolean", - "description": "True if more items exist after this page." - }, - "next_cursor": { - "type": "string", - "nullable": true, - "description": "Opaque cursor for the next page, or null if no more pages." + "description": "The provider API token to probe. Consumed, never stored." } }, "required": [ - "data", - "has_more", - "next_cursor" + "provider", + "value" ] }, - "Workspace": { + "SecretVersion": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, - "maxLength": 53, - "description": "Workspace ID", - "example": "ws_j572abc123def456" - }, - "name": { - "type": "string", - "description": "Display name", - "example": "Acme Research" + "maxLength": 55 }, - "slug": { + "secret_id": { "type": "string", - "description": "URL-safe workspace slug" + "minLength": 1, + "maxLength": 54 }, - "plan": { - "type": "object", - "properties": { - "tier": { - "type": "string" - }, - "billed_by": { - "type": "string", - "enum": [ - "platform", - "seller" - ] - } - }, - "required": [ - "tier", - "billed_by" - ] + "version_number": { + "type": "integer", + "minimum": 0, + "exclusiveMinimum": true }, - "workspace_class": { + "state": { "type": "string", "enum": [ - "standard", - "platform", - "sandbox" + "enabled", + "disabled", + "destroyed" ] }, + "comment": { + "type": "string", + "maxLength": 200 + }, "created_at": { "type": "integer", "minimum": 0, "description": "Unix timestamp (seconds)" }, - "updated_at": { + "destroyed_at": { "type": "integer", "minimum": 0, "description": "Unix timestamp (seconds)" @@ -8794,22 +21516,37 @@ }, "required": [ "id", - "name", - "slug", - "plan", - "workspace_class", + "secret_id", + "version_number", + "state", "created_at", - "updated_at", "etag" ] }, - "WorkspaceMemberList": { + "CreateSecretVersionBody": { + "type": "object", + "properties": { + "value": { + "type": "string", + "minLength": 1 + }, + "comment": { + "type": "string", + "maxLength": 200 + } + }, + "required": [ + "value" + ], + "additionalProperties": false + }, + "SecretVersionList": { "type": "object", "properties": { "data": { "type": "array", "items": { - "$ref": "#/components/schemas/WorkspaceMember" + "$ref": "#/components/schemas/SecretVersion" } }, "has_more": { @@ -8828,181 +21565,100 @@ "next_cursor" ] }, - "WorkspaceMember": { + "SecretPlaintext": { "type": "object", "properties": { - "id": { - "type": "string", - "minLength": 1, - "maxLength": 54, - "description": "Workspace member ID", - "example": "wsm_j572abc123def456" - }, - "user_id": { - "type": "string", - "description": "Member user ID", - "example": "usr_j572abc123def456" - }, - "role": { - "type": "string", - "enum": [ - "owner", - "admin", - "member" - ] - }, - "joined_at": { - "type": "string", - "format": "date-time", - "description": "ISO 8601 join timestamp" + "value": { + "type": "string" } }, "required": [ - "id", - "user_id", - "role", - "joined_at" + "value" ] }, - "WorkspaceSubscription": { + "StripeAccountCreated": { "type": "object", "properties": { - "id": { - "type": "string" - }, - "workspace_id": { - "type": "string", - "minLength": 1, - "maxLength": 53 - }, - "tier": { + "stripe_account_id": { "type": "string" - }, - "status": { + } + }, + "required": [ + "stripe_account_id" + ] + }, + "CreateStripeAccountBody": { + "type": "object", + "properties": {}, + "additionalProperties": false + }, + "StripeAccountStatus": { + "type": "object", + "properties": { + "stripe_account_id": { "type": "string" }, - "cancellation_scheduled": { + "charges_enabled": { "type": "boolean" }, - "current_period_end": { - "type": "string", - "nullable": true - }, - "billed_by": { - "type": "string", - "enum": [ - "platform", - "seller" - ] - }, - "created_at": { - "type": "integer", - "minimum": 0, - "description": "Unix timestamp (seconds)" + "payouts_enabled": { + "type": "boolean" } }, "required": [ - "id", - "workspace_id", - "tier", - "status", - "cancellation_scheduled", - "current_period_end", - "billed_by", - "created_at" + "stripe_account_id", + "charges_enabled", + "payouts_enabled" ] }, - "WorkspaceAccessState": { + "StripeAccountLinkCreated": { "type": "object", "properties": { - "workspace_id": { - "type": "string", - "minLength": 1, - "maxLength": 53 - }, - "status": { - "type": "string", - "enum": [ - "active", - "payment_grace", - "restricted", - "suspended", - "ended", - "reactivating" - ] - }, - "access_version": { - "type": "integer", - "minimum": 0 - }, - "accessible": { - "type": "boolean" - }, - "reason": { - "type": "string", - "nullable": true, - "enum": [ - "payment_grace", - "restricted", - "suspended", - "ended", - "reactivating", - null - ] - }, - "reconciliation_status": { + "url": { + "type": "string" + } + }, + "required": [ + "url" + ] + }, + "CreateStripeAccountLinkBody": { + "type": "object", + "properties": { + "return_url": { "type": "string", - "enum": [ - "pending", - "reconciled", - "failed" - ] - }, - "payment_grace_ends_at": { - "type": "integer", - "nullable": true, - "minimum": 0, - "description": "Unix timestamp (seconds)" - }, - "restricted_at": { - "type": "integer", - "nullable": true, - "minimum": 0, - "description": "Unix timestamp (seconds)" - }, - "suspend_at": { - "type": "integer", - "nullable": true, - "minimum": 0, - "description": "Unix timestamp (seconds)" + "format": "uri" }, - "ended_at": { - "type": "integer", - "nullable": true, - "minimum": 0, - "description": "Unix timestamp (seconds)" + "refresh_url": { + "type": "string", + "format": "uri" + } + }, + "additionalProperties": false + }, + "StripeAccountSessionCreated": { + "type": "object", + "properties": { + "client_secret": { + "type": "string" } }, "required": [ - "workspace_id", - "status", - "access_version", - "accessible", - "reason", - "reconciliation_status", - "payment_grace_ends_at", - "restricted_at", - "suspend_at", - "ended_at" + "client_secret" ] }, - "SubscriptionChangeRequestList": { + "CreateStripeAccountSessionBody": { + "type": "object", + "properties": {}, + "additionalProperties": false + }, + "WorkspaceStripeProducts": { "type": "object", "properties": { "data": { "type": "array", "items": { - "$ref": "#/components/schemas/SubscriptionChangeRequest" + "$ref": "#/components/schemas/StripeProduct" } }, "has_more": { @@ -9013,111 +21669,163 @@ "type": "string", "nullable": true, "description": "Opaque cursor for the next page, or null if no more pages." + }, + "stripe_account_id": { + "type": "string", + "nullable": true } }, "required": [ "data", "has_more", - "next_cursor" + "next_cursor", + "stripe_account_id" ] }, - "SubscriptionChangeRequest": { + "StripeProduct": { "type": "object", "properties": { "id": { - "type": "string", - "minLength": 1, - "maxLength": 55 - }, - "workspace_id": { - "type": "string", - "minLength": 1, - "maxLength": 53 - }, - "requested_tier": { "type": "string" }, - "status": { + "name": { "type": "string" }, - "effective_at": { - "type": "string", - "nullable": true + "images": { + "type": "array", + "items": { + "type": "string" + } }, - "created_at": { - "type": "integer", - "minimum": 0, - "description": "Unix timestamp (seconds)" + "prices": { + "type": "array", + "items": { + "$ref": "#/components/schemas/StripePrice" + } } }, "required": [ "id", - "workspace_id", - "requested_tier", - "status", - "effective_at", - "created_at" + "name", + "images", + "prices" ] }, - "CreatedApiToken": { + "StripePrice": { "type": "object", "properties": { "id": { - "type": "string", - "minLength": 1, - "maxLength": 54 + "type": "string" }, - "workspace_id": { - "type": "string", - "minLength": 1, - "maxLength": 53 + "currency": { + "type": "string" }, - "name": { + "billing_scheme": { "type": "string" }, - "token": { + "nickname": { "type": "string", - "description": "The full token. This is shown only once - store it securely.", - "example": "sk_akua_a3b2c4d5e6f7g8h9i0j1k2l3m4n5o6p7" + "nullable": true + }, + "unit_amount": { + "type": "number", + "nullable": true + }, + "unit_amount_decimal": { + "type": "string", + "nullable": true + }, + "recurring": { + "type": "object", + "nullable": true, + "properties": { + "interval": { + "type": "string" + }, + "interval_count": { + "type": "number" + }, + "usage_type": { + "type": "string" + } + }, + "required": [ + "interval", + "interval_count", + "usage_type" + ] } }, "required": [ "id", - "workspace_id", - "name", - "token" + "currency", + "billing_scheme", + "nickname", + "unit_amount", + "unit_amount_decimal", + "recurring" ] }, - "CreateApiTokenRequest": { + "UpgradeCheckoutCreated": { "type": "object", "properties": { - "name": { + "url": { + "type": "string" + } + }, + "required": [ + "url" + ] + }, + "CreateUpgradeCheckoutBody": { + "type": "object", + "properties": { + "success_url": { "type": "string", - "minLength": 1, - "maxLength": 100, - "description": "Human-readable name for the token", - "example": "My CLI token" + "format": "uri" }, - "expires_at": { - "type": "integer", - "nullable": true, - "minimum": 0, - "description": "Unix timestamp (seconds) when the token expires. Omit or pass null for no expiry.", - "example": 1742169600 + "cancel_url": { + "type": "string", + "format": "uri" } }, "required": [ - "name" + "success_url", + "cancel_url" ], "additionalProperties": false }, - "ApiTokenList": { + "BillingPortalSessionCreated": { + "type": "object", + "properties": { + "url": { + "type": "string" + } + }, + "required": [ + "url" + ] + }, + "CreateBillingPortalSessionBody": { + "type": "object", + "properties": { + "return_url": { + "type": "string", + "format": "uri" + } + }, + "required": [ + "return_url" + ], + "additionalProperties": false + }, + "ClusterList": { "type": "object", "properties": { "data": { "type": "array", "items": { - "$ref": "#/components/schemas/ApiToken" + "$ref": "#/components/schemas/Cluster" } }, "has_more": { @@ -9136,7 +21844,7 @@ "next_cursor" ] }, - "ApiToken": { + "Cluster": { "type": "object", "properties": { "id": { @@ -9144,931 +21852,886 @@ "minLength": 1, "maxLength": 54 }, + "html_url": { + "type": "string", + "maxLength": 2048, + "format": "uri", + "description": "Absolute dashboard URL for this resource. OUTPUT_ONLY.", + "example": "https://akua.dev/clusters/clu_j572abc123def456" + }, + "name": { + "type": "string" + }, "workspace_id": { "type": "string", "minLength": 1, "maxLength": 53 }, - "name": { + "state": { "type": "string", - "example": "My CLI token" + "enum": [ + "pending", + "provisioning", + "active", + "suspended", + "deleting" + ], + "description": "Cluster lifecycle state in canonical lowercase, past-participle naming." }, - "prefix": { + "provider": { "type": "string", - "example": "sk_akua_a3b2", - "description": "Short identifier prefix of the full token, for display only." + "enum": [ + "managed_kaas", + "imported_byoc" + ], + "description": "Cluster control-plane family: managed (`managed_kaas`) vs imported self-managed (`imported_byoc`)." + }, + "reconciling": { + "type": "boolean" }, "created_at": { "type": "integer", "minimum": 0, "description": "Unix timestamp (seconds)" }, - "last_used_at": { - "type": "integer", - "nullable": true, - "minimum": 0, - "description": "Unix timestamp (seconds) of last use, or null if never used" - }, - "expires_at": { - "type": "integer", - "nullable": true, - "minimum": 0, - "description": "Unix timestamp (seconds) when the token expires, or null if never" - } - }, - "required": [ - "id", - "workspace_id", - "name", - "prefix", - "created_at", - "last_used_at", - "expires_at" - ] - }, - "RepositoryList": { - "type": "object", - "properties": { - "data": { - "type": "array", - "items": { - "$ref": "#/components/schemas/Repository" - } - }, - "has_more": { - "type": "boolean", - "description": "True if more items exist after this page." - }, - "next_cursor": { - "type": "string", - "nullable": true, - "description": "Opaque cursor for the next page, or null if no more pages." - } - }, - "required": [ - "data", - "has_more", - "next_cursor" - ] - }, - "Repository": { - "oneOf": [ - { - "type": "object", - "properties": { - "id": { - "type": "string", - "minLength": 1, - "maxLength": 55 - }, - "name": { - "type": "string" - }, - "workspace_id": { - "type": "string", - "minLength": 1, - "maxLength": 53 - }, - "created_at": { - "type": "integer", - "minimum": 0, - "description": "Unix timestamp (seconds)" - }, - "updated_at": { - "type": "integer", - "minimum": 0, - "description": "Unix timestamp (seconds)" - }, - "etag": { - "type": "string" - }, - "reconciling": { - "type": "boolean" - }, - "purpose": { - "type": "string", - "enum": [ - "deploy" - ] - }, - "cluster_id": { - "type": "string", - "minLength": 1, - "maxLength": 54 - }, - "last_deploy_sha": { - "type": "string", - "nullable": true - }, - "last_render_hash": { - "type": "string", - "nullable": true - } - }, - "required": [ - "id", - "name", - "workspace_id", - "created_at", - "updated_at", - "etag", - "reconciling", - "purpose", - "cluster_id" - ] - }, - { - "type": "object", - "properties": { - "id": { - "type": "string", - "minLength": 1, - "maxLength": 55 - }, - "name": { - "type": "string" - }, - "workspace_id": { - "type": "string", - "minLength": 1, - "maxLength": 53 - }, - "created_at": { - "type": "integer", - "minimum": 0, - "description": "Unix timestamp (seconds)" - }, - "updated_at": { - "type": "integer", - "minimum": 0, - "description": "Unix timestamp (seconds)" - }, - "etag": { - "type": "string" - }, - "reconciling": { - "type": "boolean" - }, - "purpose": { - "type": "string", - "enum": [ - "package" - ] - }, - "package_id": { - "type": "string", - "minLength": 1, - "maxLength": 54 - } - }, - "required": [ - "id", - "name", - "workspace_id", - "created_at", - "updated_at", - "etag", - "reconciling", - "purpose", - "package_id" - ] - }, - { - "type": "object", - "properties": { - "id": { - "type": "string", - "minLength": 1, - "maxLength": 55 - }, - "name": { - "type": "string" - }, - "workspace_id": { - "type": "string", - "minLength": 1, - "maxLength": 53 - }, - "created_at": { - "type": "integer", - "minimum": 0, - "description": "Unix timestamp (seconds)" - }, - "updated_at": { - "type": "integer", - "minimum": 0, - "description": "Unix timestamp (seconds)" - }, - "etag": { - "type": "string" - }, - "reconciling": { - "type": "boolean" - }, - "purpose": { - "type": "string", - "enum": [ - "repository_change_request" - ] - }, - "repository_change_request_id": { - "type": "string", - "minLength": 1, - "maxLength": 54 - } - }, - "required": [ - "id", - "name", - "workspace_id", - "created_at", - "updated_at", - "etag", - "reconciling", - "purpose", - "repository_change_request_id" - ] - } - ] - }, - "GithubInstallationUrl": { - "type": "object", - "properties": { - "url": { - "type": "string", - "format": "uri" - } - }, - "required": [ - "url" - ] - }, - "GithubCreateInstallationUrlBody": { - "type": "object", - "properties": { - "redirect_url": { - "type": "string", - "format": "uri" + "updated_at": { + "type": "integer", + "minimum": 0, + "description": "Unix timestamp (seconds)" + }, + "etag": { + "type": "string" } }, - "additionalProperties": false + "required": [ + "id", + "html_url", + "name", + "workspace_id", + "state", + "provider", + "reconciling", + "created_at", + "updated_at", + "etag" + ] }, - "GithubRepoList": { + "DashboardClusterList": { "type": "object", "properties": { - "data": { + "clusters": { "type": "array", "items": { - "$ref": "#/components/schemas/GithubRepo" + "$ref": "#/components/schemas/DashboardCluster" + } + }, + "regions": { + "type": "array", + "items": { + "$ref": "#/components/schemas/DashboardClusterRegion" } } }, "required": [ - "data" + "clusters", + "regions" ] }, - "GithubRepo": { + "DashboardCluster": { "type": "object", "properties": { "id": { - "type": "number" + "type": "string", + "minLength": 1, + "maxLength": 54 + }, + "html_url": { + "type": "string", + "maxLength": 2048, + "format": "uri", + "description": "Absolute dashboard URL for this resource. OUTPUT_ONLY.", + "example": "https://akua.dev/clusters/clu_j572abc123def456" }, "name": { "type": "string" }, - "full_name": { - "type": "string" + "workspace_id": { + "type": "string", + "minLength": 1, + "maxLength": 53 }, - "archived": { - "type": "boolean" + "region_id": { + "type": "string", + "minLength": 1, + "maxLength": 54 }, - "disabled": { - "type": "boolean" + "region": { + "$ref": "#/components/schemas/DashboardClusterRegion" }, - "default_branch": { - "type": "string" + "provider": { + "type": "string", + "enum": [ + "managed_kaas", + "imported_byoc" + ], + "description": "Cluster control-plane family: managed (`managed_kaas`) vs imported self-managed (`imported_byoc`)." }, - "html_url": { - "type": "string" + "kaas": { + "$ref": "#/components/schemas/ClusterKaas" }, - "owner": { - "type": "object", - "properties": { - "id": { - "type": "number" - }, - "login": { - "type": "string" - }, - "type": { - "type": "string" - }, - "avatar_url": { - "type": "string" - }, - "html_url": { - "type": "string" - } - }, - "required": [ - "id", - "login", - "type", - "avatar_url", - "html_url" - ] + "created_at": { + "type": "integer", + "minimum": 0, + "description": "Unix timestamp (seconds)" + }, + "updated_at": { + "type": "integer", + "minimum": 0, + "description": "Unix timestamp (seconds)" + }, + "product_count": { + "type": "integer", + "minimum": 0 + }, + "installs_count": { + "type": "integer", + "minimum": 0 + }, + "deployment_health": { + "$ref": "#/components/schemas/DashboardClusterDeploymentHealth" + }, + "active_operation": { + "$ref": "#/components/schemas/DashboardClusterActiveOperation" + }, + "etag": { + "type": "string" } }, "required": [ "id", - "name", - "full_name", - "archived", - "disabled", - "default_branch", "html_url", - "owner" - ] - }, - "GithubAppInstallationList": { - "type": "object", - "properties": { - "data": { - "type": "array", - "items": { - "$ref": "#/components/schemas/GithubAppInstallation" - } - } - }, - "required": [ - "data" + "name", + "workspace_id", + "region_id", + "region", + "provider", + "kaas", + "created_at", + "updated_at", + "product_count", + "installs_count", + "deployment_health", + "active_operation", + "etag" ] }, - "GithubAppInstallation": { + "DashboardClusterRegion": { "type": "object", "properties": { - "installation_id": { - "type": "integer", - "minimum": 0, - "exclusiveMinimum": true + "id": { + "type": "string", + "minLength": 1, + "maxLength": 54 + }, + "name": { + "type": "string" + }, + "icon": { + "type": "string", + "nullable": true }, "workspace_id": { "type": "string", "minLength": 1, "maxLength": 53 }, - "account": { - "type": "object", - "properties": { - "type": { - "type": "string", - "enum": [ - "User", - "Organization" - ] - }, - "login": { - "type": "string" - }, - "id": { - "type": "number" - } - }, - "required": [ - "type", - "login", - "id" - ] + "created_at": { + "type": "integer", + "minimum": 0, + "description": "Unix timestamp (seconds)" } }, "required": [ - "installation_id", + "id", + "name", + "icon", "workspace_id", - "account" - ] - }, - "GithubWorkflowPrGet": { - "type": "object", - "properties": { - "data": { - "$ref": "#/components/schemas/GithubWorkflowPr" - } - }, - "required": [ - "data" + "created_at" ] }, - "GithubWorkflowPr": { + "ClusterKaas": { "type": "object", "nullable": true, "properties": { - "pr_id": { - "type": "integer", - "minimum": 0, - "exclusiveMinimum": true + "namespace": { + "type": "string" }, - "pr_url": { + "version": { + "type": "string" + }, + "network_profile": { "type": "string", - "format": "uri" + "enum": [ + "linux_cilium", + "mixed_os_calico" + ], + "default": "linux_cilium", + "description": "Immutable networking profile for managed KaaS clusters. Defaults to `linux_cilium`; Windows workers require `mixed_os_calico`." }, "status": { "type": "string", "enum": [ - "open", - "merged", - "closed", - "draft" + "PROVISIONING", + "RUNNING", + "RECONCILING", + "SUSPENDING", + "SUSPENDED", + "RESUMING", + "DELETING", + "ERROR", + "DEGRADED" ] + }, + "status_message": { + "type": "string", + "nullable": true + }, + "suspended_at": { + "type": "integer", + "nullable": true, + "minimum": 0, + "description": "Unix timestamp (seconds)" + }, + "suspended_by": { + "type": "string", + "nullable": true } }, "required": [ - "pr_id", - "pr_url", - "status" + "namespace", + "version", + "network_profile", + "status", + "status_message", + "suspended_at", + "suspended_by" ] }, - "GithubWorkflowRunList": { + "DashboardClusterDeploymentHealth": { "type": "object", "properties": { - "data": { - "type": "array", - "items": { - "$ref": "#/components/schemas/GithubWorkflowRun" - } + "healthy": { + "type": "integer", + "minimum": 0 }, - "has_more": { - "type": "boolean", - "description": "True if more items exist after this page." + "degraded": { + "type": "integer", + "minimum": 0 }, - "next_cursor": { - "type": "string", - "nullable": true, - "description": "Opaque cursor for the next page, or null if no more pages." + "reconciling": { + "type": "integer", + "minimum": 0 + }, + "failed": { + "type": "integer", + "minimum": 0 } }, "required": [ - "data", - "has_more", - "next_cursor" - ] + "healthy", + "degraded", + "reconciling", + "failed" + ], + "description": "Persisted deployment counts. Healthy, degraded, and failed are mutually exclusive lifecycle states; reconciling is an independent activity count and may overlap a health state." }, - "GithubWorkflowRun": { + "DashboardClusterActiveOperation": { "type": "object", + "nullable": true, "properties": { "id": { "type": "string", "minLength": 1, - "maxLength": 54 + "maxLength": 53 }, - "custom": { - "type": "object", - "properties": { - "image": { - "type": "string" - }, - "sent_at": { - "type": "number" - } - }, - "required": [ - "image", - "sent_at" - ] + "type": { + "type": "string", + "minLength": 1 }, - "installation": { - "type": "object", - "properties": { - "id": { - "type": "number" - } - }, - "required": [ - "id" - ] + "started_at": { + "type": "integer", + "minimum": 0, + "description": "Unix timestamp (seconds)" + } + }, + "required": [ + "id", + "type", + "started_at" + ], + "description": "The authoritative running operation for this cluster, independent of recent-operation pagination." + }, + "ClusterCapabilities": { + "type": "object", + "properties": { + "api_groups": { + "type": "array", + "items": { + "type": "string" + } }, - "workflow_run": { - "type": "object", - "properties": { - "id": { - "type": "number" - }, - "name": { - "type": "string" - }, - "path": { - "type": "string" - }, - "workflow_id": { - "type": "number" - }, - "run_number": { - "type": "number" - }, - "html_url": { - "type": "string", - "format": "uri" - }, - "created_at": { - "type": "string" - }, - "updated_at": { - "type": "string" - }, - "run_started_at": { - "type": "string" - }, - "event": { - "type": "string" - }, - "head_branch": { - "type": "string" - }, - "head_sha": { - "type": "string" - }, - "status": { - "type": "string", - "enum": [ - "queued", - "in_progress", - "completed", - "action_required", - "cancelled", - "failure", - "neutral", - "skipped", - "stale", - "success", - "timed_out", - "requested", - "waiting", - "pending" - ] - }, - "conclusion": { - "type": "string", - "nullable": true, - "enum": [ - "success", - "failure", - "cancelled", - "timed_out", - "action_required", - "neutral", - "skipped", - "stale", - "startup_failure", - null - ] - }, - "actor": { - "type": "object", - "properties": { - "login": { - "type": "string" - }, - "id": { - "type": "number" - }, - "avatar_url": { - "type": "string" - }, - "html_url": { - "type": "string", - "format": "uri" - } + "storage_classes": { + "type": "array", + "items": { + "type": "object", + "properties": { + "name": { + "type": "string" }, - "required": [ - "login", - "id" - ] - }, - "referenced_workflows": { - "type": "array", - "items": { - "type": "object", - "properties": { - "path": { - "type": "string" - }, - "sha": { - "type": "string" - }, - "ref": { - "type": "string" - } - }, - "required": [ - "path", - "sha" - ] + "provisioner": { + "type": "string" + }, + "is_default": { + "type": "boolean" + }, + "reclaim_policy": { + "type": "string" + }, + "volume_binding_mode": { + "type": "string" } }, - "head_commit": { - "type": "object", - "properties": { - "id": { - "type": "string" - }, - "tree_id": { - "type": "string" - }, - "timestamp": { - "type": "string" - }, - "message": { - "type": "string" - }, - "author": { + "required": [ + "name", + "provisioner", + "is_default", + "reclaim_policy", + "volume_binding_mode" + ] + } + }, + "gateway_classes": { + "type": "array", + "items": { + "type": "string" + } + }, + "gateways": { + "type": "array", + "items": { + "type": "object", + "properties": { + "namespace": { + "type": "string" + }, + "name": { + "type": "string" + }, + "gateway_class_name": { + "type": "string" + }, + "listeners": { + "type": "array", + "items": { "type": "object", "properties": { "name": { "type": "string" }, - "email": { + "protocol": { + "type": "string" + }, + "port": { + "type": "number" + }, + "hostname": { "type": "string" } }, "required": [ - "name" + "name", + "protocol", + "port" ] - }, - "committer": { + } + }, + "addresses": { + "type": "array", + "items": { "type": "object", "properties": { - "name": { + "type": { "type": "string" }, - "email": { + "value": { "type": "string" } }, "required": [ - "name" + "type", + "value" ] } }, - "required": [ - "id", - "tree_id", - "timestamp", - "message", - "author", - "committer" - ] - } - }, - "required": [ - "id", - "name", - "path", - "workflow_id", - "run_number", - "html_url", - "created_at", - "updated_at", - "run_started_at", - "event", - "head_branch", - "head_sha", - "status", - "conclusion", - "head_commit" - ] + "status": { + "type": "string", + "enum": [ + "Ready", + "Accepted", + "Pending", + "Error", + "Unknown" + ] + }, + "status_message": { + "type": "string" + } + }, + "required": [ + "namespace", + "name", + "gateway_class_name", + "listeners" + ] + } }, - "repository": { + "default_gateway": { "type": "object", "properties": { - "id": { - "type": "number" - }, - "owner": { - "type": "object", - "properties": { - "login": { - "type": "string" - }, - "id": { - "type": "number" - }, - "avatar_url": { - "type": "string", - "format": "uri" - }, - "html_url": { - "type": "string", - "format": "uri" - } - }, - "required": [ - "login", - "id", - "avatar_url", - "html_url" - ] - }, - "name": { + "namespace": { "type": "string" }, - "full_name": { + "name": { "type": "string" - }, - "html_url": { - "type": "string", - "format": "uri" } }, "required": [ - "id", - "owner", - "name", - "full_name", - "html_url" + "namespace", + "name" ] + }, + "ingress_classes": { + "type": "array", + "items": { + "type": "string" + } + }, + "nodes": { + "type": "array", + "items": { + "$ref": "#/components/schemas/ClusterNode" + } + }, + "freshness": { + "$ref": "#/components/schemas/ClusterCapabilitiesFreshness" } }, "required": [ - "id", - "installation", - "workflow_run", - "repository" + "api_groups", + "storage_classes", + "gateway_classes", + "gateways", + "ingress_classes", + "nodes", + "freshness" ] }, - "GithubPackagePermissions": { + "ClusterNode": { "type": "object", "properties": { - "has_warning": { + "name": { + "type": "string" + }, + "ready": { "type": "boolean" }, - "warning": { + "worker_capacity": { + "type": "boolean" + }, + "schedulable": { + "type": "boolean" + }, + "addresses": { + "type": "array", + "items": { + "type": "object", + "properties": { + "type": { + "type": "string" + }, + "value": { + "type": "string" + } + }, + "required": [ + "type", + "value" + ] + } + }, + "status_message": { "type": "string" }, - "fix_url": { + "roles": { + "type": "array", + "items": { + "type": "string" + } + }, + "created_at": { + "type": "string" + }, + "version": { + "type": "string" + }, + "cpu_capacity": { + "type": "string" + }, + "memory_capacity": { + "type": "string" + }, + "os_image": { + "type": "string" + }, + "operating_system": { + "type": "string" + }, + "architecture": { "type": "string" } }, "required": [ - "has_warning" + "name", + "roles", + "version", + "cpu_capacity", + "memory_capacity", + "os_image", + "architecture" ] }, - "GithubCheckPackagePermissionsBody": { - "type": "object", - "properties": { - "repository": { + "ClusterCapabilitiesFreshness": { + "anyOf": [ + { "type": "object", "properties": { - "id": { - "type": "number" + "state": { + "type": "string", + "enum": [ + "missing" + ] }, - "owner": { - "type": "string" + "max_age_seconds": { + "type": "integer", + "minimum": 0 }, - "name": { - "type": "string" + "age_seconds": { + "nullable": true + }, + "last_successful_at": { + "nullable": true + }, + "last_refresh_status": { + "type": "string", + "nullable": true, + "enum": [ + "FAILED", + "RUNNING", + null + ] + }, + "last_refresh_error": { + "type": "string", + "nullable": true } }, "required": [ - "id", - "owner", - "name" + "state", + "max_age_seconds", + "age_seconds", + "last_successful_at", + "last_refresh_status", + "last_refresh_error" ] }, - "installation_id": { - "type": "integer", - "minimum": 0, - "exclusiveMinimum": true + { + "type": "object", + "properties": { + "state": { + "type": "string", + "enum": [ + "fresh", + "stale" + ] + }, + "max_age_seconds": { + "type": "integer", + "minimum": 0 + }, + "age_seconds": { + "type": "integer", + "minimum": 0 + }, + "last_successful_at": { + "type": "integer", + "minimum": 0, + "description": "Unix timestamp (seconds)" + }, + "last_refresh_status": { + "type": "string", + "enum": [ + "SUCCESS", + "FAILED", + "RUNNING" + ] + }, + "last_refresh_error": { + "type": "string", + "nullable": true + } + }, + "required": [ + "state", + "max_age_seconds", + "age_seconds", + "last_successful_at", + "last_refresh_status", + "last_refresh_error" + ] + } + ] + }, + "Kubeconfig": { + "type": "object", + "properties": { + "kubeconfig": { + "type": "string" } }, "required": [ - "repository", - "installation_id" + "kubeconfig" + ] + }, + "ExecResult": { + "type": "object", + "properties": { + "output": { + "type": "string" + }, + "exit_code": { + "type": "integer" + }, + "duration_ms": { + "type": "number", + "minimum": 0 + } + }, + "required": [ + "output", + "exit_code", + "duration_ms" + ] + }, + "ExecBody": { + "type": "object", + "properties": { + "namespace": { + "type": "string", + "minLength": 1, + "maxLength": 253 + }, + "pod": { + "type": "string", + "minLength": 1, + "maxLength": 253 + }, + "container": { + "type": "string", + "minLength": 1, + "maxLength": 253 + }, + "command": { + "type": "array", + "items": { + "type": "string" + } + } + }, + "required": [ + "namespace", + "pod", + "command" ], "additionalProperties": false }, - "GithubWorkflowPrCreated": { + "WorkerBootstrap": { "type": "object", "properties": { - "pr_id": { - "type": "integer", - "minimum": 0, - "exclusiveMinimum": true + "id": { + "type": "string", + "minLength": 1, + "maxLength": 54 }, - "pr_url": { + "cluster_id": { "type": "string", - "format": "uri" + "minLength": 1, + "maxLength": 54 }, "status": { "type": "string", "enum": [ - "open" + "active", + "revoked", + "expired" + ], + "description": "Lifecycle state for a one-time worker bootstrap token." + }, + "created_at": { + "type": "integer", + "minimum": 0, + "description": "Unix timestamp (seconds)" + }, + "updated_at": { + "type": "integer", + "minimum": 0, + "description": "Unix timestamp (seconds)" + }, + "expires_at": { + "type": "integer", + "minimum": 0, + "description": "Unix timestamp (seconds)" + }, + "etag": { + "type": "string" + }, + "reconciling": { + "type": "boolean", + "description": "True while an authoritative revoke operation is still running." + }, + "active_operation": { + "allOf": [ + { + "$ref": "#/components/schemas/DashboardClusterActiveOperation" + }, + { + "description": "The running revoke operation when its standard operation resource is available." + } ] + }, + "token": { + "type": "string", + "description": "One-time-view bearer token. Populated only on the create response; never returned on subsequent GET/LIST/:revoke reads." + }, + "command": { + "type": "string", + "description": "Bash bootstrap command with the token already substituted, ready to run on a worker node. Reveal-on-create only." + }, + "cloud_init": { + "type": "string", + "description": "Cloud-init YAML with the token already substituted, ready to use as worker-node user-data. Reveal-on-create only." + }, + "artifacts": { + "$ref": "#/components/schemas/WorkerBootstrapArtifacts" } }, "required": [ - "pr_id", - "pr_url", - "status" + "id", + "cluster_id", + "status", + "created_at", + "updated_at", + "etag", + "reconciling", + "active_operation" ] }, - "GithubCreateWorkflowPrBody": { + "WorkerBootstrapList": { "type": "object", "properties": { - "repository": { - "type": "object", - "properties": { - "id": { - "type": "number" - }, - "owner": { - "type": "string" - }, - "name": { - "type": "string" - }, - "default_branch": { - "type": "string" - } - }, - "required": [ - "id", - "owner", - "name", - "default_branch" - ] - }, - "build_settings": { - "type": "object", - "properties": { - "buildContext": { - "type": "string", - "default": "./" - }, - "buildCommand": { - "type": "string" - }, - "startCommand": { - "type": "string" - }, - "installCommand": { - "type": "string" - }, - "buildAptPackages": { - "type": "string" - }, - "runtimeAptPackages": { - "type": "string" - } + "data": { + "type": "array", + "items": { + "$ref": "#/components/schemas/WorkerBootstrap" } }, - "installation_id": { - "type": "integer", - "minimum": 0, - "exclusiveMinimum": true + "has_more": { + "type": "boolean", + "description": "True if more items exist after this page." + }, + "next_cursor": { + "type": "string", + "nullable": true, + "description": "Opaque cursor for the next page, or null if no more pages." } }, "required": [ - "repository", - "build_settings", - "installation_id" + "data", + "has_more", + "next_cursor" + ] + }, + "AdminStatus": { + "type": "object", + "properties": { + "is_admin": { + "type": "boolean", + "description": "Whether the authenticated user has platform administrator access." + } + }, + "required": [ + "is_admin" ], - "additionalProperties": false + "x-platform-visibility": "ADMIN" }, - "GithubVerifyInstallationResponse": { + "DashboardCounts": { "type": "object", "properties": { - "redirect_url": { - "type": "string" + "install_count": { + "type": "integer", + "minimum": 0 + }, + "product_count": { + "type": "integer", + "minimum": 0 + }, + "cluster_count": { + "type": "integer", + "minimum": 0 } }, "required": [ - "redirect_url" - ] + "install_count", + "product_count", + "cluster_count" + ], + "x-platform-visibility": "INTERNAL" }, - "GithubVerifyInstallationBody": { + "OrganizationList": { "type": "object", "properties": { - "installation_id": { - "type": "integer", - "minimum": 0, - "exclusiveMinimum": true + "data": { + "type": "array", + "items": { + "$ref": "#/components/schemas/OrganizationListItem" + } }, - "code": { - "type": "string", - "minLength": 1 + "has_more": { + "type": "boolean", + "description": "True if more items exist after this page." }, - "state": { + "next_cursor": { "type": "string", - "minLength": 1 + "nullable": true, + "description": "Opaque cursor for the next page, or null if no more pages." } }, "required": [ - "installation_id", - "code", - "state" - ], - "additionalProperties": false + "data", + "has_more", + "next_cursor" + ] }, - "Secret": { + "OrganizationListItem": { "type": "object", "properties": { "id": { @@ -10076,68 +22739,21 @@ "minLength": 1, "maxLength": 54 }, - "html_url": { - "type": "string", - "maxLength": 2048, - "format": "uri", - "description": "Absolute dashboard URL for this resource. OUTPUT_ONLY.", - "example": "https://akua.dev/secrets/sec_j572abc123def456" - }, - "workspace_id": { - "type": "string", - "minLength": 1, - "maxLength": 53 - }, "name": { "type": "string", - "minLength": 1, - "maxLength": 200 - }, - "kind": { - "type": "string", - "description": "Secret kind. Current public create values: cloud_provider/hcloud, cloud_provider/aws, cloud_provider/gcp, cloud_provider/azure, oci_registry, cloudflare_api, webhook_signing, generic. cloud_credential is migration-only metadata and cannot be used for new public creates.", - "example": "generic" - }, - "description": { - "type": "string", - "maxLength": 500 - }, - "labels": { - "type": "object", - "additionalProperties": { - "type": "string", - "maxLength": 200 - } + "example": "Code Zero" }, - "state": { + "slug": { "type": "string", - "enum": [ - "active", - "soft_deleted" - ] - }, - "validation": { - "$ref": "#/components/schemas/SecretValidation" + "nullable": true, + "example": "code-zero" }, - "mime_type": { + "icon": { "type": "string", - "maxLength": 100 - }, - "version_aliases": { - "type": "object", - "additionalProperties": { - "type": "integer", - "minimum": 0, - "exclusiveMinimum": true - } - }, - "version_count": { - "type": "integer", - "minimum": 0 - }, - "enabled_version_count": { - "type": "integer", - "minimum": 0 + "nullable": true, + "maxLength": 256, + "format": "uri", + "example": "https://github.com/code-zero.png" }, "created_at": { "type": "integer", @@ -10149,17 +22765,60 @@ "minimum": 0, "description": "Unix timestamp (seconds)" }, - "deleted_at": { - "type": "integer", - "minimum": 0, - "description": "Unix timestamp (seconds)" + "etag": { + "type": "string" }, - "purge_at": { + "role": { + "type": "string", + "enum": [ + "owner", + "admin", + "member" + ], + "description": "Membership role in the organization" + } + }, + "required": [ + "id", + "name", + "slug", + "icon", + "created_at", + "updated_at", + "etag", + "role" + ] + }, + "Organization": { + "type": "object", + "properties": { + "id": { + "type": "string", + "minLength": 1, + "maxLength": 54 + }, + "name": { + "type": "string", + "example": "Code Zero" + }, + "slug": { + "type": "string", + "nullable": true, + "example": "code-zero" + }, + "icon": { + "type": "string", + "nullable": true, + "maxLength": 256, + "format": "uri", + "example": "https://github.com/code-zero.png" + }, + "created_at": { "type": "integer", "minimum": 0, "description": "Unix timestamp (seconds)" }, - "expire_time": { + "updated_at": { "type": "integer", "minimum": 0, "description": "Unix timestamp (seconds)" @@ -10170,484 +22829,139 @@ }, "required": [ "id", - "html_url", - "workspace_id", "name", - "kind", - "state", - "validation", - "version_count", - "enabled_version_count", + "slug", + "icon", "created_at", "updated_at", "etag" ] }, - "SecretValidation": { + "OrganizationCreateRequest": { "type": "object", - "nullable": true, "properties": { - "state": { + "name": { "type": "string", - "enum": [ - "unspecified", - "valid", - "invalid" - ] - }, - "validated_at": { - "type": "integer", - "minimum": 0, - "description": "Unix timestamp (seconds)" + "minLength": 2, + "maxLength": 50, + "pattern": "^[\\p{L}\\p{N}](?:[\\p{L}\\p{N}\\s\\-'&.]*[\\p{L}\\p{N}])?$/u" }, - "error": { - "type": "string" + "slug": { + "type": "string", + "minLength": 3, + "maxLength": 39, + "pattern": "^[a-z0-9](?:[a-z0-9-]*[a-z0-9])?$" } }, "required": [ - "state", - "validated_at" + "name" ], - "description": "Server-managed validation telemetry. Populated for credential-typed secrets; null otherwise. OUTPUT_ONLY — clients cannot set this on create/update." - }, - "CreateSecretBody": { - "oneOf": [ - { - "type": "object", - "properties": { - "name": { - "type": "string", - "minLength": 1, - "maxLength": 200 - }, - "description": { - "type": "string", - "maxLength": 500 - }, - "labels": { - "type": "object", - "additionalProperties": { - "type": "string", - "maxLength": 200 - } - }, - "kind": { - "type": "string", - "enum": [ - "cloud_provider/hcloud" - ] - }, - "value": { - "type": "string", - "minLength": 1 - } - }, - "required": [ - "name", - "kind", - "value" - ], - "additionalProperties": false - }, - { - "type": "object", - "properties": { - "name": { - "type": "string", - "minLength": 1, - "maxLength": 200 - }, - "description": { - "type": "string", - "maxLength": 500 - }, - "labels": { - "type": "object", - "additionalProperties": { - "type": "string", - "maxLength": 200 - } - }, - "kind": { - "type": "string", - "enum": [ - "cloud_provider/aws" - ] - }, - "value": { - "type": "string", - "minLength": 1 - }, - "aws_access_key_id": { - "type": "string" - } - }, - "required": [ - "name", - "kind", - "value" - ], - "additionalProperties": false - }, - { - "type": "object", - "properties": { - "name": { - "type": "string", - "minLength": 1, - "maxLength": 200 - }, - "description": { - "type": "string", - "maxLength": 500 - }, - "labels": { - "type": "object", - "additionalProperties": { - "type": "string", - "maxLength": 200 - } - }, - "kind": { - "type": "string", - "enum": [ - "cloud_provider/gcp" - ] - }, - "value": { - "type": "string", - "minLength": 1 - } - }, - "required": [ - "name", - "kind", - "value" - ], - "additionalProperties": false - }, - { - "type": "object", - "properties": { - "name": { - "type": "string", - "minLength": 1, - "maxLength": 200 - }, - "description": { - "type": "string", - "maxLength": 500 - }, - "labels": { - "type": "object", - "additionalProperties": { - "type": "string", - "maxLength": 200 - } - }, - "kind": { - "type": "string", - "enum": [ - "cloud_provider/azure" - ] - }, - "value": { - "type": "string", - "minLength": 1 - } - }, - "required": [ - "name", - "kind", - "value" - ], - "additionalProperties": false - }, - { - "type": "object", - "properties": { - "name": { - "type": "string", - "minLength": 1, - "maxLength": 200 - }, - "description": { - "type": "string", - "maxLength": 500 - }, - "labels": { - "type": "object", - "additionalProperties": { - "type": "string", - "maxLength": 200 - } - }, - "kind": { - "type": "string", - "enum": [ - "oci_registry" - ] - }, - "value": { - "type": "string", - "minLength": 1 - }, - "username": { - "type": "string" - } - }, - "required": [ - "name", - "kind", - "value" - ], - "additionalProperties": false - }, - { - "type": "object", - "properties": { - "name": { - "type": "string", - "minLength": 1, - "maxLength": 200 - }, - "description": { - "type": "string", - "maxLength": 500 - }, - "labels": { - "type": "object", - "additionalProperties": { - "type": "string", - "maxLength": 200 - } - }, - "kind": { - "type": "string", - "enum": [ - "cloudflare_api" - ] - }, - "value": { - "type": "string", - "minLength": 1 - } - }, - "required": [ - "name", - "kind", - "value" - ], - "additionalProperties": false - }, - { - "type": "object", - "properties": { - "name": { - "type": "string", - "minLength": 1, - "maxLength": 200 - }, - "description": { - "type": "string", - "maxLength": 500 - }, - "labels": { - "type": "object", - "additionalProperties": { - "type": "string", - "maxLength": 200 - } - }, - "kind": { - "type": "string", - "enum": [ - "webhook_signing" - ] - }, - "value": { - "type": "string", - "minLength": 16 - } - }, - "required": [ - "name", - "kind", - "value" - ], - "additionalProperties": false - }, - { - "type": "object", - "properties": { - "name": { - "type": "string", - "minLength": 1, - "maxLength": 200 - }, - "description": { - "type": "string", - "maxLength": 500 - }, - "labels": { - "type": "object", - "additionalProperties": { - "type": "string", - "maxLength": 200 - } - }, - "kind": { - "type": "string", - "enum": [ - "generic" - ] - }, - "value": { - "type": "string", - "minLength": 1 - } - }, - "required": [ - "name", - "kind", - "value" - ], - "additionalProperties": false - } - ] + "additionalProperties": false }, - "SecretList": { + "OrganizationOk": { "type": "object", - "properties": { - "data": { - "type": "array", - "items": { - "$ref": "#/components/schemas/Secret" - } - }, - "has_more": { - "type": "boolean", - "description": "True if more items exist after this page." - }, - "next_cursor": { - "type": "string", - "nullable": true, - "description": "Opaque cursor for the next page, or null if no more pages." + "properties": { + "ok": { + "type": "boolean", + "enum": [ + true + ] } }, "required": [ - "data", - "has_more", - "next_cursor" + "ok" ] }, - "UpdateSecretBody": { + "OrganizationUpdateRequest": { "type": "object", "properties": { "name": { "type": "string", - "minLength": 1, - "maxLength": 200 + "minLength": 2, + "maxLength": 50, + "pattern": "^[\\p{L}\\p{N}](?:[\\p{L}\\p{N}\\s\\-'&.]*[\\p{L}\\p{N}])?$/u" }, - "description": { + "slug": { "type": "string", - "maxLength": 500 - }, - "labels": { - "type": "object", - "additionalProperties": { - "type": "string", - "maxLength": 200 - } + "minLength": 3, + "maxLength": 39, + "pattern": "^[a-z0-9](?:[a-z0-9-]*[a-z0-9])?$" }, - "mime_type": { + "icon": { "type": "string", - "maxLength": 100 - }, - "version_aliases": { - "type": "object", - "additionalProperties": { - "type": "integer", - "minimum": 0, - "exclusiveMinimum": true - } + "nullable": true, + "maxLength": 256, + "format": "uri" } }, "additionalProperties": false }, - "ValidateProviderTokenResult": { + "OrganizationMemberList": { "type": "object", "properties": { - "valid": { + "data": { + "type": "array", + "items": { + "$ref": "#/components/schemas/OrganizationMember" + } + }, + "has_more": { "type": "boolean", - "description": "Whether the token authenticated successfully." + "description": "True if more items exist after this page." }, - "error": { + "next_cursor": { "type": "string", - "description": "Human-readable reason when `valid` is false." + "nullable": true, + "description": "Opaque cursor for the next page, or null if no more pages." } }, "required": [ - "valid" + "data", + "has_more", + "next_cursor" ] }, - "ValidateProviderTokenBody": { + "OrganizationMember": { "type": "object", "properties": { - "provider": { + "user_id": { "type": "string", - "enum": [ - "hcloud" - ], - "description": "Cloud provider to validate the token against." + "example": "user_abc123", + "description": "BetterAuth user ID of the member" }, - "value": { - "type": "string", - "minLength": 1, - "description": "The provider API token to probe. Consumed, never stored." - } - }, - "required": [ - "provider", - "value" - ] - }, - "SecretVersion": { - "type": "object", - "properties": { - "id": { + "name": { "type": "string", - "minLength": 1, - "maxLength": 55 + "nullable": true, + "example": "Robin Owner" }, - "secret_id": { + "email": { "type": "string", - "minLength": 1, - "maxLength": 54 - }, - "version_number": { - "type": "integer", - "minimum": 0, - "exclusiveMinimum": true + "nullable": true, + "format": "email", + "example": "robin@example.com" }, - "state": { + "image": { "type": "string", - "enum": [ - "enabled", - "disabled", - "destroyed" - ] + "nullable": true, + "format": "uri", + "example": "https://example.com/robin.png" }, - "comment": { + "role": { "type": "string", - "maxLength": 200 + "enum": [ + "owner", + "admin", + "member" + ], + "description": "Membership role in the organization", + "example": "admin" }, - "created_at": { + "joined_at": { "type": "integer", "minimum": 0, "description": "Unix timestamp (seconds)" }, - "destroyed_at": { + "updated_at": { "type": "integer", "minimum": 0, "description": "Unix timestamp (seconds)" @@ -10657,38 +22971,47 @@ } }, "required": [ - "id", - "secret_id", - "version_number", - "state", - "created_at", + "user_id", + "name", + "email", + "image", + "role", + "joined_at", + "updated_at", "etag" ] }, - "CreateSecretVersionBody": { + "OrganizationAddMemberRequest": { "type": "object", "properties": { - "value": { + "user_id": { "type": "string", - "minLength": 1 + "example": "user_abc123", + "description": "BetterAuth user ID of the user to add" }, - "comment": { + "role": { "type": "string", - "maxLength": 200 + "enum": [ + "owner", + "admin", + "member" + ], + "default": "member", + "description": "Membership role in the organization" } }, "required": [ - "value" + "user_id" ], "additionalProperties": false }, - "SecretVersionList": { + "OrganizationInvitationList": { "type": "object", "properties": { "data": { "type": "array", "items": { - "$ref": "#/components/schemas/SecretVersion" + "$ref": "#/components/schemas/OrganizationInvitation" } }, "has_more": { @@ -10707,100 +23030,135 @@ "next_cursor" ] }, - "SecretPlaintext": { - "type": "object", - "properties": { - "value": { - "type": "string" - } - }, - "required": [ - "value" - ] - }, - "StripeAccountCreated": { - "type": "object", - "properties": { - "stripe_account_id": { - "type": "string" - } - }, - "required": [ - "stripe_account_id" - ] - }, - "CreateStripeAccountBody": { - "type": "object", - "properties": {}, - "additionalProperties": false - }, - "StripeAccountStatus": { + "OrganizationInvitation": { "type": "object", "properties": { - "stripe_account_id": { + "id": { + "type": "string", + "pattern": "^orgi_[a-z0-9]+$" + }, + "organization_id": { + "type": "string", + "minLength": 1, + "maxLength": 54 + }, + "email": { + "type": "string", + "format": "email" + }, + "role": { + "type": "string", + "enum": [ + "owner", + "admin", + "member" + ], + "description": "Membership role in the organization" + }, + "status": { + "type": "string", + "enum": [ + "pending", + "accepted", + "canceled" + ] + }, + "invited_by": { "type": "string" }, - "charges_enabled": { - "type": "boolean" + "expires_at": { + "type": "integer", + "minimum": 0, + "description": "Unix timestamp (seconds)" }, - "payouts_enabled": { - "type": "boolean" + "created_at": { + "type": "integer", + "minimum": 0, + "description": "Unix timestamp (seconds)" + }, + "updated_at": { + "type": "integer", + "minimum": 0, + "description": "Unix timestamp (seconds)" + }, + "etag": { + "type": "string" } }, "required": [ - "stripe_account_id", - "charges_enabled", - "payouts_enabled" + "id", + "organization_id", + "email", + "role", + "status", + "invited_by", + "expires_at", + "created_at", + "updated_at", + "etag" ] }, - "StripeAccountLinkCreated": { + "OrganizationInvitationCreateRequest": { "type": "object", "properties": { - "url": { + "email": { "type": "string" + }, + "role": { + "type": "string", + "enum": [ + "owner", + "admin", + "member" + ], + "default": "member", + "description": "Membership role in the organization" } }, "required": [ - "url" - ] + "email" + ], + "additionalProperties": false }, - "CreateStripeAccountLinkBody": { + "OrganizationInvitationAcceptRequest": { "type": "object", "properties": { - "return_url": { - "type": "string", - "format": "uri" - }, - "refresh_url": { + "token": { "type": "string", - "format": "uri" + "minLength": 32, + "maxLength": 512 } }, + "required": [ + "token" + ], "additionalProperties": false }, - "StripeAccountSessionCreated": { + "OrganizationUpdateMemberRoleRequest": { "type": "object", "properties": { - "client_secret": { - "type": "string" + "role": { + "type": "string", + "enum": [ + "owner", + "admin", + "member" + ], + "description": "Membership role in the organization" } }, "required": [ - "client_secret" - ] - }, - "CreateStripeAccountSessionBody": { - "type": "object", - "properties": {}, + "role" + ], "additionalProperties": false }, - "WorkspaceStripeProducts": { + "ManagedWorkspaceList": { "type": "object", "properties": { "data": { "type": "array", "items": { - "$ref": "#/components/schemas/StripeProduct" + "$ref": "#/components/schemas/ManagedWorkspace" } }, "has_more": { @@ -10811,163 +23169,246 @@ "type": "string", "nullable": true, "description": "Opaque cursor for the next page, or null if no more pages." - }, - "stripe_account_id": { - "type": "string", - "nullable": true } }, "required": [ "data", "has_more", - "next_cursor", - "stripe_account_id" + "next_cursor" ] }, - "StripeProduct": { + "ManagedWorkspace": { "type": "object", "properties": { "id": { - "type": "string" + "type": "string", + "minLength": 1, + "maxLength": 53 }, "name": { - "type": "string" + "type": "string", + "example": "My Workspace" }, - "images": { - "type": "array", - "items": { - "type": "string" - } + "icon": { + "type": "string", + "nullable": true, + "example": null }, - "prices": { + "created_at": { + "type": "integer", + "minimum": 0, + "description": "Unix timestamp (seconds)" + } + }, + "required": [ + "id", + "name", + "icon", + "created_at" + ] + }, + "NotificationList": { + "type": "object", + "properties": { + "data": { "type": "array", "items": { - "$ref": "#/components/schemas/StripePrice" + "$ref": "#/components/schemas/Notification" } + }, + "has_more": { + "type": "boolean", + "description": "True if more items exist after this page." + }, + "next_cursor": { + "type": "string", + "nullable": true, + "description": "Opaque cursor for the next page, or null if no more pages." } }, "required": [ - "id", - "name", - "images", - "prices" + "data", + "has_more", + "next_cursor" ] }, - "StripePrice": { + "Notification": { "type": "object", "properties": { "id": { - "type": "string" + "type": "string", + "minLength": 1, + "maxLength": 54 }, - "currency": { - "type": "string" + "type": { + "type": "string", + "example": "machine_expiry" }, - "billing_scheme": { + "resource_type": { + "type": "string", + "example": "machine" + }, + "resource_id": { "type": "string" }, - "nickname": { + "title": { "type": "string", "nullable": true }, - "unit_amount": { - "type": "number", + "body": { + "type": "string", "nullable": true }, - "unit_amount_decimal": { + "severity": { "type": "string", - "nullable": true + "nullable": true, + "enum": [ + "info", + "warning", + "critical", + null + ], + "description": "Severity level surfaced to UI indicators." }, - "recurring": { + "context": { "type": "object", "nullable": true, - "properties": { - "interval": { - "type": "string" - }, - "interval_count": { - "type": "number" - }, - "usage_type": { - "type": "string" - } - }, - "required": [ - "interval", - "interval_count", - "usage_type" - ] + "additionalProperties": { + "type": "string" + } + }, + "read_at": { + "type": "integer", + "nullable": true, + "minimum": 0, + "description": "Unix timestamp (seconds) when read, null if unread" + }, + "created_at": { + "type": "integer", + "minimum": 0, + "description": "Unix timestamp (seconds)" } }, "required": [ "id", - "currency", - "billing_scheme", - "nickname", - "unit_amount", - "unit_amount_decimal", - "recurring" + "type", + "resource_type", + "resource_id", + "title", + "body", + "severity", + "context", + "read_at", + "created_at" ] }, - "UpgradeCheckoutCreated": { + "UnreadCount": { "type": "object", "properties": { - "url": { - "type": "string" + "count": { + "type": "number" } }, "required": [ - "url" + "count" ] }, - "CreateUpgradeCheckoutBody": { + "QuotaInfoList": { "type": "object", "properties": { - "success_url": { + "data": { + "type": "array", + "items": { + "$ref": "#/components/schemas/QuotaInfo" + } + }, + "has_more": { + "type": "boolean", + "description": "True if more items exist after this page." + }, + "next_cursor": { "type": "string", - "format": "uri" + "nullable": true, + "description": "Opaque cursor for the next page, or null if no more pages." + } + }, + "required": [ + "data", + "has_more", + "next_cursor" + ] + }, + "QuotaInfo": { + "type": "object", + "properties": { + "metric": { + "type": "string", + "example": "compute/machines", + "description": "Metric: service/resource" + }, + "type": { + "type": "string", + "enum": [ + "allocation", + "rate", + "concurrency" + ], + "description": "Allocation = max owned, rate = max per time window, concurrency = max in-flight.", + "example": "allocation" + }, + "display_name": { + "type": "string", + "example": "Compute machines" + }, + "unit": { + "type": "string", + "enum": [ + "count", + "cores", + "bytes", + "seconds", + "count/day", + "count/minute", + "cents/day" + ], + "description": "Unit the limit/usage numbers are measured in.", + "example": "count" + }, + "limit": { + "type": "number", + "example": 1 + }, + "usage": { + "type": "number", + "example": 0 }, - "cancel_url": { - "type": "string", - "format": "uri" - } - }, - "required": [ - "success_url", - "cancel_url" - ], - "additionalProperties": false - }, - "BillingPortalSessionCreated": { - "type": "object", - "properties": { - "url": { - "type": "string" + "remaining": { + "type": "number", + "example": 1 + }, + "resets_at": { + "type": "integer", + "minimum": 0, + "description": "For rate quotas: Unix timestamp (seconds) reset time" } }, "required": [ - "url" + "metric", + "type", + "display_name", + "unit", + "limit", + "usage", + "remaining" ] }, - "CreateBillingPortalSessionBody": { - "type": "object", - "properties": { - "return_url": { - "type": "string", - "format": "uri" - } - }, - "required": [ - "return_url" - ], - "additionalProperties": false - }, - "ClusterList": { + "RegionList": { "type": "object", "properties": { "data": { "type": "array", "items": { - "$ref": "#/components/schemas/Cluster" + "$ref": "#/components/schemas/Region" } }, "has_more": { @@ -10986,7 +23427,7 @@ "next_cursor" ] }, - "Cluster": { + "Region": { "type": "object", "properties": { "id": { @@ -10994,529 +23435,327 @@ "minLength": 1, "maxLength": 54 }, - "html_url": { + "name": { "type": "string", - "maxLength": 2048, - "format": "uri", - "description": "Absolute dashboard URL for this resource. OUTPUT_ONLY.", - "example": "https://akua.dev/clusters/clu_j572abc123def456" + "example": "us-east-1" }, - "name": { - "type": "string" + "icon": { + "type": "string", + "nullable": true, + "description": "Icon URL" }, "workspace_id": { "type": "string", "minLength": 1, "maxLength": 53 }, - "state": { - "type": "string", - "enum": [ - "pending", - "provisioning", - "active", - "suspended", - "deleting" - ], - "description": "Cluster lifecycle state in canonical lowercase, past-participle naming." - }, - "provider": { - "type": "string", - "enum": [ - "managed_kaas", - "imported_byoc" - ], - "description": "Cluster control-plane family: managed (`managed_kaas`) vs imported self-managed (`imported_byoc`)." - }, - "reconciling": { - "type": "boolean" - }, "created_at": { "type": "integer", "minimum": 0, "description": "Unix timestamp (seconds)" - }, - "updated_at": { - "type": "integer", - "minimum": 0, - "description": "Unix timestamp (seconds)" - }, - "etag": { - "type": "string" } }, "required": [ "id", - "html_url", "name", + "icon", "workspace_id", - "state", - "provider", - "reconciling", - "created_at", - "updated_at", - "etag" + "created_at" ] }, - "DashboardClusterList": { + "DashboardRegionList": { "type": "object", "properties": { - "clusters": { + "data": { "type": "array", "items": { - "$ref": "#/components/schemas/DashboardCluster" + "$ref": "#/components/schemas/DashboardRegion" } }, - "regions": { - "type": "array", - "items": { - "$ref": "#/components/schemas/DashboardClusterRegion" - } + "has_more": { + "type": "boolean", + "description": "True if more items exist after this page." + }, + "next_cursor": { + "type": "string", + "nullable": true, + "description": "Opaque cursor for the next page, or null if no more pages." } }, "required": [ - "clusters", - "regions" + "data", + "has_more", + "next_cursor" ] }, - "DashboardCluster": { + "DashboardRegion": { + "allOf": [ + { + "$ref": "#/components/schemas/Region" + }, + { + "type": "object", + "properties": { + "cluster_pool_health": { + "$ref": "#/components/schemas/ClusterPoolHealth" + } + }, + "required": [ + "cluster_pool_health" + ] + } + ] + }, + "ClusterPoolHealth": { "type": "object", "properties": { - "id": { + "region_id": { "type": "string", "minLength": 1, "maxLength": 54 }, - "html_url": { - "type": "string", - "maxLength": 2048, - "format": "uri", - "description": "Absolute dashboard URL for this resource. OUTPUT_ONLY.", - "example": "https://akua.dev/clusters/clu_j572abc123def456" + "target_size": { + "type": "number" }, - "name": { - "type": "string" + "enabled": { + "type": "boolean" }, - "workspace_id": { - "type": "string", - "minLength": 1, - "maxLength": 53 + "available": { + "type": "number" }, - "region_id": { - "type": "string", - "minLength": 1, - "maxLength": 54 + "provisioning": { + "type": "number" }, - "region": { - "$ref": "#/components/schemas/DashboardClusterRegion" + "allocation_requests": { + "type": "number" }, - "kaas": { - "$ref": "#/components/schemas/ClusterKaas" + "allocated_last_24h": { + "type": "number" }, - "created_at": { - "type": "integer", - "minimum": 0, - "description": "Unix timestamp (seconds)" + "deleted_last_24h": { + "type": "number" }, - "updated_at": { + "failed_last_24h": { + "type": "number" + }, + "last_refill_at": { "type": "integer", "minimum": 0, "description": "Unix timestamp (seconds)" }, - "product_count": { - "type": "integer", - "minimum": 0 - }, - "installs_count": { - "type": "integer", - "minimum": 0 - }, - "etag": { + "last_error": { "type": "string" } }, "required": [ - "id", - "html_url", - "name", - "workspace_id", "region_id", - "region", - "kaas", - "created_at", - "updated_at", - "product_count", - "installs_count", - "etag" + "target_size", + "enabled", + "available", + "provisioning", + "allocation_requests", + "allocated_last_24h", + "deleted_last_24h", + "failed_last_24h" ] }, - "DashboardClusterRegion": { + "RegistryCredentialList": { "type": "object", "properties": { - "id": { - "type": "string", - "minLength": 1, - "maxLength": 54 - }, - "name": { - "type": "string" + "data": { + "type": "array", + "items": { + "$ref": "#/components/schemas/RegistryCredential" + } }, - "icon": { - "type": "string", - "nullable": true + "has_more": { + "type": "boolean", + "description": "True if more items exist after this page." }, - "workspace_id": { + "next_cursor": { "type": "string", - "minLength": 1, - "maxLength": 53 - }, - "created_at": { - "type": "integer", - "minimum": 0, - "description": "Unix timestamp (seconds)" + "nullable": true, + "description": "Opaque cursor for the next page, or null if no more pages." } }, "required": [ - "id", - "name", - "icon", - "workspace_id", - "created_at" + "data", + "has_more", + "next_cursor" ] }, - "ClusterKaas": { + "RegistryCredential": { "type": "object", - "nullable": true, "properties": { - "namespace": { - "type": "string" + "id": { + "type": "string", + "minLength": 1, + "maxLength": 55 }, - "version": { - "type": "string" + "name": { + "type": "string", + "example": "GitHub Container Registry" }, - "network_profile": { + "registry_url": { "type": "string", - "enum": [ - "linux_cilium", - "mixed_os_calico" - ], - "default": "linux_cilium", - "description": "Immutable networking profile for managed KaaS clusters. Defaults to `linux_cilium`; Windows workers require `mixed_os_calico`." + "example": "ghcr.io" }, - "status": { + "type": { "type": "string", "enum": [ - "PROVISIONING", - "RUNNING", - "RECONCILING", - "SUSPENDING", - "SUSPENDED", - "RESUMING", - "DELETING", - "ERROR", - "DEGRADED" - ] + "basic", + "token", + "oauth" + ], + "description": "Authentication scheme used to talk to the upstream registry." }, - "status_message": { - "type": "string", - "nullable": true + "is_active": { + "type": "boolean", + "description": "Whether the credential is active" }, - "suspended_at": { + "created_at": { "type": "integer", - "nullable": true, "minimum": 0, "description": "Unix timestamp (seconds)" }, - "suspended_by": { - "type": "string", - "nullable": true + "last_used_at": { + "type": "integer", + "nullable": true, + "minimum": 0, + "description": "Unix timestamp (seconds), null if never used" } }, "required": [ - "namespace", - "version", - "network_profile", - "status", - "status_message", - "suspended_at", - "suspended_by" + "id", + "name", + "registry_url", + "type", + "is_active", + "created_at", + "last_used_at" ] }, - "ClusterCapabilities": { + "RegistryStats": { "type": "object", "properties": { - "api_groups": { - "type": "array", - "items": { - "type": "string" - } + "total_pulls": { + "type": "number" }, - "storage_classes": { - "type": "array", - "items": { - "type": "object", - "properties": { - "name": { - "type": "string" - }, - "provisioner": { - "type": "string" - }, - "is_default": { - "type": "boolean" - }, - "reclaim_policy": { - "type": "string" - }, - "volume_binding_mode": { - "type": "string" - } - }, - "required": [ - "name", - "provisioner", - "is_default", - "reclaim_policy", - "volume_binding_mode" - ] - } + "successful_pulls": { + "type": "number" }, - "gateway_classes": { - "type": "array", - "items": { - "type": "string" - } + "failed_pulls": { + "type": "number" }, - "gateways": { - "type": "array", - "items": { - "type": "object", - "properties": { - "namespace": { - "type": "string" - }, - "name": { - "type": "string" - }, - "gateway_class_name": { - "type": "string" - }, - "listeners": { - "type": "array", - "items": { - "type": "object", - "properties": { - "name": { - "type": "string" - }, - "protocol": { - "type": "string" - }, - "port": { - "type": "number" - }, - "hostname": { - "type": "string" - } - }, - "required": [ - "name", - "protocol", - "port" - ] - } - }, - "addresses": { - "type": "array", - "items": { - "type": "object", - "properties": { - "type": { - "type": "string" - }, - "value": { - "type": "string" - } - }, - "required": [ - "type", - "value" - ] - } - }, - "status": { - "type": "string", - "enum": [ - "Ready", - "Accepted", - "Pending", - "Error", - "Unknown" - ] - }, - "status_message": { - "type": "string" - } - }, - "required": [ - "namespace", - "name", - "gateway_class_name", - "listeners" - ] - } + "success_rate": { + "type": "number" }, - "default_gateway": { - "type": "object", - "properties": { - "namespace": { - "type": "string" - }, - "name": { - "type": "string" - } - }, - "required": [ - "namespace", - "name" - ] + "auth_successes": { + "type": "number" }, - "ingress_classes": { - "type": "array", - "items": { - "type": "string" - } + "auth_failures": { + "type": "number" }, - "nodes": { + "by_registry": { "type": "array", "items": { "type": "object", "properties": { - "name": { - "type": "string" - }, - "ready": { - "type": "boolean" - }, - "worker_capacity": { - "type": "boolean" - }, - "status_message": { - "type": "string" - }, - "roles": { - "type": "array", - "items": { - "type": "string" - } - }, - "created_at": { - "type": "string" - }, - "version": { - "type": "string" - }, - "cpu_capacity": { - "type": "string" - }, - "memory_capacity": { - "type": "string" - }, - "os_image": { + "registry_url": { "type": "string" }, - "operating_system": { - "type": "string" + "pulls": { + "type": "number" }, - "architecture": { - "type": "string" + "failures": { + "type": "number" } }, "required": [ - "name", - "roles", - "version", - "cpu_capacity", - "memory_capacity", - "os_image", - "architecture" + "registry_url", + "pulls", + "failures" ] } + }, + "latency": { + "type": "object", + "properties": { + "avg": { + "type": "number", + "nullable": true + }, + "p95": { + "type": "number", + "nullable": true + } + }, + "required": [ + "avg", + "p95" + ] } }, "required": [ - "api_groups", - "storage_classes", - "gateway_classes", - "gateways", - "ingress_classes", - "nodes" + "total_pulls", + "successful_pulls", + "failed_pulls", + "success_rate", + "auth_successes", + "auth_failures", + "by_registry", + "latency" ] }, - "Kubeconfig": { + "RegistryActivityResponse": { "type": "object", "properties": { - "kubeconfig": { - "type": "string" + "data": { + "type": "array", + "items": { + "$ref": "#/components/schemas/RegistryActivityBucket" + } } }, "required": [ - "kubeconfig" + "data" ] }, - "ExecResult": { + "RegistryActivityBucket": { "type": "object", "properties": { - "output": { - "type": "string" + "timestamp": { + "type": "number", + "description": "Unix timestamp in milliseconds." }, - "exit_code": { - "type": "integer" + "success": { + "type": "number" }, - "duration_ms": { - "type": "number", - "minimum": 0 + "failed": { + "type": "number" } }, "required": [ - "output", - "exit_code", - "duration_ms" + "timestamp", + "success", + "failed" ] }, - "ExecBody": { + "RegistryAuditLogList": { "type": "object", "properties": { - "namespace": { - "type": "string", - "minLength": 1, - "maxLength": 253 - }, - "pod": { - "type": "string", - "minLength": 1, - "maxLength": 253 - }, - "container": { - "type": "string", - "minLength": 1, - "maxLength": 253 - }, - "command": { + "data": { "type": "array", "items": { - "type": "string" + "$ref": "#/components/schemas/RegistryAuditLog" } } }, "required": [ - "namespace", - "pod", - "command" - ], - "additionalProperties": false + "data" + ] }, - "WorkerBootstrap": { + "RegistryAuditLog": { "type": "object", "properties": { "id": { @@ -11524,150 +23763,79 @@ "minLength": 1, "maxLength": 54 }, - "cluster_id": { - "type": "string", - "minLength": 1, - "maxLength": 54 + "timestamp": { + "type": "number", + "description": "Unix timestamp in milliseconds." }, - "status": { + "operation": { "type": "string", "enum": [ - "active", - "revoked", - "expired" - ], - "description": "Lifecycle state for a one-time worker bootstrap token." - }, - "created_at": { - "type": "integer", - "minimum": 0, - "description": "Unix timestamp (seconds)" - }, - "updated_at": { - "type": "integer", - "minimum": 0, - "description": "Unix timestamp (seconds)" + "pull_manifest", + "pull_blob", + "pull_failed", + "auth_success", + "auth_failed" + ] }, - "expires_at": { - "type": "integer", - "minimum": 0, - "description": "Unix timestamp (seconds)" + "registry_url": { + "type": "string" }, - "etag": { + "repository": { "type": "string" }, - "token": { + "reference": { "type": "string", - "description": "One-time-view bearer token. Populated only on the create response; never returned on subsequent GET/LIST/:revoke reads." + "nullable": true }, - "command": { - "type": "string", - "description": "Bash bootstrap command with the token already substituted, ready to run on a worker node. Reveal-on-create only." + "success": { + "type": "boolean" }, - "cloud_init": { + "install_name": { "type": "string", - "description": "Cloud-init YAML with the token already substituted, ready to use as worker-node user-data. Reveal-on-create only." - }, - "artifacts": { - "$ref": "#/components/schemas/WorkerBootstrapArtifacts" + "nullable": true } }, "required": [ "id", - "cluster_id", - "status", - "created_at", - "updated_at", - "etag" + "timestamp", + "operation", + "registry_url", + "repository", + "reference", + "success", + "install_name" ] }, - "WorkerBootstrapList": { + "RegistryErrorList": { "type": "object", "properties": { "data": { "type": "array", "items": { - "$ref": "#/components/schemas/WorkerBootstrap" + "$ref": "#/components/schemas/RegistryError" } - }, - "has_more": { - "type": "boolean", - "description": "True if more items exist after this page." - }, - "next_cursor": { - "type": "string", - "nullable": true, - "description": "Opaque cursor for the next page, or null if no more pages." } }, "required": [ - "data", - "has_more", - "next_cursor" + "data" ] }, - "AdminStatus": { - "type": "object", - "properties": { - "is_admin": { - "type": "boolean", - "description": "Whether the authenticated user has platform administrator access." - } - }, - "required": [ - "is_admin" - ], - "x-platform-visibility": "ADMIN" - }, - "DashboardCounts": { - "type": "object", - "properties": { - "install_count": { - "type": "integer", - "minimum": 0 - }, - "product_count": { - "type": "integer", - "minimum": 0 - }, - "cluster_count": { - "type": "integer", - "minimum": 0 - } - }, - "required": [ - "install_count", - "product_count", - "cluster_count" - ], - "x-platform-visibility": "INTERNAL" - }, - "OrganizationList": { + "RegistryError": { "type": "object", "properties": { - "data": { - "type": "array", - "items": { - "$ref": "#/components/schemas/Organization" - } - }, - "has_more": { - "type": "boolean", - "description": "True if more items exist after this page." + "message": { + "type": "string" }, - "next_cursor": { - "type": "string", - "nullable": true, - "description": "Opaque cursor for the next page, or null if no more pages." + "count": { + "type": "number" } }, "required": [ - "data", - "has_more", - "next_cursor" + "message", + "count" ] }, - "Organization": { + "CreateRepositoryChangeRequestResponse": { "type": "object", "properties": { "id": { @@ -11675,14 +23843,109 @@ "minLength": 1, "maxLength": 54 }, - "name": { + "html_url": { "type": "string", - "example": "Code Zero" + "maxLength": 2048, + "format": "uri", + "description": "Absolute dashboard URL for this resource. OUTPUT_ONLY.", + "example": "https://akua.dev/repository-change-requests/rcr_j572abc123def456" }, - "slug": { + "workspace_id": { + "type": "string", + "minLength": 1, + "maxLength": 53 + }, + "parent_repository_id": { + "type": "string", + "minLength": 1, + "maxLength": 55 + }, + "fork_repository_id": { + "type": "string", + "minLength": 1, + "maxLength": 55 + }, + "state": { + "type": "string", + "enum": [ + "AWAITING_CHANGES", + "VALIDATING", + "READY", + "ACCEPTING", + "ACCEPTED", + "REJECTED", + "WITHDRAWN", + "EXPIRED", + "FAILED" + ], + "description": "Repository change request lifecycle state" + }, + "change_type": { + "type": "string", + "enum": [ + "manifest_patch", + "inputs_change", + "package_change", + "unknown" + ] + }, + "created_by_type": { "type": "string", + "enum": [ + "user", + "wizard", + "agent" + ] + }, + "created_by_id": { + "type": "string" + }, + "remediation_evidence": { + "type": "object", "nullable": true, - "example": "code-zero" + "properties": { + "summary": { + "type": "string", + "minLength": 1, + "maxLength": 2000 + }, + "likely_fix": { + "type": "string", + "minLength": 1, + "maxLength": 2000 + }, + "resource_refs": { + "type": "array", + "items": { + "type": "object", + "properties": { + "resource": { + "type": "string", + "minLength": 1, + "maxLength": 120 + }, + "id": { + "type": "string", + "minLength": 1, + "maxLength": 200 + } + }, + "required": [ + "resource", + "id" + ], + "additionalProperties": false + }, + "minItems": 1, + "maxItems": 20 + } + }, + "required": [ + "summary", + "likely_fix", + "resource_refs" + ], + "additionalProperties": false }, "created_at": { "type": "integer", @@ -11694,219 +23957,237 @@ "minimum": 0, "description": "Unix timestamp (seconds)" }, + "expires_at": { + "type": "integer", + "minimum": 0, + "description": "Unix timestamp (seconds)" + }, + "rejection_reason": { + "type": "string", + "nullable": true + }, "etag": { "type": "string" } }, "required": [ "id", - "name", - "slug", + "html_url", + "workspace_id", + "parent_repository_id", + "fork_repository_id", + "state", + "change_type", + "created_by_type", + "created_by_id", + "remediation_evidence", "created_at", "updated_at", + "expires_at", + "rejection_reason", "etag" ] }, - "OrganizationCreateRequest": { - "type": "object", - "properties": { - "name": { - "type": "string", - "minLength": 2, - "maxLength": 50, - "pattern": "^[\\p{L}\\p{N}](?:[\\p{L}\\p{N}\\s\\-'&.]*[\\p{L}\\p{N}])?$/u" + "CreateRepositoryChangeRequestBody": { + "oneOf": [ + { + "type": "object", + "properties": { + "parent_repository_id": { + "type": "string", + "minLength": 1, + "maxLength": 55, + "description": "Repository that will receive the accepted change request." + }, + "expires_at_seconds": { + "type": "integer", + "minimum": 0, + "exclusiveMinimum": true, + "description": "Seconds until the repository change request expires." + }, + "kind": { + "type": "string", + "enum": [ + "user" + ] + } + }, + "required": [ + "parent_repository_id", + "kind" + ], + "additionalProperties": false }, - "slug": { - "type": "string", - "minLength": 3, - "maxLength": 39, - "pattern": "^[a-z0-9](?:[a-z0-9-]*[a-z0-9])?$" - } - }, - "required": [ - "name" - ], - "additionalProperties": false - }, - "OrganizationOk": { - "type": "object", - "properties": { - "ok": { - "type": "boolean", - "enum": [ - true - ] - } - }, - "required": [ - "ok" - ] - }, - "OrganizationUpdateRequest": { - "type": "object", - "properties": { - "name": { - "type": "string", - "minLength": 2, - "maxLength": 50, - "pattern": "^[\\p{L}\\p{N}](?:[\\p{L}\\p{N}\\s\\-'&.]*[\\p{L}\\p{N}])?$/u" + { + "type": "object", + "properties": { + "parent_repository_id": { + "type": "string", + "minLength": 1, + "maxLength": 55, + "description": "Repository that will receive the accepted change request." + }, + "expires_at_seconds": { + "type": "integer", + "minimum": 0, + "exclusiveMinimum": true, + "description": "Seconds until the repository change request expires." + }, + "kind": { + "type": "string", + "enum": [ + "wizard" + ] + } + }, + "required": [ + "parent_repository_id", + "kind" + ], + "additionalProperties": false }, - "slug": { - "type": "string", - "minLength": 3, - "maxLength": 39, - "pattern": "^[a-z0-9](?:[a-z0-9-]*[a-z0-9])?$" - } - }, - "additionalProperties": false - }, - "OrganizationMemberList": { - "type": "object", - "properties": { - "data": { - "type": "array", - "items": { - "$ref": "#/components/schemas/OrganizationMember" - } + { + "type": "object", + "properties": { + "parent_repository_id": { + "type": "string", + "minLength": 1, + "maxLength": 55, + "description": "Repository that will receive the accepted change request." + }, + "expires_at_seconds": { + "type": "integer", + "minimum": 0, + "exclusiveMinimum": true, + "description": "Seconds until the repository change request expires." + }, + "kind": { + "type": "string", + "enum": [ + "agent" + ], + "description": "Agent actor creating the change request." + }, + "agent_id": { + "type": "string", + "minLength": 1, + "maxLength": 54, + "description": "Agent that found the likely source or configuration fix." + }, + "remediation_evidence": { + "type": "object", + "properties": { + "summary": { + "type": "string", + "minLength": 1, + "maxLength": 2000 + }, + "likely_fix": { + "type": "string", + "minLength": 1, + "maxLength": 2000 + }, + "resource_refs": { + "type": "array", + "items": { + "type": "object", + "properties": { + "resource": { + "type": "string", + "minLength": 1, + "maxLength": 120 + }, + "id": { + "type": "string", + "minLength": 1, + "maxLength": 200 + } + }, + "required": [ + "resource", + "id" + ], + "additionalProperties": false + }, + "minItems": 1, + "maxItems": 20 + } + }, + "required": [ + "summary", + "likely_fix", + "resource_refs" + ], + "additionalProperties": false, + "description": "Evidence that the agent found a likely source or configuration fix before opening the change request." + } + }, + "required": [ + "parent_repository_id", + "kind", + "agent_id", + "remediation_evidence" + ], + "additionalProperties": false } - }, - "required": [ - "data" ] }, - "OrganizationMember": { + "CreateRepositoryChangeRequestTokenResponse": { "type": "object", "properties": { - "user_id": { + "repository_change_request_id": { "type": "string", - "example": "user_abc123", - "description": "BetterAuth user ID of the member" + "minLength": 1, + "maxLength": 54 }, - "role": { + "fork_remote_url": { "type": "string", - "enum": [ - "owner", - "admin", - "member" - ], - "description": "Membership role in the organization", - "example": "admin" + "format": "uri" }, - "joined_at": { - "type": "integer", - "minimum": 0, - "description": "Unix timestamp (seconds)" + "fork_write_token": { + "type": "string" }, - "updated_at": { + "expires_at": { "type": "integer", "minimum": 0, "description": "Unix timestamp (seconds)" - }, - "etag": { - "type": "string" } }, "required": [ - "user_id", - "role", - "joined_at", - "updated_at", - "etag" + "repository_change_request_id", + "fork_remote_url", + "fork_write_token", + "expires_at" ] }, - "OrganizationAddMemberRequest": { - "type": "object", - "properties": { - "user_id": { - "type": "string", - "example": "user_abc123", - "description": "BetterAuth user ID of the user to add" - }, - "role": { - "type": "string", - "enum": [ - "owner", - "admin", - "member" - ], - "default": "member", - "description": "Membership role in the organization" - } - }, - "required": [ - "user_id" - ], - "additionalProperties": false - }, - "OrganizationUpdateMemberRoleRequest": { + "CreateRepositoryChangeRequestTokenBody": { "type": "object", "properties": { - "role": { + "scope": { "type": "string", "enum": [ - "owner", - "admin", - "member" + "read", + "write" ], - "description": "Membership role in the organization" - } - }, - "required": [ - "role" - ], - "additionalProperties": false - }, - "ManagedWorkspaceList": { - "type": "object", - "properties": { - "data": { - "type": "array", - "items": { - "$ref": "#/components/schemas/ManagedWorkspace" - } - } - }, - "required": [ - "data" - ] - }, - "ManagedWorkspace": { - "type": "object", - "properties": { - "id": { - "type": "string", - "minLength": 1, - "maxLength": 53 - }, - "name": { - "type": "string", - "example": "My Workspace" - }, - "icon": { - "type": "string", - "nullable": true, - "example": null + "default": "write" }, - "created_at": { + "expires_in_seconds": { "type": "integer", "minimum": 0, - "description": "Unix timestamp (seconds)" + "exclusiveMinimum": true, + "maximum": 3600, + "description": "Seconds until the fork write token expires. Maximum is one hour." } }, - "required": [ - "id", - "name", - "icon", - "created_at" - ] + "additionalProperties": false }, - "NotificationList": { + "RepositoryChangeRequestList": { "type": "object", "properties": { "data": { "type": "array", "items": { - "$ref": "#/components/schemas/Notification" + "$ref": "#/components/schemas/RepositoryChangeRequest" } }, "has_more": { @@ -11925,7 +24206,7 @@ "next_cursor" ] }, - "Notification": { + "RepositoryChangeRequest": { "type": "object", "properties": { "id": { @@ -11933,194 +24214,230 @@ "minLength": 1, "maxLength": 54 }, - "type": { + "html_url": { "type": "string", - "example": "machine_expiry" + "maxLength": 2048, + "format": "uri", + "description": "Absolute dashboard URL for this resource. OUTPUT_ONLY.", + "example": "https://akua.dev/repository-change-requests/rcr_j572abc123def456" }, - "resource_type": { + "workspace_id": { "type": "string", - "example": "machine" - }, - "resource_id": { - "type": "string" + "minLength": 1, + "maxLength": 53 }, - "title": { + "parent_repository_id": { "type": "string", - "nullable": true + "minLength": 1, + "maxLength": 55 }, - "body": { + "fork_repository_id": { "type": "string", - "nullable": true + "minLength": 1, + "maxLength": 55 }, - "severity": { + "state": { "type": "string", - "nullable": true, "enum": [ - "info", - "warning", - "critical", - null + "AWAITING_CHANGES", + "VALIDATING", + "READY", + "ACCEPTING", + "ACCEPTED", + "REJECTED", + "WITHDRAWN", + "EXPIRED", + "FAILED" ], - "description": "Severity level surfaced to UI indicators." + "description": "Repository change request lifecycle state" }, - "context": { + "change_type": { + "type": "string", + "enum": [ + "manifest_patch", + "inputs_change", + "package_change", + "unknown" + ] + }, + "created_by_type": { + "type": "string", + "enum": [ + "user", + "wizard", + "agent" + ] + }, + "created_by_id": { + "type": "string" + }, + "remediation_evidence": { "type": "object", "nullable": true, - "additionalProperties": { - "type": "string" - } + "properties": { + "summary": { + "type": "string", + "minLength": 1, + "maxLength": 2000 + }, + "likely_fix": { + "type": "string", + "minLength": 1, + "maxLength": 2000 + }, + "resource_refs": { + "type": "array", + "items": { + "type": "object", + "properties": { + "resource": { + "type": "string", + "minLength": 1, + "maxLength": 120 + }, + "id": { + "type": "string", + "minLength": 1, + "maxLength": 200 + } + }, + "required": [ + "resource", + "id" + ], + "additionalProperties": false + }, + "minItems": 1, + "maxItems": 20 + } + }, + "required": [ + "summary", + "likely_fix", + "resource_refs" + ], + "additionalProperties": false }, - "read_at": { + "created_at": { "type": "integer", - "nullable": true, "minimum": 0, - "description": "Unix timestamp (seconds) when read, null if unread" + "description": "Unix timestamp (seconds)" }, - "created_at": { + "updated_at": { + "type": "integer", + "minimum": 0, + "description": "Unix timestamp (seconds)" + }, + "expires_at": { "type": "integer", "minimum": 0, "description": "Unix timestamp (seconds)" + }, + "rejection_reason": { + "type": "string", + "nullable": true + }, + "etag": { + "type": "string" } }, "required": [ "id", - "type", - "resource_type", - "resource_id", - "title", - "body", - "severity", - "context", - "read_at", - "created_at" + "html_url", + "workspace_id", + "parent_repository_id", + "fork_repository_id", + "state", + "change_type", + "created_by_type", + "created_by_id", + "remediation_evidence", + "created_at", + "updated_at", + "expires_at", + "rejection_reason", + "etag" ] }, - "UnreadCount": { + "AcceptRepositoryChangeRequestResponse": { "type": "object", "properties": { - "count": { - "type": "number" + "repository_change_request_id": { + "type": "string", + "minLength": 1, + "maxLength": 54 + }, + "operation_id": { + "type": "string", + "minLength": 1, + "maxLength": 53 + }, + "accepted_at": { + "type": "integer", + "minimum": 0, + "description": "Unix timestamp (seconds)" } }, "required": [ - "count" + "repository_change_request_id", + "operation_id", + "accepted_at" ] }, - "QuotaInfoList": { + "RejectRepositoryChangeRequestResponse": { "type": "object", "properties": { - "data": { - "type": "array", - "items": { - "$ref": "#/components/schemas/QuotaInfo" - } - }, - "has_more": { - "type": "boolean", - "description": "True if more items exist after this page." - }, - "next_cursor": { + "repository_change_request_id": { "type": "string", - "nullable": true, - "description": "Opaque cursor for the next page, or null if no more pages." + "minLength": 1, + "maxLength": 54 + }, + "rejected_at": { + "type": "integer", + "minimum": 0, + "description": "Unix timestamp (seconds)" } }, "required": [ - "data", - "has_more", - "next_cursor" + "repository_change_request_id", + "rejected_at" ] }, - "QuotaInfo": { + "RejectRepositoryChangeRequestBody": { "type": "object", "properties": { - "metric": { - "type": "string", - "example": "compute/machines", - "description": "Metric: service/resource" - }, - "type": { - "type": "string", - "enum": [ - "allocation", - "rate", - "concurrency" - ], - "description": "Allocation = max owned, rate = max per time window, concurrency = max in-flight.", - "example": "allocation" - }, - "display_name": { - "type": "string", - "example": "Compute machines" - }, - "unit": { + "rejection_reason": { "type": "string", - "enum": [ - "count", - "cores", - "bytes", - "seconds", - "count/day", - "count/minute", - "cents/day" - ], - "description": "Unit the limit/usage numbers are measured in.", - "example": "count" - }, - "limit": { - "type": "number", - "example": 1 - }, - "usage": { - "type": "number", - "example": 0 - }, - "remaining": { - "type": "number", - "example": 1 - }, - "resets_at": { - "type": "integer", - "minimum": 0, - "description": "For rate quotas: Unix timestamp (seconds) reset time" + "minLength": 1, + "maxLength": 2000, + "description": "Reason shown in audit logs and review UI." } }, "required": [ - "metric", - "type", - "display_name", - "unit", - "limit", - "usage", - "remaining" - ] + "rejection_reason" + ], + "additionalProperties": false }, - "RegionList": { + "WithdrawRepositoryChangeRequestResponse": { "type": "object", "properties": { - "data": { - "type": "array", - "items": { - "$ref": "#/components/schemas/Region" - } - }, - "has_more": { - "type": "boolean", - "description": "True if more items exist after this page." - }, - "next_cursor": { + "repository_change_request_id": { "type": "string", - "nullable": true, - "description": "Opaque cursor for the next page, or null if no more pages." + "minLength": 1, + "maxLength": 54 + }, + "withdrawn_at": { + "type": "integer", + "minimum": 0, + "description": "Unix timestamp (seconds)" } }, "required": [ - "data", - "has_more", - "next_cursor" + "repository_change_request_id", + "withdrawn_at" ] }, - "Region": { + "Agent": { "type": "object", "properties": { "id": { @@ -12128,327 +24445,493 @@ "minLength": 1, "maxLength": 54 }, - "name": { + "workspace_id": { + "type": "string", + "minLength": 1, + "maxLength": 53 + }, + "organization_id": { + "type": "string", + "nullable": true, + "minLength": 1, + "maxLength": 54 + }, + "name": { + "type": "string" + }, + "description": { + "type": "string", + "nullable": true + }, + "instructions": { + "type": "string" + }, + "state": { + "type": "string", + "enum": [ + "ENABLED", + "ARCHIVED" + ] + }, + "origin": { "type": "string", - "example": "us-east-1" + "enum": [ + "PLATFORM", + "USER", + "SYSTEM" + ] }, - "icon": { - "type": "string", - "nullable": true, - "description": "Icon URL" + "capabilities": { + "type": "array", + "items": { + "type": "string", + "enum": [ + "CHAT", + "CODING", + "AMBIENT" + ] + } }, - "workspace_id": { - "type": "string", - "minLength": 1, - "maxLength": 53 + "ambient": { + "$ref": "#/components/schemas/AgentAmbientConfig" + }, + "model_policy": { + "$ref": "#/components/schemas/AgentModelPolicy" + }, + "created_by": { + "type": "string" + }, + "usage_summary": { + "$ref": "#/components/schemas/AgentUsageSummary" }, "created_at": { "type": "integer", "minimum": 0, "description": "Unix timestamp (seconds)" + }, + "updated_at": { + "type": "integer", + "minimum": 0, + "description": "Unix timestamp (seconds)" + }, + "etag": { + "type": "string" } }, "required": [ "id", - "name", - "icon", "workspace_id", - "created_at" + "organization_id", + "name", + "description", + "instructions", + "state", + "origin", + "capabilities", + "ambient", + "model_policy", + "created_by", + "usage_summary", + "created_at", + "updated_at", + "etag" ] }, - "DashboardRegionList": { + "AgentAmbientConfig": { "type": "object", + "nullable": true, "properties": { - "data": { - "type": "array", - "items": { - "$ref": "#/components/schemas/DashboardRegion" - } + "enabled": { + "type": "boolean" }, - "has_more": { - "type": "boolean", - "description": "True if more items exist after this page." + "policy": { + "$ref": "#/components/schemas/AgentAmbientPolicy" }, - "next_cursor": { - "type": "string", - "nullable": true, - "description": "Opaque cursor for the next page, or null if no more pages." + "triggers": { + "type": "array", + "items": { + "$ref": "#/components/schemas/AgentAmbientTrigger" + }, + "maxItems": 50 } }, "required": [ - "data", - "has_more", - "next_cursor" - ] - }, - "DashboardRegion": { - "allOf": [ - { - "$ref": "#/components/schemas/Region" - }, - { - "type": "object", - "properties": { - "cluster_pool_health": { - "$ref": "#/components/schemas/ClusterPoolHealth" - } - }, - "required": [ - "cluster_pool_health" - ] - } + "enabled", + "triggers" ] }, - "ClusterPoolHealth": { + "AgentAmbientPolicy": { "type": "object", "properties": { - "region_id": { + "remediation_mode": { "type": "string", - "minLength": 1, - "maxLength": 54 - }, - "target_size": { - "type": "number" - }, - "enabled": { - "type": "boolean" - }, - "available": { - "type": "number" - }, - "provisioning": { - "type": "number" - }, - "allocation_requests": { - "type": "number" - }, - "allocated_last_24h": { - "type": "number" - }, - "deleted_last_24h": { - "type": "number" + "enum": [ + "READ_ONLY", + "APPROVAL_GATED" + ] }, - "failed_last_24h": { - "type": "number" + "allowed_resource_scopes": { + "type": "array", + "items": { + "$ref": "#/components/schemas/AgentAmbientResourceScope" + }, + "maxItems": 100 }, - "last_refill_at": { + "max_spend_cents_per_trigger": { "type": "integer", - "minimum": 0, - "description": "Unix timestamp (seconds)" - }, - "last_error": { - "type": "string" + "minimum": 0 } }, "required": [ - "region_id", - "target_size", - "enabled", - "available", - "provisioning", - "allocation_requests", - "allocated_last_24h", - "deleted_last_24h", - "failed_last_24h" + "remediation_mode", + "allowed_resource_scopes" ] }, - "RegistryCredentialList": { + "AgentAmbientResourceScope": { "type": "object", "properties": { - "data": { - "type": "array", - "items": { - "$ref": "#/components/schemas/RegistryCredential" - } - }, - "has_more": { - "type": "boolean", - "description": "True if more items exist after this page." + "type": { + "type": "string", + "minLength": 1, + "maxLength": 120 }, - "next_cursor": { + "id": { "type": "string", - "nullable": true, - "description": "Opaque cursor for the next page, or null if no more pages." + "minLength": 1, + "maxLength": 200 } }, "required": [ - "data", - "has_more", - "next_cursor" + "type" ] }, - "RegistryCredential": { + "AgentAmbientTrigger": { "type": "object", "properties": { - "id": { + "trigger_id": { "type": "string", "minLength": 1, - "maxLength": 55 + "maxLength": 120 }, - "name": { + "type": { "type": "string", - "example": "GitHub Container Registry" + "enum": [ + "INSTALL_STATE", + "CLUSTER_DEGRADATION", + "SECURITY_FINDING", + "QUOTA_PRESSURE", + "COST_ANOMALY", + "MANUAL_TEST" + ] }, - "registry_url": { + "state": { "type": "string", - "example": "ghcr.io" + "enum": [ + "ENABLED", + "DISABLED" + ] }, - "type": { + "severity_min": { "type": "string", "enum": [ - "basic", - "token", - "oauth" - ], - "description": "Authentication scheme used to talk to the upstream registry." + "LOW", + "MEDIUM", + "HIGH", + "CRITICAL" + ] }, - "is_active": { - "type": "boolean", - "description": "Whether the credential is active" + "runtime_hint": { + "type": "string", + "enum": [ + "AUTO", + "CODE_MODE", + "RETAINED_RUNTIME" + ] }, - "created_at": { + "cooldown_seconds": { "type": "integer", "minimum": 0, - "description": "Unix timestamp (seconds)" + "exclusiveMinimum": true }, - "last_used_at": { - "type": "integer", - "nullable": true, - "minimum": 0, - "description": "Unix timestamp (seconds), null if never used" + "relationship_scope": { + "anyOf": [ + { + "type": "object", + "properties": { + "type": { + "type": "string", + "enum": [ + "WORKSPACE" + ] + } + }, + "required": [ + "type" + ] + }, + { + "type": "object", + "properties": { + "type": { + "type": "string", + "enum": [ + "SELLER_CUSTOMER" + ] + }, + "seller_workspace_id": { + "type": "string", + "minLength": 1, + "maxLength": 53 + }, + "customer_workspace_id": { + "type": "string", + "minLength": 1, + "maxLength": 53 + }, + "support_relationship_id": { + "type": "string", + "minLength": 1, + "maxLength": 200 + } + }, + "required": [ + "type", + "seller_workspace_id", + "customer_workspace_id" + ] + } + ] + }, + "resource_filters": { + "type": "array", + "items": { + "type": "object", + "properties": { + "type": { + "type": "string", + "minLength": 1, + "maxLength": 120 + }, + "id": { + "type": "string", + "minLength": 1, + "maxLength": 200 + } + }, + "required": [ + "type", + "id" + ] + }, + "maxItems": 50 + }, + "quiet_hours": { + "type": "object", + "properties": { + "timezone": { + "type": "string", + "minLength": 1, + "maxLength": 120 + }, + "start": { + "type": "string", + "pattern": "^\\d{2}:\\d{2}$" + }, + "end": { + "type": "string", + "pattern": "^\\d{2}:\\d{2}$" + } + }, + "required": [ + "timezone", + "start", + "end" + ] } }, "required": [ - "id", - "name", - "registry_url", + "trigger_id", "type", - "is_active", - "created_at", - "last_used_at" + "state", + "runtime_hint" ] }, - "RegistryStats": { + "AgentModelPolicy": { "type": "object", "properties": { - "total_pulls": { - "type": "number" - }, - "successful_pulls": { - "type": "number" - }, - "failed_pulls": { - "type": "number" + "default_model": { + "type": "string", + "minLength": 1, + "maxLength": 120 }, - "success_rate": { - "type": "number" + "billing_mode": { + "type": "string", + "enum": [ + "PLATFORM_SUBSCRIPTION", + "PLATFORM_API", + "WORKSPACE_BYOK" + ] }, - "auth_successes": { - "type": "number" + "credential_secret_id": { + "type": "string", + "nullable": true, + "minLength": 1, + "maxLength": 54 }, - "auth_failures": { - "type": "number" + "allowed_models": { + "type": "array", + "items": { + "type": "string", + "minLength": 1, + "maxLength": 120 + }, + "minItems": 1, + "maxItems": 50 }, - "by_registry": { + "severity_model_overrides": { "type": "array", "items": { "type": "object", "properties": { - "registry_url": { - "type": "string" - }, - "pulls": { - "type": "number" + "severity": { + "type": "string", + "enum": [ + "LOW", + "MEDIUM", + "HIGH", + "CRITICAL" + ] }, - "failures": { - "type": "number" + "model": { + "type": "string", + "minLength": 1, + "maxLength": 120 } }, "required": [ - "registry_url", - "pulls", - "failures" + "severity", + "model" ] - } - }, - "latency": { - "type": "object", - "properties": { - "avg": { - "type": "number", - "nullable": true - }, - "p95": { - "type": "number", - "nullable": true - } }, - "required": [ - "avg", - "p95" + "maxItems": 4 + }, + "max_budget_cents": { + "type": "integer", + "minimum": 0 + }, + "budget_period": { + "type": "string", + "enum": [ + "DAY", + "WEEK", + "MONTH" ] + }, + "max_turn_budget_cents": { + "type": "integer", + "minimum": 0 } }, "required": [ - "total_pulls", - "successful_pulls", - "failed_pulls", - "success_rate", - "auth_successes", - "auth_failures", - "by_registry", - "latency" + "default_model", + "billing_mode", + "credential_secret_id", + "allowed_models" ] }, - "RegistryActivityResponse": { + "AgentUsageSummary": { "type": "object", "properties": { - "data": { - "type": "array", - "items": { - "$ref": "#/components/schemas/RegistryActivityBucket" - } + "provider_cost_cents": { + "type": "integer", + "minimum": 0 + }, + "provider_token_count": { + "type": "integer", + "minimum": 0 + }, + "runtime_compute_seconds": { + "type": "number", + "minimum": 0 + }, + "runtime_storage_gb_hours": { + "type": "number", + "minimum": 0 + }, + "mcp_call_count": { + "type": "integer", + "minimum": 0 + }, + "api_call_count": { + "type": "integer", + "minimum": 0 + }, + "ambient_trigger_count": { + "type": "integer", + "minimum": 0 } }, "required": [ - "data" + "provider_cost_cents", + "provider_token_count", + "runtime_compute_seconds", + "runtime_storage_gb_hours", + "mcp_call_count", + "api_call_count", + "ambient_trigger_count" ] }, - "RegistryActivityBucket": { + "AgentList": { "type": "object", "properties": { - "timestamp": { - "type": "number", - "description": "Unix timestamp in milliseconds." + "data": { + "type": "array", + "items": { + "$ref": "#/components/schemas/Agent" + } }, - "success": { - "type": "number" + "has_more": { + "type": "boolean", + "description": "True if more items exist after this page." }, - "failed": { - "type": "number" + "next_cursor": { + "type": "string", + "nullable": true, + "description": "Opaque cursor for the next page, or null if no more pages." } }, "required": [ - "timestamp", - "success", - "failed" + "data", + "has_more", + "next_cursor" ] }, - "RegistryAuditLogList": { + "AgentSkillList": { "type": "object", "properties": { "data": { "type": "array", "items": { - "$ref": "#/components/schemas/RegistryAuditLog" + "$ref": "#/components/schemas/AgentSkill" } + }, + "has_more": { + "type": "boolean", + "description": "True if more items exist after this page." + }, + "next_cursor": { + "type": "string", + "nullable": true, + "description": "Opaque cursor for the next page, or null if no more pages." } }, "required": [ - "data" + "data", + "has_more", + "next_cursor" ] }, - "RegistryAuditLog": { + "AgentSkill": { "type": "object", "properties": { "id": { @@ -12456,189 +24939,184 @@ "minLength": 1, "maxLength": 54 }, - "timestamp": { - "type": "number", - "description": "Unix timestamp in milliseconds." - }, - "operation": { + "workspace_id": { "type": "string", - "enum": [ - "pull_manifest", - "pull_blob", - "pull_failed", - "auth_success", - "auth_failed" - ] + "minLength": 1, + "maxLength": 53 }, - "registry_url": { + "name": { "type": "string" }, - "repository": { + "version": { "type": "string" }, - "reference": { + "description": { + "type": "string" + }, + "state": { "type": "string", - "nullable": true + "enum": [ + "PUBLISHED", + "ARCHIVED" + ] }, - "success": { - "type": "boolean" + "required_grants": { + "type": "array", + "items": { + "type": "object", + "properties": { + "resource": { + "type": "string" + }, + "actions": { + "type": "array", + "items": { + "type": "string" + } + } + }, + "required": [ + "resource", + "actions" + ] + } }, - "install_name": { - "type": "string", - "nullable": true + "supported_capabilities": { + "type": "array", + "items": { + "type": "string", + "enum": [ + "CHAT", + "CODING", + "AMBIENT" + ] + } + }, + "created_at": { + "type": "integer", + "minimum": 0, + "description": "Unix timestamp (seconds)" + }, + "updated_at": { + "type": "integer", + "minimum": 0, + "description": "Unix timestamp (seconds)" + }, + "etag": { + "type": "string" } }, "required": [ "id", - "timestamp", - "operation", - "registry_url", - "repository", - "reference", - "success", - "install_name" + "workspace_id", + "name", + "version", + "description", + "state", + "required_grants", + "supported_capabilities", + "created_at", + "updated_at", + "etag" ] }, - "RegistryErrorList": { + "AgentTemplateList": { "type": "object", "properties": { "data": { "type": "array", "items": { - "$ref": "#/components/schemas/RegistryError" + "$ref": "#/components/schemas/AgentTemplate" } - } - }, - "required": [ - "data" - ] - }, - "RegistryError": { - "type": "object", - "properties": { - "message": { - "type": "string" }, - "count": { - "type": "number" + "has_more": { + "type": "boolean", + "description": "True if more items exist after this page." + }, + "next_cursor": { + "type": "string", + "nullable": true, + "description": "Opaque cursor for the next page, or null if no more pages." } }, "required": [ - "message", - "count" + "data", + "has_more", + "next_cursor" ] }, - "CreateRepositoryChangeRequestResponse": { + "AgentTemplate": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, - "maxLength": 54 - }, - "html_url": { - "type": "string", - "maxLength": 2048, - "format": "uri", - "description": "Absolute dashboard URL for this resource. OUTPUT_ONLY.", - "example": "https://akua.dev/repository-change-requests/rcr_j572abc123def456" + "maxLength": 56 }, - "workspace_id": { - "type": "string", - "minLength": 1, - "maxLength": 53 + "name": { + "type": "string" }, - "parent_repository_id": { - "type": "string", - "minLength": 1, - "maxLength": 55 + "description": { + "type": "string" }, - "fork_repository_id": { - "type": "string", - "minLength": 1, - "maxLength": 55 + "instructions": { + "type": "string" }, "state": { "type": "string", "enum": [ - "AWAITING_CHANGES", - "VALIDATING", - "READY", - "ACCEPTING", - "ACCEPTED", - "REJECTED", - "WITHDRAWN", - "EXPIRED", - "FAILED" - ], - "description": "Repository change request lifecycle state" - }, - "change_type": { - "type": "string", - "enum": [ - "manifest_patch", - "inputs_change", - "package_change", - "unknown" + "PUBLISHED" ] }, - "created_by_type": { - "type": "string", - "enum": [ - "user", - "wizard", - "agent" - ] + "capabilities": { + "type": "array", + "items": { + "type": "string", + "enum": [ + "CHAT", + "CODING", + "AMBIENT" + ] + } }, - "created_by_id": { - "type": "string" + "ambient": { + "$ref": "#/components/schemas/AgentAmbientConfig" }, - "remediation_evidence": { - "type": "object", - "nullable": true, - "properties": { - "summary": { - "type": "string", - "minLength": 1, - "maxLength": 2000 - }, - "likely_fix": { - "type": "string", - "minLength": 1, - "maxLength": 2000 - }, - "resource_refs": { - "type": "array", - "items": { - "type": "object", - "properties": { - "resource": { - "type": "string", - "minLength": 1, - "maxLength": 120 - }, - "id": { - "type": "string", - "minLength": 1, - "maxLength": 200 - } - }, - "required": [ - "resource", - "id" - ], - "additionalProperties": false + "trigger_filters": { + "type": "array", + "items": { + "$ref": "#/components/schemas/AgentTemplateTriggerFilter" + } + }, + "model_policy": { + "$ref": "#/components/schemas/AgentModelPolicy" + }, + "runtime_policy": { + "$ref": "#/components/schemas/AgentRuntimePolicy" + }, + "remediation_policy": { + "$ref": "#/components/schemas/AgentTemplateRemediationPolicy" + }, + "grants": { + "type": "array", + "items": { + "type": "object", + "properties": { + "resource": { + "type": "string" }, - "minItems": 1, - "maxItems": 20 - } - }, - "required": [ - "summary", - "likely_fix", - "resource_refs" - ], - "additionalProperties": false + "actions": { + "type": "array", + "items": { + "type": "string" + } + } + }, + "required": [ + "resource", + "actions" + ] + } }, "created_at": { "type": "integer", @@ -12650,256 +25128,273 @@ "minimum": 0, "description": "Unix timestamp (seconds)" }, - "expires_at": { - "type": "integer", - "minimum": 0, - "description": "Unix timestamp (seconds)" - }, - "rejection_reason": { - "type": "string", - "nullable": true - }, "etag": { "type": "string" } }, "required": [ "id", - "html_url", - "workspace_id", - "parent_repository_id", - "fork_repository_id", + "name", + "description", + "instructions", "state", - "change_type", - "created_by_type", - "created_by_id", - "remediation_evidence", + "capabilities", + "ambient", + "trigger_filters", + "model_policy", + "runtime_policy", + "remediation_policy", + "grants", "created_at", "updated_at", - "expires_at", - "rejection_reason", "etag" ] }, - "CreateRepositoryChangeRequestBody": { - "oneOf": [ - { - "type": "object", - "properties": { - "parent_repository_id": { - "type": "string", - "minLength": 1, - "maxLength": 55, - "description": "Repository that will receive the accepted change request." - }, - "expires_at_seconds": { - "type": "integer", - "minimum": 0, - "exclusiveMinimum": true, - "description": "Seconds until the repository change request expires." - }, - "kind": { - "type": "string", - "enum": [ - "user" - ] - } - }, - "required": [ - "parent_repository_id", - "kind" - ], - "additionalProperties": false + "AgentTemplateTriggerFilter": { + "type": "object", + "properties": { + "type": { + "type": "string", + "enum": [ + "INSTALL_STATE", + "CLUSTER_DEGRADATION", + "SECURITY_FINDING", + "QUOTA_PRESSURE", + "COST_ANOMALY", + "MANUAL_TEST" + ] }, - { - "type": "object", - "properties": { - "parent_repository_id": { - "type": "string", - "minLength": 1, - "maxLength": 55, - "description": "Repository that will receive the accepted change request." - }, - "expires_at_seconds": { - "type": "integer", - "minimum": 0, - "exclusiveMinimum": true, - "description": "Seconds until the repository change request expires." - }, - "kind": { - "type": "string", - "enum": [ - "wizard" - ] - } - }, - "required": [ - "parent_repository_id", - "kind" - ], - "additionalProperties": false + "resource_types": { + "type": "array", + "items": { + "type": "string" + } }, - { - "type": "object", - "properties": { - "parent_repository_id": { - "type": "string", - "minLength": 1, - "maxLength": 55, - "description": "Repository that will receive the accepted change request." - }, - "expires_at_seconds": { - "type": "integer", - "minimum": 0, - "exclusiveMinimum": true, - "description": "Seconds until the repository change request expires." - }, - "kind": { - "type": "string", - "enum": [ - "agent" - ], - "description": "Agent actor creating the change request." - }, - "agent_id": { - "type": "string", - "minLength": 1, - "maxLength": 54, - "description": "Agent that found the likely source or configuration fix." - }, - "remediation_evidence": { - "type": "object", - "properties": { - "summary": { - "type": "string", - "minLength": 1, - "maxLength": 2000 - }, - "likely_fix": { - "type": "string", - "minLength": 1, - "maxLength": 2000 - }, - "resource_refs": { - "type": "array", - "items": { - "type": "object", - "properties": { - "resource": { - "type": "string", - "minLength": 1, - "maxLength": 120 - }, - "id": { - "type": "string", - "minLength": 1, - "maxLength": 200 - } - }, - "required": [ - "resource", - "id" - ], - "additionalProperties": false - }, - "minItems": 1, - "maxItems": 20 - } - }, - "required": [ - "summary", - "likely_fix", - "resource_refs" - ], - "additionalProperties": false, - "description": "Evidence that the agent found a likely source or configuration fix before opening the change request." - } - }, - "required": [ - "parent_repository_id", - "kind", - "agent_id", - "remediation_evidence" - ], - "additionalProperties": false + "states": { + "type": "array", + "items": { + "type": "string" + } + }, + "min_severity": { + "type": "string", + "enum": [ + "LOW", + "MEDIUM", + "HIGH", + "CRITICAL" + ] } + }, + "required": [ + "type", + "resource_types", + "states" ] }, - "CreateRepositoryChangeRequestTokenResponse": { + "AgentRuntimePolicy": { "type": "object", "properties": { - "repository_change_request_id": { + "execution_environment": { "type": "string", - "minLength": 1, - "maxLength": 54 + "enum": [ + "CODE_MODE_FIRST", + "RETAINED_RUNTIME_ALLOWED", + "NO_RETAINED_RUNTIME" + ] }, - "fork_remote_url": { - "type": "string", - "format": "uri" + "filesystem": { + "type": "string" }, - "fork_write_token": { + "shell": { "type": "string" }, - "expires_at": { - "type": "integer", - "minimum": 0, - "description": "Unix timestamp (seconds)" + "browser": { + "type": "string" } }, "required": [ - "repository_change_request_id", - "fork_remote_url", - "fork_write_token", - "expires_at" + "execution_environment", + "filesystem", + "shell", + "browser" ] }, - "CreateRepositoryChangeRequestTokenBody": { + "AgentTemplateRemediationPolicy": { "type": "object", + "nullable": true, "properties": { - "scope": { + "repository_change_request": { + "$ref": "#/components/schemas/AgentTemplateRepositoryChangeRequestRemediationPolicy" + } + }, + "required": [ + "repository_change_request" + ] + }, + "AgentTemplateRepositoryChangeRequestRemediationPolicy": { + "type": "object", + "properties": { + "mode": { "type": "string", "enum": [ - "read", - "write" - ], - "default": "write" + "LIKELY_SOURCE_OR_CONFIG_FIX_ONLY" + ] }, - "expires_in_seconds": { + "evidence_required": { + "type": "boolean" + }, + "allowed_actions": { + "type": "array", + "items": { + "type": "string" + } + }, + "blocked_actions": { + "type": "array", + "items": { + "type": "string" + } + } + }, + "required": [ + "mode", + "evidence_required", + "allowed_actions", + "blocked_actions" + ] + }, + "AgentPreference": { + "type": "object", + "properties": { + "id": { + "type": "string", + "minLength": 1, + "maxLength": 54 + }, + "workspace_id": { + "type": "string", + "minLength": 1, + "maxLength": 53 + }, + "user_id": { + "type": "string" + }, + "communication_profile": { + "type": "string", + "enum": [ + "BEGINNER", + "INTERMEDIATE", + "ADVANCED", + "EXPERT", + "ADAPTIVE" + ] + }, + "learning_mode_enabled": { + "type": "boolean" + }, + "seen_concepts": { + "type": "array", + "items": { + "type": "string" + } + }, + "created_at": { "type": "integer", "minimum": 0, - "exclusiveMinimum": true, - "maximum": 3600, - "description": "Seconds until the fork write token expires. Maximum is one hour." + "description": "Unix timestamp (seconds)" + }, + "updated_at": { + "type": "integer", + "minimum": 0, + "description": "Unix timestamp (seconds)" + }, + "etag": { + "type": "string" } }, - "additionalProperties": false + "required": [ + "id", + "workspace_id", + "user_id", + "communication_profile", + "learning_mode_enabled", + "seen_concepts", + "created_at", + "updated_at", + "etag" + ] }, - "RepositoryChangeRequestList": { + "SandboxOperationsSummary": { "type": "object", "properties": { - "data": { + "active_sandbox_count": { + "type": "integer", + "minimum": 0 + }, + "idle_retained_filesystem_count": { + "type": "integer", + "minimum": 0 + }, + "retained_filesystem_age_ms": { + "type": "number", + "minimum": 0 + }, + "estimated_retained_filesystem_gb_hours": { + "type": "number", + "minimum": 0 + }, + "stuck_sandbox_count_by_state": { "type": "array", "items": { - "$ref": "#/components/schemas/RepositoryChangeRequest" + "type": "object", + "properties": { + "state": { + "type": "string", + "enum": [ + "CREATING", + "STARTING", + "ACTIVE", + "STOPPING", + "STOPPED", + "DELETING", + "DELETED", + "FAILED" + ] + }, + "count": { + "type": "integer", + "minimum": 0 + } + }, + "required": [ + "state", + "count" + ] } }, - "has_more": { - "type": "boolean", - "description": "True if more items exist after this page." + "average_cold_start_latency_ms": { + "type": "number", + "nullable": true, + "minimum": 0 }, - "next_cursor": { - "type": "string", + "average_resume_latency_ms": { + "type": "number", "nullable": true, - "description": "Opaque cursor for the next page, or null if no more pages." + "minimum": 0 } }, "required": [ - "data", - "has_more", - "next_cursor" + "active_sandbox_count", + "idle_retained_filesystem_count", + "retained_filesystem_age_ms", + "estimated_retained_filesystem_gb_hours", + "stuck_sandbox_count_by_state", + "average_cold_start_latency_ms", + "average_resume_latency_ms" ] }, - "RepositoryChangeRequest": { + "AgentSession": { "type": "object", "properties": { "id": { @@ -12907,128 +25402,119 @@ "minLength": 1, "maxLength": 54 }, - "html_url": { - "type": "string", - "maxLength": 2048, - "format": "uri", - "description": "Absolute dashboard URL for this resource. OUTPUT_ONLY.", - "example": "https://akua.dev/repository-change-requests/rcr_j572abc123def456" - }, "workspace_id": { "type": "string", "minLength": 1, "maxLength": 53 }, - "parent_repository_id": { + "organization_id": { "type": "string", + "nullable": true, "minLength": 1, - "maxLength": 55 + "maxLength": 54 }, - "fork_repository_id": { + "agent_id": { "type": "string", "minLength": 1, - "maxLength": 55 + "maxLength": 54 }, "state": { "type": "string", "enum": [ - "AWAITING_CHANGES", - "VALIDATING", - "READY", - "ACCEPTING", - "ACCEPTED", - "REJECTED", - "WITHDRAWN", - "EXPIRED", - "FAILED" - ], - "description": "Repository change request lifecycle state" + "ACTIVE", + "WAITING_FOR_INPUT", + "WAITING_FOR_PERMISSION", + "COMPLETED", + "FAILED", + "CANCELLED", + "ARCHIVED" + ] }, - "change_type": { + "origin": { "type": "string", "enum": [ - "manifest_patch", - "inputs_change", - "package_change", - "unknown" + "DASHBOARD", + "API", + "MCP", + "ACP", + "AMBIENT", + "SYSTEM" ] }, - "created_by_type": { + "title": { + "type": "string", + "nullable": true + }, + "communication_profile": { "type": "string", "enum": [ - "user", - "wizard", - "agent" + "BEGINNER", + "INTERMEDIATE", + "ADVANCED", + "EXPERT", + "ADAPTIVE" ] }, - "created_by_id": { + "created_by": { "type": "string" }, - "remediation_evidence": { - "type": "object", + "parent_session_id": { + "type": "string", "nullable": true, - "properties": { - "summary": { - "type": "string", - "minLength": 1, - "maxLength": 2000 - }, - "likely_fix": { - "type": "string", - "minLength": 1, - "maxLength": 2000 - }, - "resource_refs": { - "type": "array", - "items": { - "type": "object", - "properties": { - "resource": { - "type": "string", - "minLength": 1, - "maxLength": 120 - }, - "id": { - "type": "string", - "minLength": 1, - "maxLength": 200 - } - }, - "required": [ - "resource", - "id" - ], - "additionalProperties": false - }, - "minItems": 1, - "maxItems": 20 - } - }, - "required": [ - "summary", - "likely_fix", - "resource_refs" - ], - "additionalProperties": false + "minLength": 1, + "maxLength": 54 }, - "created_at": { + "forked_from_session_id": { + "type": "string", + "nullable": true, + "minLength": 1, + "maxLength": 54 + }, + "spawned_by_turn_id": { + "type": "string", + "nullable": true, + "minLength": 1, + "maxLength": 54 + }, + "agent_role": { + "type": "string", + "nullable": true + }, + "current_sandbox_id": { + "type": "string", + "nullable": true, + "minLength": 1, + "maxLength": 54 + }, + "last_event_cursor": { + "type": "string", + "nullable": true + }, + "events_retained_until": { "type": "integer", "minimum": 0, "description": "Unix timestamp (seconds)" }, - "updated_at": { + "filesystem_retained_until": { "type": "integer", "minimum": 0, "description": "Unix timestamp (seconds)" }, - "expires_at": { + "filesystem_pinned": { + "type": "boolean" + }, + "usage_summary": { + "$ref": "#/components/schemas/AgentUsageSummary" + }, + "created_at": { "type": "integer", "minimum": 0, "description": "Unix timestamp (seconds)" }, - "rejection_reason": { - "type": "string", - "nullable": true + "updated_at": { + "type": "integer", + "minimum": 0, + "description": "Unix timestamp (seconds)" }, "etag": { "type": "string" @@ -13036,101 +25522,166 @@ }, "required": [ "id", - "html_url", "workspace_id", - "parent_repository_id", - "fork_repository_id", + "organization_id", + "agent_id", "state", - "change_type", - "created_by_type", - "created_by_id", - "remediation_evidence", + "origin", + "title", + "communication_profile", + "created_by", + "parent_session_id", + "forked_from_session_id", + "spawned_by_turn_id", + "agent_role", + "current_sandbox_id", + "last_event_cursor", + "events_retained_until", + "filesystem_retained_until", + "filesystem_pinned", + "usage_summary", "created_at", "updated_at", - "expires_at", - "rejection_reason", "etag" ] }, - "AcceptRepositoryChangeRequestResponse": { + "AgentSessionList": { "type": "object", "properties": { - "repository_change_request_id": { - "type": "string", - "minLength": 1, - "maxLength": 54 + "data": { + "type": "array", + "items": { + "$ref": "#/components/schemas/AgentSession" + } }, - "operation_id": { - "type": "string", - "minLength": 1, - "maxLength": 53 + "has_more": { + "type": "boolean", + "description": "True if more items exist after this page." }, - "accepted_at": { - "type": "integer", - "minimum": 0, - "description": "Unix timestamp (seconds)" + "next_cursor": { + "type": "string", + "nullable": true, + "description": "Opaque cursor for the next page, or null if no more pages." } }, "required": [ - "repository_change_request_id", - "operation_id", - "accepted_at" + "data", + "has_more", + "next_cursor" ] }, - "RejectRepositoryChangeRequestResponse": { + "AgentWorkConflictList": { "type": "object", "properties": { - "repository_change_request_id": { - "type": "string", - "minLength": 1, - "maxLength": 54 - }, - "rejected_at": { - "type": "integer", - "minimum": 0, - "description": "Unix timestamp (seconds)" + "data": { + "type": "array", + "items": { + "$ref": "#/components/schemas/AgentWorkConflict" + } } }, "required": [ - "repository_change_request_id", - "rejected_at" - ] + "data" + ], + "additionalProperties": false }, - "RejectRepositoryChangeRequestBody": { + "AgentWorkConflict": { "type": "object", "properties": { - "rejection_reason": { + "agent_id": { "type": "string", "minLength": 1, - "maxLength": 2000, - "description": "Reason shown in audit logs and review UI." + "maxLength": 54 + }, + "session_id": { + "type": "string", + "minLength": 1, + "maxLength": 54 + }, + "turn_id": { + "type": "string", + "minLength": 1, + "maxLength": 54 + }, + "event_id": { + "type": "string", + "minLength": 1, + "maxLength": 54 + }, + "event_type": { + "type": "string", + "enum": [ + "message.created", + "widget.created", + "artifact.created", + "progress.updated", + "execution_environment.started", + "execution_environment.stopped", + "execution_environment.resumed", + "execution_environment.deleted", + "execution_environment.failed", + "handoff_summary.created", + "turn.cancelled" + ] + }, + "reason": { + "type": "string", + "minLength": 1, + "maxLength": 500 + }, + "created_at": { + "type": "integer", + "minimum": 0, + "description": "Unix timestamp (seconds)" } }, "required": [ - "rejection_reason" + "agent_id", + "session_id", + "turn_id", + "event_id", + "event_type", + "reason", + "created_at" ], "additionalProperties": false }, - "WithdrawRepositoryChangeRequestResponse": { + "SetAgentSessionRetentionBody": { "type": "object", "properties": { - "repository_change_request_id": { - "type": "string", - "minLength": 1, - "maxLength": 54 + "events_retained_until": { + "type": "integer", + "minimum": 0, + "description": "Unix timestamp (seconds)" }, - "withdrawn_at": { + "filesystem_retained_until": { "type": "integer", "minimum": 0, "description": "Unix timestamp (seconds)" + }, + "filesystem_pinned": { + "type": "boolean" + }, + "retention_reason": { + "type": "string", + "enum": [ + "SESSION_ACTIVE", + "PINNED", + "POLICY", + "TERMINAL_GRACE", + "MANUAL_DELETE" + ] } }, "required": [ - "repository_change_request_id", - "withdrawn_at" - ] + "events_retained_until", + "filesystem_retained_until", + "filesystem_pinned", + "retention_reason" + ], + "additionalProperties": false }, - "Agent": { + "AgentTurn": { "type": "object", "properties": { "id": { @@ -13149,54 +25700,142 @@ "minLength": 1, "maxLength": 54 }, - "name": { - "type": "string" - }, - "description": { + "agent_id": { "type": "string", - "nullable": true + "minLength": 1, + "maxLength": 54 }, - "instructions": { - "type": "string" + "session_id": { + "type": "string", + "minLength": 1, + "maxLength": 54 }, "state": { "type": "string", "enum": [ - "ENABLED", - "ARCHIVED" + "QUEUED", + "RUNNING", + "WAITING_FOR_INPUT", + "WAITING_FOR_PERMISSION", + "COMPLETED", + "FAILED", + "CANCELLED" ] }, "origin": { "type": "string", "enum": [ - "PLATFORM", - "USER", + "DASHBOARD", + "API", + "MCP", + "ACP", + "AMBIENT", "SYSTEM" ] }, - "capabilities": { - "type": "array", - "items": { - "type": "string", - "enum": [ - "CHAT", - "CODING", - "AMBIENT" - ] - } + "input": { + "type": "object", + "properties": { + "type": { + "type": "string", + "enum": [ + "message" + ] + }, + "content": { + "type": "string" + } + }, + "required": [ + "type", + "content" + ] }, - "ambient": { - "$ref": "#/components/schemas/AgentAmbientConfig" + "runtime_hint": { + "type": "string", + "enum": [ + "AUTO", + "CODE_MODE", + "RETAINED_RUNTIME" + ] }, - "model_policy": { - "$ref": "#/components/schemas/AgentModelPolicy" + "model": { + "type": "string", + "nullable": true }, "created_by": { "type": "string" }, + "started_at": { + "type": "integer", + "nullable": true, + "minimum": 0, + "description": "Unix timestamp (seconds)" + }, + "completed_at": { + "type": "integer", + "nullable": true, + "minimum": 0, + "description": "Unix timestamp (seconds)" + }, + "runtime_decision": { + "type": "string", + "nullable": true, + "enum": [ + "ALLOWED", + "DENIED", + "APPROVAL_REQUIRED", + null + ] + }, + "decision_reason": { + "type": "string", + "nullable": true + }, + "resolved_execution_mode": { + "type": "string", + "nullable": true, + "enum": [ + "CODE_MODE", + "RETAINED_RUNTIME", + null + ] + }, + "admission_error": { + "type": "object", + "nullable": true, + "properties": { + "code": { + "type": "string" + }, + "message": { + "type": "string" + } + }, + "required": [ + "code", + "message" + ] + }, "usage_summary": { "$ref": "#/components/schemas/AgentUsageSummary" }, + "failure": { + "type": "object", + "nullable": true, + "properties": { + "code": { + "type": "string" + }, + "message": { + "type": "string" + } + }, + "required": [ + "code", + "message" + ] + }, "created_at": { "type": "integer", "minimum": 0, @@ -13215,397 +25854,500 @@ "id", "workspace_id", "organization_id", - "name", - "description", - "instructions", + "agent_id", + "session_id", "state", "origin", - "capabilities", - "ambient", - "model_policy", + "input", + "runtime_hint", + "model", "created_by", + "started_at", + "completed_at", + "runtime_decision", + "decision_reason", + "resolved_execution_mode", + "admission_error", "usage_summary", + "failure", "created_at", "updated_at", "etag" ] }, - "AgentAmbientConfig": { + "AgentTurnList": { "type": "object", - "nullable": true, "properties": { - "enabled": { - "type": "boolean" - }, - "policy": { - "$ref": "#/components/schemas/AgentAmbientPolicy" - }, - "triggers": { + "data": { "type": "array", "items": { - "$ref": "#/components/schemas/AgentAmbientTrigger" - }, - "maxItems": 50 + "$ref": "#/components/schemas/AgentTurn" + } + }, + "has_more": { + "type": "boolean", + "description": "True if more items exist after this page." + }, + "next_cursor": { + "type": "string", + "nullable": true, + "description": "Opaque cursor for the next page, or null if no more pages." } }, "required": [ - "enabled", - "triggers" + "data", + "has_more", + "next_cursor" ] }, - "AgentAmbientPolicy": { + "AgentEvent": { "type": "object", "properties": { - "remediation_mode": { + "id": { + "type": "string", + "minLength": 1, + "maxLength": 54 + }, + "workspace_id": { + "type": "string", + "minLength": 1, + "maxLength": 53 + }, + "agent_id": { + "type": "string", + "minLength": 1, + "maxLength": 54 + }, + "session_id": { + "type": "string", + "minLength": 1, + "maxLength": 54 + }, + "turn_id": { + "type": "string", + "minLength": 1, + "maxLength": 54 + }, + "sequence": { + "type": "integer" + }, + "cursor": { + "type": "string" + }, + "type": { "type": "string", "enum": [ - "READ_ONLY", - "APPROVAL_GATED" + "message.created", + "widget.created", + "artifact.created", + "progress.updated", + "execution_environment.started", + "execution_environment.stopped", + "execution_environment.resumed", + "execution_environment.deleted", + "execution_environment.failed", + "handoff_summary.created", + "turn.cancelled" ] }, - "allowed_resource_scopes": { - "type": "array", - "items": { - "$ref": "#/components/schemas/AgentAmbientResourceScope" - }, - "maxItems": 100 - }, - "max_spend_cents_per_trigger": { + "created_at": { "type": "integer", - "minimum": 0 + "minimum": 0, + "description": "Unix timestamp (seconds)" + }, + "data": { + "nullable": true } }, "required": [ - "remediation_mode", - "allowed_resource_scopes" + "id", + "workspace_id", + "agent_id", + "session_id", + "turn_id", + "sequence", + "cursor", + "type", + "created_at" ] }, - "AgentAmbientResourceScope": { + "AgentProviderExchangeList": { "type": "object", "properties": { - "type": { - "type": "string", - "minLength": 1, - "maxLength": 120 + "data": { + "type": "array", + "items": { + "$ref": "#/components/schemas/AgentProviderExchange" + } }, - "id": { + "has_more": { + "type": "boolean", + "description": "True if more items exist after this page." + }, + "next_cursor": { "type": "string", - "minLength": 1, - "maxLength": 200 + "nullable": true, + "description": "Opaque cursor for the next page, or null if no more pages." } }, "required": [ - "type" + "data", + "has_more", + "next_cursor" ] }, - "AgentAmbientTrigger": { + "AgentProviderExchange": { "type": "object", "properties": { - "trigger_id": { + "id": { "type": "string", "minLength": 1, - "maxLength": 120 + "maxLength": 54 }, - "type": { + "workspace_id": { "type": "string", - "enum": [ - "INSTALL_STATE", - "CLUSTER_DEGRADATION", - "SECURITY_FINDING", - "QUOTA_PRESSURE", - "COST_ANOMALY", - "MANUAL_TEST" - ] + "minLength": 1, + "maxLength": 53 }, - "state": { + "organization_id": { "type": "string", - "enum": [ - "ENABLED", - "DISABLED" - ] + "nullable": true, + "minLength": 1, + "maxLength": 54 }, - "severity_min": { + "agent_id": { "type": "string", - "enum": [ - "LOW", - "MEDIUM", - "HIGH", - "CRITICAL" - ] + "minLength": 1, + "maxLength": 54 }, - "runtime_hint": { + "session_id": { + "type": "string", + "minLength": 1, + "maxLength": 54 + }, + "turn_id": { + "type": "string", + "minLength": 1, + "maxLength": 54 + }, + "provider": { + "type": "string" + }, + "model": { + "type": "string", + "nullable": true + }, + "fallback_from_model": { + "type": "string", + "nullable": true + }, + "fallback_reason": { + "type": "string", + "nullable": true + }, + "credential_mode": { "type": "string", "enum": [ - "AUTO", - "CODE_MODE", - "RETAINED_RUNTIME" + "PLATFORM_SUBSCRIPTION", + "PLATFORM_API", + "WORKSPACE_BYOK" ] }, - "cooldown_seconds": { + "credential_secret_id": { + "type": "string", + "nullable": true, + "minLength": 1, + "maxLength": 54 + }, + "requested_at": { "type": "integer", "minimum": 0, - "exclusiveMinimum": true + "description": "Unix timestamp (seconds)" }, - "relationship_scope": { - "anyOf": [ - { - "type": "object", - "properties": { - "type": { - "type": "string", - "enum": [ - "WORKSPACE" - ] - } - }, - "required": [ - "type" - ] + "responded_at": { + "type": "integer", + "minimum": 0, + "description": "Unix timestamp (seconds)" + }, + "provider_cost_cents": { + "type": "integer", + "minimum": 0 + }, + "provider_token_count": { + "type": "integer", + "minimum": 0 + }, + "token_counts": { + "type": "object", + "nullable": true, + "properties": { + "input": { + "type": "integer", + "minimum": 0 }, - { - "type": "object", - "properties": { - "type": { - "type": "string", - "enum": [ - "SELLER_CUSTOMER" - ] - }, - "seller_workspace_id": { - "type": "string", - "minLength": 1, - "maxLength": 53 - }, - "customer_workspace_id": { - "type": "string", - "minLength": 1, - "maxLength": 53 - }, - "support_relationship_id": { - "type": "string", - "minLength": 1, - "maxLength": 200 - } - }, - "required": [ - "type", - "seller_workspace_id", - "customer_workspace_id" - ] + "output": { + "type": "integer", + "minimum": 0 + }, + "total": { + "type": "integer", + "minimum": 0 } - ] + } + }, + "message_summary": { + "type": "string", + "nullable": true + }, + "upstream_error_code": { + "type": "string", + "nullable": true + }, + "created_at": { + "type": "integer", + "minimum": 0, + "description": "Unix timestamp (seconds)" + } + }, + "required": [ + "id", + "workspace_id", + "organization_id", + "agent_id", + "session_id", + "turn_id", + "provider", + "model", + "fallback_from_model", + "fallback_reason", + "credential_mode", + "credential_secret_id", + "requested_at", + "responded_at", + "provider_cost_cents", + "provider_token_count", + "token_counts", + "message_summary", + "upstream_error_code", + "created_at" + ] + }, + "AgentEventList": { + "type": "object", + "properties": { + "data": { + "type": "array", + "items": { + "$ref": "#/components/schemas/AgentEvent" + } }, - "resource_filters": { + "has_more": { + "type": "boolean", + "description": "True if more items exist after this page." + }, + "next_cursor": { + "type": "string", + "nullable": true, + "description": "Opaque cursor for the next page, or null if no more pages." + } + }, + "required": [ + "data", + "has_more", + "next_cursor" + ] + }, + "ApprovalRequestList": { + "type": "object", + "properties": { + "data": { "type": "array", "items": { - "type": "object", - "properties": { - "type": { - "type": "string", - "minLength": 1, - "maxLength": 120 - }, - "id": { - "type": "string", - "minLength": 1, - "maxLength": 200 - } - }, - "required": [ - "type", - "id" - ] - }, - "maxItems": 50 + "$ref": "#/components/schemas/ApprovalRequest" + } }, - "quiet_hours": { - "type": "object", - "properties": { - "timezone": { - "type": "string", - "minLength": 1, - "maxLength": 120 - }, - "start": { - "type": "string", - "pattern": "^\\d{2}:\\d{2}$" - }, - "end": { - "type": "string", - "pattern": "^\\d{2}:\\d{2}$" - } - }, - "required": [ - "timezone", - "start", - "end" - ] + "has_more": { + "type": "boolean", + "description": "True if more items exist after this page." + }, + "next_cursor": { + "type": "string", + "nullable": true, + "description": "Opaque cursor for the next page, or null if no more pages." } }, "required": [ - "trigger_id", - "type", - "state", - "runtime_hint" + "data", + "has_more", + "next_cursor" ] }, - "AgentModelPolicy": { + "ApprovalRequest": { "type": "object", "properties": { - "default_model": { + "id": { "type": "string", "minLength": 1, - "maxLength": 120 + "maxLength": 54 }, - "billing_mode": { + "workspace_id": { "type": "string", - "enum": [ - "PLATFORM_SUBSCRIPTION", - "PLATFORM_API", - "WORKSPACE_BYOK" - ] + "minLength": 1, + "maxLength": 53 }, - "credential_secret_id": { + "agent_id": { "type": "string", - "nullable": true, "minLength": 1, "maxLength": 54 }, - "allowed_models": { - "type": "array", - "items": { - "type": "string", - "minLength": 1, - "maxLength": 120 - }, - "minItems": 1, - "maxItems": 50 + "session_id": { + "type": "string", + "minLength": 1, + "maxLength": 54 }, - "severity_model_overrides": { + "turn_id": { + "type": "string", + "minLength": 1, + "maxLength": 54 + }, + "state": { + "type": "string", + "enum": [ + "PENDING", + "APPROVED", + "REJECTED" + ] + }, + "title": { + "type": "string" + }, + "summary": { + "type": "string" + }, + "actions": { "type": "array", "items": { - "type": "object", - "properties": { - "severity": { - "type": "string", - "enum": [ - "LOW", - "MEDIUM", - "HIGH", - "CRITICAL" - ] - }, - "model": { - "type": "string", - "minLength": 1, - "maxLength": 120 - } - }, - "required": [ - "severity", - "model" - ] + "nullable": true }, - "maxItems": 4 + "default": [] }, - "max_budget_cents": { - "type": "integer", - "minimum": 0 + "created_by": { + "type": "string" }, - "budget_period": { - "type": "string", - "enum": [ - "DAY", - "WEEK", - "MONTH" - ] + "created_at": { + "type": "integer", + "minimum": 0, + "description": "Unix timestamp (seconds)" }, - "max_turn_budget_cents": { + "updated_at": { "type": "integer", - "minimum": 0 + "minimum": 0, + "description": "Unix timestamp (seconds)" + }, + "etag": { + "type": "string" } }, "required": [ - "default_model", - "billing_mode", - "credential_secret_id", - "allowed_models" + "id", + "workspace_id", + "agent_id", + "session_id", + "turn_id", + "state", + "title", + "summary", + "created_by", + "created_at", + "updated_at", + "etag" ] }, - "AgentUsageSummary": { + "WorkspaceSubdomain": { "type": "object", "properties": { - "provider_cost_cents": { - "type": "integer", - "minimum": 0 + "id": { + "type": "string", + "minLength": 1, + "maxLength": 54 }, - "provider_token_count": { - "type": "integer", - "minimum": 0 + "workspace_id": { + "type": "string", + "minLength": 1, + "maxLength": 53 }, - "runtime_compute_seconds": { - "type": "number", - "minimum": 0 + "name": { + "type": "string", + "minLength": 1, + "maxLength": 63 }, - "runtime_storage_gb_hours": { - "type": "number", - "minimum": 0 + "fqdn": { + "type": "string", + "minLength": 1, + "maxLength": 253 }, - "mcp_call_count": { + "status": { + "type": "string", + "enum": [ + "active", + "propagating", + "reserved" + ], + "description": "Current workspace subdomain lifecycle state." + }, + "name_changed_at": { "type": "integer", - "minimum": 0 + "nullable": true, + "minimum": 0, + "description": "Unix timestamp (seconds)" }, - "api_call_count": { + "created_at": { "type": "integer", - "minimum": 0 + "minimum": 0, + "description": "Unix timestamp (seconds)" }, - "ambient_trigger_count": { + "updated_at": { "type": "integer", - "minimum": 0 + "minimum": 0, + "description": "Unix timestamp (seconds)" + }, + "etag": { + "type": "string" } }, "required": [ - "provider_cost_cents", - "provider_token_count", - "runtime_compute_seconds", - "runtime_storage_gb_hours", - "mcp_call_count", - "api_call_count", - "ambient_trigger_count" + "id", + "workspace_id", + "name", + "fqdn", + "status", + "name_changed_at", + "created_at", + "updated_at", + "etag" ] }, - "AgentList": { + "SetWorkspaceSubdomainNameBody": { "type": "object", "properties": { - "data": { - "type": "array", - "items": { - "$ref": "#/components/schemas/Agent" - } - }, - "has_more": { - "type": "boolean", - "description": "True if more items exist after this page." - }, - "next_cursor": { + "name": { "type": "string", - "nullable": true, - "description": "Opaque cursor for the next page, or null if no more pages." + "minLength": 1, + "maxLength": 63 } }, "required": [ - "data", - "has_more", - "next_cursor" - ] + "name" + ], + "additionalProperties": false }, - "AgentSkillList": { + "PreviewHostnameList": { "type": "object", "properties": { "data": { "type": "array", "items": { - "$ref": "#/components/schemas/AgentSkill" + "$ref": "#/components/schemas/PreviewHostname" } }, "has_more": { @@ -13624,7 +26366,7 @@ "next_cursor" ] }, - "AgentSkill": { + "PreviewHostname": { "type": "object", "properties": { "id": { @@ -13637,53 +26379,100 @@ "minLength": 1, "maxLength": 53 }, - "name": { - "type": "string" + "install_id": { + "type": "string", + "minLength": 1, + "maxLength": 55 }, - "version": { - "type": "string" + "hostname": { + "type": "string", + "minLength": 1, + "maxLength": 253 }, - "description": { - "type": "string" + "protocol": { + "type": "string", + "enum": [ + "http", + "websocket", + "grpc" + ], + "description": "Transport class for route forwarding." }, - "state": { + "routing_mode": { "type": "string", "enum": [ - "PUBLISHED", - "ARCHIVED" - ] + "through_dispatcher", + "bypass_dispatcher" + ], + "description": "Whether traffic uses the dispatcher Worker or bypasses it." }, - "required_grants": { - "type": "array", - "items": { - "type": "object", - "properties": { - "resource": { - "type": "string" - }, - "actions": { - "type": "array", - "items": { - "type": "string" + "binding": { + "oneOf": [ + { + "type": "object", + "properties": { + "kind": { + "type": "string", + "enum": [ + "pinned" + ] + }, + "render_id": { + "type": "string", + "minLength": 1, + "maxLength": 54 } - } + }, + "required": [ + "kind", + "render_id" + ], + "additionalProperties": false }, - "required": [ - "resource", - "actions" - ] - } + { + "type": "object", + "properties": { + "kind": { + "type": "string", + "enum": [ + "floating" + ] + }, + "track": { + "type": "string", + "minLength": 1, + "maxLength": 100 + }, + "render_id": { + "type": "string", + "minLength": 1, + "maxLength": 54 + } + }, + "required": [ + "kind", + "track", + "render_id" + ], + "additionalProperties": false + } + ] }, - "supported_capabilities": { - "type": "array", - "items": { - "type": "string", - "enum": [ - "CHAT", - "CODING", - "AMBIENT" - ] - } + "status": { + "type": "string", + "enum": [ + "provisioning", + "active", + "evicted", + "releasing" + ], + "description": "Current preview hostname lifecycle state." + }, + "last_seen_at": { + "type": "integer", + "nullable": true, + "minimum": 0, + "description": "Unix timestamp (seconds)" }, "created_at": { "type": "integer", @@ -13702,24 +26491,97 @@ "required": [ "id", "workspace_id", - "name", - "version", - "description", - "state", - "required_grants", - "supported_capabilities", + "install_id", + "hostname", + "protocol", + "routing_mode", + "binding", + "status", + "last_seen_at", "created_at", "updated_at", "etag" ] }, - "AgentTemplateList": { + "BindPinnedPreviewHostnameBody": { + "type": "object", + "properties": { + "render_id": { + "type": "string", + "minLength": 1, + "maxLength": 54 + }, + "protocol": { + "type": "string", + "enum": [ + "http", + "websocket", + "grpc" + ], + "default": "http", + "description": "Transport class for route forwarding." + }, + "routing_mode": { + "type": "string", + "enum": [ + "through_dispatcher", + "bypass_dispatcher" + ], + "default": "through_dispatcher", + "description": "Whether traffic uses the dispatcher Worker or bypasses it." + } + }, + "required": [ + "render_id" + ], + "additionalProperties": false + }, + "BindFloatingPreviewHostnameBody": { + "type": "object", + "properties": { + "track": { + "type": "string", + "minLength": 1, + "maxLength": 100 + }, + "render_id": { + "type": "string", + "minLength": 1, + "maxLength": 54 + }, + "protocol": { + "type": "string", + "enum": [ + "http", + "websocket", + "grpc" + ], + "default": "http", + "description": "Transport class for route forwarding." + }, + "routing_mode": { + "type": "string", + "enum": [ + "through_dispatcher", + "bypass_dispatcher" + ], + "default": "through_dispatcher", + "description": "Whether traffic uses the dispatcher Worker or bypasses it." + } + }, + "required": [ + "track", + "render_id" + ], + "additionalProperties": false + }, + "CustomDomainList": { "type": "object", "properties": { "data": { "type": "array", "items": { - "$ref": "#/components/schemas/AgentTemplate" + "$ref": "#/components/schemas/CustomDomain" } }, "has_more": { @@ -13738,78 +26600,145 @@ "next_cursor" ] }, - "AgentTemplate": { + "CustomDomain": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, - "maxLength": 56 + "maxLength": 54 }, - "name": { - "type": "string" + "workspace_id": { + "type": "string", + "minLength": 1, + "maxLength": 53 }, - "description": { - "type": "string" + "hostname": { + "type": "string", + "minLength": 1, + "maxLength": 253 }, - "instructions": { - "type": "string" + "target": { + "oneOf": [ + { + "type": "object", + "properties": { + "kind": { + "type": "string", + "enum": [ + "install" + ] + }, + "install_id": { + "type": "string", + "minLength": 1, + "maxLength": 55 + } + }, + "required": [ + "kind", + "install_id" + ], + "additionalProperties": false + }, + { + "type": "object", + "properties": { + "kind": { + "type": "string", + "enum": [ + "cluster" + ] + }, + "cluster_id": { + "type": "string", + "minLength": 1, + "maxLength": 54 + } + }, + "required": [ + "kind", + "cluster_id" + ], + "additionalProperties": false + }, + { + "type": "object", + "properties": { + "kind": { + "type": "string", + "enum": [ + "external" + ] + }, + "endpoint": { + "type": "string", + "format": "uri" + }, + "mtls_secret_id": { + "type": "string", + "minLength": 1, + "maxLength": 54 + } + }, + "required": [ + "kind", + "endpoint" + ], + "additionalProperties": false + } + ] }, - "state": { + "protocol": { "type": "string", "enum": [ - "PUBLISHED" - ] - }, - "capabilities": { - "type": "array", - "items": { - "type": "string", - "enum": [ - "CHAT", - "CODING", - "AMBIENT" - ] - } - }, - "ambient": { - "$ref": "#/components/schemas/AgentAmbientConfig" - }, - "trigger_filters": { - "type": "array", - "items": { - "$ref": "#/components/schemas/AgentTemplateTriggerFilter" - } - }, - "model_policy": { - "$ref": "#/components/schemas/AgentModelPolicy" - }, - "runtime_policy": { - "$ref": "#/components/schemas/AgentRuntimePolicy" + "http", + "websocket", + "grpc" + ], + "description": "Transport class for route forwarding." }, - "remediation_policy": { - "$ref": "#/components/schemas/AgentTemplateRemediationPolicy" + "routing_mode": { + "type": "string", + "enum": [ + "through_dispatcher", + "bypass_dispatcher" + ], + "description": "Whether traffic uses the dispatcher Worker or bypasses it." }, - "grants": { - "type": "array", - "items": { - "type": "object", - "properties": { - "resource": { - "type": "string" - }, - "actions": { - "type": "array", - "items": { + "ssl": { + "type": "object", + "properties": { + "status": { + "type": "string", + "enum": [ + "pending_validation", + "active", + "failed" + ] + }, + "validation_records": { + "type": "array", + "items": { + "type": "object", + "additionalProperties": { "type": "string" } } - }, - "required": [ - "resource", - "actions" - ] - } + } + }, + "required": [ + "status" + ] + }, + "status": { + "type": "string", + "enum": [ + "provisioning", + "active", + "failed", + "releasing" + ] }, "created_at": { "type": "integer", @@ -13827,4377 +26756,6898 @@ }, "required": [ "id", - "name", - "description", - "instructions", - "state", - "capabilities", - "ambient", - "trigger_filters", - "model_policy", - "runtime_policy", - "remediation_policy", - "grants", + "workspace_id", + "hostname", + "target", + "protocol", + "routing_mode", + "ssl", + "status", "created_at", "updated_at", "etag" ] }, - "AgentTemplateTriggerFilter": { + "CreateCustomDomainBody": { "type": "object", "properties": { - "type": { + "hostname": { "type": "string", - "enum": [ - "INSTALL_STATE", - "CLUSTER_DEGRADATION", - "SECURITY_FINDING", - "QUOTA_PRESSURE", - "COST_ANOMALY", - "MANUAL_TEST" - ] + "minLength": 1, + "maxLength": 253 }, - "resource_types": { - "type": "array", - "items": { - "type": "string" - } + "target": { + "oneOf": [ + { + "type": "object", + "properties": { + "kind": { + "type": "string", + "enum": [ + "install" + ] + }, + "install_id": { + "type": "string", + "minLength": 1, + "maxLength": 55 + } + }, + "required": [ + "kind", + "install_id" + ], + "additionalProperties": false + }, + { + "type": "object", + "properties": { + "kind": { + "type": "string", + "enum": [ + "cluster" + ] + }, + "cluster_id": { + "type": "string", + "minLength": 1, + "maxLength": 54 + } + }, + "required": [ + "kind", + "cluster_id" + ], + "additionalProperties": false + }, + { + "type": "object", + "properties": { + "kind": { + "type": "string", + "enum": [ + "external" + ] + }, + "endpoint": { + "type": "string", + "format": "uri" + }, + "mtls_secret_id": { + "type": "string", + "minLength": 1, + "maxLength": 54 + } + }, + "required": [ + "kind", + "endpoint" + ], + "additionalProperties": false + } + ] }, - "states": { - "type": "array", - "items": { - "type": "string" - } + "protocol": { + "type": "string", + "enum": [ + "http", + "websocket", + "grpc" + ], + "default": "http", + "description": "Transport class for route forwarding." }, - "min_severity": { + "routing_mode": { "type": "string", "enum": [ - "LOW", - "MEDIUM", - "HIGH", - "CRITICAL" - ] + "through_dispatcher", + "bypass_dispatcher" + ], + "default": "through_dispatcher", + "description": "Whether traffic uses the dispatcher Worker or bypasses it." } }, "required": [ - "type", - "resource_types", - "states" - ] + "hostname", + "target" + ], + "additionalProperties": false }, - "AgentRuntimePolicy": { + "UpdateCustomDomainBody": { "type": "object", "properties": { - "execution_environment": { - "type": "string", - "enum": [ - "CODE_MODE_FIRST", - "RETAINED_RUNTIME_ALLOWED", - "NO_RETAINED_RUNTIME" + "target": { + "oneOf": [ + { + "type": "object", + "properties": { + "kind": { + "type": "string", + "enum": [ + "install" + ] + }, + "install_id": { + "type": "string", + "minLength": 1, + "maxLength": 55 + } + }, + "required": [ + "kind", + "install_id" + ], + "additionalProperties": false + }, + { + "type": "object", + "properties": { + "kind": { + "type": "string", + "enum": [ + "cluster" + ] + }, + "cluster_id": { + "type": "string", + "minLength": 1, + "maxLength": 54 + } + }, + "required": [ + "kind", + "cluster_id" + ], + "additionalProperties": false + }, + { + "type": "object", + "properties": { + "kind": { + "type": "string", + "enum": [ + "external" + ] + }, + "endpoint": { + "type": "string", + "format": "uri" + }, + "mtls_secret_id": { + "type": "string", + "minLength": 1, + "maxLength": 54 + } + }, + "required": [ + "kind", + "endpoint" + ], + "additionalProperties": false + } ] }, - "filesystem": { - "type": "string" - }, - "shell": { - "type": "string" + "protocol": { + "type": "string", + "enum": [ + "http", + "websocket", + "grpc" + ], + "description": "Transport class for route forwarding." }, - "browser": { - "type": "string" - } - }, - "required": [ - "execution_environment", - "filesystem", - "shell", - "browser" - ] - }, - "AgentTemplateRemediationPolicy": { - "type": "object", - "nullable": true, - "properties": { - "repository_change_request": { - "$ref": "#/components/schemas/AgentTemplateRepositoryChangeRequestRemediationPolicy" + "routing_mode": { + "type": "string", + "enum": [ + "through_dispatcher", + "bypass_dispatcher" + ], + "description": "Whether traffic uses the dispatcher Worker or bypasses it." } }, - "required": [ - "repository_change_request" - ] + "additionalProperties": false }, - "AgentTemplateRepositoryChangeRequestRemediationPolicy": { + "CloudflareCredentialList": { "type": "object", "properties": { - "mode": { - "type": "string", - "enum": [ - "LIKELY_SOURCE_OR_CONFIG_FIX_ONLY" - ] - }, - "evidence_required": { - "type": "boolean" - }, - "allowed_actions": { + "data": { "type": "array", "items": { - "type": "string" + "$ref": "#/components/schemas/CloudflareCredential" } }, - "blocked_actions": { - "type": "array", - "items": { - "type": "string" - } + "has_more": { + "type": "boolean", + "description": "True if more items exist after this page." + }, + "next_cursor": { + "type": "string", + "nullable": true, + "description": "Opaque cursor for the next page, or null if no more pages." } }, "required": [ - "mode", - "evidence_required", - "allowed_actions", - "blocked_actions" + "data", + "has_more", + "next_cursor" ] }, - "AgentPreference": { + "CloudflareCredential": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, - "maxLength": 54 + "maxLength": 56 }, - "workspace_id": { + "name": { "type": "string", - "minLength": 1, - "maxLength": 53 - }, - "user_id": { - "type": "string" + "example": "Production Cloudflare" }, - "communication_profile": { + "account_id": { "type": "string", - "enum": [ - "BEGINNER", - "INTERMEDIATE", - "ADVANCED", - "EXPERT", - "ADAPTIVE" - ] + "description": "Cloudflare account ID." }, - "learning_mode_enabled": { - "type": "boolean" + "origin_zone_id": { + "type": "string", + "nullable": true, + "description": "Cloudflare zone ID used for Access-protected origin hostnames." }, - "seen_concepts": { - "type": "array", - "items": { - "type": "string" - } + "origin_hostname_suffix": { + "type": "string", + "nullable": true, + "description": "Hostname suffix used for Access-protected origin hostnames." + }, + "is_active": { + "type": "boolean", + "description": "Whether the credential is active" }, "created_at": { "type": "integer", "minimum": 0, "description": "Unix timestamp (seconds)" }, - "updated_at": { + "last_used_at": { "type": "integer", + "nullable": true, "minimum": 0, - "description": "Unix timestamp (seconds)" - }, - "etag": { - "type": "string" + "description": "Unix timestamp (seconds), null if never used" } }, "required": [ "id", - "workspace_id", - "user_id", - "communication_profile", - "learning_mode_enabled", - "seen_concepts", + "name", + "account_id", + "origin_zone_id", + "origin_hostname_suffix", + "is_active", "created_at", - "updated_at", - "etag" + "last_used_at" ] }, - "SandboxOperationsSummary": { + "CreateCloudflareCredentialBody": { "type": "object", "properties": { - "active_sandbox_count": { - "type": "integer", - "minimum": 0 - }, - "idle_retained_filesystem_count": { - "type": "integer", - "minimum": 0 - }, - "retained_filesystem_age_ms": { - "type": "number", - "minimum": 0 + "name": { + "type": "string", + "minLength": 1, + "maxLength": 100, + "example": "Production Cloudflare" }, - "estimated_retained_filesystem_gb_hours": { - "type": "number", - "minimum": 0 + "account_id": { + "type": "string", + "minLength": 1, + "maxLength": 200, + "pattern": "^[A-Za-z0-9_-]+$", + "description": "Cloudflare account ID." }, - "stuck_sandbox_count_by_state": { - "type": "array", - "items": { - "type": "object", - "properties": { - "state": { - "type": "string", - "enum": [ - "CREATING", - "STARTING", - "ACTIVE", - "STOPPING", - "STOPPED", - "DELETING", - "DELETED", - "FAILED" - ] - }, - "count": { - "type": "integer", - "minimum": 0 - } - }, - "required": [ - "state", - "count" - ] - } + "origin_zone_id": { + "type": "string", + "minLength": 1, + "maxLength": 200, + "pattern": "^[A-Za-z0-9_-]+$", + "description": "Cloudflare zone ID used for Access-protected origin hostnames." }, - "average_cold_start_latency_ms": { - "type": "number", - "nullable": true, - "minimum": 0 + "origin_hostname_suffix": { + "type": "string", + "minLength": 1, + "maxLength": 253, + "description": "Hostname suffix used for Access-protected origin hostnames." }, - "average_resume_latency_ms": { - "type": "number", - "nullable": true, - "minimum": 0 + "api_token": { + "type": "string", + "minLength": 1, + "maxLength": 2000, + "description": "Cloudflare API token. Stored as a platform Secret; never returned." } }, "required": [ - "active_sandbox_count", - "idle_retained_filesystem_count", - "retained_filesystem_age_ms", - "estimated_retained_filesystem_gb_hours", - "stuck_sandbox_count_by_state", - "average_cold_start_latency_ms", - "average_resume_latency_ms" - ] + "name", + "account_id", + "origin_zone_id", + "origin_hostname_suffix", + "api_token" + ], + "additionalProperties": false }, - "AgentSession": { + "AccessDecision": { "type": "object", "properties": { - "id": { - "type": "string", - "minLength": 1, - "maxLength": 54 + "decision": { + "$ref": "#/components/schemas/AccessDecisionResult" }, - "workspace_id": { - "type": "string", - "minLength": 1, - "maxLength": 53 + "action": { + "type": "object", + "properties": { + "id": { + "type": "string", + "minLength": 1 + }, + "name": { + "type": "string", + "minLength": 1 + } + }, + "required": [ + "id", + "name" + ], + "additionalProperties": false }, - "organization_id": { - "type": "string", - "nullable": true, - "minLength": 1, - "maxLength": 54 + "reasons": { + "type": "array", + "items": { + "$ref": "#/components/schemas/AccessReason" + } + } + }, + "required": [ + "decision", + "action", + "reasons" + ], + "additionalProperties": false + }, + "AccessDecisionResult": { + "oneOf": [ + { + "type": "object", + "properties": { + "result": { + "type": "string", + "enum": [ + "allowed" + ] + } + }, + "required": [ + "result" + ], + "additionalProperties": false }, - "agent_id": { - "type": "string", - "minLength": 1, - "maxLength": 54 + { + "type": "object", + "properties": { + "result": { + "type": "string", + "enum": [ + "denied" + ] + }, + "message": { + "type": "string", + "minLength": 1 + } + }, + "required": [ + "result", + "message" + ], + "additionalProperties": false }, - "state": { + { + "type": "object", + "properties": { + "result": { + "type": "string", + "enum": [ + "unknown" + ] + }, + "message": { + "type": "string", + "minLength": 1 + } + }, + "required": [ + "result", + "message" + ], + "additionalProperties": false + } + ] + }, + "AccessReason": { + "type": "object", + "properties": { + "kind": { "type": "string", "enum": [ - "ACTIVE", - "WAITING_FOR_INPUT", - "WAITING_FOR_PERMISSION", - "COMPLETED", - "FAILED", - "CANCELLED", - "ARCHIVED" + "catalog_default", + "external_feature_flag", + "external_billing_entitlement", + "workspace_access_status", + "admin_override", + "policy_rule", + "quota_limit", + "quota_usage", + "quota_override", + "actor_context", + "resource_state", + "workspace_membership", + "workspace_role", + "organization_membership", + "organization_role", + "workspace_class", + "resource_ownership", + "relationship", + "domain_policy" ] }, - "origin": { + "result": { "type": "string", "enum": [ - "DASHBOARD", - "API", - "MCP", - "ACP", - "AMBIENT", - "SYSTEM" + "allowed", + "denied", + "not_evaluated" ] }, - "title": { - "type": "string", - "nullable": true + "key": { + "type": "string" }, - "communication_profile": { + "source": { + "type": "string" + }, + "message": { + "type": "string" + }, + "metric": { + "type": "string" + }, + "scope": { "type": "string", "enum": [ - "BEGINNER", - "INTERMEDIATE", - "ADVANCED", - "EXPERT", - "ADAPTIVE" + "global", + "organization", + "workspace", + "user" ] }, - "created_by": { + "limit": { + "type": "number" + }, + "usage": { + "type": "number" + }, + "remaining": { + "type": "number" + }, + "resourceId": { "type": "string" }, - "parent_session_id": { - "type": "string", - "nullable": true, - "minLength": 1, - "maxLength": 54 + "resourceType": { + "type": "string" }, - "forked_from_session_id": { - "type": "string", - "nullable": true, - "minLength": 1, - "maxLength": 54 + "relationship": { + "type": "string" + } + }, + "required": [ + "kind", + "result" + ], + "additionalProperties": false + }, + "ExplainAccessDecisionBody": { + "oneOf": [ + { + "type": "object", + "properties": { + "subject": { + "$ref": "#/components/schemas/AccessSubject" + }, + "permission": { + "type": "string", + "enum": [ + "offers.create_via_channel" + ] + }, + "resource": { + "$ref": "#/components/schemas/OfferChannelCreateResource" + }, + "context": { + "$ref": "#/components/schemas/OfferChannelDecisionContext" + } + }, + "required": [ + "permission", + "resource" + ], + "additionalProperties": false }, - "spawned_by_turn_id": { - "type": "string", - "nullable": true, - "minLength": 1, - "maxLength": 54 + { + "type": "object", + "properties": { + "subject": { + "$ref": "#/components/schemas/AccessSubject" + }, + "permission": { + "type": "string", + "enum": [ + "offers.create_non_channel_paid_product_offer" + ] + }, + "resource": { + "$ref": "#/components/schemas/NonChannelPaidProductOfferResource" + } + }, + "required": [ + "permission", + "resource" + ], + "additionalProperties": false }, - "agent_role": { - "type": "string", - "nullable": true + { + "type": "object", + "properties": { + "subject": { + "$ref": "#/components/schemas/AccessSubject" + }, + "permission": { + "type": "string", + "enum": [ + "offers.create_non_billable_test_offer" + ] + }, + "resource": { + "$ref": "#/components/schemas/NonBillableTestOfferResource" + } + }, + "required": [ + "permission", + "resource" + ], + "additionalProperties": false }, - "current_sandbox_id": { - "type": "string", - "nullable": true, - "minLength": 1, - "maxLength": 54 + { + "type": "object", + "properties": { + "subject": { + "$ref": "#/components/schemas/AccessSubject" + }, + "permission": { + "type": "string", + "enum": [ + "offer_channels.create" + ] + }, + "resource": { + "$ref": "#/components/schemas/OfferChannelCreateDecisionResource" + } + }, + "required": [ + "permission", + "resource" + ], + "additionalProperties": false }, - "last_event_cursor": { - "type": "string", - "nullable": true + { + "type": "object", + "properties": { + "subject": { + "$ref": "#/components/schemas/AccessSubject" + }, + "permission": { + "type": "string", + "enum": [ + "offer_channels.inspect" + ] + }, + "resource": { + "$ref": "#/components/schemas/OfferChannelInspectResource" + } + }, + "required": [ + "permission", + "resource" + ], + "additionalProperties": false }, - "events_retained_until": { - "type": "integer", - "minimum": 0, - "description": "Unix timestamp (seconds)" + { + "type": "object", + "properties": { + "subject": { + "$ref": "#/components/schemas/AccessSubject" + }, + "permission": { + "type": "string", + "enum": [ + "channel_policies.approve" + ] + }, + "resource": { + "$ref": "#/components/schemas/ChannelPolicyApproveResource" + } + }, + "required": [ + "permission", + "resource" + ], + "additionalProperties": false }, - "filesystem_retained_until": { - "type": "integer", - "minimum": 0, - "description": "Unix timestamp (seconds)" + { + "type": "object", + "properties": { + "subject": { + "$ref": "#/components/schemas/AccessSubject" + }, + "permission": { + "type": "string", + "enum": [ + "channel_policies.activate" + ] + }, + "resource": { + "$ref": "#/components/schemas/ChannelPolicyActivateResource" + } + }, + "required": [ + "permission", + "resource" + ], + "additionalProperties": false + }, + { + "type": "object", + "properties": { + "subject": { + "$ref": "#/components/schemas/AccessSubject" + }, + "permission": { + "type": "string", + "enum": [ + "offers.approve_channel_offer" + ] + }, + "resource": { + "$ref": "#/components/schemas/OfferChannelModerationResource" + }, + "context": { + "$ref": "#/components/schemas/OfferChannelDecisionContext" + } + }, + "required": [ + "permission", + "resource" + ], + "additionalProperties": false }, - "filesystem_pinned": { - "type": "boolean" + { + "type": "object", + "properties": { + "subject": { + "$ref": "#/components/schemas/AccessSubject" + }, + "permission": { + "type": "string", + "enum": [ + "offers.reject_channel_offer" + ] + }, + "resource": { + "$ref": "#/components/schemas/OfferChannelModerationResource" + }, + "context": { + "$ref": "#/components/schemas/OfferChannelDecisionContext" + } + }, + "required": [ + "permission", + "resource" + ], + "additionalProperties": false }, - "usage_summary": { - "$ref": "#/components/schemas/AgentUsageSummary" + { + "type": "object", + "properties": { + "subject": { + "$ref": "#/components/schemas/AccessSubject" + }, + "permission": { + "type": "string", + "enum": [ + "workspaces.inspect_class" + ] + }, + "resource": { + "$ref": "#/components/schemas/WorkspaceClassResource" + } + }, + "required": [ + "permission", + "resource" + ], + "additionalProperties": false }, - "created_at": { - "type": "integer", - "minimum": 0, - "description": "Unix timestamp (seconds)" + { + "type": "object", + "properties": { + "subject": { + "$ref": "#/components/schemas/AccessSubject" + }, + "permission": { + "type": "string", + "enum": [ + "workspaces.inspect_membership" + ] + }, + "resource": { + "$ref": "#/components/schemas/WorkspaceMembershipResource" + } + }, + "required": [ + "permission", + "resource" + ], + "additionalProperties": false }, - "updated_at": { - "type": "integer", - "minimum": 0, - "description": "Unix timestamp (seconds)" + { + "type": "object", + "properties": { + "subject": { + "$ref": "#/components/schemas/AccessSubject" + }, + "permission": { + "type": "string", + "enum": [ + "products.create" + ] + }, + "resource": { + "$ref": "#/components/schemas/ProductCockpitResource" + } + }, + "required": [ + "permission" + ], + "additionalProperties": false }, - "etag": { - "type": "string" - } - }, - "required": [ - "id", - "workspace_id", - "organization_id", - "agent_id", - "state", - "origin", - "title", - "communication_profile", - "created_by", - "parent_session_id", - "forked_from_session_id", - "spawned_by_turn_id", - "agent_role", - "current_sandbox_id", - "last_event_cursor", - "events_retained_until", - "filesystem_retained_until", - "filesystem_pinned", - "usage_summary", - "created_at", - "updated_at", - "etag" - ] - }, - "AgentSessionList": { - "type": "object", - "properties": { - "data": { - "type": "array", - "items": { - "$ref": "#/components/schemas/AgentSession" - } + { + "type": "object", + "properties": { + "subject": { + "$ref": "#/components/schemas/AccessSubject" + }, + "permission": { + "type": "string", + "enum": [ + "products.get" + ] + }, + "resource": { + "type": "object", + "properties": { + "product_id": { + "type": "string", + "minLength": 1, + "maxLength": 55 + }, + "workspace_id": { + "type": "string", + "minLength": 1, + "maxLength": 53 + }, + "package_id": { + "type": "string", + "minLength": 1, + "maxLength": 54 + }, + "package_version_id": { + "type": "string", + "minLength": 1, + "maxLength": 55 + }, + "resource_state": { + "type": "string", + "enum": [ + "draft", + "active", + "archived" + ] + } + }, + "required": [ + "product_id", + "workspace_id" + ], + "additionalProperties": false + } + }, + "required": [ + "permission", + "resource" + ], + "additionalProperties": false }, - "has_more": { - "type": "boolean", - "description": "True if more items exist after this page." + { + "type": "object", + "properties": { + "subject": { + "$ref": "#/components/schemas/AccessSubject" + }, + "permission": { + "type": "string", + "enum": [ + "products.update" + ] + }, + "resource": { + "type": "object", + "properties": { + "product_id": { + "type": "string", + "minLength": 1, + "maxLength": 55 + }, + "workspace_id": { + "type": "string", + "minLength": 1, + "maxLength": 53 + }, + "package_id": { + "type": "string", + "minLength": 1, + "maxLength": 54 + }, + "package_version_id": { + "type": "string", + "minLength": 1, + "maxLength": 55 + }, + "resource_state": { + "type": "string", + "enum": [ + "draft", + "active", + "archived" + ] + } + }, + "required": [ + "product_id", + "workspace_id" + ], + "additionalProperties": false + } + }, + "required": [ + "permission", + "resource" + ], + "additionalProperties": false }, - "next_cursor": { - "type": "string", - "nullable": true, - "description": "Opaque cursor for the next page, or null if no more pages." - } - }, - "required": [ - "data", - "has_more", - "next_cursor" - ] - }, - "AgentWorkConflictList": { - "type": "object", - "properties": { - "data": { - "type": "array", - "items": { - "$ref": "#/components/schemas/AgentWorkConflict" - } - } - }, - "required": [ - "data" - ], - "additionalProperties": false - }, - "AgentWorkConflict": { - "type": "object", - "properties": { - "agent_id": { - "type": "string", - "minLength": 1, - "maxLength": 54 + { + "type": "object", + "properties": { + "subject": { + "$ref": "#/components/schemas/AccessSubject" + }, + "permission": { + "type": "string", + "enum": [ + "products.archive" + ] + }, + "resource": { + "type": "object", + "properties": { + "product_id": { + "type": "string", + "minLength": 1, + "maxLength": 55 + }, + "workspace_id": { + "type": "string", + "minLength": 1, + "maxLength": 53 + }, + "package_id": { + "type": "string", + "minLength": 1, + "maxLength": 54 + }, + "package_version_id": { + "type": "string", + "minLength": 1, + "maxLength": 55 + }, + "resource_state": { + "type": "string", + "enum": [ + "draft", + "active", + "archived" + ] + } + }, + "required": [ + "product_id", + "workspace_id" + ], + "additionalProperties": false + } + }, + "required": [ + "permission", + "resource" + ], + "additionalProperties": false }, - "session_id": { - "type": "string", - "minLength": 1, - "maxLength": 54 + { + "type": "object", + "properties": { + "subject": { + "$ref": "#/components/schemas/AccessSubject" + }, + "permission": { + "type": "string", + "enum": [ + "products.unarchive" + ] + }, + "resource": { + "type": "object", + "properties": { + "product_id": { + "type": "string", + "minLength": 1, + "maxLength": 55 + }, + "workspace_id": { + "type": "string", + "minLength": 1, + "maxLength": 53 + }, + "package_id": { + "type": "string", + "minLength": 1, + "maxLength": 54 + }, + "package_version_id": { + "type": "string", + "minLength": 1, + "maxLength": 55 + }, + "resource_state": { + "type": "string", + "enum": [ + "draft", + "active", + "archived" + ] + } + }, + "required": [ + "product_id", + "workspace_id" + ], + "additionalProperties": false + } + }, + "required": [ + "permission", + "resource" + ], + "additionalProperties": false }, - "turn_id": { - "type": "string", - "minLength": 1, - "maxLength": 54 + { + "type": "object", + "properties": { + "subject": { + "$ref": "#/components/schemas/AccessSubject" + }, + "permission": { + "type": "string", + "enum": [ + "products.inspect_readiness" + ] + }, + "resource": { + "type": "object", + "properties": { + "product_id": { + "type": "string", + "minLength": 1, + "maxLength": 55 + }, + "workspace_id": { + "type": "string", + "minLength": 1, + "maxLength": 53 + }, + "package_id": { + "type": "string", + "minLength": 1, + "maxLength": 54 + }, + "package_version_id": { + "type": "string", + "minLength": 1, + "maxLength": 55 + }, + "resource_state": { + "type": "string", + "enum": [ + "draft", + "active", + "archived" + ] + } + }, + "required": [ + "product_id", + "workspace_id" + ], + "additionalProperties": false + } + }, + "required": [ + "permission", + "resource" + ], + "additionalProperties": false }, - "event_id": { - "type": "string", - "minLength": 1, - "maxLength": 54 + { + "type": "object", + "properties": { + "subject": { + "$ref": "#/components/schemas/AccessSubject" + }, + "permission": { + "type": "string", + "enum": [ + "products.inspect_offer_creation" + ] + }, + "resource": { + "type": "object", + "properties": { + "product_id": { + "type": "string", + "minLength": 1, + "maxLength": 55 + }, + "workspace_id": { + "type": "string", + "minLength": 1, + "maxLength": 53 + }, + "package_id": { + "type": "string", + "minLength": 1, + "maxLength": 54 + }, + "package_version_id": { + "type": "string", + "minLength": 1, + "maxLength": 55 + }, + "resource_state": { + "type": "string", + "enum": [ + "draft", + "active", + "archived" + ] + } + }, + "required": [ + "product_id", + "workspace_id" + ], + "additionalProperties": false + } + }, + "required": [ + "permission", + "resource" + ], + "additionalProperties": false }, - "event_type": { - "type": "string", - "enum": [ - "message.created", - "widget.created", - "artifact.created", - "progress.updated", - "execution_environment.started", - "execution_environment.stopped", - "execution_environment.resumed", - "execution_environment.deleted", - "execution_environment.failed", - "handoff_summary.created", - "turn.cancelled" - ] + { + "type": "object", + "properties": { + "subject": { + "$ref": "#/components/schemas/AccessSubject" + }, + "permission": { + "type": "string", + "enum": [ + "products.inspect_channels" + ] + }, + "resource": { + "type": "object", + "properties": { + "product_id": { + "type": "string", + "minLength": 1, + "maxLength": 55 + }, + "workspace_id": { + "type": "string", + "minLength": 1, + "maxLength": 53 + }, + "package_id": { + "type": "string", + "minLength": 1, + "maxLength": 54 + }, + "package_version_id": { + "type": "string", + "minLength": 1, + "maxLength": 55 + }, + "resource_state": { + "type": "string", + "enum": [ + "draft", + "active", + "archived" + ] + } + }, + "required": [ + "product_id", + "workspace_id" + ], + "additionalProperties": false + } + }, + "required": [ + "permission", + "resource" + ], + "additionalProperties": false }, - "reason": { - "type": "string", - "minLength": 1, - "maxLength": 500 + { + "type": "object", + "properties": { + "subject": { + "$ref": "#/components/schemas/AccessSubject" + }, + "permission": { + "type": "string", + "enum": [ + "products.inspect_installs" + ] + }, + "resource": { + "type": "object", + "properties": { + "product_id": { + "type": "string", + "minLength": 1, + "maxLength": 55 + }, + "workspace_id": { + "type": "string", + "minLength": 1, + "maxLength": 53 + }, + "package_id": { + "type": "string", + "minLength": 1, + "maxLength": 54 + }, + "package_version_id": { + "type": "string", + "minLength": 1, + "maxLength": 55 + }, + "resource_state": { + "type": "string", + "enum": [ + "draft", + "active", + "archived" + ] + } + }, + "required": [ + "product_id", + "workspace_id" + ], + "additionalProperties": false + } + }, + "required": [ + "permission", + "resource" + ], + "additionalProperties": false }, - "created_at": { - "type": "integer", - "minimum": 0, - "description": "Unix timestamp (seconds)" - } - }, - "required": [ - "agent_id", - "session_id", - "turn_id", - "event_id", - "event_type", - "reason", - "created_at" - ], - "additionalProperties": false - }, - "SetAgentSessionRetentionBody": { - "type": "object", - "properties": { - "events_retained_until": { - "type": "integer", - "minimum": 0, - "description": "Unix timestamp (seconds)" + { + "type": "object", + "properties": { + "subject": { + "$ref": "#/components/schemas/AccessSubject" + }, + "permission": { + "type": "string", + "enum": [ + "packages.create" + ] + }, + "resource": { + "$ref": "#/components/schemas/PackageCockpitResource" + } + }, + "required": [ + "permission" + ], + "additionalProperties": false }, - "filesystem_retained_until": { - "type": "integer", - "minimum": 0, - "description": "Unix timestamp (seconds)" + { + "type": "object", + "properties": { + "subject": { + "$ref": "#/components/schemas/AccessSubject" + }, + "permission": { + "type": "string", + "enum": [ + "packages.import_published_package" + ] + }, + "resource": { + "$ref": "#/components/schemas/PackageCockpitResource" + } + }, + "required": [ + "permission" + ], + "additionalProperties": false }, - "filesystem_pinned": { - "type": "boolean" + { + "type": "object", + "properties": { + "subject": { + "$ref": "#/components/schemas/AccessSubject" + }, + "permission": { + "type": "string", + "enum": [ + "packages.get" + ] + }, + "resource": { + "type": "object", + "properties": { + "package_id": { + "type": "string", + "minLength": 1, + "maxLength": 54 + }, + "package_version_id": { + "type": "string", + "minLength": 1, + "maxLength": 55 + }, + "workspace_id": { + "type": "string", + "minLength": 1, + "maxLength": 53 + } + }, + "required": [ + "package_id", + "workspace_id" + ], + "additionalProperties": false + } + }, + "required": [ + "permission", + "resource" + ], + "additionalProperties": false }, - "retention_reason": { - "type": "string", - "enum": [ - "SESSION_ACTIVE", - "PINNED", - "POLICY", - "TERMINAL_GRACE", - "MANUAL_DELETE" - ] - } - }, - "required": [ - "events_retained_until", - "filesystem_retained_until", - "filesystem_pinned", - "retention_reason" - ], - "additionalProperties": false - }, - "AgentTurn": { - "type": "object", - "properties": { - "id": { - "type": "string", - "minLength": 1, - "maxLength": 54 + { + "type": "object", + "properties": { + "subject": { + "$ref": "#/components/schemas/AccessSubject" + }, + "permission": { + "type": "string", + "enum": [ + "package_versions.get" + ] + }, + "resource": { + "type": "object", + "properties": { + "package_id": { + "type": "string", + "minLength": 1, + "maxLength": 54 + }, + "package_version_id": { + "type": "string", + "minLength": 1, + "maxLength": 55 + }, + "workspace_id": { + "type": "string", + "minLength": 1, + "maxLength": 53 + } + }, + "required": [ + "package_id", + "package_version_id", + "workspace_id" + ], + "additionalProperties": false + } + }, + "required": [ + "permission", + "resource" + ], + "additionalProperties": false }, - "workspace_id": { - "type": "string", - "minLength": 1, - "maxLength": 53 + { + "type": "object", + "properties": { + "subject": { + "$ref": "#/components/schemas/AccessSubject" + }, + "permission": { + "type": "string", + "enum": [ + "package_versions.inputs" + ] + }, + "resource": { + "type": "object", + "properties": { + "package_id": { + "type": "string", + "minLength": 1, + "maxLength": 54 + }, + "package_version_id": { + "type": "string", + "minLength": 1, + "maxLength": 55 + }, + "workspace_id": { + "type": "string", + "minLength": 1, + "maxLength": 53 + } + }, + "required": [ + "package_id", + "package_version_id", + "workspace_id" + ], + "additionalProperties": false + } + }, + "required": [ + "permission", + "resource" + ], + "additionalProperties": false }, - "organization_id": { - "type": "string", - "nullable": true, - "minLength": 1, - "maxLength": 54 + { + "type": "object", + "properties": { + "subject": { + "$ref": "#/components/schemas/AccessSubject" + }, + "permission": { + "type": "string", + "enum": [ + "clusters.update" + ] + }, + "resource": { + "$ref": "#/components/schemas/ClusterCockpitResource" + } + }, + "required": [ + "permission", + "resource" + ], + "additionalProperties": false }, - "agent_id": { - "type": "string", - "minLength": 1, - "maxLength": 54 + { + "type": "object", + "properties": { + "subject": { + "$ref": "#/components/schemas/AccessSubject" + }, + "permission": { + "type": "string", + "enum": [ + "clusters.delete" + ] + }, + "resource": { + "$ref": "#/components/schemas/ClusterCockpitResource" + } + }, + "required": [ + "permission", + "resource" + ], + "additionalProperties": false }, - "session_id": { - "type": "string", - "minLength": 1, - "maxLength": 54 + { + "type": "object", + "properties": { + "subject": { + "$ref": "#/components/schemas/AccessSubject" + }, + "permission": { + "type": "string", + "enum": [ + "clusters.suspend" + ] + }, + "resource": { + "$ref": "#/components/schemas/ClusterCockpitResource" + } + }, + "required": [ + "permission", + "resource" + ], + "additionalProperties": false }, - "state": { - "type": "string", - "enum": [ - "QUEUED", - "RUNNING", - "WAITING_FOR_INPUT", - "WAITING_FOR_PERMISSION", - "COMPLETED", - "FAILED", - "CANCELLED" - ] + { + "type": "object", + "properties": { + "subject": { + "$ref": "#/components/schemas/AccessSubject" + }, + "permission": { + "type": "string", + "enum": [ + "clusters.resume" + ] + }, + "resource": { + "$ref": "#/components/schemas/ClusterCockpitResource" + } + }, + "required": [ + "permission", + "resource" + ], + "additionalProperties": false }, - "origin": { - "type": "string", - "enum": [ - "DASHBOARD", - "API", - "MCP", - "ACP", - "AMBIENT", - "SYSTEM" - ] + { + "type": "object", + "properties": { + "subject": { + "$ref": "#/components/schemas/AccessSubject" + }, + "permission": { + "type": "string", + "enum": [ + "clusters.refresh_capabilities" + ] + }, + "resource": { + "$ref": "#/components/schemas/ClusterCockpitResource" + } + }, + "required": [ + "permission", + "resource" + ], + "additionalProperties": false }, - "input": { + { "type": "object", "properties": { - "type": { + "subject": { + "$ref": "#/components/schemas/AccessSubject" + }, + "permission": { "type": "string", "enum": [ - "message" + "clusters.get_kubeconfig" ] }, - "content": { - "type": "string" + "resource": { + "$ref": "#/components/schemas/ClusterCockpitResource" } }, "required": [ - "type", - "content" - ] - }, - "runtime_hint": { - "type": "string", - "enum": [ - "AUTO", - "CODE_MODE", - "RETAINED_RUNTIME" - ] - }, - "model": { - "type": "string", - "nullable": true - }, - "created_by": { - "type": "string" - }, - "started_at": { - "type": "integer", - "nullable": true, - "minimum": 0, - "description": "Unix timestamp (seconds)" - }, - "completed_at": { - "type": "integer", - "nullable": true, - "minimum": 0, - "description": "Unix timestamp (seconds)" - }, - "runtime_decision": { - "type": "string", - "nullable": true, - "enum": [ - "ALLOWED", - "DENIED", - "APPROVAL_REQUIRED", - null - ] - }, - "decision_reason": { - "type": "string", - "nullable": true - }, - "resolved_execution_mode": { - "type": "string", - "nullable": true, - "enum": [ - "CODE_MODE", - "RETAINED_RUNTIME", - null - ] + "permission", + "resource" + ], + "additionalProperties": false }, - "admission_error": { + { "type": "object", - "nullable": true, "properties": { - "code": { - "type": "string" + "subject": { + "$ref": "#/components/schemas/AccessSubject" }, - "message": { - "type": "string" + "permission": { + "type": "string", + "enum": [ + "clusters.create_worker_bootstrap" + ] + }, + "resource": { + "$ref": "#/components/schemas/ClusterCockpitResource" } }, "required": [ - "code", - "message" - ] - }, - "usage_summary": { - "$ref": "#/components/schemas/AgentUsageSummary" + "permission", + "resource" + ], + "additionalProperties": false }, - "failure": { + { "type": "object", - "nullable": true, "properties": { - "code": { - "type": "string" + "subject": { + "$ref": "#/components/schemas/AccessSubject" }, - "message": { - "type": "string" + "permission": { + "type": "string", + "enum": [ + "clusters.revoke_worker_bootstrap" + ] + }, + "resource": { + "$ref": "#/components/schemas/ClusterCockpitResource" } }, "required": [ - "code", - "message" - ] - }, - "created_at": { - "type": "integer", - "minimum": 0, - "description": "Unix timestamp (seconds)" - }, - "updated_at": { - "type": "integer", - "minimum": 0, - "description": "Unix timestamp (seconds)" - }, - "etag": { - "type": "string" - } - }, - "required": [ - "id", - "workspace_id", - "organization_id", - "agent_id", - "session_id", - "state", - "origin", - "input", - "runtime_hint", - "model", - "created_by", - "started_at", - "completed_at", - "runtime_decision", - "decision_reason", - "resolved_execution_mode", - "admission_error", - "usage_summary", - "failure", - "created_at", - "updated_at", - "etag" - ] - }, - "AgentTurnList": { - "type": "object", - "properties": { - "data": { - "type": "array", - "items": { - "$ref": "#/components/schemas/AgentTurn" - } - }, - "has_more": { - "type": "boolean", - "description": "True if more items exist after this page." - }, - "next_cursor": { - "type": "string", - "nullable": true, - "description": "Opaque cursor for the next page, or null if no more pages." - } - }, - "required": [ - "data", - "has_more", - "next_cursor" - ] - }, - "AgentEvent": { - "type": "object", - "properties": { - "id": { - "type": "string", - "minLength": 1, - "maxLength": 54 - }, - "workspace_id": { - "type": "string", - "minLength": 1, - "maxLength": 53 - }, - "agent_id": { - "type": "string", - "minLength": 1, - "maxLength": 54 - }, - "session_id": { - "type": "string", - "minLength": 1, - "maxLength": 54 - }, - "turn_id": { - "type": "string", - "minLength": 1, - "maxLength": 54 - }, - "sequence": { - "type": "integer" - }, - "cursor": { - "type": "string" - }, - "type": { - "type": "string", - "enum": [ - "message.created", - "widget.created", - "artifact.created", - "progress.updated", - "execution_environment.started", - "execution_environment.stopped", - "execution_environment.resumed", - "execution_environment.deleted", - "execution_environment.failed", - "handoff_summary.created", - "turn.cancelled" - ] - }, - "created_at": { - "type": "integer", - "minimum": 0, - "description": "Unix timestamp (seconds)" - }, - "data": { - "nullable": true - } - }, - "required": [ - "id", - "workspace_id", - "agent_id", - "session_id", - "turn_id", - "sequence", - "cursor", - "type", - "created_at" - ] - }, - "AgentProviderExchangeList": { - "type": "object", - "properties": { - "data": { - "type": "array", - "items": { - "$ref": "#/components/schemas/AgentProviderExchange" - } - }, - "has_more": { - "type": "boolean", - "description": "True if more items exist after this page." - }, - "next_cursor": { - "type": "string", - "nullable": true, - "description": "Opaque cursor for the next page, or null if no more pages." - } - }, - "required": [ - "data", - "has_more", - "next_cursor" - ] - }, - "AgentProviderExchange": { - "type": "object", - "properties": { - "id": { - "type": "string", - "minLength": 1, - "maxLength": 54 - }, - "workspace_id": { - "type": "string", - "minLength": 1, - "maxLength": 53 - }, - "organization_id": { - "type": "string", - "nullable": true, - "minLength": 1, - "maxLength": 54 - }, - "agent_id": { - "type": "string", - "minLength": 1, - "maxLength": 54 - }, - "session_id": { - "type": "string", - "minLength": 1, - "maxLength": 54 - }, - "turn_id": { - "type": "string", - "minLength": 1, - "maxLength": 54 - }, - "provider": { - "type": "string" - }, - "model": { - "type": "string", - "nullable": true - }, - "fallback_from_model": { - "type": "string", - "nullable": true - }, - "fallback_reason": { - "type": "string", - "nullable": true - }, - "credential_mode": { - "type": "string", - "enum": [ - "PLATFORM_SUBSCRIPTION", - "PLATFORM_API", - "WORKSPACE_BYOK" - ] - }, - "credential_secret_id": { - "type": "string", - "nullable": true, - "minLength": 1, - "maxLength": 54 + "permission", + "resource" + ], + "additionalProperties": false }, - "requested_at": { - "type": "integer", - "minimum": 0, - "description": "Unix timestamp (seconds)" + { + "type": "object", + "properties": { + "subject": { + "$ref": "#/components/schemas/AccessSubject" + }, + "permission": { + "type": "string", + "enum": [ + "machines.create" + ] + }, + "resource": { + "$ref": "#/components/schemas/ClusterCockpitResource" + } + }, + "required": [ + "permission", + "resource" + ], + "additionalProperties": false }, - "responded_at": { - "type": "integer", - "minimum": 0, - "description": "Unix timestamp (seconds)" + { + "type": "object", + "properties": { + "subject": { + "$ref": "#/components/schemas/AccessSubject" + }, + "permission": { + "type": "string", + "enum": [ + "machines.update" + ] + }, + "resource": { + "$ref": "#/components/schemas/MachineCockpitResource" + } + }, + "required": [ + "permission", + "resource" + ], + "additionalProperties": false }, - "provider_cost_cents": { - "type": "integer", - "minimum": 0 + { + "type": "object", + "properties": { + "subject": { + "$ref": "#/components/schemas/AccessSubject" + }, + "permission": { + "type": "string", + "enum": [ + "machines.delete" + ] + }, + "resource": { + "$ref": "#/components/schemas/MachineCockpitResource" + } + }, + "required": [ + "permission", + "resource" + ], + "additionalProperties": false }, - "provider_token_count": { - "type": "integer", - "minimum": 0 + { + "type": "object", + "properties": { + "subject": { + "$ref": "#/components/schemas/AccessSubject" + }, + "permission": { + "type": "string", + "enum": [ + "machines.suspend" + ] + }, + "resource": { + "$ref": "#/components/schemas/MachineCockpitResource" + } + }, + "required": [ + "permission", + "resource" + ], + "additionalProperties": false }, - "token_counts": { + { "type": "object", - "nullable": true, "properties": { - "input": { - "type": "integer", - "minimum": 0 + "subject": { + "$ref": "#/components/schemas/AccessSubject" }, - "output": { - "type": "integer", - "minimum": 0 + "permission": { + "type": "string", + "enum": [ + "machines.resume" + ] }, - "total": { - "type": "integer", - "minimum": 0 + "resource": { + "$ref": "#/components/schemas/MachineCockpitResource" } - } + }, + "required": [ + "permission", + "resource" + ], + "additionalProperties": false }, - "message_summary": { - "type": "string", - "nullable": true + { + "type": "object", + "properties": { + "subject": { + "$ref": "#/components/schemas/AccessSubject" + }, + "permission": { + "type": "string", + "enum": [ + "compute_configs.update" + ] + }, + "resource": { + "$ref": "#/components/schemas/ClusterCockpitResource" + } + }, + "required": [ + "permission", + "resource" + ], + "additionalProperties": false }, - "upstream_error_code": { - "type": "string", - "nullable": true + { + "type": "object", + "properties": { + "subject": { + "$ref": "#/components/schemas/AccessSubject" + }, + "permission": { + "type": "string", + "enum": [ + "installs.create" + ] + }, + "resource": { + "$ref": "#/components/schemas/ClusterCockpitResource" + } + }, + "required": [ + "permission", + "resource" + ], + "additionalProperties": false }, - "created_at": { - "type": "integer", - "minimum": 0, - "description": "Unix timestamp (seconds)" + { + "type": "object", + "properties": { + "subject": { + "$ref": "#/components/schemas/AccessSubject" + }, + "permission": { + "type": "string", + "enum": [ + "catalog_actions.explain" + ] + }, + "resource": { + "$ref": "#/components/schemas/CatalogActionExplainResource" + } + }, + "required": [ + "permission", + "resource" + ], + "additionalProperties": false, + "x-platform-visibility": "ADMIN" } - }, - "required": [ - "id", - "workspace_id", - "organization_id", - "agent_id", - "session_id", - "turn_id", - "provider", - "model", - "fallback_from_model", - "fallback_reason", - "credential_mode", - "credential_secret_id", - "requested_at", - "responded_at", - "provider_cost_cents", - "provider_token_count", - "token_counts", - "message_summary", - "upstream_error_code", - "created_at" ] }, - "AgentEventList": { + "AccessSubject": { "type": "object", "properties": { - "data": { - "type": "array", - "items": { - "$ref": "#/components/schemas/AgentEvent" - } + "user_id": { + "type": "string", + "minLength": 1 }, - "has_more": { - "type": "boolean", - "description": "True if more items exist after this page." + "organization_id": { + "type": "string", + "minLength": 1, + "maxLength": 54 }, - "next_cursor": { + "workspace_id": { "type": "string", - "nullable": true, - "description": "Opaque cursor for the next page, or null if no more pages." + "minLength": 1, + "maxLength": 53 } }, - "required": [ - "data", - "has_more", - "next_cursor" - ] + "additionalProperties": false }, - "ApprovalRequestList": { + "OfferChannelCreateResource": { "type": "object", "properties": { - "data": { - "type": "array", - "items": { - "$ref": "#/components/schemas/ApprovalRequest" - } + "offer_channel_id": { + "type": "string", + "minLength": 1, + "maxLength": 54 }, - "has_more": { - "type": "boolean", - "description": "True if more items exist after this page." + "target_workspace_id": { + "type": "string", + "minLength": 1, + "maxLength": 53 }, - "next_cursor": { + "product_id": { "type": "string", - "nullable": true, - "description": "Opaque cursor for the next page, or null if no more pages." + "minLength": 1, + "maxLength": 55 + }, + "commercial_mode": { + "type": "string", + "enum": [ + "paid", + "non_billable_test" + ] } }, "required": [ - "data", - "has_more", - "next_cursor" - ] + "offer_channel_id", + "product_id", + "commercial_mode" + ], + "additionalProperties": false }, - "ApprovalRequest": { + "OfferChannelDecisionContext": { "type": "object", "properties": { - "id": { + "selected_organization_id": { "type": "string", "minLength": 1, "maxLength": 54 }, + "stripe_mode": { + "type": "string", + "enum": [ + "live", + "test", + "sandbox" + ] + } + }, + "additionalProperties": false + }, + "NonChannelPaidProductOfferResource": { + "type": "object", + "properties": { "workspace_id": { "type": "string", "minLength": 1, "maxLength": 53 }, - "agent_id": { + "product_id": { "type": "string", "minLength": 1, - "maxLength": 54 + "maxLength": 55 }, - "session_id": { + "package_version_id": { "type": "string", "minLength": 1, - "maxLength": 54 + "maxLength": 55 }, - "turn_id": { + "target_workspace_id": { "type": "string", "minLength": 1, - "maxLength": 54 + "maxLength": 53 }, - "state": { + "commercial_mode": { "type": "string", "enum": [ - "PENDING", - "APPROVED", - "REJECTED" + "paid" ] - }, - "title": { - "type": "string" - }, - "summary": { - "type": "string" - }, - "actions": { - "type": "array", - "items": { - "nullable": true - }, - "default": [] - }, - "created_by": { - "type": "string" - }, - "created_at": { - "type": "integer", - "minimum": 0, - "description": "Unix timestamp (seconds)" - }, - "updated_at": { - "type": "integer", - "minimum": 0, - "description": "Unix timestamp (seconds)" - }, - "etag": { - "type": "string" } }, "required": [ - "id", "workspace_id", - "agent_id", - "session_id", - "turn_id", - "state", - "title", - "summary", - "created_by", - "created_at", - "updated_at", - "etag" - ] + "product_id", + "package_version_id", + "commercial_mode" + ], + "additionalProperties": false }, - "WorkspaceSubdomain": { + "NonBillableTestOfferResource": { "type": "object", "properties": { - "id": { + "workspace_id": { "type": "string", "minLength": 1, - "maxLength": 54 + "maxLength": 53 }, - "workspace_id": { + "product_id": { "type": "string", "minLength": 1, - "maxLength": 53 + "maxLength": 55 }, - "name": { + "package_version_id": { "type": "string", "minLength": 1, - "maxLength": 63 + "maxLength": 55 }, - "fqdn": { + "target_workspace_id": { "type": "string", "minLength": 1, - "maxLength": 253 + "maxLength": 53 }, - "status": { + "target_workspace_class": { "type": "string", "enum": [ - "active", - "propagating", - "reserved" - ], - "description": "Current workspace subdomain lifecycle state." - }, - "name_changed_at": { - "type": "integer", - "nullable": true, - "minimum": 0, - "description": "Unix timestamp (seconds)" - }, - "created_at": { - "type": "integer", - "minimum": 0, - "description": "Unix timestamp (seconds)" - }, - "updated_at": { - "type": "integer", - "minimum": 0, - "description": "Unix timestamp (seconds)" + "standard", + "platform", + "sandbox" + ] }, - "etag": { - "type": "string" + "commercial_mode": { + "type": "string", + "enum": [ + "non_billable_test" + ] } }, "required": [ - "id", "workspace_id", - "name", - "fqdn", - "status", - "name_changed_at", - "created_at", - "updated_at", - "etag" - ] + "package_version_id", + "commercial_mode" + ], + "additionalProperties": false }, - "SetWorkspaceSubdomainNameBody": { + "OfferChannelCreateDecisionResource": { "type": "object", "properties": { - "name": { + "workspace_id": { "type": "string", "minLength": 1, - "maxLength": 63 + "maxLength": 53 + }, + "product_id": { + "type": "string", + "minLength": 1, + "maxLength": 55 + }, + "partner_organization_id": { + "type": "string", + "minLength": 1, + "maxLength": 54 } }, "required": [ - "name" + "workspace_id" ], "additionalProperties": false }, - "PreviewHostnameList": { + "OfferChannelInspectResource": { "type": "object", "properties": { - "data": { - "type": "array", - "items": { - "$ref": "#/components/schemas/PreviewHostname" - } + "workspace_id": { + "type": "string", + "minLength": 1, + "maxLength": 53 }, - "has_more": { - "type": "boolean", - "description": "True if more items exist after this page." + "offer_channel_id": { + "type": "string", + "minLength": 1, + "maxLength": 54 }, - "next_cursor": { + "product_id": { "type": "string", - "nullable": true, - "description": "Opaque cursor for the next page, or null if no more pages." + "minLength": 1, + "maxLength": 55 } }, "required": [ - "data", - "has_more", - "next_cursor" - ] + "workspace_id" + ], + "additionalProperties": false }, - "PreviewHostname": { + "ChannelPolicyApproveResource": { "type": "object", "properties": { - "id": { - "type": "string", - "minLength": 1, - "maxLength": 54 - }, "workspace_id": { "type": "string", "minLength": 1, "maxLength": 53 }, - "install_id": { + "offer_channel_id": { "type": "string", "minLength": 1, - "maxLength": 55 + "maxLength": 54 }, - "hostname": { + "channel_policy_id": { "type": "string", "minLength": 1, - "maxLength": 253 - }, - "protocol": { - "type": "string", - "enum": [ - "http", - "websocket", - "grpc" - ], - "description": "Transport class for route forwarding." + "maxLength": 56 }, - "routing_mode": { + "resource_state": { "type": "string", "enum": [ - "through_dispatcher", - "bypass_dispatcher" - ], - "description": "Whether traffic uses the dispatcher Worker or bypasses it." - }, - "binding": { - "oneOf": [ - { - "type": "object", - "properties": { - "kind": { - "type": "string", - "enum": [ - "pinned" - ] - }, - "render_id": { - "type": "string", - "minLength": 1, - "maxLength": 54 - } - }, - "required": [ - "kind", - "render_id" - ], - "additionalProperties": false - }, - { - "type": "object", - "properties": { - "kind": { - "type": "string", - "enum": [ - "floating" - ] - }, - "track": { - "type": "string", - "minLength": 1, - "maxLength": 100 - }, - "render_id": { - "type": "string", - "minLength": 1, - "maxLength": 54 - } - }, - "required": [ - "kind", - "track", - "render_id" - ], - "additionalProperties": false - } + "draft" ] - }, - "status": { - "type": "string", - "enum": [ - "provisioning", - "active", - "evicted", - "releasing" - ], - "description": "Current preview hostname lifecycle state." - }, - "last_seen_at": { - "type": "integer", - "nullable": true, - "minimum": 0, - "description": "Unix timestamp (seconds)" - }, - "created_at": { - "type": "integer", - "minimum": 0, - "description": "Unix timestamp (seconds)" - }, - "updated_at": { - "type": "integer", - "minimum": 0, - "description": "Unix timestamp (seconds)" - }, - "etag": { - "type": "string" } }, "required": [ - "id", "workspace_id", - "install_id", - "hostname", - "protocol", - "routing_mode", - "binding", - "status", - "last_seen_at", - "created_at", - "updated_at", - "etag" - ] + "offer_channel_id", + "channel_policy_id", + "resource_state" + ], + "additionalProperties": false }, - "BindPinnedPreviewHostnameBody": { + "ChannelPolicyActivateResource": { "type": "object", "properties": { - "render_id": { + "workspace_id": { + "type": "string", + "minLength": 1, + "maxLength": 53 + }, + "offer_channel_id": { "type": "string", "minLength": 1, "maxLength": 54 }, - "protocol": { + "channel_policy_id": { "type": "string", - "enum": [ - "http", - "websocket", - "grpc" - ], - "default": "http", - "description": "Transport class for route forwarding." + "minLength": 1, + "maxLength": 56 }, - "routing_mode": { + "resource_state": { "type": "string", "enum": [ - "through_dispatcher", - "bypass_dispatcher" - ], - "default": "through_dispatcher", - "description": "Whether traffic uses the dispatcher Worker or bypasses it." + "approved" + ] } }, "required": [ - "render_id" + "workspace_id", + "offer_channel_id", + "channel_policy_id", + "resource_state" ], "additionalProperties": false }, - "BindFloatingPreviewHostnameBody": { + "OfferChannelModerationResource": { "type": "object", "properties": { - "track": { + "offer_id": { "type": "string", "minLength": 1, - "maxLength": 100 + "maxLength": 56 }, - "render_id": { + "offer_channel_id": { "type": "string", "minLength": 1, "maxLength": 54 }, - "protocol": { + "owner_workspace_id": { + "type": "string", + "minLength": 1, + "maxLength": 53 + }, + "resource_state": { "type": "string", "enum": [ - "http", - "websocket", - "grpc" - ], - "default": "http", - "description": "Transport class for route forwarding." + "pending_approval", + "approved", + "rejected" + ] + }, + "platform_policy_snapshot_id": { + "type": "string", + "minLength": 1, + "x-platform-visibility": "ADMIN" + }, + "partner_price_band_key": { + "type": "string", + "minLength": 1, + "x-platform-visibility": "TRUSTED_PARTNER" + } + }, + "required": [ + "offer_id", + "offer_channel_id", + "owner_workspace_id", + "resource_state" + ], + "additionalProperties": false + }, + "WorkspaceClassResource": { + "type": "object", + "properties": { + "workspace_id": { + "type": "string", + "minLength": 1, + "maxLength": 53 }, - "routing_mode": { + "required_class": { "type": "string", "enum": [ - "through_dispatcher", - "bypass_dispatcher" - ], - "default": "through_dispatcher", - "description": "Whether traffic uses the dispatcher Worker or bypasses it." + "standard", + "platform", + "sandbox" + ] } }, "required": [ - "track", - "render_id" + "workspace_id" ], "additionalProperties": false }, - "CustomDomainList": { + "WorkspaceMembershipResource": { "type": "object", "properties": { - "data": { + "workspace_id": { + "type": "string", + "minLength": 1, + "maxLength": 53 + }, + "required_roles": { "type": "array", "items": { - "$ref": "#/components/schemas/CustomDomain" + "type": "string", + "enum": [ + "owner", + "admin", + "member" + ] } - }, - "has_more": { - "type": "boolean", - "description": "True if more items exist after this page." - }, - "next_cursor": { - "type": "string", - "nullable": true, - "description": "Opaque cursor for the next page, or null if no more pages." } }, "required": [ - "data", - "has_more", - "next_cursor" - ] + "workspace_id" + ], + "additionalProperties": false }, - "CustomDomain": { + "ProductCockpitResource": { "type": "object", "properties": { - "id": { + "product_id": { "type": "string", "minLength": 1, - "maxLength": 54 + "maxLength": 55 }, "workspace_id": { "type": "string", "minLength": 1, "maxLength": 53 }, - "hostname": { + "package_id": { "type": "string", "minLength": 1, - "maxLength": 253 - }, - "target": { - "oneOf": [ - { - "type": "object", - "properties": { - "kind": { - "type": "string", - "enum": [ - "install" - ] - }, - "install_id": { - "type": "string", - "minLength": 1, - "maxLength": 55 - } - }, - "required": [ - "kind", - "install_id" - ], - "additionalProperties": false - }, - { - "type": "object", - "properties": { - "kind": { - "type": "string", - "enum": [ - "cluster" - ] - }, - "cluster_id": { - "type": "string", - "minLength": 1, - "maxLength": 54 - } - }, - "required": [ - "kind", - "cluster_id" - ], - "additionalProperties": false - }, - { - "type": "object", - "properties": { - "kind": { - "type": "string", - "enum": [ - "external" - ] - }, - "endpoint": { - "type": "string", - "format": "uri" - }, - "mtls_secret_id": { - "type": "string", - "minLength": 1, - "maxLength": 54 - } - }, - "required": [ - "kind", - "endpoint" - ], - "additionalProperties": false - } - ] - }, - "protocol": { - "type": "string", - "enum": [ - "http", - "websocket", - "grpc" - ], - "description": "Transport class for route forwarding." + "maxLength": 54 }, - "routing_mode": { + "package_version_id": { "type": "string", - "enum": [ - "through_dispatcher", - "bypass_dispatcher" - ], - "description": "Whether traffic uses the dispatcher Worker or bypasses it." - }, - "ssl": { - "type": "object", - "properties": { - "status": { - "type": "string", - "enum": [ - "pending_validation", - "active", - "failed" - ] - }, - "validation_records": { - "type": "array", - "items": { - "type": "object", - "additionalProperties": { - "type": "string" - } - } - } - }, - "required": [ - "status" - ] + "minLength": 1, + "maxLength": 55 }, - "status": { + "resource_state": { "type": "string", "enum": [ - "provisioning", + "draft", "active", - "failed", - "releasing" + "archived" ] - }, - "created_at": { - "type": "integer", - "minimum": 0, - "description": "Unix timestamp (seconds)" - }, - "updated_at": { - "type": "integer", - "minimum": 0, - "description": "Unix timestamp (seconds)" - }, - "etag": { - "type": "string" } }, "required": [ - "id", - "workspace_id", - "hostname", - "target", - "protocol", - "routing_mode", - "ssl", - "status", - "created_at", - "updated_at", - "etag" - ] + "workspace_id" + ], + "additionalProperties": false }, - "CreateCustomDomainBody": { + "PackageCockpitResource": { "type": "object", "properties": { - "hostname": { + "package_id": { "type": "string", "minLength": 1, - "maxLength": 253 - }, - "target": { - "oneOf": [ - { - "type": "object", - "properties": { - "kind": { - "type": "string", - "enum": [ - "install" - ] - }, - "install_id": { - "type": "string", - "minLength": 1, - "maxLength": 55 - } - }, - "required": [ - "kind", - "install_id" - ], - "additionalProperties": false - }, - { - "type": "object", - "properties": { - "kind": { - "type": "string", - "enum": [ - "cluster" - ] - }, - "cluster_id": { - "type": "string", - "minLength": 1, - "maxLength": 54 - } - }, - "required": [ - "kind", - "cluster_id" - ], - "additionalProperties": false - }, - { - "type": "object", - "properties": { - "kind": { - "type": "string", - "enum": [ - "external" - ] - }, - "endpoint": { - "type": "string", - "format": "uri" - }, - "mtls_secret_id": { - "type": "string", - "minLength": 1, - "maxLength": 54 - } - }, - "required": [ - "kind", - "endpoint" - ], - "additionalProperties": false - } - ] + "maxLength": 54 }, - "protocol": { + "package_version_id": { "type": "string", - "enum": [ - "http", - "websocket", - "grpc" - ], - "default": "http", - "description": "Transport class for route forwarding." + "minLength": 1, + "maxLength": 55 }, - "routing_mode": { + "workspace_id": { "type": "string", - "enum": [ - "through_dispatcher", - "bypass_dispatcher" - ], - "default": "through_dispatcher", - "description": "Whether traffic uses the dispatcher Worker or bypasses it." + "minLength": 1, + "maxLength": 53 } }, "required": [ - "hostname", - "target" + "workspace_id" ], "additionalProperties": false }, - "UpdateCustomDomainBody": { + "ClusterCockpitResource": { "type": "object", "properties": { - "target": { - "oneOf": [ - { - "type": "object", - "properties": { - "kind": { - "type": "string", - "enum": [ - "install" - ] - }, - "install_id": { - "type": "string", - "minLength": 1, - "maxLength": 55 - } - }, - "required": [ - "kind", - "install_id" - ], - "additionalProperties": false - }, - { - "type": "object", - "properties": { - "kind": { - "type": "string", - "enum": [ - "cluster" - ] - }, - "cluster_id": { - "type": "string", - "minLength": 1, - "maxLength": 54 - } - }, - "required": [ - "kind", - "cluster_id" - ], - "additionalProperties": false - }, - { - "type": "object", - "properties": { - "kind": { - "type": "string", - "enum": [ - "external" - ] - }, - "endpoint": { - "type": "string", - "format": "uri" - }, - "mtls_secret_id": { - "type": "string", - "minLength": 1, - "maxLength": 54 - } - }, - "required": [ - "kind", - "endpoint" - ], - "additionalProperties": false - } - ] - }, - "protocol": { + "workspace_id": { "type": "string", - "enum": [ - "http", - "websocket", - "grpc" - ], - "description": "Transport class for route forwarding." + "minLength": 1, + "maxLength": 53 }, - "routing_mode": { + "cluster_id": { "type": "string", - "enum": [ - "through_dispatcher", - "bypass_dispatcher" - ], - "description": "Whether traffic uses the dispatcher Worker or bypasses it." + "minLength": 1, + "maxLength": 54 } }, + "required": [ + "workspace_id", + "cluster_id" + ], "additionalProperties": false }, - "CloudflareCredentialList": { + "MachineCockpitResource": { "type": "object", "properties": { - "data": { - "type": "array", - "items": { - "$ref": "#/components/schemas/CloudflareCredential" - } + "workspace_id": { + "type": "string", + "minLength": 1, + "maxLength": 53 }, - "has_more": { - "type": "boolean", - "description": "True if more items exist after this page." + "cluster_id": { + "type": "string", + "minLength": 1, + "maxLength": 54 }, - "next_cursor": { + "machine_id": { "type": "string", - "nullable": true, - "description": "Opaque cursor for the next page, or null if no more pages." + "minLength": 1, + "maxLength": 54 } }, "required": [ - "data", - "has_more", - "next_cursor" - ] + "workspace_id", + "cluster_id", + "machine_id" + ], + "additionalProperties": false }, - "CloudflareCredential": { + "CatalogActionExplainResource": { "type": "object", "properties": { - "id": { + "action_id": { "type": "string", - "minLength": 1, - "maxLength": 56 + "minLength": 1 }, - "name": { + "workspace_id": { "type": "string", - "example": "Production Cloudflare" + "minLength": 1, + "maxLength": 53 }, - "account_id": { + "organization_id": { "type": "string", - "description": "Cloudflare account ID." + "minLength": 1, + "maxLength": 54 }, - "origin_zone_id": { + "user_id": { "type": "string", - "nullable": true, - "description": "Cloudflare zone ID used for Access-protected origin hostnames." + "minLength": 1 }, - "origin_hostname_suffix": { + "product_id": { "type": "string", - "nullable": true, - "description": "Hostname suffix used for Access-protected origin hostnames." - }, - "is_active": { - "type": "boolean", - "description": "Whether the credential is active" - }, - "created_at": { - "type": "integer", - "minimum": 0, - "description": "Unix timestamp (seconds)" + "minLength": 1, + "maxLength": 55 }, - "last_used_at": { - "type": "integer", - "nullable": true, - "minimum": 0, - "description": "Unix timestamp (seconds), null if never used" - } - }, - "required": [ - "id", - "name", - "account_id", - "origin_zone_id", - "origin_hostname_suffix", - "is_active", - "created_at", - "last_used_at" - ] - }, - "CreateCloudflareCredentialBody": { - "type": "object", - "properties": { - "name": { + "package_id": { "type": "string", "minLength": 1, - "maxLength": 100, - "example": "Production Cloudflare" + "maxLength": 54 }, - "account_id": { + "package_version_id": { "type": "string", "minLength": 1, - "maxLength": 200, - "pattern": "^[A-Za-z0-9_-]+$", - "description": "Cloudflare account ID." + "maxLength": 55 }, - "origin_zone_id": { + "offer_id": { "type": "string", "minLength": 1, - "maxLength": 200, - "pattern": "^[A-Za-z0-9_-]+$", - "description": "Cloudflare zone ID used for Access-protected origin hostnames." + "maxLength": 56 }, - "origin_hostname_suffix": { + "offer_channel_id": { "type": "string", "minLength": 1, - "maxLength": 253, - "description": "Hostname suffix used for Access-protected origin hostnames." + "maxLength": 54 }, - "api_token": { + "channel_policy_id": { "type": "string", "minLength": 1, - "maxLength": 2000, - "description": "Cloudflare API token. Stored as a platform Secret; never returned." + "maxLength": 56 } }, "required": [ - "name", - "account_id", - "origin_zone_id", - "origin_hostname_suffix", - "api_token" + "action_id" ], - "additionalProperties": false + "additionalProperties": false, + "x-platform-visibility": "ADMIN" }, - "AccessDecision": { + "AccessDecisionBatch": { "type": "object", "properties": { - "decision": { - "$ref": "#/components/schemas/AccessDecisionResult" - }, - "action": { - "type": "object", - "properties": { - "id": { - "type": "string", - "minLength": 1 - }, - "name": { - "type": "string", - "minLength": 1 - } - }, - "required": [ - "id", - "name" - ], - "additionalProperties": false - }, - "reasons": { + "decisions": { "type": "array", "items": { - "$ref": "#/components/schemas/AccessReason" - } + "$ref": "#/components/schemas/AccessDecision" + }, + "minItems": 1, + "maxItems": 25 } }, "required": [ - "decision", - "action", - "reasons" + "decisions" ], "additionalProperties": false }, - "AccessDecisionResult": { - "oneOf": [ - { - "type": "object", - "properties": { - "result": { - "type": "string", - "enum": [ - "allowed" - ] - } + "ExplainAccessDecisionsBatchBody": { + "type": "object", + "properties": { + "requests": { + "type": "array", + "items": { + "$ref": "#/components/schemas/ExplainAccessDecisionBody" }, - "required": [ - "result" - ], - "additionalProperties": false + "minItems": 1, + "maxItems": 25 + } + }, + "required": [ + "requests" + ], + "additionalProperties": false + }, + "AdminCapabilityList": { + "type": "object", + "properties": { + "data": { + "type": "array", + "items": { + "$ref": "#/components/schemas/AdminCapability" + } }, - { - "type": "object", - "properties": { - "result": { - "type": "string", - "enum": [ - "denied" - ] - }, - "message": { - "type": "string", - "minLength": 1 - } - }, - "required": [ - "result", - "message" - ], - "additionalProperties": false + "has_more": { + "type": "boolean", + "description": "True if more items exist after this page." }, - { - "type": "object", - "properties": { - "result": { - "type": "string", - "enum": [ - "unknown" - ] - }, - "message": { - "type": "string", - "minLength": 1 - } - }, - "required": [ - "result", - "message" - ], - "additionalProperties": false + "next_cursor": { + "type": "string", + "nullable": true, + "description": "Opaque cursor for the next page, or null if no more pages." } - ] + }, + "required": [ + "data", + "has_more", + "next_cursor" + ], + "x-platform-visibility": "ADMIN" }, - "AccessReason": { + "AdminCapability": { "type": "object", "properties": { - "kind": { - "type": "string", - "enum": [ - "catalog_default", - "external_feature_flag", - "external_billing_entitlement", - "workspace_access_status", - "admin_override", - "policy_rule", - "quota_limit", - "quota_usage", - "quota_override", - "actor_context", - "resource_state", - "workspace_membership", - "workspace_role", - "organization_membership", - "organization_role", - "workspace_class", - "resource_ownership", - "relationship", - "domain_policy" - ] - }, - "result": { + "id": { "type": "string", - "enum": [ - "allowed", - "denied", - "not_evaluated" - ] - }, - "key": { - "type": "string" - }, - "source": { - "type": "string" + "example": "networking" }, - "message": { + "name": { "type": "string" }, - "metric": { + "owner": { "type": "string" }, - "scope": { - "type": "string", - "enum": [ - "global", - "organization", - "workspace", - "user" - ] + "surfaces": { + "type": "array", + "items": { + "type": "string", + "enum": [ + "web", + "api", + "worker", + "docs" + ] + } }, - "limit": { - "type": "number" + "actions": { + "type": "array", + "items": { + "$ref": "#/components/schemas/AdminCapabilityAction" + } }, - "usage": { - "type": "number" + "flags": { + "type": "array", + "items": { + "type": "string" + } }, - "remaining": { - "type": "number" + "entitlements": { + "type": "array", + "items": { + "type": "string" + } + } + }, + "required": [ + "id", + "name", + "owner", + "surfaces", + "actions", + "flags", + "entitlements" + ], + "x-platform-visibility": "ADMIN" + }, + "AdminCapabilityAction": { + "type": "object", + "properties": { + "id": { + "type": "string", + "example": "custom_domains.use_dispatcher_bypass" }, - "resourceId": { + "name": { "type": "string" }, - "resourceType": { - "type": "string" + "access": { + "$ref": "#/components/schemas/AdminCapabilityActionAccess" }, - "relationship": { - "type": "string" + "quota_metrics": { + "type": "array", + "items": { + "type": "string" + } + }, + "operations": { + "type": "array", + "items": { + "type": "string" + } } }, "required": [ - "kind", - "result" + "id", + "name", + "access" ], - "additionalProperties": false + "x-platform-visibility": "ADMIN" }, - "ExplainAccessDecisionBody": { + "AdminCapabilityActionAccess": { "oneOf": [ { "type": "object", "properties": { - "subject": { - "$ref": "#/components/schemas/AccessSubject" - }, - "permission": { - "type": "string", - "enum": [ - "offers.create_via_channel" - ] - }, - "resource": { - "$ref": "#/components/schemas/OfferChannelCreateResource" - }, - "context": { - "$ref": "#/components/schemas/OfferChannelDecisionContext" - } - }, - "required": [ - "permission", - "resource" - ], - "additionalProperties": false - }, - { - "type": "object", - "properties": { - "subject": { - "$ref": "#/components/schemas/AccessSubject" - }, - "permission": { - "type": "string", - "enum": [ - "offers.create_non_channel_paid_product_offer" - ] - }, - "resource": { - "$ref": "#/components/schemas/NonChannelPaidProductOfferResource" - } - }, - "required": [ - "permission", - "resource" - ], - "additionalProperties": false - }, - { - "type": "object", - "properties": { - "subject": { - "$ref": "#/components/schemas/AccessSubject" - }, - "permission": { - "type": "string", - "enum": [ - "offers.create_non_billable_test_offer" - ] - }, - "resource": { - "$ref": "#/components/schemas/NonBillableTestOfferResource" - } - }, - "required": [ - "permission", - "resource" - ], - "additionalProperties": false - }, - { - "type": "object", - "properties": { - "subject": { - "$ref": "#/components/schemas/AccessSubject" - }, - "permission": { - "type": "string", - "enum": [ - "offer_channels.create" - ] - }, - "resource": { - "$ref": "#/components/schemas/OfferChannelCreateDecisionResource" - } - }, - "required": [ - "permission", - "resource" - ], - "additionalProperties": false - }, - { - "type": "object", - "properties": { - "subject": { - "$ref": "#/components/schemas/AccessSubject" - }, - "permission": { - "type": "string", - "enum": [ - "offer_channels.inspect" - ] - }, - "resource": { - "$ref": "#/components/schemas/OfferChannelInspectResource" - } - }, - "required": [ - "permission", - "resource" - ], - "additionalProperties": false - }, - { - "type": "object", - "properties": { - "subject": { - "$ref": "#/components/schemas/AccessSubject" - }, - "permission": { - "type": "string", - "enum": [ - "channel_policies.approve" - ] - }, - "resource": { - "$ref": "#/components/schemas/ChannelPolicyApproveResource" - } - }, - "required": [ - "permission", - "resource" - ], - "additionalProperties": false - }, - { - "type": "object", - "properties": { - "subject": { - "$ref": "#/components/schemas/AccessSubject" - }, - "permission": { - "type": "string", - "enum": [ - "channel_policies.activate" - ] - }, - "resource": { - "$ref": "#/components/schemas/ChannelPolicyActivateResource" - } - }, - "required": [ - "permission", - "resource" - ], - "additionalProperties": false - }, - { - "type": "object", - "properties": { - "subject": { - "$ref": "#/components/schemas/AccessSubject" - }, - "permission": { - "type": "string", - "enum": [ - "offers.approve_channel_offer" - ] - }, - "resource": { - "$ref": "#/components/schemas/OfferChannelModerationResource" - }, - "context": { - "$ref": "#/components/schemas/OfferChannelDecisionContext" - } - }, - "required": [ - "permission", - "resource" - ], - "additionalProperties": false - }, - { - "type": "object", - "properties": { - "subject": { - "$ref": "#/components/schemas/AccessSubject" - }, - "permission": { - "type": "string", - "enum": [ - "offers.reject_channel_offer" - ] - }, - "resource": { - "$ref": "#/components/schemas/OfferChannelModerationResource" - }, - "context": { - "$ref": "#/components/schemas/OfferChannelDecisionContext" - } - }, - "required": [ - "permission", - "resource" - ], - "additionalProperties": false - }, - { - "type": "object", - "properties": { - "subject": { - "$ref": "#/components/schemas/AccessSubject" - }, - "permission": { - "type": "string", - "enum": [ - "workspaces.inspect_class" - ] - }, - "resource": { - "$ref": "#/components/schemas/WorkspaceClassResource" - } - }, - "required": [ - "permission", - "resource" - ], - "additionalProperties": false - }, - { - "type": "object", - "properties": { - "subject": { - "$ref": "#/components/schemas/AccessSubject" - }, - "permission": { + "kind": { "type": "string", "enum": [ - "workspaces.inspect_membership" + "baseline" ] }, - "resource": { - "$ref": "#/components/schemas/WorkspaceMembershipResource" + "reason": { + "type": "string" } }, - "required": [ - "permission", - "resource" - ], - "additionalProperties": false + "required": [ + "kind", + "reason" + ] }, { "type": "object", "properties": { - "subject": { - "$ref": "#/components/schemas/AccessSubject" - }, - "permission": { + "kind": { "type": "string", "enum": [ - "products.create" + "feature_flagged" ] }, - "resource": { - "$ref": "#/components/schemas/ProductCockpitResource" + "flags": { + "type": "array", + "items": { + "type": "string" + } } }, "required": [ - "permission" - ], - "additionalProperties": false + "kind", + "flags" + ] }, { "type": "object", "properties": { - "subject": { - "$ref": "#/components/schemas/AccessSubject" - }, - "permission": { + "kind": { "type": "string", "enum": [ - "products.get" + "entitled" ] }, - "resource": { - "type": "object", - "properties": { - "product_id": { - "type": "string", - "minLength": 1, - "maxLength": 55 - }, - "workspace_id": { - "type": "string", - "minLength": 1, - "maxLength": 53 - }, - "package_id": { - "type": "string", - "minLength": 1, - "maxLength": 54 - }, - "package_version_id": { - "type": "string", - "minLength": 1, - "maxLength": 55 - }, - "resource_state": { - "type": "string", - "enum": [ - "draft", - "active", - "archived" - ] - } - }, - "required": [ - "product_id", - "workspace_id" - ], - "additionalProperties": false + "entitlements": { + "type": "array", + "items": { + "type": "string" + } } }, "required": [ - "permission", - "resource" - ], - "additionalProperties": false + "kind", + "entitlements" + ] }, { "type": "object", "properties": { - "subject": { - "$ref": "#/components/schemas/AccessSubject" - }, - "permission": { + "kind": { "type": "string", "enum": [ - "products.update" + "admin" ] }, - "resource": { - "type": "object", - "properties": { - "product_id": { - "type": "string", - "minLength": 1, - "maxLength": 55 - }, - "workspace_id": { - "type": "string", - "minLength": 1, - "maxLength": 53 - }, - "package_id": { - "type": "string", - "minLength": 1, - "maxLength": 54 - }, - "package_version_id": { - "type": "string", - "minLength": 1, - "maxLength": 55 - }, - "resource_state": { - "type": "string", - "enum": [ - "draft", - "active", - "archived" - ] - } - }, - "required": [ - "product_id", - "workspace_id" - ], - "additionalProperties": false + "reason": { + "type": "string" } }, "required": [ - "permission", - "resource" - ], - "additionalProperties": false + "kind", + "reason" + ] }, { "type": "object", "properties": { - "subject": { - "$ref": "#/components/schemas/AccessSubject" - }, - "permission": { + "kind": { "type": "string", "enum": [ - "products.archive" + "internal" ] }, - "resource": { - "type": "object", - "properties": { - "product_id": { - "type": "string", - "minLength": 1, - "maxLength": 55 - }, - "workspace_id": { - "type": "string", - "minLength": 1, - "maxLength": 53 - }, - "package_id": { - "type": "string", - "minLength": 1, - "maxLength": 54 - }, - "package_version_id": { - "type": "string", - "minLength": 1, - "maxLength": 55 - }, - "resource_state": { - "type": "string", - "enum": [ - "draft", - "active", - "archived" - ] - } - }, - "required": [ - "product_id", - "workspace_id" - ], - "additionalProperties": false + "reason": { + "type": "string" } }, "required": [ - "permission", - "resource" - ], - "additionalProperties": false + "kind", + "reason" + ] + } + ], + "x-platform-visibility": "ADMIN" + }, + "AdminDirectoryOrganizationList": { + "type": "object", + "properties": { + "data": { + "type": "array", + "items": { + "$ref": "#/components/schemas/AdminDirectoryOrganization" + } + }, + "has_more": { + "type": "boolean", + "description": "True if more items exist after this page." + }, + "next_cursor": { + "type": "string", + "nullable": true, + "description": "Opaque cursor for the next page, or null if no more pages." + } + }, + "required": [ + "data", + "has_more", + "next_cursor" + ], + "x-platform-visibility": "ADMIN" + }, + "AdminDirectoryOrganization": { + "type": "object", + "properties": { + "id": { + "type": "string", + "minLength": 1, + "maxLength": 54 + }, + "name": { + "type": "string" + }, + "slug": { + "type": "string", + "nullable": true + }, + "created_at": { + "type": "number" + }, + "member_count": { + "type": "integer", + "minimum": 0 + }, + "workspace_count": { + "type": "integer", + "minimum": 0 + } + }, + "required": [ + "id", + "name", + "slug", + "created_at", + "member_count", + "workspace_count" + ], + "x-platform-visibility": "ADMIN" + }, + "AdminDirectoryUserList": { + "type": "object", + "properties": { + "data": { + "type": "array", + "items": { + "$ref": "#/components/schemas/AdminDirectoryUser" + } + }, + "has_more": { + "type": "boolean", + "description": "True if more items exist after this page." + }, + "next_cursor": { + "type": "string", + "nullable": true, + "description": "Opaque cursor for the next page, or null if no more pages." + } + }, + "required": [ + "data", + "has_more", + "next_cursor" + ], + "x-platform-visibility": "ADMIN" + }, + "AdminDirectoryUser": { + "type": "object", + "properties": { + "id": { + "type": "string", + "minLength": 1 + }, + "name": { + "type": "string" + }, + "email": { + "type": "string", + "format": "email" + }, + "email_verified": { + "type": "boolean" + }, + "workspace_count": { + "type": "integer", + "minimum": 0 + }, + "organization_count": { + "type": "integer", + "minimum": 0 + }, + "created_at": { + "type": "number" + } + }, + "required": [ + "id", + "name", + "email", + "email_verified", + "workspace_count", + "organization_count", + "created_at" + ], + "x-platform-visibility": "ADMIN" + }, + "AdminDirectoryWorkspaceList": { + "type": "object", + "properties": { + "data": { + "type": "array", + "items": { + "$ref": "#/components/schemas/AdminDirectoryWorkspace" + } + }, + "has_more": { + "type": "boolean", + "description": "True if more items exist after this page." + }, + "next_cursor": { + "type": "string", + "nullable": true, + "description": "Opaque cursor for the next page, or null if no more pages." + } + }, + "required": [ + "data", + "has_more", + "next_cursor" + ], + "x-platform-visibility": "ADMIN" + }, + "AdminDirectoryWorkspace": { + "type": "object", + "properties": { + "id": { + "type": "string", + "minLength": 1, + "maxLength": 53 + }, + "name": { + "type": "string" + }, + "slug": { + "type": "string" + }, + "organization_id": { + "type": "string", + "minLength": 1, + "maxLength": 54 + }, + "organization_name": { + "type": "string" + }, + "workspace_class": { + "type": "string", + "enum": [ + "standard", + "platform", + "sandbox" + ] + }, + "plan_tier": { + "type": "string" + }, + "access_status": { + "type": "string", + "enum": [ + "active", + "payment_grace", + "restricted", + "suspended", + "ended", + "reactivating" + ] + }, + "accessible": { + "type": "boolean" + }, + "member_count": { + "type": "integer", + "minimum": 0 + }, + "cluster_count": { + "type": "integer", + "minimum": 0 + }, + "product_count": { + "type": "integer", + "minimum": 0 + }, + "operation_count": { + "type": "integer", + "minimum": 0 + }, + "created_at": { + "type": "number" + } + }, + "required": [ + "id", + "name", + "slug", + "workspace_class", + "plan_tier", + "member_count", + "cluster_count", + "product_count", + "operation_count", + "created_at" + ], + "x-platform-visibility": "ADMIN" + }, + "AdminAccessOverrideList": { + "type": "object", + "properties": { + "data": { + "type": "array", + "items": { + "$ref": "#/components/schemas/AdminAccessOverride" + } + }, + "has_more": { + "type": "boolean", + "description": "True if more items exist after this page." + }, + "next_cursor": { + "type": "string", + "nullable": true, + "description": "Opaque cursor for the next page, or null if no more pages." + } + }, + "required": [ + "data", + "has_more", + "next_cursor" + ], + "x-platform-visibility": "ADMIN" + }, + "AdminAccessOverride": { + "type": "object", + "properties": { + "id": { + "type": "string" + }, + "target_type": { + "type": "string", + "enum": [ + "feature_flag", + "entitlement" + ] + }, + "key": { + "type": "string" + }, + "scope": { + "type": "string", + "enum": [ + "global", + "organization", + "workspace" + ] + }, + "organization_id": { + "type": "string", + "minLength": 1, + "maxLength": 54 + }, + "workspace_id": { + "type": "string", + "minLength": 1, + "maxLength": 53 + }, + "effect": { + "type": "string", + "enum": [ + "allow", + "deny" + ] + }, + "previous_effect": { + "type": "string", + "nullable": true, + "enum": [ + "allow", + "deny", + null + ] + }, + "new_effect": { + "type": "string", + "nullable": true, + "enum": [ + "allow", + "deny", + null + ] + }, + "reason": { + "type": "string" + }, + "created_by": { + "type": "string", + "minLength": 1 + }, + "created_at": { + "type": "number" + }, + "updated_by": { + "type": "string", + "minLength": 1 + }, + "updated_at": { + "type": "number" + }, + "expires_at": { + "type": "number" }, + "revoked_at": { + "type": "number" + } + }, + "required": [ + "id", + "target_type", + "key", + "scope", + "effect", + "previous_effect", + "new_effect", + "reason", + "created_by", + "created_at", + "updated_by", + "updated_at" + ], + "x-platform-visibility": "ADMIN" + }, + "CreateAdminAccessOverrideBody": { + "oneOf": [ { "type": "object", "properties": { - "subject": { - "$ref": "#/components/schemas/AccessSubject" - }, - "permission": { + "target_type": { "type": "string", "enum": [ - "products.unarchive" + "feature_flag", + "entitlement" ] }, - "resource": { - "type": "object", - "properties": { - "product_id": { - "type": "string", - "minLength": 1, - "maxLength": 55 - }, - "workspace_id": { - "type": "string", - "minLength": 1, - "maxLength": 53 - }, - "package_id": { - "type": "string", - "minLength": 1, - "maxLength": 54 - }, - "package_version_id": { - "type": "string", - "minLength": 1, - "maxLength": 55 - }, - "resource_state": { - "type": "string", - "enum": [ - "draft", - "active", - "archived" - ] - } - }, - "required": [ - "product_id", - "workspace_id" - ], - "additionalProperties": false - } - }, - "required": [ - "permission", - "resource" - ], - "additionalProperties": false - }, - { - "type": "object", - "properties": { - "subject": { - "$ref": "#/components/schemas/AccessSubject" + "key": { + "type": "string", + "minLength": 1, + "maxLength": 256 }, - "permission": { + "effect": { "type": "string", "enum": [ - "products.inspect_readiness" + "allow", + "deny" ] }, - "resource": { - "type": "object", - "properties": { - "product_id": { - "type": "string", - "minLength": 1, - "maxLength": 55 - }, - "workspace_id": { - "type": "string", - "minLength": 1, - "maxLength": 53 - }, - "package_id": { - "type": "string", - "minLength": 1, - "maxLength": 54 - }, - "package_version_id": { - "type": "string", - "minLength": 1, - "maxLength": 55 - }, - "resource_state": { - "type": "string", - "enum": [ - "draft", - "active", - "archived" - ] - } - }, - "required": [ - "product_id", - "workspace_id" - ], - "additionalProperties": false - } - }, - "required": [ - "permission", - "resource" - ], - "additionalProperties": false - }, - { - "type": "object", - "properties": { - "subject": { - "$ref": "#/components/schemas/AccessSubject" - }, - "permission": { + "reason": { "type": "string", - "enum": [ - "products.inspect_offer_creation" - ] + "minLength": 1, + "maxLength": 500 }, - "resource": { - "type": "object", - "properties": { - "product_id": { - "type": "string", - "minLength": 1, - "maxLength": 55 - }, - "workspace_id": { - "type": "string", - "minLength": 1, - "maxLength": 53 - }, - "package_id": { - "type": "string", - "minLength": 1, - "maxLength": 54 - }, - "package_version_id": { - "type": "string", - "minLength": 1, - "maxLength": 55 - }, - "resource_state": { - "type": "string", - "enum": [ - "draft", - "active", - "archived" - ] - } - }, - "required": [ - "product_id", - "workspace_id" - ], - "additionalProperties": false - } - }, - "required": [ - "permission", - "resource" - ], - "additionalProperties": false - }, - { - "type": "object", - "properties": { - "subject": { - "$ref": "#/components/schemas/AccessSubject" + "expires_at": { + "type": "number" }, - "permission": { + "scope": { "type": "string", "enum": [ - "products.inspect_channels" + "global" ] - }, - "resource": { - "type": "object", - "properties": { - "product_id": { - "type": "string", - "minLength": 1, - "maxLength": 55 - }, - "workspace_id": { - "type": "string", - "minLength": 1, - "maxLength": 53 - }, - "package_id": { - "type": "string", - "minLength": 1, - "maxLength": 54 - }, - "package_version_id": { - "type": "string", - "minLength": 1, - "maxLength": 55 - }, - "resource_state": { - "type": "string", - "enum": [ - "draft", - "active", - "archived" - ] - } - }, - "required": [ - "product_id", - "workspace_id" - ], - "additionalProperties": false } }, "required": [ - "permission", - "resource" + "target_type", + "key", + "effect", + "reason", + "scope" ], "additionalProperties": false }, { "type": "object", "properties": { - "subject": { - "$ref": "#/components/schemas/AccessSubject" - }, - "permission": { + "target_type": { "type": "string", "enum": [ - "products.inspect_installs" + "feature_flag", + "entitlement" ] }, - "resource": { - "type": "object", - "properties": { - "product_id": { - "type": "string", - "minLength": 1, - "maxLength": 55 - }, - "workspace_id": { - "type": "string", - "minLength": 1, - "maxLength": 53 - }, - "package_id": { - "type": "string", - "minLength": 1, - "maxLength": 54 - }, - "package_version_id": { - "type": "string", - "minLength": 1, - "maxLength": 55 - }, - "resource_state": { - "type": "string", - "enum": [ - "draft", - "active", - "archived" - ] - } - }, - "required": [ - "product_id", - "workspace_id" - ], - "additionalProperties": false - } - }, - "required": [ - "permission", - "resource" - ], - "additionalProperties": false - }, - { - "type": "object", - "properties": { - "subject": { - "$ref": "#/components/schemas/AccessSubject" + "key": { + "type": "string", + "minLength": 1, + "maxLength": 256 }, - "permission": { + "effect": { "type": "string", "enum": [ - "packages.create" + "allow", + "deny" ] }, - "resource": { - "$ref": "#/components/schemas/PackageCockpitResource" - } - }, - "required": [ - "permission" - ], - "additionalProperties": false - }, - { - "type": "object", - "properties": { - "subject": { - "$ref": "#/components/schemas/AccessSubject" - }, - "permission": { + "reason": { "type": "string", - "enum": [ - "packages.import_published_package" - ] + "minLength": 1, + "maxLength": 500 }, - "resource": { - "$ref": "#/components/schemas/PackageCockpitResource" - } - }, - "required": [ - "permission" - ], - "additionalProperties": false - }, - { - "type": "object", - "properties": { - "subject": { - "$ref": "#/components/schemas/AccessSubject" + "expires_at": { + "type": "number" }, - "permission": { + "scope": { "type": "string", "enum": [ - "packages.get" + "organization" ] }, - "resource": { - "type": "object", - "properties": { - "package_id": { - "type": "string", - "minLength": 1, - "maxLength": 54 - }, - "package_version_id": { - "type": "string", - "minLength": 1, - "maxLength": 55 - }, - "workspace_id": { - "type": "string", - "minLength": 1, - "maxLength": 53 - } - }, - "required": [ - "package_id", - "workspace_id" - ], - "additionalProperties": false + "organization_id": { + "type": "string", + "minLength": 1, + "maxLength": 54 } }, "required": [ - "permission", - "resource" + "target_type", + "key", + "effect", + "reason", + "scope", + "organization_id" ], "additionalProperties": false }, { "type": "object", "properties": { - "subject": { - "$ref": "#/components/schemas/AccessSubject" - }, - "permission": { + "target_type": { "type": "string", "enum": [ - "package_versions.get" + "feature_flag", + "entitlement" ] }, - "resource": { - "type": "object", - "properties": { - "package_id": { - "type": "string", - "minLength": 1, - "maxLength": 54 - }, - "package_version_id": { - "type": "string", - "minLength": 1, - "maxLength": 55 - }, - "workspace_id": { - "type": "string", - "minLength": 1, - "maxLength": 53 - } - }, - "required": [ - "package_id", - "package_version_id", - "workspace_id" - ], - "additionalProperties": false - } - }, - "required": [ - "permission", - "resource" - ], - "additionalProperties": false - }, - { - "type": "object", - "properties": { - "subject": { - "$ref": "#/components/schemas/AccessSubject" + "key": { + "type": "string", + "minLength": 1, + "maxLength": 256 }, - "permission": { + "effect": { "type": "string", "enum": [ - "package_versions.inputs" + "allow", + "deny" ] }, - "resource": { - "type": "object", - "properties": { - "package_id": { - "type": "string", - "minLength": 1, - "maxLength": 54 - }, - "package_version_id": { - "type": "string", - "minLength": 1, - "maxLength": 55 - }, - "workspace_id": { - "type": "string", - "minLength": 1, - "maxLength": 53 - } - }, - "required": [ - "package_id", - "package_version_id", - "workspace_id" - ], - "additionalProperties": false - } - }, - "required": [ - "permission", - "resource" - ], - "additionalProperties": false - }, - { - "type": "object", - "properties": { - "subject": { - "$ref": "#/components/schemas/AccessSubject" + "reason": { + "type": "string", + "minLength": 1, + "maxLength": 500 }, - "permission": { + "expires_at": { + "type": "number" + }, + "scope": { "type": "string", "enum": [ - "catalog_actions.explain" + "workspace" ] }, - "resource": { - "$ref": "#/components/schemas/CatalogActionExplainResource" + "workspace_id": { + "type": "string", + "minLength": 1, + "maxLength": 53 } }, "required": [ - "permission", - "resource" + "target_type", + "key", + "effect", + "reason", + "scope", + "workspace_id" ], - "additionalProperties": false, - "x-platform-visibility": "ADMIN" + "additionalProperties": false + } + ], + "x-platform-visibility": "ADMIN", + "x-platform-exact-union": true + }, + "AdminQuotaOverrideList": { + "type": "object", + "properties": { + "data": { + "type": "array", + "items": { + "$ref": "#/components/schemas/AdminQuotaOverride" + } + }, + "has_more": { + "type": "boolean", + "description": "True if more items exist after this page." + }, + "next_cursor": { + "type": "string", + "nullable": true, + "description": "Opaque cursor for the next page, or null if no more pages." } - ] + }, + "required": [ + "data", + "has_more", + "next_cursor" + ], + "x-platform-visibility": "ADMIN" }, - "AccessSubject": { + "AdminQuotaOverride": { "type": "object", "properties": { - "user_id": { - "type": "string", - "minLength": 1 - }, - "organization_id": { + "id": { "type": "string", "minLength": 1, "maxLength": 54 }, + "scope": { + "type": "string", + "enum": [ + "user", + "workspace" + ] + }, + "user_id": { + "type": "string", + "minLength": 1 + }, "workspace_id": { "type": "string", "minLength": 1, "maxLength": 53 + }, + "metric": { + "type": "string" + }, + "limit": { + "type": "number" + }, + "previous_limit": { + "type": "number", + "nullable": true + }, + "new_limit": { + "type": "number", + "nullable": true + }, + "reason": { + "type": "string" + }, + "created_by": { + "type": "string", + "minLength": 1 + }, + "created_at": { + "type": "number" + }, + "updated_by": { + "type": "string", + "minLength": 1 + }, + "updated_at": { + "type": "number" + }, + "revoked_at": { + "type": "number" } }, - "additionalProperties": false + "required": [ + "id", + "scope", + "metric", + "limit", + "previous_limit", + "new_limit" + ], + "x-platform-visibility": "ADMIN" }, - "OfferChannelCreateResource": { + "SetAdminQuotaOverrideBody": { "type": "object", "properties": { - "offer_channel_id": { + "scope": { "type": "string", - "minLength": 1, - "maxLength": 54 + "enum": [ + "user", + "workspace" + ] }, - "target_workspace_id": { + "user_id": { + "type": "string", + "minLength": 1 + }, + "workspace_id": { "type": "string", "minLength": 1, "maxLength": 53 }, - "product_id": { + "metric": { "type": "string", "minLength": 1, - "maxLength": 55 + "maxLength": 256 }, - "commercial_mode": { + "limit": { + "type": "integer", + "minimum": 0 + }, + "reason": { "type": "string", - "enum": [ - "paid", - "non_billable_test" - ] + "minLength": 1, + "maxLength": 500 + } + }, + "required": [ + "scope", + "metric", + "limit", + "reason" + ], + "additionalProperties": false, + "x-platform-visibility": "ADMIN" + } + }, + "parameters": {} + }, + "paths": { + "/v1/snippets": { + "get": { + "x-platform-visibility": "PUBLIC", + "x-platform-live": { + "visibility": "INTERNAL", + "transport": "convex", + "convexQuery": "snippet.ui.listSnippetsForApi" + }, + "operationId": "snippets.list", + "tags": [ + "Snippets" + ], + "summary": "List snippets in workspace", + "description": "Returns all snippets belonging to the workspace specified in the workspace context.", + "security": [ + { + "BearerAuth": [] + } + ], + "parameters": [ + { + "schema": { + "type": "string", + "description": "Pagination cursor from a previous response's `next_cursor`." + }, + "required": false, + "description": "Pagination cursor from a previous response's `next_cursor`.", + "name": "cursor", + "in": "query" + }, + { + "schema": { + "type": "integer", + "minimum": 1, + "maximum": 100, + "default": 50, + "description": "Items per page (1-100, default 50)", + "example": 50 + }, + "required": false, + "description": "Items per page (1-100, default 50)", + "name": "limit", + "in": "query" + }, + { + "schema": { + "type": "string", + "minLength": 1, + "maxLength": 53, + "description": "Optional workspace/scope context for the request. Carries a single workspace wire id (`ws_…`) today. Only needed for broad tokens — a workspace-owned token implies its workspace.", + "example": "ws_j572abc123def456" + }, + "required": false, + "description": "Optional workspace/scope context for the request. Carries a single workspace wire id (`ws_…`) today. Only needed for broad tokens — a workspace-owned token implies its workspace.", + "name": "akua-context", + "in": "header" + } + ], + "responses": { + "200": { + "description": "List of snippets", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/SnippetList" + } + } + } + }, + "401": { + "description": "Unauthorized", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } + } + } + }, + "403": { + "description": "Forbidden", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } + } + } + } + } + }, + "post": { + "x-platform-visibility": "PUBLIC", + "operationId": "snippets.create", + "tags": [ + "Snippets" + ], + "summary": "Create snippet", + "description": "Creates a reusable code snippet in the workspace. Snippets are async JavaScript functions executed in a sandboxed runtime with access to platform.request() for API calls.", + "security": [ + { + "BearerAuth": [] + } + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/CreateSnippetBody" + } + } + } + }, + "responses": { + "201": { + "description": "Snippet created", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "snippet_id": { + "type": "string" + } + }, + "required": [ + "snippet_id" + ] + } + } + } + }, + "401": { + "description": "Unauthorized", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } + } + } + }, + "403": { + "description": "Forbidden", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } + } + } + }, + "422": { + "description": "Unprocessable entity", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } + } + } + } + } + } + }, + "/v1/snippets:usage": { + "get": { + "x-platform-visibility": "PUBLIC", + "x-platform-live": { + "visibility": "INTERNAL", + "transport": "convex", + "convexQuery": "snippet.ui.listSnippetUsageForApi" + }, + "operationId": "snippets.listUsage", + "tags": [ + "Snippets" + ], + "summary": "List snippet dashboard usage in workspace", + "description": "Returns dashboard references for snippets in the workspace specified in the workspace context.", + "security": [ + { + "BearerAuth": [] + } + ], + "parameters": [ + { + "schema": { + "type": "string", + "minLength": 1, + "maxLength": 53, + "description": "Optional workspace/scope context for the request. Carries a single workspace wire id (`ws_…`) today. Only needed for broad tokens — a workspace-owned token implies its workspace.", + "example": "ws_j572abc123def456" + }, + "required": false, + "description": "Optional workspace/scope context for the request. Carries a single workspace wire id (`ws_…`) today. Only needed for broad tokens — a workspace-owned token implies its workspace.", + "name": "akua-context", + "in": "header" + } + ], + "responses": { + "200": { + "description": "Snippet dashboard usage", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/SnippetUsageList" + } + } + } + }, + "401": { + "description": "Unauthorized", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } + } + } + }, + "403": { + "description": "Forbidden", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } + } + } + } + } + } + }, + "/v1/snippets/{id}:usage": { + "get": { + "x-platform-visibility": "PUBLIC", + "x-platform-live": { + "visibility": "INTERNAL", + "transport": "convex", + "convexQuery": "snippet.ui.getSnippetUsageForApi" + }, + "operationId": "snippets.getUsage", + "tags": [ + "Snippets" + ], + "summary": "Get snippet dashboard usage", + "description": "Returns dashboard references for one snippet.", + "security": [ + { + "BearerAuth": [] + } + ], + "parameters": [ + { + "schema": { + "type": "string", + "minLength": 1, + "maxLength": 54, + "description": "Snippet ID" + }, + "required": true, + "description": "Snippet ID", + "name": "id", + "in": "path" + } + ], + "responses": { + "200": { + "description": "Snippet dashboard usage", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/SnippetUsage" + } + } + } + }, + "401": { + "description": "Unauthorized", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } + } + } + }, + "403": { + "description": "Forbidden", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } + } + } + }, + "404": { + "description": "Not found", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } + } + } + } + } + } + }, + "/v1/snippets/{id}": { + "get": { + "x-platform-visibility": "PUBLIC", + "x-platform-live": { + "visibility": "INTERNAL", + "transport": "convex", + "convexQuery": "snippet.ui.getSnippetForApi" + }, + "operationId": "snippets.get", + "tags": [ + "Snippets" + ], + "summary": "Get snippet details", + "description": "Returns a snippet including its code and display type.", + "security": [ + { + "BearerAuth": [] + } + ], + "parameters": [ + { + "schema": { + "type": "string", + "minLength": 1, + "maxLength": 54, + "description": "Snippet ID" + }, + "required": true, + "description": "Snippet ID", + "name": "id", + "in": "path" + } + ], + "responses": { + "200": { + "description": "Snippet details", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Snippet" + } + } + } + }, + "401": { + "description": "Unauthorized", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } + } + } + }, + "403": { + "description": "Forbidden", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } + } + } + }, + "404": { + "description": "Not found", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } + } + } + } + } + }, + "patch": { + "x-platform-visibility": "PUBLIC", + "operationId": "snippets.update", + "tags": [ + "Snippets" + ], + "summary": "Update snippet", + "description": "Updates snippet properties. Only provided fields are changed. Dashboards using this snippet will pick up code changes on next run.", + "security": [ + { + "BearerAuth": [] } - }, - "required": [ - "offer_channel_id", - "product_id", - "commercial_mode" ], - "additionalProperties": false - }, - "OfferChannelDecisionContext": { - "type": "object", - "properties": { - "selected_organization_id": { - "type": "string", - "minLength": 1, - "maxLength": 54 + "parameters": [ + { + "schema": { + "type": "string", + "minLength": 1, + "maxLength": 54, + "description": "Snippet ID" + }, + "required": true, + "description": "Snippet ID", + "name": "id", + "in": "path" }, - "stripe_mode": { - "type": "string", - "enum": [ - "live", - "test", - "sandbox" - ] + { + "schema": { + "type": "string", + "minLength": 1, + "maxLength": 256, + "description": "The `etag` of the resource version the client last read. Required on writes when the resource exposes an `etag` field. Mismatch returns 409 `ABORTED` with the current etag in the error metadata.", + "example": "42" + }, + "required": true, + "description": "The `etag` of the resource version the client last read. Required on writes when the resource exposes an `etag` field. Mismatch returns 409 `ABORTED` with the current etag in the error metadata.", + "name": "if-match", + "in": "header" } - }, - "additionalProperties": false - }, - "NonChannelPaidProductOfferResource": { - "type": "object", - "properties": { - "workspace_id": { - "type": "string", - "minLength": 1, - "maxLength": 53 - }, - "product_id": { - "type": "string", - "minLength": 1, - "maxLength": 55 - }, - "package_version_id": { - "type": "string", - "minLength": 1, - "maxLength": 55 - }, - "target_workspace_id": { - "type": "string", - "minLength": 1, - "maxLength": 53 - }, - "commercial_mode": { - "type": "string", - "enum": [ - "paid" - ] + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/UpdateSnippetBody" + } + } } }, - "required": [ - "workspace_id", - "product_id", - "package_version_id", - "commercial_mode" - ], - "additionalProperties": false - }, - "NonBillableTestOfferResource": { - "type": "object", - "properties": { - "workspace_id": { - "type": "string", - "minLength": 1, - "maxLength": 53 - }, - "product_id": { - "type": "string", - "minLength": 1, - "maxLength": 55 - }, - "package_version_id": { - "type": "string", - "minLength": 1, - "maxLength": 55 + "responses": { + "200": { + "description": "Snippet updated", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "snippet_id": { + "type": "string" + } + }, + "required": [ + "snippet_id" + ] + } + } + } }, - "target_workspace_id": { - "type": "string", - "minLength": 1, - "maxLength": 53 + "401": { + "description": "Unauthorized", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } + } + } }, - "target_workspace_class": { - "type": "string", - "enum": [ - "standard", - "platform", - "sandbox" - ] + "404": { + "description": "Not found", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } + } + } }, - "commercial_mode": { - "type": "string", - "enum": [ - "non_billable_test" - ] + "409": { + "description": "Conflict", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } + } + } } - }, - "required": [ - "workspace_id", - "product_id", - "package_version_id", - "commercial_mode" - ], - "additionalProperties": false + } }, - "OfferChannelCreateDecisionResource": { - "type": "object", - "properties": { - "workspace_id": { - "type": "string", - "minLength": 1, - "maxLength": 53 - }, - "product_id": { - "type": "string", - "minLength": 1, - "maxLength": 55 - }, - "partner_organization_id": { - "type": "string", - "minLength": 1, - "maxLength": 54 + "delete": { + "x-platform-visibility": "PUBLIC", + "operationId": "snippets.delete", + "tags": [ + "Snippets" + ], + "summary": "Archive snippet", + "description": "Archives a snippet while preserving its runs and dashboard revision history. Fails with 409 while an active dashboard references it.", + "security": [ + { + "BearerAuth": [] } - }, - "required": [ - "workspace_id" ], - "additionalProperties": false - }, - "OfferChannelInspectResource": { - "type": "object", - "properties": { - "workspace_id": { - "type": "string", - "minLength": 1, - "maxLength": 53 - }, - "offer_channel_id": { - "type": "string", - "minLength": 1, - "maxLength": 54 + "parameters": [ + { + "schema": { + "type": "string", + "minLength": 1, + "maxLength": 54, + "description": "Snippet ID" + }, + "required": true, + "description": "Snippet ID", + "name": "id", + "in": "path" }, - "product_id": { - "type": "string", - "minLength": 1, - "maxLength": 55 + { + "schema": { + "type": "string", + "minLength": 1, + "maxLength": 256, + "description": "The `etag` of the resource version the client last read. Required on writes when the resource exposes an `etag` field. Mismatch returns 409 `ABORTED` with the current etag in the error metadata.", + "example": "42" + }, + "required": true, + "description": "The `etag` of the resource version the client last read. Required on writes when the resource exposes an `etag` field. Mismatch returns 409 `ABORTED` with the current etag in the error metadata.", + "name": "if-match", + "in": "header" } - }, - "required": [ - "workspace_id" ], - "additionalProperties": false - }, - "ChannelPolicyApproveResource": { - "type": "object", - "properties": { - "workspace_id": { - "type": "string", - "minLength": 1, - "maxLength": 53 + "responses": { + "204": { + "description": "Snippet archived, or already archived" }, - "offer_channel_id": { - "type": "string", - "minLength": 1, - "maxLength": 54 + "401": { + "description": "Unauthorized", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } + } + } }, - "channel_policy_id": { - "type": "string", - "minLength": 1, - "maxLength": 56 + "404": { + "description": "Not found", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } + } + } }, - "resource_state": { - "type": "string", - "enum": [ - "draft" - ] + "409": { + "description": "Conflict", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } + } + } } - }, - "required": [ - "workspace_id", - "offer_channel_id", - "channel_policy_id", - "resource_state" + } + } + }, + "/v1/snippets:execute": { + "post": { + "x-platform-visibility": "PUBLIC", + "operationId": "snippets.execute", + "tags": [ + "Snippets" ], - "additionalProperties": false - }, - "ChannelPolicyActivateResource": { - "type": "object", - "properties": { - "workspace_id": { - "type": "string", - "minLength": 1, - "maxLength": 53 - }, - "offer_channel_id": { - "type": "string", - "minLength": 1, - "maxLength": 54 - }, - "channel_policy_id": { - "type": "string", - "minLength": 1, - "maxLength": 56 - }, - "resource_state": { - "type": "string", - "enum": [ - "approved" - ] + "summary": "Execute ad-hoc snippet code", + "description": "Executes ad-hoc JavaScript in the snippet sandbox and returns the synchronous result. Does not persist a snippet or run resource.", + "security": [ + { + "BearerAuth": [] } - }, - "required": [ - "workspace_id", - "offer_channel_id", - "channel_policy_id", - "resource_state" ], - "additionalProperties": false - }, - "OfferChannelModerationResource": { - "type": "object", - "properties": { - "offer_id": { - "type": "string", - "minLength": 1, - "maxLength": 56 - }, - "offer_channel_id": { - "type": "string", - "minLength": 1, - "maxLength": 54 - }, - "owner_workspace_id": { - "type": "string", - "minLength": 1, - "maxLength": 53 + "parameters": [ + { + "schema": { + "type": "string", + "minLength": 1, + "maxLength": 53, + "description": "Optional workspace/scope context for the request. Carries a single workspace wire id (`ws_…`) today. Only needed for broad tokens — a workspace-owned token implies its workspace.", + "example": "ws_j572abc123def456" + }, + "required": false, + "description": "Optional workspace/scope context for the request. Carries a single workspace wire id (`ws_…`) today. Only needed for broad tokens — a workspace-owned token implies its workspace.", + "name": "akua-context", + "in": "header" + } + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ExecuteSnippetBody" + } + } + } + }, + "responses": { + "200": { + "description": "Snippet execution result", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ExecuteSnippetResponse" + } + } + } }, - "resource_state": { - "type": "string", - "enum": [ - "pending_approval", - "approved", - "rejected" - ] + "401": { + "description": "Unauthorized", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } + } + } }, - "platform_policy_snapshot_id": { - "type": "string", - "minLength": 1, - "x-platform-visibility": "ADMIN" + "403": { + "description": "Forbidden", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } + } + } }, - "partner_price_band_key": { - "type": "string", - "minLength": 1, - "x-platform-visibility": "TRUSTED_PARTNER" + "422": { + "description": "Unprocessable entity", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } + } + } } - }, - "required": [ - "offer_id", - "offer_channel_id", - "owner_workspace_id", - "resource_state" + } + } + }, + "/v1/snippets/{id}:execute": { + "post": { + "x-platform-visibility": "PUBLIC", + "operationId": "snippets.executeStored", + "tags": [ + "Snippets" ], - "additionalProperties": false - }, - "WorkspaceClassResource": { - "type": "object", - "properties": { - "workspace_id": { - "type": "string", - "minLength": 1, - "maxLength": 53 - }, - "required_class": { - "type": "string", - "enum": [ - "standard", - "platform", - "sandbox" - ] + "summary": "Execute stored snippet", + "description": "Fetches a stored snippet by ID server-side, executes its code in the snippet sandbox, and returns the synchronous result.", + "security": [ + { + "BearerAuth": [] } - }, - "required": [ - "workspace_id" ], - "additionalProperties": false - }, - "WorkspaceMembershipResource": { - "type": "object", - "properties": { - "workspace_id": { - "type": "string", - "minLength": 1, - "maxLength": 53 - }, - "required_roles": { - "type": "array", - "items": { + "parameters": [ + { + "schema": { "type": "string", - "enum": [ - "owner", - "admin", - "member" - ] + "minLength": 1, + "maxLength": 54 + }, + "required": true, + "name": "id", + "in": "path" + } + ], + "requestBody": { + "required": false, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ExecuteStoredSnippetBody" + } } } }, - "required": [ - "workspace_id" - ], - "additionalProperties": false - }, - "ProductCockpitResource": { - "type": "object", - "properties": { - "product_id": { - "type": "string", - "minLength": 1, - "maxLength": 55 + "responses": { + "200": { + "description": "Snippet execution result", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ExecuteSnippetResponse" + } + } + } }, - "workspace_id": { - "type": "string", - "minLength": 1, - "maxLength": 53 + "401": { + "description": "Unauthorized", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } + } + } }, - "package_id": { - "type": "string", - "minLength": 1, - "maxLength": 54 + "404": { + "description": "Not found", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } + } + } }, - "package_version_id": { - "type": "string", - "minLength": 1, - "maxLength": 55 + "409": { + "description": "Conflict", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } + } + } }, - "resource_state": { - "type": "string", - "enum": [ - "draft", - "active", - "archived" - ] + "422": { + "description": "Unprocessable entity", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } + } + } } - }, - "required": [ - "workspace_id" + } + } + }, + "/v1/snippets/{id}/runs": { + "post": { + "x-platform-visibility": "PUBLIC", + "operationId": "snippets.createRun", + "tags": [ + "Snippets" ], - "additionalProperties": false - }, - "PackageCockpitResource": { - "type": "object", - "properties": { - "package_id": { - "type": "string", - "minLength": 1, - "maxLength": 54 - }, - "package_version_id": { - "type": "string", - "minLength": 1, - "maxLength": 55 - }, - "workspace_id": { - "type": "string", - "minLength": 1, - "maxLength": 53 + "summary": "Create snippet run", + "description": "Creates a new snippet run resource under a snippet and starts execution. Idempotent with Idempotency-Key; callers receive the created run resource and Location header.", + "security": [ + { + "BearerAuth": [] } - }, - "required": [ - "workspace_id" ], - "additionalProperties": false - }, - "CatalogActionExplainResource": { - "type": "object", - "properties": { - "action_id": { - "type": "string", - "minLength": 1 - }, - "workspace_id": { - "type": "string", - "minLength": 1, - "maxLength": 53 - }, - "organization_id": { - "type": "string", - "minLength": 1, - "maxLength": 54 - }, - "user_id": { - "type": "string", - "minLength": 1 + "parameters": [ + { + "schema": { + "type": "string", + "minLength": 1, + "maxLength": 54 + }, + "required": true, + "name": "id", + "in": "path" }, - "product_id": { - "type": "string", - "minLength": 1, - "maxLength": 55 + { + "schema": { + "type": "string", + "minLength": 1, + "maxLength": 53, + "description": "Optional workspace/scope context for the request. Carries a single workspace wire id (`ws_…`) today. Only needed for broad tokens — a workspace-owned token implies its workspace.", + "example": "ws_j572abc123def456" + }, + "required": false, + "description": "Optional workspace/scope context for the request. Carries a single workspace wire id (`ws_…`) today. Only needed for broad tokens — a workspace-owned token implies its workspace.", + "name": "akua-context", + "in": "header" }, - "package_id": { - "type": "string", - "minLength": 1, - "maxLength": 54 + { + "schema": { + "type": "string", + "minLength": 1, + "maxLength": 64, + "description": "Optional caller-supplied idempotency key. Any non-empty key up to 64 characters is accepted. Endpoint-specific documentation describes how the key is used.", + "example": "create-prod-2026-05-07" + }, + "required": false, + "description": "Optional caller-supplied idempotency key. Any non-empty key up to 64 characters is accepted. Endpoint-specific documentation describes how the key is used.", + "name": "idempotency-key", + "in": "header" + } + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/CreateSnippetRunBody" + } + } + } + }, + "responses": { + "201": { + "description": "Snippet run created", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/SnippetRun" + } + } + } }, - "package_version_id": { - "type": "string", - "minLength": 1, - "maxLength": 55 + "401": { + "description": "Unauthorized", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } + } + } }, - "offer_id": { - "type": "string", - "minLength": 1, - "maxLength": 56 + "403": { + "description": "Forbidden", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } + } + } }, - "offer_channel_id": { - "type": "string", - "minLength": 1, - "maxLength": 54 + "409": { + "description": "Conflict", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } + } + } }, - "channel_policy_id": { - "type": "string", - "minLength": 1, - "maxLength": 56 + "422": { + "description": "Unprocessable entity", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } + } + } } + } + }, + "get": { + "x-platform-visibility": "PUBLIC", + "x-platform-live": { + "visibility": "INTERNAL", + "transport": "convex", + "convexQuery": "snippet.ui.listSnippetRunsForApi" }, - "required": [ - "action_id" + "operationId": "snippets.listRuns", + "tags": [ + "Snippets" ], - "additionalProperties": false, - "x-platform-visibility": "ADMIN" - }, - "AdminCapabilityList": { - "type": "object", - "properties": { - "data": { - "type": "array", - "items": { - "$ref": "#/components/schemas/AdminCapability" - } - }, - "has_more": { - "type": "boolean", - "description": "True if more items exist after this page." - }, - "next_cursor": { - "type": "string", - "nullable": true, - "description": "Opaque cursor for the next page, or null if no more pages." + "summary": "List snippet runs", + "description": "Returns runs for a snippet. Use `view=basic` for a compact listing.", + "security": [ + { + "BearerAuth": [] } - }, - "required": [ - "data", - "has_more", - "next_cursor" ], - "x-platform-visibility": "ADMIN" - }, - "AdminCapability": { - "type": "object", - "properties": { - "id": { - "type": "string", - "example": "networking" + "parameters": [ + { + "schema": { + "type": "string", + "minLength": 1, + "maxLength": 54 + }, + "required": true, + "name": "id", + "in": "path" }, - "name": { - "type": "string" + { + "schema": { + "type": "string", + "description": "Pagination cursor from a previous response's `next_cursor`." + }, + "required": false, + "description": "Pagination cursor from a previous response's `next_cursor`.", + "name": "cursor", + "in": "query" }, - "owner": { - "type": "string" + { + "schema": { + "type": "integer", + "minimum": 1, + "maximum": 100, + "default": 50, + "description": "Items per page (1-100, default 50)", + "example": 50 + }, + "required": false, + "description": "Items per page (1-100, default 50)", + "name": "limit", + "in": "query" }, - "surfaces": { - "type": "array", - "items": { + { + "schema": { "type": "string", "enum": [ - "web", - "api", - "worker", - "docs" + "succeeded", + "failed", + "timed_out" ] - } + }, + "required": false, + "name": "state", + "in": "query" }, - "actions": { - "type": "array", - "items": { - "$ref": "#/components/schemas/AdminCapabilityAction" + { + "schema": { + "type": "string", + "enum": [ + "basic", + "full" + ], + "default": "basic", + "description": "Control whether output and error details are included." + }, + "required": false, + "description": "Control whether output and error details are included.", + "name": "view", + "in": "query" + } + ], + "responses": { + "200": { + "description": "List of snippet runs", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/SnippetRunList" + } + } } }, - "flags": { - "type": "array", - "items": { - "type": "string" + "401": { + "description": "Unauthorized", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } + } } }, - "entitlements": { - "type": "array", - "items": { - "type": "string" + "403": { + "description": "Forbidden", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } + } } } + } + } + }, + "/v1/snippets/{id}/runs/{run_id}": { + "get": { + "x-platform-visibility": "PUBLIC", + "x-platform-live": { + "visibility": "INTERNAL", + "transport": "convex", + "convexQuery": "snippet.ui.getSnippetRun" }, - "required": [ - "id", - "name", - "owner", - "surfaces", - "actions", - "flags", - "entitlements" + "operationId": "snippets.getRun", + "tags": [ + "Snippets" ], - "x-platform-visibility": "ADMIN" - }, - "AdminCapabilityAction": { - "type": "object", - "properties": { - "id": { - "type": "string", - "example": "custom_domains.use_dispatcher_bypass" + "summary": "Get snippet run", + "description": "Returns a single snippet run by ID.", + "security": [ + { + "BearerAuth": [] + } + ], + "parameters": [ + { + "schema": { + "type": "string", + "minLength": 1, + "maxLength": 54 + }, + "required": true, + "name": "id", + "in": "path" }, - "name": { - "type": "string" + { + "schema": { + "type": "string", + "minLength": 1, + "maxLength": 54 + }, + "required": true, + "name": "run_id", + "in": "path" + } + ], + "responses": { + "200": { + "description": "Snippet run details", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/SnippetRun" + } + } + } }, - "access": { - "$ref": "#/components/schemas/AdminCapabilityActionAccess" + "401": { + "description": "Unauthorized", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } + } + } }, - "quota_metrics": { - "type": "array", - "items": { - "type": "string" + "403": { + "description": "Forbidden", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } + } } }, - "operations": { - "type": "array", - "items": { - "type": "string" + "404": { + "description": "Not found", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } + } } } + } + } + }, + "/v1/snippet_runs": { + "get": { + "x-platform-visibility": "PUBLIC", + "x-platform-live": { + "visibility": "INTERNAL", + "transport": "convex", + "convexQuery": "snippet.ui.listWorkspaceSnippetRunsForApi" }, - "required": [ - "id", - "name", - "access" + "operationId": "snippetRuns.list", + "tags": [ + "Snippet Runs" ], - "x-platform-visibility": "ADMIN" - }, - "AdminCapabilityActionAccess": { - "oneOf": [ + "summary": "List workspace snippet runs", + "description": "Returns durable snippet execution activity for the selected workspace, newest first.", + "security": [ { - "type": "object", - "properties": { - "kind": { - "type": "string", - "enum": [ - "baseline" - ] - }, - "reason": { - "type": "string" - } + "BearerAuth": [] + } + ], + "parameters": [ + { + "schema": { + "type": "string", + "description": "Pagination cursor from a previous response's `next_cursor`." }, - "required": [ - "kind", - "reason" - ] + "required": false, + "description": "Pagination cursor from a previous response's `next_cursor`.", + "name": "cursor", + "in": "query" }, { - "type": "object", - "properties": { - "kind": { - "type": "string", - "enum": [ - "feature_flagged" - ] - }, - "flags": { - "type": "array", - "items": { - "type": "string" - } - } + "schema": { + "type": "integer", + "minimum": 1, + "maximum": 100, + "default": 50, + "description": "Items per page (1-100, default 50)", + "example": 50 }, - "required": [ - "kind", - "flags" - ] + "required": false, + "description": "Items per page (1-100, default 50)", + "name": "limit", + "in": "query" }, { - "type": "object", - "properties": { - "kind": { - "type": "string", - "enum": [ - "entitled" - ] - }, - "entitlements": { - "type": "array", - "items": { - "type": "string" - } - } + "schema": { + "type": "string", + "enum": [ + "succeeded", + "failed", + "timed_out" + ] }, - "required": [ - "kind", - "entitlements" - ] + "required": false, + "name": "state", + "in": "query" }, { - "type": "object", - "properties": { - "kind": { - "type": "string", - "enum": [ - "admin" - ] - }, - "reason": { - "type": "string" - } + "schema": { + "type": "string", + "enum": [ + "manual", + "dashboard_open", + "dashboard_refresh", + "agent" + ] }, - "required": [ - "kind", - "reason" - ] + "required": false, + "name": "source", + "in": "query" }, { - "type": "object", - "properties": { - "kind": { - "type": "string", - "enum": [ - "internal" - ] - }, - "reason": { - "type": "string" - } + "schema": { + "type": "string", + "minLength": 1, + "maxLength": 54 }, - "required": [ - "kind", - "reason" - ] + "required": false, + "name": "snippet", + "in": "query" + }, + { + "schema": { + "type": "string", + "minLength": 1, + "maxLength": 55 + }, + "required": false, + "name": "dashboard", + "in": "query" + }, + { + "schema": { + "type": "string", + "enum": [ + "basic", + "full" + ], + "default": "basic", + "description": "Control whether output and error details are included." + }, + "required": false, + "description": "Control whether output and error details are included.", + "name": "view", + "in": "query" + }, + { + "schema": { + "type": "string", + "minLength": 1, + "maxLength": 53, + "description": "Optional workspace/scope context for the request. Carries a single workspace wire id (`ws_…`) today. Only needed for broad tokens — a workspace-owned token implies its workspace.", + "example": "ws_j572abc123def456" + }, + "required": false, + "description": "Optional workspace/scope context for the request. Carries a single workspace wire id (`ws_…`) today. Only needed for broad tokens — a workspace-owned token implies its workspace.", + "name": "akua-context", + "in": "header" } ], - "x-platform-visibility": "ADMIN" - }, - "AdminDirectoryOrganizationList": { - "type": "object", - "properties": { - "data": { - "type": "array", - "items": { - "$ref": "#/components/schemas/AdminDirectoryOrganization" + "responses": { + "200": { + "description": "Workspace snippet-run history", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/SnippetRunList" + } + } } }, - "has_more": { - "type": "boolean", - "description": "True if more items exist after this page." + "401": { + "description": "Unauthorized", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } + } + } }, - "next_cursor": { - "type": "string", - "nullable": true, - "description": "Opaque cursor for the next page, or null if no more pages." + "403": { + "description": "Forbidden", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } + } + } } + } + } + }, + "/v1/snippet_runs/{id}": { + "get": { + "x-platform-visibility": "PUBLIC", + "x-platform-live": { + "visibility": "INTERNAL", + "transport": "convex", + "convexQuery": "snippet.ui.getWorkspaceSnippetRunForApi" }, - "required": [ - "data", - "has_more", - "next_cursor" + "operationId": "snippetRuns.get", + "tags": [ + "Snippet Runs" ], - "x-platform-visibility": "ADMIN" - }, - "AdminDirectoryOrganization": { - "type": "object", - "properties": { - "id": { - "type": "string", - "minLength": 1, - "maxLength": 54 - }, - "name": { - "type": "string" - }, - "slug": { - "type": "string", - "nullable": true - }, - "created_at": { - "type": "number" - }, - "member_count": { - "type": "integer", - "minimum": 0 - }, - "workspace_count": { - "type": "integer", - "minimum": 0 + "summary": "Get workspace snippet run", + "description": "Returns one durable snippet execution, including its terminal payload.", + "security": [ + { + "BearerAuth": [] } - }, - "required": [ - "id", - "name", - "slug", - "created_at", - "member_count", - "workspace_count" ], - "x-platform-visibility": "ADMIN" - }, - "AdminDirectoryUserList": { - "type": "object", - "properties": { - "data": { - "type": "array", - "items": { - "$ref": "#/components/schemas/AdminDirectoryUser" - } - }, - "has_more": { - "type": "boolean", - "description": "True if more items exist after this page." + "parameters": [ + { + "schema": { + "type": "string", + "minLength": 1, + "maxLength": 54 + }, + "required": true, + "name": "id", + "in": "path" }, - "next_cursor": { - "type": "string", - "nullable": true, - "description": "Opaque cursor for the next page, or null if no more pages." + { + "schema": { + "type": "string", + "minLength": 1, + "maxLength": 53, + "description": "Optional workspace/scope context for the request. Carries a single workspace wire id (`ws_…`) today. Only needed for broad tokens — a workspace-owned token implies its workspace.", + "example": "ws_j572abc123def456" + }, + "required": false, + "description": "Optional workspace/scope context for the request. Carries a single workspace wire id (`ws_…`) today. Only needed for broad tokens — a workspace-owned token implies its workspace.", + "name": "akua-context", + "in": "header" } - }, - "required": [ - "data", - "has_more", - "next_cursor" ], - "x-platform-visibility": "ADMIN" - }, - "AdminDirectoryUser": { - "type": "object", - "properties": { - "id": { - "type": "string", - "minLength": 1 - }, - "name": { - "type": "string" - }, - "email": { - "type": "string", - "format": "email" - }, - "email_verified": { - "type": "boolean" + "responses": { + "200": { + "description": "Snippet run details", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/SnippetRun" + } + } + } }, - "workspace_count": { - "type": "integer", - "minimum": 0 + "401": { + "description": "Unauthorized", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } + } + } }, - "organization_count": { - "type": "integer", - "minimum": 0 + "403": { + "description": "Forbidden", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } + } + } }, - "created_at": { - "type": "number" + "404": { + "description": "Not found", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } + } + } } - }, - "required": [ - "id", - "name", - "email", - "email_verified", - "workspace_count", - "organization_count", - "created_at" + } + } + }, + "/v1/dashboard_widget_results:resolve": { + "post": { + "x-platform-visibility": "INTERNAL", + "operationId": "dashboardWidgetResults.resolve", + "tags": [ + "Dashboard Overview" ], - "x-platform-visibility": "ADMIN" - }, - "AdminDirectoryWorkspaceList": { - "type": "object", - "properties": { - "data": { - "type": "array", - "items": { - "$ref": "#/components/schemas/AdminDirectoryWorkspace" - } - }, - "has_more": { - "type": "boolean", - "description": "True if more items exist after this page." - }, - "next_cursor": { - "type": "string", - "nullable": true, - "description": "Opaque cursor for the next page, or null if no more pages." + "summary": "Resolve dashboard widget result", + "description": "Returns the authenticated viewer's last successful matching snippet-widget result and freshness metadata.", + "security": [ + { + "BearerAuth": [] } - }, - "required": [ - "data", - "has_more", - "next_cursor" ], - "x-platform-visibility": "ADMIN" - }, - "AdminDirectoryWorkspace": { - "type": "object", - "properties": { - "id": { - "type": "string", - "minLength": 1, - "maxLength": 53 - }, - "name": { - "type": "string" - }, - "slug": { - "type": "string" - }, - "organization_id": { - "type": "string", - "minLength": 1, - "maxLength": 54 - }, - "organization_name": { - "type": "string" - }, - "workspace_class": { - "type": "string", - "enum": [ - "standard", - "platform", - "sandbox" - ] - }, - "plan_tier": { - "type": "string" - }, - "access_status": { - "type": "string", - "enum": [ - "active", - "payment_grace", - "restricted", - "suspended", - "ended", - "reactivating" - ] - }, - "accessible": { - "type": "boolean" - }, - "member_count": { - "type": "integer", - "minimum": 0 - }, - "cluster_count": { - "type": "integer", - "minimum": 0 - }, - "product_count": { - "type": "integer", - "minimum": 0 - }, - "operation_count": { - "type": "integer", - "minimum": 0 - }, - "created_at": { - "type": "number" + "parameters": [ + { + "schema": { + "type": "string", + "minLength": 1, + "maxLength": 53, + "description": "Optional workspace/scope context for the request. Carries a single workspace wire id (`ws_…`) today. Only needed for broad tokens — a workspace-owned token implies its workspace.", + "example": "ws_j572abc123def456" + }, + "required": false, + "description": "Optional workspace/scope context for the request. Carries a single workspace wire id (`ws_…`) today. Only needed for broad tokens — a workspace-owned token implies its workspace.", + "name": "akua-context", + "in": "header" } - }, - "required": [ - "id", - "name", - "slug", - "workspace_class", - "plan_tier", - "member_count", - "cluster_count", - "product_count", - "operation_count", - "created_at" ], - "x-platform-visibility": "ADMIN" - }, - "AdminAccessOverrideList": { - "type": "object", - "properties": { - "data": { - "type": "array", - "items": { - "$ref": "#/components/schemas/AdminAccessOverride" + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ResolveDashboardWidgetResultBody" + } } - }, - "has_more": { - "type": "boolean", - "description": "True if more items exist after this page." - }, - "next_cursor": { - "type": "string", - "nullable": true, - "description": "Opaque cursor for the next page, or null if no more pages." } }, - "required": [ - "data", - "has_more", - "next_cursor" - ], - "x-platform-visibility": "ADMIN" - }, - "AdminAccessOverride": { - "type": "object", - "properties": { - "id": { - "type": "string" - }, - "target_type": { - "type": "string", - "enum": [ - "feature_flag", - "entitlement" - ] - }, - "key": { - "type": "string" - }, - "scope": { - "type": "string", - "enum": [ - "global", - "organization", - "workspace" - ] - }, - "organization_id": { - "type": "string", - "minLength": 1, - "maxLength": 54 - }, - "workspace_id": { - "type": "string", - "minLength": 1, - "maxLength": 53 - }, - "effect": { - "type": "string", - "enum": [ - "allow", - "deny" - ] - }, - "previous_effect": { - "type": "string", - "nullable": true, - "enum": [ - "allow", - "deny", - null - ] - }, - "new_effect": { - "type": "string", - "nullable": true, - "enum": [ - "allow", - "deny", - null - ] - }, - "reason": { - "type": "string" - }, - "created_by": { - "type": "string", - "minLength": 1 - }, - "created_at": { - "type": "number" + "responses": { + "200": { + "description": "Matching widget result resolution", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/DashboardWidgetResultResolution" + } + } + } }, - "updated_by": { - "type": "string", - "minLength": 1 + "401": { + "description": "Unauthorized", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } + } + } }, - "updated_at": { - "type": "number" + "403": { + "description": "Forbidden", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } + } + } }, - "expires_at": { - "type": "number" + "404": { + "description": "Not found", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } + } + } }, - "revoked_at": { - "type": "number" + "422": { + "description": "Unprocessable entity", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } + } + } } + } + } + }, + "/v1/dashboards": { + "get": { + "x-platform-visibility": "PUBLIC", + "x-platform-live": { + "visibility": "INTERNAL", + "transport": "convex", + "convexQuery": "snippet.ui.listDashboardsForApi" }, - "required": [ - "id", - "target_type", - "key", - "scope", - "effect", - "previous_effect", - "new_effect", - "reason", - "created_by", - "created_at", - "updated_by", - "updated_at" + "operationId": "dashboards.list", + "tags": [ + "Dashboards" ], - "x-platform-visibility": "ADMIN" - }, - "CreateAdminAccessOverrideBody": { - "type": "object", - "properties": { - "target_type": { - "type": "string", - "enum": [ - "feature_flag", - "entitlement" - ] + "summary": "List dashboards in workspace", + "description": "Returns all dashboards belonging to the workspace specified in the workspace context.", + "security": [ + { + "BearerAuth": [] + } + ], + "parameters": [ + { + "schema": { + "type": "string", + "description": "Pagination cursor from a previous response's `next_cursor`." + }, + "required": false, + "description": "Pagination cursor from a previous response's `next_cursor`.", + "name": "cursor", + "in": "query" }, - "key": { - "type": "string", - "minLength": 1, - "maxLength": 256 + { + "schema": { + "type": "integer", + "minimum": 1, + "maximum": 100, + "default": 50, + "description": "Items per page (1-100, default 50)", + "example": 50 + }, + "required": false, + "description": "Items per page (1-100, default 50)", + "name": "limit", + "in": "query" }, - "scope": { - "type": "string", - "enum": [ - "global", - "organization", - "workspace" - ] + { + "schema": { + "type": "string", + "minLength": 1, + "maxLength": 53, + "description": "Optional workspace/scope context for the request. Carries a single workspace wire id (`ws_…`) today. Only needed for broad tokens — a workspace-owned token implies its workspace.", + "example": "ws_j572abc123def456" + }, + "required": false, + "description": "Optional workspace/scope context for the request. Carries a single workspace wire id (`ws_…`) today. Only needed for broad tokens — a workspace-owned token implies its workspace.", + "name": "akua-context", + "in": "header" + } + ], + "responses": { + "200": { + "description": "List of dashboards", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/DashboardList" + } + } + } }, - "organization_id": { - "type": "string", - "minLength": 1, - "maxLength": 54 + "401": { + "description": "Unauthorized", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } + } + } }, - "workspace_id": { - "type": "string", - "minLength": 1, - "maxLength": 53 + "403": { + "description": "Forbidden", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } + } + } + } + } + }, + "post": { + "x-platform-visibility": "PUBLIC", + "operationId": "dashboards.create", + "tags": [ + "Dashboards" + ], + "summary": "Create dashboard", + "description": "Creates a dashboard in the workspace, optionally with an ordered set of initial snippet widgets. Blank dashboards remain valid.", + "security": [ + { + "BearerAuth": [] + } + ], + "parameters": [ + { + "schema": { + "type": "string", + "minLength": 1, + "maxLength": 53, + "description": "Optional workspace/scope context for the request. Carries a single workspace wire id (`ws_…`) today. Only needed for broad tokens — a workspace-owned token implies its workspace.", + "example": "ws_j572abc123def456" + }, + "required": false, + "description": "Optional workspace/scope context for the request. Carries a single workspace wire id (`ws_…`) today. Only needed for broad tokens — a workspace-owned token implies its workspace.", + "name": "akua-context", + "in": "header" + } + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "name": { + "type": "string", + "minLength": 1, + "maxLength": 100, + "example": "Cluster Overview" + }, + "description": { + "type": "string", + "maxLength": 500 + }, + "widgets": { + "type": "array", + "items": { + "oneOf": [ + { + "type": "object", + "properties": { + "snippet_id": { + "type": "string", + "minLength": 1, + "maxLength": 54 + }, + "title": { + "type": "string", + "maxLength": 100 + }, + "display_type": { + "type": "string", + "enum": [ + "table", + "stat", + "json", + "logs", + "timeseries" + ], + "description": "Controls how the snippet result is rendered in dashboard widgets" + }, + "col_span": { + "anyOf": [ + { + "type": "number", + "enum": [ + 1 + ] + }, + { + "type": "number", + "enum": [ + 2 + ] + }, + { + "type": "number", + "enum": [ + 3 + ] + }, + { + "type": "number", + "enum": [ + 4 + ] + } + ], + "default": 2 + } + }, + "required": [ + "snippet_id" + ], + "additionalProperties": false + }, + { + "type": "object", + "properties": { + "widget_type": { + "type": "string", + "enum": [ + "snippet" + ] + }, + "snippet_id": { + "type": "string", + "minLength": 1, + "maxLength": 54 + }, + "snippet_etag": { + "type": "string", + "nullable": true, + "default": null + }, + "title": { + "type": "string", + "maxLength": 100 + }, + "col_span": { + "anyOf": [ + { + "type": "number", + "enum": [ + 1 + ] + }, + { + "type": "number", + "enum": [ + 2 + ] + }, + { + "type": "number", + "enum": [ + 3 + ] + }, + { + "type": "number", + "enum": [ + 4 + ] + } + ], + "default": 2 + }, + "height": { + "type": "string", + "enum": [ + "compact", + "standard", + "tall" + ], + "default": "standard" + }, + "drill_down": { + "type": "string", + "nullable": true, + "minLength": 1, + "maxLength": 2048, + "default": null + }, + "visualization_options": { + "type": "object", + "additionalProperties": { + "nullable": true + }, + "default": {} + }, + "freshness_policy": { + "oneOf": [ + { + "type": "object", + "properties": { + "mode": { + "type": "string", + "enum": [ + "provider_default" + ] + } + }, + "required": [ + "mode" + ], + "additionalProperties": false + }, + { + "type": "object", + "properties": { + "mode": { + "type": "string", + "enum": [ + "max_age" + ] + }, + "max_age_seconds": { + "type": "integer", + "minimum": 30, + "maximum": 86400 + } + }, + "required": [ + "mode", + "max_age_seconds" + ], + "additionalProperties": false + } + ], + "default": { + "mode": "provider_default" + } + }, + "input_bindings": { + "type": "object", + "additionalProperties": { + "oneOf": [ + { + "type": "object", + "properties": { + "mode": { + "type": "string", + "enum": [ + "inherit" + ] + }, + "filter_key": { + "anyOf": [ + { + "type": "string", + "enum": [ + "time", + "comparison", + "cluster", + "install", + "product", + "package", + "region", + "status" + ] + }, + { + "type": "string", + "pattern": "^var\\.[a-z][a-z0-9_]{0,31}$" + } + ] + } + }, + "required": [ + "mode", + "filter_key" + ], + "additionalProperties": false + }, + { + "type": "object", + "properties": { + "mode": { + "type": "string", + "enum": [ + "fixed" + ] + }, + "value": { + "nullable": true + } + }, + "required": [ + "mode", + "value" + ], + "additionalProperties": false + }, + { + "type": "object", + "properties": { + "mode": { + "type": "string", + "enum": [ + "unbound" + ] + } + }, + "required": [ + "mode" + ], + "additionalProperties": false + } + ] + }, + "default": {} + }, + "visualization": { + "type": "string", + "nullable": true, + "enum": [ + "stat", + "sparkline", + "line", + "area", + "bar", + "donut", + "table", + "status_list", + "logs", + "json", + null + ], + "default": null + }, + "refresh_policy": { + "oneOf": [ + { + "type": "object", + "properties": { + "mode": { + "type": "string", + "enum": [ + "on_load" + ] + } + }, + "required": [ + "mode" + ], + "additionalProperties": false + }, + { + "type": "object", + "properties": { + "mode": { + "type": "string", + "enum": [ + "manual" + ] + } + }, + "required": [ + "mode" + ], + "additionalProperties": false + }, + { + "type": "object", + "properties": { + "mode": { + "type": "string", + "enum": [ + "interval" + ] + }, + "interval_seconds": { + "type": "integer", + "minimum": 60, + "maximum": 86400 + } + }, + "required": [ + "mode", + "interval_seconds" + ], + "additionalProperties": false + } + ], + "default": { + "mode": "on_load" + } + }, + "display_type": { + "type": "string", + "nullable": true, + "enum": [ + "table", + "stat", + "json", + "logs", + "timeseries", + null + ], + "default": null, + "description": "Controls how the snippet result is rendered in dashboard widgets" + } + }, + "required": [ + "widget_type", + "snippet_id" + ], + "additionalProperties": false + }, + { + "type": "object", + "properties": { + "widget_type": { + "type": "string", + "enum": [ + "platform_metric" + ] + }, + "metric_key": { + "type": "string", + "minLength": 1, + "maxLength": 100, + "pattern": "^[a-z][a-z0-9_]*$" + }, + "metric_version": { + "type": "integer", + "minimum": 0, + "exclusiveMinimum": true + }, + "filter_bindings": { + "type": "object", + "additionalProperties": { + "oneOf": [ + { + "type": "object", + "properties": { + "mode": { + "type": "string", + "enum": [ + "inherit" + ] + }, + "filter_key": { + "anyOf": [ + { + "type": "string", + "enum": [ + "time", + "comparison", + "cluster", + "install", + "product", + "package", + "region", + "status" + ] + }, + { + "type": "string", + "pattern": "^var\\.[a-z][a-z0-9_]{0,31}$" + } + ] + } + }, + "required": [ + "mode", + "filter_key" + ], + "additionalProperties": false + }, + { + "type": "object", + "properties": { + "mode": { + "type": "string", + "enum": [ + "fixed" + ] + }, + "value": { + "nullable": true + } + }, + "required": [ + "mode", + "value" + ], + "additionalProperties": false + }, + { + "type": "object", + "properties": { + "mode": { + "type": "string", + "enum": [ + "unbound" + ] + } + }, + "required": [ + "mode" + ], + "additionalProperties": false + } + ] + }, + "default": {} + }, + "title": { + "type": "string", + "maxLength": 100 + }, + "col_span": { + "anyOf": [ + { + "type": "number", + "enum": [ + 1 + ] + }, + { + "type": "number", + "enum": [ + 2 + ] + }, + { + "type": "number", + "enum": [ + 3 + ] + }, + { + "type": "number", + "enum": [ + 4 + ] + } + ], + "default": 2 + }, + "height": { + "type": "string", + "enum": [ + "compact", + "standard", + "tall" + ], + "default": "standard" + }, + "drill_down": { + "type": "string", + "nullable": true, + "minLength": 1, + "maxLength": 2048, + "default": null + }, + "visualization_options": { + "type": "object", + "additionalProperties": { + "nullable": true + }, + "default": {} + }, + "freshness_policy": { + "oneOf": [ + { + "type": "object", + "properties": { + "mode": { + "type": "string", + "enum": [ + "provider_default" + ] + } + }, + "required": [ + "mode" + ], + "additionalProperties": false + }, + { + "type": "object", + "properties": { + "mode": { + "type": "string", + "enum": [ + "max_age" + ] + }, + "max_age_seconds": { + "type": "integer", + "minimum": 30, + "maximum": 86400 + } + }, + "required": [ + "mode", + "max_age_seconds" + ], + "additionalProperties": false + } + ], + "default": { + "mode": "provider_default" + } + } + }, + "required": [ + "widget_type", + "metric_key", + "metric_version" + ], + "additionalProperties": false + } + ], + "x-platform-exact-union": true + }, + "maxItems": 24 + } + }, + "required": [ + "name" + ], + "additionalProperties": false + } + } + } + }, + "responses": { + "201": { + "description": "Dashboard created", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "dashboard_id": { + "type": "string" + } + }, + "required": [ + "dashboard_id" + ] + } + } + } }, - "effect": { - "type": "string", - "enum": [ - "allow", - "deny" - ] + "401": { + "description": "Unauthorized", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } + } + } }, - "reason": { - "type": "string", - "minLength": 1, - "maxLength": 500 + "403": { + "description": "Forbidden", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } + } + } }, - "expires_at": { - "type": "number" + "409": { + "description": "Conflict", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } + } + } + }, + "422": { + "description": "Unprocessable entity", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } + } + } } + } + } + }, + "/v1/dashboards/workspace_overview": { + "get": { + "x-platform-visibility": "PUBLIC", + "x-platform-live": { + "visibility": "INTERNAL", + "transport": "convex", + "convexQuery": "snippet.ui.getWorkspaceOverviewForApi" }, - "required": [ - "target_type", - "key", - "scope", - "effect", - "reason" + "operationId": "dashboards.getWorkspaceOverview", + "tags": [ + "Dashboards" ], - "additionalProperties": false, - "x-platform-visibility": "ADMIN" - }, - "AdminQuotaOverrideList": { - "type": "object", - "properties": { - "data": { - "type": "array", - "items": { - "$ref": "#/components/schemas/AdminQuotaOverride" + "summary": "Get the workspace overview dashboard", + "description": "Returns the unique shared Workspace overview and its ordered widget configuration.", + "security": [ + { + "BearerAuth": [] + } + ], + "parameters": [ + { + "schema": { + "type": "string", + "minLength": 1, + "maxLength": 53, + "description": "Optional workspace/scope context for the request. Carries a single workspace wire id (`ws_…`) today. Only needed for broad tokens — a workspace-owned token implies its workspace.", + "example": "ws_j572abc123def456" + }, + "required": false, + "description": "Optional workspace/scope context for the request. Carries a single workspace wire id (`ws_…`) today. Only needed for broad tokens — a workspace-owned token implies its workspace.", + "name": "akua-context", + "in": "header" + } + ], + "responses": { + "200": { + "description": "Workspace overview dashboard", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Dashboard" + } + } } }, - "has_more": { - "type": "boolean", - "description": "True if more items exist after this page." + "401": { + "description": "Unauthorized", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } + } + } }, - "next_cursor": { - "type": "string", - "nullable": true, - "description": "Opaque cursor for the next page, or null if no more pages." + "403": { + "description": "Forbidden", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } + } + } + }, + "404": { + "description": "Not found", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } + } + } + }, + "409": { + "description": "Conflict", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } + } + } } + } + } + }, + "/v1/dashboards/{id}": { + "get": { + "x-platform-visibility": "PUBLIC", + "x-platform-live": { + "visibility": "INTERNAL", + "transport": "convex", + "convexQuery": "snippet.ui.getDashboardForApi" }, - "required": [ - "data", - "has_more", - "next_cursor" + "operationId": "dashboards.get", + "tags": [ + "Dashboards" ], - "x-platform-visibility": "ADMIN" - }, - "AdminQuotaOverride": { - "type": "object", - "properties": { - "id": { - "type": "string", - "minLength": 1, - "maxLength": 54 + "summary": "Get dashboard details", + "description": "Returns a dashboard including its widget layout and snippet references.", + "security": [ + { + "BearerAuth": [] + } + ], + "parameters": [ + { + "schema": { + "type": "string", + "minLength": 1, + "maxLength": 55, + "description": "Dashboard ID" + }, + "required": true, + "description": "Dashboard ID", + "name": "id", + "in": "path" + } + ], + "responses": { + "200": { + "description": "Dashboard details", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Dashboard" + } + } + } }, - "scope": { - "type": "string", - "enum": [ - "user", - "workspace" - ] + "401": { + "description": "Unauthorized", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } + } + } }, - "user_id": { - "type": "string", - "minLength": 1 + "403": { + "description": "Forbidden", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } + } + } }, - "workspace_id": { - "type": "string", - "minLength": 1, - "maxLength": 53 + "404": { + "description": "Not found", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } + } + } + } + } + }, + "patch": { + "x-platform-visibility": "PUBLIC", + "operationId": "dashboards.update", + "tags": [ + "Dashboards" + ], + "summary": "Update dashboard", + "description": "Update dashboard metadata. Widget mutations use the `/widgets` sub-collection.", + "security": [ + { + "BearerAuth": [] + } + ], + "parameters": [ + { + "schema": { + "type": "string", + "minLength": 1, + "maxLength": 55, + "description": "Dashboard ID" + }, + "required": true, + "description": "Dashboard ID", + "name": "id", + "in": "path" }, - "metric": { - "type": "string" + { + "schema": { + "type": "string", + "minLength": 1, + "maxLength": 256, + "description": "The `etag` of the resource version the client last read. Required on writes when the resource exposes an `etag` field. Mismatch returns 409 `ABORTED` with the current etag in the error metadata.", + "example": "42" + }, + "required": true, + "description": "The `etag` of the resource version the client last read. Required on writes when the resource exposes an `etag` field. Mismatch returns 409 `ABORTED` with the current etag in the error metadata.", + "name": "if-match", + "in": "header" + } + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "name": { + "type": "string", + "minLength": 1, + "maxLength": 100 + }, + "description": { + "type": "string", + "maxLength": 500 + } + }, + "additionalProperties": false + } + } + } + }, + "responses": { + "200": { + "description": "Dashboard updated", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "dashboard_id": { + "type": "string" + } + }, + "required": [ + "dashboard_id" + ] + } + } + } }, - "limit": { - "type": "number" + "401": { + "description": "Unauthorized", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } + } + } }, - "previous_limit": { - "type": "number", - "nullable": true + "404": { + "description": "Not found", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } + } + } }, - "new_limit": { - "type": "number", - "nullable": true + "409": { + "description": "Conflict", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } + } + } + } + } + }, + "delete": { + "x-platform-visibility": "PUBLIC", + "operationId": "dashboards.delete", + "tags": [ + "Dashboards" + ], + "summary": "Delete dashboard", + "description": "Permanently deletes a dashboard. Referenced snippets are not affected.", + "security": [ + { + "BearerAuth": [] + } + ], + "parameters": [ + { + "schema": { + "type": "string", + "minLength": 1, + "maxLength": 55, + "description": "Dashboard ID" + }, + "required": true, + "description": "Dashboard ID", + "name": "id", + "in": "path" }, - "reason": { - "type": "string" + { + "schema": { + "type": "string", + "minLength": 1, + "maxLength": 256, + "description": "The `etag` of the resource version the client last read. Required on writes when the resource exposes an `etag` field. Mismatch returns 409 `ABORTED` with the current etag in the error metadata.", + "example": "42" + }, + "required": true, + "description": "The `etag` of the resource version the client last read. Required on writes when the resource exposes an `etag` field. Mismatch returns 409 `ABORTED` with the current etag in the error metadata.", + "name": "if-match", + "in": "header" + } + ], + "responses": { + "204": { + "description": "Dashboard deleted" }, - "created_by": { - "type": "string", - "minLength": 1 + "401": { + "description": "Unauthorized", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } + } + } }, - "created_at": { - "type": "number" + "404": { + "description": "Not found", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } + } + } }, - "updated_by": { - "type": "string", - "minLength": 1 + "409": { + "description": "Conflict", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } + } + } + } + } + } + }, + "/v1/dashboards/{id}/revisions": { + "get": { + "x-platform-visibility": "PUBLIC", + "operationId": "dashboards.listRevisions", + "tags": [ + "Dashboards" + ], + "summary": "List dashboard revisions", + "description": "Lists immutable dashboard revisions from newest to oldest.", + "security": [ + { + "BearerAuth": [] + } + ], + "parameters": [ + { + "schema": { + "type": "string", + "minLength": 1, + "maxLength": 55 + }, + "required": true, + "name": "id", + "in": "path" }, - "updated_at": { - "type": "number" + { + "schema": { + "type": "string", + "description": "Pagination cursor from a previous response's `next_cursor`." + }, + "required": false, + "description": "Pagination cursor from a previous response's `next_cursor`.", + "name": "cursor", + "in": "query" }, - "revoked_at": { - "type": "number" + { + "schema": { + "type": "integer", + "minimum": 1, + "maximum": 10, + "default": 10, + "description": "Dashboard revisions per page (1-10, default 10)", + "example": 10 + }, + "required": false, + "description": "Dashboard revisions per page (1-10, default 10)", + "name": "limit", + "in": "query" } - }, - "required": [ - "id", - "scope", - "metric", - "limit", - "previous_limit", - "new_limit" ], - "x-platform-visibility": "ADMIN" - }, - "SetAdminQuotaOverrideBody": { - "type": "object", - "properties": { - "scope": { - "type": "string", - "enum": [ - "user", - "workspace" - ] - }, - "user_id": { - "type": "string", - "minLength": 1 + "responses": { + "200": { + "description": "Dashboard revision history", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/DashboardRevisionList" + } + } + } }, - "workspace_id": { - "type": "string", - "minLength": 1, - "maxLength": 53 + "401": { + "description": "Unauthorized", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } + } + } }, - "metric": { - "type": "string", - "minLength": 1, - "maxLength": 256 + "403": { + "description": "Forbidden", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } + } + } }, - "limit": { - "type": "integer", - "minimum": 0 + "404": { + "description": "Not found", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } + } + } }, - "reason": { - "type": "string", - "minLength": 1, - "maxLength": 500 + "422": { + "description": "Input validation error", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } + } + } } - }, - "required": [ - "scope", - "metric", - "limit", - "reason" - ], - "additionalProperties": false, - "x-platform-visibility": "ADMIN" - } - }, - "parameters": {} - }, - "paths": { - "/v1/compute/machines": { + } + }, "post": { "x-platform-visibility": "PUBLIC", - "operationId": "compute.createMachine", + "operationId": "dashboards.createRevision", "tags": [ - "Compute" + "Dashboards" ], - "summary": "Create a machine", - "description": "Provisions a new machine in the specified cluster with the given compute configuration.", + "summary": "Create dashboard revision", + "description": "Atomically saves and activates a complete ordered dashboard snapshot as one immutable revision.", "security": [ { "BearerAuth": [] } ], + "parameters": [ + { + "schema": { + "type": "string", + "minLength": 1, + "maxLength": 55 + }, + "required": true, + "name": "id", + "in": "path" + }, + { + "schema": { + "type": "string", + "minLength": 1, + "maxLength": 256, + "description": "The `etag` of the resource version the client last read. Required on writes when the resource exposes an `etag` field. Mismatch returns 409 `ABORTED` with the current etag in the error metadata.", + "example": "42" + }, + "required": true, + "description": "The `etag` of the resource version the client last read. Required on writes when the resource exposes an `etag` field. Mismatch returns 409 `ABORTED` with the current etag in the error metadata.", + "name": "if-match", + "in": "header" + }, + { + "schema": { + "type": "string", + "minLength": 1, + "maxLength": 64, + "description": "Required caller-supplied idempotency key. Any non-empty key up to 64 characters is accepted. Endpoint-specific documentation describes how the key is used.", + "example": "create-prod-2026-05-07" + }, + "required": true, + "description": "Required caller-supplied idempotency key. Any non-empty key up to 64 characters is accepted. Endpoint-specific documentation describes how the key is used.", + "name": "idempotency-key", + "in": "header" + } + ], "requestBody": { + "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { - "config_ref": { + "name": { "type": "string", - "description": "ComputeConfig ID" + "minLength": 1, + "maxLength": 100 }, - "cluster_id": { + "description": { "type": "string", - "description": "Cluster ID" - }, - "node_claim": { "nullable": true, - "description": "Machine requirements (instance type, resources, taints)" + "maxLength": 500 + }, + "filter_definitions": { + "type": "array", + "items": { + "oneOf": [ + { + "type": "object", + "properties": { + "kind": { + "type": "string", + "enum": [ + "time" + ] + }, + "key": { + "type": "string", + "enum": [ + "time" + ] + }, + "label": { + "type": "string", + "minLength": 1, + "maxLength": 100 + } + }, + "required": [ + "kind", + "key", + "label" + ], + "additionalProperties": false + }, + { + "type": "object", + "properties": { + "kind": { + "type": "string", + "enum": [ + "comparison" + ] + }, + "key": { + "type": "string", + "enum": [ + "comparison" + ] + }, + "label": { + "type": "string", + "minLength": 1, + "maxLength": 100 + } + }, + "required": [ + "kind", + "key", + "label" + ], + "additionalProperties": false + }, + { + "type": "object", + "properties": { + "kind": { + "type": "string", + "enum": [ + "resource" + ] + }, + "key": { + "type": "string", + "enum": [ + "cluster", + "install", + "product", + "package", + "region" + ] + }, + "resource": { + "type": "string", + "enum": [ + "cluster", + "install", + "product", + "package", + "region" + ] + }, + "label": { + "type": "string", + "minLength": 1, + "maxLength": 100 + } + }, + "required": [ + "kind", + "key", + "resource", + "label" + ], + "additionalProperties": false + }, + { + "type": "object", + "properties": { + "kind": { + "type": "string", + "enum": [ + "status" + ] + }, + "key": { + "type": "string", + "enum": [ + "status" + ] + }, + "label": { + "type": "string", + "minLength": 1, + "maxLength": 100 + }, + "options": { + "type": "array", + "items": { + "type": "string", + "minLength": 1, + "maxLength": 100 + }, + "minItems": 1, + "maxItems": 100 + } + }, + "required": [ + "kind", + "key", + "label", + "options" + ], + "additionalProperties": false + }, + { + "type": "object", + "properties": { + "kind": { + "type": "string", + "enum": [ + "variable" + ] + }, + "key": { + "type": "string", + "pattern": "^var\\.[a-z][a-z0-9_]{0,31}$" + }, + "input": { + "oneOf": [ + { + "type": "object", + "properties": { + "key": { + "type": "string", + "pattern": "^[a-z][a-z0-9_]{0,31}$" + }, + "label": { + "type": "string", + "minLength": 1, + "maxLength": 100 + }, + "description": { + "type": "string", + "maxLength": 500 + }, + "required": { + "type": "boolean" + }, + "kind": { + "type": "string", + "enum": [ + "time_range" + ] + }, + "default": { + "type": "object", + "properties": { + "from": { + "type": "integer" + }, + "to": { + "type": "integer" + } + }, + "required": [ + "from", + "to" + ], + "additionalProperties": false + } + }, + "required": [ + "key", + "label", + "kind" + ], + "additionalProperties": false + }, + { + "type": "object", + "properties": { + "key": { + "type": "string", + "pattern": "^[a-z][a-z0-9_]{0,31}$" + }, + "label": { + "type": "string", + "minLength": 1, + "maxLength": 100 + }, + "description": { + "type": "string", + "maxLength": 500 + }, + "required": { + "type": "boolean" + }, + "kind": { + "type": "string", + "enum": [ + "resource" + ] + }, + "resource": { + "type": "string", + "enum": [ + "cluster", + "install", + "product", + "package", + "region" + ] + }, + "default": { + "anyOf": [ + { + "type": "string", + "maxLength": 255 + }, + { + "type": "array", + "items": { + "type": "string", + "maxLength": 255 + }, + "minItems": 1, + "maxItems": 100 + } + ] + }, + "multiple": { + "type": "boolean" + } + }, + "required": [ + "key", + "label", + "kind", + "resource" + ], + "additionalProperties": false + }, + { + "type": "object", + "properties": { + "key": { + "type": "string", + "pattern": "^[a-z][a-z0-9_]{0,31}$" + }, + "label": { + "type": "string", + "minLength": 1, + "maxLength": 100 + }, + "description": { + "type": "string", + "maxLength": 500 + }, + "required": { + "type": "boolean" + }, + "kind": { + "type": "string", + "enum": [ + "enum" + ] + }, + "options": { + "type": "array", + "items": { + "type": "string", + "minLength": 1, + "maxLength": 100 + }, + "minItems": 1, + "maxItems": 100 + }, + "default": { + "type": "string", + "minLength": 1, + "maxLength": 100 + } + }, + "required": [ + "key", + "label", + "kind", + "options" + ], + "additionalProperties": false + }, + { + "type": "object", + "properties": { + "key": { + "type": "string", + "pattern": "^[a-z][a-z0-9_]{0,31}$" + }, + "label": { + "type": "string", + "minLength": 1, + "maxLength": 100 + }, + "description": { + "type": "string", + "maxLength": 500 + }, + "required": { + "type": "boolean" + }, + "kind": { + "type": "string", + "enum": [ + "boolean" + ] + }, + "default": { + "type": "boolean" + } + }, + "required": [ + "key", + "label", + "kind" + ], + "additionalProperties": false + }, + { + "type": "object", + "properties": { + "key": { + "type": "string", + "pattern": "^[a-z][a-z0-9_]{0,31}$" + }, + "label": { + "type": "string", + "minLength": 1, + "maxLength": 100 + }, + "description": { + "type": "string", + "maxLength": 500 + }, + "required": { + "type": "boolean" + }, + "kind": { + "type": "string", + "enum": [ + "number" + ] + }, + "min": { + "type": "number" + }, + "max": { + "type": "number" + }, + "default": { + "type": "number" + } + }, + "required": [ + "key", + "label", + "kind" + ], + "additionalProperties": false + }, + { + "type": "object", + "properties": { + "key": { + "type": "string", + "pattern": "^[a-z][a-z0-9_]{0,31}$" + }, + "label": { + "type": "string", + "minLength": 1, + "maxLength": 100 + }, + "description": { + "type": "string", + "maxLength": 500 + }, + "required": { + "type": "boolean" + }, + "kind": { + "type": "string", + "enum": [ + "text" + ] + }, + "default": { + "type": "string", + "maxLength": 500 + }, + "max_length": { + "type": "integer", + "minimum": 1, + "maximum": 500 + } + }, + "required": [ + "key", + "label", + "kind" + ], + "additionalProperties": false + } + ] + } + }, + "required": [ + "kind", + "key", + "input" + ], + "additionalProperties": false + } + ] + }, + "maxItems": 24 + }, + "default_filter_values": { + "type": "object", + "additionalProperties": { + "nullable": true + } + }, + "summary": { + "type": "string", + "maxLength": 500 + }, + "widgets": { + "type": "array", + "items": { + "oneOf": [ + { + "type": "object", + "properties": { + "widget_id": { + "type": "string", + "minLength": 1, + "maxLength": 54 + }, + "title": { + "type": "string", + "maxLength": 100 + }, + "col_span": { + "anyOf": [ + { + "type": "number", + "enum": [ + 1 + ] + }, + { + "type": "number", + "enum": [ + 2 + ] + }, + { + "type": "number", + "enum": [ + 3 + ] + }, + { + "type": "number", + "enum": [ + 4 + ] + } + ] + }, + "height": { + "type": "string", + "enum": [ + "compact", + "standard", + "tall" + ] + }, + "drill_down": { + "type": "string", + "nullable": true, + "minLength": 1, + "maxLength": 2048 + }, + "visualization_options": { + "type": "object", + "additionalProperties": { + "nullable": true + } + }, + "freshness_policy": { + "oneOf": [ + { + "type": "object", + "properties": { + "mode": { + "type": "string", + "enum": [ + "provider_default" + ] + } + }, + "required": [ + "mode" + ], + "additionalProperties": false + }, + { + "type": "object", + "properties": { + "mode": { + "type": "string", + "enum": [ + "max_age" + ] + }, + "max_age_seconds": { + "type": "integer", + "minimum": 30, + "maximum": 86400 + } + }, + "required": [ + "mode", + "max_age_seconds" + ], + "additionalProperties": false + } + ] + }, + "widget_type": { + "type": "string", + "enum": [ + "snippet" + ] + }, + "snippet_id": { + "type": "string", + "minLength": 1, + "maxLength": 54 + }, + "input_bindings": { + "type": "object", + "additionalProperties": { + "oneOf": [ + { + "type": "object", + "properties": { + "mode": { + "type": "string", + "enum": [ + "inherit" + ] + }, + "filter_key": { + "anyOf": [ + { + "type": "string", + "enum": [ + "time", + "comparison", + "cluster", + "install", + "product", + "package", + "region", + "status" + ] + }, + { + "type": "string", + "pattern": "^var\\.[a-z][a-z0-9_]{0,31}$" + } + ] + } + }, + "required": [ + "mode", + "filter_key" + ], + "additionalProperties": false + }, + { + "type": "object", + "properties": { + "mode": { + "type": "string", + "enum": [ + "fixed" + ] + }, + "value": { + "nullable": true + } + }, + "required": [ + "mode", + "value" + ], + "additionalProperties": false + }, + { + "type": "object", + "properties": { + "mode": { + "type": "string", + "enum": [ + "unbound" + ] + } + }, + "required": [ + "mode" + ], + "additionalProperties": false + } + ] + } + }, + "visualization": { + "type": "string", + "nullable": true, + "enum": [ + "stat", + "sparkline", + "line", + "area", + "bar", + "donut", + "table", + "status_list", + "logs", + "json", + null + ] + }, + "refresh_policy": { + "oneOf": [ + { + "type": "object", + "properties": { + "mode": { + "type": "string", + "enum": [ + "on_load" + ] + } + }, + "required": [ + "mode" + ], + "additionalProperties": false + }, + { + "type": "object", + "properties": { + "mode": { + "type": "string", + "enum": [ + "manual" + ] + } + }, + "required": [ + "mode" + ], + "additionalProperties": false + }, + { + "type": "object", + "properties": { + "mode": { + "type": "string", + "enum": [ + "interval" + ] + }, + "interval_seconds": { + "type": "integer", + "minimum": 60, + "maximum": 86400 + } + }, + "required": [ + "mode", + "interval_seconds" + ], + "additionalProperties": false + } + ] + }, + "display_type": { + "type": "string", + "nullable": true, + "enum": [ + "table", + "stat", + "json", + "logs", + "timeseries", + null + ], + "description": "Controls how the snippet result is rendered in dashboard widgets" + } + }, + "required": [ + "col_span", + "height", + "drill_down", + "visualization_options", + "freshness_policy", + "widget_type", + "snippet_id", + "input_bindings", + "visualization", + "refresh_policy", + "display_type" + ], + "additionalProperties": false + }, + { + "type": "object", + "properties": { + "widget_id": { + "type": "string", + "minLength": 1, + "maxLength": 54 + }, + "title": { + "type": "string", + "maxLength": 100 + }, + "col_span": { + "anyOf": [ + { + "type": "number", + "enum": [ + 1 + ] + }, + { + "type": "number", + "enum": [ + 2 + ] + }, + { + "type": "number", + "enum": [ + 3 + ] + }, + { + "type": "number", + "enum": [ + 4 + ] + } + ] + }, + "height": { + "type": "string", + "enum": [ + "compact", + "standard", + "tall" + ] + }, + "drill_down": { + "type": "string", + "nullable": true, + "minLength": 1, + "maxLength": 2048 + }, + "visualization_options": { + "type": "object", + "additionalProperties": { + "nullable": true + } + }, + "freshness_policy": { + "oneOf": [ + { + "type": "object", + "properties": { + "mode": { + "type": "string", + "enum": [ + "provider_default" + ] + } + }, + "required": [ + "mode" + ], + "additionalProperties": false + }, + { + "type": "object", + "properties": { + "mode": { + "type": "string", + "enum": [ + "max_age" + ] + }, + "max_age_seconds": { + "type": "integer", + "minimum": 30, + "maximum": 86400 + } + }, + "required": [ + "mode", + "max_age_seconds" + ], + "additionalProperties": false + } + ] + }, + "widget_type": { + "type": "string", + "enum": [ + "platform_metric" + ] + }, + "metric_key": { + "type": "string", + "minLength": 1, + "maxLength": 100, + "pattern": "^[a-z][a-z0-9_]*$" + }, + "metric_version": { + "type": "integer", + "minimum": 0, + "exclusiveMinimum": true + }, + "filter_bindings": { + "type": "object", + "additionalProperties": { + "oneOf": [ + { + "type": "object", + "properties": { + "mode": { + "type": "string", + "enum": [ + "inherit" + ] + }, + "filter_key": { + "anyOf": [ + { + "type": "string", + "enum": [ + "time", + "comparison", + "cluster", + "install", + "product", + "package", + "region", + "status" + ] + }, + { + "type": "string", + "pattern": "^var\\.[a-z][a-z0-9_]{0,31}$" + } + ] + } + }, + "required": [ + "mode", + "filter_key" + ], + "additionalProperties": false + }, + { + "type": "object", + "properties": { + "mode": { + "type": "string", + "enum": [ + "fixed" + ] + }, + "value": { + "nullable": true + } + }, + "required": [ + "mode", + "value" + ], + "additionalProperties": false + }, + { + "type": "object", + "properties": { + "mode": { + "type": "string", + "enum": [ + "unbound" + ] + } + }, + "required": [ + "mode" + ], + "additionalProperties": false + } + ] + } + } + }, + "required": [ + "col_span", + "height", + "drill_down", + "visualization_options", + "freshness_policy", + "widget_type", + "metric_key", + "metric_version", + "filter_bindings" + ], + "additionalProperties": false + } + ] + }, + "maxItems": 24 } }, "required": [ - "config_ref", - "cluster_id" - ] + "name", + "description", + "filter_definitions", + "default_filter_values", + "widgets" + ], + "additionalProperties": false } } } }, "responses": { "201": { - "description": "Machine created", + "description": "Dashboard revision created and activated", + "headers": { + "ETag": { + "description": "Current parent dashboard ETag after activating the revision.", + "schema": { + "type": "string" + } + }, + "Location": { + "description": "Location of the newly created dashboard revision.", + "schema": { + "type": "string" + } + } + }, "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/ComputeMachine" + "$ref": "#/components/schemas/DashboardRevisionMutationResponse" } } } @@ -18212,69 +33662,38 @@ } } }, - "404": { - "description": "Config not found (NodeClassNotReady)", + "403": { + "description": "Forbidden", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/ComputeError" + "$ref": "#/components/schemas/ApiErrorResponse" } } } }, - "503": { - "description": "No capacity available (InsufficientCapacity)", + "404": { + "description": "Not found", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/ComputeError" + "$ref": "#/components/schemas/ApiErrorResponse" } } } - } - } - }, - "get": { - "x-platform-visibility": "PUBLIC", - "operationId": "compute.listMachines", - "tags": [ - "Compute" - ], - "summary": "List machines in cluster", - "description": "Lists all machines for a cluster.", - "security": [ - { - "BearerAuth": [] - } - ], - "parameters": [ - { - "schema": { - "type": "string", - "description": "Cluster ID" - }, - "required": true, - "description": "Cluster ID", - "name": "cluster", - "in": "query" - } - ], - "responses": { - "200": { - "description": "List of machines", + }, + "409": { + "description": "Conflict", "content": { "application/json": { "schema": { - "type": "array", - "items": { - "$ref": "#/components/schemas/ComputeMachine" - } + "$ref": "#/components/schemas/ApiErrorResponse" } } } }, - "401": { - "description": "Unauthorized", + "422": { + "description": "Unprocessable entity", "content": { "application/json": { "schema": { @@ -18286,15 +33705,15 @@ } } }, - "/v1/compute/machines/{providerId}": { - "delete": { + "/v1/dashboards/{id}/revisions/{revision_id}": { + "get": { "x-platform-visibility": "PUBLIC", - "operationId": "compute.deleteMachine", + "operationId": "dashboards.getRevision", "tags": [ - "Compute" + "Dashboards" ], - "summary": "Delete a machine", - "description": "Deletes a machine by provider ID. The node is drained before the cloud server is terminated.", + "summary": "Get dashboard revision", + "description": "Returns one immutable dashboard revision and its snippet version drift.", "security": [ { "BearerAuth": [] @@ -18304,17 +33723,34 @@ { "schema": { "type": "string", - "description": "Provider-assigned machine ID" + "minLength": 1, + "maxLength": 55 }, "required": true, - "description": "Provider-assigned machine ID", - "name": "providerId", + "name": "id", + "in": "path" + }, + { + "schema": { + "type": "string", + "minLength": 1, + "maxLength": 55 + }, + "required": true, + "name": "revision_id", "in": "path" } ], "responses": { - "204": { - "description": "Machine deleted" + "200": { + "description": "Dashboard revision details", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/DashboardRevision" + } + } + } }, "401": { "description": "Unauthorized", @@ -18326,26 +33762,48 @@ } } }, + "403": { + "description": "Forbidden", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } + } + } + }, "404": { - "description": "Machine not found (NodeClaimNotFound)", + "description": "Not found", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/ComputeError" + "$ref": "#/components/schemas/ApiErrorResponse" + } + } + } + }, + "422": { + "description": "Input validation error", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" } } } } } - }, - "get": { + } + }, + "/v1/dashboards/{id}/revisions/{revision_id}:restore": { + "post": { "x-platform-visibility": "PUBLIC", - "operationId": "compute.getMachine", + "operationId": "dashboards.restoreRevision", "tags": [ - "Compute" + "Dashboards" ], - "summary": "Get machine status", - "description": "Returns current state of a machine including conditions and provider metadata.", + "summary": "Restore dashboard revision", + "description": "Restores an immutable snapshot by creating and activating a new dashboard revision.", "security": [ { "BearerAuth": [] @@ -18355,21 +33813,92 @@ { "schema": { "type": "string", - "description": "Provider-assigned machine ID" + "minLength": 1, + "maxLength": 55 }, "required": true, - "description": "Provider-assigned machine ID", - "name": "providerId", + "name": "id", + "in": "path" + }, + { + "schema": { + "type": "string", + "minLength": 1, + "maxLength": 55 + }, + "required": true, + "name": "revision_id", "in": "path" + }, + { + "schema": { + "type": "string", + "minLength": 1, + "maxLength": 256, + "description": "The `etag` of the resource version the client last read. Required on writes when the resource exposes an `etag` field. Mismatch returns 409 `ABORTED` with the current etag in the error metadata.", + "example": "42" + }, + "required": true, + "description": "The `etag` of the resource version the client last read. Required on writes when the resource exposes an `etag` field. Mismatch returns 409 `ABORTED` with the current etag in the error metadata.", + "name": "if-match", + "in": "header" + }, + { + "schema": { + "type": "string", + "minLength": 1, + "maxLength": 64, + "description": "Required caller-supplied idempotency key. Any non-empty key up to 64 characters is accepted. Endpoint-specific documentation describes how the key is used.", + "example": "create-prod-2026-05-07" + }, + "required": true, + "description": "Required caller-supplied idempotency key. Any non-empty key up to 64 characters is accepted. Endpoint-specific documentation describes how the key is used.", + "name": "idempotency-key", + "in": "header" } ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "summary": { + "type": "string", + "nullable": true, + "maxLength": 500 + } + }, + "required": [ + "summary" + ], + "additionalProperties": false + } + } + } + }, "responses": { - "200": { - "description": "Machine details", + "201": { + "description": "Dashboard revision restored into a new active revision", + "headers": { + "ETag": { + "description": "Current parent dashboard ETag after activating the revision.", + "schema": { + "type": "string" + } + }, + "Location": { + "description": "Location of the newly created dashboard revision.", + "schema": { + "type": "string" + } + } + }, "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/ComputeMachine" + "$ref": "#/components/schemas/DashboardRevisionMutationResponse" } } } @@ -18384,61 +33913,28 @@ } } }, - "404": { - "description": "Machine not found (NodeClaimNotFound)", + "403": { + "description": "Forbidden", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/ComputeError" + "$ref": "#/components/schemas/ApiErrorResponse" } } } - } - } - } - }, - "/v1/compute/instance_types": { - "get": { - "x-platform-visibility": "PUBLIC", - "operationId": "compute.listInstanceTypes", - "tags": [ - "Compute" - ], - "summary": "List available instance types", - "description": "Returns instance types with pricing for a compute config. Returns available instance types for provisioning. Results are cached.", - "security": [ - { - "BearerAuth": [] - } - ], - "parameters": [ - { - "schema": { - "type": "string", - "description": "Config name (optional — derived from cluster context when omitted)" - }, - "required": false, - "description": "Config name (optional — derived from cluster context when omitted)", - "name": "config", - "in": "query" - } - ], - "responses": { - "200": { - "description": "Available instance types", + }, + "404": { + "description": "Not found", "content": { "application/json": { "schema": { - "type": "array", - "items": { - "$ref": "#/components/schemas/InstanceType" - } + "$ref": "#/components/schemas/ApiErrorResponse" } } } }, - "401": { - "description": "Unauthorized", + "409": { + "description": "Conflict", "content": { "application/json": { "schema": { @@ -18447,12 +33943,12 @@ } } }, - "404": { - "description": "Config not found (NodeClassNotReady)", + "422": { + "description": "Unprocessable entity", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/ComputeError" + "$ref": "#/components/schemas/ApiErrorResponse" } } } @@ -18460,15 +33956,15 @@ } } }, - "/v1/compute/machines/{providerId}/drift": { - "get": { + "/v1/dashboards/{id}:resetToRecommended": { + "post": { "x-platform-visibility": "PUBLIC", - "operationId": "compute.checkMachineDrift", + "operationId": "dashboards.resetToRecommended", "tags": [ - "Compute" + "Dashboards" ], - "summary": "Check if machine has drifted", - "description": "Checks if a machine has drifted from its desired compute configuration.", + "summary": "Reset the Workspace overview to the recommended configuration", + "description": "Replaces the shared Workspace overview configuration with the current recommended built-ins and creates one immutable revision.", "security": [ { "BearerAuth": [] @@ -18478,21 +33974,61 @@ { "schema": { "type": "string", - "description": "Provider-assigned machine ID" + "minLength": 1, + "maxLength": 55 }, "required": true, - "description": "Provider-assigned machine ID", - "name": "providerId", + "name": "id", "in": "path" + }, + { + "schema": { + "type": "string", + "minLength": 1, + "maxLength": 256, + "description": "The `etag` of the resource version the client last read. Required on writes when the resource exposes an `etag` field. Mismatch returns 409 `ABORTED` with the current etag in the error metadata.", + "example": "42" + }, + "required": true, + "description": "The `etag` of the resource version the client last read. Required on writes when the resource exposes an `etag` field. Mismatch returns 409 `ABORTED` with the current etag in the error metadata.", + "name": "if-match", + "in": "header" + }, + { + "schema": { + "type": "string", + "minLength": 1, + "maxLength": 64, + "description": "Required caller-supplied idempotency key. Any non-empty key up to 64 characters is accepted. Endpoint-specific documentation describes how the key is used.", + "example": "create-prod-2026-05-07" + }, + "required": true, + "description": "Required caller-supplied idempotency key. Any non-empty key up to 64 characters is accepted. Endpoint-specific documentation describes how the key is used.", + "name": "idempotency-key", + "in": "header" } ], "responses": { - "200": { - "description": "Drift result", + "201": { + "description": "Workspace overview reset into a new active revision", + "headers": { + "ETag": { + "description": "Current parent dashboard ETag after activating the revision.", + "schema": { + "type": "string" + } + }, + "Location": { + "description": "Location of the newly created dashboard revision.", + "schema": { + "type": "string" + } + } + }, "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/DriftResult" + "$ref": "#/components/schemas/DashboardRevisionMutationResponse" } } } @@ -18506,42 +34042,9 @@ } } } - } - } - } - }, - "/v1/compute/machines/{providerId}/suspend": { - "post": { - "x-platform-visibility": "PUBLIC", - "operationId": "compute.suspendMachine", - "tags": [ - "Compute" - ], - "summary": "Suspend a machine", - "description": "Snapshots the machine disk, deletes the cloud server to stop billing, and creates a suspension record.", - "security": [ - { - "BearerAuth": [] - } - ], - "parameters": [ - { - "schema": { - "type": "string", - "description": "Provider-assigned machine ID" - }, - "required": true, - "description": "Provider-assigned machine ID", - "name": "providerId", - "in": "path" - } - ], - "responses": { - "204": { - "description": "Suspend workflow started" }, - "401": { - "description": "Unauthorized", + "403": { + "description": "Forbidden", "content": { "application/json": { "schema": { @@ -18551,11 +34054,31 @@ } }, "404": { - "description": "Machine not found (NodeClaimNotFound)", + "description": "Not found", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } + } + } + }, + "409": { + "description": "Conflict", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } + } + } + }, + "422": { + "description": "Unprocessable entity", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/ComputeError" + "$ref": "#/components/schemas/ApiErrorResponse" } } } @@ -18563,15 +34086,15 @@ } } }, - "/v1/compute/suspensions/{id}/resume": { + "/v1/dashboards/{id}/widgets": { "post": { "x-platform-visibility": "PUBLIC", - "operationId": "compute.resumeSuspension", + "operationId": "dashboards.createWidget", "tags": [ - "Compute" + "Dashboards" ], - "summary": "Resume a suspended machine", - "description": "Restores the machine from its snapshot, creates a new cloud server.", + "summary": "Create dashboard widget", + "description": "Creates a widget as a child resource under a dashboard.", "security": [ { "BearerAuth": [] @@ -18581,17 +34104,59 @@ { "schema": { "type": "string", - "description": "Suspension ID" + "minLength": 1, + "maxLength": 55 }, "required": true, - "description": "Suspension ID", "name": "id", "in": "path" + }, + { + "schema": { + "type": "string", + "minLength": 1, + "maxLength": 53, + "description": "Optional workspace/scope context for the request. Carries a single workspace wire id (`ws_…`) today. Only needed for broad tokens — a workspace-owned token implies its workspace.", + "example": "ws_j572abc123def456" + }, + "required": false, + "description": "Optional workspace/scope context for the request. Carries a single workspace wire id (`ws_…`) today. Only needed for broad tokens — a workspace-owned token implies its workspace.", + "name": "akua-context", + "in": "header" + }, + { + "schema": { + "type": "string", + "minLength": 1, + "maxLength": 64, + "description": "Optional caller-supplied idempotency key. Any non-empty key up to 64 characters is accepted. Endpoint-specific documentation describes how the key is used.", + "example": "create-prod-2026-05-07" + }, + "required": false, + "description": "Optional caller-supplied idempotency key. Any non-empty key up to 64 characters is accepted. Endpoint-specific documentation describes how the key is used.", + "name": "idempotency-key", + "in": "header" } ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/CreateDashboardWidgetBody" + } + } + } + }, "responses": { - "204": { - "description": "Resume workflow started" + "201": { + "description": "Dashboard widget created", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Widget" + } + } + } }, "401": { "description": "Unauthorized", @@ -18603,49 +34168,28 @@ } } }, - "404": { - "description": "Suspension not found", + "403": { + "description": "Forbidden", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/ComputeError" + "$ref": "#/components/schemas/ApiErrorResponse" } } } - } - } - } - }, - "/v1/compute/suspensions": { - "get": { - "x-platform-visibility": "PUBLIC", - "operationId": "compute.listSuspensions", - "tags": [ - "Compute" - ], - "summary": "List suspended machines", - "description": "Lists all suspended machines for the workspace.", - "security": [ - { - "BearerAuth": [] - } - ], - "responses": { - "200": { - "description": "List of suspensions", + }, + "404": { + "description": "Not found", "content": { "application/json": { "schema": { - "type": "array", - "items": { - "$ref": "#/components/schemas/Suspension" - } + "$ref": "#/components/schemas/ApiErrorResponse" } } } }, - "401": { - "description": "Unauthorized", + "409": { + "description": "Conflict", "content": { "application/json": { "schema": { @@ -18654,8 +34198,8 @@ } } }, - "403": { - "description": "Akua-Context required", + "422": { + "description": "Unprocessable entity", "content": { "application/json": { "schema": { @@ -18665,17 +34209,15 @@ } } } - } - }, - "/v1/compute/suspensions/{id}": { - "delete": { + }, + "get": { "x-platform-visibility": "PUBLIC", - "operationId": "compute.deleteSuspension", + "operationId": "dashboards.listWidgets", "tags": [ - "Compute" + "Dashboards" ], - "summary": "Delete a suspension", - "description": "Deletes the snapshot and suspension record permanently.", + "summary": "List dashboard widgets", + "description": "Lists widgets for a dashboard.", "security": [ { "BearerAuth": [] @@ -18685,56 +34227,13 @@ { "schema": { "type": "string", - "description": "Suspension ID" + "minLength": 1, + "maxLength": 55 }, "required": true, - "description": "Suspension ID", "name": "id", "in": "path" - } - ], - "responses": { - "204": { - "description": "Suspension deleted" - }, - "401": { - "description": "Unauthorized", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/ApiErrorResponse" - } - } - } }, - "404": { - "description": "Suspension not found", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/ComputeError" - } - } - } - } - } - } - }, - "/v1/compute/configs": { - "get": { - "x-platform-visibility": "PUBLIC", - "operationId": "compute.listConfigs", - "tags": [ - "Compute" - ], - "summary": "List compute configs", - "description": "Lists compute configs for the workspace.", - "security": [ - { - "BearerAuth": [] - } - ], - "parameters": [ { "schema": { "type": "string", @@ -18762,11 +34261,11 @@ ], "responses": { "200": { - "description": "List of compute configs", + "description": "List of dashboard widgets", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/ComputeConfigList" + "$ref": "#/components/schemas/WidgetList" } } } @@ -18782,7 +34281,17 @@ } }, "403": { - "description": "Akua-Context required", + "description": "Forbidden", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } + } + } + }, + "404": { + "description": "Not found", "content": { "application/json": { "schema": { @@ -18792,70 +34301,51 @@ } } } - }, - "post": { + } + }, + "/v1/dashboards/{id}/widgets/{wgt_id}": { + "get": { "x-platform-visibility": "PUBLIC", - "operationId": "compute.createConfig", + "operationId": "dashboards.getWidget", "tags": [ - "Compute" + "Dashboards" ], - "summary": "Create a compute config", + "summary": "Get dashboard widget", + "description": "Returns a single dashboard widget.", "security": [ { "BearerAuth": [] } ], - "requestBody": { - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "name": { - "type": "string", - "minLength": 1, - "maxLength": 100 - }, - "provider": { - "type": "string", - "enum": [ - "hcloud" - ] - }, - "region": { - "type": "string", - "minLength": 1 - }, - "image": { - "type": "string", - "minLength": 1 - }, - "machine_type_filter": { - "type": "string", - "description": "Glob pattern to filter available instance types (e.g., \"cx*\" for shared CPU, \"cpx*\" for dedicated)" - }, - "secret_id": { - "type": "string", - "description": "Secret ID for BYOM (bring your own machine). Omit to use platform-managed defaults." - } - }, - "required": [ - "name", - "provider", - "region", - "image" - ] - } - } + "parameters": [ + { + "schema": { + "type": "string", + "minLength": 1, + "maxLength": 55 + }, + "required": true, + "name": "id", + "in": "path" + }, + { + "schema": { + "type": "string", + "minLength": 1, + "maxLength": 54 + }, + "required": true, + "name": "wgt_id", + "in": "path" } - }, + ], "responses": { - "201": { - "description": "Config created", + "200": { + "description": "Dashboard widget details", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/CreatedComputeConfig" + "$ref": "#/components/schemas/Widget" } } } @@ -18871,7 +34361,17 @@ } }, "403": { - "description": "Akua-Context required", + "description": "Forbidden", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } + } + } + }, + "404": { + "description": "Not found", "content": { "application/json": { "schema": { @@ -18881,16 +34381,15 @@ } } } - } - }, - "/v1/compute/configs/{id}": { - "get": { + }, + "patch": { "x-platform-visibility": "PUBLIC", - "operationId": "compute.getConfig", + "operationId": "dashboards.updateWidget", "tags": [ - "Compute" + "Dashboards" ], - "summary": "Get a compute config", + "summary": "Update dashboard widget", + "description": "Updates widget placement and display settings.", "security": [ { "BearerAuth": [] @@ -18900,21 +34399,79 @@ { "schema": { "type": "string", - "description": "ComputeConfig ID" + "minLength": 1, + "maxLength": 55 }, "required": true, - "description": "ComputeConfig ID", "name": "id", "in": "path" + }, + { + "schema": { + "type": "string", + "minLength": 1, + "maxLength": 54 + }, + "required": true, + "name": "wgt_id", + "in": "path" + }, + { + "schema": { + "type": "string", + "minLength": 1, + "maxLength": 53, + "description": "Optional workspace/scope context for the request. Carries a single workspace wire id (`ws_…`) today. Only needed for broad tokens — a workspace-owned token implies its workspace.", + "example": "ws_j572abc123def456" + }, + "required": false, + "description": "Optional workspace/scope context for the request. Carries a single workspace wire id (`ws_…`) today. Only needed for broad tokens — a workspace-owned token implies its workspace.", + "name": "akua-context", + "in": "header" + }, + { + "schema": { + "type": "string", + "minLength": 1, + "maxLength": 64, + "description": "Optional caller-supplied idempotency key. Any non-empty key up to 64 characters is accepted. Endpoint-specific documentation describes how the key is used.", + "example": "create-prod-2026-05-07" + }, + "required": false, + "description": "Optional caller-supplied idempotency key. Any non-empty key up to 64 characters is accepted. Endpoint-specific documentation describes how the key is used.", + "name": "idempotency-key", + "in": "header" + }, + { + "schema": { + "type": "string", + "minLength": 1, + "maxLength": 256, + "description": "The `etag` of the resource version the client last read. Required on writes when the resource exposes an `etag` field. Mismatch returns 409 `ABORTED` with the current etag in the error metadata.", + "example": "42" + }, + "required": true, + "description": "The `etag` of the resource version the client last read. Required on writes when the resource exposes an `etag` field. Mismatch returns 409 `ABORTED` with the current etag in the error metadata.", + "name": "if-match", + "in": "header" } ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/UpdateDashboardWidgetBody" + } + } + } + }, "responses": { "200": { - "description": "Compute config", + "description": "Dashboard widget updated", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/ComputeConfig" + "$ref": "#/components/schemas/Widget" } } } @@ -18930,7 +34487,7 @@ } }, "403": { - "description": "Akua-Context required", + "description": "Forbidden", "content": { "application/json": { "schema": { @@ -18940,11 +34497,31 @@ } }, "404": { - "description": "Config not found", + "description": "Not found", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } + } + } + }, + "409": { + "description": "Conflict", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } + } + } + }, + "422": { + "description": "Unprocessable entity", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/ComputeError" + "$ref": "#/components/schemas/ApiErrorResponse" } } } @@ -18953,11 +34530,12 @@ }, "delete": { "x-platform-visibility": "PUBLIC", - "operationId": "compute.deleteConfig", + "operationId": "dashboards.deleteWidget", "tags": [ - "Compute" + "Dashboards" ], - "summary": "Delete a compute config", + "summary": "Delete dashboard widget", + "description": "Deletes a dashboard widget. Snippet references are preserved.", "security": [ { "BearerAuth": [] @@ -18967,13 +34545,36 @@ { "schema": { "type": "string", - "description": "ComputeConfig ID" + "minLength": 1, + "maxLength": 55 }, "required": true, - "description": "ComputeConfig ID", "name": "id", "in": "path" }, + { + "schema": { + "type": "string", + "minLength": 1, + "maxLength": 54 + }, + "required": true, + "name": "wgt_id", + "in": "path" + }, + { + "schema": { + "type": "string", + "minLength": 1, + "maxLength": 53, + "description": "Optional workspace/scope context for the request. Carries a single workspace wire id (`ws_…`) today. Only needed for broad tokens — a workspace-owned token implies its workspace.", + "example": "ws_j572abc123def456" + }, + "required": false, + "description": "Optional workspace/scope context for the request. Carries a single workspace wire id (`ws_…`) today. Only needed for broad tokens — a workspace-owned token implies its workspace.", + "name": "akua-context", + "in": "header" + }, { "schema": { "type": "string", @@ -18990,7 +34591,7 @@ ], "responses": { "204": { - "description": "Config deleted" + "description": "Dashboard widget deleted" }, "401": { "description": "Unauthorized", @@ -19003,7 +34604,7 @@ } }, "403": { - "description": "Akua-Context required", + "description": "Forbidden", "content": { "application/json": { "schema": { @@ -19013,21 +34614,21 @@ } }, "404": { - "description": "Config not found", + "description": "Not found", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/ComputeError" + "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "409": { - "description": "Config has active machines", + "description": "Conflict", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/ComputeError" + "$ref": "#/components/schemas/ApiErrorResponse" } } } @@ -19035,134 +34636,333 @@ } } }, - "/v1/clusters/{clusterId}/compute_status": { - "get": { - "x-platform-visibility": "PUBLIC", - "operationId": "compute.getClusterStatus", + "/v1/cluster_runtime/machines": { + "post": { + "x-platform-visibility": "INTERNAL", + "operationId": "clusterRuntime.createMachine", "tags": [ - "Compute" + "Cluster Runtime" ], - "summary": "Get cluster compute status", - "description": "Returns auto-scaling state, machine count, and limits for a cluster.", + "summary": "Create a machine for the authenticated cluster", + "description": "Creates a machine using only the workspace and cluster scope encoded in the service-account token.", "security": [ { "BearerAuth": [] } ], - "parameters": [ - { - "schema": { - "type": "string", - "description": "Cluster ID" - }, - "required": true, - "description": "Cluster ID", - "name": "clusterId", - "in": "path" + "requestBody": { + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "config_ref": { + "type": "string", + "maxLength": 100, + "description": "Compute configuration name; derived from cluster context when omitted" + }, + "node_claim": { + "type": "object", + "properties": { + "metadata": { + "type": "object", + "properties": { + "name": { + "type": "string" + }, + "namespace": { + "type": "string" + }, + "labels": { + "type": "object", + "additionalProperties": { + "type": "string" + } + }, + "annotations": { + "type": "object", + "additionalProperties": { + "type": "string" + } + } + } + }, + "spec": { + "type": "object", + "properties": { + "requirements": { + "type": "array", + "items": { + "type": "object", + "properties": { + "key": { + "type": "string" + }, + "operator": { + "type": "string", + "enum": [ + "In", + "NotIn", + "Exists", + "DoesNotExist", + "Gt", + "Lt", + "Gte", + "Lte" + ] + }, + "values": { + "type": "array", + "items": { + "type": "string" + } + }, + "minValues": { + "type": "integer", + "minimum": 0, + "exclusiveMinimum": true + } + }, + "required": [ + "key", + "operator" + ] + } + }, + "resources": { + "type": "object", + "properties": { + "requests": { + "type": "object", + "additionalProperties": { + "type": "string" + } + } + } + }, + "nodeClassRef": { + "type": "object", + "nullable": true, + "properties": { + "group": { + "type": "string" + }, + "kind": { + "type": "string" + }, + "name": { + "type": "string" + } + }, + "required": [ + "group", + "kind", + "name" + ] + }, + "taints": { + "type": "array", + "items": { + "type": "object", + "properties": { + "key": { + "type": "string" + }, + "value": { + "type": "string" + }, + "effect": { + "type": "string", + "enum": [ + "NoSchedule", + "PreferNoSchedule", + "NoExecute" + ] + } + }, + "required": [ + "key", + "effect" + ] + } + }, + "startupTaints": { + "type": "array", + "items": { + "type": "object", + "properties": { + "key": { + "type": "string" + }, + "value": { + "type": "string" + }, + "effect": { + "type": "string", + "enum": [ + "NoSchedule", + "PreferNoSchedule", + "NoExecute" + ] + } + }, + "required": [ + "key", + "effect" + ] + } + }, + "terminationGracePeriod": { + "type": "string" + }, + "expireAfter": { + "type": "string" + } + }, + "required": [ + "requirements" + ] + }, + "status": { + "type": "object", + "properties": { + "providerId": { + "type": "string" + }, + "nodeName": { + "type": "string" + }, + "capacity": { + "type": "object", + "additionalProperties": { + "type": "string" + } + }, + "allocatable": { + "type": "object", + "additionalProperties": { + "type": "string" + } + }, + "imageID": { + "type": "string" + } + } + } + }, + "required": [ + "spec" + ], + "description": "Karpenter NodeClaim requirements for the new machine" + } + }, + "required": [ + "node_claim" + ], + "additionalProperties": false + } + } } - ], + }, "responses": { - "200": { - "description": "Compute status", + "201": { + "description": "Machine creation accepted", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClusterRuntimeMachine" + } + } + } + }, + "401": { + "description": "Unauthorized", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } + } + } + }, + "403": { + "description": "Cluster service-account authentication required", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClusterRuntimeError" + } + } + } + }, + "404": { + "description": "Compute configuration not found", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClusterRuntimeError" + } + } + } + }, + "422": { + "description": "Invalid runtime machine request", "content": { "application/json": { "schema": { - "type": "object", - "properties": { - "auto_scaling": { - "type": "string", - "enum": [ - "active", - "paused" - ] - }, - "machines": { - "type": "number" - }, - "max_machines": { - "type": "number" - } - }, - "required": [ - "auto_scaling", - "machines", - "max_machines" - ] + "$ref": "#/components/schemas/ClusterRuntimeError" } } } }, - "401": { - "description": "Unauthorized", + "429": { + "description": "Machine quota exhausted", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/ApiErrorResponse" + "$ref": "#/components/schemas/ClusterRuntimeError" } } } }, - "403": { - "description": "Akua-Context required", + "503": { + "description": "No matching capacity available", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/ApiErrorResponse" + "$ref": "#/components/schemas/ClusterRuntimeError" } } } } } - } - }, - "/v1/clusters/{clusterId}/compute_settings": { - "patch": { - "x-platform-visibility": "PUBLIC", - "operationId": "compute.updateClusterSettings", + }, + "get": { + "x-platform-visibility": "INTERNAL", + "operationId": "clusterRuntime.listMachines", "tags": [ - "Compute" + "Cluster Runtime" ], - "summary": "Update cluster compute settings", - "description": "Controls auto-scaling behavior and machine limits for a cluster.", + "summary": "List machines for the authenticated cluster", + "description": "Lists only machines assigned to the cluster encoded in the service-account token.", "security": [ { "BearerAuth": [] } ], - "parameters": [ - { - "schema": { - "type": "string", - "description": "Cluster ID" - }, - "required": true, - "description": "Cluster ID", - "name": "clusterId", - "in": "path" - } - ], - "requestBody": { - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "auto_scaling_enabled": { - "type": "boolean" - }, - "max_machines": { - "type": "number", - "minimum": 0, - "maximum": 100 + "responses": { + "200": { + "description": "Cluster machines", + "content": { + "application/json": { + "schema": { + "type": "array", + "items": { + "$ref": "#/components/schemas/ClusterRuntimeMachine" } } } } - } - }, - "responses": { - "204": { - "description": "Settings updated" }, "401": { "description": "Unauthorized", @@ -19175,11 +34975,11 @@ } }, "403": { - "description": "Akua-Context required", + "description": "Cluster service-account authentication required", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/ApiErrorResponse" + "$ref": "#/components/schemas/ClusterRuntimeError" } } } @@ -19187,71 +34987,40 @@ } } }, - "/v1/snippets": { + "/v1/cluster_runtime/machines/{provider_id}": { "get": { - "x-platform-visibility": "PUBLIC", - "x-platform-live": { - "visibility": "INTERNAL", - "transport": "convex", - "convexQuery": "snippet.ui.listSnippetsForApi" - }, - "operationId": "snippets.list", + "x-platform-visibility": "INTERNAL", + "operationId": "clusterRuntime.getMachine", "tags": [ - "Snippets" + "Cluster Runtime" ], - "summary": "List snippets in workspace", - "description": "Returns all snippets belonging to the workspace specified in the workspace context.", + "summary": "Get a machine in the authenticated cluster", + "description": "Returns a machine only when it belongs to the workspace and cluster encoded in the service-account token.", "security": [ { "BearerAuth": [] } ], "parameters": [ - { - "schema": { - "type": "string", - "description": "Pagination cursor from a previous response's `next_cursor`." - }, - "required": false, - "description": "Pagination cursor from a previous response's `next_cursor`.", - "name": "cursor", - "in": "query" - }, - { - "schema": { - "type": "integer", - "minimum": 1, - "maximum": 100, - "default": 50, - "description": "Items per page (1-100, default 50)", - "example": 50 - }, - "required": false, - "description": "Items per page (1-100, default 50)", - "name": "limit", - "in": "query" - }, { "schema": { "type": "string", "minLength": 1, - "maxLength": 53, - "description": "Optional workspace/scope context for the request. Carries a single workspace wire id (`ws_…`) today. Only needed for broad tokens — a workspace-owned token implies its workspace.", - "example": "ws_j572abc123def456" + "description": "Provider-assigned machine ID" }, - "required": false, - "description": "Optional workspace/scope context for the request. Carries a single workspace wire id (`ws_…`) today. Only needed for broad tokens — a workspace-owned token implies its workspace.", - "name": "akua-context", - "in": "header" + "required": true, + "description": "Provider-assigned machine ID", + "name": "provider_id", + "in": "path" } ], "responses": { "200": { - "description": "List of snippets", + "description": "Machine status", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/SnippetList" + "$ref": "#/components/schemas/ClusterRuntimeMachine" } } } @@ -19267,155 +35036,93 @@ } }, "403": { - "description": "Forbidden", + "description": "Cluster service-account authentication required", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/ApiErrorResponse" + "$ref": "#/components/schemas/ClusterRuntimeError" + } + } + } + }, + "404": { + "description": "Machine not found", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClusterRuntimeError" } } } } } }, - "post": { - "x-platform-visibility": "PUBLIC", - "operationId": "snippets.create", + "delete": { + "x-platform-visibility": "INTERNAL", + "operationId": "clusterRuntime.deleteMachine", "tags": [ - "Snippets" + "Cluster Runtime" ], - "summary": "Create snippet", - "description": "Creates a reusable code snippet in the workspace. Snippets are async JavaScript functions executed in a sandboxed runtime with access to platform.request() for API calls.", + "summary": "Report a drained machine deleted by the authenticated cluster", + "description": "Acknowledges Karpenter drain completion and starts deletion for a machine in the token-derived cluster.", "security": [ { "BearerAuth": [] } ], - "requestBody": { - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "name": { - "type": "string", - "minLength": 1, - "maxLength": 100, - "example": "Cluster Resource Audit" - }, - "description": { - "type": "string", - "maxLength": 500, - "description": "Optional human-readable description" - }, - "code": { - "type": "string", - "minLength": 1, - "maxLength": 50000, - "description": "Async JavaScript function body. Executed in a sandboxed runtime with access to platform.request()." - }, - "display_type": { - "type": "string", - "enum": [ - "table", - "stat", - "json", - "logs" - ], - "description": "Controls how the snippet result is rendered in dashboard widgets" - }, - "visibility": { - "type": "string", - "enum": [ - "workspace", - "session" - ], - "description": "Whether the snippet is reusable workspace state or scoped to an agent session." - }, - "origin": { - "type": "string", - "enum": [ - "user", - "agent", - "system" - ], - "description": "Who authored the snippet descriptor." - }, - "agent_session_id": { - "type": "string", - "minLength": 1, - "maxLength": 54 - }, - "agent_turn_id": { - "type": "string", - "minLength": 1, - "maxLength": 54 - }, - "purpose": { - "type": "string", - "enum": [ - "general", - "prepared_action", - "reactive_read", - "widget" - ] - } - }, - "required": [ - "name", - "code", - "display_type" - ], - "additionalProperties": false - } - } + "parameters": [ + { + "schema": { + "type": "string", + "minLength": 1, + "description": "Provider-assigned machine ID" + }, + "required": true, + "description": "Provider-assigned machine ID", + "name": "provider_id", + "in": "path" } - }, + ], "responses": { - "201": { - "description": "Snippet created", + "204": { + "description": "Machine deletion acknowledged" + }, + "401": { + "description": "Unauthorized", "content": { "application/json": { "schema": { - "type": "object", - "properties": { - "snippet_id": { - "type": "string" - } - }, - "required": [ - "snippet_id" - ] + "$ref": "#/components/schemas/ApiErrorResponse" } } } }, - "401": { - "description": "Unauthorized", + "403": { + "description": "Cluster service-account authentication required", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/ApiErrorResponse" + "$ref": "#/components/schemas/ClusterRuntimeError" } } } }, - "403": { - "description": "Forbidden", + "404": { + "description": "Machine not found", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/ApiErrorResponse" + "$ref": "#/components/schemas/ClusterRuntimeError" } } } }, - "422": { - "description": "Unprocessable entity", + "503": { + "description": "Machine lifecycle is unavailable", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/ApiErrorResponse" + "$ref": "#/components/schemas/ClusterRuntimeError" } } } @@ -19423,20 +35130,15 @@ } } }, - "/v1/snippets:usage": { + "/v1/cluster_runtime/machines/{provider_id}/drift": { "get": { - "x-platform-visibility": "PUBLIC", - "x-platform-live": { - "visibility": "INTERNAL", - "transport": "convex", - "convexQuery": "snippet.ui.listSnippetUsageForApi" - }, - "operationId": "snippets.listUsage", + "x-platform-visibility": "INTERNAL", + "operationId": "clusterRuntime.checkMachineDrift", "tags": [ - "Snippets" + "Cluster Runtime" ], - "summary": "List snippet dashboard usage in workspace", - "description": "Returns dashboard references for snippets in the workspace specified in the workspace context.", + "summary": "Check machine drift in the authenticated cluster", + "description": "Checks desired-state drift only for a machine in the workspace and cluster encoded in the service-account token.", "security": [ { "BearerAuth": [] @@ -19447,23 +35149,21 @@ "schema": { "type": "string", "minLength": 1, - "maxLength": 53, - "description": "Optional workspace/scope context for the request. Carries a single workspace wire id (`ws_…`) today. Only needed for broad tokens — a workspace-owned token implies its workspace.", - "example": "ws_j572abc123def456" + "description": "Provider-assigned machine ID" }, - "required": false, - "description": "Optional workspace/scope context for the request. Carries a single workspace wire id (`ws_…`) today. Only needed for broad tokens — a workspace-owned token implies its workspace.", - "name": "akua-context", - "in": "header" + "required": true, + "description": "Provider-assigned machine ID", + "name": "provider_id", + "in": "path" } ], "responses": { "200": { - "description": "Snippet dashboard usage", + "description": "Drift result", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/SnippetUsageList" + "$ref": "#/components/schemas/ClusterRuntimeDrift" } } } @@ -19479,11 +35179,31 @@ } }, "403": { - "description": "Forbidden", + "description": "Cluster service-account authentication required", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/ApiErrorResponse" + "$ref": "#/components/schemas/ClusterRuntimeError" + } + } + } + }, + "404": { + "description": "Machine not found", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClusterRuntimeError" + } + } + } + }, + "503": { + "description": "Machine lifecycle is unavailable", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClusterRuntimeError" } } } @@ -19491,20 +35211,15 @@ } } }, - "/v1/snippets/{id}:usage": { + "/v1/cluster_runtime/instance_types": { "get": { - "x-platform-visibility": "PUBLIC", - "x-platform-live": { - "visibility": "INTERNAL", - "transport": "convex", - "convexQuery": "snippet.ui.getSnippetUsageForApi" - }, - "operationId": "snippets.getUsage", + "x-platform-visibility": "INTERNAL", + "operationId": "clusterRuntime.listInstanceTypes", "tags": [ - "Snippets" + "Cluster Runtime" ], - "summary": "Get snippet dashboard usage", - "description": "Returns dashboard references for one snippet.", + "summary": "List instance types for the authenticated cluster", + "description": "Lists capacity eligible for the workspace and cluster encoded in the service-account token.", "security": [ { "BearerAuth": [] @@ -19514,23 +35229,25 @@ { "schema": { "type": "string", - "minLength": 1, - "maxLength": 54, - "description": "Snippet ID" + "maxLength": 100, + "description": "Compute configuration name; derived from cluster context when omitted" }, - "required": true, - "description": "Snippet ID", - "name": "id", - "in": "path" + "required": false, + "description": "Compute configuration name; derived from cluster context when omitted", + "name": "config", + "in": "query" } ], "responses": { "200": { - "description": "Snippet dashboard usage", + "description": "Available instance types", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/SnippetUsage" + "type": "array", + "items": { + "$ref": "#/components/schemas/ClusterRuntimeInstanceType" + } } } } @@ -19546,21 +35263,31 @@ } }, "403": { - "description": "Forbidden", + "description": "Cluster service-account authentication required", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/ApiErrorResponse" + "$ref": "#/components/schemas/ClusterRuntimeError" } } } }, "404": { - "description": "Not found", + "description": "Compute configuration not found", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/ApiErrorResponse" + "$ref": "#/components/schemas/ClusterRuntimeError" + } + } + } + }, + "422": { + "description": "Invalid instance-type query", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClusterRuntimeError" } } } @@ -19568,46 +35295,27 @@ } } }, - "/v1/snippets/{id}": { + "/v1/cluster_runtime/compute_status": { "get": { - "x-platform-visibility": "PUBLIC", - "x-platform-live": { - "visibility": "INTERNAL", - "transport": "convex", - "convexQuery": "snippet.ui.getSnippetForApi" - }, - "operationId": "snippets.get", + "x-platform-visibility": "INTERNAL", + "operationId": "clusterRuntime.getComputeStatus", "tags": [ - "Snippets" + "Cluster Runtime" ], - "summary": "Get snippet details", - "description": "Returns a snippet including its code and display type.", + "summary": "Get compute status for the authenticated cluster", + "description": "Returns autoscaling state and machine limits for the cluster encoded in the service-account token.", "security": [ { "BearerAuth": [] } ], - "parameters": [ - { - "schema": { - "type": "string", - "minLength": 1, - "maxLength": 54, - "description": "Snippet ID" - }, - "required": true, - "description": "Snippet ID", - "name": "id", - "in": "path" - } - ], "responses": { "200": { - "description": "Snippet details", + "description": "Cluster compute status", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/Snippet" + "$ref": "#/components/schemas/ClusterRuntimeComputeStatus" } } } @@ -19623,35 +35331,42 @@ } }, "403": { - "description": "Forbidden", + "description": "Cluster service-account authentication required", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/ApiErrorResponse" + "$ref": "#/components/schemas/ClusterRuntimeError" } } } }, "404": { - "description": "Not found", + "description": "Cluster not found", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/ApiErrorResponse" + "$ref": "#/components/schemas/ClusterRuntimeError" } } } } } - }, - "patch": { + } + }, + "/v1/clusters/{id}/compute_settings": { + "get": { "x-platform-visibility": "PUBLIC", - "operationId": "snippets.update", + "x-platform-live": { + "visibility": "PUBLIC", + "transport": "convex", + "convexQuery": "compute.ui.getClusterComputeSettingsForApi" + }, + "operationId": "clusters.getComputeSettings", "tags": [ - "Snippets" + "Clusters" ], - "summary": "Update snippet", - "description": "Updates snippet properties. Only provided fields are changed. Dashboards using this snippet will pick up code changes on next run.", + "summary": "Get cluster compute settings", + "description": "Returns autoscaling state, current machine usage, the configured limit, and the etag required for updates.", "security": [ { "BearerAuth": [] @@ -19663,10 +35378,10 @@ "type": "string", "minLength": 1, "maxLength": 54, - "description": "Snippet ID" + "description": "Cluster ID." }, "required": true, - "description": "Snippet ID", + "description": "Cluster ID.", "name": "id", "in": "path" }, @@ -19674,84 +35389,23 @@ "schema": { "type": "string", "minLength": 1, - "maxLength": 256, - "description": "The `etag` of the resource version the client last read. Required on writes when the resource exposes an `etag` field. Mismatch returns 409 `ABORTED` with the current etag in the error metadata.", - "example": "42" + "maxLength": 53, + "description": "Optional workspace/scope context for the request. Carries a single workspace wire id (`ws_…`) today. Only needed for broad tokens — a workspace-owned token implies its workspace.", + "example": "ws_j572abc123def456" }, - "required": true, - "description": "The `etag` of the resource version the client last read. Required on writes when the resource exposes an `etag` field. Mismatch returns 409 `ABORTED` with the current etag in the error metadata.", - "name": "if-match", + "required": false, + "description": "Optional workspace/scope context for the request. Carries a single workspace wire id (`ws_…`) today. Only needed for broad tokens — a workspace-owned token implies its workspace.", + "name": "akua-context", "in": "header" } ], - "requestBody": { - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "name": { - "type": "string", - "minLength": 1, - "maxLength": 100 - }, - "description": { - "type": "string", - "maxLength": 500 - }, - "code": { - "type": "string", - "minLength": 1, - "maxLength": 50000 - }, - "display_type": { - "type": "string", - "enum": [ - "table", - "stat", - "json", - "logs" - ], - "description": "Controls how the snippet result is rendered in dashboard widgets" - }, - "visibility": { - "type": "string", - "enum": [ - "workspace", - "session" - ], - "description": "Whether the snippet is reusable workspace state or scoped to an agent session." - }, - "purpose": { - "type": "string", - "enum": [ - "general", - "prepared_action", - "reactive_read", - "widget" - ] - } - }, - "additionalProperties": false - } - } - } - }, "responses": { "200": { - "description": "Snippet updated", + "description": "Cluster compute settings", "content": { "application/json": { "schema": { - "type": "object", - "properties": { - "snippet_id": { - "type": "string" - } - }, - "required": [ - "snippet_id" - ] + "$ref": "#/components/schemas/ClusterComputeSettings" } } } @@ -19766,8 +35420,8 @@ } } }, - "404": { - "description": "Not found", + "403": { + "description": "Forbidden", "content": { "application/json": { "schema": { @@ -19776,8 +35430,8 @@ } } }, - "409": { - "description": "Conflict", + "404": { + "description": "Not found", "content": { "application/json": { "schema": { @@ -19788,14 +35442,14 @@ } } }, - "delete": { + "patch": { "x-platform-visibility": "PUBLIC", - "operationId": "snippets.delete", + "operationId": "clusters.updateComputeSettings", "tags": [ - "Snippets" + "Clusters" ], - "summary": "Delete snippet", - "description": "Permanently deletes a snippet. Fails with 409 if the snippet is referenced by any dashboard widgets.", + "summary": "Update cluster compute settings", + "description": "Updates autoscaling or machine limits. If-Match is required and must contain the etag from the latest settings response.", "security": [ { "BearerAuth": [] @@ -19807,10 +35461,10 @@ "type": "string", "minLength": 1, "maxLength": 54, - "description": "Snippet ID" + "description": "Cluster ID." }, "required": true, - "description": "Snippet ID", + "description": "Cluster ID.", "name": "id", "in": "path" }, @@ -19818,98 +35472,56 @@ "schema": { "type": "string", "minLength": 1, - "maxLength": 256, - "description": "The `etag` of the resource version the client last read. Required on writes when the resource exposes an `etag` field. Mismatch returns 409 `ABORTED` with the current etag in the error metadata.", - "example": "42" + "maxLength": 53, + "description": "Optional workspace/scope context for the request. Carries a single workspace wire id (`ws_…`) today. Only needed for broad tokens — a workspace-owned token implies its workspace.", + "example": "ws_j572abc123def456" }, - "required": true, - "description": "The `etag` of the resource version the client last read. Required on writes when the resource exposes an `etag` field. Mismatch returns 409 `ABORTED` with the current etag in the error metadata.", - "name": "if-match", + "required": false, + "description": "Optional workspace/scope context for the request. Carries a single workspace wire id (`ws_…`) today. Only needed for broad tokens — a workspace-owned token implies its workspace.", + "name": "akua-context", "in": "header" - } - ], - "responses": { - "204": { - "description": "Snippet deleted" - }, - "401": { - "description": "Unauthorized", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/ApiErrorResponse" - } - } - } - }, - "404": { - "description": "Not found", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/ApiErrorResponse" - } - } - } }, - "409": { - "description": "Conflict", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/ApiErrorResponse" - } - } - } - } - } - } - }, - "/v1/snippets:execute": { - "post": { - "x-platform-visibility": "PUBLIC", - "operationId": "snippets.execute", - "tags": [ - "Snippets" - ], - "summary": "Execute ad-hoc snippet code", - "description": "Executes ad-hoc JavaScript in the snippet sandbox and returns the synchronous result. Does not persist a snippet or run resource.", - "security": [ - { - "BearerAuth": [] - } - ], - "parameters": [ { "schema": { "type": "string", "minLength": 1, - "maxLength": 53, - "description": "Optional workspace/scope context for the request. Carries a single workspace wire id (`ws_…`) today. Only needed for broad tokens — a workspace-owned token implies its workspace.", - "example": "ws_j572abc123def456" + "maxLength": 256, + "description": "The `etag` of the resource version the client last read. Required on writes when the resource exposes an `etag` field. Mismatch returns 409 `ABORTED` with the current etag in the error metadata.", + "example": "42" }, - "required": false, - "description": "Optional workspace/scope context for the request. Carries a single workspace wire id (`ws_…`) today. Only needed for broad tokens — a workspace-owned token implies its workspace.", - "name": "akua-context", + "required": true, + "description": "The `etag` of the resource version the client last read. Required on writes when the resource exposes an `etag` field. Mismatch returns 409 `ABORTED` with the current etag in the error metadata.", + "name": "if-match", "in": "header" } ], "requestBody": { + "required": true, "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/ExecuteSnippetBody" + "$ref": "#/components/schemas/UpdateClusterComputeSettingsBody" } } } }, "responses": { "200": { - "description": "Snippet execution result", + "description": "Cluster compute settings updated", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClusterComputeSettings" + } + } + } + }, + "400": { + "description": "Bad request", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/ExecuteSnippetResponse" + "$ref": "#/components/schemas/ApiErrorResponse" } } } @@ -19934,8 +35546,8 @@ } } }, - "422": { - "description": "Unprocessable entity", + "404": { + "description": "Not found", "content": { "application/json": { "schema": { @@ -19943,49 +35555,19 @@ } } } - } - } - } - }, - "/v1/snippets/{id}:execute": { - "post": { - "x-platform-visibility": "PUBLIC", - "operationId": "snippets.executeStored", - "tags": [ - "Snippets" - ], - "summary": "Execute stored snippet", - "description": "Fetches a stored snippet by ID server-side, executes its code in the snippet sandbox, and returns the synchronous result.", - "security": [ - { - "BearerAuth": [] - } - ], - "parameters": [ - { - "schema": { - "type": "string", - "minLength": 1, - "maxLength": 54 - }, - "required": true, - "name": "id", - "in": "path" - } - ], - "responses": { - "200": { - "description": "Snippet execution result", + }, + "409": { + "description": "Conflict", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/ExecuteSnippetResponse" + "$ref": "#/components/schemas/ApiErrorResponse" } } } }, - "401": { - "description": "Unauthorized", + "422": { + "description": "Unprocessable entity", "content": { "application/json": { "schema": { @@ -19994,8 +35576,8 @@ } } }, - "404": { - "description": "Not found", + "429": { + "description": "Too many requests", "content": { "application/json": { "schema": { @@ -20004,8 +35586,8 @@ } } }, - "422": { - "description": "Unprocessable entity", + "503": { + "description": "Service unavailable", "content": { "application/json": { "schema": { @@ -20017,31 +35599,21 @@ } } }, - "/v1/snippets/{id}/runs": { + "/v1/machines": { "post": { "x-platform-visibility": "PUBLIC", - "operationId": "snippets.createRun", "tags": [ - "Snippets" + "Machines" ], - "summary": "Create snippet run", - "description": "Creates a new snippet run resource under a snippet and starts execution. Idempotent with Idempotency-Key; callers receive the created run resource and Location header.", + "operationId": "machines.create", + "summary": "Create machine", + "description": "Creates a machine and returns a long-running operation envelope.", "security": [ { "BearerAuth": [] } ], "parameters": [ - { - "schema": { - "type": "string", - "minLength": 1, - "maxLength": 54 - }, - "required": true, - "name": "id", - "in": "path" - }, { "schema": { "type": "string", @@ -20060,11 +35632,11 @@ "type": "string", "minLength": 1, "maxLength": 64, - "description": "Caller-supplied idempotency key. Repeated requests with the same key return the existing resource instead of creating a duplicate. Safe to retry after a timed-out or interrupted request.", + "description": "Optional caller-supplied idempotency key. Any non-empty key up to 64 characters is accepted. Endpoint-specific documentation describes how the key is used.", "example": "create-prod-2026-05-07" }, "required": false, - "description": "Caller-supplied idempotency key. Repeated requests with the same key return the existing resource instead of creating a duplicate. Safe to retry after a timed-out or interrupted request.", + "description": "Optional caller-supplied idempotency key. Any non-empty key up to 64 characters is accepted. Endpoint-specific documentation describes how the key is used.", "name": "idempotency-key", "in": "header" } @@ -20073,18 +35645,50 @@ "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/CreateSnippetRunBody" + "type": "object", + "properties": { + "cluster_id": { + "type": "string", + "minLength": 1, + "maxLength": 54 + }, + "instance_type": { + "type": "string", + "minLength": 1 + }, + "compute_config_id": { + "type": "string", + "minLength": 1, + "maxLength": 54 + }, + "name": { + "type": "string", + "maxLength": 120 + }, + "node_claim": { + "type": "object", + "additionalProperties": { + "nullable": true + } + } + }, + "required": [ + "cluster_id", + "instance_type", + "compute_config_id" + ], + "additionalProperties": false } } } }, "responses": { - "201": { - "description": "Snippet run created", + "202": { + "description": "Machine creation accepted", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/SnippetRun" + "$ref": "#/components/schemas/MachineOperation" } } } @@ -20109,8 +35713,28 @@ } } }, - "422": { - "description": "Unprocessable entity", + "404": { + "description": "Not found", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } + } + } + }, + "409": { + "description": "Conflict", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } + } + } + }, + "503": { + "description": "Service unavailable", "content": { "application/json": { "schema": { @@ -20124,32 +35748,22 @@ "get": { "x-platform-visibility": "PUBLIC", "x-platform-live": { - "visibility": "INTERNAL", + "visibility": "PUBLIC", "transport": "convex", - "convexQuery": "snippet.ui.listSnippetRunsForApi" + "convexQuery": "compute.ui.listMachinesForApi" }, - "operationId": "snippets.listRuns", "tags": [ - "Snippets" + "Machines" ], - "summary": "List snippet runs", - "description": "Returns runs for a snippet. Use `view=basic` for a compact listing.", + "operationId": "machines.list", + "summary": "List machines", + "description": "Lists all machines in the workspace.", "security": [ { "BearerAuth": [] } ], "parameters": [ - { - "schema": { - "type": "string", - "minLength": 1, - "maxLength": 54 - }, - "required": true, - "name": "id", - "in": "path" - }, { "schema": { "type": "string", @@ -20174,16 +35788,31 @@ "name": "limit", "in": "query" }, + { + "schema": { + "type": "string", + "minLength": 1, + "maxLength": 54 + }, + "required": false, + "name": "cluster_id", + "in": "query" + }, { "schema": { "type": "string", "enum": [ - "succeeded", - "failed", - "timed_out" - ] + "ACTIVE", + "PROVISIONING", + "SUSPENDING", + "SUSPENDED", + "RESUMING", + "DELETING" + ], + "description": "Machine lifecycle state." }, "required": false, + "description": "Machine lifecycle state.", "name": "state", "in": "query" }, @@ -20194,22 +35823,33 @@ "basic", "full" ], - "default": "basic", - "description": "Control whether output and error details are included." + "default": "basic" }, "required": false, - "description": "Control whether output and error details are included.", "name": "view", "in": "query" + }, + { + "schema": { + "type": "string", + "minLength": 1, + "maxLength": 53, + "description": "Optional workspace/scope context for the request. Carries a single workspace wire id (`ws_…`) today. Only needed for broad tokens — a workspace-owned token implies its workspace.", + "example": "ws_j572abc123def456" + }, + "required": false, + "description": "Optional workspace/scope context for the request. Carries a single workspace wire id (`ws_…`) today. Only needed for broad tokens — a workspace-owned token implies its workspace.", + "name": "akua-context", + "in": "header" } ], "responses": { "200": { - "description": "List of snippet runs", + "description": "Machine list", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/SnippetRunList" + "$ref": "#/components/schemas/MachineList" } } } @@ -20223,34 +35863,24 @@ } } } - }, - "403": { - "description": "Forbidden", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/ApiErrorResponse" - } - } - } } } } }, - "/v1/snippets/{id}/runs/{run_id}": { + "/v1/clusters/{id}/workers:dashboardList": { "get": { - "x-platform-visibility": "PUBLIC", + "x-platform-visibility": "INTERNAL", "x-platform-live": { "visibility": "INTERNAL", "transport": "convex", - "convexQuery": "snippet.ui.getSnippetRun" + "convexQuery": "compute.ui.listDashboardClusterWorkersForApi" }, - "operationId": "snippets.getRun", "tags": [ - "Snippets" + "Clusters" ], - "summary": "Get snippet run", - "description": "Returns a single snippet run by ID.", + "operationId": "clusters.listDashboardWorkers", + "summary": "List dashboard cluster workers", + "description": "Lists managed machines and observed cluster nodes as one cursor-paginated dashboard worker projection.", "security": [ { "BearerAuth": [] @@ -20267,24 +35897,51 @@ "name": "id", "in": "path" }, + { + "schema": { + "type": "string", + "description": "Pagination cursor from a previous response's `next_cursor`." + }, + "required": false, + "description": "Pagination cursor from a previous response's `next_cursor`.", + "name": "cursor", + "in": "query" + }, + { + "schema": { + "type": "integer", + "minimum": 1, + "maximum": 100, + "default": 50, + "description": "Items per page (1-100, default 50)", + "example": 50 + }, + "required": false, + "description": "Items per page (1-100, default 50)", + "name": "limit", + "in": "query" + }, { "schema": { "type": "string", "minLength": 1, - "maxLength": 54 + "maxLength": 53, + "description": "Optional workspace/scope context for the request. Carries a single workspace wire id (`ws_…`) today. Only needed for broad tokens — a workspace-owned token implies its workspace.", + "example": "ws_j572abc123def456" }, - "required": true, - "name": "run_id", - "in": "path" + "required": false, + "description": "Optional workspace/scope context for the request. Carries a single workspace wire id (`ws_…`) today. Only needed for broad tokens — a workspace-owned token implies its workspace.", + "name": "akua-context", + "in": "header" } ], "responses": { "200": { - "description": "Snippet run details", + "description": "Dashboard cluster worker page", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/SnippetRun" + "$ref": "#/components/schemas/DashboardClusterWorkerList" } } } @@ -20322,20 +35979,15 @@ } } }, - "/v1/dashboards": { + "/v1/machines/{id}": { "get": { "x-platform-visibility": "PUBLIC", - "x-platform-live": { - "visibility": "INTERNAL", - "transport": "convex", - "convexQuery": "snippet.ui.listDashboardsForApi" - }, - "operationId": "dashboards.list", "tags": [ - "Dashboards" + "Machines" ], - "summary": "List dashboards in workspace", - "description": "Returns all dashboards belonging to the workspace specified in the workspace context.", + "operationId": "machines.get", + "summary": "Get machine", + "description": "Returns a machine by ID.", "security": [ { "BearerAuth": [] @@ -20345,26 +35997,12 @@ { "schema": { "type": "string", - "description": "Pagination cursor from a previous response's `next_cursor`." - }, - "required": false, - "description": "Pagination cursor from a previous response's `next_cursor`.", - "name": "cursor", - "in": "query" - }, - { - "schema": { - "type": "integer", - "minimum": 1, - "maximum": 100, - "default": 50, - "description": "Items per page (1-100, default 50)", - "example": 50 + "minLength": 1, + "maxLength": 54 }, - "required": false, - "description": "Items per page (1-100, default 50)", - "name": "limit", - "in": "query" + "required": true, + "name": "id", + "in": "path" }, { "schema": { @@ -20382,11 +36020,11 @@ ], "responses": { "200": { - "description": "List of dashboards", + "description": "Machine details", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/DashboardList" + "$ref": "#/components/schemas/Machine" } } } @@ -20410,22 +36048,83 @@ } } } + }, + "404": { + "description": "Not found", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } + } + } } } }, - "post": { + "patch": { "x-platform-visibility": "PUBLIC", - "operationId": "dashboards.create", "tags": [ - "Dashboards" + "Machines" ], - "summary": "Create dashboard", - "description": "Creates a dashboard in the workspace. Widgets are added through the dashboard widgets sub-collection.", + "operationId": "machines.update", + "summary": "Update machine", + "description": "Updates machine metadata.", "security": [ { "BearerAuth": [] } ], + "parameters": [ + { + "schema": { + "type": "string", + "minLength": 1, + "maxLength": 54 + }, + "required": true, + "name": "id", + "in": "path" + }, + { + "schema": { + "type": "string", + "minLength": 1, + "maxLength": 53, + "description": "Optional workspace/scope context for the request. Carries a single workspace wire id (`ws_…`) today. Only needed for broad tokens — a workspace-owned token implies its workspace.", + "example": "ws_j572abc123def456" + }, + "required": false, + "description": "Optional workspace/scope context for the request. Carries a single workspace wire id (`ws_…`) today. Only needed for broad tokens — a workspace-owned token implies its workspace.", + "name": "akua-context", + "in": "header" + }, + { + "schema": { + "type": "string", + "minLength": 1, + "maxLength": 64, + "description": "Optional caller-supplied idempotency key. Any non-empty key up to 64 characters is accepted. Endpoint-specific documentation describes how the key is used.", + "example": "create-prod-2026-05-07" + }, + "required": false, + "description": "Optional caller-supplied idempotency key. Any non-empty key up to 64 characters is accepted. Endpoint-specific documentation describes how the key is used.", + "name": "idempotency-key", + "in": "header" + }, + { + "schema": { + "type": "string", + "minLength": 1, + "maxLength": 256, + "description": "The `etag` of the resource version the client last read. Required on writes when the resource exposes an `etag` field. Mismatch returns 409 `ABORTED` with the current etag in the error metadata.", + "example": "42" + }, + "required": true, + "description": "The `etag` of the resource version the client last read. Required on writes when the resource exposes an `etag` field. Mismatch returns 409 `ABORTED` with the current etag in the error metadata.", + "name": "if-match", + "in": "header" + } + ], "requestBody": { "content": { "application/json": { @@ -20433,39 +36132,29 @@ "type": "object", "properties": { "name": { - "type": "string", - "minLength": 1, - "maxLength": 100, - "example": "Cluster Overview" - }, - "description": { - "type": "string", - "maxLength": 500 + "anyOf": [ + { + "type": "string", + "maxLength": 120 + }, + { + "nullable": true + } + ] } }, - "required": [ - "name" - ], "additionalProperties": false } } } }, "responses": { - "201": { - "description": "Dashboard created", + "200": { + "description": "Machine updated", "content": { "application/json": { "schema": { - "type": "object", - "properties": { - "dashboard_id": { - "type": "string" - } - }, - "required": [ - "dashboard_id" - ] + "$ref": "#/components/schemas/Machine" } } } @@ -20490,8 +36179,18 @@ } } }, - "422": { - "description": "Unprocessable entity", + "404": { + "description": "Not found", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } + } + } + }, + "409": { + "description": "Conflict", "content": { "application/json": { "schema": { @@ -20501,22 +36200,15 @@ } } } - } - }, - "/v1/dashboards/{id}": { - "get": { + }, + "delete": { "x-platform-visibility": "PUBLIC", - "x-platform-live": { - "visibility": "INTERNAL", - "transport": "convex", - "convexQuery": "snippet.ui.getDashboardForApi" - }, - "operationId": "dashboards.get", "tags": [ - "Dashboards" + "Machines" ], - "summary": "Get dashboard details", - "description": "Returns a dashboard including its widget layout and snippet references.", + "operationId": "machines.delete", + "summary": "Delete machine", + "description": "Deletes a machine and returns a long-running operation envelope.", "security": [ { "BearerAuth": [] @@ -20527,28 +36219,95 @@ "schema": { "type": "string", "minLength": 1, - "maxLength": 55, - "description": "Dashboard ID" + "maxLength": 54 }, "required": true, - "description": "Dashboard ID", "name": "id", "in": "path" + }, + { + "schema": { + "type": "string", + "minLength": 1, + "maxLength": 53, + "description": "Optional workspace/scope context for the request. Carries a single workspace wire id (`ws_…`) today. Only needed for broad tokens — a workspace-owned token implies its workspace.", + "example": "ws_j572abc123def456" + }, + "required": false, + "description": "Optional workspace/scope context for the request. Carries a single workspace wire id (`ws_…`) today. Only needed for broad tokens — a workspace-owned token implies its workspace.", + "name": "akua-context", + "in": "header" + }, + { + "schema": { + "type": "string", + "minLength": 1, + "maxLength": 64, + "description": "Required caller key for idempotent machine lifecycle operations.", + "example": "suspend-worker-2026-07-18" + }, + "required": true, + "description": "Required caller key for idempotent machine lifecycle operations.", + "name": "idempotency-key", + "in": "header" + }, + { + "schema": { + "type": "string", + "minLength": 1, + "maxLength": 256, + "description": "The `etag` of the resource version the client last read. Required on writes when the resource exposes an `etag` field. Mismatch returns 409 `ABORTED` with the current etag in the error metadata.", + "example": "42" + }, + "required": true, + "description": "The `etag` of the resource version the client last read. Required on writes when the resource exposes an `etag` field. Mismatch returns 409 `ABORTED` with the current etag in the error metadata.", + "name": "if-match", + "in": "header" } ], "responses": { - "200": { - "description": "Dashboard details", + "202": { + "description": "Machine deletion accepted", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/MachineOperation" + } + } + } + }, + "401": { + "description": "Unauthorized", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } + } + } + }, + "403": { + "description": "Forbidden", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } + } + } + }, + "404": { + "description": "Not found", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/Dashboard" + "$ref": "#/components/schemas/ApiErrorResponse" } } } }, - "401": { - "description": "Unauthorized", + "409": { + "description": "Conflict", "content": { "application/json": { "schema": { @@ -20557,8 +36316,8 @@ } } }, - "404": { - "description": "Not found", + "503": { + "description": "Service unavailable", "content": { "application/json": { "schema": { @@ -20568,15 +36327,17 @@ } } } - }, - "patch": { + } + }, + "/v1/machines/{id}:suspend": { + "post": { "x-platform-visibility": "PUBLIC", - "operationId": "dashboards.update", "tags": [ - "Dashboards" + "Machines" ], - "summary": "Update dashboard", - "description": "Update dashboard metadata. Widget mutations use the `/widgets` sub-collection.", + "operationId": "machines.suspend", + "summary": "Suspend machine", + "description": "Suspends a machine and returns a long-running operation envelope. On providers that recycle instances during suspension, the machine ID stays stable but the public IP usually changes on resume unless a floating IP is attached.", "security": [ { "BearerAuth": [] @@ -20587,14 +36348,38 @@ "schema": { "type": "string", "minLength": 1, - "maxLength": 55, - "description": "Dashboard ID" + "maxLength": 54 }, "required": true, - "description": "Dashboard ID", "name": "id", "in": "path" }, + { + "schema": { + "type": "string", + "minLength": 1, + "maxLength": 53, + "description": "Optional workspace/scope context for the request. Carries a single workspace wire id (`ws_…`) today. Only needed for broad tokens — a workspace-owned token implies its workspace.", + "example": "ws_j572abc123def456" + }, + "required": false, + "description": "Optional workspace/scope context for the request. Carries a single workspace wire id (`ws_…`) today. Only needed for broad tokens — a workspace-owned token implies its workspace.", + "name": "akua-context", + "in": "header" + }, + { + "schema": { + "type": "string", + "minLength": 1, + "maxLength": 64, + "description": "Required caller key for idempotent machine lifecycle operations.", + "example": "suspend-worker-2026-07-18" + }, + "required": true, + "description": "Required caller key for idempotent machine lifecycle operations.", + "name": "idempotency-key", + "in": "header" + }, { "schema": { "type": "string", @@ -20613,38 +36398,18 @@ "content": { "application/json": { "schema": { - "type": "object", - "properties": { - "name": { - "type": "string", - "minLength": 1, - "maxLength": 100 - }, - "description": { - "type": "string", - "maxLength": 500 - } - }, - "additionalProperties": false + "$ref": "#/components/schemas/SuspendMachineBody" } } } }, "responses": { - "200": { - "description": "Dashboard updated", + "202": { + "description": "Machine suspend accepted", "content": { "application/json": { "schema": { - "type": "object", - "properties": { - "dashboard_id": { - "type": "string" - } - }, - "required": [ - "dashboard_id" - ] + "$ref": "#/components/schemas/MachineOperation" } } } @@ -20659,6 +36424,16 @@ } } }, + "403": { + "description": "Forbidden", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } + } + } + }, "404": { "description": "Not found", "content": { @@ -20678,17 +36453,29 @@ } } } + }, + "503": { + "description": "Service unavailable", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } + } + } } } - }, - "delete": { + } + }, + "/v1/machines/{id}:resume": { + "post": { "x-platform-visibility": "PUBLIC", - "operationId": "dashboards.delete", "tags": [ - "Dashboards" + "Machines" ], - "summary": "Delete dashboard", - "description": "Permanently deletes a dashboard. Referenced snippets are not affected.", + "operationId": "machines.resume", + "summary": "Resume machine", + "description": "Resumes a suspended machine and returns a long-running operation envelope. The machine ID stays stable, but provider_resource.public_ip can change after resume on providers that recycle instances during suspension.", "security": [ { "BearerAuth": [] @@ -20699,14 +36486,38 @@ "schema": { "type": "string", "minLength": 1, - "maxLength": 55, - "description": "Dashboard ID" + "maxLength": 54 }, "required": true, - "description": "Dashboard ID", "name": "id", "in": "path" }, + { + "schema": { + "type": "string", + "minLength": 1, + "maxLength": 53, + "description": "Optional workspace/scope context for the request. Carries a single workspace wire id (`ws_…`) today. Only needed for broad tokens — a workspace-owned token implies its workspace.", + "example": "ws_j572abc123def456" + }, + "required": false, + "description": "Optional workspace/scope context for the request. Carries a single workspace wire id (`ws_…`) today. Only needed for broad tokens — a workspace-owned token implies its workspace.", + "name": "akua-context", + "in": "header" + }, + { + "schema": { + "type": "string", + "minLength": 1, + "maxLength": 64, + "description": "Required caller key for idempotent machine lifecycle operations.", + "example": "suspend-worker-2026-07-18" + }, + "required": true, + "description": "Required caller key for idempotent machine lifecycle operations.", + "name": "idempotency-key", + "in": "header" + }, { "schema": { "type": "string", @@ -20721,9 +36532,25 @@ "in": "header" } ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ResumeMachineBody" + } + } + } + }, "responses": { - "204": { - "description": "Dashboard deleted" + "202": { + "description": "Machine resume accepted", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/MachineOperation" + } + } + } }, "401": { "description": "Unauthorized", @@ -20735,6 +36562,16 @@ } } }, + "403": { + "description": "Forbidden", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } + } + } + }, "404": { "description": "Not found", "content": { @@ -20754,19 +36591,30 @@ } } } + }, + "503": { + "description": "Service unavailable", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } + } + } } } } }, - "/v1/dashboards/{id}/widgets": { + "/v1/machines/{id}/drift_reports": { "post": { "x-platform-visibility": "PUBLIC", - "operationId": "dashboards.createWidget", "tags": [ - "Dashboards" + "Machines" ], - "summary": "Create dashboard widget", - "description": "Creates a widget as a child resource under a dashboard.", + "operationId": "machines.createDriftReport", + "summary": "Create machine drift report", + "description": "Unsupported. This scaffold-only endpoint has no production handler. Do not call it in production.", + "deprecated": true, "security": [ { "BearerAuth": [] @@ -20777,7 +36625,7 @@ "schema": { "type": "string", "minLength": 1, - "maxLength": 55 + "maxLength": 54 }, "required": true, "name": "id", @@ -20801,11 +36649,11 @@ "type": "string", "minLength": 1, "maxLength": 64, - "description": "Caller-supplied idempotency key. Repeated requests with the same key return the existing resource instead of creating a duplicate. Safe to retry after a timed-out or interrupted request.", + "description": "Optional caller-supplied idempotency key. Any non-empty key up to 64 characters is accepted. Endpoint-specific documentation describes how the key is used.", "example": "create-prod-2026-05-07" }, "required": false, - "description": "Caller-supplied idempotency key. Repeated requests with the same key return the existing resource instead of creating a duplicate. Safe to retry after a timed-out or interrupted request.", + "description": "Optional caller-supplied idempotency key. Any non-empty key up to 64 characters is accepted. Endpoint-specific documentation describes how the key is used.", "name": "idempotency-key", "in": "header" } @@ -20816,59 +36664,10 @@ "schema": { "type": "object", "properties": { - "snippet_id": { - "type": "string", - "minLength": 1, - "maxLength": 54 - }, - "col_span": { - "anyOf": [ - { - "type": "number", - "enum": [ - 1 - ] - }, - { - "type": "number", - "enum": [ - 2 - ] - }, - { - "type": "number", - "enum": [ - 3 - ] - }, - { - "type": "number", - "enum": [ - 4 - ] - } - ] - }, - "display_type": { - "type": "string", - "nullable": true, - "enum": [ - "table", - "stat", - "json", - "logs", - null - ], - "description": "Controls how the snippet result is rendered in dashboard widgets" - }, - "position": { - "type": "integer" + "trigger": { + "type": "string" } }, - "required": [ - "snippet_id", - "col_span" - ], "additionalProperties": false } } @@ -20876,11 +36675,19 @@ }, "responses": { "201": { - "description": "Dashboard widget created", + "description": "Machine drift report created", + "headers": { + "Location": { + "schema": { + "type": "string" + }, + "description": "Location of the drift report." + } + }, "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/Widget" + "$ref": "#/components/schemas/DriftReport" } } } @@ -20919,12 +36726,13 @@ }, "get": { "x-platform-visibility": "PUBLIC", - "operationId": "dashboards.listWidgets", "tags": [ - "Dashboards" + "Machines" ], - "summary": "List dashboard widgets", - "description": "Lists widgets for a dashboard.", + "operationId": "machines.listDriftReports", + "summary": "List machine drift reports", + "description": "Unsupported. This scaffold-only endpoint has no production handler. Do not call it in production.", + "deprecated": true, "security": [ { "BearerAuth": [] @@ -20935,7 +36743,7 @@ "schema": { "type": "string", "minLength": 1, - "maxLength": 55 + "maxLength": 54 }, "required": true, "name": "id", @@ -20964,15 +36772,42 @@ "description": "Items per page (1-100, default 50)", "name": "limit", "in": "query" + }, + { + "schema": { + "type": "string", + "enum": [ + "in_sync", + "drifted" + ], + "description": "Machine drift comparison state." + }, + "required": false, + "description": "Machine drift comparison state.", + "name": "state", + "in": "query" + }, + { + "schema": { + "type": "string", + "minLength": 1, + "maxLength": 53, + "description": "Optional workspace/scope context for the request. Carries a single workspace wire id (`ws_…`) today. Only needed for broad tokens — a workspace-owned token implies its workspace.", + "example": "ws_j572abc123def456" + }, + "required": false, + "description": "Optional workspace/scope context for the request. Carries a single workspace wire id (`ws_…`) today. Only needed for broad tokens — a workspace-owned token implies its workspace.", + "name": "akua-context", + "in": "header" } ], "responses": { "200": { - "description": "List of dashboard widgets", + "description": "Drift report list", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/WidgetList" + "$ref": "#/components/schemas/DriftReportList" } } } @@ -20996,19 +36831,30 @@ } } } + }, + "404": { + "description": "Not found", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } + } + } } } } }, - "/v1/dashboards/{id}/widgets/{wgt_id}": { + "/v1/machines/{id}/drift_reports/{report_id}": { "get": { "x-platform-visibility": "PUBLIC", - "operationId": "dashboards.getWidget", "tags": [ - "Dashboards" + "Machines" ], - "summary": "Get dashboard widget", - "description": "Returns a single dashboard widget.", + "operationId": "machines.getDriftReport", + "summary": "Get machine drift report", + "description": "Unsupported. This scaffold-only endpoint has no production handler. Do not call it in production.", + "deprecated": true, "security": [ { "BearerAuth": [] @@ -21019,7 +36865,7 @@ "schema": { "type": "string", "minLength": 1, - "maxLength": 55 + "maxLength": 54 }, "required": true, "name": "id", @@ -21028,21 +36874,34 @@ { "schema": { "type": "string", - "minLength": 1, - "maxLength": 54 + "description": "Drift report ID" }, "required": true, - "name": "wgt_id", + "description": "Drift report ID", + "name": "report_id", "in": "path" + }, + { + "schema": { + "type": "string", + "minLength": 1, + "maxLength": 53, + "description": "Optional workspace/scope context for the request. Carries a single workspace wire id (`ws_…`) today. Only needed for broad tokens — a workspace-owned token implies its workspace.", + "example": "ws_j572abc123def456" + }, + "required": false, + "description": "Optional workspace/scope context for the request. Carries a single workspace wire id (`ws_…`) today. Only needed for broad tokens — a workspace-owned token implies its workspace.", + "name": "akua-context", + "in": "header" } ], "responses": { "200": { - "description": "Dashboard widget details", + "description": "Machine drift report", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/Widget" + "$ref": "#/components/schemas/DriftReport" } } } @@ -21057,6 +36916,16 @@ } } }, + "403": { + "description": "Forbidden", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } + } + } + }, "404": { "description": "Not found", "content": { @@ -21068,15 +36937,18 @@ } } } - }, - "patch": { + } + }, + "/v1/machines/{id}/suspension_events": { + "get": { "x-platform-visibility": "PUBLIC", - "operationId": "dashboards.updateWidget", "tags": [ - "Dashboards" + "Machines" ], - "summary": "Update dashboard widget", - "description": "Updates widget placement and display settings.", + "operationId": "machines.listSuspensionEvents", + "summary": "List machine suspension events", + "description": "Unsupported. This scaffold-only endpoint has no production handler. Do not call it in production.", + "deprecated": true, "security": [ { "BearerAuth": [] @@ -21087,7 +36959,7 @@ "schema": { "type": "string", "minLength": 1, - "maxLength": 55 + "maxLength": 54 }, "required": true, "name": "id", @@ -21096,115 +36968,60 @@ { "schema": { "type": "string", - "minLength": 1, - "maxLength": 54 + "description": "Pagination cursor from a previous response's `next_cursor`." }, - "required": true, - "name": "wgt_id", - "in": "path" + "required": false, + "description": "Pagination cursor from a previous response's `next_cursor`.", + "name": "cursor", + "in": "query" }, { "schema": { - "type": "string", - "minLength": 1, - "maxLength": 53, - "description": "Optional workspace/scope context for the request. Carries a single workspace wire id (`ws_…`) today. Only needed for broad tokens — a workspace-owned token implies its workspace.", - "example": "ws_j572abc123def456" + "type": "integer", + "minimum": 1, + "maximum": 100, + "default": 50, + "description": "Items per page (1-100, default 50)", + "example": 50 }, "required": false, - "description": "Optional workspace/scope context for the request. Carries a single workspace wire id (`ws_…`) today. Only needed for broad tokens — a workspace-owned token implies its workspace.", - "name": "akua-context", - "in": "header" + "description": "Items per page (1-100, default 50)", + "name": "limit", + "in": "query" }, { "schema": { "type": "string", - "minLength": 1, - "maxLength": 64, - "description": "Caller-supplied idempotency key. Repeated requests with the same key return the existing resource instead of creating a duplicate. Safe to retry after a timed-out or interrupted request.", - "example": "create-prod-2026-05-07" + "enum": [ + "manual", + "downgrade" + ] }, "required": false, - "description": "Caller-supplied idempotency key. Repeated requests with the same key return the existing resource instead of creating a duplicate. Safe to retry after a timed-out or interrupted request.", - "name": "idempotency-key", - "in": "header" + "name": "reason", + "in": "query" }, { "schema": { "type": "string", "minLength": 1, - "maxLength": 256, - "description": "The `etag` of the resource version the client last read. Required on writes when the resource exposes an `etag` field. Mismatch returns 409 `ABORTED` with the current etag in the error metadata.", - "example": "42" + "maxLength": 53, + "description": "Optional workspace/scope context for the request. Carries a single workspace wire id (`ws_…`) today. Only needed for broad tokens — a workspace-owned token implies its workspace.", + "example": "ws_j572abc123def456" }, - "required": true, - "description": "The `etag` of the resource version the client last read. Required on writes when the resource exposes an `etag` field. Mismatch returns 409 `ABORTED` with the current etag in the error metadata.", - "name": "if-match", + "required": false, + "description": "Optional workspace/scope context for the request. Carries a single workspace wire id (`ws_…`) today. Only needed for broad tokens — a workspace-owned token implies its workspace.", + "name": "akua-context", "in": "header" } ], - "requestBody": { - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "col_span": { - "anyOf": [ - { - "type": "number", - "enum": [ - 1 - ] - }, - { - "type": "number", - "enum": [ - 2 - ] - }, - { - "type": "number", - "enum": [ - 3 - ] - }, - { - "type": "number", - "enum": [ - 4 - ] - } - ] - }, - "position": { - "type": "integer" - }, - "display_type": { - "type": "string", - "nullable": true, - "enum": [ - "table", - "stat", - "json", - "logs", - null - ], - "description": "Controls how the snippet result is rendered in dashboard widgets" - } - }, - "additionalProperties": false - } - } - } - }, "responses": { "200": { - "description": "Dashboard widget updated", + "description": "Suspension event list", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/Widget" + "$ref": "#/components/schemas/SuspensionEventList" } } } @@ -21238,37 +37055,20 @@ } } } - }, - "409": { - "description": "Conflict", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/ApiErrorResponse" - } - } - } - }, - "422": { - "description": "Unprocessable entity", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/ApiErrorResponse" - } - } - } } } - }, - "delete": { + } + }, + "/v1/machines/{id}/suspension_events/{event_id}": { + "get": { "x-platform-visibility": "PUBLIC", - "operationId": "dashboards.deleteWidget", "tags": [ - "Dashboards" + "Machines" ], - "summary": "Delete dashboard widget", - "description": "Deletes a dashboard widget. Snippet references are preserved.", + "operationId": "machines.getSuspensionEvent", + "summary": "Get machine suspension event", + "description": "Unsupported. This scaffold-only endpoint has no production handler. Do not call it in production.", + "deprecated": true, "security": [ { "BearerAuth": [] @@ -21279,7 +37079,7 @@ "schema": { "type": "string", "minLength": 1, - "maxLength": 55 + "maxLength": 54 }, "required": true, "name": "id", @@ -21292,7 +37092,7 @@ "maxLength": 54 }, "required": true, - "name": "wgt_id", + "name": "event_id", "in": "path" }, { @@ -21307,37 +37107,21 @@ "description": "Optional workspace/scope context for the request. Carries a single workspace wire id (`ws_…`) today. Only needed for broad tokens — a workspace-owned token implies its workspace.", "name": "akua-context", "in": "header" - }, - { - "schema": { - "type": "string", - "minLength": 1, - "maxLength": 256, - "description": "The `etag` of the resource version the client last read. Required on writes when the resource exposes an `etag` field. Mismatch returns 409 `ABORTED` with the current etag in the error metadata.", - "example": "42" - }, - "required": true, - "description": "The `etag` of the resource version the client last read. Required on writes when the resource exposes an `etag` field. Mismatch returns 409 `ABORTED` with the current etag in the error metadata.", - "name": "if-match", - "in": "header" } ], "responses": { - "204": { - "description": "Dashboard widget deleted" - }, - "401": { - "description": "Unauthorized", + "200": { + "description": "Suspension event", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/ApiErrorResponse" + "$ref": "#/components/schemas/SuspensionEvent" } } } }, - "403": { - "description": "Forbidden", + "401": { + "description": "Unauthorized", "content": { "application/json": { "schema": { @@ -21346,8 +37130,8 @@ } } }, - "404": { - "description": "Not found", + "403": { + "description": "Forbidden", "content": { "application/json": { "schema": { @@ -21356,8 +37140,8 @@ } } }, - "409": { - "description": "Conflict", + "404": { + "description": "Not found", "content": { "application/json": { "schema": { @@ -21369,15 +37153,15 @@ } } }, - "/v1/machines": { + "/v1/compute_configs": { "post": { "x-platform-visibility": "PUBLIC", "tags": [ - "Machines" + "ComputeConfigs" ], - "operationId": "machines.create", - "summary": "Create machine", - "description": "Creates a machine and returns a long-running operation envelope.", + "operationId": "computeConfigs.create", + "summary": "Create compute config", + "description": "Creates a compute config row.", "security": [ { "BearerAuth": [] @@ -21402,11 +37186,11 @@ "type": "string", "minLength": 1, "maxLength": 64, - "description": "Caller-supplied idempotency key. Repeated requests with the same key return the existing resource instead of creating a duplicate. Safe to retry after a timed-out or interrupted request.", + "description": "Optional caller-supplied idempotency key. Any non-empty key up to 64 characters is accepted. Endpoint-specific documentation describes how the key is used.", "example": "create-prod-2026-05-07" }, "required": false, - "description": "Caller-supplied idempotency key. Repeated requests with the same key return the existing resource instead of creating a duplicate. Safe to retry after a timed-out or interrupted request.", + "description": "Optional caller-supplied idempotency key. Any non-empty key up to 64 characters is accepted. Endpoint-specific documentation describes how the key is used.", "name": "idempotency-key", "in": "header" } @@ -21417,35 +37201,46 @@ "schema": { "type": "object", "properties": { - "cluster_id": { - "type": "string", - "minLength": 1, - "maxLength": 54 - }, - "instance_type": { - "type": "string", - "minLength": 1 - }, - "compute_config_id": { + "name": { "type": "string", "minLength": 1, - "maxLength": 54 + "maxLength": 100 }, - "name": { + "provider": { "type": "string", - "maxLength": 120 + "enum": [ + "hcloud" + ] }, - "node_claim": { + "provider_config": { "type": "object", - "additionalProperties": { - "nullable": true - } + "properties": { + "region": { + "type": "string", + "minLength": 1 + }, + "image": { + "type": "string", + "minLength": 1 + }, + "machine_type_filter": { + "type": "string" + } + }, + "required": [ + "region", + "image" + ] + }, + "credential_scope": { + "$ref": "#/components/schemas/CredentialScope" } }, "required": [ - "cluster_id", - "instance_type", - "compute_config_id" + "name", + "provider", + "provider_config", + "credential_scope" ], "additionalProperties": false } @@ -21453,12 +37248,12 @@ } }, "responses": { - "202": { - "description": "Machine creation accepted", + "201": { + "description": "Compute config created", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/OperationEnvelope" + "$ref": "#/components/schemas/ComputeConfig" } } } @@ -21482,36 +37277,6 @@ } } } - }, - "404": { - "description": "Not found", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/ApiErrorResponse" - } - } - } - }, - "409": { - "description": "Conflict", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/ApiErrorResponse" - } - } - } - }, - "503": { - "description": "Service unavailable", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/ApiErrorResponse" - } - } - } } } }, @@ -21520,14 +37285,14 @@ "x-platform-live": { "visibility": "PUBLIC", "transport": "convex", - "convexQuery": "compute.ui.listMachinesForApi" + "convexQuery": "compute.ui.listComputeConfigsForApi" }, "tags": [ - "Machines" + "ComputeConfigs" ], - "operationId": "machines.list", - "summary": "List machines", - "description": "Lists all machines in the workspace.", + "operationId": "computeConfigs.list", + "summary": "List compute configs", + "description": "Lists compute configs in the workspace.", "security": [ { "BearerAuth": [] @@ -21558,34 +37323,6 @@ "name": "limit", "in": "query" }, - { - "schema": { - "type": "string", - "minLength": 1, - "maxLength": 54 - }, - "required": false, - "name": "cluster_id", - "in": "query" - }, - { - "schema": { - "type": "string", - "enum": [ - "ACTIVE", - "PROVISIONING", - "SUSPENDING", - "SUSPENDED", - "RESUMING", - "DELETING" - ], - "description": "Machine lifecycle state." - }, - "required": false, - "description": "Machine lifecycle state.", - "name": "state", - "in": "query" - }, { "schema": { "type": "string", @@ -21615,11 +37352,11 @@ ], "responses": { "200": { - "description": "Machine list", + "description": "Compute config list", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/MachineList" + "$ref": "#/components/schemas/ComputeConfigList" } } } @@ -21637,15 +37374,15 @@ } } }, - "/v1/machines/{id}": { + "/v1/compute_configs/{id}": { "get": { "x-platform-visibility": "PUBLIC", "tags": [ - "Machines" + "ComputeConfigs" ], - "operationId": "machines.get", - "summary": "Get machine", - "description": "Returns a machine by ID.", + "operationId": "computeConfigs.get", + "summary": "Get compute config", + "description": "Returns a compute config by ID.", "security": [ { "BearerAuth": [] @@ -21678,11 +37415,11 @@ ], "responses": { "200": { - "description": "Machine details", + "description": "Compute config details", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/Machine" + "$ref": "#/components/schemas/ComputeConfig" } } } @@ -21722,11 +37459,11 @@ "patch": { "x-platform-visibility": "PUBLIC", "tags": [ - "Machines" + "ComputeConfigs" ], - "operationId": "machines.update", - "summary": "Update machine", - "description": "Updates machine metadata.", + "operationId": "computeConfigs.update", + "summary": "Update compute config", + "description": "Updates mutable fields of a compute config.", "security": [ { "BearerAuth": [] @@ -21761,11 +37498,11 @@ "type": "string", "minLength": 1, "maxLength": 64, - "description": "Caller-supplied idempotency key. Repeated requests with the same key return the existing resource instead of creating a duplicate. Safe to retry after a timed-out or interrupted request.", + "description": "Optional caller-supplied idempotency key. Any non-empty key up to 64 characters is accepted. Endpoint-specific documentation describes how the key is used.", "example": "create-prod-2026-05-07" }, "required": false, - "description": "Caller-supplied idempotency key. Repeated requests with the same key return the existing resource instead of creating a duplicate. Safe to retry after a timed-out or interrupted request.", + "description": "Optional caller-supplied idempotency key. Any non-empty key up to 64 characters is accepted. Endpoint-specific documentation describes how the key is used.", "name": "idempotency-key", "in": "header" }, @@ -21790,15 +37527,28 @@ "type": "object", "properties": { "name": { - "anyOf": [ - { + "type": "string", + "minLength": 1, + "maxLength": 100 + }, + "provider_config": { + "type": "object", + "properties": { + "region": { "type": "string", - "maxLength": 120 + "minLength": 1 }, - { - "nullable": true + "image": { + "type": "string", + "minLength": 1 + }, + "machine_type_filter": { + "type": "string" } - ] + } + }, + "credential_scope": { + "$ref": "#/components/schemas/CredentialScope" } }, "additionalProperties": false @@ -21808,11 +37558,11 @@ }, "responses": { "200": { - "description": "Machine updated", + "description": "Compute config updated", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/Machine" + "$ref": "#/components/schemas/ComputeConfig" } } } @@ -21862,11 +37612,11 @@ "delete": { "x-platform-visibility": "PUBLIC", "tags": [ - "Machines" + "ComputeConfigs" ], - "operationId": "machines.delete", - "summary": "Delete machine", - "description": "Deletes a machine and returns a long-running operation envelope.", + "operationId": "computeConfigs.delete", + "summary": "Delete compute config", + "description": "Deletes a compute config.", "security": [ { "BearerAuth": [] @@ -21901,11 +37651,11 @@ "type": "string", "minLength": 1, "maxLength": 64, - "description": "Caller-supplied idempotency key. Repeated requests with the same key return the existing resource instead of creating a duplicate. Safe to retry after a timed-out or interrupted request.", + "description": "Optional caller-supplied idempotency key. Any non-empty key up to 64 characters is accepted. Endpoint-specific documentation describes how the key is used.", "example": "create-prod-2026-05-07" }, "required": false, - "description": "Caller-supplied idempotency key. Repeated requests with the same key return the existing resource instead of creating a duplicate. Safe to retry after a timed-out or interrupted request.", + "description": "Optional caller-supplied idempotency key. Any non-empty key up to 64 characters is accepted. Endpoint-specific documentation describes how the key is used.", "name": "idempotency-key", "in": "header" }, @@ -21924,12 +37674,314 @@ } ], "responses": { - "202": { - "description": "Machine deletion accepted", + "200": { + "description": "Compute config deleted", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ComputeConfig" + } + } + } + }, + "401": { + "description": "Unauthorized", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } + } + } + }, + "403": { + "description": "Forbidden", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } + } + } + }, + "404": { + "description": "Not found", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } + } + } + }, + "409": { + "description": "Conflict", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } + } + } + } + } + } + }, + "/v1/products": { + "get": { + "x-platform-visibility": "PUBLIC", + "operationId": "products.list", + "tags": [ + "Products" + ], + "summary": "List products in workspace", + "description": "Returns all products belonging to the workspace specified in the workspace context.", + "security": [ + { + "BearerAuth": [] + } + ], + "parameters": [ + { + "schema": { + "type": "string", + "description": "Pagination cursor from a previous response's `next_cursor`." + }, + "required": false, + "description": "Pagination cursor from a previous response's `next_cursor`.", + "name": "cursor", + "in": "query" + }, + { + "schema": { + "type": "integer", + "minimum": 1, + "maximum": 100, + "default": 50, + "description": "Items per page (1-100, default 50)", + "example": 50 + }, + "required": false, + "description": "Items per page (1-100, default 50)", + "name": "limit", + "in": "query" + }, + { + "schema": { + "type": "string", + "minLength": 1, + "maxLength": 53, + "description": "Optional workspace/scope context for the request. Carries a single workspace wire id (`ws_…`) today. Only needed for broad tokens — a workspace-owned token implies its workspace.", + "example": "ws_j572abc123def456" + }, + "required": false, + "description": "Optional workspace/scope context for the request. Carries a single workspace wire id (`ws_…`) today. Only needed for broad tokens — a workspace-owned token implies its workspace.", + "name": "akua-context", + "in": "header" + } + ], + "responses": { + "200": { + "description": "List of products", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ProductList" + } + } + } + }, + "401": { + "description": "Unauthorized", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } + } + } + }, + "403": { + "description": "Forbidden", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } + } + } + } + } + }, + "post": { + "x-platform-visibility": "PUBLIC", + "operationId": "products.create", + "tags": [ + "Products" + ], + "summary": "Create product", + "description": "Creates a Product backed by an existing Package and package version pin. Package source import belongs to the Packages API.", + "security": [ + { + "BearerAuth": [] + } + ], + "parameters": [ + { + "schema": { + "type": "string", + "minLength": 1, + "maxLength": 53, + "description": "Optional workspace/scope context for the request. Carries a single workspace wire id (`ws_…`) today. Only needed for broad tokens — a workspace-owned token implies its workspace.", + "example": "ws_j572abc123def456" + }, + "required": false, + "description": "Optional workspace/scope context for the request. Carries a single workspace wire id (`ws_…`) today. Only needed for broad tokens — a workspace-owned token implies its workspace.", + "name": "akua-context", + "in": "header" + }, + { + "schema": { + "type": "string", + "minLength": 1, + "maxLength": 64, + "description": "Optional caller-supplied idempotency key. Any non-empty key up to 64 characters is accepted. Endpoint-specific documentation describes how the key is used.", + "example": "create-prod-2026-05-07" + }, + "required": false, + "description": "Optional caller-supplied idempotency key. Any non-empty key up to 64 characters is accepted. Endpoint-specific documentation describes how the key is used.", + "name": "idempotency-key", + "in": "header" + } + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/CreateProductBody" + } + } + } + }, + "responses": { + "201": { + "description": "Product created", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Product" + } + } + } + }, + "400": { + "description": "Bad request", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } + } + } + }, + "401": { + "description": "Unauthorized", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } + } + } + }, + "403": { + "description": "Forbidden", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } + } + } + }, + "422": { + "description": "Unprocessable entity", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } + } + } + } + } + } + }, + "/v1/products:dashboardList": { + "get": { + "x-platform-visibility": "INTERNAL", + "x-platform-live": { + "visibility": "INTERNAL", + "transport": "convex", + "convexQuery": "product.ui.listDashboardProductsForApi" + }, + "operationId": "products.listDashboard", + "tags": [ + "Products" + ], + "summary": "List dashboard products in workspace", + "description": "Returns product rows shaped for the dashboard product catalog, including target counts.", + "security": [ + { + "BearerAuth": [] + } + ], + "parameters": [ + { + "schema": { + "type": "string", + "description": "Pagination cursor from a previous response's `next_cursor`." + }, + "required": false, + "description": "Pagination cursor from a previous response's `next_cursor`.", + "name": "cursor", + "in": "query" + }, + { + "schema": { + "type": "integer", + "minimum": 1, + "maximum": 100, + "default": 50, + "description": "Items per page (1-100, default 50)", + "example": 50 + }, + "required": false, + "description": "Items per page (1-100, default 50)", + "name": "limit", + "in": "query" + }, + { + "schema": { + "type": "string", + "minLength": 1, + "maxLength": 53, + "description": "Optional workspace/scope context for the request. Carries a single workspace wire id (`ws_…`) today. Only needed for broad tokens — a workspace-owned token implies its workspace.", + "example": "ws_j572abc123def456" + }, + "required": false, + "description": "Optional workspace/scope context for the request. Carries a single workspace wire id (`ws_…`) today. Only needed for broad tokens — a workspace-owned token implies its workspace.", + "name": "akua-context", + "in": "header" + } + ], + "responses": { + "200": { + "description": "Dashboard product list", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/OperationEnvelope" + "$ref": "#/components/schemas/DashboardProductList" } } } @@ -21953,19 +38005,42 @@ } } } - }, - "404": { - "description": "Not found", + } + } + } + }, + "/v1/products:marketplaceList": { + "get": { + "x-platform-visibility": "INTERNAL", + "x-platform-live": { + "visibility": "INTERNAL", + "transport": "convex", + "convexQuery": "product.ui.getMarketplaceProductsForUi" + }, + "operationId": "products.listMarketplace", + "tags": [ + "Products" + ], + "summary": "List marketplace products", + "description": "Returns product rows shaped for the marketplace catalog.", + "security": [ + { + "BearerAuth": [] + } + ], + "responses": { + "200": { + "description": "Marketplace product list", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/ApiErrorResponse" + "$ref": "#/components/schemas/MarketplaceProductList" } } } }, - "409": { - "description": "Conflict", + "401": { + "description": "Unauthorized", "content": { "application/json": { "schema": { @@ -21977,15 +38052,20 @@ } } }, - "/v1/machines/{id}:suspend": { - "post": { - "x-platform-visibility": "PUBLIC", + "/v1/products/{id}:dashboard": { + "get": { + "x-platform-visibility": "INTERNAL", + "x-platform-live": { + "visibility": "INTERNAL", + "transport": "convex", + "convexQuery": "product.ui.getProductDashboardForApi" + }, + "operationId": "products.getDashboard", "tags": [ - "Machines" + "Products" ], - "operationId": "machines.suspend", - "summary": "Suspend machine", - "description": "Suspends a machine and returns a long-running operation envelope. On providers that recycle instances during suspension, the machine ID stays stable but the public IP usually changes on resume unless a floating IP is attached.", + "summary": "Get product dashboard summary", + "description": "Returns the product-level customer, install, offer, and redemption summary used by the product dashboard.", "security": [ { "BearerAuth": [] @@ -21996,9 +38076,12 @@ "schema": { "type": "string", "minLength": 1, - "maxLength": 54 + "maxLength": 55, + "description": "Product ID", + "example": "prod_j572abc..." }, "required": true, + "description": "Product ID", "name": "id", "in": "path" }, @@ -22014,50 +38097,15 @@ "description": "Optional workspace/scope context for the request. Carries a single workspace wire id (`ws_…`) today. Only needed for broad tokens — a workspace-owned token implies its workspace.", "name": "akua-context", "in": "header" - }, - { - "schema": { - "type": "string", - "minLength": 1, - "maxLength": 64, - "description": "Caller-supplied idempotency key. Repeated requests with the same key return the existing resource instead of creating a duplicate. Safe to retry after a timed-out or interrupted request.", - "example": "create-prod-2026-05-07" - }, - "required": false, - "description": "Caller-supplied idempotency key. Repeated requests with the same key return the existing resource instead of creating a duplicate. Safe to retry after a timed-out or interrupted request.", - "name": "idempotency-key", - "in": "header" - }, - { - "schema": { - "type": "string", - "minLength": 1, - "maxLength": 256, - "description": "The `etag` of the resource version the client last read. Required on writes when the resource exposes an `etag` field. Mismatch returns 409 `ABORTED` with the current etag in the error metadata.", - "example": "42" - }, - "required": true, - "description": "The `etag` of the resource version the client last read. Required on writes when the resource exposes an `etag` field. Mismatch returns 409 `ABORTED` with the current etag in the error metadata.", - "name": "if-match", - "in": "header" } ], - "requestBody": { - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/SuspendMachineBody" - } - } - } - }, "responses": { - "202": { - "description": "Machine suspend accepted", + "200": { + "description": "Product dashboard summary", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/OperationEnvelope" + "$ref": "#/components/schemas/ProductDashboard" } } } @@ -22091,29 +38139,24 @@ } } } - }, - "409": { - "description": "Conflict", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/ApiErrorResponse" - } - } - } } } } }, - "/v1/machines/{id}:resume": { - "post": { - "x-platform-visibility": "PUBLIC", + "/v1/products/{id}:marketplace": { + "get": { + "x-platform-visibility": "INTERNAL", + "x-platform-live": { + "visibility": "INTERNAL", + "transport": "convex", + "convexQuery": "product.ui.getPublicProductForUi" + }, + "operationId": "products.getMarketplace", "tags": [ - "Machines" + "Products" ], - "operationId": "machines.resume", - "summary": "Resume machine", - "description": "Resumes a suspended machine and returns a long-running operation envelope. The machine ID stays stable, but provider_resource.public_ip can change after resume on providers that recycle instances during suspension.", + "summary": "Get marketplace product", + "description": "Returns product detail shaped for the marketplace product page.", "security": [ { "BearerAuth": [] @@ -22124,68 +38167,23 @@ "schema": { "type": "string", "minLength": 1, - "maxLength": 54 + "maxLength": 55, + "description": "Product ID", + "example": "prod_j572abc..." }, "required": true, + "description": "Product ID", "name": "id", "in": "path" - }, - { - "schema": { - "type": "string", - "minLength": 1, - "maxLength": 53, - "description": "Optional workspace/scope context for the request. Carries a single workspace wire id (`ws_…`) today. Only needed for broad tokens — a workspace-owned token implies its workspace.", - "example": "ws_j572abc123def456" - }, - "required": false, - "description": "Optional workspace/scope context for the request. Carries a single workspace wire id (`ws_…`) today. Only needed for broad tokens — a workspace-owned token implies its workspace.", - "name": "akua-context", - "in": "header" - }, - { - "schema": { - "type": "string", - "minLength": 1, - "maxLength": 64, - "description": "Caller-supplied idempotency key. Repeated requests with the same key return the existing resource instead of creating a duplicate. Safe to retry after a timed-out or interrupted request.", - "example": "create-prod-2026-05-07" - }, - "required": false, - "description": "Caller-supplied idempotency key. Repeated requests with the same key return the existing resource instead of creating a duplicate. Safe to retry after a timed-out or interrupted request.", - "name": "idempotency-key", - "in": "header" - }, - { - "schema": { - "type": "string", - "minLength": 1, - "maxLength": 256, - "description": "The `etag` of the resource version the client last read. Required on writes when the resource exposes an `etag` field. Mismatch returns 409 `ABORTED` with the current etag in the error metadata.", - "example": "42" - }, - "required": true, - "description": "The `etag` of the resource version the client last read. Required on writes when the resource exposes an `etag` field. Mismatch returns 409 `ABORTED` with the current etag in the error metadata.", - "name": "if-match", - "in": "header" } ], - "requestBody": { - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/ResumeMachineBody" - } - } - } - }, "responses": { - "202": { - "description": "Machine resume accepted", + "200": { + "description": "Marketplace product detail", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/OperationEnvelope" + "$ref": "#/components/schemas/MarketplaceProductDetail" } } } @@ -22200,16 +38198,6 @@ } } }, - "403": { - "description": "Forbidden", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/ApiErrorResponse" - } - } - } - }, "404": { "description": "Not found", "content": { @@ -22219,29 +38207,24 @@ } } } - }, - "409": { - "description": "Conflict", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/ApiErrorResponse" - } - } - } } } } }, - "/v1/machines/{id}/drift_reports": { - "post": { + "/v1/products/{id}": { + "get": { "x-platform-visibility": "PUBLIC", + "x-platform-live": { + "visibility": "INTERNAL", + "transport": "convex", + "convexQuery": "product.ui.getProductForApi" + }, + "operationId": "products.get", "tags": [ - "Machines" + "Products" ], - "operationId": "machines.createDriftReport", - "summary": "Create machine drift report", - "description": "Runs drift detection and stores a dedicated report row.", + "summary": "Get product details", + "description": "Returns product metadata including the backing Package and marketplace settings.", "security": [ { "BearerAuth": [] @@ -22252,9 +38235,12 @@ "schema": { "type": "string", "minLength": 1, - "maxLength": 54 + "maxLength": 55, + "description": "Product ID", + "example": "prod_j572abc..." }, "required": true, + "description": "Product ID", "name": "id", "in": "path" }, @@ -22270,51 +38256,15 @@ "description": "Optional workspace/scope context for the request. Carries a single workspace wire id (`ws_…`) today. Only needed for broad tokens — a workspace-owned token implies its workspace.", "name": "akua-context", "in": "header" - }, - { - "schema": { - "type": "string", - "minLength": 1, - "maxLength": 64, - "description": "Caller-supplied idempotency key. Repeated requests with the same key return the existing resource instead of creating a duplicate. Safe to retry after a timed-out or interrupted request.", - "example": "create-prod-2026-05-07" - }, - "required": false, - "description": "Caller-supplied idempotency key. Repeated requests with the same key return the existing resource instead of creating a duplicate. Safe to retry after a timed-out or interrupted request.", - "name": "idempotency-key", - "in": "header" } ], - "requestBody": { - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "trigger": { - "type": "string" - } - }, - "additionalProperties": false - } - } - } - }, "responses": { - "201": { - "description": "Machine drift report created", - "headers": { - "Location": { - "schema": { - "type": "string" - }, - "description": "Location of the drift report." - } - }, + "200": { + "description": "Product details", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/DriftReport" + "$ref": "#/components/schemas/Product" } } } @@ -22351,14 +38301,14 @@ } } }, - "get": { + "patch": { "x-platform-visibility": "PUBLIC", + "operationId": "products.update", "tags": [ - "Machines" + "Products" ], - "operationId": "machines.listDriftReports", - "summary": "List machine drift reports", - "description": "Lists historical drift reports for a machine.", + "summary": "Update product", + "description": "Updates Product metadata, marketplace listing state, and the package version pin for future offers and installs.", "security": [ { "BearerAuth": [] @@ -22369,71 +38319,71 @@ "schema": { "type": "string", "minLength": 1, - "maxLength": 54 + "maxLength": 55, + "description": "Product ID", + "example": "prod_j572abc..." }, "required": true, + "description": "Product ID", "name": "id", "in": "path" }, { "schema": { "type": "string", - "description": "Pagination cursor from a previous response's `next_cursor`." - }, - "required": false, - "description": "Pagination cursor from a previous response's `next_cursor`.", - "name": "cursor", - "in": "query" - }, - { - "schema": { - "type": "integer", - "minimum": 1, - "maximum": 100, - "default": 50, - "description": "Items per page (1-100, default 50)", - "example": 50 + "minLength": 1, + "maxLength": 53, + "description": "Optional workspace/scope context for the request. Carries a single workspace wire id (`ws_…`) today. Only needed for broad tokens — a workspace-owned token implies its workspace.", + "example": "ws_j572abc123def456" }, "required": false, - "description": "Items per page (1-100, default 50)", - "name": "limit", - "in": "query" + "description": "Optional workspace/scope context for the request. Carries a single workspace wire id (`ws_…`) today. Only needed for broad tokens — a workspace-owned token implies its workspace.", + "name": "akua-context", + "in": "header" }, { "schema": { "type": "string", - "enum": [ - "in_sync", - "drifted" - ], - "description": "Machine drift comparison state." + "minLength": 1, + "maxLength": 64, + "description": "Optional caller-supplied idempotency key. Any non-empty key up to 64 characters is accepted. Endpoint-specific documentation describes how the key is used.", + "example": "create-prod-2026-05-07" }, "required": false, - "description": "Machine drift comparison state.", - "name": "state", - "in": "query" + "description": "Optional caller-supplied idempotency key. Any non-empty key up to 64 characters is accepted. Endpoint-specific documentation describes how the key is used.", + "name": "idempotency-key", + "in": "header" }, { "schema": { "type": "string", "minLength": 1, - "maxLength": 53, - "description": "Optional workspace/scope context for the request. Carries a single workspace wire id (`ws_…`) today. Only needed for broad tokens — a workspace-owned token implies its workspace.", - "example": "ws_j572abc123def456" + "maxLength": 256, + "description": "The `etag` of the resource version the client last read. Required on writes when the resource exposes an `etag` field. Mismatch returns 409 `ABORTED` with the current etag in the error metadata.", + "example": "42" }, - "required": false, - "description": "Optional workspace/scope context for the request. Carries a single workspace wire id (`ws_…`) today. Only needed for broad tokens — a workspace-owned token implies its workspace.", - "name": "akua-context", + "required": true, + "description": "The `etag` of the resource version the client last read. Required on writes when the resource exposes an `etag` field. Mismatch returns 409 `ABORTED` with the current etag in the error metadata.", + "name": "if-match", "in": "header" } ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/UpdateProductBody" + } + } + } + }, "responses": { "200": { - "description": "Drift report list", + "description": "Product updated", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/DriftReportList" + "$ref": "#/components/schemas/Product" } } } @@ -22467,19 +38417,39 @@ } } } + }, + "409": { + "description": "Conflict", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } + } + } + }, + "422": { + "description": "Unprocessable entity", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } + } + } } } } }, - "/v1/machines/{id}/drift_reports/{report_id}": { - "get": { + "/v1/products/{id}:archive": { + "post": { "x-platform-visibility": "PUBLIC", + "operationId": "products.archive", "tags": [ - "Machines" + "Products" ], - "operationId": "machines.getDriftReport", - "summary": "Get machine drift report", - "description": "Returns a single drift report by ID.", + "summary": "Archive product", + "description": "Archives the product and removes it from active marketplace listings. The row persists with state `archived` for audit/history/revenue-attribution. Active installs and past orders are unaffected; backing packages remain independently managed and unchanged. Dashboard callers can still render historical product context.", "security": [ { "BearerAuth": [] @@ -22490,22 +38460,15 @@ "schema": { "type": "string", "minLength": 1, - "maxLength": 54 + "maxLength": 55, + "description": "Product ID", + "example": "prod_j572abc..." }, "required": true, + "description": "Product ID", "name": "id", "in": "path" }, - { - "schema": { - "type": "string", - "description": "Drift report ID" - }, - "required": true, - "description": "Drift report ID", - "name": "report_id", - "in": "path" - }, { "schema": { "type": "string", @@ -22518,15 +38481,50 @@ "description": "Optional workspace/scope context for the request. Carries a single workspace wire id (`ws_…`) today. Only needed for broad tokens — a workspace-owned token implies its workspace.", "name": "akua-context", "in": "header" + }, + { + "schema": { + "type": "string", + "minLength": 1, + "maxLength": 64, + "description": "Optional caller-supplied idempotency key. Any non-empty key up to 64 characters is accepted. Endpoint-specific documentation describes how the key is used.", + "example": "create-prod-2026-05-07" + }, + "required": false, + "description": "Optional caller-supplied idempotency key. Any non-empty key up to 64 characters is accepted. Endpoint-specific documentation describes how the key is used.", + "name": "idempotency-key", + "in": "header" + }, + { + "schema": { + "type": "string", + "minLength": 1, + "maxLength": 256, + "description": "The `etag` of the resource version the client last read. Required on writes when the resource exposes an `etag` field. Mismatch returns 409 `ABORTED` with the current etag in the error metadata.", + "example": "42" + }, + "required": true, + "description": "The `etag` of the resource version the client last read. Required on writes when the resource exposes an `etag` field. Mismatch returns 409 `ABORTED` with the current etag in the error metadata.", + "name": "if-match", + "in": "header" } ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ArchiveProductBody" + } + } + } + }, "responses": { "200": { - "description": "Machine drift report", + "description": "Product archived", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/DriftReport" + "$ref": "#/components/schemas/Product" } } } @@ -22560,19 +38558,39 @@ } } } + }, + "409": { + "description": "Conflict", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } + } + } + }, + "422": { + "description": "Unprocessable entity", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } + } + } } } } }, - "/v1/machines/{id}/suspension_events": { - "get": { + "/v1/products/{id}:unarchive": { + "post": { "x-platform-visibility": "PUBLIC", + "operationId": "products.unarchive", "tags": [ - "Machines" + "Products" ], - "operationId": "machines.listSuspensionEvents", - "summary": "List machine suspension events", - "description": "Lists historical suspension events for the machine. Events record suspend, resume, expiry, and snapshot-cost details for audit and billing reports.", + "summary": "Unarchive product", + "description": "Restores a previously-archived product to `active`. The row remains in place and history is preserved. Active installs continue; dependent offers stay untouched unless separately unarchived.", "security": [ { "BearerAuth": [] @@ -22583,69 +38601,73 @@ "schema": { "type": "string", "minLength": 1, - "maxLength": 54 + "maxLength": 55, + "description": "Product ID", + "example": "prod_j572abc..." }, "required": true, + "description": "Product ID", "name": "id", "in": "path" }, { "schema": { "type": "string", - "description": "Pagination cursor from a previous response's `next_cursor`." - }, - "required": false, - "description": "Pagination cursor from a previous response's `next_cursor`.", - "name": "cursor", - "in": "query" - }, - { - "schema": { - "type": "integer", - "minimum": 1, - "maximum": 100, - "default": 50, - "description": "Items per page (1-100, default 50)", - "example": 50 + "minLength": 1, + "maxLength": 53, + "description": "Optional workspace/scope context for the request. Carries a single workspace wire id (`ws_…`) today. Only needed for broad tokens — a workspace-owned token implies its workspace.", + "example": "ws_j572abc123def456" }, "required": false, - "description": "Items per page (1-100, default 50)", - "name": "limit", - "in": "query" + "description": "Optional workspace/scope context for the request. Carries a single workspace wire id (`ws_…`) today. Only needed for broad tokens — a workspace-owned token implies its workspace.", + "name": "akua-context", + "in": "header" }, { "schema": { "type": "string", - "enum": [ - "manual", - "downgrade" - ] + "minLength": 1, + "maxLength": 64, + "description": "Optional caller-supplied idempotency key. Any non-empty key up to 64 characters is accepted. Endpoint-specific documentation describes how the key is used.", + "example": "create-prod-2026-05-07" }, "required": false, - "name": "reason", - "in": "query" + "description": "Optional caller-supplied idempotency key. Any non-empty key up to 64 characters is accepted. Endpoint-specific documentation describes how the key is used.", + "name": "idempotency-key", + "in": "header" }, { "schema": { "type": "string", "minLength": 1, - "maxLength": 53, - "description": "Optional workspace/scope context for the request. Carries a single workspace wire id (`ws_…`) today. Only needed for broad tokens — a workspace-owned token implies its workspace.", - "example": "ws_j572abc123def456" + "maxLength": 256, + "description": "The `etag` of the resource version the client last read. Required on writes when the resource exposes an `etag` field. Mismatch returns 409 `ABORTED` with the current etag in the error metadata.", + "example": "42" }, - "required": false, - "description": "Optional workspace/scope context for the request. Carries a single workspace wire id (`ws_…`) today. Only needed for broad tokens — a workspace-owned token implies its workspace.", - "name": "akua-context", + "required": true, + "description": "The `etag` of the resource version the client last read. Required on writes when the resource exposes an `etag` field. Mismatch returns 409 `ABORTED` with the current etag in the error metadata.", + "name": "if-match", "in": "header" } - ], + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": {}, + "additionalProperties": false + } + } + } + }, "responses": { "200": { - "description": "Suspension event list", + "description": "Product unarchived", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/SuspensionEventList" + "$ref": "#/components/schemas/Product" } } } @@ -22679,19 +38701,38 @@ } } } + }, + "409": { + "description": "Conflict", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } + } + } + }, + "422": { + "description": "Unprocessable entity", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } + } + } } } } }, - "/v1/machines/{id}/suspension_events/{event_id}": { + "/v1/product_rollouts": { "get": { - "x-platform-visibility": "PUBLIC", + "x-platform-visibility": "INTERNAL", + "operationId": "productRollouts.list", "tags": [ - "Machines" + "Product rollouts" ], - "operationId": "machines.getSuspensionEvent", - "summary": "Get machine suspension event", - "description": "Returns a single suspension event for a machine, including snapshot reference, cost, lifecycle state, and timing details.", + "summary": "List product rollouts", "security": [ { "BearerAuth": [] @@ -22701,22 +38742,36 @@ { "schema": { "type": "string", - "minLength": 1, - "maxLength": 54 + "description": "Pagination cursor from a previous response's `next_cursor`." }, - "required": true, - "name": "id", - "in": "path" + "required": false, + "description": "Pagination cursor from a previous response's `next_cursor`.", + "name": "cursor", + "in": "query" + }, + { + "schema": { + "type": "integer", + "minimum": 1, + "maximum": 100, + "default": 50, + "description": "Items per page (1-100, default 50)", + "example": 50 + }, + "required": false, + "description": "Items per page (1-100, default 50)", + "name": "limit", + "in": "query" }, { "schema": { "type": "string", "minLength": 1, - "maxLength": 54 + "maxLength": 55 }, - "required": true, - "name": "event_id", - "in": "path" + "required": false, + "name": "product_id", + "in": "query" }, { "schema": { @@ -22734,11 +38789,11 @@ ], "responses": { "200": { - "description": "Suspension event", + "description": "Product rollouts", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/SuspensionEvent" + "$ref": "#/components/schemas/ProductRolloutList" } } } @@ -22762,29 +38817,17 @@ } } } - }, - "404": { - "description": "Not found", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/ApiErrorResponse" - } - } - } } } - } - }, - "/v1/compute_configs": { + }, "post": { - "x-platform-visibility": "PUBLIC", + "x-platform-visibility": "INTERNAL", + "operationId": "productRollouts.create", "tags": [ - "ComputeConfigs" + "Product rollouts" ], - "operationId": "computeConfigs.create", - "summary": "Create compute config", - "description": "Creates a compute config row.", + "summary": "Create product rollout", + "description": "Starts a durable rollout of one published PackageVersion across a bounded Product audience.", "security": [ { "BearerAuth": [] @@ -22809,11 +38852,11 @@ "type": "string", "minLength": 1, "maxLength": 64, - "description": "Caller-supplied idempotency key. Repeated requests with the same key return the existing resource instead of creating a duplicate. Safe to retry after a timed-out or interrupted request.", + "description": "Required caller-supplied idempotency key. Any non-empty key up to 64 characters is accepted. Endpoint-specific documentation describes how the key is used.", "example": "create-prod-2026-05-07" }, - "required": false, - "description": "Caller-supplied idempotency key. Repeated requests with the same key return the existing resource instead of creating a duplicate. Safe to retry after a timed-out or interrupted request.", + "required": true, + "description": "Required caller-supplied idempotency key. Any non-empty key up to 64 characters is accepted. Endpoint-specific documentation describes how the key is used.", "name": "idempotency-key", "in": "header" } @@ -22822,61 +38865,28 @@ "content": { "application/json": { "schema": { - "type": "object", - "properties": { - "name": { - "type": "string", - "minLength": 1, - "maxLength": 100 - }, - "provider": { - "type": "string", - "enum": [ - "hcloud" - ] - }, - "provider_config": { - "type": "object", - "properties": { - "region": { - "type": "string", - "minLength": 1 - }, - "image": { - "type": "string", - "minLength": 1 - }, - "machine_type_filter": { - "type": "string" - } - }, - "required": [ - "region", - "image" - ] - }, - "credential_scope": { - "$ref": "#/components/schemas/CredentialScope" - } - }, - "required": [ - "name", - "provider", - "provider_config", - "credential_scope" - ], - "additionalProperties": false + "$ref": "#/components/schemas/CreateProductRolloutBody" } } } }, "responses": { "201": { - "description": "Compute config created", + "description": "Product rollout created", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/ComputeConfig" + "$ref": "#/components/schemas/ProductRollout" + } + } + } + }, + "400": { + "description": "Bad request", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" } } } @@ -22900,22 +38910,38 @@ } } } + }, + "409": { + "description": "Conflict", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } + } + } + }, + "422": { + "description": "Unprocessable entity", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } + } + } } } - }, + } + }, + "/v1/product_rollouts/{id}": { "get": { - "x-platform-visibility": "PUBLIC", - "x-platform-live": { - "visibility": "PUBLIC", - "transport": "convex", - "convexQuery": "compute.ui.listComputeConfigsForApi" - }, + "x-platform-visibility": "INTERNAL", + "operationId": "productRollouts.get", "tags": [ - "ComputeConfigs" + "Product rollouts" ], - "operationId": "computeConfigs.list", - "summary": "List compute configs", - "description": "Lists compute configs in the workspace.", + "summary": "Get product rollout", "security": [ { "BearerAuth": [] @@ -22925,39 +38951,12 @@ { "schema": { "type": "string", - "description": "Pagination cursor from a previous response's `next_cursor`." - }, - "required": false, - "description": "Pagination cursor from a previous response's `next_cursor`.", - "name": "cursor", - "in": "query" - }, - { - "schema": { - "type": "integer", - "minimum": 1, - "maximum": 100, - "default": 50, - "description": "Items per page (1-100, default 50)", - "example": 50 - }, - "required": false, - "description": "Items per page (1-100, default 50)", - "name": "limit", - "in": "query" - }, - { - "schema": { - "type": "string", - "enum": [ - "basic", - "full" - ], - "default": "basic" + "minLength": 1, + "maxLength": 55 }, - "required": false, - "name": "view", - "in": "query" + "required": true, + "name": "id", + "in": "path" }, { "schema": { @@ -22975,11 +38974,11 @@ ], "responses": { "200": { - "description": "Compute config list", + "description": "Product rollout", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/ComputeConfigList" + "$ref": "#/components/schemas/ProductRollout" } } } @@ -22993,34 +38992,85 @@ } } } + }, + "403": { + "description": "Forbidden", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } + } + } + }, + "404": { + "description": "Not found", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } + } + } } } } }, - "/v1/compute_configs/{id}": { + "/v1/product_rollout_targets": { "get": { - "x-platform-visibility": "PUBLIC", + "x-platform-visibility": "INTERNAL", + "operationId": "productRolloutTargets.list", "tags": [ - "ComputeConfigs" + "Product rollouts" ], - "operationId": "computeConfigs.get", - "summary": "Get compute config", - "description": "Returns a compute config by ID.", + "summary": "List product rollout customer progress", "security": [ { "BearerAuth": [] } ], "parameters": [ + { + "schema": { + "type": "string", + "description": "Pagination cursor from a previous response's `next_cursor`." + }, + "required": false, + "description": "Pagination cursor from a previous response's `next_cursor`.", + "name": "cursor", + "in": "query" + }, + { + "schema": { + "type": "integer", + "minimum": 1, + "maximum": 100, + "default": 50, + "description": "Items per page (1-100, default 50)", + "example": 50 + }, + "required": false, + "description": "Items per page (1-100, default 50)", + "name": "limit", + "in": "query" + }, { "schema": { "type": "string", "minLength": 1, - "maxLength": 54 + "maxLength": 55 }, "required": true, - "name": "id", - "in": "path" + "name": "rollout_id", + "in": "query" + }, + { + "schema": { + "$ref": "#/components/schemas/ProductRolloutTargetState" + }, + "required": false, + "name": "state", + "in": "query" }, { "schema": { @@ -23038,11 +39088,11 @@ ], "responses": { "200": { - "description": "Compute config details", + "description": "Customer rollout progress", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/ComputeConfig" + "$ref": "#/components/schemas/ProductRolloutTargetList" } } } @@ -23078,15 +39128,16 @@ } } } - }, - "patch": { - "x-platform-visibility": "PUBLIC", + } + }, + "/v1/product_rollouts/{id}:pause": { + "post": { + "x-platform-visibility": "INTERNAL", + "operationId": "productRollouts.pause", "tags": [ - "ComputeConfigs" + "Product rollouts" ], - "operationId": "computeConfigs.update", - "summary": "Update compute config", - "description": "Updates mutable fields of a compute config.", + "summary": "Pause product rollout", "security": [ { "BearerAuth": [] @@ -23097,7 +39148,7 @@ "schema": { "type": "string", "minLength": 1, - "maxLength": 54 + "maxLength": 55 }, "required": true, "name": "id", @@ -23120,72 +39171,36 @@ "schema": { "type": "string", "minLength": 1, - "maxLength": 64, - "description": "Caller-supplied idempotency key. Repeated requests with the same key return the existing resource instead of creating a duplicate. Safe to retry after a timed-out or interrupted request.", - "example": "create-prod-2026-05-07" + "maxLength": 256, + "description": "The `etag` of the resource version the client last read. Required on writes when the resource exposes an `etag` field. Mismatch returns 409 `ABORTED` with the current etag in the error metadata.", + "example": "42" }, - "required": false, - "description": "Caller-supplied idempotency key. Repeated requests with the same key return the existing resource instead of creating a duplicate. Safe to retry after a timed-out or interrupted request.", - "name": "idempotency-key", + "required": true, + "description": "The `etag` of the resource version the client last read. Required on writes when the resource exposes an `etag` field. Mismatch returns 409 `ABORTED` with the current etag in the error metadata.", + "name": "if-match", "in": "header" }, { "schema": { "type": "string", "minLength": 1, - "maxLength": 256, - "description": "The `etag` of the resource version the client last read. Required on writes when the resource exposes an `etag` field. Mismatch returns 409 `ABORTED` with the current etag in the error metadata.", - "example": "42" + "maxLength": 64, + "description": "Required caller-supplied idempotency key. Any non-empty key up to 64 characters is accepted. Endpoint-specific documentation describes how the key is used.", + "example": "create-prod-2026-05-07" }, "required": true, - "description": "The `etag` of the resource version the client last read. Required on writes when the resource exposes an `etag` field. Mismatch returns 409 `ABORTED` with the current etag in the error metadata.", - "name": "if-match", + "description": "Required caller-supplied idempotency key. Any non-empty key up to 64 characters is accepted. Endpoint-specific documentation describes how the key is used.", + "name": "idempotency-key", "in": "header" } ], - "requestBody": { - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "name": { - "type": "string", - "minLength": 1, - "maxLength": 100 - }, - "provider_config": { - "type": "object", - "properties": { - "region": { - "type": "string", - "minLength": 1 - }, - "image": { - "type": "string", - "minLength": 1 - }, - "machine_type_filter": { - "type": "string" - } - } - }, - "credential_scope": { - "$ref": "#/components/schemas/CredentialScope" - } - }, - "additionalProperties": false - } - } - } - }, "responses": { "200": { - "description": "Compute config updated", + "description": "Paused product rollout", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/ComputeConfig" + "$ref": "#/components/schemas/ProductRollout" } } } @@ -23229,17 +39244,28 @@ } } } + }, + "422": { + "description": "Unprocessable entity", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } + } + } } } - }, - "delete": { - "x-platform-visibility": "PUBLIC", + } + }, + "/v1/product_rollouts/{id}:resume": { + "post": { + "x-platform-visibility": "INTERNAL", + "operationId": "productRollouts.resume", "tags": [ - "ComputeConfigs" + "Product rollouts" ], - "operationId": "computeConfigs.delete", - "summary": "Delete compute config", - "description": "Deletes a compute config.", + "summary": "Resume product rollout", "security": [ { "BearerAuth": [] @@ -23250,7 +39276,7 @@ "schema": { "type": "string", "minLength": 1, - "maxLength": 54 + "maxLength": 55 }, "required": true, "name": "id", @@ -23273,36 +39299,36 @@ "schema": { "type": "string", "minLength": 1, - "maxLength": 64, - "description": "Caller-supplied idempotency key. Repeated requests with the same key return the existing resource instead of creating a duplicate. Safe to retry after a timed-out or interrupted request.", - "example": "create-prod-2026-05-07" + "maxLength": 256, + "description": "The `etag` of the resource version the client last read. Required on writes when the resource exposes an `etag` field. Mismatch returns 409 `ABORTED` with the current etag in the error metadata.", + "example": "42" }, - "required": false, - "description": "Caller-supplied idempotency key. Repeated requests with the same key return the existing resource instead of creating a duplicate. Safe to retry after a timed-out or interrupted request.", - "name": "idempotency-key", + "required": true, + "description": "The `etag` of the resource version the client last read. Required on writes when the resource exposes an `etag` field. Mismatch returns 409 `ABORTED` with the current etag in the error metadata.", + "name": "if-match", "in": "header" }, { "schema": { "type": "string", "minLength": 1, - "maxLength": 256, - "description": "The `etag` of the resource version the client last read. Required on writes when the resource exposes an `etag` field. Mismatch returns 409 `ABORTED` with the current etag in the error metadata.", - "example": "42" + "maxLength": 64, + "description": "Required caller-supplied idempotency key. Any non-empty key up to 64 characters is accepted. Endpoint-specific documentation describes how the key is used.", + "example": "create-prod-2026-05-07" }, "required": true, - "description": "The `etag` of the resource version the client last read. Required on writes when the resource exposes an `etag` field. Mismatch returns 409 `ABORTED` with the current etag in the error metadata.", - "name": "if-match", + "description": "Required caller-supplied idempotency key. Any non-empty key up to 64 characters is accepted. Endpoint-specific documentation describes how the key is used.", + "name": "idempotency-key", "in": "header" } ], "responses": { "200": { - "description": "Compute config deleted", + "description": "Resumed product rollout", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/ComputeConfig" + "$ref": "#/components/schemas/ProductRollout" } } } @@ -23346,86 +39372,9 @@ } } } - } - } - } - }, - "/v1/products": { - "get": { - "x-platform-visibility": "PUBLIC", - "operationId": "products.list", - "tags": [ - "Products" - ], - "summary": "List products in workspace", - "description": "Returns all products belonging to the workspace specified in the workspace context.", - "security": [ - { - "BearerAuth": [] - } - ], - "parameters": [ - { - "schema": { - "type": "string", - "description": "Pagination cursor from a previous response's `next_cursor`." - }, - "required": false, - "description": "Pagination cursor from a previous response's `next_cursor`.", - "name": "cursor", - "in": "query" - }, - { - "schema": { - "type": "integer", - "minimum": 1, - "maximum": 100, - "default": 50, - "description": "Items per page (1-100, default 50)", - "example": 50 - }, - "required": false, - "description": "Items per page (1-100, default 50)", - "name": "limit", - "in": "query" - }, - { - "schema": { - "type": "string", - "minLength": 1, - "maxLength": 53, - "description": "Optional workspace/scope context for the request. Carries a single workspace wire id (`ws_…`) today. Only needed for broad tokens — a workspace-owned token implies its workspace.", - "example": "ws_j572abc123def456" - }, - "required": false, - "description": "Optional workspace/scope context for the request. Carries a single workspace wire id (`ws_…`) today. Only needed for broad tokens — a workspace-owned token implies its workspace.", - "name": "akua-context", - "in": "header" - } - ], - "responses": { - "200": { - "description": "List of products", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/ProductList" - } - } - } - }, - "401": { - "description": "Unauthorized", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/ApiErrorResponse" - } - } - } }, - "403": { - "description": "Forbidden", + "422": { + "description": "Unprocessable entity", "content": { "application/json": { "schema": { @@ -23435,15 +39384,16 @@ } } } - }, + } + }, + "/v1/offer_channels": { "post": { - "x-platform-visibility": "PUBLIC", - "operationId": "products.create", + "x-platform-visibility": "TRUSTED_PARTNER", + "operationId": "offerChannels.create", "tags": [ - "Products" + "Offer Channels" ], - "summary": "Create product", - "description": "Creates a Product backed by an existing Package and package version pin. Package source import belongs to the Packages API.", + "summary": "Create offer channel", "security": [ { "BearerAuth": [] @@ -23468,11 +39418,11 @@ "type": "string", "minLength": 1, "maxLength": 64, - "description": "Caller-supplied idempotency key. Repeated requests with the same key return the existing resource instead of creating a duplicate. Safe to retry after a timed-out or interrupted request.", + "description": "Required caller-supplied idempotency key. Any non-empty key up to 64 characters is accepted. Endpoint-specific documentation describes how the key is used.", "example": "create-prod-2026-05-07" }, - "required": false, - "description": "Caller-supplied idempotency key. Repeated requests with the same key return the existing resource instead of creating a duplicate. Safe to retry after a timed-out or interrupted request.", + "required": true, + "description": "Required caller-supplied idempotency key. Any non-empty key up to 64 characters is accepted. Endpoint-specific documentation describes how the key is used.", "name": "idempotency-key", "in": "header" } @@ -23481,28 +39431,18 @@ "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/CreateProductBody" + "$ref": "#/components/schemas/CreateOfferChannelBody" } } } }, "responses": { "201": { - "description": "Product created", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/Product" - } - } - } - }, - "400": { - "description": "Bad request", + "description": "Offer channel created", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/ApiErrorResponse" + "$ref": "#/components/schemas/OfferChannel" } } } @@ -23526,34 +39466,21 @@ } } } - }, - "422": { - "description": "Unprocessable entity", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/ApiErrorResponse" - } - } - } } } - } - }, - "/v1/products:dashboardList": { + }, "get": { - "x-platform-visibility": "INTERNAL", + "x-platform-visibility": "TRUSTED_PARTNER", "x-platform-live": { - "visibility": "INTERNAL", + "visibility": "TRUSTED_PARTNER", "transport": "convex", - "convexQuery": "product.ui.listDashboardProductsForApi" + "convexQuery": "offers.ui.listOfferChannelsForApi" }, - "operationId": "products.listDashboard", + "operationId": "offerChannels.list", "tags": [ - "Products" + "Offer Channels" ], - "summary": "List dashboard products in workspace", - "description": "Returns product rows shaped for the dashboard product catalog, including target counts.", + "summary": "List offer channels", "security": [ { "BearerAuth": [] @@ -23563,25 +39490,11 @@ { "schema": { "type": "string", - "description": "Pagination cursor from a previous response's `next_cursor`." - }, - "required": false, - "description": "Pagination cursor from a previous response's `next_cursor`.", - "name": "cursor", - "in": "query" - }, - { - "schema": { - "type": "integer", - "minimum": 1, - "maximum": 100, - "default": 50, - "description": "Items per page (1-100, default 50)", - "example": 50 + "minLength": 1, + "maxLength": 55 }, "required": false, - "description": "Items per page (1-100, default 50)", - "name": "limit", + "name": "product_id", "in": "query" }, { @@ -23600,11 +39513,11 @@ ], "responses": { "200": { - "description": "Dashboard product list", + "description": "Offer channels", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/DashboardProductList" + "$ref": "#/components/schemas/OfferChannelList" } } } @@ -23632,32 +39545,38 @@ } } }, - "/v1/products:marketplaceList": { + "/v1/offer_channels/{id}": { "get": { - "x-platform-visibility": "INTERNAL", - "x-platform-live": { - "visibility": "INTERNAL", - "transport": "convex", - "convexQuery": "product.ui.getMarketplaceProductsForUi" - }, - "operationId": "products.listMarketplace", + "x-platform-visibility": "TRUSTED_PARTNER", + "operationId": "offerChannels.get", "tags": [ - "Products" + "Offer Channels" ], - "summary": "List marketplace products", - "description": "Returns product rows shaped for the marketplace catalog.", + "summary": "Get offer channel", "security": [ { "BearerAuth": [] } ], + "parameters": [ + { + "schema": { + "type": "string", + "minLength": 1, + "maxLength": 54 + }, + "required": true, + "name": "id", + "in": "path" + } + ], "responses": { "200": { - "description": "Marketplace product list", + "description": "Offer channel", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/MarketplaceProductList" + "$ref": "#/components/schemas/OfferChannel" } } } @@ -23671,24 +39590,38 @@ } } } + }, + "403": { + "description": "Forbidden", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } + } + } + }, + "404": { + "description": "Not found", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } + } + } } } } }, - "/v1/products/{id}": { - "get": { - "x-platform-visibility": "PUBLIC", - "x-platform-live": { - "visibility": "INTERNAL", - "transport": "convex", - "convexQuery": "product.ui.getProductForApi" - }, - "operationId": "products.get", + "/v1/offer_channels/{id}:archive": { + "post": { + "x-platform-visibility": "TRUSTED_PARTNER", + "operationId": "offerChannels.archive", "tags": [ - "Products" + "Offer Channels" ], - "summary": "Get product details", - "description": "Returns product metadata including the backing Package and marketplace settings.", + "summary": "Archive offer channel", "security": [ { "BearerAuth": [] @@ -23699,12 +39632,9 @@ "schema": { "type": "string", "minLength": 1, - "maxLength": 55, - "description": "Product ID", - "example": "prod_j572abc..." + "maxLength": 54 }, "required": true, - "description": "Product ID", "name": "id", "in": "path" }, @@ -23720,15 +39650,28 @@ "description": "Optional workspace/scope context for the request. Carries a single workspace wire id (`ws_…`) today. Only needed for broad tokens — a workspace-owned token implies its workspace.", "name": "akua-context", "in": "header" + }, + { + "schema": { + "type": "string", + "minLength": 1, + "maxLength": 64, + "description": "Required caller-supplied idempotency key. Any non-empty key up to 64 characters is accepted. Endpoint-specific documentation describes how the key is used.", + "example": "create-prod-2026-05-07" + }, + "required": true, + "description": "Required caller-supplied idempotency key. Any non-empty key up to 64 characters is accepted. Endpoint-specific documentation describes how the key is used.", + "name": "idempotency-key", + "in": "header" } ], "responses": { "200": { - "description": "Product details", + "description": "Offer channel archived", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/Product" + "$ref": "#/components/schemas/OfferChannel" } } } @@ -23752,46 +39695,24 @@ } } } - }, - "404": { - "description": "Not found", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/ApiErrorResponse" - } - } - } } } - }, - "patch": { - "x-platform-visibility": "PUBLIC", - "operationId": "products.update", + } + }, + "/v1/channel_policies": { + "post": { + "x-platform-visibility": "TRUSTED_PARTNER", + "operationId": "channelPolicies.create", "tags": [ - "Products" + "Channel Policies" ], - "summary": "Update product", - "description": "Updates Product metadata, marketplace listing state, and the package version pin for future offers and installs.", + "summary": "Create channel policy", "security": [ { "BearerAuth": [] } ], "parameters": [ - { - "schema": { - "type": "string", - "minLength": 1, - "maxLength": 55, - "description": "Product ID", - "example": "prod_j572abc..." - }, - "required": true, - "description": "Product ID", - "name": "id", - "in": "path" - }, { "schema": { "type": "string", @@ -23810,25 +39731,12 @@ "type": "string", "minLength": 1, "maxLength": 64, - "description": "Caller-supplied idempotency key. Repeated requests with the same key return the existing resource instead of creating a duplicate. Safe to retry after a timed-out or interrupted request.", + "description": "Required caller-supplied idempotency key. Any non-empty key up to 64 characters is accepted. Endpoint-specific documentation describes how the key is used.", "example": "create-prod-2026-05-07" }, - "required": false, - "description": "Caller-supplied idempotency key. Repeated requests with the same key return the existing resource instead of creating a duplicate. Safe to retry after a timed-out or interrupted request.", - "name": "idempotency-key", - "in": "header" - }, - { - "schema": { - "type": "string", - "minLength": 1, - "maxLength": 256, - "description": "The `etag` of the resource version the client last read. Required on writes when the resource exposes an `etag` field. Mismatch returns 409 `ABORTED` with the current etag in the error metadata.", - "example": "42" - }, "required": true, - "description": "The `etag` of the resource version the client last read. Required on writes when the resource exposes an `etag` field. Mismatch returns 409 `ABORTED` with the current etag in the error metadata.", - "name": "if-match", + "description": "Required caller-supplied idempotency key. Any non-empty key up to 64 characters is accepted. Endpoint-specific documentation describes how the key is used.", + "name": "idempotency-key", "in": "header" } ], @@ -23836,18 +39744,18 @@ "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/UpdateProductBody" + "$ref": "#/components/schemas/CreateChannelPolicyBody" } } } }, "responses": { - "200": { - "description": "Product updated", + "201": { + "description": "Channel policy created", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/Product" + "$ref": "#/components/schemas/ChannelPolicy" } } } @@ -23871,29 +39779,51 @@ } } } - }, - "404": { - "description": "Not found", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/ApiErrorResponse" - } - } - } - }, - "409": { - "description": "Conflict", + } + } + }, + "get": { + "x-platform-visibility": "TRUSTED_PARTNER", + "x-platform-live": { + "visibility": "TRUSTED_PARTNER", + "transport": "convex", + "convexQuery": "offers.ui.listChannelPoliciesForApi" + }, + "operationId": "channelPolicies.list", + "tags": [ + "Channel Policies" + ], + "summary": "List channel policies", + "security": [ + { + "BearerAuth": [] + } + ], + "parameters": [ + { + "schema": { + "type": "string", + "minLength": 1, + "maxLength": 54 + }, + "required": true, + "name": "offer_channel", + "in": "query" + } + ], + "responses": { + "200": { + "description": "Channel policies", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/ApiErrorResponse" + "$ref": "#/components/schemas/ChannelPolicyList" } } } }, - "422": { - "description": "Unprocessable entity", + "401": { + "description": "Unauthorized", "content": { "application/json": { "schema": { @@ -23905,20 +39835,14 @@ } } }, - "/v1/products/{id}:marketplace": { + "/v1/channel_policies/{id}": { "get": { - "x-platform-visibility": "INTERNAL", - "x-platform-live": { - "visibility": "INTERNAL", - "transport": "convex", - "convexQuery": "product.ui.getPublicProductForUi" - }, - "operationId": "products.getMarketplace", + "x-platform-visibility": "TRUSTED_PARTNER", + "operationId": "channelPolicies.get", "tags": [ - "Products" + "Channel Policies" ], - "summary": "Get marketplace product", - "description": "Returns product detail shaped for the marketplace product page.", + "summary": "Get channel policy", "security": [ { "BearerAuth": [] @@ -23929,23 +39853,20 @@ "schema": { "type": "string", "minLength": 1, - "maxLength": 55, - "description": "Product ID", - "example": "prod_j572abc..." + "maxLength": 56 }, "required": true, - "description": "Product ID", "name": "id", "in": "path" } ], "responses": { "200": { - "description": "Marketplace product detail", + "description": "Channel policy", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/MarketplaceProductDetail" + "$ref": "#/components/schemas/ChannelPolicy" } } } @@ -23973,15 +39894,14 @@ } } }, - "/v1/products/{id}:archive": { + "/v1/channel_policies/{id}:approve": { "post": { - "x-platform-visibility": "PUBLIC", - "operationId": "products.archive", + "x-platform-visibility": "TRUSTED_PARTNER", + "operationId": "channelPolicies.approve", "tags": [ - "Products" + "Channel Policies" ], - "summary": "Archive product", - "description": "Archives the product and removes it from active marketplace listings. The row persists with state `archived` for audit/history/revenue-attribution. Active installs and past orders are unaffected; backing packages remain independently managed and unchanged. Dashboard callers can still render historical product context.", + "summary": "Approve channel policy", "security": [ { "BearerAuth": [] @@ -23992,12 +39912,9 @@ "schema": { "type": "string", "minLength": 1, - "maxLength": 55, - "description": "Product ID", - "example": "prod_j572abc..." + "maxLength": 56 }, "required": true, - "description": "Product ID", "name": "id", "in": "path" }, @@ -24019,44 +39936,22 @@ "type": "string", "minLength": 1, "maxLength": 64, - "description": "Caller-supplied idempotency key. Repeated requests with the same key return the existing resource instead of creating a duplicate. Safe to retry after a timed-out or interrupted request.", + "description": "Required caller-supplied idempotency key. Any non-empty key up to 64 characters is accepted. Endpoint-specific documentation describes how the key is used.", "example": "create-prod-2026-05-07" }, - "required": false, - "description": "Caller-supplied idempotency key. Repeated requests with the same key return the existing resource instead of creating a duplicate. Safe to retry after a timed-out or interrupted request.", - "name": "idempotency-key", - "in": "header" - }, - { - "schema": { - "type": "string", - "minLength": 1, - "maxLength": 256, - "description": "The `etag` of the resource version the client last read. Required on writes when the resource exposes an `etag` field. Mismatch returns 409 `ABORTED` with the current etag in the error metadata.", - "example": "42" - }, "required": true, - "description": "The `etag` of the resource version the client last read. Required on writes when the resource exposes an `etag` field. Mismatch returns 409 `ABORTED` with the current etag in the error metadata.", - "name": "if-match", + "description": "Required caller-supplied idempotency key. Any non-empty key up to 64 characters is accepted. Endpoint-specific documentation describes how the key is used.", + "name": "idempotency-key", "in": "header" } ], - "requestBody": { - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/ArchiveProductBody" - } - } - } - }, "responses": { "200": { - "description": "Product archived", + "description": "Channel policy", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/Product" + "$ref": "#/components/schemas/ChannelPolicy" } } } @@ -24080,19 +39975,74 @@ } } } + } + } + } + }, + "/v1/channel_policies/{id}:activate": { + "post": { + "x-platform-visibility": "TRUSTED_PARTNER", + "operationId": "channelPolicies.activate", + "tags": [ + "Channel Policies" + ], + "summary": "Activate channel policy", + "security": [ + { + "BearerAuth": [] + } + ], + "parameters": [ + { + "schema": { + "type": "string", + "minLength": 1, + "maxLength": 56 + }, + "required": true, + "name": "id", + "in": "path" }, - "404": { - "description": "Not found", + { + "schema": { + "type": "string", + "minLength": 1, + "maxLength": 53, + "description": "Optional workspace/scope context for the request. Carries a single workspace wire id (`ws_…`) today. Only needed for broad tokens — a workspace-owned token implies its workspace.", + "example": "ws_j572abc123def456" + }, + "required": false, + "description": "Optional workspace/scope context for the request. Carries a single workspace wire id (`ws_…`) today. Only needed for broad tokens — a workspace-owned token implies its workspace.", + "name": "akua-context", + "in": "header" + }, + { + "schema": { + "type": "string", + "minLength": 1, + "maxLength": 64, + "description": "Required caller-supplied idempotency key. Any non-empty key up to 64 characters is accepted. Endpoint-specific documentation describes how the key is used.", + "example": "create-prod-2026-05-07" + }, + "required": true, + "description": "Required caller-supplied idempotency key. Any non-empty key up to 64 characters is accepted. Endpoint-specific documentation describes how the key is used.", + "name": "idempotency-key", + "in": "header" + } + ], + "responses": { + "200": { + "description": "Channel policy", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/ApiErrorResponse" + "$ref": "#/components/schemas/ChannelPolicy" } } } }, - "409": { - "description": "Conflict", + "401": { + "description": "Unauthorized", "content": { "application/json": { "schema": { @@ -24101,8 +40051,8 @@ } } }, - "422": { - "description": "Unprocessable entity", + "403": { + "description": "Forbidden", "content": { "application/json": { "schema": { @@ -24114,15 +40064,14 @@ } } }, - "/v1/products/{id}:unarchive": { + "/v1/channel_policies/{id}:archive": { "post": { - "x-platform-visibility": "PUBLIC", - "operationId": "products.unarchive", + "x-platform-visibility": "TRUSTED_PARTNER", + "operationId": "channelPolicies.archive", "tags": [ - "Products" + "Channel Policies" ], - "summary": "Unarchive product", - "description": "Restores a previously-archived product to `active`. The row remains in place and history is preserved. Active installs continue; dependent offers stay untouched unless separately unarchived.", + "summary": "Archive channel policy", "security": [ { "BearerAuth": [] @@ -24133,12 +40082,9 @@ "schema": { "type": "string", "minLength": 1, - "maxLength": 55, - "description": "Product ID", - "example": "prod_j572abc..." + "maxLength": 56 }, "required": true, - "description": "Product ID", "name": "id", "in": "path" }, @@ -24160,46 +40106,22 @@ "type": "string", "minLength": 1, "maxLength": 64, - "description": "Caller-supplied idempotency key. Repeated requests with the same key return the existing resource instead of creating a duplicate. Safe to retry after a timed-out or interrupted request.", + "description": "Required caller-supplied idempotency key. Any non-empty key up to 64 characters is accepted. Endpoint-specific documentation describes how the key is used.", "example": "create-prod-2026-05-07" }, - "required": false, - "description": "Caller-supplied idempotency key. Repeated requests with the same key return the existing resource instead of creating a duplicate. Safe to retry after a timed-out or interrupted request.", - "name": "idempotency-key", - "in": "header" - }, - { - "schema": { - "type": "string", - "minLength": 1, - "maxLength": 256, - "description": "The `etag` of the resource version the client last read. Required on writes when the resource exposes an `etag` field. Mismatch returns 409 `ABORTED` with the current etag in the error metadata.", - "example": "42" - }, "required": true, - "description": "The `etag` of the resource version the client last read. Required on writes when the resource exposes an `etag` field. Mismatch returns 409 `ABORTED` with the current etag in the error metadata.", - "name": "if-match", + "description": "Required caller-supplied idempotency key. Any non-empty key up to 64 characters is accepted. Endpoint-specific documentation describes how the key is used.", + "name": "idempotency-key", "in": "header" } ], - "requestBody": { - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": {}, - "additionalProperties": false - } - } - } - }, "responses": { "200": { - "description": "Product unarchived", + "description": "Channel policy", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/Product" + "$ref": "#/components/schemas/ChannelPolicy" } } } @@ -24223,19 +40145,91 @@ } } } + } + } + } + }, + "/v1/offers": { + "get": { + "x-platform-visibility": "PUBLIC", + "x-platform-live": { + "visibility": "TRUSTED_PARTNER", + "transport": "convex", + "convexQuery": "offers.ui.listMyWorkspaceOffers" + }, + "operationId": "offers.list", + "tags": [ + "Offers" + ], + "summary": "List offers in workspace", + "description": "Returns offers belonging to the workspace specified in the workspace context, newest first.", + "security": [ + { + "BearerAuth": [] + } + ], + "parameters": [ + { + "schema": { + "type": "string", + "description": "Pagination cursor from a previous response's `next_cursor`." + }, + "required": false, + "description": "Pagination cursor from a previous response's `next_cursor`.", + "name": "cursor", + "in": "query" }, - "404": { - "description": "Not found", + { + "schema": { + "type": "integer", + "minimum": 1, + "maximum": 100, + "default": 50, + "description": "Items per page (1-100, default 50)", + "example": 50 + }, + "required": false, + "description": "Items per page (1-100, default 50)", + "name": "limit", + "in": "query" + }, + { + "schema": { + "type": "string", + "minLength": 1, + "maxLength": 55 + }, + "required": false, + "name": "product_id", + "in": "query" + }, + { + "schema": { + "type": "string", + "minLength": 1, + "maxLength": 53, + "description": "Optional workspace/scope context for the request. Carries a single workspace wire id (`ws_…`) today. Only needed for broad tokens — a workspace-owned token implies its workspace.", + "example": "ws_j572abc123def456" + }, + "required": false, + "description": "Optional workspace/scope context for the request. Carries a single workspace wire id (`ws_…`) today. Only needed for broad tokens — a workspace-owned token implies its workspace.", + "name": "akua-context", + "in": "header" + } + ], + "responses": { + "200": { + "description": "List of offers", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/ApiErrorResponse" + "$ref": "#/components/schemas/OfferList" } } } }, - "409": { - "description": "Conflict", + "401": { + "description": "Unauthorized", "content": { "application/json": { "schema": { @@ -24244,8 +40238,8 @@ } } }, - "422": { - "description": "Unprocessable entity", + "403": { + "description": "Forbidden", "content": { "application/json": { "schema": { @@ -24255,16 +40249,15 @@ } } } - } - }, - "/v1/offer_channels": { + }, "post": { - "x-platform-visibility": "TRUSTED_PARTNER", - "operationId": "offerChannels.create", + "x-platform-visibility": "PUBLIC", + "operationId": "offers.create", "tags": [ - "Offer Channels" + "Offers" ], - "summary": "Create offer channel", + "summary": "Create offer", + "description": "Creates an Offer for a product or a specific package version. Idempotency is workspace-scoped: reusing an `Idempotency-Key` with the same create intent returns the original Offer, while reusing it with a changed create intent returns HTTP 409 Conflict. Product-only requests that expire before an Offer is created retain their resolved-version binding and reject key reuse for 24 hours after reservation expiry; after that retention window the abandoned binding may be purged. When `product_id` is supplied without `package_version_id`, the server resolves the product’s current package version pin, validates `field_values` against that resolved version’s input schema, and stores the concrete package version on the Offer. Customers reach the Offer at `/i/` to start an install. When `allowed_emails` is non-empty, only those email addresses can use the Offer; when empty or omitted, any authenticated customer can.", "security": [ { "BearerAuth": [] @@ -24288,29 +40281,43 @@ "schema": { "type": "string", "minLength": 1, - "maxLength": 64 + "maxLength": 64, + "description": "Optional caller-supplied idempotency key. Any non-empty key up to 64 characters is accepted. Endpoint-specific documentation describes how the key is used.", + "example": "create-prod-2026-05-07" }, - "required": true, + "required": false, + "description": "Optional caller-supplied idempotency key. Any non-empty key up to 64 characters is accepted. Endpoint-specific documentation describes how the key is used.", "name": "idempotency-key", "in": "header" } ], "requestBody": { + "required": true, "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/CreateOfferChannelBody" + "$ref": "#/components/schemas/CreateOfferBody" } } } }, "responses": { "201": { - "description": "Offer channel created", + "description": "Offer created", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/OfferChannel" + "$ref": "#/components/schemas/OfferCreated" + } + } + } + }, + "400": { + "description": "Bad request", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" } } } @@ -24334,21 +40341,39 @@ } } } + }, + "409": { + "description": "Conflict", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } + } + } + }, + "422": { + "description": "Unprocessable entity", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } + } + } } } - }, + } + }, + "/v1/offers/{id}": { "get": { - "x-platform-visibility": "TRUSTED_PARTNER", - "x-platform-live": { - "visibility": "TRUSTED_PARTNER", - "transport": "convex", - "convexQuery": "offers.ui.listOfferChannelsForApi" - }, - "operationId": "offerChannels.list", + "x-platform-visibility": "PUBLIC", + "operationId": "offers.get", "tags": [ - "Offer Channels" + "Offers" ], - "summary": "List offer channels", + "summary": "Get offer details", + "description": "Returns the full offer record including pre-fill values and email allowlist. Caller must be a member of the offer’s workspace.", "security": [ { "BearerAuth": [] @@ -24359,33 +40384,23 @@ "schema": { "type": "string", "minLength": 1, - "maxLength": 55 - }, - "required": false, - "name": "product_id", - "in": "query" - }, - { - "schema": { - "type": "string", - "minLength": 1, - "maxLength": 53, - "description": "Optional workspace/scope context for the request. Carries a single workspace wire id (`ws_…`) today. Only needed for broad tokens — a workspace-owned token implies its workspace.", - "example": "ws_j572abc123def456" + "maxLength": 56, + "description": "Offer ID", + "example": "offer_j572abc..." }, - "required": false, - "description": "Optional workspace/scope context for the request. Carries a single workspace wire id (`ws_…`) today. Only needed for broad tokens — a workspace-owned token implies its workspace.", - "name": "akua-context", - "in": "header" + "required": true, + "description": "Offer ID", + "name": "id", + "in": "path" } ], "responses": { "200": { - "description": "Offer channels", + "description": "Offer details", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/OfferChannelList" + "$ref": "#/components/schemas/Offer" } } } @@ -24409,18 +40424,29 @@ } } } + }, + "404": { + "description": "Not found", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } + } + } } } } }, - "/v1/offer_channels/{id}": { - "get": { + "/v1/offers:preview": { + "post": { "x-platform-visibility": "TRUSTED_PARTNER", - "operationId": "offerChannels.get", + "operationId": "offers.preview", "tags": [ - "Offer Channels" + "Offers" ], - "summary": "Get offer channel", + "summary": "Preview offer policy", + "description": "Resolves an offer request against the active Offer Channel policy without creating an offer.", "security": [ { "BearerAuth": [] @@ -24431,20 +40457,42 @@ "schema": { "type": "string", "minLength": 1, - "maxLength": 54 + "maxLength": 53, + "description": "Optional workspace/scope context for the request. Carries a single workspace wire id (`ws_…`) today. Only needed for broad tokens — a workspace-owned token implies its workspace.", + "example": "ws_j572abc123def456" }, - "required": true, - "name": "id", - "in": "path" + "required": false, + "description": "Optional workspace/scope context for the request. Carries a single workspace wire id (`ws_…`) today. Only needed for broad tokens — a workspace-owned token implies its workspace.", + "name": "akua-context", + "in": "header" } ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/PreviewOfferBody" + } + } + } + }, "responses": { "200": { - "description": "Offer channel", + "description": "Offer policy preview", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/OfferChannel" + "$ref": "#/components/schemas/OfferPolicySnapshot" + } + } + } + }, + "400": { + "description": "Bad request", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" } } } @@ -24469,8 +40517,8 @@ } } }, - "404": { - "description": "Not found", + "422": { + "description": "Unprocessable entity", "content": { "application/json": { "schema": { @@ -24482,14 +40530,15 @@ } } }, - "/v1/offer_channels/{id}:archive": { + "/v1/offers/{id}:approve": { "post": { - "x-platform-visibility": "TRUSTED_PARTNER", - "operationId": "offerChannels.archive", + "x-platform-visibility": "INTERNAL", + "operationId": "offers.approve", "tags": [ - "Offer Channels" + "Offers" ], - "summary": "Archive offer channel", + "summary": "Approve offer", + "description": "Approves a pending channel-backed offer and freezes its requested policy snapshot as the approved effective policy snapshot.", "security": [ { "BearerAuth": [] @@ -24500,9 +40549,12 @@ "schema": { "type": "string", "minLength": 1, - "maxLength": 54 + "maxLength": 56, + "description": "Offer ID", + "example": "offer_j572abc..." }, "required": true, + "description": "Offer ID", "name": "id", "in": "path" }, @@ -24518,25 +40570,25 @@ "description": "Optional workspace/scope context for the request. Carries a single workspace wire id (`ws_…`) today. Only needed for broad tokens — a workspace-owned token implies its workspace.", "name": "akua-context", "in": "header" - }, - { - "schema": { - "type": "string", - "minLength": 1, - "maxLength": 64 - }, - "required": true, - "name": "idempotency-key", - "in": "header" } ], "responses": { "200": { - "description": "Offer channel archived", + "description": "Offer approved", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/OfferChannel" + "$ref": "#/components/schemas/Offer" + } + } + } + }, + "400": { + "description": "Bad request", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" } } } @@ -24560,18 +40612,39 @@ } } } + }, + "404": { + "description": "Not found", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } + } + } + }, + "409": { + "description": "Conflict", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } + } + } } } } }, - "/v1/channel_policies": { + "/v1/offers/{id}:reject": { "post": { - "x-platform-visibility": "TRUSTED_PARTNER", - "operationId": "channelPolicies.create", + "x-platform-visibility": "INTERNAL", + "operationId": "offers.reject", "tags": [ - "Channel Policies" + "Offers" ], - "summary": "Create channel policy", + "summary": "Reject offer", + "description": "Rejects a pending channel-backed offer. Rejected offers keep their requested policy snapshot but cannot receive an approved effective snapshot.", "security": [ { "BearerAuth": [] @@ -24582,42 +40655,46 @@ "schema": { "type": "string", "minLength": 1, - "maxLength": 53, - "description": "Optional workspace/scope context for the request. Carries a single workspace wire id (`ws_…`) today. Only needed for broad tokens — a workspace-owned token implies its workspace.", - "example": "ws_j572abc123def456" + "maxLength": 56, + "description": "Offer ID", + "example": "offer_j572abc..." }, - "required": false, - "description": "Optional workspace/scope context for the request. Carries a single workspace wire id (`ws_…`) today. Only needed for broad tokens — a workspace-owned token implies its workspace.", - "name": "akua-context", - "in": "header" + "required": true, + "description": "Offer ID", + "name": "id", + "in": "path" }, { "schema": { "type": "string", "minLength": 1, - "maxLength": 64 + "maxLength": 53, + "description": "Optional workspace/scope context for the request. Carries a single workspace wire id (`ws_…`) today. Only needed for broad tokens — a workspace-owned token implies its workspace.", + "example": "ws_j572abc123def456" }, - "required": true, - "name": "idempotency-key", + "required": false, + "description": "Optional workspace/scope context for the request. Carries a single workspace wire id (`ws_…`) today. Only needed for broad tokens — a workspace-owned token implies its workspace.", + "name": "akua-context", "in": "header" } ], - "requestBody": { - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/CreateChannelPolicyBody" + "responses": { + "200": { + "description": "Offer rejected", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Offer" + } } } - } - }, - "responses": { - "201": { - "description": "Channel policy created", + }, + "400": { + "description": "Bad request", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/ChannelPolicy" + "$ref": "#/components/schemas/ApiErrorResponse" } } } @@ -24641,51 +40718,77 @@ } } } + }, + "404": { + "description": "Not found", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } + } + } + }, + "409": { + "description": "Conflict", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } + } + } } } - }, + } + }, + "/v1/offers:resolve": { "get": { - "x-platform-visibility": "TRUSTED_PARTNER", - "x-platform-live": { - "visibility": "TRUSTED_PARTNER", - "transport": "convex", - "convexQuery": "offers.ui.listChannelPoliciesForApi" - }, - "operationId": "channelPolicies.list", + "x-platform-visibility": "PUBLIC", + "operationId": "offers.resolve", "tags": [ - "Channel Policies" - ], - "summary": "List channel policies", - "security": [ - { - "BearerAuth": [] - } + "Offers" ], + "summary": "Resolve offer by short hash", + "description": "Resolves an offer from the customer-clicked URL `/i/`. Anonymous callers receive the publicly-safe subset of fields needed to render the landing page (product name, logo, seller name, status, tier). Authenticated callers authorized to claim through an open allowlist or a verified-email match additionally receive entitled pre-fill values. Customer resolve never returns seller owner metadata or the configured email allowlist. Authenticated callers whose email is not on a configured allowlist receive 403.", + "security": [], "parameters": [ { "schema": { "type": "string", "minLength": 1, - "maxLength": 54 + "maxLength": 64, + "description": "Offer short hash from the customer-clicked URL" }, "required": true, - "name": "offer_channel", + "description": "Offer short hash from the customer-clicked URL", + "name": "short_hash", "in": "query" } ], "responses": { "200": { - "description": "Channel policies", + "description": "Offer resolved", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/ChannelPolicyList" + "$ref": "#/components/schemas/Offer" } } } }, - "401": { - "description": "Unauthorized", + "403": { + "description": "Forbidden", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } + } + } + }, + "404": { + "description": "Not found", "content": { "application/json": { "schema": { @@ -24697,14 +40800,15 @@ } } }, - "/v1/channel_policies/{id}": { - "get": { - "x-platform-visibility": "TRUSTED_PARTNER", - "operationId": "channelPolicies.get", + "/v1/offers/{id}:archive": { + "post": { + "x-platform-visibility": "PUBLIC", + "operationId": "offers.archive", "tags": [ - "Channel Policies" + "Offers" ], - "summary": "Get channel policy", + "summary": "Archive offer", + "description": "Archives the offer and blocks new redemptions. The offer row remains for history and audit; callers receive the full Offer with `status: \"archived\"`. Idempotent: already-archived offers return unchanged. If-Match is required for optimistic concurrency.", "security": [ { "BearerAuth": [] @@ -24715,20 +40819,62 @@ "schema": { "type": "string", "minLength": 1, - "maxLength": 56 + "maxLength": 56, + "description": "Offer ID", + "example": "offer_j572abc..." }, "required": true, + "description": "Offer ID", "name": "id", "in": "path" + }, + { + "schema": { + "type": "string", + "minLength": 1, + "maxLength": 53, + "description": "Optional workspace/scope context for the request. Carries a single workspace wire id (`ws_…`) today. Only needed for broad tokens — a workspace-owned token implies its workspace.", + "example": "ws_j572abc123def456" + }, + "required": false, + "description": "Optional workspace/scope context for the request. Carries a single workspace wire id (`ws_…`) today. Only needed for broad tokens — a workspace-owned token implies its workspace.", + "name": "akua-context", + "in": "header" + }, + { + "schema": { + "type": "string", + "minLength": 1, + "maxLength": 64, + "description": "Optional caller-supplied idempotency key. Any non-empty key up to 64 characters is accepted. Endpoint-specific documentation describes how the key is used.", + "example": "create-prod-2026-05-07" + }, + "required": false, + "description": "Optional caller-supplied idempotency key. Any non-empty key up to 64 characters is accepted. Endpoint-specific documentation describes how the key is used.", + "name": "idempotency-key", + "in": "header" + }, + { + "schema": { + "type": "string", + "minLength": 1, + "maxLength": 256, + "description": "The `etag` of the resource version the client last read. Required on writes when the resource exposes an `etag` field. Mismatch returns 409 `ABORTED` with the current etag in the error metadata.", + "example": "42" + }, + "required": true, + "description": "The `etag` of the resource version the client last read. Required on writes when the resource exposes an `etag` field. Mismatch returns 409 `ABORTED` with the current etag in the error metadata.", + "name": "if-match", + "in": "header" } ], "responses": { "200": { - "description": "Channel policy", + "description": "Offer archived", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/ChannelPolicy" + "$ref": "#/components/schemas/Offer" } } } @@ -24743,6 +40889,16 @@ } } }, + "403": { + "description": "Forbidden", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } + } + } + }, "404": { "description": "Not found", "content": { @@ -24752,18 +40908,39 @@ } } } + }, + "409": { + "description": "Conflict", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } + } + } + }, + "422": { + "description": "Unprocessable entity", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } + } + } } } } }, - "/v1/channel_policies/{id}:approve": { + "/v1/offers/{id}:unarchive": { "post": { - "x-platform-visibility": "TRUSTED_PARTNER", - "operationId": "channelPolicies.approve", + "x-platform-visibility": "PUBLIC", + "operationId": "offers.unarchive", "tags": [ - "Channel Policies" + "Offers" ], - "summary": "Approve channel policy", + "summary": "Unarchive offer", + "description": "Reverts a previously-archived offer back to `active`. Idempotent: already-active offers return unchanged. Does not auto-cascade to dependents or previously-archived child references.", "security": [ { "BearerAuth": [] @@ -24774,9 +40951,12 @@ "schema": { "type": "string", "minLength": 1, - "maxLength": 56 + "maxLength": 56, + "description": "Offer ID", + "example": "offer_j572abc..." }, "required": true, + "description": "Offer ID", "name": "id", "in": "path" }, @@ -24797,20 +40977,36 @@ "schema": { "type": "string", "minLength": 1, - "maxLength": 64 + "maxLength": 64, + "description": "Optional caller-supplied idempotency key. Any non-empty key up to 64 characters is accepted. Endpoint-specific documentation describes how the key is used.", + "example": "create-prod-2026-05-07" }, - "required": true, + "required": false, + "description": "Optional caller-supplied idempotency key. Any non-empty key up to 64 characters is accepted. Endpoint-specific documentation describes how the key is used.", "name": "idempotency-key", "in": "header" + }, + { + "schema": { + "type": "string", + "minLength": 1, + "maxLength": 256, + "description": "The `etag` of the resource version the client last read. Required on writes when the resource exposes an `etag` field. Mismatch returns 409 `ABORTED` with the current etag in the error metadata.", + "example": "42" + }, + "required": true, + "description": "The `etag` of the resource version the client last read. Required on writes when the resource exposes an `etag` field. Mismatch returns 409 `ABORTED` with the current etag in the error metadata.", + "name": "if-match", + "in": "header" } ], "responses": { "200": { - "description": "Channel policy", + "description": "Offer unarchived", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/ChannelPolicy" + "$ref": "#/components/schemas/Offer" } } } @@ -24834,18 +41030,49 @@ } } } + }, + "404": { + "description": "Not found", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } + } + } + }, + "409": { + "description": "Conflict", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } + } + } + }, + "422": { + "description": "Unprocessable entity", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } + } + } } } } }, - "/v1/channel_policies/{id}:activate": { + "/v1/offers/{offer}/order_drafts": { "post": { - "x-platform-visibility": "TRUSTED_PARTNER", - "operationId": "channelPolicies.activate", + "x-platform-visibility": "PUBLIC", + "operationId": "orderDrafts.create", "tags": [ - "Channel Policies" + "Order Drafts" ], - "summary": "Activate channel policy", + "summary": "Create order draft", + "description": "Creates a customer wizard session (OrderDraft) for the parent offer. The caller is the customer; their authenticated user becomes the draft's owner. Each idempotent create call returns the same draft for the same Idempotency-Key. Concurrency limits and email-allowlist gates apply per the offer's configuration; failures map to 403 (forbidden) or 422 (offer not redeemable).", "security": [ { "BearerAuth": [] @@ -24856,43 +41083,36 @@ "schema": { "type": "string", "minLength": 1, - "maxLength": 56 + "maxLength": 56, + "description": "Parent offer ID", + "example": "offer_j572abc..." }, "required": true, - "name": "id", + "description": "Parent offer ID", + "name": "offer", "in": "path" }, { "schema": { "type": "string", "minLength": 1, - "maxLength": 53, - "description": "Optional workspace/scope context for the request. Carries a single workspace wire id (`ws_…`) today. Only needed for broad tokens — a workspace-owned token implies its workspace.", - "example": "ws_j572abc123def456" + "maxLength": 64, + "description": "Optional caller-supplied idempotency key. Any non-empty key up to 64 characters is accepted. Endpoint-specific documentation describes how the key is used.", + "example": "create-prod-2026-05-07" }, "required": false, - "description": "Optional workspace/scope context for the request. Carries a single workspace wire id (`ws_…`) today. Only needed for broad tokens — a workspace-owned token implies its workspace.", - "name": "akua-context", - "in": "header" - }, - { - "schema": { - "type": "string", - "minLength": 1, - "maxLength": 64 - }, - "required": true, + "description": "Optional caller-supplied idempotency key. Any non-empty key up to 64 characters is accepted. Endpoint-specific documentation describes how the key is used.", "name": "idempotency-key", "in": "header" } ], "responses": { - "200": { - "description": "Channel policy", + "201": { + "description": "Order draft started", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/ChannelPolicy" + "$ref": "#/components/schemas/OrderDraft" } } } @@ -24916,18 +41136,39 @@ } } } + }, + "404": { + "description": "Not found", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } + } + } + }, + "422": { + "description": "Unprocessable entity", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } + } + } } } } }, - "/v1/channel_policies/{id}:archive": { - "post": { - "x-platform-visibility": "TRUSTED_PARTNER", - "operationId": "channelPolicies.archive", + "/v1/order_drafts": { + "get": { + "x-platform-visibility": "PUBLIC", + "operationId": "orderDrafts.list", "tags": [ - "Channel Policies" + "Order Drafts" ], - "summary": "Archive channel policy", + "summary": "List order drafts", + "description": "Returns order drafts for one offer. `?offer=` is required in v1; `?status=` can further filter by wizard phase. With a workspace context (token-implied or `Akua-Context`), only workspace-member-visible drafts are returned and `field_values` is omitted.", "security": [ { "BearerAuth": [] @@ -24937,44 +41178,70 @@ { "schema": { "type": "string", - "minLength": 1, - "maxLength": 56 + "description": "Pagination cursor from a previous response's `next_cursor`." }, - "required": true, - "name": "id", - "in": "path" + "required": false, + "description": "Pagination cursor from a previous response's `next_cursor`.", + "name": "cursor", + "in": "query" + }, + { + "schema": { + "type": "integer", + "minimum": 1, + "maximum": 100, + "default": 50, + "description": "Items per page (1-100, default 50)", + "example": 50 + }, + "required": false, + "description": "Items per page (1-100, default 50)", + "name": "limit", + "in": "query" }, { "schema": { "type": "string", "minLength": 1, - "maxLength": 53, - "description": "Optional workspace/scope context for the request. Carries a single workspace wire id (`ws_…`) today. Only needed for broad tokens — a workspace-owned token implies its workspace.", - "example": "ws_j572abc123def456" + "maxLength": 56, + "description": "Filter by offer ID", + "example": "offer_j572abc123def456" }, "required": false, - "description": "Optional workspace/scope context for the request. Carries a single workspace wire id (`ws_…`) today. Only needed for broad tokens — a workspace-owned token implies its workspace.", - "name": "akua-context", - "in": "header" + "description": "Filter by offer ID", + "name": "offer", + "in": "query" + }, + { + "schema": { + "$ref": "#/components/schemas/OrderDraftStatus" + }, + "required": false, + "description": "Wizard phase. Driven by the order draft actor; mirrored on every patch to the row so reactive UIs render one column. `done` and `terminated` are terminal.", + "name": "status", + "in": "query" }, { "schema": { "type": "string", "minLength": 1, - "maxLength": 64 + "maxLength": 53, + "description": "Optional workspace/scope context for the request. Carries a single workspace wire id (`ws_…`) today. Only needed for broad tokens — a workspace-owned token implies its workspace.", + "example": "ws_j572abc123def456" }, - "required": true, - "name": "idempotency-key", + "required": false, + "description": "Optional workspace/scope context for the request. Carries a single workspace wire id (`ws_…`) today. Only needed for broad tokens — a workspace-owned token implies its workspace.", + "name": "akua-context", "in": "header" } ], "responses": { "200": { - "description": "Channel policy", + "description": "List of order drafts", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/ChannelPolicy" + "$ref": "#/components/schemas/OrderDraftList" } } } @@ -25002,20 +41269,20 @@ } } }, - "/v1/offers": { + "/v1/order_drafts:workspaceList": { "get": { - "x-platform-visibility": "PUBLIC", + "x-platform-visibility": "INTERNAL", "x-platform-live": { - "visibility": "TRUSTED_PARTNER", + "visibility": "INTERNAL", "transport": "convex", - "convexQuery": "offers.ui.listMyWorkspaceOffers" + "convexQuery": "orders.ui.listMyWorkspaceOrders" }, - "operationId": "offers.list", + "operationId": "orderDrafts.listWorkspace", "tags": [ - "Offers" + "Order Drafts" ], - "summary": "List offers in workspace", - "description": "Returns offers belonging to the workspace specified in the workspace context, newest first.", + "summary": "List workspace order drafts", + "description": "Returns order drafts for offers in the selected workspace. Intended for dashboard live reads.", "security": [ { "BearerAuth": [] @@ -25046,16 +41313,6 @@ "name": "limit", "in": "query" }, - { - "schema": { - "type": "string", - "minLength": 1, - "maxLength": 55 - }, - "required": false, - "name": "product_id", - "in": "query" - }, { "schema": { "type": "string", @@ -25072,11 +41329,11 @@ ], "responses": { "200": { - "description": "List of offers", + "description": "List of workspace order drafts", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/OfferList" + "$ref": "#/components/schemas/OrderDraftList" } } } @@ -25102,15 +41359,22 @@ } } } - }, - "post": { + } + }, + "/v1/order_drafts/{id}": { + "get": { "x-platform-visibility": "PUBLIC", - "operationId": "offers.create", + "x-platform-live": { + "visibility": "INTERNAL", + "transport": "convex", + "convexQuery": "orders.ui.getMyOrderDraft" + }, + "operationId": "orderDrafts.get", "tags": [ - "Offers" + "Order Drafts" ], - "summary": "Create offer", - "description": "Creates an Offer for a product or a specific package version. When `product_id` is supplied without `package_version_id`, the server resolves the product’s current package version pin, validates `field_values` against that resolved version’s input schema, and stores the concrete package version on the Offer. Customers reach the Offer at `/i/` to start an install. When `allowed_emails` is non-empty, only those email addresses can use the Offer; when empty or omitted, any authenticated customer can.", + "summary": "Get order draft details", + "description": "Returns the order draft row. The order draft’s own customer sees the full record including `field_values`; workspace members of the parent offer see the row with `field_values` omitted.", "security": [ { "BearerAuth": [] @@ -25121,42 +41385,23 @@ "schema": { "type": "string", "minLength": 1, - "maxLength": 53, - "description": "Optional workspace/scope context for the request. Carries a single workspace wire id (`ws_…`) today. Only needed for broad tokens — a workspace-owned token implies its workspace.", - "example": "ws_j572abc123def456" + "maxLength": 55, + "description": "Order draft ID", + "example": "odft_j572abc..." }, - "required": false, - "description": "Optional workspace/scope context for the request. Carries a single workspace wire id (`ws_…`) today. Only needed for broad tokens — a workspace-owned token implies its workspace.", - "name": "akua-context", - "in": "header" + "required": true, + "description": "Order draft ID", + "name": "id", + "in": "path" } ], - "requestBody": { - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/CreateOfferBody" - } - } - } - }, "responses": { - "201": { - "description": "Offer created", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/OfferCreated" - } - } - } - }, - "400": { - "description": "Bad request", + "200": { + "description": "Order draft details", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/ApiErrorResponse" + "$ref": "#/components/schemas/OrderDraft" } } } @@ -25181,8 +41426,8 @@ } } }, - "422": { - "description": "Unprocessable entity", + "404": { + "description": "Not found", "content": { "application/json": { "schema": { @@ -25194,15 +41439,15 @@ } } }, - "/v1/offers/{id}": { - "get": { + "/v1/order_drafts/{id}:cancel": { + "post": { "x-platform-visibility": "PUBLIC", - "operationId": "offers.get", + "operationId": "orderDrafts.cancel", "tags": [ - "Offers" + "Order Drafts" ], - "summary": "Get offer details", - "description": "Returns the full offer record including pre-fill values and email allowlist. Caller must be a member of the offer’s workspace.", + "summary": "Cancel order draft", + "description": "Terminates an in-flight order draft, returning the updated record. Allowed for the order draft’s own customer or any member of the parent offer’s workspace. Idempotent — cancelling a terminated order draft returns it unchanged. Allocated cluster resources are released and any in-flight install workflow is terminated; previously-completed work is NOT undone.", "security": [ { "BearerAuth": [] @@ -25213,23 +41458,36 @@ "schema": { "type": "string", "minLength": 1, - "maxLength": 56, - "description": "Offer ID", - "example": "offer_j572abc..." + "maxLength": 55, + "description": "Order draft ID", + "example": "odft_j572abc..." }, "required": true, - "description": "Offer ID", + "description": "Order draft ID", "name": "id", "in": "path" + }, + { + "schema": { + "type": "string", + "minLength": 1, + "maxLength": 256, + "description": "The `etag` of the resource version the client last read. Required on writes when the resource exposes an `etag` field. Mismatch returns 409 `ABORTED` with the current etag in the error metadata.", + "example": "42" + }, + "required": true, + "description": "The `etag` of the resource version the client last read. Required on writes when the resource exposes an `etag` field. Mismatch returns 409 `ABORTED` with the current etag in the error metadata.", + "name": "if-match", + "in": "header" } ], "responses": { "200": { - "description": "Offer details", + "description": "Order draft cancelled", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/Offer" + "$ref": "#/components/schemas/OrderDraft" } } } @@ -25263,19 +41521,39 @@ } } } + }, + "409": { + "description": "Conflict", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } + } + } + }, + "422": { + "description": "Unprocessable entity", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } + } + } } } } }, - "/v1/offers:preview": { + "/v1/order_drafts/{id}:claim": { "post": { - "x-platform-visibility": "TRUSTED_PARTNER", - "operationId": "offers.preview", + "x-platform-visibility": "PUBLIC", + "operationId": "orderDrafts.claim", "tags": [ - "Offers" + "Order Drafts" ], - "summary": "Preview offer policy", - "description": "Resolves an offer request against the active Offer Channel policy without creating an offer.", + "summary": "Claim order draft", + "description": "Binds the calling authenticated user to an anonymous order draft using a one-time claim token (R13 + AIP-147 INPUT_ONLY).", "security": [ { "BearerAuth": [] @@ -25286,38 +41564,52 @@ "schema": { "type": "string", "minLength": 1, - "maxLength": 53, - "description": "Optional workspace/scope context for the request. Carries a single workspace wire id (`ws_…`) today. Only needed for broad tokens — a workspace-owned token implies its workspace.", - "example": "ws_j572abc123def456" + "maxLength": 55, + "description": "Order draft ID", + "example": "odft_j572abc..." }, - "required": false, - "description": "Optional workspace/scope context for the request. Carries a single workspace wire id (`ws_…`) today. Only needed for broad tokens — a workspace-owned token implies its workspace.", - "name": "akua-context", + "required": true, + "description": "Order draft ID", + "name": "id", + "in": "path" + }, + { + "schema": { + "type": "string", + "minLength": 1, + "maxLength": 256, + "description": "The `etag` of the resource version the client last read. Required on writes when the resource exposes an `etag` field. Mismatch returns 409 `ABORTED` with the current etag in the error metadata.", + "example": "42" + }, + "required": true, + "description": "The `etag` of the resource version the client last read. Required on writes when the resource exposes an `etag` field. Mismatch returns 409 `ABORTED` with the current etag in the error metadata.", + "name": "if-match", "in": "header" } ], "requestBody": { + "required": true, "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/PreviewOfferBody" + "$ref": "#/components/schemas/ClaimOrderDraftBody" } } } }, "responses": { "200": { - "description": "Offer policy preview", + "description": "Order draft claimed", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/OfferPolicySnapshot" + "$ref": "#/components/schemas/OrderDraft" } } } }, - "400": { - "description": "Bad request", + "401": { + "description": "Unauthorized", "content": { "application/json": { "schema": { @@ -25326,8 +41618,8 @@ } } }, - "401": { - "description": "Unauthorized", + "403": { + "description": "Forbidden", "content": { "application/json": { "schema": { @@ -25336,8 +41628,18 @@ } } }, - "403": { - "description": "Forbidden", + "404": { + "description": "Not found", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } + } + } + }, + "409": { + "description": "Conflict", "content": { "application/json": { "schema": { @@ -25359,15 +41661,15 @@ } } }, - "/v1/offers/{id}:approve": { + "/v1/order_drafts/{id}:selectWorkspace": { "post": { - "x-platform-visibility": "INTERNAL", - "operationId": "offers.approve", + "x-platform-visibility": "PUBLIC", + "operationId": "orderDrafts.selectWorkspace", "tags": [ - "Offers" + "Order Drafts" ], - "summary": "Approve offer", - "description": "Approves a pending channel-backed offer and freezes its requested policy snapshot as the approved effective policy snapshot.", + "summary": "Select order workspace", + "description": "Selects the customer workspace for an order draft, or creates a new workspace for the order. This advances the draft from workspace selection to compute allocation.", "security": [ { "BearerAuth": [] @@ -25378,12 +41680,12 @@ "schema": { "type": "string", "minLength": 1, - "maxLength": 56, - "description": "Offer ID", - "example": "offer_j572abc..." + "maxLength": 55, + "description": "Order draft ID", + "example": "odft_j572abc..." }, "required": true, - "description": "Offer ID", + "description": "Order draft ID", "name": "id", "in": "path" }, @@ -25391,33 +41693,33 @@ "schema": { "type": "string", "minLength": 1, - "maxLength": 53, - "description": "Optional workspace/scope context for the request. Carries a single workspace wire id (`ws_…`) today. Only needed for broad tokens — a workspace-owned token implies its workspace.", - "example": "ws_j572abc123def456" + "maxLength": 256, + "description": "The `etag` of the resource version the client last read. Required on writes when the resource exposes an `etag` field. Mismatch returns 409 `ABORTED` with the current etag in the error metadata.", + "example": "42" }, - "required": false, - "description": "Optional workspace/scope context for the request. Carries a single workspace wire id (`ws_…`) today. Only needed for broad tokens — a workspace-owned token implies its workspace.", - "name": "akua-context", + "required": true, + "description": "The `etag` of the resource version the client last read. Required on writes when the resource exposes an `etag` field. Mismatch returns 409 `ABORTED` with the current etag in the error metadata.", + "name": "if-match", "in": "header" } ], - "responses": { - "200": { - "description": "Offer approved", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/Offer" - } + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/SelectOrderDraftWorkspaceBody" } } - }, - "400": { - "description": "Bad request", + } + }, + "responses": { + "200": { + "description": "Workspace selected", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/ApiErrorResponse" + "$ref": "#/components/schemas/OrderDraft" } } } @@ -25461,19 +41763,29 @@ } } } + }, + "422": { + "description": "Unprocessable entity", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } + } + } } } } }, - "/v1/offers/{id}:reject": { + "/v1/order_drafts/{id}:submitConfiguration": { "post": { - "x-platform-visibility": "INTERNAL", - "operationId": "offers.reject", + "x-platform-visibility": "PUBLIC", + "operationId": "orderDrafts.submitConfigure", "tags": [ - "Offers" + "Order Drafts" ], - "summary": "Reject offer", - "description": "Rejects a pending channel-backed offer. Rejected offers keep their requested policy snapshot but cannot receive an approved effective snapshot.", + "summary": "Submit configure values", + "description": "Persists the customer’s configure-form values on the order draft and advances it to the payment phase, returning the updated record. Values are validated against the package version’s schema.", "security": [ { "BearerAuth": [] @@ -25484,12 +41796,12 @@ "schema": { "type": "string", "minLength": 1, - "maxLength": 56, - "description": "Offer ID", - "example": "offer_j572abc..." + "maxLength": 55, + "description": "Order draft ID", + "example": "odft_j572abc..." }, "required": true, - "description": "Offer ID", + "description": "Order draft ID", "name": "id", "in": "path" }, @@ -25497,33 +41809,33 @@ "schema": { "type": "string", "minLength": 1, - "maxLength": 53, - "description": "Optional workspace/scope context for the request. Carries a single workspace wire id (`ws_…`) today. Only needed for broad tokens — a workspace-owned token implies its workspace.", - "example": "ws_j572abc123def456" + "maxLength": 256, + "description": "The `etag` of the resource version the client last read. Required on writes when the resource exposes an `etag` field. Mismatch returns 409 `ABORTED` with the current etag in the error metadata.", + "example": "42" }, - "required": false, - "description": "Optional workspace/scope context for the request. Carries a single workspace wire id (`ws_…`) today. Only needed for broad tokens — a workspace-owned token implies its workspace.", - "name": "akua-context", + "required": true, + "description": "The `etag` of the resource version the client last read. Required on writes when the resource exposes an `etag` field. Mismatch returns 409 `ABORTED` with the current etag in the error metadata.", + "name": "if-match", "in": "header" } ], - "responses": { - "200": { - "description": "Offer rejected", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/Offer" - } + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/SubmitConfigureOrderDraftBody" } } - }, - "400": { - "description": "Bad request", + } + }, + "responses": { + "200": { + "description": "Configure submitted", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/ApiErrorResponse" + "$ref": "#/components/schemas/OrderDraft" } } } @@ -25567,41 +41879,84 @@ } } } + }, + "422": { + "description": "Unprocessable entity", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } + } + } } } } }, - "/v1/offers:resolve": { - "get": { + "/v1/order_drafts/{id}:createWorkerBootstrap": { + "post": { "x-platform-visibility": "PUBLIC", - "operationId": "offers.resolve", + "operationId": "orderDrafts.createWorkerBootstrap", "tags": [ - "Offers" + "Order Drafts" + ], + "summary": "Create order draft worker bootstrap", + "description": "Creates a short-lived worker bootstrap token and renders command/cloud-init data for the cluster allocated to this order draft. Only valid while the draft is waiting for compute bootstrap.", + "security": [ + { + "BearerAuth": [] + } ], - "summary": "Resolve offer by short hash", - "description": "Resolves an offer from the customer-clicked URL `/i/`. Anonymous callers receive the publicly-safe subset of fields needed to render the landing page (product name, logo, seller name, status, tier). Authenticated callers whose verified email matches the offer's allowlist additionally receive pre-fill values and other workspace-private fields. Authenticated callers whose email is not on the allowlist receive 403.", - "security": [], "parameters": [ { "schema": { "type": "string", "minLength": 1, - "maxLength": 64, - "description": "Offer short hash from the customer-clicked URL" + "maxLength": 55, + "description": "Order draft ID", + "example": "odft_j572abc..." }, "required": true, - "description": "Offer short hash from the customer-clicked URL", - "name": "short_hash", - "in": "query" + "description": "Order draft ID", + "name": "id", + "in": "path" + } + ], + "requestBody": { + "required": false, + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "ttl_seconds": { + "type": "integer", + "minimum": 60, + "maximum": 86400 + } + }, + "additionalProperties": false + } + } } - ], + }, "responses": { "200": { - "description": "Offer resolved", + "description": "Worker bootstrap data", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/Offer" + "$ref": "#/components/schemas/OrderDraftWorkerBootstrap" + } + } + } + }, + "401": { + "description": "Unauthorized", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" } } } @@ -25625,19 +41980,29 @@ } } } + }, + "409": { + "description": "Conflict", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } + } + } } } } }, - "/v1/offers/{id}:archive": { + "/v1/order_drafts/{id}/checkout_sessions": { "post": { "x-platform-visibility": "PUBLIC", - "operationId": "offers.archive", + "operationId": "orderDrafts.createCheckoutSession", "tags": [ - "Offers" + "Order Drafts" ], - "summary": "Archive offer", - "description": "Archives the offer and blocks new redemptions. The offer row remains for history and audit; callers receive the full Offer with `status: \"archived\"`. Idempotent: already-archived offers return unchanged. If-Match is required for optimistic concurrency.", + "summary": "Create order draft checkout session", + "description": "Creates a Stripe Checkout Session for the current order-draft payment revision, or returns the existing open session when it still has enough remaining lifetime. Stale sessions are expired and superseded before a replacement is created.", "security": [ { "BearerAuth": [] @@ -25648,41 +42013,15 @@ "schema": { "type": "string", "minLength": 1, - "maxLength": 56, - "description": "Offer ID", - "example": "offer_j572abc..." + "maxLength": 55, + "description": "Order draft ID", + "example": "odft_j572abc..." }, "required": true, - "description": "Offer ID", + "description": "Order draft ID", "name": "id", "in": "path" }, - { - "schema": { - "type": "string", - "minLength": 1, - "maxLength": 53, - "description": "Optional workspace/scope context for the request. Carries a single workspace wire id (`ws_…`) today. Only needed for broad tokens — a workspace-owned token implies its workspace.", - "example": "ws_j572abc123def456" - }, - "required": false, - "description": "Optional workspace/scope context for the request. Carries a single workspace wire id (`ws_…`) today. Only needed for broad tokens — a workspace-owned token implies its workspace.", - "name": "akua-context", - "in": "header" - }, - { - "schema": { - "type": "string", - "minLength": 1, - "maxLength": 64, - "description": "Caller-supplied idempotency key. Repeated requests with the same key return the existing resource instead of creating a duplicate. Safe to retry after a timed-out or interrupted request.", - "example": "create-prod-2026-05-07" - }, - "required": false, - "description": "Caller-supplied idempotency key. Repeated requests with the same key return the existing resource instead of creating a duplicate. Safe to retry after a timed-out or interrupted request.", - "name": "idempotency-key", - "in": "header" - }, { "schema": { "type": "string", @@ -25698,12 +42037,12 @@ } ], "responses": { - "200": { - "description": "Offer archived", + "201": { + "description": "Checkout session created or reused", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/Offer" + "$ref": "#/components/schemas/OrderDraftCheckoutSession" } } } @@ -25757,19 +42096,27 @@ } } } + }, + "500": { + "description": "Internal server error", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } + } + } } } - } - }, - "/v1/offers/{id}:unarchive": { - "post": { + }, + "get": { "x-platform-visibility": "PUBLIC", - "operationId": "offers.unarchive", + "operationId": "orderDrafts.listCheckoutSessions", "tags": [ - "Offers" + "Order Drafts" ], - "summary": "Unarchive offer", - "description": "Reverts a previously-archived offer back to `active`. Idempotent: already-active offers return unchanged. Does not auto-cascade to dependents or previously-archived child references.", + "summary": "List order draft checkout sessions", + "description": "Returns historical checkout session rows for the order draft (current and past) for resume/audit workflows.", "security": [ { "BearerAuth": [] @@ -25780,62 +42127,47 @@ "schema": { "type": "string", "minLength": 1, - "maxLength": 56, - "description": "Offer ID", - "example": "offer_j572abc..." + "maxLength": 55, + "description": "Order draft ID", + "example": "odft_j572abc..." }, "required": true, - "description": "Offer ID", + "description": "Order draft ID", "name": "id", "in": "path" }, { "schema": { "type": "string", - "minLength": 1, - "maxLength": 53, - "description": "Optional workspace/scope context for the request. Carries a single workspace wire id (`ws_…`) today. Only needed for broad tokens — a workspace-owned token implies its workspace.", - "example": "ws_j572abc123def456" + "description": "Pagination cursor from a previous response's `next_cursor`." }, "required": false, - "description": "Optional workspace/scope context for the request. Carries a single workspace wire id (`ws_…`) today. Only needed for broad tokens — a workspace-owned token implies its workspace.", - "name": "akua-context", - "in": "header" + "description": "Pagination cursor from a previous response's `next_cursor`.", + "name": "cursor", + "in": "query" }, { "schema": { - "type": "string", - "minLength": 1, - "maxLength": 64, - "description": "Caller-supplied idempotency key. Repeated requests with the same key return the existing resource instead of creating a duplicate. Safe to retry after a timed-out or interrupted request.", - "example": "create-prod-2026-05-07" + "type": "integer", + "minimum": 1, + "maximum": 100, + "default": 50, + "description": "Items per page (1-100, default 50)", + "example": 50 }, "required": false, - "description": "Caller-supplied idempotency key. Repeated requests with the same key return the existing resource instead of creating a duplicate. Safe to retry after a timed-out or interrupted request.", - "name": "idempotency-key", - "in": "header" - }, - { - "schema": { - "type": "string", - "minLength": 1, - "maxLength": 256, - "description": "The `etag` of the resource version the client last read. Required on writes when the resource exposes an `etag` field. Mismatch returns 409 `ABORTED` with the current etag in the error metadata.", - "example": "42" - }, - "required": true, - "description": "The `etag` of the resource version the client last read. Required on writes when the resource exposes an `etag` field. Mismatch returns 409 `ABORTED` with the current etag in the error metadata.", - "name": "if-match", - "in": "header" + "description": "Items per page (1-100, default 50)", + "name": "limit", + "in": "query" } ], "responses": { "200": { - "description": "Offer unarchived", + "description": "List of checkout sessions", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/Offer" + "$ref": "#/components/schemas/CheckoutSessionList" } } } @@ -25869,9 +42201,73 @@ } } } + } + } + } + }, + "/v1/order_drafts/{id}/checkout_sessions/{chk_id}": { + "get": { + "x-platform-visibility": "PUBLIC", + "operationId": "orderDrafts.getCheckoutSession", + "tags": [ + "Order Drafts" + ], + "summary": "Get order draft checkout session", + "description": "Returns one historical checkout session by ID, including the current session state.", + "security": [ + { + "BearerAuth": [] + } + ], + "parameters": [ + { + "schema": { + "type": "string", + "minLength": 1, + "maxLength": 55, + "description": "Order draft ID", + "example": "odft_j572abc..." + }, + "required": true, + "description": "Order draft ID", + "name": "id", + "in": "path" + }, + { + "schema": { + "type": "string", + "description": "Checkout session ID", + "example": "chk_abcdefghijk..." + }, + "required": true, + "description": "Checkout session ID", + "name": "chk_id", + "in": "path" + } + ], + "responses": { + "200": { + "description": "Checkout session details", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/CheckoutSession" + } + } + } + }, + "401": { + "description": "Unauthorized", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } + } + } }, - "409": { - "description": "Conflict", + "403": { + "description": "Forbidden", "content": { "application/json": { "schema": { @@ -25880,8 +42276,8 @@ } } }, - "422": { - "description": "Unprocessable entity", + "404": { + "description": "Not found", "content": { "application/json": { "schema": { @@ -25893,15 +42289,15 @@ } } }, - "/v1/offers/{offer}/order_drafts": { + "/v1/orders/{order}/deliveries/{delivery}:removeDemoCleanup": { "post": { - "x-platform-visibility": "PUBLIC", - "operationId": "orderDrafts.create", + "x-platform-visibility": "ADMIN", + "operationId": "orderDrafts.removeDemoCleanup", "tags": [ "Order Drafts" ], - "summary": "Create order draft", - "description": "Creates a customer wizard session (OrderDraft) for the parent offer. The caller is the customer; their authenticated user becomes the draft's owner. Each idempotent create call returns the same draft for the same Idempotency-Key. Concurrency limits and email-allowlist gates apply per the offer's configuration; failures map to 403 (forbidden) or 422 (offer not redeemable).", + "summary": "Remove demo cleanup after platform approval", + "description": "Removes scheduled cleanup from a non-billable demo/test order delivery after platform approval. This is an admin-only conversion hook; sellers and customers cannot remove cleanup unilaterally.", "security": [ { "BearerAuth": [] @@ -25912,36 +42308,44 @@ "schema": { "type": "string", "minLength": 1, - "maxLength": 56, - "description": "Parent offer ID", - "example": "offer_j572abc..." + "maxLength": 54, + "description": "Committed order ID" }, "required": true, - "description": "Parent offer ID", - "name": "offer", + "description": "Committed order ID", + "name": "order", "in": "path" }, { "schema": { "type": "string", "minLength": 1, - "maxLength": 64, - "description": "Caller-supplied idempotency key. Repeated requests with the same key return the existing resource instead of creating a duplicate. Safe to retry after a timed-out or interrupted request.", - "example": "create-prod-2026-05-07" + "maxLength": 55, + "description": "Order delivery ID" }, - "required": false, - "description": "Caller-supplied idempotency key. Repeated requests with the same key return the existing resource instead of creating a duplicate. Safe to retry after a timed-out or interrupted request.", - "name": "idempotency-key", - "in": "header" + "required": true, + "description": "Order delivery ID", + "name": "delivery", + "in": "path" } ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/RemoveDemoCleanupAfterPlatformApprovalBody" + } + } + } + }, "responses": { - "201": { - "description": "Order draft started", + "200": { + "description": "Demo cleanup removed from the order and delivery", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/OrderDraft" + "$ref": "#/components/schemas/DemoCleanupRemoval" } } } @@ -25976,6 +42380,16 @@ } } }, + "409": { + "description": "Conflict", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } + } + } + }, "422": { "description": "Unprocessable entity", "content": { @@ -25989,15 +42403,20 @@ } } }, - "/v1/order_drafts": { + "/v1/entitlements": { "get": { "x-platform-visibility": "PUBLIC", - "operationId": "orderDrafts.list", + "operationId": "entitlements.list", "tags": [ - "Order Drafts" + "Entitlements" ], - "summary": "List order drafts", - "description": "Returns order drafts for one offer. `?offer=` is required in v1; `?status=` can further filter by wizard phase. With a workspace context (token-implied or `Akua-Context`), only workspace-member-visible drafts are returned and `field_values` is omitted.", + "x-platform-live": { + "visibility": "INTERNAL", + "transport": "convex", + "convexQuery": "workspace.ui.listEffectiveEntitlementsForApi" + }, + "summary": "List entitlements", + "description": "Returns active effective entitlements visible to the authenticated caller.", "security": [ { "BearerAuth": [] @@ -26032,45 +42451,47 @@ "schema": { "type": "string", "minLength": 1, - "maxLength": 56, - "description": "Filter by offer ID", - "example": "offer_j572abc123def456" + "maxLength": 53, + "description": "Filter entitlements to one workspace.", + "example": "ws_j572abc123def456" }, "required": false, - "description": "Filter by offer ID", - "name": "offer", + "description": "Filter entitlements to one workspace.", + "name": "workspace", "in": "query" }, { "schema": { - "$ref": "#/components/schemas/OrderDraftStatus" + "type": "string", + "minLength": 1, + "maxLength": 128, + "description": "Filter entitlements to one feature set, such as `compute`." }, "required": false, - "description": "Wizard phase. Driven by the order draft actor; mirrored on every patch to the row so reactive UIs render one column. `done` and `terminated` are terminal.", - "name": "status", + "description": "Filter entitlements to one feature set, such as `compute`.", + "name": "feature_set", "in": "query" }, { "schema": { "type": "string", "minLength": 1, - "maxLength": 53, - "description": "Optional workspace/scope context for the request. Carries a single workspace wire id (`ws_…`) today. Only needed for broad tokens — a workspace-owned token implies its workspace.", - "example": "ws_j572abc123def456" + "maxLength": 256, + "description": "Filter entitlements to one exact feature key, such as `compute.max_clusters`." }, "required": false, - "description": "Optional workspace/scope context for the request. Carries a single workspace wire id (`ws_…`) today. Only needed for broad tokens — a workspace-owned token implies its workspace.", - "name": "akua-context", - "in": "header" + "description": "Filter entitlements to one exact feature key, such as `compute.max_clusters`.", + "name": "feature", + "in": "query" } ], "responses": { "200": { - "description": "List of order drafts", + "description": "Entitlement list", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/OrderDraftList" + "$ref": "#/components/schemas/EntitlementList" } } } @@ -26098,25 +42519,34 @@ } } }, - "/v1/order_drafts:workspaceList": { + "/v1/operations": { "get": { - "x-platform-visibility": "INTERNAL", + "x-platform-visibility": "PUBLIC", "x-platform-live": { "visibility": "INTERNAL", "transport": "convex", - "convexQuery": "orders.ui.listMyWorkspaceOrders" + "convexQuery": "operations.ui.listOperationsForWorkspaceForApi" }, - "operationId": "orderDrafts.listWorkspace", + "operationId": "operations.list", "tags": [ - "Order Drafts" + "Operations" ], - "summary": "List workspace order drafts", - "description": "Returns order drafts for offers in the selected workspace. Intended for dashboard live reads.", + "summary": "List operations", + "description": "Workspace-scoped list of long-running operations, newest first. Without filters returns every operation in the workspace; with `?owner_type=install&owner_id=` narrows to a single entity.\n\nState for in-flight operations is eventually consistent — may lag actual execution by a few seconds. State for completed operations (`done: true`) is immutable.", "security": [ { "BearerAuth": [] } ], + "x-platform-query-contracts": [ + { + "kind": "requires-together", + "fields": [ + "owner_type", + "owner_id" + ] + } + ], "parameters": [ { "schema": { @@ -26145,204 +42575,44 @@ { "schema": { "type": "string", - "minLength": 1, - "maxLength": 53, - "description": "Optional workspace/scope context for the request. Carries a single workspace wire id (`ws_…`) today. Only needed for broad tokens — a workspace-owned token implies its workspace.", - "example": "ws_j572abc123def456" - }, - "required": false, - "description": "Optional workspace/scope context for the request. Carries a single workspace wire id (`ws_…`) today. Only needed for broad tokens — a workspace-owned token implies its workspace.", - "name": "akua-context", - "in": "header" - } - ], - "responses": { - "200": { - "description": "List of workspace order drafts", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/OrderDraftList" - } - } - } - }, - "401": { - "description": "Unauthorized", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/ApiErrorResponse" - } - } - } - }, - "403": { - "description": "Forbidden", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/ApiErrorResponse" - } - } - } - } - } - } - }, - "/v1/order_drafts/{id}": { - "get": { - "x-platform-visibility": "PUBLIC", - "x-platform-live": { - "visibility": "INTERNAL", - "transport": "convex", - "convexQuery": "orders.ui.getMyOrderDraft" - }, - "operationId": "orderDrafts.get", - "tags": [ - "Order Drafts" - ], - "summary": "Get order draft details", - "description": "Returns the order draft row. The order draft’s own customer sees the full record including `field_values`; workspace members of the parent offer see the row with `field_values` omitted.", - "security": [ - { - "BearerAuth": [] - } - ], - "parameters": [ - { - "schema": { - "type": "string", - "minLength": 1, - "maxLength": 55, - "description": "Order draft ID", - "example": "odft_j572abc..." - }, - "required": true, - "description": "Order draft ID", - "name": "id", - "in": "path" - } - ], - "responses": { - "200": { - "description": "Order draft details", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/OrderDraft" - } - } - } - }, - "401": { - "description": "Unauthorized", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/ApiErrorResponse" - } - } - } - }, - "403": { - "description": "Forbidden", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/ApiErrorResponse" - } - } - } - }, - "404": { - "description": "Not found", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/ApiErrorResponse" - } - } - } - } - } - } - }, - "/v1/order_drafts/{id}:cancel": { - "post": { - "x-platform-visibility": "PUBLIC", - "operationId": "orderDrafts.cancel", - "tags": [ - "Order Drafts" - ], - "summary": "Cancel order draft", - "description": "Terminates an in-flight order draft, returning the updated record. Allowed for the order draft’s own customer or any member of the parent offer’s workspace. Idempotent — cancelling a terminated order draft returns it unchanged. Allocated cluster resources are released and any in-flight install workflow is terminated; previously-completed work is NOT undone.", - "security": [ - { - "BearerAuth": [] - } - ], - "parameters": [ - { - "schema": { - "type": "string", - "minLength": 1, - "maxLength": 55, - "description": "Order draft ID", - "example": "odft_j572abc..." + "enum": [ + "install", + "repository_change_request", + "repository", + "workspace", + "machine", + "cluster", + "package" + ] }, - "required": true, - "description": "Order draft ID", - "name": "id", - "in": "path" + "required": false, + "name": "owner_type", + "in": "query" }, { "schema": { "type": "string", - "minLength": 1, - "maxLength": 256, - "description": "The `etag` of the resource version the client last read. Required on writes when the resource exposes an `etag` field. Mismatch returns 409 `ABORTED` with the current etag in the error metadata.", - "example": "42" + "description": "Required when `owner_type` is set. Ignored otherwise." }, - "required": true, - "description": "The `etag` of the resource version the client last read. Required on writes when the resource exposes an `etag` field. Mismatch returns 409 `ABORTED` with the current etag in the error metadata.", - "name": "if-match", - "in": "header" + "required": false, + "description": "Required when `owner_type` is set. Ignored otherwise.", + "name": "owner_id", + "in": "query" } ], "responses": { "200": { - "description": "Order draft cancelled", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/OrderDraft" - } - } - } - }, - "401": { - "description": "Unauthorized", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/ApiErrorResponse" - } - } - } - }, - "403": { - "description": "Forbidden", + "description": "List of operations (without per-step detail)", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/ApiErrorResponse" + "$ref": "#/components/schemas/OperationList" } } } }, - "404": { - "description": "Not found", + "400": { + "description": "Bad request", "content": { "application/json": { "schema": { @@ -26351,8 +42621,8 @@ } } }, - "409": { - "description": "Conflict", + "401": { + "description": "Unauthorized", "content": { "application/json": { "schema": { @@ -26361,8 +42631,8 @@ } } }, - "422": { - "description": "Unprocessable entity", + "403": { + "description": "Forbidden", "content": { "application/json": { "schema": { @@ -26374,15 +42644,20 @@ } } }, - "/v1/order_drafts/{id}:claim": { - "post": { + "/v1/operations/{id}": { + "get": { "x-platform-visibility": "PUBLIC", - "operationId": "orderDrafts.claim", + "operationId": "operations.get", "tags": [ - "Order Drafts" + "Operations" ], - "summary": "Claim order draft", - "description": "Binds the calling authenticated user to an anonymous order draft using a one-time claim token (R13 + AIP-147 INPUT_ONLY).", + "x-platform-live": { + "visibility": "INTERNAL", + "transport": "convex", + "convexQuery": "operations.ui.getOperationWithStepsForApi" + }, + "summary": "Get operation details + steps", + "description": "Returns the operation row plus its per-step progress events. Clients poll this endpoint while `done` is false; when `done` flips true, `response` carries the typed result (`SUCCEEDED`) or `error.message` carries the failure reason. Prefer `POST /v1/operations/{id}:wait` for sync \"wait until done\" semantics — it long-polls server-side instead of asking the client to tight-poll.\n\nState for in-flight operations is eventually consistent — may lag actual execution by a few seconds. State for completed operations (`done: true`) is immutable.", "security": [ { "BearerAuth": [] @@ -26393,12 +42668,12 @@ "schema": { "type": "string", "minLength": 1, - "maxLength": 55, - "description": "Order draft ID", - "example": "odft_j572abc..." + "maxLength": 53, + "description": "Operation ID. Prefixed form `op_` is canonical; bare IDs accepted during transition.", + "example": "op_j572abc..." }, "required": true, - "description": "Order draft ID", + "description": "Operation ID. Prefixed form `op_` is canonical; bare IDs accepted during transition.", "name": "id", "in": "path" }, @@ -26406,32 +42681,23 @@ "schema": { "type": "string", "minLength": 1, - "maxLength": 256, - "description": "The `etag` of the resource version the client last read. Required on writes when the resource exposes an `etag` field. Mismatch returns 409 `ABORTED` with the current etag in the error metadata.", - "example": "42" + "maxLength": 53, + "description": "Optional workspace/scope context for the request. Carries a single workspace wire id (`ws_…`) today. Only needed for broad tokens — a workspace-owned token implies its workspace.", + "example": "ws_j572abc123def456" }, - "required": true, - "description": "The `etag` of the resource version the client last read. Required on writes when the resource exposes an `etag` field. Mismatch returns 409 `ABORTED` with the current etag in the error metadata.", - "name": "if-match", + "required": false, + "description": "Optional workspace/scope context for the request. Carries a single workspace wire id (`ws_…`) today. Only needed for broad tokens — a workspace-owned token implies its workspace.", + "name": "akua-context", "in": "header" } ], - "requestBody": { - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/ClaimOrderDraftBody" - } - } - } - }, "responses": { "200": { - "description": "Order draft claimed", + "description": "Operation details (with steps)", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/OrderDraft" + "$ref": "#/components/schemas/Operation" } } } @@ -26465,39 +42731,19 @@ } } } - }, - "409": { - "description": "Conflict", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/ApiErrorResponse" - } - } - } - }, - "422": { - "description": "Unprocessable entity", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/ApiErrorResponse" - } - } - } } } } }, - "/v1/order_drafts/{id}:selectWorkspace": { + "/v1/operations/{id}:wait": { "post": { "x-platform-visibility": "PUBLIC", - "operationId": "orderDrafts.selectWorkspace", + "operationId": "operations.wait", "tags": [ - "Order Drafts" + "Operations" ], - "summary": "Select order workspace", - "description": "Selects the customer workspace for an order draft, or creates a new workspace for the order. This advances the draft from workspace selection to compute allocation.", + "summary": "Wait for an operation to reach a terminal state", + "description": "Long-polls server-side until the operation reaches a terminal state (`SUCCEEDED`, `FAILED`, `CANCELLED`) or the timeout elapses. Returns the latest `Operation` either way — check `done` to distinguish.\n\nServer-side this is a live subscription on the operation row, not a polling loop, so the response fires within milliseconds of the workflow reaching its terminal state.\n\nState for in-flight operations is eventually consistent — may lag actual execution by a few seconds. State for completed operations (`done: true`) is immutable.", "security": [ { "BearerAuth": [] @@ -26508,45 +42754,35 @@ "schema": { "type": "string", "minLength": 1, - "maxLength": 55, - "description": "Order draft ID", - "example": "odft_j572abc..." + "maxLength": 53, + "description": "Operation ID. Prefixed form `op_` is canonical; bare IDs accepted during transition.", + "example": "op_j572abc..." }, "required": true, - "description": "Order draft ID", + "description": "Operation ID. Prefixed form `op_` is canonical; bare IDs accepted during transition.", "name": "id", "in": "path" }, { "schema": { - "type": "string", - "minLength": 1, - "maxLength": 256, - "description": "The `etag` of the resource version the client last read. Required on writes when the resource exposes an `etag` field. Mismatch returns 409 `ABORTED` with the current etag in the error metadata.", - "example": "42" + "type": "integer", + "minimum": 1, + "maximum": 60, + "description": "Max seconds to wait for the operation to reach a terminal state. Default 30, max 60." }, - "required": true, - "description": "The `etag` of the resource version the client last read. Required on writes when the resource exposes an `etag` field. Mismatch returns 409 `ABORTED` with the current etag in the error metadata.", - "name": "if-match", - "in": "header" + "required": false, + "description": "Max seconds to wait for the operation to reach a terminal state. Default 30, max 60.", + "name": "timeout", + "in": "query" } ], - "requestBody": { - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/SelectOrderDraftWorkspaceBody" - } - } - } - }, "responses": { "200": { - "description": "Workspace selected", + "description": "Operation in its latest known state (terminal or still running on timeout)", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/OrderDraft" + "$ref": "#/components/schemas/Operation" } } } @@ -26580,39 +42816,19 @@ } } } - }, - "409": { - "description": "Conflict", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/ApiErrorResponse" - } - } - } - }, - "422": { - "description": "Unprocessable entity", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/ApiErrorResponse" - } - } - } } } } }, - "/v1/order_drafts/{id}:submitConfiguration": { + "/v1/operations/{id}:cancel": { "post": { "x-platform-visibility": "PUBLIC", - "operationId": "orderDrafts.submitConfigure", + "operationId": "operations.cancel", "tags": [ - "Order Drafts" + "Operations" ], - "summary": "Submit configure values", - "description": "Persists the customer’s configure-form values on the order draft and advances it to the payment phase, returning the updated record. Values are validated against the package version’s schema.", + "summary": "Request operation cancellation", + "description": "Requests cancellation of an in-flight operation. Cancellation is asynchronous: successful requests return the current operation envelope while the worker drains the current step before settling into a terminal result. Replaying the request with the same Idempotency-Key is supported. If the operation has already reached a terminal state, cancellation is rejected with Unprocessable Entity.\n\nWhen accepted, the operation is not cancelled instantly; it transitions through the normal cancellation flow and may still report progress for a short time.", "security": [ { "BearerAuth": [] @@ -26623,12 +42839,12 @@ "schema": { "type": "string", "minLength": 1, - "maxLength": 55, - "description": "Order draft ID", - "example": "odft_j572abc..." + "maxLength": 53, + "description": "Operation ID. Prefixed form `op_` is canonical; bare IDs accepted during transition.", + "example": "op_j572abc..." }, "required": true, - "description": "Order draft ID", + "description": "Operation ID. Prefixed form `op_` is canonical; bare IDs accepted during transition.", "name": "id", "in": "path" }, @@ -26636,32 +42852,49 @@ "schema": { "type": "string", "minLength": 1, - "maxLength": 256, - "description": "The `etag` of the resource version the client last read. Required on writes when the resource exposes an `etag` field. Mismatch returns 409 `ABORTED` with the current etag in the error metadata.", - "example": "42" + "maxLength": 53, + "description": "Optional workspace/scope context for the request. Carries a single workspace wire id (`ws_…`) today. Only needed for broad tokens — a workspace-owned token implies its workspace.", + "example": "ws_j572abc123def456" }, - "required": true, - "description": "The `etag` of the resource version the client last read. Required on writes when the resource exposes an `etag` field. Mismatch returns 409 `ABORTED` with the current etag in the error metadata.", + "required": false, + "description": "Optional workspace/scope context for the request. Carries a single workspace wire id (`ws_…`) today. Only needed for broad tokens — a workspace-owned token implies its workspace.", + "name": "akua-context", + "in": "header" + }, + { + "schema": { + "type": "string", + "minLength": 1, + "maxLength": 64, + "description": "Optional caller-supplied idempotency key. Any non-empty key up to 64 characters is accepted. Endpoint-specific documentation describes how the key is used.", + "example": "create-prod-2026-05-07" + }, + "required": false, + "description": "Optional caller-supplied idempotency key. Any non-empty key up to 64 characters is accepted. Endpoint-specific documentation describes how the key is used.", + "name": "idempotency-key", + "in": "header" + }, + { + "schema": { + "type": "string", + "minLength": 1, + "maxLength": 64, + "description": "Optional optimistic concurrency token for clients that track the latest operation revision.", + "example": "WzQ1Njc=" + }, + "required": false, + "description": "Optional optimistic concurrency token for clients that track the latest operation revision.", "name": "if-match", "in": "header" } ], - "requestBody": { - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/SubmitConfigureOrderDraftBody" - } - } - } - }, "responses": { - "200": { - "description": "Configure submitted", + "202": { + "description": "Cancellation requested; operation transition is in progress", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/OrderDraft" + "$ref": "#/components/schemas/Operation" } } } @@ -26696,16 +42929,6 @@ } } }, - "409": { - "description": "Conflict", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/ApiErrorResponse" - } - } - } - }, "422": { "description": "Unprocessable entity", "content": { @@ -26719,60 +42942,81 @@ } } }, - "/v1/order_drafts/{id}:createWorkerBootstrap": { - "post": { - "x-platform-visibility": "PUBLIC", - "operationId": "orderDrafts.createWorkerBootstrap", + "/v1/installs:dashboardList": { + "get": { + "x-platform-visibility": "INTERNAL", + "x-platform-live": { + "visibility": "INTERNAL", + "transport": "convex", + "convexQuery": "install.listDashboardInstallsForApi" + }, + "operationId": "installs.listDashboard", "tags": [ - "Order Drafts" + "Installs" ], - "summary": "Create order draft worker bootstrap", - "description": "Creates a short-lived worker bootstrap token and renders command/cloud-init data for the cluster allocated to this order draft. Only valid while the draft is waiting for compute bootstrap.", + "summary": "List dashboard installs", + "description": "Returns extant install rows shaped for the dashboard deployments table. Deleted installs are excluded before pagination. Use `cluster` to limit results to one cluster.", "security": [ { "BearerAuth": [] } ], "parameters": [ + { + "schema": { + "type": "string", + "description": "Pagination cursor from a previous response's `next_cursor`." + }, + "required": false, + "description": "Pagination cursor from a previous response's `next_cursor`.", + "name": "cursor", + "in": "query" + }, + { + "schema": { + "type": "integer", + "minimum": 1, + "maximum": 100, + "default": 50, + "description": "Items per page (1-100, default 50)", + "example": 50 + }, + "required": false, + "description": "Items per page (1-100, default 50)", + "name": "limit", + "in": "query" + }, { "schema": { "type": "string", "minLength": 1, - "maxLength": 55, - "description": "Order draft ID", - "example": "odft_j572abc..." + "maxLength": 54 }, - "required": true, - "description": "Order draft ID", - "name": "id", - "in": "path" + "required": false, + "name": "cluster", + "in": "query" + }, + { + "schema": { + "type": "string", + "minLength": 1, + "maxLength": 53, + "description": "Optional workspace/scope context for the request. Carries a single workspace wire id (`ws_…`) today. Only needed for broad tokens — a workspace-owned token implies its workspace.", + "example": "ws_j572abc123def456" + }, + "required": false, + "description": "Optional workspace/scope context for the request. Carries a single workspace wire id (`ws_…`) today. Only needed for broad tokens — a workspace-owned token implies its workspace.", + "name": "akua-context", + "in": "header" } ], - "requestBody": { - "required": false, - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "ttl_seconds": { - "type": "integer", - "minimum": 60, - "maximum": 86400 - } - }, - "additionalProperties": false - } - } - } - }, "responses": { "200": { - "description": "Worker bootstrap data", + "description": "Dashboard install list", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/OrderDraftWorkerBootstrap" + "$ref": "#/components/schemas/DashboardInstallList" } } } @@ -26796,39 +43040,24 @@ } } } - }, - "404": { - "description": "Not found", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/ApiErrorResponse" - } - } - } - }, - "409": { - "description": "Conflict", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/ApiErrorResponse" - } - } - } } } } }, - "/v1/order_drafts/{id}/checkout_sessions": { - "post": { - "x-platform-visibility": "PUBLIC", - "operationId": "orderDrafts.createCheckoutSession", + "/v1/installs/{id}:dashboard": { + "get": { + "x-platform-visibility": "INTERNAL", + "x-platform-live": { + "visibility": "INTERNAL", + "transport": "convex", + "convexQuery": "install.getDashboardInstallForApi" + }, + "operationId": "installs.getDashboard", "tags": [ - "Order Drafts" + "Installs" ], - "summary": "Create order draft checkout session", - "description": "Creates a Stripe Checkout Session for the current order-draft payment revision, or returns the existing open session when it still has enough remaining lifetime. Stale sessions are expired and superseded before a replacement is created.", + "summary": "Get dashboard install detail", + "description": "Returns an install detail row shaped for the dashboard install pages.", "security": [ { "BearerAuth": [] @@ -26839,12 +43068,9 @@ "schema": { "type": "string", "minLength": 1, - "maxLength": 55, - "description": "Order draft ID", - "example": "odft_j572abc..." + "maxLength": 55 }, "required": true, - "description": "Order draft ID", "name": "id", "in": "path" }, @@ -26852,23 +43078,23 @@ "schema": { "type": "string", "minLength": 1, - "maxLength": 256, - "description": "The `etag` of the resource version the client last read. Required on writes when the resource exposes an `etag` field. Mismatch returns 409 `ABORTED` with the current etag in the error metadata.", - "example": "42" + "maxLength": 53, + "description": "Optional workspace/scope context for the request. Carries a single workspace wire id (`ws_…`) today. Only needed for broad tokens — a workspace-owned token implies its workspace.", + "example": "ws_j572abc123def456" }, - "required": true, - "description": "The `etag` of the resource version the client last read. Required on writes when the resource exposes an `etag` field. Mismatch returns 409 `ABORTED` with the current etag in the error metadata.", - "name": "if-match", + "required": false, + "description": "Optional workspace/scope context for the request. Carries a single workspace wire id (`ws_…`) today. Only needed for broad tokens — a workspace-owned token implies its workspace.", + "name": "akua-context", "in": "header" } ], "responses": { - "201": { - "description": "Checkout session created or reused", + "200": { + "description": "Dashboard install detail", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/OrderDraftCheckoutSession" + "$ref": "#/components/schemas/DashboardInstallDetail" } } } @@ -26902,47 +43128,24 @@ } } } - }, - "409": { - "description": "Conflict", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/ApiErrorResponse" - } - } - } - }, - "422": { - "description": "Unprocessable entity", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/ApiErrorResponse" - } - } - } - }, - "500": { - "description": "Internal server error", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/ApiErrorResponse" - } - } - } } } - }, + } + }, + "/v1/organizations/{organization_id}/managed_installs": { "get": { - "x-platform-visibility": "PUBLIC", - "operationId": "orderDrafts.listCheckoutSessions", + "x-platform-visibility": "INTERNAL", + "x-platform-live": { + "visibility": "INTERNAL", + "transport": "convex", + "convexQuery": "install.listManagedInstallsForApi" + }, + "operationId": "organizations.listManagedInstalls", "tags": [ - "Order Drafts" + "Organizations" ], - "summary": "List order draft checkout sessions", - "description": "Returns historical checkout session rows for the order draft (current and past) for resume/audit workflows.", + "summary": "List managed deployments", + "description": "Lists deployments in customer workspaces managed by the organization, ordered by managed workspace and then install creation time, both descending. Filtered pages can be empty or shorter than the requested limit while has_more is true; continue with next_cursor. Organization membership is required; inaccessible organizations are not disclosed.", "security": [ { "BearerAuth": [] @@ -26952,54 +43155,107 @@ { "schema": { "type": "string", - "minLength": 1, - "maxLength": 55, - "description": "Order draft ID", - "example": "odft_j572abc..." + "minLength": 1, + "maxLength": 54, + "description": "Organization ID.", + "example": "org_j572abc123def456" + }, + "required": true, + "description": "Organization ID.", + "name": "organization_id", + "in": "path" + }, + { + "schema": { + "type": "string", + "description": "Pagination cursor from a previous response's `next_cursor`." + }, + "required": false, + "description": "Pagination cursor from a previous response's `next_cursor`.", + "name": "cursor", + "in": "query" + }, + { + "schema": { + "type": "integer", + "minimum": 1, + "maximum": 100, + "default": 50, + "description": "Items per page (1-100, default 50)", + "example": 50 + }, + "required": false, + "description": "Items per page (1-100, default 50)", + "name": "limit", + "in": "query" + }, + { + "schema": { + "type": "string", + "minLength": 1, + "maxLength": 100 + }, + "required": false, + "name": "search", + "in": "query" + }, + { + "schema": { + "type": "string", + "enum": [ + "pending", + "rendering", + "syncing", + "healthy", + "degraded", + "failed", + "deleted" + ], + "description": "Install lifecycle state from the control plane perspective." }, - "required": true, - "description": "Order draft ID", - "name": "id", - "in": "path" + "required": false, + "description": "Install lifecycle state from the control plane perspective.", + "name": "status", + "in": "query" }, { "schema": { "type": "string", - "description": "Pagination cursor from a previous response's `next_cursor`." + "minLength": 1, + "maxLength": 128, + "pattern": "^(0|[1-9]\\d*)\\.(0|[1-9]\\d*)\\.(0|[1-9]\\d*)(?:-((?:0|[1-9]\\d*|[0-9A-Za-z-]*[A-Za-z-][0-9A-Za-z-]*)(?:\\.(?:0|[1-9]\\d*|[0-9A-Za-z-]*[A-Za-z-][0-9A-Za-z-]*))*))?(?:\\+([0-9A-Za-z-]+(?:\\.[0-9A-Za-z-]+)*))?$" }, "required": false, - "description": "Pagination cursor from a previous response's `next_cursor`.", - "name": "cursor", + "name": "version", "in": "query" }, { "schema": { - "type": "integer", - "minimum": 1, - "maximum": 100, - "default": 50, - "description": "Items per page (1-100, default 50)", - "example": 50 + "type": "string", + "enum": [ + "required", + "none", + "update_available" + ] }, "required": false, - "description": "Items per page (1-100, default 50)", - "name": "limit", + "name": "attention", "in": "query" } ], "responses": { "200": { - "description": "List of checkout sessions", + "description": "Managed deployment list", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/CheckoutSessionList" + "$ref": "#/components/schemas/ManagedInstallList" } } } }, - "401": { - "description": "Unauthorized", + "400": { + "description": "Bad request", "content": { "application/json": { "schema": { @@ -27008,8 +43264,8 @@ } } }, - "403": { - "description": "Forbidden", + "401": { + "description": "Unauthorized", "content": { "application/json": { "schema": { @@ -27031,15 +43287,20 @@ } } }, - "/v1/order_drafts/{id}/checkout_sessions/{chk_id}": { + "/v1/organizations/{organization_id}/managed_installs/{install_id}": { "get": { - "x-platform-visibility": "PUBLIC", - "operationId": "orderDrafts.getCheckoutSession", + "x-platform-visibility": "INTERNAL", + "x-platform-live": { + "visibility": "INTERNAL", + "transport": "convex", + "convexQuery": "install.getManagedInstallForApi" + }, + "operationId": "organizations.getManagedInstall", "tags": [ - "Order Drafts" + "Organizations" ], - "summary": "Get order draft checkout session", - "description": "Returns one historical checkout session by ID, including the current session state.", + "summary": "Get a managed deployment", + "description": "Returns one bounded deployment projection when its customer workspace is managed by the organization. Organization and deployment existence are not disclosed to non-members.", "security": [ { "BearerAuth": [] @@ -27050,34 +43311,36 @@ "schema": { "type": "string", "minLength": 1, - "maxLength": 55, - "description": "Order draft ID", - "example": "odft_j572abc..." + "maxLength": 54, + "description": "Organization ID.", + "example": "org_j572abc123def456" }, "required": true, - "description": "Order draft ID", - "name": "id", + "description": "Organization ID.", + "name": "organization_id", "in": "path" }, { "schema": { "type": "string", - "description": "Checkout session ID", - "example": "chk_abcdefghijk..." + "minLength": 1, + "maxLength": 55, + "description": "Install ID.", + "example": "inst_j572abc123def456" }, "required": true, - "description": "Checkout session ID", - "name": "chk_id", + "description": "Install ID.", + "name": "install_id", "in": "path" } ], "responses": { "200": { - "description": "Checkout session details", + "description": "Managed deployment detail", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/CheckoutSession" + "$ref": "#/components/schemas/ManagedInstall" } } } @@ -27092,16 +43355,6 @@ } } }, - "403": { - "description": "Forbidden", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/ApiErrorResponse" - } - } - } - }, "404": { "description": "Not found", "content": { @@ -27115,63 +43368,81 @@ } } }, - "/v1/orders/{order}/deliveries/{delivery}:removeDemoCleanup": { - "post": { - "x-platform-visibility": "ADMIN", - "operationId": "orderDrafts.removeDemoCleanup", + "/v1/installs:productAttention": { + "get": { + "x-platform-visibility": "INTERNAL", + "x-platform-live": { + "visibility": "INTERNAL", + "transport": "convex", + "convexQuery": "install.listProductAttentionForApi" + }, + "operationId": "installs.listProductAttention", "tags": [ - "Order Drafts" + "Installs" ], - "summary": "Remove demo cleanup after platform approval", - "description": "Removes scheduled cleanup from a non-billable demo/test order delivery after platform approval. This is an admin-only conversion hook; sellers and customers cannot remove cleanup unilaterally.", + "summary": "List Product attention installs", + "description": "Lists seller-visible degraded and failed installs for a Product, ordered by attention priority and observation time.", "security": [ { "BearerAuth": [] } ], "parameters": [ + { + "schema": { + "type": "string", + "description": "Pagination cursor from a previous response's `next_cursor`." + }, + "required": false, + "description": "Pagination cursor from a previous response's `next_cursor`.", + "name": "cursor", + "in": "query" + }, + { + "schema": { + "type": "integer", + "minimum": 1, + "maximum": 100, + "default": 50, + "description": "Items per page (1-100, default 50)", + "example": 50 + }, + "required": false, + "description": "Items per page (1-100, default 50)", + "name": "limit", + "in": "query" + }, { "schema": { "type": "string", "minLength": 1, - "maxLength": 54, - "description": "Committed order ID" + "maxLength": 55 }, "required": true, - "description": "Committed order ID", - "name": "order", - "in": "path" + "name": "product_id", + "in": "query" }, { "schema": { "type": "string", "minLength": 1, - "maxLength": 55, - "description": "Order delivery ID" + "maxLength": 53, + "description": "Optional workspace/scope context for the request. Carries a single workspace wire id (`ws_…`) today. Only needed for broad tokens — a workspace-owned token implies its workspace.", + "example": "ws_j572abc123def456" }, - "required": true, - "description": "Order delivery ID", - "name": "delivery", - "in": "path" + "required": false, + "description": "Optional workspace/scope context for the request. Carries a single workspace wire id (`ws_…`) today. Only needed for broad tokens — a workspace-owned token implies its workspace.", + "name": "akua-context", + "in": "header" } ], - "requestBody": { - "required": true, - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/RemoveDemoCleanupAfterPlatformApprovalBody" - } - } - } - }, "responses": { "200": { - "description": "Demo cleanup removed from the order and delivery", + "description": "Product attention installs", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/DemoCleanupRemoval" + "$ref": "#/components/schemas/ProductAttentionResponse" } } } @@ -27206,18 +43477,8 @@ } } }, - "409": { - "description": "Conflict", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/ApiErrorResponse" - } - } - } - }, - "422": { - "description": "Unprocessable entity", + "503": { + "description": "Service unavailable", "content": { "application/json": { "schema": { @@ -27229,20 +43490,20 @@ } } }, - "/v1/entitlements": { + "/v1/installs": { "get": { "x-platform-visibility": "PUBLIC", - "operationId": "entitlements.list", - "tags": [ - "Entitlements" - ], "x-platform-live": { - "visibility": "INTERNAL", + "visibility": "PUBLIC", "transport": "convex", - "convexQuery": "workspace.ui.listEffectiveEntitlementsForApi" + "convexQuery": "install.listInstallsForApi" }, - "summary": "List entitlements", - "description": "Returns active effective entitlements visible to the authenticated caller.", + "operationId": "installs.list", + "tags": [ + "Installs" + ], + "summary": "List installs", + "description": "Lists installs in the current workspace. With `product_id`, lists installs attributed to that product for product-owner support visibility, newest first.", "security": [ { "BearerAuth": [] @@ -27277,47 +43538,33 @@ "schema": { "type": "string", "minLength": 1, - "maxLength": 53, - "description": "Filter entitlements to one workspace.", - "example": "ws_j572abc123def456" - }, - "required": false, - "description": "Filter entitlements to one workspace.", - "name": "workspace", - "in": "query" - }, - { - "schema": { - "type": "string", - "minLength": 1, - "maxLength": 128, - "description": "Filter entitlements to one feature set, such as `compute`." + "maxLength": 55 }, "required": false, - "description": "Filter entitlements to one feature set, such as `compute`.", - "name": "feature_set", + "name": "product_id", "in": "query" }, { "schema": { "type": "string", "minLength": 1, - "maxLength": 256, - "description": "Filter entitlements to one exact feature key, such as `compute.max_clusters`." + "maxLength": 53, + "description": "Optional workspace/scope context for the request. Carries a single workspace wire id (`ws_…`) today. Only needed for broad tokens — a workspace-owned token implies its workspace.", + "example": "ws_j572abc123def456" }, "required": false, - "description": "Filter entitlements to one exact feature key, such as `compute.max_clusters`.", - "name": "feature", - "in": "query" + "description": "Optional workspace/scope context for the request. Carries a single workspace wire id (`ws_…`) today. Only needed for broad tokens — a workspace-owned token implies its workspace.", + "name": "akua-context", + "in": "header" } ], "responses": { "200": { - "description": "Entitlement list", + "description": "Installs list", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/EntitlementList" + "$ref": "#/components/schemas/InstallList" } } } @@ -27343,102 +43590,146 @@ } } } - } - }, - "/v1/operations": { - "get": { + }, + "post": { "x-platform-visibility": "PUBLIC", - "x-platform-live": { - "visibility": "INTERNAL", - "transport": "convex", - "convexQuery": "operations.ui.listOperationsForWorkspaceForApi" - }, - "operationId": "operations.list", + "operationId": "installs.create", "tags": [ - "Operations" + "Installs" ], - "summary": "List operations", - "description": "Workspace-scoped list of long-running operations, newest first. Without filters returns every operation in the workspace; with `?owner_type=install&owner_id=` narrows to a single entity.\n\nState for in-flight operations is eventually consistent — may lag actual execution by a few seconds. State for completed operations (`done: true`) is immutable.", + "summary": "Create install", + "description": "Creates a product-based or direct installation. Akua processes the installation in the background and returns an Operation envelope to poll for progress.", "security": [ { "BearerAuth": [] } ], - "x-platform-query-contracts": [ - { - "kind": "requires-together", - "fields": [ - "owner_type", - "owner_id" - ] - } - ], "parameters": [ { "schema": { "type": "string", - "description": "Pagination cursor from a previous response's `next_cursor`." + "minLength": 1, + "maxLength": 53, + "description": "Optional workspace/scope context for the request. Carries a single workspace wire id (`ws_…`) today. Only needed for broad tokens — a workspace-owned token implies its workspace.", + "example": "ws_j572abc123def456" }, "required": false, - "description": "Pagination cursor from a previous response's `next_cursor`.", - "name": "cursor", - "in": "query" + "description": "Optional workspace/scope context for the request. Carries a single workspace wire id (`ws_…`) today. Only needed for broad tokens — a workspace-owned token implies its workspace.", + "name": "akua-context", + "in": "header" }, { "schema": { - "type": "integer", - "minimum": 1, - "maximum": 100, - "default": 50, - "description": "Items per page (1-100, default 50)", - "example": 50 + "type": "string", + "minLength": 1, + "maxLength": 64, + "description": "Optional caller-supplied idempotency key. Any non-empty key up to 64 characters is accepted. Endpoint-specific documentation describes how the key is used.", + "example": "create-prod-2026-05-07" }, "required": false, - "description": "Items per page (1-100, default 50)", - "name": "limit", - "in": "query" + "description": "Optional caller-supplied idempotency key. Any non-empty key up to 64 characters is accepted. Endpoint-specific documentation describes how the key is used.", + "name": "idempotency-key", + "in": "header" + } + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/CreateInstallBody" + } + } + } + }, + "responses": { + "202": { + "description": "Install workflow started", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Operation" + } + } + } + }, + "401": { + "description": "Unauthorized", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } + } + } }, + "403": { + "description": "Forbidden", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } + } + } + } + } + } + }, + "/v1/installs/{id}": { + "get": { + "x-platform-visibility": "PUBLIC", + "operationId": "installs.get", + "tags": [ + "Installs" + ], + "summary": "Get install details", + "description": "Returns current install metadata.", + "security": [ + { + "BearerAuth": [] + } + ], + "parameters": [ { "schema": { "type": "string", - "enum": [ - "install", - "repository_change_request", - "repository", - "workspace", - "machine", - "cluster", - "package" - ] + "minLength": 1, + "maxLength": 55, + "description": "Install ID", + "example": "inst_j572abc123def456" }, - "required": false, - "name": "owner_type", - "in": "query" + "required": true, + "description": "Install ID", + "name": "id", + "in": "path" }, { "schema": { "type": "string", - "description": "Required when `owner_type` is set. Ignored otherwise." + "minLength": 1, + "maxLength": 53, + "description": "Optional workspace/scope context for the request. Carries a single workspace wire id (`ws_…`) today. Only needed for broad tokens — a workspace-owned token implies its workspace.", + "example": "ws_j572abc123def456" }, "required": false, - "description": "Required when `owner_type` is set. Ignored otherwise.", - "name": "owner_id", - "in": "query" + "description": "Optional workspace/scope context for the request. Carries a single workspace wire id (`ws_…`) today. Only needed for broad tokens — a workspace-owned token implies its workspace.", + "name": "akua-context", + "in": "header" } ], "responses": { "200": { - "description": "List of operations (without per-step detail)", + "description": "Install details", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/OperationList" + "$ref": "#/components/schemas/Install" } } } }, - "400": { - "description": "Bad request", + "401": { + "description": "Unauthorized", "content": { "application/json": { "schema": { @@ -27447,8 +43738,8 @@ } } }, - "401": { - "description": "Unauthorized", + "403": { + "description": "Forbidden", "content": { "application/json": { "schema": { @@ -27457,8 +43748,8 @@ } } }, - "403": { - "description": "Forbidden", + "404": { + "description": "Not found", "content": { "application/json": { "schema": { @@ -27468,22 +43759,15 @@ } } } - } - }, - "/v1/operations/{id}": { - "get": { + }, + "delete": { "x-platform-visibility": "PUBLIC", - "operationId": "operations.get", + "operationId": "installs.delete", "tags": [ - "Operations" + "Installs" ], - "x-platform-live": { - "visibility": "INTERNAL", - "transport": "convex", - "convexQuery": "operations.ui.getOperationWithStepsForApi" - }, - "summary": "Get operation details + steps", - "description": "Returns the operation row plus its per-step progress events. Clients poll this endpoint while `done` is false; when `done` flips true, `response` carries the typed result (`SUCCEEDED`) or `error.message` carries the failure reason. Prefer `POST /v1/operations/{id}:wait` for sync \"wait until done\" semantics — it long-polls server-side instead of asking the client to tight-poll.\n\nState for in-flight operations is eventually consistent — may lag actual execution by a few seconds. State for completed operations (`done: true`) is immutable.", + "summary": "Delete install", + "description": "Deletes an install and cascades resource cleanup asynchronously. Returns an Operation envelope to poll for progress.", "security": [ { "BearerAuth": [] @@ -27494,12 +43778,12 @@ "schema": { "type": "string", "minLength": 1, - "maxLength": 53, - "description": "Operation ID. Prefixed form `op_` is canonical; bare IDs accepted during transition.", - "example": "op_j572abc..." + "maxLength": 55, + "description": "Install ID", + "example": "inst_j572abc123def456" }, "required": true, - "description": "Operation ID. Prefixed form `op_` is canonical; bare IDs accepted during transition.", + "description": "Install ID", "name": "id", "in": "path" }, @@ -27515,11 +43799,37 @@ "description": "Optional workspace/scope context for the request. Carries a single workspace wire id (`ws_…`) today. Only needed for broad tokens — a workspace-owned token implies its workspace.", "name": "akua-context", "in": "header" + }, + { + "schema": { + "type": "string", + "minLength": 1, + "maxLength": 64, + "description": "Optional caller-supplied idempotency key. Any non-empty key up to 64 characters is accepted. Endpoint-specific documentation describes how the key is used.", + "example": "create-prod-2026-05-07" + }, + "required": false, + "description": "Optional caller-supplied idempotency key. Any non-empty key up to 64 characters is accepted. Endpoint-specific documentation describes how the key is used.", + "name": "idempotency-key", + "in": "header" + }, + { + "schema": { + "type": "string", + "minLength": 1, + "maxLength": 256, + "description": "The `etag` of the resource version the client last read. Required on writes when the resource exposes an `etag` field. Mismatch returns 409 `ABORTED` with the current etag in the error metadata.", + "example": "42" + }, + "required": true, + "description": "The `etag` of the resource version the client last read. Required on writes when the resource exposes an `etag` field. Mismatch returns 409 `ABORTED` with the current etag in the error metadata.", + "name": "if-match", + "in": "header" } ], "responses": { - "200": { - "description": "Operation details (with steps)", + "202": { + "description": "Delete workflow started", "content": { "application/json": { "schema": { @@ -27548,8 +43858,8 @@ } } }, - "404": { - "description": "Not found", + "409": { + "description": "Conflict", "content": { "application/json": { "schema": { @@ -27561,15 +43871,20 @@ } } }, - "/v1/operations/{id}:wait": { - "post": { - "x-platform-visibility": "PUBLIC", - "operationId": "operations.wait", + "/v1/installs/{id}/domain_settings": { + "get": { + "x-platform-visibility": "INTERNAL", + "x-platform-live": { + "visibility": "INTERNAL", + "transport": "convex", + "convexQuery": "cloudflare.ui.getInstallDomainSettingsForApi" + }, + "operationId": "installs.getDomainSettings", "tags": [ - "Operations" + "Installs" ], - "summary": "Wait for an operation to reach a terminal state", - "description": "Long-polls server-side until the operation reaches a terminal state (`SUCCEEDED`, `FAILED`, `CANCELLED`) or the timeout elapses. Returns the latest `Operation` either way — check `done` to distinguish.\n\nServer-side this is a live subscription on the operation row, not a polling loop, so the response fires within milliseconds of the workflow reaching its terminal state.\n\nState for in-flight operations is eventually consistent — may lag actual execution by a few seconds. State for completed operations (`done: true`) is immutable.", + "summary": "Get install domain settings", + "description": "Returns dashboard domain-routing settings for one install.", "security": [ { "BearerAuth": [] @@ -27580,35 +43895,22 @@ "schema": { "type": "string", "minLength": 1, - "maxLength": 53, - "description": "Operation ID. Prefixed form `op_` is canonical; bare IDs accepted during transition.", - "example": "op_j572abc..." + "maxLength": 55, + "description": "Install ID" }, "required": true, - "description": "Operation ID. Prefixed form `op_` is canonical; bare IDs accepted during transition.", + "description": "Install ID", "name": "id", "in": "path" - }, - { - "schema": { - "type": "integer", - "minimum": 1, - "maximum": 60, - "description": "Max seconds to wait for the operation to reach a terminal state. Default 30, max 60." - }, - "required": false, - "description": "Max seconds to wait for the operation to reach a terminal state. Default 30, max 60.", - "name": "timeout", - "in": "query" } ], "responses": { "200": { - "description": "Operation in its latest known state (terminal or still running on timeout)", + "description": "Install domain settings", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/Operation" + "$ref": "#/components/schemas/InstallDomainSettings" } } } @@ -27646,15 +43948,15 @@ } } }, - "/v1/operations/{id}:cancel": { + "/v1/installs/{id}:update": { "post": { "x-platform-visibility": "PUBLIC", - "operationId": "operations.cancel", + "operationId": "installs.updateVersion", "tags": [ - "Operations" + "Installs" ], - "summary": "Request operation cancellation", - "description": "Requests cancellation of an in-flight operation. Cancellation is asynchronous: successful requests return the current operation envelope while the worker drains the current step before settling into a terminal result. Replaying the request with the same Idempotency-Key is supported. If the operation has already reached a terminal state, cancellation is rejected with Unprocessable Entity.\n\nWhen accepted, the operation is not cancelled instantly; it transitions through the normal cancellation flow and may still report progress for a short time.", + "summary": "Update install version", + "description": "Requests a selected PackageVersion from the same Package. The current version changes only after the new git-backed render deploys successfully.", "security": [ { "BearerAuth": [] @@ -27665,12 +43967,9 @@ "schema": { "type": "string", "minLength": 1, - "maxLength": 53, - "description": "Operation ID. Prefixed form `op_` is canonical; bare IDs accepted during transition.", - "example": "op_j572abc..." + "maxLength": 55 }, "required": true, - "description": "Operation ID. Prefixed form `op_` is canonical; bare IDs accepted during transition.", "name": "id", "in": "path" }, @@ -27691,13 +43990,13 @@ "schema": { "type": "string", "minLength": 1, - "maxLength": 64, - "description": "Caller-supplied idempotency key. Repeated requests with the same key return the existing resource instead of creating a duplicate. Safe to retry after a timed-out or interrupted request.", - "example": "create-prod-2026-05-07" + "maxLength": 256, + "description": "The `etag` of the resource version the client last read. Required on writes when the resource exposes an `etag` field. Mismatch returns 409 `ABORTED` with the current etag in the error metadata.", + "example": "42" }, - "required": false, - "description": "Caller-supplied idempotency key. Repeated requests with the same key return the existing resource instead of creating a duplicate. Safe to retry after a timed-out or interrupted request.", - "name": "idempotency-key", + "required": true, + "description": "The `etag` of the resource version the client last read. Required on writes when the resource exposes an `etag` field. Mismatch returns 409 `ABORTED` with the current etag in the error metadata.", + "name": "if-match", "in": "header" }, { @@ -27705,22 +44004,32 @@ "type": "string", "minLength": 1, "maxLength": 64, - "description": "Optional optimistic concurrency token for clients that track the latest operation revision.", - "example": "WzQ1Njc=" + "description": "Required caller-supplied idempotency key. Any non-empty key up to 64 characters is accepted. Endpoint-specific documentation describes how the key is used.", + "example": "create-prod-2026-05-07" }, - "required": false, - "description": "Optional optimistic concurrency token for clients that track the latest operation revision.", - "name": "if-match", + "required": true, + "description": "Required caller-supplied idempotency key. Any non-empty key up to 64 characters is accepted. Endpoint-specific documentation describes how the key is used.", + "name": "idempotency-key", "in": "header" } - ], + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/UpdateInstallVersionBody" + } + } + } + }, "responses": { "202": { - "description": "Cancellation requested; operation transition is in progress", + "description": "Version update render accepted", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/Operation" + "$ref": "#/components/schemas/InstallLifecycleMutation" } } } @@ -27755,8 +44064,8 @@ } } }, - "422": { - "description": "Unprocessable entity", + "409": { + "description": "Conflict", "content": { "application/json": { "schema": { @@ -27768,20 +44077,15 @@ } } }, - "/v1/installs:dashboardList": { - "get": { - "x-platform-visibility": "INTERNAL", - "x-platform-live": { - "visibility": "INTERNAL", - "transport": "convex", - "convexQuery": "install.listDashboardInstallsForApi" - }, - "operationId": "installs.listDashboard", + "/v1/installs/{id}:restore": { + "post": { + "x-platform-visibility": "PUBLIC", + "operationId": "installs.restore", "tags": [ "Installs" ], - "summary": "List dashboard installs", - "description": "Returns standalone install rows shaped for the dashboard applications table.", + "summary": "Restore install render", + "description": "Restores a prior successful same-Package render by copying its git tree into a new forward commit. Existing git history is never rewritten.", "security": [ { "BearerAuth": [] @@ -27791,26 +44095,12 @@ { "schema": { "type": "string", - "description": "Pagination cursor from a previous response's `next_cursor`." - }, - "required": false, - "description": "Pagination cursor from a previous response's `next_cursor`.", - "name": "cursor", - "in": "query" - }, - { - "schema": { - "type": "integer", - "minimum": 1, - "maximum": 100, - "default": 50, - "description": "Items per page (1-100, default 50)", - "example": 50 + "minLength": 1, + "maxLength": 55 }, - "required": false, - "description": "Items per page (1-100, default 50)", - "name": "limit", - "in": "query" + "required": true, + "name": "id", + "in": "path" }, { "schema": { @@ -27824,93 +44114,51 @@ "description": "Optional workspace/scope context for the request. Carries a single workspace wire id (`ws_…`) today. Only needed for broad tokens — a workspace-owned token implies its workspace.", "name": "akua-context", "in": "header" - } - ], - "responses": { - "200": { - "description": "Dashboard install list", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/DashboardInstallList" - } - } - } - }, - "401": { - "description": "Unauthorized", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/ApiErrorResponse" - } - } - } }, - "403": { - "description": "Forbidden", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/ApiErrorResponse" - } - } - } - } - } - } - }, - "/v1/installs/{id}:dashboard": { - "get": { - "x-platform-visibility": "INTERNAL", - "x-platform-live": { - "visibility": "INTERNAL", - "transport": "convex", - "convexQuery": "install.getDashboardInstallForApi" - }, - "operationId": "installs.getDashboard", - "tags": [ - "Installs" - ], - "summary": "Get dashboard install detail", - "description": "Returns an install detail row shaped for the dashboard install pages.", - "security": [ - { - "BearerAuth": [] - } - ], - "parameters": [ { "schema": { "type": "string", "minLength": 1, - "maxLength": 55 + "maxLength": 256, + "description": "The `etag` of the resource version the client last read. Required on writes when the resource exposes an `etag` field. Mismatch returns 409 `ABORTED` with the current etag in the error metadata.", + "example": "42" }, "required": true, - "name": "id", - "in": "path" + "description": "The `etag` of the resource version the client last read. Required on writes when the resource exposes an `etag` field. Mismatch returns 409 `ABORTED` with the current etag in the error metadata.", + "name": "if-match", + "in": "header" }, { "schema": { "type": "string", "minLength": 1, - "maxLength": 53, - "description": "Optional workspace/scope context for the request. Carries a single workspace wire id (`ws_…`) today. Only needed for broad tokens — a workspace-owned token implies its workspace.", - "example": "ws_j572abc123def456" + "maxLength": 64, + "description": "Required caller-supplied idempotency key. Any non-empty key up to 64 characters is accepted. Endpoint-specific documentation describes how the key is used.", + "example": "create-prod-2026-05-07" }, - "required": false, - "description": "Optional workspace/scope context for the request. Carries a single workspace wire id (`ws_…`) today. Only needed for broad tokens — a workspace-owned token implies its workspace.", - "name": "akua-context", + "required": true, + "description": "Required caller-supplied idempotency key. Any non-empty key up to 64 characters is accepted. Endpoint-specific documentation describes how the key is used.", + "name": "idempotency-key", "in": "header" } ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/RestoreInstallBody" + } + } + } + }, "responses": { - "200": { - "description": "Dashboard install detail", + "202": { + "description": "Restore render accepted", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/DashboardInstallDetail" + "$ref": "#/components/schemas/InstallLifecycleMutation" } } } @@ -27944,24 +44192,29 @@ } } } + }, + "409": { + "description": "Conflict", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } + } + } } } } }, - "/v1/installs": { - "get": { + "/v1/installs/{id}/automatic_updates": { + "patch": { "x-platform-visibility": "PUBLIC", - "x-platform-live": { - "visibility": "PUBLIC", - "transport": "convex", - "convexQuery": "install.listInstallsForApi" - }, - "operationId": "installs.list", + "operationId": "installs.setAutomaticUpdates", "tags": [ "Installs" ], - "summary": "List installs", - "description": "Lists installs in the current workspace. With `product_id`, lists installs attributed to that product for product-owner support visibility.", + "summary": "Set automatic install updates", + "description": "Enables or disables automatic PackageVersion updates for one install.", "security": [ { "BearerAuth": [] @@ -27971,58 +44224,70 @@ { "schema": { "type": "string", - "description": "Pagination cursor from a previous response's `next_cursor`." + "minLength": 1, + "maxLength": 55 }, - "required": false, - "description": "Pagination cursor from a previous response's `next_cursor`.", - "name": "cursor", - "in": "query" + "required": true, + "name": "id", + "in": "path" }, { "schema": { - "type": "integer", - "minimum": 1, - "maximum": 100, - "default": 50, - "description": "Items per page (1-100, default 50)", - "example": 50 + "type": "string", + "minLength": 1, + "maxLength": 53, + "description": "Optional workspace/scope context for the request. Carries a single workspace wire id (`ws_…`) today. Only needed for broad tokens — a workspace-owned token implies its workspace.", + "example": "ws_j572abc123def456" }, "required": false, - "description": "Items per page (1-100, default 50)", - "name": "limit", - "in": "query" + "description": "Optional workspace/scope context for the request. Carries a single workspace wire id (`ws_…`) today. Only needed for broad tokens — a workspace-owned token implies its workspace.", + "name": "akua-context", + "in": "header" }, { "schema": { "type": "string", "minLength": 1, - "maxLength": 55 + "maxLength": 256, + "description": "The `etag` of the resource version the client last read. Required on writes when the resource exposes an `etag` field. Mismatch returns 409 `ABORTED` with the current etag in the error metadata.", + "example": "42" }, - "required": false, - "name": "product_id", - "in": "query" + "required": true, + "description": "The `etag` of the resource version the client last read. Required on writes when the resource exposes an `etag` field. Mismatch returns 409 `ABORTED` with the current etag in the error metadata.", + "name": "if-match", + "in": "header" }, { "schema": { "type": "string", "minLength": 1, - "maxLength": 53, - "description": "Optional workspace/scope context for the request. Carries a single workspace wire id (`ws_…`) today. Only needed for broad tokens — a workspace-owned token implies its workspace.", - "example": "ws_j572abc123def456" + "maxLength": 64, + "description": "Required caller-supplied idempotency key. Any non-empty key up to 64 characters is accepted. Endpoint-specific documentation describes how the key is used.", + "example": "create-prod-2026-05-07" }, - "required": false, - "description": "Optional workspace/scope context for the request. Carries a single workspace wire id (`ws_…`) today. Only needed for broad tokens — a workspace-owned token implies its workspace.", - "name": "akua-context", + "required": true, + "description": "Required caller-supplied idempotency key. Any non-empty key up to 64 characters is accepted. Endpoint-specific documentation describes how the key is used.", + "name": "idempotency-key", "in": "header" } ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/SetInstallAutomaticUpdatesBody" + } + } + } + }, "responses": { "200": { - "description": "Installs list", + "description": "Automatic-update policy updated", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/InstallList" + "$ref": "#/components/schemas/InstallLifecycleMutation" } } } @@ -28046,23 +44311,58 @@ } } } + }, + "404": { + "description": "Not found", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } + } + } + }, + "409": { + "description": "Conflict", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } + } + } } } - }, + } + }, + "/v1/installs/{id}/renders": { "post": { "x-platform-visibility": "PUBLIC", - "operationId": "installs.create", + "operationId": "installs.createRender", "tags": [ "Installs" ], - "summary": "Create install", - "description": "Creates a product install via a long-running saga that may run for several minutes. Returns an Operation envelope to poll for progress.", + "summary": "Create install render", + "description": "Starts a render attempt and records the resulting render artifact metadata.", "security": [ { "BearerAuth": [] } ], "parameters": [ + { + "schema": { + "type": "string", + "minLength": 1, + "maxLength": 55, + "description": "Install ID", + "example": "inst_j572abc123def456" + }, + "required": true, + "description": "Install ID", + "name": "id", + "in": "path" + }, { "schema": { "type": "string", @@ -28081,11 +44381,11 @@ "type": "string", "minLength": 1, "maxLength": 64, - "description": "Caller-supplied idempotency key. Repeated requests with the same key return the existing resource instead of creating a duplicate. Safe to retry after a timed-out or interrupted request.", + "description": "Optional caller-supplied idempotency key. Any non-empty key up to 64 characters is accepted. Endpoint-specific documentation describes how the key is used.", "example": "create-prod-2026-05-07" }, "required": false, - "description": "Caller-supplied idempotency key. Repeated requests with the same key return the existing resource instead of creating a duplicate. Safe to retry after a timed-out or interrupted request.", + "description": "Optional caller-supplied idempotency key. Any non-empty key up to 64 characters is accepted. Endpoint-specific documentation describes how the key is used.", "name": "idempotency-key", "in": "header" } @@ -28094,18 +44394,18 @@ "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/CreateInstallBody" + "$ref": "#/components/schemas/CreateInstallRenderBody" } } } }, "responses": { - "202": { - "description": "Install workflow started", + "201": { + "description": "Render artifact created", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/Operation" + "$ref": "#/components/schemas/InstallRender" } } } @@ -28129,19 +44429,37 @@ } } } + }, + "404": { + "description": "Not found", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } + } + } + }, + "409": { + "description": "Conflict", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } + } + } } } - } - }, - "/v1/installs/{id}": { + }, "get": { "x-platform-visibility": "PUBLIC", - "operationId": "installs.get", + "operationId": "installs.listRenders", "tags": [ "Installs" ], - "summary": "Get install details", - "description": "Returns current install metadata.", + "summary": "List install renders", + "description": "Lists render artifacts for an install.", "security": [ { "BearerAuth": [] @@ -28161,6 +44479,30 @@ "name": "id", "in": "path" }, + { + "schema": { + "type": "string", + "description": "Pagination cursor from a previous response's `next_cursor`." + }, + "required": false, + "description": "Pagination cursor from a previous response's `next_cursor`.", + "name": "cursor", + "in": "query" + }, + { + "schema": { + "type": "integer", + "minimum": 1, + "maximum": 100, + "default": 50, + "description": "Items per page (1-100, default 50)", + "example": 50 + }, + "required": false, + "description": "Items per page (1-100, default 50)", + "name": "limit", + "in": "query" + }, { "schema": { "type": "string", @@ -28177,11 +44519,11 @@ ], "responses": { "200": { - "description": "Install details", + "description": "Install renders", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/Install" + "$ref": "#/components/schemas/InstallRenderList" } } } @@ -28217,15 +44559,17 @@ } } } - }, - "delete": { - "x-platform-visibility": "PUBLIC", - "operationId": "installs.delete", + } + }, + "/v1/organizations/{organization_id}/managed_installs/{install_id}:update": { + "post": { + "x-platform-visibility": "INTERNAL", + "operationId": "organizations.updateManagedInstallVersion", "tags": [ - "Installs" + "Organizations" ], - "summary": "Delete install", - "description": "Deletes an install and cascades resource cleanup asynchronously. Returns an Operation envelope to poll for progress.", + "summary": "Update a managed deployment version", + "description": "Requests a PackageVersion update after atomically verifying that the deployment is currently managed by the selected organization.", "security": [ { "BearerAuth": [] @@ -28236,62 +44580,66 @@ "schema": { "type": "string", "minLength": 1, - "maxLength": 55, - "description": "Install ID", - "example": "inst_j572abc123def456" + "maxLength": 54 }, "required": true, - "description": "Install ID", - "name": "id", + "name": "organization_id", "in": "path" }, { "schema": { "type": "string", "minLength": 1, - "maxLength": 53, - "description": "Optional workspace/scope context for the request. Carries a single workspace wire id (`ws_…`) today. Only needed for broad tokens — a workspace-owned token implies its workspace.", - "example": "ws_j572abc123def456" + "maxLength": 55 }, - "required": false, - "description": "Optional workspace/scope context for the request. Carries a single workspace wire id (`ws_…`) today. Only needed for broad tokens — a workspace-owned token implies its workspace.", - "name": "akua-context", - "in": "header" + "required": true, + "name": "install_id", + "in": "path" }, { "schema": { "type": "string", "minLength": 1, - "maxLength": 64, - "description": "Caller-supplied idempotency key. Repeated requests with the same key return the existing resource instead of creating a duplicate. Safe to retry after a timed-out or interrupted request.", - "example": "create-prod-2026-05-07" + "maxLength": 256, + "description": "The `etag` of the resource version the client last read. Required on writes when the resource exposes an `etag` field. Mismatch returns 409 `ABORTED` with the current etag in the error metadata.", + "example": "42" }, - "required": false, - "description": "Caller-supplied idempotency key. Repeated requests with the same key return the existing resource instead of creating a duplicate. Safe to retry after a timed-out or interrupted request.", - "name": "idempotency-key", + "required": true, + "description": "The `etag` of the resource version the client last read. Required on writes when the resource exposes an `etag` field. Mismatch returns 409 `ABORTED` with the current etag in the error metadata.", + "name": "if-match", "in": "header" }, { "schema": { "type": "string", "minLength": 1, - "maxLength": 256, - "description": "The `etag` of the resource version the client last read. Required on writes when the resource exposes an `etag` field. Mismatch returns 409 `ABORTED` with the current etag in the error metadata.", - "example": "42" + "maxLength": 64, + "description": "Required caller-supplied idempotency key. Any non-empty key up to 64 characters is accepted. Endpoint-specific documentation describes how the key is used.", + "example": "create-prod-2026-05-07" }, "required": true, - "description": "The `etag` of the resource version the client last read. Required on writes when the resource exposes an `etag` field. Mismatch returns 409 `ABORTED` with the current etag in the error metadata.", - "name": "if-match", + "description": "Required caller-supplied idempotency key. Any non-empty key up to 64 characters is accepted. Endpoint-specific documentation describes how the key is used.", + "name": "idempotency-key", "in": "header" } ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/UpdateInstallVersionBody" + } + } + } + }, "responses": { "202": { - "description": "Delete workflow started", + "description": "Managed deployment version update accepted", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/Operation" + "$ref": "#/components/schemas/InstallLifecycleMutation" } } } @@ -28306,8 +44654,8 @@ } } }, - "403": { - "description": "Forbidden", + "404": { + "description": "Not found", "content": { "application/json": { "schema": { @@ -28329,20 +44677,15 @@ } } }, - "/v1/installs/{id}/domain_settings": { - "get": { + "/v1/organizations/{organization_id}/managed_installs/{install_id}:restore": { + "post": { "x-platform-visibility": "INTERNAL", - "x-platform-live": { - "visibility": "INTERNAL", - "transport": "convex", - "convexQuery": "cloudflare.ui.getInstallDomainSettingsForApi" - }, - "operationId": "installs.getDomainSettings", + "operationId": "organizations.restoreManagedInstall", "tags": [ - "Installs" + "Organizations" ], - "summary": "Get install domain settings", - "description": "Returns dashboard domain-routing settings for one install.", + "summary": "Restore a managed deployment render", + "description": "Restores a prior successful render after atomically verifying that the deployment is currently managed by the selected organization.", "security": [ { "BearerAuth": [] @@ -28353,22 +44696,66 @@ "schema": { "type": "string", "minLength": 1, - "maxLength": 55, - "description": "Install ID" + "maxLength": 54 }, "required": true, - "description": "Install ID", - "name": "id", + "name": "organization_id", + "in": "path" + }, + { + "schema": { + "type": "string", + "minLength": 1, + "maxLength": 55 + }, + "required": true, + "name": "install_id", "in": "path" + }, + { + "schema": { + "type": "string", + "minLength": 1, + "maxLength": 256, + "description": "The `etag` of the resource version the client last read. Required on writes when the resource exposes an `etag` field. Mismatch returns 409 `ABORTED` with the current etag in the error metadata.", + "example": "42" + }, + "required": true, + "description": "The `etag` of the resource version the client last read. Required on writes when the resource exposes an `etag` field. Mismatch returns 409 `ABORTED` with the current etag in the error metadata.", + "name": "if-match", + "in": "header" + }, + { + "schema": { + "type": "string", + "minLength": 1, + "maxLength": 64, + "description": "Required caller-supplied idempotency key. Any non-empty key up to 64 characters is accepted. Endpoint-specific documentation describes how the key is used.", + "example": "create-prod-2026-05-07" + }, + "required": true, + "description": "Required caller-supplied idempotency key. Any non-empty key up to 64 characters is accepted. Endpoint-specific documentation describes how the key is used.", + "name": "idempotency-key", + "in": "header" } ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/RestoreInstallBody" + } + } + } + }, "responses": { - "200": { - "description": "Install domain settings", + "202": { + "description": "Managed deployment restore accepted", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/InstallDomainSettings" + "$ref": "#/components/schemas/InstallLifecycleMutation" } } } @@ -28383,8 +44770,8 @@ } } }, - "403": { - "description": "Forbidden", + "404": { + "description": "Not found", "content": { "application/json": { "schema": { @@ -28393,8 +44780,8 @@ } } }, - "404": { - "description": "Not found", + "409": { + "description": "Conflict", "content": { "application/json": { "schema": { @@ -28406,15 +44793,15 @@ } } }, - "/v1/installs/{id}/renders": { - "post": { - "x-platform-visibility": "PUBLIC", - "operationId": "installs.createRender", + "/v1/organizations/{organization_id}/managed_installs/{install_id}/automatic_updates": { + "patch": { + "x-platform-visibility": "INTERNAL", + "operationId": "organizations.setManagedInstallAutomaticUpdates", "tags": [ - "Installs" + "Organizations" ], - "summary": "Create install render", - "description": "Starts a render attempt and records the resulting render artifact metadata.", + "summary": "Set managed deployment automatic updates", + "description": "Enables or disables automatic updates after atomically verifying that the deployment is currently managed by the selected organization.", "security": [ { "BearerAuth": [] @@ -28425,26 +44812,33 @@ "schema": { "type": "string", "minLength": 1, - "maxLength": 55, - "description": "Install ID", - "example": "inst_j572abc123def456" + "maxLength": 54 }, "required": true, - "description": "Install ID", - "name": "id", + "name": "organization_id", "in": "path" }, { "schema": { "type": "string", "minLength": 1, - "maxLength": 53, - "description": "Optional workspace/scope context for the request. Carries a single workspace wire id (`ws_…`) today. Only needed for broad tokens — a workspace-owned token implies its workspace.", - "example": "ws_j572abc123def456" + "maxLength": 55 }, - "required": false, - "description": "Optional workspace/scope context for the request. Carries a single workspace wire id (`ws_…`) today. Only needed for broad tokens — a workspace-owned token implies its workspace.", - "name": "akua-context", + "required": true, + "name": "install_id", + "in": "path" + }, + { + "schema": { + "type": "string", + "minLength": 1, + "maxLength": 256, + "description": "The `etag` of the resource version the client last read. Required on writes when the resource exposes an `etag` field. Mismatch returns 409 `ABORTED` with the current etag in the error metadata.", + "example": "42" + }, + "required": true, + "description": "The `etag` of the resource version the client last read. Required on writes when the resource exposes an `etag` field. Mismatch returns 409 `ABORTED` with the current etag in the error metadata.", + "name": "if-match", "in": "header" }, { @@ -28452,31 +44846,32 @@ "type": "string", "minLength": 1, "maxLength": 64, - "description": "Caller-supplied idempotency key. Repeated requests with the same key return the existing resource instead of creating a duplicate. Safe to retry after a timed-out or interrupted request.", + "description": "Required caller-supplied idempotency key. Any non-empty key up to 64 characters is accepted. Endpoint-specific documentation describes how the key is used.", "example": "create-prod-2026-05-07" }, - "required": false, - "description": "Caller-supplied idempotency key. Repeated requests with the same key return the existing resource instead of creating a duplicate. Safe to retry after a timed-out or interrupted request.", + "required": true, + "description": "Required caller-supplied idempotency key. Any non-empty key up to 64 characters is accepted. Endpoint-specific documentation describes how the key is used.", "name": "idempotency-key", "in": "header" } ], "requestBody": { + "required": true, "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/CreateInstallRenderBody" + "$ref": "#/components/schemas/SetInstallAutomaticUpdatesBody" } } } }, "responses": { - "201": { - "description": "Render artifact created", + "200": { + "description": "Managed deployment automatic-update policy updated", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/InstallRender" + "$ref": "#/components/schemas/InstallLifecycleMutation" } } } @@ -28491,16 +44886,6 @@ } } }, - "403": { - "description": "Forbidden", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/ApiErrorResponse" - } - } - } - }, "404": { "description": "Not found", "content": { @@ -28522,15 +44907,17 @@ } } } - }, - "get": { - "x-platform-visibility": "PUBLIC", - "operationId": "installs.listRenders", + } + }, + "/v1/organizations/{organization_id}/managed_installs/{install_id}/renders": { + "post": { + "x-platform-visibility": "INTERNAL", + "operationId": "organizations.createManagedInstallRender", "tags": [ - "Installs" + "Organizations" ], - "summary": "List install renders", - "description": "Lists render artifacts for an install.", + "summary": "Create a managed deployment render", + "description": "Starts a render after atomically verifying that the deployment is currently managed by the selected organization.", "security": [ { "BearerAuth": [] @@ -28541,60 +44928,52 @@ "schema": { "type": "string", "minLength": 1, - "maxLength": 55, - "description": "Install ID", - "example": "inst_j572abc123def456" + "maxLength": 54 }, "required": true, - "description": "Install ID", - "name": "id", + "name": "organization_id", "in": "path" }, { "schema": { "type": "string", - "description": "Pagination cursor from a previous response's `next_cursor`." - }, - "required": false, - "description": "Pagination cursor from a previous response's `next_cursor`.", - "name": "cursor", - "in": "query" - }, - { - "schema": { - "type": "integer", - "minimum": 1, - "maximum": 100, - "default": 50, - "description": "Items per page (1-100, default 50)", - "example": 50 + "minLength": 1, + "maxLength": 55 }, - "required": false, - "description": "Items per page (1-100, default 50)", - "name": "limit", - "in": "query" + "required": true, + "name": "install_id", + "in": "path" }, { "schema": { "type": "string", "minLength": 1, - "maxLength": 53, - "description": "Optional workspace/scope context for the request. Carries a single workspace wire id (`ws_…`) today. Only needed for broad tokens — a workspace-owned token implies its workspace.", - "example": "ws_j572abc123def456" + "maxLength": 64, + "description": "Optional caller-supplied idempotency key. Any non-empty key up to 64 characters is accepted. Endpoint-specific documentation describes how the key is used.", + "example": "create-prod-2026-05-07" }, "required": false, - "description": "Optional workspace/scope context for the request. Carries a single workspace wire id (`ws_…`) today. Only needed for broad tokens — a workspace-owned token implies its workspace.", - "name": "akua-context", + "description": "Optional caller-supplied idempotency key. Any non-empty key up to 64 characters is accepted. Endpoint-specific documentation describes how the key is used.", + "name": "idempotency-key", "in": "header" } ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/CreateInstallRenderBody" + } + } + } + }, "responses": { - "200": { - "description": "Install renders", + "201": { + "description": "Managed deployment render created", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/InstallRenderList" + "$ref": "#/components/schemas/InstallRender" } } } @@ -28609,8 +44988,8 @@ } } }, - "403": { - "description": "Forbidden", + "404": { + "description": "Not found", "content": { "application/json": { "schema": { @@ -28619,8 +44998,8 @@ } } }, - "404": { - "description": "Not found", + "409": { + "description": "Conflict", "content": { "application/json": { "schema": { @@ -29186,11 +45565,11 @@ "type": "string", "minLength": 1, "maxLength": 64, - "description": "Caller-supplied idempotency key. Repeated requests with the same key return the existing resource instead of creating a duplicate. Safe to retry after a timed-out or interrupted request.", + "description": "Optional caller-supplied idempotency key. Any non-empty key up to 64 characters is accepted. Endpoint-specific documentation describes how the key is used.", "example": "create-prod-2026-05-07" }, "required": false, - "description": "Caller-supplied idempotency key. Repeated requests with the same key return the existing resource instead of creating a duplicate. Safe to retry after a timed-out or interrupted request.", + "description": "Optional caller-supplied idempotency key. Any non-empty key up to 64 characters is accepted. Endpoint-specific documentation describes how the key is used.", "name": "idempotency-key", "in": "header" } @@ -29571,11 +45950,11 @@ "type": "string", "minLength": 1, "maxLength": 64, - "description": "Caller-supplied idempotency key. Repeated requests with the same key return the existing resource instead of creating a duplicate. Safe to retry after a timed-out or interrupted request.", + "description": "Optional caller-supplied idempotency key. Any non-empty key up to 64 characters is accepted. Endpoint-specific documentation describes how the key is used.", "example": "create-prod-2026-05-07" }, "required": false, - "description": "Caller-supplied idempotency key. Repeated requests with the same key return the existing resource instead of creating a duplicate. Safe to retry after a timed-out or interrupted request.", + "description": "Optional caller-supplied idempotency key. Any non-empty key up to 64 characters is accepted. Endpoint-specific documentation describes how the key is used.", "name": "idempotency-key", "in": "header" }, @@ -30237,11 +46616,11 @@ "type": "string", "minLength": 1, "maxLength": 64, - "description": "Caller-supplied idempotency key. Repeated requests with the same key return the existing resource instead of creating a duplicate. Safe to retry after a timed-out or interrupted request.", + "description": "Optional caller-supplied idempotency key. Any non-empty key up to 64 characters is accepted. Endpoint-specific documentation describes how the key is used.", "example": "create-prod-2026-05-07" }, "required": false, - "description": "Caller-supplied idempotency key. Repeated requests with the same key return the existing resource instead of creating a duplicate. Safe to retry after a timed-out or interrupted request.", + "description": "Optional caller-supplied idempotency key. Any non-empty key up to 64 characters is accepted. Endpoint-specific documentation describes how the key is used.", "name": "idempotency-key", "in": "header" } @@ -30322,7 +46701,7 @@ "Workspaces" ], "summary": "List workspaces", - "description": "Returns all workspaces visible to the authenticated user.", + "description": "Returns workspaces visible within the authenticated request scope. An unscoped user credential sees all of its workspaces; a workspace-scoped request sees only that workspace.", "security": [ { "BearerAuth": [] @@ -30738,11 +47117,11 @@ "type": "string", "minLength": 1, "maxLength": 64, - "description": "Caller-supplied idempotency key. Repeated requests with the same key return the existing resource instead of creating a duplicate. Safe to retry after a timed-out or interrupted request.", + "description": "Optional caller-supplied idempotency key. Any non-empty key up to 64 characters is accepted. Endpoint-specific documentation describes how the key is used.", "example": "create-prod-2026-05-07" }, "required": false, - "description": "Caller-supplied idempotency key. Repeated requests with the same key return the existing resource instead of creating a duplicate. Safe to retry after a timed-out or interrupted request.", + "description": "Optional caller-supplied idempotency key. Any non-empty key up to 64 characters is accepted. Endpoint-specific documentation describes how the key is used.", "name": "idempotency-key", "in": "header" }, @@ -30952,11 +47331,11 @@ "type": "string", "minLength": 1, "maxLength": 64, - "description": "Caller-supplied idempotency key. Repeated requests with the same key return the existing resource instead of creating a duplicate. Safe to retry after a timed-out or interrupted request.", + "description": "Optional caller-supplied idempotency key. Any non-empty key up to 64 characters is accepted. Endpoint-specific documentation describes how the key is used.", "example": "create-prod-2026-05-07" }, "required": false, - "description": "Caller-supplied idempotency key. Repeated requests with the same key return the existing resource instead of creating a duplicate. Safe to retry after a timed-out or interrupted request.", + "description": "Optional caller-supplied idempotency key. Any non-empty key up to 64 characters is accepted. Endpoint-specific documentation describes how the key is used.", "name": "idempotency-key", "in": "header" } @@ -31091,11 +47470,11 @@ "type": "string", "minLength": 1, "maxLength": 64, - "description": "Caller-supplied idempotency key. Repeated requests with the same key return the existing resource instead of creating a duplicate. Safe to retry after a timed-out or interrupted request.", + "description": "Optional caller-supplied idempotency key. Any non-empty key up to 64 characters is accepted. Endpoint-specific documentation describes how the key is used.", "example": "create-prod-2026-05-07" }, "required": false, - "description": "Caller-supplied idempotency key. Repeated requests with the same key return the existing resource instead of creating a duplicate. Safe to retry after a timed-out or interrupted request.", + "description": "Optional caller-supplied idempotency key. Any non-empty key up to 64 characters is accepted. Endpoint-specific documentation describes how the key is used.", "name": "idempotency-key", "in": "header" } @@ -31232,11 +47611,11 @@ "type": "string", "minLength": 1, "maxLength": 64, - "description": "Caller-supplied idempotency key. Repeated requests with the same key return the existing resource instead of creating a duplicate. Safe to retry after a timed-out or interrupted request.", + "description": "Optional caller-supplied idempotency key. Any non-empty key up to 64 characters is accepted. Endpoint-specific documentation describes how the key is used.", "example": "create-prod-2026-05-07" }, "required": false, - "description": "Caller-supplied idempotency key. Repeated requests with the same key return the existing resource instead of creating a duplicate. Safe to retry after a timed-out or interrupted request.", + "description": "Optional caller-supplied idempotency key. Any non-empty key up to 64 characters is accepted. Endpoint-specific documentation describes how the key is used.", "name": "idempotency-key", "in": "header" } @@ -31478,6 +47857,205 @@ } } }, + "/v1/workspaces/{id}/management": { + "get": { + "x-platform-visibility": "PUBLIC", + "operationId": "workspaces.getManagement", + "tags": [ + "Workspaces" + ], + "summary": "Get workspace management access", + "description": "Returns the organization currently allowed to manage this customer-owned workspace.", + "security": [ + { + "BearerAuth": [] + } + ], + "parameters": [ + { + "schema": { + "type": "string", + "minLength": 1, + "maxLength": 53, + "description": "Workspace ID" + }, + "required": true, + "description": "Workspace ID", + "name": "id", + "in": "path" + }, + { + "schema": { + "type": "string", + "minLength": 1, + "maxLength": 53, + "description": "Optional workspace/scope context for the request. Carries a single workspace wire id (`ws_…`) today. Only needed for broad tokens — a workspace-owned token implies its workspace.", + "example": "ws_j572abc123def456" + }, + "required": false, + "description": "Optional workspace/scope context for the request. Carries a single workspace wire id (`ws_…`) today. Only needed for broad tokens — a workspace-owned token implies its workspace.", + "name": "akua-context", + "in": "header" + } + ], + "responses": { + "200": { + "description": "Workspace management relationship", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/WorkspaceManagement" + } + } + } + }, + "401": { + "description": "Unauthorized", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } + } + } + }, + "403": { + "description": "Forbidden", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } + } + } + }, + "404": { + "description": "Not found", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } + } + } + } + } + } + }, + "/v1/workspaces/{id}:revokeManagement": { + "post": { + "x-platform-visibility": "PUBLIC", + "operationId": "workspaces.revokeManagement", + "tags": [ + "Workspaces" + ], + "summary": "Revoke workspace management access", + "description": "Removes organization-level management access while preserving customer ownership and the running workspace.", + "security": [ + { + "BearerAuth": [] + } + ], + "parameters": [ + { + "schema": { + "type": "string", + "minLength": 1, + "maxLength": 53, + "description": "Workspace ID" + }, + "required": true, + "description": "Workspace ID", + "name": "id", + "in": "path" + }, + { + "schema": { + "type": "string", + "minLength": 1, + "maxLength": 53, + "description": "Optional workspace/scope context for the request. Carries a single workspace wire id (`ws_…`) today. Only needed for broad tokens — a workspace-owned token implies its workspace.", + "example": "ws_j572abc123def456" + }, + "required": false, + "description": "Optional workspace/scope context for the request. Carries a single workspace wire id (`ws_…`) today. Only needed for broad tokens — a workspace-owned token implies its workspace.", + "name": "akua-context", + "in": "header" + }, + { + "schema": { + "type": "string", + "minLength": 1, + "maxLength": 64, + "description": "Optional caller-supplied idempotency key. Any non-empty key up to 64 characters is accepted. Endpoint-specific documentation describes how the key is used.", + "example": "create-prod-2026-05-07" + }, + "required": false, + "description": "Optional caller-supplied idempotency key. Any non-empty key up to 64 characters is accepted. Endpoint-specific documentation describes how the key is used.", + "name": "idempotency-key", + "in": "header" + }, + { + "schema": { + "type": "string", + "minLength": 1, + "maxLength": 256, + "description": "The `etag` of the resource version the client last read. Required on writes when the resource exposes an `etag` field. Mismatch returns 409 `ABORTED` with the current etag in the error metadata.", + "example": "42" + }, + "required": true, + "description": "The `etag` of the resource version the client last read. Required on writes when the resource exposes an `etag` field. Mismatch returns 409 `ABORTED` with the current etag in the error metadata.", + "name": "if-match", + "in": "header" + } + ], + "responses": { + "204": { + "description": "Workspace management access revoked" + }, + "401": { + "description": "Unauthorized", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } + } + } + }, + "403": { + "description": "Forbidden", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } + } + } + }, + "404": { + "description": "Not found", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } + } + } + }, + "409": { + "description": "Conflict", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } + } + } + } + } + } + }, "/v1/workspaces/{id}/subscription:cancel": { "post": { "x-platform-visibility": "PUBLIC", @@ -31523,11 +48101,11 @@ "type": "string", "minLength": 1, "maxLength": 64, - "description": "Caller-supplied idempotency key. Repeated requests with the same key return the existing resource instead of creating a duplicate. Safe to retry after a timed-out or interrupted request.", + "description": "Optional caller-supplied idempotency key. Any non-empty key up to 64 characters is accepted. Endpoint-specific documentation describes how the key is used.", "example": "create-prod-2026-05-07" }, "required": false, - "description": "Caller-supplied idempotency key. Repeated requests with the same key return the existing resource instead of creating a duplicate. Safe to retry after a timed-out or interrupted request.", + "description": "Optional caller-supplied idempotency key. Any non-empty key up to 64 characters is accepted. Endpoint-specific documentation describes how the key is used.", "name": "idempotency-key", "in": "header" }, @@ -33231,11 +49809,11 @@ "type": "string", "minLength": 1, "maxLength": 64, - "description": "Caller-supplied idempotency key. Repeated requests with the same key return the existing resource instead of creating a duplicate. Safe to retry after a timed-out or interrupted request.", + "description": "Optional caller-supplied idempotency key. Any non-empty key up to 64 characters is accepted. Endpoint-specific documentation describes how the key is used.", "example": "create-prod-2026-05-07" }, "required": false, - "description": "Caller-supplied idempotency key. Repeated requests with the same key return the existing resource instead of creating a duplicate. Safe to retry after a timed-out or interrupted request.", + "description": "Optional caller-supplied idempotency key. Any non-empty key up to 64 characters is accepted. Endpoint-specific documentation describes how the key is used.", "name": "idempotency-key", "in": "header" } @@ -33797,11 +50375,11 @@ "type": "string", "minLength": 1, "maxLength": 64, - "description": "Caller-supplied idempotency key. Repeated requests with the same key return the existing resource instead of creating a duplicate. Safe to retry after a timed-out or interrupted request.", + "description": "Optional caller-supplied idempotency key. Any non-empty key up to 64 characters is accepted. Endpoint-specific documentation describes how the key is used.", "example": "create-prod-2026-05-07" }, "required": false, - "description": "Caller-supplied idempotency key. Repeated requests with the same key return the existing resource instead of creating a duplicate. Safe to retry after a timed-out or interrupted request.", + "description": "Optional caller-supplied idempotency key. Any non-empty key up to 64 characters is accepted. Endpoint-specific documentation describes how the key is used.", "name": "idempotency-key", "in": "header" }, @@ -33990,11 +50568,11 @@ "type": "string", "minLength": 1, "maxLength": 64, - "description": "Caller-supplied idempotency key. Repeated requests with the same key return the existing resource instead of creating a duplicate. Safe to retry after a timed-out or interrupted request.", + "description": "Optional caller-supplied idempotency key. Any non-empty key up to 64 characters is accepted. Endpoint-specific documentation describes how the key is used.", "example": "create-prod-2026-05-07" }, "required": false, - "description": "Caller-supplied idempotency key. Repeated requests with the same key return the existing resource instead of creating a duplicate. Safe to retry after a timed-out or interrupted request.", + "description": "Optional caller-supplied idempotency key. Any non-empty key up to 64 characters is accepted. Endpoint-specific documentation describes how the key is used.", "name": "idempotency-key", "in": "header" } @@ -34354,11 +50932,11 @@ "type": "string", "minLength": 1, "maxLength": 64, - "description": "Caller-supplied idempotency key. Repeated requests with the same key return the existing resource instead of creating a duplicate. Safe to retry after a timed-out or interrupted request.", + "description": "Optional caller-supplied idempotency key. Any non-empty key up to 64 characters is accepted. Endpoint-specific documentation describes how the key is used.", "example": "create-prod-2026-05-07" }, "required": false, - "description": "Caller-supplied idempotency key. Repeated requests with the same key return the existing resource instead of creating a duplicate. Safe to retry after a timed-out or interrupted request.", + "description": "Optional caller-supplied idempotency key. Any non-empty key up to 64 characters is accepted. Endpoint-specific documentation describes how the key is used.", "name": "idempotency-key", "in": "header" }, @@ -34980,15 +51558,525 @@ } ], "responses": { - "204": { - "description": "Onboarding cancelled" - }, - "400": { - "description": "Bad request", + "204": { + "description": "Onboarding cancelled" + }, + "400": { + "description": "Bad request", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } + } + } + }, + "401": { + "description": "Unauthorized", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } + } + } + }, + "403": { + "description": "Forbidden", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } + } + } + }, + "404": { + "description": "Not found", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } + } + } + } + } + } + }, + "/v1/stripe_account:createLink": { + "post": { + "x-platform-visibility": "INTERNAL", + "operationId": "workspaces.createStripeAccountLink", + "tags": [ + "Stripe" + ], + "summary": "Create connected Stripe account link", + "description": "Creates an onboarding link the seller follows to onboard or update their connected payment-provider account. Dashboard-only.", + "security": [ + { + "BearerAuth": [] + } + ], + "parameters": [ + { + "schema": { + "type": "string", + "minLength": 1, + "maxLength": 53, + "description": "Optional workspace/scope context for the request. Carries a single workspace wire id (`ws_…`) today. Only needed for broad tokens — a workspace-owned token implies its workspace.", + "example": "ws_j572abc123def456" + }, + "required": false, + "description": "Optional workspace/scope context for the request. Carries a single workspace wire id (`ws_…`) today. Only needed for broad tokens — a workspace-owned token implies its workspace.", + "name": "akua-context", + "in": "header" + }, + { + "schema": { + "type": "string", + "format": "uri", + "description": "Request origin used to derive default connected-account return and refresh URLs when the body omits them.", + "example": "https://akua.dev" + }, + "required": true, + "description": "Request origin used to derive default connected-account return and refresh URLs when the body omits them.", + "name": "origin", + "in": "header" + } + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/CreateStripeAccountLinkBody" + } + } + } + }, + "responses": { + "201": { + "description": "Connected Stripe account link created", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/StripeAccountLinkCreated" + } + } + } + }, + "401": { + "description": "Unauthorized", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } + } + } + }, + "403": { + "description": "Forbidden", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } + } + } + }, + "404": { + "description": "Not found", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } + } + } + } + } + } + }, + "/v1/stripe_account:createSession": { + "post": { + "x-platform-visibility": "INTERNAL", + "operationId": "workspaces.createStripeAccountSession", + "tags": [ + "Stripe" + ], + "summary": "Create connected Stripe account session", + "description": "Creates an embedded-UI session for the workspace connected payment-provider account, returning the client secret used to mount embedded components. Dashboard-only.", + "security": [ + { + "BearerAuth": [] + } + ], + "parameters": [ + { + "schema": { + "type": "string", + "minLength": 1, + "maxLength": 53, + "description": "Optional workspace/scope context for the request. Carries a single workspace wire id (`ws_…`) today. Only needed for broad tokens — a workspace-owned token implies its workspace.", + "example": "ws_j572abc123def456" + }, + "required": false, + "description": "Optional workspace/scope context for the request. Carries a single workspace wire id (`ws_…`) today. Only needed for broad tokens — a workspace-owned token implies its workspace.", + "name": "akua-context", + "in": "header" + } + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/CreateStripeAccountSessionBody" + } + } + } + }, + "responses": { + "201": { + "description": "Connected Stripe account session created", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/StripeAccountSessionCreated" + } + } + } + }, + "401": { + "description": "Unauthorized", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } + } + } + }, + "403": { + "description": "Forbidden", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } + } + } + }, + "404": { + "description": "Not found", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } + } + } + } + } + } + }, + "/v1/stripe_products": { + "get": { + "x-platform-visibility": "INTERNAL", + "operationId": "workspaces.getStripeProducts", + "tags": [ + "Stripe" + ], + "summary": "List connected Stripe account products", + "description": "Returns the catalog of the workspace connected payment-provider account, grouped by product, for the dashboard pricing picker. Returns an empty catalog when no account is connected. Dashboard-only.", + "security": [ + { + "BearerAuth": [] + } + ], + "parameters": [ + { + "schema": { + "type": "string", + "minLength": 1, + "maxLength": 53, + "description": "Optional workspace/scope context for the request. Carries a single workspace wire id (`ws_…`) today. Only needed for broad tokens — a workspace-owned token implies its workspace.", + "example": "ws_j572abc123def456" + }, + "required": false, + "description": "Optional workspace/scope context for the request. Carries a single workspace wire id (`ws_…`) today. Only needed for broad tokens — a workspace-owned token implies its workspace.", + "name": "akua-context", + "in": "header" + } + ], + "responses": { + "200": { + "description": "Connected Stripe account catalog grouped by product", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/WorkspaceStripeProducts" + } + } + } + }, + "401": { + "description": "Unauthorized", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } + } + } + }, + "403": { + "description": "Forbidden", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } + } + } + } + } + } + }, + "/v1/workspace_subscription:createUpgradeCheckout": { + "post": { + "x-platform-visibility": "INTERNAL", + "operationId": "workspaces.createUpgradeCheckout", + "tags": [ + "Stripe" + ], + "summary": "Create Pro upgrade checkout session", + "description": "Creates a payment-provider Checkout session for upgrading the workspace to the Pro plan. Dashboard-only.", + "security": [ + { + "BearerAuth": [] + } + ], + "parameters": [ + { + "schema": { + "type": "string", + "minLength": 1, + "maxLength": 53, + "description": "Optional workspace/scope context for the request. Carries a single workspace wire id (`ws_…`) today. Only needed for broad tokens — a workspace-owned token implies its workspace.", + "example": "ws_j572abc123def456" + }, + "required": false, + "description": "Optional workspace/scope context for the request. Carries a single workspace wire id (`ws_…`) today. Only needed for broad tokens — a workspace-owned token implies its workspace.", + "name": "akua-context", + "in": "header" + } + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/CreateUpgradeCheckoutBody" + } + } + } + }, + "responses": { + "201": { + "description": "Pro upgrade checkout session created", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/UpgradeCheckoutCreated" + } + } + } + }, + "400": { + "description": "Bad request", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } + } + } + }, + "401": { + "description": "Unauthorized", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } + } + } + }, + "403": { + "description": "Forbidden", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } + } + } + }, + "404": { + "description": "Not found", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } + } + } + } + } + } + }, + "/v1/billing_portal_session": { + "post": { + "x-platform-visibility": "INTERNAL", + "operationId": "workspaces.createBillingPortalSession", + "tags": [ + "Stripe" + ], + "summary": "Create billing portal session", + "description": "Creates a payment-provider Customer Portal session for managing the workspace Pro subscription. Dashboard-only.", + "security": [ + { + "BearerAuth": [] + } + ], + "parameters": [ + { + "schema": { + "type": "string", + "minLength": 1, + "maxLength": 53, + "description": "Optional workspace/scope context for the request. Carries a single workspace wire id (`ws_…`) today. Only needed for broad tokens — a workspace-owned token implies its workspace.", + "example": "ws_j572abc123def456" + }, + "required": false, + "description": "Optional workspace/scope context for the request. Carries a single workspace wire id (`ws_…`) today. Only needed for broad tokens — a workspace-owned token implies its workspace.", + "name": "akua-context", + "in": "header" + } + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/CreateBillingPortalSessionBody" + } + } + } + }, + "responses": { + "201": { + "description": "Billing portal session created", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/BillingPortalSessionCreated" + } + } + } + }, + "401": { + "description": "Unauthorized", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } + } + } + }, + "403": { + "description": "Forbidden", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } + } + } + }, + "404": { + "description": "Not found", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } + } + } + } + } + } + }, + "/v1/clusters": { + "get": { + "x-platform-visibility": "PUBLIC", + "tags": [ + "Clusters" + ], + "operationId": "clusters.list", + "summary": "List clusters", + "description": "Lists clusters visible to the authenticated workspace owner.", + "security": [ + { + "BearerAuth": [] + } + ], + "parameters": [ + { + "schema": { + "type": "string", + "description": "Pagination cursor from a previous response's `next_cursor`." + }, + "required": false, + "description": "Pagination cursor from a previous response's `next_cursor`.", + "name": "cursor", + "in": "query" + }, + { + "schema": { + "type": "integer", + "minimum": 1, + "maximum": 100, + "default": 50, + "description": "Items per page (1-100, default 50)", + "example": 50 + }, + "required": false, + "description": "Items per page (1-100, default 50)", + "name": "limit", + "in": "query" + }, + { + "schema": { + "type": "string", + "minLength": 1, + "maxLength": 53, + "description": "Optional workspace/scope context for the request. Carries a single workspace wire id (`ws_…`) today. Only needed for broad tokens — a workspace-owned token implies its workspace.", + "example": "ws_j572abc123def456" + }, + "required": false, + "description": "Optional workspace/scope context for the request. Carries a single workspace wire id (`ws_…`) today. Only needed for broad tokens — a workspace-owned token implies its workspace.", + "name": "akua-context", + "in": "header" + } + ], + "responses": { + "200": { + "description": "Cluster list", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/ApiErrorResponse" + "$ref": "#/components/schemas/ClusterList" } } } @@ -35012,29 +52100,17 @@ } } } - }, - "404": { - "description": "Not found", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/ApiErrorResponse" - } - } - } } } - } - }, - "/v1/stripe_account:createLink": { + }, "post": { - "x-platform-visibility": "INTERNAL", - "operationId": "workspaces.createStripeAccountLink", + "x-platform-visibility": "PUBLIC", "tags": [ - "Stripe" + "Clusters" ], - "summary": "Create connected Stripe account link", - "description": "Creates an onboarding link the seller follows to onboard or update their connected payment-provider account. Dashboard-only.", + "operationId": "clusters.create", + "summary": "Create cluster", + "description": "Creates a managed cluster and returns an async Operation envelope. State for in-flight operations is eventually consistent and may lag actual execution by a few seconds. State for completed operations (`done: true`) is immutable.", "security": [ { "BearerAuth": [] @@ -35057,13 +52133,14 @@ { "schema": { "type": "string", - "format": "uri", - "description": "Request origin used to derive default connected-account return and refresh URLs when the body omits them.", - "example": "https://akua.dev" + "minLength": 1, + "maxLength": 64, + "description": "Optional caller-supplied idempotency key. Any non-empty key up to 64 characters is accepted; repeated requests with the same key in the same workspace resolve consistently instead of creating a duplicate. When omitted, the server mints a key for this request.", + "example": "create-prod-2026-05-07" }, - "required": true, - "description": "Request origin used to derive default connected-account return and refresh URLs when the body omits them.", - "name": "origin", + "required": false, + "description": "Optional caller-supplied idempotency key. Any non-empty key up to 64 characters is accepted; repeated requests with the same key in the same workspace resolve consistently instead of creating a duplicate. When omitted, the server mints a key for this request.", + "name": "idempotency-key", "in": "header" } ], @@ -35071,18 +52148,45 @@ "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/CreateStripeAccountLinkBody" + "type": "object", + "properties": { + "name": { + "type": "string", + "minLength": 1, + "maxLength": 100, + "description": "Display name for the cluster." + }, + "region_id": { + "type": "string", + "minLength": 1, + "maxLength": 54 + }, + "network_profile": { + "type": "string", + "enum": [ + "linux_cilium", + "mixed_os_calico" + ], + "default": "linux_cilium", + "description": "Immutable networking profile for managed KaaS clusters. Defaults to `linux_cilium`; Windows workers require `mixed_os_calico`." + } + }, + "required": [ + "name", + "region_id" + ], + "additionalProperties": false } } } }, "responses": { - "201": { - "description": "Connected Stripe account link created", + "202": { + "description": "Cluster create operation accepted", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/StripeAccountLinkCreated" + "$ref": "#/components/schemas/Operation" } } } @@ -35106,65 +52210,36 @@ } } } - }, - "404": { - "description": "Not found", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/ApiErrorResponse" - } - } - } } } } }, - "/v1/stripe_account:createSession": { - "post": { + "/v1/clusters:dashboardList": { + "get": { "x-platform-visibility": "INTERNAL", - "operationId": "workspaces.createStripeAccountSession", + "x-platform-live": { + "visibility": "INTERNAL", + "transport": "convex", + "convexQuery": "cluster.ui.listDashboardClustersForApi" + }, "tags": [ - "Stripe" + "Clusters" ], - "summary": "Create connected Stripe account session", - "description": "Creates an embedded-UI session for the workspace connected payment-provider account, returning the client secret used to mount embedded components. Dashboard-only.", + "operationId": "clusters.listDashboard", + "summary": "List dashboard clusters", + "description": "Returns clusters shaped for the dashboard clusters page.", "security": [ { "BearerAuth": [] } ], - "parameters": [ - { - "schema": { - "type": "string", - "minLength": 1, - "maxLength": 53, - "description": "Optional workspace/scope context for the request. Carries a single workspace wire id (`ws_…`) today. Only needed for broad tokens — a workspace-owned token implies its workspace.", - "example": "ws_j572abc123def456" - }, - "required": false, - "description": "Optional workspace/scope context for the request. Carries a single workspace wire id (`ws_…`) today. Only needed for broad tokens — a workspace-owned token implies its workspace.", - "name": "akua-context", - "in": "header" - } - ], - "requestBody": { - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/CreateStripeAccountSessionBody" - } - } - } - }, "responses": { - "201": { - "description": "Connected Stripe account session created", + "200": { + "description": "Dashboard cluster list", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/StripeAccountSessionCreated" + "$ref": "#/components/schemas/DashboardClusterList" } } } @@ -35188,35 +52263,40 @@ } } } - }, - "404": { - "description": "Not found", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/ApiErrorResponse" - } - } - } } } } }, - "/v1/stripe_products": { + "/v1/clusters/{id}:dashboard": { "get": { "x-platform-visibility": "INTERNAL", - "operationId": "workspaces.getStripeProducts", + "x-platform-live": { + "visibility": "INTERNAL", + "transport": "convex", + "convexQuery": "cluster.ui.getDashboardClusterForApi" + }, + "operationId": "clusters.getDashboard", "tags": [ - "Stripe" + "Clusters" ], - "summary": "List connected Stripe account products", - "description": "Returns the catalog of the workspace connected payment-provider account, grouped by product, for the dashboard pricing picker. Returns an empty catalog when no account is connected. Dashboard-only.", + "summary": "Get dashboard cluster detail", + "description": "Returns one cluster shaped for the dashboard cluster cockpit.", "security": [ { "BearerAuth": [] } ], "parameters": [ + { + "schema": { + "type": "string", + "minLength": 1, + "maxLength": 54 + }, + "required": true, + "name": "id", + "in": "path" + }, { "schema": { "type": "string", @@ -35233,11 +52313,11 @@ ], "responses": { "200": { - "description": "Connected Stripe account catalog grouped by product", + "description": "Dashboard cluster detail", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/WorkspaceStripeProducts" + "$ref": "#/components/schemas/DashboardCluster" } } } @@ -35261,25 +52341,47 @@ } } } + }, + "404": { + "description": "Not found", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } + } + } } } } }, - "/v1/workspace_subscription:createUpgradeCheckout": { - "post": { - "x-platform-visibility": "INTERNAL", - "operationId": "workspaces.createUpgradeCheckout", + "/v1/clusters/{id}": { + "get": { + "x-platform-visibility": "PUBLIC", "tags": [ - "Stripe" + "Clusters" ], - "summary": "Create Pro upgrade checkout session", - "description": "Creates a payment-provider Checkout session for upgrading the workspace to the Pro plan. Dashboard-only.", + "operationId": "clusters.get", + "summary": "Get cluster", + "description": "Gets a cluster by id.", "security": [ { "BearerAuth": [] } ], "parameters": [ + { + "schema": { + "type": "string", + "minLength": 1, + "maxLength": 54, + "description": "Cluster ID." + }, + "required": true, + "description": "Cluster ID.", + "name": "id", + "in": "path" + }, { "schema": { "type": "string", @@ -35294,32 +52396,13 @@ "in": "header" } ], - "requestBody": { - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/CreateUpgradeCheckoutBody" - } - } - } - }, "responses": { - "201": { - "description": "Pro upgrade checkout session created", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/UpgradeCheckoutCreated" - } - } - } - }, - "400": { - "description": "Bad request", + "200": { + "description": "Cluster details", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/ApiErrorResponse" + "$ref": "#/components/schemas/Cluster" } } } @@ -35355,23 +52438,31 @@ } } } - } - }, - "/v1/billing_portal_session": { - "post": { - "x-platform-visibility": "INTERNAL", - "operationId": "workspaces.createBillingPortalSession", + }, + "patch": { + "x-platform-visibility": "PUBLIC", "tags": [ - "Stripe" + "Clusters" ], - "summary": "Create billing portal session", - "description": "Creates a payment-provider Customer Portal session for managing the workspace Pro subscription. Dashboard-only.", + "operationId": "clusters.update", + "summary": "Update cluster", + "description": "Updates editable cluster fields.", "security": [ { "BearerAuth": [] } ], "parameters": [ + { + "schema": { + "type": "string", + "minLength": 1, + "maxLength": 54 + }, + "required": true, + "name": "id", + "in": "path" + }, { "schema": { "type": "string", @@ -35384,24 +52475,75 @@ "description": "Optional workspace/scope context for the request. Carries a single workspace wire id (`ws_…`) today. Only needed for broad tokens — a workspace-owned token implies its workspace.", "name": "akua-context", "in": "header" + }, + { + "schema": { + "type": "string", + "minLength": 1, + "maxLength": 64, + "description": "Optional caller-supplied idempotency key. Any non-empty key up to 64 characters is accepted. Endpoint-specific documentation describes how the key is used.", + "example": "create-prod-2026-05-07" + }, + "required": false, + "description": "Optional caller-supplied idempotency key. Any non-empty key up to 64 characters is accepted. Endpoint-specific documentation describes how the key is used.", + "name": "idempotency-key", + "in": "header" + }, + { + "schema": { + "type": "string", + "minLength": 1, + "maxLength": 256, + "description": "The `etag` of the resource version the client last read. Required on writes when the resource exposes an `etag` field. Mismatch returns 409 `ABORTED` with the current etag in the error metadata.", + "example": "42" + }, + "required": true, + "description": "The `etag` of the resource version the client last read. Required on writes when the resource exposes an `etag` field. Mismatch returns 409 `ABORTED` with the current etag in the error metadata.", + "name": "if-match", + "in": "header" } ], "requestBody": { "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/CreateBillingPortalSessionBody" + "type": "object", + "properties": { + "name": { + "type": "string", + "minLength": 1, + "maxLength": 100 + }, + "region_id": { + "type": "string", + "minLength": 1, + "maxLength": 54 + }, + "provider": { + "type": "string", + "enum": [ + "managed_kaas", + "imported_byoc" + ], + "description": "Cluster control-plane family: managed (`managed_kaas`) vs imported self-managed (`imported_byoc`)." + }, + "kubeconfig": { + "type": "string", + "minLength": 1 + } + }, + "additionalProperties": false } } } }, "responses": { - "201": { - "description": "Billing portal session created", + "200": { + "description": "Cluster updated", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/BillingPortalSessionCreated" + "$ref": "#/components/schemas/Cluster" } } } @@ -35435,19 +52577,27 @@ } } } + }, + "409": { + "description": "Conflict", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } + } + } } } - } - }, - "/v1/clusters": { - "get": { + }, + "delete": { "x-platform-visibility": "PUBLIC", "tags": [ "Clusters" ], - "operationId": "clusters.list", - "summary": "List clusters", - "description": "Lists clusters visible to the authenticated workspace owner.", + "operationId": "clusters.delete", + "summary": "Delete cluster", + "description": "Tears down the cluster asynchronously after active installs, managed workers, and machine snapshots have been removed. Returns an Operation envelope. Caller must be a workspace owner.", "security": [ { "BearerAuth": [] @@ -35457,26 +52607,12 @@ { "schema": { "type": "string", - "description": "Pagination cursor from a previous response's `next_cursor`." - }, - "required": false, - "description": "Pagination cursor from a previous response's `next_cursor`.", - "name": "cursor", - "in": "query" - }, - { - "schema": { - "type": "integer", - "minimum": 1, - "maximum": 100, - "default": 50, - "description": "Items per page (1-100, default 50)", - "example": 50 + "minLength": 1, + "maxLength": 54 }, - "required": false, - "description": "Items per page (1-100, default 50)", - "name": "limit", - "in": "query" + "required": true, + "name": "id", + "in": "path" }, { "schema": { @@ -35490,15 +52626,41 @@ "description": "Optional workspace/scope context for the request. Carries a single workspace wire id (`ws_…`) today. Only needed for broad tokens — a workspace-owned token implies its workspace.", "name": "akua-context", "in": "header" + }, + { + "schema": { + "type": "string", + "minLength": 1, + "maxLength": 64, + "description": "Optional caller-supplied idempotency key. Any non-empty key up to 64 characters is accepted. Endpoint-specific documentation describes how the key is used.", + "example": "create-prod-2026-05-07" + }, + "required": false, + "description": "Optional caller-supplied idempotency key. Any non-empty key up to 64 characters is accepted. Endpoint-specific documentation describes how the key is used.", + "name": "idempotency-key", + "in": "header" + }, + { + "schema": { + "type": "string", + "minLength": 1, + "maxLength": 256, + "description": "The `etag` of the resource version the client last read. Required on writes when the resource exposes an `etag` field. Mismatch returns 409 `ABORTED` with the current etag in the error metadata.", + "example": "42" + }, + "required": true, + "description": "The `etag` of the resource version the client last read. Required on writes when the resource exposes an `etag` field. Mismatch returns 409 `ABORTED` with the current etag in the error metadata.", + "name": "if-match", + "in": "header" } ], "responses": { - "200": { - "description": "Cluster list", + "202": { + "description": "Delete initiated", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/ClusterList" + "$ref": "#/components/schemas/Operation" } } } @@ -35522,17 +52684,39 @@ } } } + }, + "404": { + "description": "Not found", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } + } + } + }, + "409": { + "description": "Conflict", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } + } + } } } - }, + } + }, + "/v1/clusters:import": { "post": { "x-platform-visibility": "PUBLIC", "tags": [ "Clusters" ], - "operationId": "clusters.create", - "summary": "Create cluster", - "description": "Creates a managed cluster and returns an async Operation envelope. State for in-flight operations is eventually consistent and may lag actual execution by a few seconds. State for completed operations (`done: true`) is immutable.", + "operationId": "clusters.import", + "summary": "Import cluster", + "description": "Imports an existing cluster from kubeconfig.", "security": [ { "BearerAuth": [] @@ -35557,11 +52741,11 @@ "type": "string", "minLength": 1, "maxLength": 64, - "description": "Caller-supplied idempotency key. Repeated requests with the same key return the existing resource instead of creating a duplicate. Safe to retry after a timed-out or interrupted request.", + "description": "Optional caller-supplied idempotency key. Any non-empty key up to 64 characters is accepted. Endpoint-specific documentation describes how the key is used.", "example": "create-prod-2026-05-07" }, "required": false, - "description": "Caller-supplied idempotency key. Repeated requests with the same key return the existing resource instead of creating a duplicate. Safe to retry after a timed-out or interrupted request.", + "description": "Optional caller-supplied idempotency key. Any non-empty key up to 64 characters is accepted. Endpoint-specific documentation describes how the key is used.", "name": "idempotency-key", "in": "header" } @@ -35575,93 +52759,35 @@ "name": { "type": "string", "minLength": 1, - "maxLength": 100, - "description": "Display name for the cluster." + "maxLength": 100 }, "region_id": { "type": "string", "minLength": 1, "maxLength": 54 }, - "network_profile": { + "kubeconfig": { "type": "string", - "enum": [ - "linux_cilium", - "mixed_os_calico" - ], - "default": "linux_cilium", - "description": "Immutable networking profile for managed KaaS clusters. Defaults to `linux_cilium`; Windows workers require `mixed_os_calico`." + "minLength": 1 } }, "required": [ "name", - "region_id" + "region_id", + "kubeconfig" ], "additionalProperties": false } } } }, - "responses": { - "202": { - "description": "Cluster create operation accepted", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/Operation" - } - } - } - }, - "401": { - "description": "Unauthorized", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/ApiErrorResponse" - } - } - } - }, - "403": { - "description": "Forbidden", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/ApiErrorResponse" - } - } - } - } - } - } - }, - "/v1/clusters:dashboardList": { - "get": { - "x-platform-visibility": "INTERNAL", - "x-platform-live": { - "visibility": "INTERNAL", - "transport": "convex", - "convexQuery": "cluster.ui.listDashboardClustersForApi" - }, - "tags": [ - "Clusters" - ], - "operationId": "clusters.listDashboard", - "summary": "List dashboard clusters", - "description": "Returns clusters shaped for the dashboard clusters page.", - "security": [ - { - "BearerAuth": [] - } - ], "responses": { "200": { - "description": "Dashboard cluster list", + "description": "Cluster imported", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/DashboardClusterList" + "$ref": "#/components/schemas/Cluster" } } } @@ -35689,15 +52815,20 @@ } } }, - "/v1/clusters/{id}": { + "/v1/clusters/{id}/capabilities": { "get": { "x-platform-visibility": "PUBLIC", "tags": [ "Clusters" ], - "operationId": "clusters.get", - "summary": "Get cluster", - "description": "Gets a cluster by id.", + "operationId": "clusters.getCapabilities", + "x-platform-live": { + "visibility": "INTERNAL", + "transport": "convex", + "convexQuery": "cluster.ui.getClusterCapabilitiesForApi" + }, + "summary": "Get cluster capabilities", + "description": "Gets the last observed Kubernetes capability snapshot for a cluster.", "security": [ { "BearerAuth": [] @@ -35732,11 +52863,11 @@ ], "responses": { "200": { - "description": "Cluster details", + "description": "Cluster capabilities", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/Cluster" + "$ref": "#/components/schemas/ClusterCapabilities" } } } @@ -35772,15 +52903,17 @@ } } } - }, - "patch": { + } + }, + "/v1/clusters/{id}/capabilities:refresh": { + "post": { "x-platform-visibility": "PUBLIC", "tags": [ "Clusters" ], - "operationId": "clusters.update", - "summary": "Update cluster", - "description": "Updates editable cluster fields.", + "operationId": "clusters.refreshCapabilities", + "summary": "Refresh cluster capabilities", + "description": "Refreshes observed cluster capability facts. The API returns an Operation envelope because cluster inspection runs asynchronously.", "security": [ { "BearerAuth": [] @@ -35815,69 +52948,22 @@ "type": "string", "minLength": 1, "maxLength": 64, - "description": "Caller-supplied idempotency key. Repeated requests with the same key return the existing resource instead of creating a duplicate. Safe to retry after a timed-out or interrupted request.", + "description": "Optional caller-supplied idempotency key. Any non-empty key up to 64 characters is accepted. Endpoint-specific documentation describes how the key is used.", "example": "create-prod-2026-05-07" }, "required": false, - "description": "Caller-supplied idempotency key. Repeated requests with the same key return the existing resource instead of creating a duplicate. Safe to retry after a timed-out or interrupted request.", + "description": "Optional caller-supplied idempotency key. Any non-empty key up to 64 characters is accepted. Endpoint-specific documentation describes how the key is used.", "name": "idempotency-key", "in": "header" - }, - { - "schema": { - "type": "string", - "minLength": 1, - "maxLength": 256, - "description": "The `etag` of the resource version the client last read. Required on writes when the resource exposes an `etag` field. Mismatch returns 409 `ABORTED` with the current etag in the error metadata.", - "example": "42" - }, - "required": true, - "description": "The `etag` of the resource version the client last read. Required on writes when the resource exposes an `etag` field. Mismatch returns 409 `ABORTED` with the current etag in the error metadata.", - "name": "if-match", - "in": "header" } ], - "requestBody": { - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "name": { - "type": "string", - "minLength": 1, - "maxLength": 100 - }, - "region_id": { - "type": "string", - "minLength": 1, - "maxLength": 54 - }, - "provider": { - "type": "string", - "enum": [ - "managed_kaas", - "imported_byoc" - ], - "description": "Cluster control-plane family: managed (`managed_kaas`) vs imported self-managed (`imported_byoc`)." - }, - "kubeconfig": { - "type": "string", - "minLength": 1 - } - }, - "additionalProperties": false - } - } - } - }, "responses": { - "200": { - "description": "Cluster updated", + "202": { + "description": "Refresh initiated", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/Cluster" + "$ref": "#/components/schemas/Operation" } } } @@ -35923,15 +53009,17 @@ } } } - }, - "delete": { + } + }, + "/v1/clusters/{id}:suspend": { + "post": { "x-platform-visibility": "PUBLIC", "tags": [ "Clusters" ], - "operationId": "clusters.delete", - "summary": "Delete cluster", - "description": "Tears down the cluster and all of its owned resources. Returns an Operation envelope; the actual teardown happens asynchronously. Caller must be a workspace owner.", + "operationId": "clusters.suspend", + "summary": "Suspend cluster", + "description": "Suspends a running cluster. The API returns an Operation envelope because teardown and drain are asynchronous.", "security": [ { "BearerAuth": [] @@ -35966,11 +53054,11 @@ "type": "string", "minLength": 1, "maxLength": 64, - "description": "Caller-supplied idempotency key. Repeated requests with the same key return the existing resource instead of creating a duplicate. Safe to retry after a timed-out or interrupted request.", + "description": "Optional caller-supplied idempotency key. Any non-empty key up to 64 characters is accepted. Endpoint-specific documentation describes how the key is used.", "example": "create-prod-2026-05-07" }, "required": false, - "description": "Caller-supplied idempotency key. Repeated requests with the same key return the existing resource instead of creating a duplicate. Safe to retry after a timed-out or interrupted request.", + "description": "Optional caller-supplied idempotency key. Any non-empty key up to 64 characters is accepted. Endpoint-specific documentation describes how the key is used.", "name": "idempotency-key", "in": "header" }, @@ -35990,7 +53078,7 @@ ], "responses": { "202": { - "description": "Delete initiated", + "description": "Suspend initiated", "content": { "application/json": { "schema": { @@ -36042,21 +53130,31 @@ } } }, - "/v1/clusters:import": { + "/v1/clusters/{id}:resume": { "post": { "x-platform-visibility": "PUBLIC", "tags": [ "Clusters" ], - "operationId": "clusters.import", - "summary": "Import cluster", - "description": "Imports an existing cluster from kubeconfig.", + "operationId": "clusters.resume", + "summary": "Resume cluster", + "description": "Resumes a suspended cluster and returns an async Operation envelope.", "security": [ { "BearerAuth": [] } ], "parameters": [ + { + "schema": { + "type": "string", + "minLength": 1, + "maxLength": 54 + }, + "required": true, + "name": "id", + "in": "path" + }, { "schema": { "type": "string", @@ -36075,53 +53173,35 @@ "type": "string", "minLength": 1, "maxLength": 64, - "description": "Caller-supplied idempotency key. Repeated requests with the same key return the existing resource instead of creating a duplicate. Safe to retry after a timed-out or interrupted request.", + "description": "Optional caller-supplied idempotency key. Any non-empty key up to 64 characters is accepted. Endpoint-specific documentation describes how the key is used.", "example": "create-prod-2026-05-07" }, "required": false, - "description": "Caller-supplied idempotency key. Repeated requests with the same key return the existing resource instead of creating a duplicate. Safe to retry after a timed-out or interrupted request.", + "description": "Optional caller-supplied idempotency key. Any non-empty key up to 64 characters is accepted. Endpoint-specific documentation describes how the key is used.", "name": "idempotency-key", "in": "header" + }, + { + "schema": { + "type": "string", + "minLength": 1, + "maxLength": 256, + "description": "The `etag` of the resource version the client last read. Required on writes when the resource exposes an `etag` field. Mismatch returns 409 `ABORTED` with the current etag in the error metadata.", + "example": "42" + }, + "required": true, + "description": "The `etag` of the resource version the client last read. Required on writes when the resource exposes an `etag` field. Mismatch returns 409 `ABORTED` with the current etag in the error metadata.", + "name": "if-match", + "in": "header" } ], - "requestBody": { - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "name": { - "type": "string", - "minLength": 1, - "maxLength": 100 - }, - "region_id": { - "type": "string", - "minLength": 1, - "maxLength": 54 - }, - "kubeconfig": { - "type": "string", - "minLength": 1 - } - }, - "required": [ - "name", - "region_id", - "kubeconfig" - ], - "additionalProperties": false - } - } - } - }, "responses": { - "200": { - "description": "Cluster imported", + "202": { + "description": "Resume initiated", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/Cluster" + "$ref": "#/components/schemas/Operation" } } } @@ -36145,24 +53225,39 @@ } } } + }, + "404": { + "description": "Not found", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } + } + } + }, + "409": { + "description": "Conflict", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } + } + } } } } }, - "/v1/clusters/{id}/capabilities": { + "/v1/clusters/{id}/kubeconfig": { "get": { "x-platform-visibility": "PUBLIC", "tags": [ "Clusters" ], - "operationId": "clusters.getCapabilities", - "x-platform-live": { - "visibility": "INTERNAL", - "transport": "convex", - "convexQuery": "cluster.ui.getClusterCapabilitiesForApi" - }, - "summary": "Get cluster capabilities", - "description": "Gets the last observed Kubernetes capability snapshot for a cluster.", + "operationId": "clusters.getKubeconfig", + "summary": "Get cluster kubeconfig", + "description": "Returns a cluster admin kubeconfig for workspace owners and admins. Successful credential disclosure is fail-closed on a cluster-scoped audit record.", "security": [ { "BearerAuth": [] @@ -36173,11 +53268,9 @@ "schema": { "type": "string", "minLength": 1, - "maxLength": 54, - "description": "Cluster ID." + "maxLength": 54 }, "required": true, - "description": "Cluster ID.", "name": "id", "in": "path" }, @@ -36197,11 +53290,11 @@ ], "responses": { "200": { - "description": "Cluster capabilities", + "description": "Cluster kubeconfig", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/ClusterCapabilities" + "$ref": "#/components/schemas/Kubeconfig" } } } @@ -36235,19 +53328,29 @@ } } } + }, + "500": { + "description": "Internal server error", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } + } + } } } } }, - "/v1/clusters/{id}/capabilities:refresh": { - "post": { + "/v1/clusters/{id}/kube_proxy/{path:*}": { + "get": { "x-platform-visibility": "PUBLIC", "tags": [ "Clusters" ], - "operationId": "clusters.refreshCapabilities", - "summary": "Refresh cluster capabilities", - "description": "Refreshes observed cluster capability facts. The API returns an Operation envelope because cluster inspection runs asynchronously.", + "operationId": "clusters.proxyKube", + "summary": "Proxy cluster API", + "description": "Proxy kube-apiserver traffic through the public API. `path:*` is forwarded verbatim to upstream.", "security": [ { "BearerAuth": [] @@ -36267,40 +53370,30 @@ { "schema": { "type": "string", - "minLength": 1, - "maxLength": 53, - "description": "Optional workspace/scope context for the request. Carries a single workspace wire id (`ws_…`) today. Only needed for broad tokens — a workspace-owned token implies its workspace.", - "example": "ws_j572abc123def456" + "description": "Kube API path forwarded verbatim" }, - "required": false, - "description": "Optional workspace/scope context for the request. Carries a single workspace wire id (`ws_…`) today. Only needed for broad tokens — a workspace-owned token implies its workspace.", - "name": "akua-context", - "in": "header" + "required": true, + "description": "Kube API path forwarded verbatim", + "name": "path", + "in": "path" }, { "schema": { "type": "string", "minLength": 1, - "maxLength": 64, - "description": "Caller-supplied idempotency key. Repeated requests with the same key return the existing resource instead of creating a duplicate. Safe to retry after a timed-out or interrupted request.", - "example": "create-prod-2026-05-07" + "maxLength": 53, + "description": "Optional workspace/scope context for the request. Carries a single workspace wire id (`ws_…`) today. Only needed for broad tokens — a workspace-owned token implies its workspace.", + "example": "ws_j572abc123def456" }, "required": false, - "description": "Caller-supplied idempotency key. Repeated requests with the same key return the existing resource instead of creating a duplicate. Safe to retry after a timed-out or interrupted request.", - "name": "idempotency-key", + "description": "Optional workspace/scope context for the request. Carries a single workspace wire id (`ws_…`) today. Only needed for broad tokens — a workspace-owned token implies its workspace.", + "name": "akua-context", "in": "header" } ], "responses": { - "202": { - "description": "Refresh initiated", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/Operation" - } - } - } + "200": { + "description": "Kube API response passthrough" }, "401": { "description": "Unauthorized", @@ -36331,29 +53424,19 @@ } } } - }, - "409": { - "description": "Conflict", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/ApiErrorResponse" - } - } - } } } } }, - "/v1/clusters/{id}:suspend": { + "/v1/clusters/{id}:exec": { "post": { "x-platform-visibility": "PUBLIC", "tags": [ "Clusters" ], - "operationId": "clusters.suspend", - "summary": "Suspend cluster", - "description": "Suspends a running cluster. The API returns an Operation envelope because teardown and drain are asynchronous.", + "operationId": "clusters.exec", + "summary": "Execute command in cluster", + "description": "Runs a structured command in a pod and returns the result inline. No LRO wrapper by design.", "security": [ { "BearerAuth": [] @@ -36388,11 +53471,11 @@ "type": "string", "minLength": 1, "maxLength": 64, - "description": "Caller-supplied idempotency key. Repeated requests with the same key return the existing resource instead of creating a duplicate. Safe to retry after a timed-out or interrupted request.", + "description": "Optional caller-supplied idempotency key. Any non-empty key up to 64 characters is accepted. Endpoint-specific documentation describes how the key is used.", "example": "create-prod-2026-05-07" }, "required": false, - "description": "Caller-supplied idempotency key. Repeated requests with the same key return the existing resource instead of creating a duplicate. Safe to retry after a timed-out or interrupted request.", + "description": "Optional caller-supplied idempotency key. Any non-empty key up to 64 characters is accepted. Endpoint-specific documentation describes how the key is used.", "name": "idempotency-key", "in": "header" }, @@ -36409,14 +53492,23 @@ "name": "if-match", "in": "header" } - ], + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ExecBody" + } + } + } + }, "responses": { - "202": { - "description": "Suspend initiated", + "200": { + "description": "Command output", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/Operation" + "$ref": "#/components/schemas/ExecResult" } } } @@ -36464,15 +53556,15 @@ } } }, - "/v1/clusters/{id}:resume": { + "/v1/clusters/{id}/worker_bootstraps": { "post": { "x-platform-visibility": "PUBLIC", "tags": [ "Clusters" ], - "operationId": "clusters.resume", - "summary": "Resume cluster", - "description": "Resumes a suspended cluster and returns an async Operation envelope.", + "operationId": "clusters.createWorkerBootstrap", + "summary": "Create worker bootstrap", + "description": "Issues a new worker-bootstrap row and returns its metadata.", "security": [ { "BearerAuth": [] @@ -36507,35 +53599,48 @@ "type": "string", "minLength": 1, "maxLength": 64, - "description": "Caller-supplied idempotency key. Repeated requests with the same key return the existing resource instead of creating a duplicate. Safe to retry after a timed-out or interrupted request.", + "description": "Optional caller-supplied idempotency key. Any non-empty key up to 64 characters is accepted. Endpoint-specific documentation describes how the key is used.", "example": "create-prod-2026-05-07" }, "required": false, - "description": "Caller-supplied idempotency key. Repeated requests with the same key return the existing resource instead of creating a duplicate. Safe to retry after a timed-out or interrupted request.", + "description": "Optional caller-supplied idempotency key. Any non-empty key up to 64 characters is accepted. Endpoint-specific documentation describes how the key is used.", "name": "idempotency-key", "in": "header" - }, - { - "schema": { - "type": "string", - "minLength": 1, - "maxLength": 256, - "description": "The `etag` of the resource version the client last read. Required on writes when the resource exposes an `etag` field. Mismatch returns 409 `ABORTED` with the current etag in the error metadata.", - "example": "42" - }, - "required": true, - "description": "The `etag` of the resource version the client last read. Required on writes when the resource exposes an `etag` field. Mismatch returns 409 `ABORTED` with the current etag in the error metadata.", - "name": "if-match", - "in": "header" } ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "ttl_seconds": { + "type": "integer", + "minimum": 60, + "maximum": 86400, + "description": "Token TTL in seconds (optional)." + } + }, + "additionalProperties": false + } + } + } + }, "responses": { - "202": { - "description": "Resume initiated", + "201": { + "description": "Worker bootstrap created", + "headers": { + "Location": { + "description": "Location of the created worker bootstrap.", + "schema": { + "type": "string" + } + } + }, "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/Operation" + "$ref": "#/components/schemas/WorkerBootstrap" } } } @@ -36569,29 +53674,22 @@ } } } - }, - "409": { - "description": "Conflict", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/ApiErrorResponse" - } - } - } } } - } - }, - "/v1/clusters/{id}/kubeconfig": { + }, "get": { "x-platform-visibility": "PUBLIC", + "x-platform-live": { + "visibility": "INTERNAL", + "transport": "convex", + "convexQuery": "cluster.ui.listWorkerBootstrapsByClusterForApi" + }, "tags": [ "Clusters" ], - "operationId": "clusters.getKubeconfig", - "summary": "Get cluster kubeconfig", - "description": "Returns cluster admin kubeconfig for workspace owners. R6 deliberate divergence retained with an audit-log requirement.", + "operationId": "clusters.listWorkerBootstraps", + "summary": "List cluster worker bootstraps", + "description": "Lists worker-bootstrap tokens for the cluster. Cursor-paginated. Includes revoked / expired tokens by default — filter via the `status` query when implemented.", "security": [ { "BearerAuth": [] @@ -36608,6 +53706,30 @@ "name": "id", "in": "path" }, + { + "schema": { + "type": "string", + "description": "Pagination cursor from a previous response's `next_cursor`." + }, + "required": false, + "description": "Pagination cursor from a previous response's `next_cursor`.", + "name": "cursor", + "in": "query" + }, + { + "schema": { + "type": "integer", + "minimum": 1, + "maximum": 100, + "default": 50, + "description": "Items per page (1-100, default 50)", + "example": 50 + }, + "required": false, + "description": "Items per page (1-100, default 50)", + "name": "limit", + "in": "query" + }, { "schema": { "type": "string", @@ -36624,11 +53746,11 @@ ], "responses": { "200": { - "description": "Cluster kubeconfig", + "description": "Worker bootstraps page", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/Kubeconfig" + "$ref": "#/components/schemas/WorkerBootstrapList" } } } @@ -36666,15 +53788,15 @@ } } }, - "/v1/clusters/{id}/kube_proxy/{path:*}": { + "/v1/clusters/{id}/worker_bootstraps/{wbs_id}": { "get": { "x-platform-visibility": "PUBLIC", "tags": [ "Clusters" ], - "operationId": "clusters.proxyKube", - "summary": "Proxy cluster API", - "description": "Proxy kube-apiserver traffic through the public API. `path:*` is forwarded verbatim to upstream.", + "operationId": "clusters.getWorkerBootstrap", + "summary": "Get cluster worker bootstrap", + "description": "Returns a single worker-bootstrap token by ID, including its current status and expiry timestamp.", "security": [ { "BearerAuth": [] @@ -36694,11 +53816,11 @@ { "schema": { "type": "string", - "description": "Kube API path forwarded verbatim" + "minLength": 1, + "maxLength": 54 }, "required": true, - "description": "Kube API path forwarded verbatim", - "name": "path", + "name": "wbs_id", "in": "path" }, { @@ -36717,7 +53839,14 @@ ], "responses": { "200": { - "description": "Kube API response passthrough" + "description": "Worker bootstrap", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/WorkerBootstrap" + } + } + } }, "401": { "description": "Unauthorized", @@ -36752,15 +53881,15 @@ } } }, - "/v1/clusters/{id}:exec": { + "/v1/clusters/{id}/worker_bootstraps/{wbs_id}:revoke": { "post": { "x-platform-visibility": "PUBLIC", "tags": [ "Clusters" ], - "operationId": "clusters.exec", - "summary": "Execute command in cluster", - "description": "Runs a structured command in a pod and returns the result inline. No LRO wrapper by design.", + "operationId": "clusters.revokeWorkerBootstrap", + "summary": "Revoke worker bootstrap", + "description": "Starts an asynchronous revoke of a worker bootstrap token. The bootstrap is soft-revoked immediately; k0s token invalidation completes when the managed control plane is reachable.", "security": [ { "BearerAuth": [] @@ -36777,6 +53906,16 @@ "name": "id", "in": "path" }, + { + "schema": { + "type": "string", + "minLength": 1, + "maxLength": 54 + }, + "required": true, + "name": "wbs_id", + "in": "path" + }, { "schema": { "type": "string", @@ -36795,11 +53934,11 @@ "type": "string", "minLength": 1, "maxLength": 64, - "description": "Caller-supplied idempotency key. Repeated requests with the same key return the existing resource instead of creating a duplicate. Safe to retry after a timed-out or interrupted request.", + "description": "Optional caller-supplied idempotency key. Any non-empty key up to 64 characters is accepted. Endpoint-specific documentation describes how the key is used.", "example": "create-prod-2026-05-07" }, "required": false, - "description": "Caller-supplied idempotency key. Repeated requests with the same key return the existing resource instead of creating a duplicate. Safe to retry after a timed-out or interrupted request.", + "description": "Optional caller-supplied idempotency key. Any non-empty key up to 64 characters is accepted. Endpoint-specific documentation describes how the key is used.", "name": "idempotency-key", "in": "header" }, @@ -36817,22 +53956,13 @@ "in": "header" } ], - "requestBody": { - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/ExecBody" - } - } - } - }, "responses": { - "200": { - "description": "Command output", + "202": { + "description": "Revoke initiated", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/ExecResult" + "$ref": "#/components/schemas/Operation" } } } @@ -36880,91 +54010,1964 @@ } } }, - "/v1/clusters/{id}/worker_bootstraps": { - "post": { - "x-platform-visibility": "PUBLIC", + "/v1/user/admin_status": { + "get": { + "x-platform-visibility": "ADMIN", + "operationId": "auth.getAdminStatus", "tags": [ - "Clusters" + "Auth" ], - "operationId": "clusters.createWorkerBootstrap", - "summary": "Create worker bootstrap", - "description": "Issues a new worker-bootstrap row and returns its metadata.", + "summary": "Get current admin status", + "description": "Returns whether the authenticated user has platform administrator access in the dashboard.", + "security": [ + { + "BearerAuth": [] + } + ], + "responses": { + "200": { + "description": "Current admin status", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/AdminStatus" + } + } + } + }, + "401": { + "description": "Unauthorized", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } + } + } + } + } + } + }, + "/v1/dashboard/counts": { + "get": { + "x-platform-visibility": "INTERNAL", + "x-platform-live": { + "visibility": "INTERNAL", + "transport": "convex", + "convexQuery": "ui.getDashboardCountsForApi" + }, + "operationId": "dashboard.getCounts", + "tags": [ + "Dashboard Overview" + ], + "summary": "Get dashboard counts", + "description": "Returns aggregate dashboard counts for the selected workspace scope.", + "security": [ + { + "BearerAuth": [] + } + ], + "responses": { + "200": { + "description": "Dashboard counts", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/DashboardCounts" + } + } + } + }, + "401": { + "description": "Unauthorized", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } + } + } + } + } + } + }, + "/v1/dashboard/metrics": { + "get": { + "x-platform-visibility": "INTERNAL", + "operationId": "dashboard.getMetrics", + "tags": [ + "Dashboard Overview" + ], + "summary": "Get dashboard overview metrics", + "description": "Returns independently resolved metric results for the active workspace and selected filters.", "security": [ { "BearerAuth": [] } ], "parameters": [ + { + "schema": { + "anyOf": [ + { + "type": "string", + "enum": [ + "needs_attention", + "install_health", + "active_products", + "capacity_pressure", + "operation_outcomes", + "new_installs", + "cluster_health", + "recent_issues", + "recent_activity" + ] + }, + { + "type": "array", + "items": { + "type": "string", + "enum": [ + "needs_attention", + "install_health", + "active_products", + "capacity_pressure", + "operation_outcomes", + "new_installs", + "cluster_health", + "recent_issues", + "recent_activity" + ] + } + } + ] + }, + "required": true, + "name": "metric_key", + "in": "query" + }, { "schema": { "type": "string", - "minLength": 1, - "maxLength": 54 + "pattern": "^(0|[1-9]\\d*)$" }, "required": true, - "name": "id", - "in": "path" + "name": "from", + "in": "query" }, { "schema": { "type": "string", - "minLength": 1, - "maxLength": 53, - "description": "Optional workspace/scope context for the request. Carries a single workspace wire id (`ws_…`) today. Only needed for broad tokens — a workspace-owned token implies its workspace.", - "example": "ws_j572abc123def456" + "pattern": "^(0|[1-9]\\d*)$" + }, + "required": true, + "name": "to", + "in": "query" + }, + { + "schema": { + "type": "string", + "enum": [ + "true", + "false" + ] }, "required": false, - "description": "Optional workspace/scope context for the request. Carries a single workspace wire id (`ws_…`) today. Only needed for broad tokens — a workspace-owned token implies its workspace.", - "name": "akua-context", - "in": "header" + "name": "compare", + "in": "query" + }, + { + "schema": { + "type": "array", + "items": { + "type": "string", + "minLength": 1, + "maxLength": 54 + }, + "maxItems": 100 + }, + "required": false, + "name": "cluster", + "in": "query" + }, + { + "schema": { + "type": "array", + "items": { + "type": "string", + "minLength": 1, + "maxLength": 55 + }, + "maxItems": 100 + }, + "required": false, + "name": "install", + "in": "query" + }, + { + "schema": { + "type": "array", + "items": { + "type": "string", + "minLength": 1, + "maxLength": 55 + }, + "maxItems": 100 + }, + "required": false, + "name": "product", + "in": "query" + }, + { + "schema": { + "type": "array", + "items": { + "type": "string", + "minLength": 1, + "maxLength": 54 + }, + "maxItems": 100 + }, + "required": false, + "name": "package", + "in": "query" + }, + { + "schema": { + "type": "array", + "items": { + "type": "string", + "minLength": 1, + "maxLength": 54 + }, + "maxItems": 100 + }, + "required": false, + "name": "region", + "in": "query" + }, + { + "schema": { + "anyOf": [ + { + "type": "string", + "enum": [ + "ready", + "attention", + "unknown", + "degraded", + "unavailable", + "succeeded", + "failed", + "canceled", + "running" + ] + }, + { + "type": "array", + "items": { + "type": "string", + "enum": [ + "ready", + "attention", + "unknown", + "degraded", + "unavailable", + "succeeded", + "failed", + "canceled", + "running" + ] + } + } + ] + }, + "required": false, + "name": "status", + "in": "query" }, { "schema": { "type": "string", "minLength": 1, - "maxLength": 64, - "description": "Caller-supplied idempotency key. Repeated requests with the same key return the existing resource instead of creating a duplicate. Safe to retry after a timed-out or interrupted request.", - "example": "create-prod-2026-05-07" + "maxLength": 53, + "description": "Optional workspace/scope context for the request. Carries a single workspace wire id (`ws_…`) today. Only needed for broad tokens — a workspace-owned token implies its workspace.", + "example": "ws_j572abc123def456" }, "required": false, - "description": "Caller-supplied idempotency key. Repeated requests with the same key return the existing resource instead of creating a duplicate. Safe to retry after a timed-out or interrupted request.", - "name": "idempotency-key", + "description": "Optional workspace/scope context for the request. Carries a single workspace wire id (`ws_…`) today. Only needed for broad tokens — a workspace-owned token implies its workspace.", + "name": "akua-context", "in": "header" } ], - "requestBody": { - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "ttl_seconds": { - "type": "integer", - "minimum": 60, - "maximum": 86400, - "description": "Token TTL in seconds (optional)." - } - }, - "additionalProperties": false - } - } - } - }, "responses": { - "201": { - "description": "Worker bootstrap created", - "headers": { - "Location": { - "description": "Location of the created worker bootstrap.", - "schema": { - "type": "string" - } - } - }, + "200": { + "description": "Dashboard overview metrics", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/WorkerBootstrap" + "type": "object", + "properties": { + "contract_version": { + "type": "number", + "enum": [ + 1 + ] + }, + "range": { + "type": "object", + "properties": { + "from": { + "type": "integer", + "minimum": 0 + }, + "to": { + "type": "integer", + "minimum": 0 + } + }, + "required": [ + "from", + "to" + ], + "additionalProperties": false + }, + "comparison_range": { + "type": "object", + "nullable": true, + "properties": { + "from": { + "type": "integer", + "minimum": 0 + }, + "to": { + "type": "integer", + "minimum": 0 + } + }, + "required": [ + "from", + "to" + ], + "additionalProperties": false + }, + "metrics": { + "type": "array", + "items": { + "oneOf": [ + { + "type": "object", + "properties": { + "metric_key": { + "type": "string", + "enum": [ + "needs_attention", + "install_health", + "active_products", + "capacity_pressure", + "operation_outcomes", + "new_installs", + "cluster_health", + "recent_issues", + "recent_activity" + ] + }, + "metric_version": { + "type": "integer", + "minimum": 0, + "exclusiveMinimum": true + }, + "time_semantics": { + "type": "string", + "enum": [ + "current", + "range", + "mixed" + ] + }, + "observed_at": { + "type": "integer", + "minimum": 0 + }, + "result": { + "oneOf": [ + { + "type": "object", + "properties": { + "contract_version": { + "type": "number", + "enum": [ + 1 + ] + }, + "type": { + "type": "string", + "enum": [ + "scalar" + ] + }, + "value": { + "anyOf": [ + { + "type": "string", + "maxLength": 16384 + }, + { + "type": "number" + }, + { + "type": "boolean" + }, + { + "nullable": true + } + ] + }, + "unit": { + "type": "string", + "minLength": 1, + "maxLength": 64 + }, + "definition": { + "type": "string", + "minLength": 1, + "maxLength": 500 + }, + "timestamp": { + "type": "integer", + "minimum": 0 + }, + "history": { + "type": "array", + "items": { + "type": "object", + "properties": { + "timestamp": { + "type": "integer", + "minimum": 0 + }, + "value": { + "type": "number", + "nullable": true + } + }, + "required": [ + "timestamp", + "value" + ], + "additionalProperties": false + }, + "maxItems": 2000 + } + }, + "required": [ + "contract_version", + "type", + "value" + ], + "additionalProperties": false + }, + { + "type": "object", + "properties": { + "contract_version": { + "type": "number", + "enum": [ + 1 + ] + }, + "type": { + "type": "string", + "enum": [ + "timeseries" + ] + }, + "series": { + "type": "array", + "items": { + "type": "object", + "properties": { + "key": { + "type": "string", + "minLength": 1, + "maxLength": 64, + "pattern": "^[a-z][a-z0-9]*(?:_[a-z0-9]+)*$" + }, + "label": { + "type": "string", + "minLength": 1, + "maxLength": 200 + }, + "unit": { + "type": "string", + "minLength": 1, + "maxLength": 64 + }, + "definition": { + "type": "string", + "minLength": 1, + "maxLength": 500 + } + }, + "required": [ + "key", + "label" + ], + "additionalProperties": false + }, + "minItems": 1, + "maxItems": 8 + }, + "points": { + "type": "array", + "items": { + "type": "object", + "properties": { + "timestamp": { + "type": "integer", + "minimum": 0 + }, + "values": { + "type": "array", + "items": { + "type": "number", + "nullable": true + }, + "maxItems": 8 + } + }, + "required": [ + "timestamp", + "values" + ], + "additionalProperties": false + }, + "maxItems": 2000 + } + }, + "required": [ + "contract_version", + "type", + "series", + "points" + ], + "additionalProperties": false + }, + { + "type": "object", + "properties": { + "contract_version": { + "type": "number", + "enum": [ + 1 + ] + }, + "type": { + "type": "string", + "enum": [ + "categorical" + ] + }, + "series": { + "type": "array", + "items": { + "type": "object", + "properties": { + "key": { + "type": "string", + "minLength": 1, + "maxLength": 64, + "pattern": "^[a-z][a-z0-9]*(?:_[a-z0-9]+)*$" + }, + "label": { + "type": "string", + "minLength": 1, + "maxLength": 200 + }, + "unit": { + "type": "string", + "minLength": 1, + "maxLength": 64 + }, + "definition": { + "type": "string", + "minLength": 1, + "maxLength": 500 + } + }, + "required": [ + "key", + "label" + ], + "additionalProperties": false + }, + "minItems": 1, + "maxItems": 8 + }, + "categories": { + "type": "array", + "items": { + "type": "object", + "properties": { + "key": { + "type": "string", + "minLength": 1, + "maxLength": 64, + "pattern": "^[a-z][a-z0-9]*(?:_[a-z0-9]+)*$" + }, + "label": { + "type": "string", + "minLength": 1, + "maxLength": 200 + } + }, + "required": [ + "key", + "label" + ], + "additionalProperties": false + }, + "maxItems": 100 + }, + "values": { + "type": "array", + "items": { + "type": "array", + "items": { + "type": "number", + "nullable": true + }, + "maxItems": 8 + }, + "maxItems": 100 + } + }, + "required": [ + "contract_version", + "type", + "series", + "categories", + "values" + ], + "additionalProperties": false + }, + { + "type": "object", + "properties": { + "contract_version": { + "type": "number", + "enum": [ + 1 + ] + }, + "type": { + "type": "string", + "enum": [ + "status_list" + ] + }, + "items": { + "type": "array", + "items": { + "type": "object", + "properties": { + "key": { + "type": "string", + "minLength": 1, + "maxLength": 64, + "pattern": "^[a-z][a-z0-9]*(?:_[a-z0-9]+)*$" + }, + "label": { + "type": "string", + "minLength": 1, + "maxLength": 200 + }, + "severity": { + "type": "string", + "enum": [ + "info", + "success", + "warning", + "critical", + "unknown" + ] + }, + "detail": { + "type": "string", + "maxLength": 16384 + }, + "timestamp": { + "type": "integer", + "minimum": 0 + }, + "link": { + "type": "string", + "minLength": 1, + "maxLength": 2048 + } + }, + "required": [ + "key", + "label", + "severity" + ], + "additionalProperties": false + }, + "maxItems": 200 + } + }, + "required": [ + "contract_version", + "type", + "items" + ], + "additionalProperties": false + } + ] + }, + "comparison_result": { + "oneOf": [ + { + "type": "object", + "properties": { + "contract_version": { + "type": "number", + "enum": [ + 1 + ] + }, + "type": { + "type": "string", + "enum": [ + "scalar" + ] + }, + "value": { + "anyOf": [ + { + "type": "string", + "maxLength": 16384 + }, + { + "type": "number" + }, + { + "type": "boolean" + }, + { + "nullable": true + } + ] + }, + "unit": { + "type": "string", + "minLength": 1, + "maxLength": 64 + }, + "definition": { + "type": "string", + "minLength": 1, + "maxLength": 500 + }, + "timestamp": { + "type": "integer", + "minimum": 0 + }, + "history": { + "type": "array", + "items": { + "type": "object", + "properties": { + "timestamp": { + "type": "integer", + "minimum": 0 + }, + "value": { + "type": "number", + "nullable": true + } + }, + "required": [ + "timestamp", + "value" + ], + "additionalProperties": false + }, + "maxItems": 2000 + } + }, + "required": [ + "contract_version", + "type", + "value" + ], + "additionalProperties": false + }, + { + "type": "object", + "properties": { + "contract_version": { + "type": "number", + "enum": [ + 1 + ] + }, + "type": { + "type": "string", + "enum": [ + "timeseries" + ] + }, + "series": { + "type": "array", + "items": { + "type": "object", + "properties": { + "key": { + "type": "string", + "minLength": 1, + "maxLength": 64, + "pattern": "^[a-z][a-z0-9]*(?:_[a-z0-9]+)*$" + }, + "label": { + "type": "string", + "minLength": 1, + "maxLength": 200 + }, + "unit": { + "type": "string", + "minLength": 1, + "maxLength": 64 + }, + "definition": { + "type": "string", + "minLength": 1, + "maxLength": 500 + } + }, + "required": [ + "key", + "label" + ], + "additionalProperties": false + }, + "minItems": 1, + "maxItems": 8 + }, + "points": { + "type": "array", + "items": { + "type": "object", + "properties": { + "timestamp": { + "type": "integer", + "minimum": 0 + }, + "values": { + "type": "array", + "items": { + "type": "number", + "nullable": true + }, + "maxItems": 8 + } + }, + "required": [ + "timestamp", + "values" + ], + "additionalProperties": false + }, + "maxItems": 2000 + } + }, + "required": [ + "contract_version", + "type", + "series", + "points" + ], + "additionalProperties": false + }, + { + "type": "object", + "properties": { + "contract_version": { + "type": "number", + "enum": [ + 1 + ] + }, + "type": { + "type": "string", + "enum": [ + "categorical" + ] + }, + "series": { + "type": "array", + "items": { + "type": "object", + "properties": { + "key": { + "type": "string", + "minLength": 1, + "maxLength": 64, + "pattern": "^[a-z][a-z0-9]*(?:_[a-z0-9]+)*$" + }, + "label": { + "type": "string", + "minLength": 1, + "maxLength": 200 + }, + "unit": { + "type": "string", + "minLength": 1, + "maxLength": 64 + }, + "definition": { + "type": "string", + "minLength": 1, + "maxLength": 500 + } + }, + "required": [ + "key", + "label" + ], + "additionalProperties": false + }, + "minItems": 1, + "maxItems": 8 + }, + "categories": { + "type": "array", + "items": { + "type": "object", + "properties": { + "key": { + "type": "string", + "minLength": 1, + "maxLength": 64, + "pattern": "^[a-z][a-z0-9]*(?:_[a-z0-9]+)*$" + }, + "label": { + "type": "string", + "minLength": 1, + "maxLength": 200 + } + }, + "required": [ + "key", + "label" + ], + "additionalProperties": false + }, + "maxItems": 100 + }, + "values": { + "type": "array", + "items": { + "type": "array", + "items": { + "type": "number", + "nullable": true + }, + "maxItems": 8 + }, + "maxItems": 100 + } + }, + "required": [ + "contract_version", + "type", + "series", + "categories", + "values" + ], + "additionalProperties": false + }, + { + "type": "object", + "properties": { + "contract_version": { + "type": "number", + "enum": [ + 1 + ] + }, + "type": { + "type": "string", + "enum": [ + "status_list" + ] + }, + "items": { + "type": "array", + "items": { + "type": "object", + "properties": { + "key": { + "type": "string", + "minLength": 1, + "maxLength": 64, + "pattern": "^[a-z][a-z0-9]*(?:_[a-z0-9]+)*$" + }, + "label": { + "type": "string", + "minLength": 1, + "maxLength": 200 + }, + "severity": { + "type": "string", + "enum": [ + "info", + "success", + "warning", + "critical", + "unknown" + ] + }, + "detail": { + "type": "string", + "maxLength": 16384 + }, + "timestamp": { + "type": "integer", + "minimum": 0 + }, + "link": { + "type": "string", + "minLength": 1, + "maxLength": 2048 + } + }, + "required": [ + "key", + "label", + "severity" + ], + "additionalProperties": false + }, + "maxItems": 200 + } + }, + "required": [ + "contract_version", + "type", + "items" + ], + "additionalProperties": false + }, + { + "nullable": true + } + ] + }, + "completeness": { + "type": "string", + "enum": [ + "complete" + ] + }, + "unavailable_reason": { + "nullable": true + } + }, + "required": [ + "metric_key", + "metric_version", + "time_semantics", + "observed_at", + "result", + "comparison_result", + "completeness", + "unavailable_reason" + ], + "additionalProperties": false + }, + { + "type": "object", + "properties": { + "metric_key": { + "type": "string", + "enum": [ + "needs_attention", + "install_health", + "active_products", + "capacity_pressure", + "operation_outcomes", + "new_installs", + "cluster_health", + "recent_issues", + "recent_activity" + ] + }, + "metric_version": { + "type": "integer", + "minimum": 0, + "exclusiveMinimum": true + }, + "time_semantics": { + "type": "string", + "enum": [ + "current", + "range", + "mixed" + ] + }, + "observed_at": { + "type": "integer", + "minimum": 0 + }, + "result": { + "oneOf": [ + { + "type": "object", + "properties": { + "contract_version": { + "type": "number", + "enum": [ + 1 + ] + }, + "type": { + "type": "string", + "enum": [ + "scalar" + ] + }, + "value": { + "anyOf": [ + { + "type": "string", + "maxLength": 16384 + }, + { + "type": "number" + }, + { + "type": "boolean" + }, + { + "nullable": true + } + ] + }, + "unit": { + "type": "string", + "minLength": 1, + "maxLength": 64 + }, + "definition": { + "type": "string", + "minLength": 1, + "maxLength": 500 + }, + "timestamp": { + "type": "integer", + "minimum": 0 + }, + "history": { + "type": "array", + "items": { + "type": "object", + "properties": { + "timestamp": { + "type": "integer", + "minimum": 0 + }, + "value": { + "type": "number", + "nullable": true + } + }, + "required": [ + "timestamp", + "value" + ], + "additionalProperties": false + }, + "maxItems": 2000 + } + }, + "required": [ + "contract_version", + "type", + "value" + ], + "additionalProperties": false + }, + { + "type": "object", + "properties": { + "contract_version": { + "type": "number", + "enum": [ + 1 + ] + }, + "type": { + "type": "string", + "enum": [ + "timeseries" + ] + }, + "series": { + "type": "array", + "items": { + "type": "object", + "properties": { + "key": { + "type": "string", + "minLength": 1, + "maxLength": 64, + "pattern": "^[a-z][a-z0-9]*(?:_[a-z0-9]+)*$" + }, + "label": { + "type": "string", + "minLength": 1, + "maxLength": 200 + }, + "unit": { + "type": "string", + "minLength": 1, + "maxLength": 64 + }, + "definition": { + "type": "string", + "minLength": 1, + "maxLength": 500 + } + }, + "required": [ + "key", + "label" + ], + "additionalProperties": false + }, + "minItems": 1, + "maxItems": 8 + }, + "points": { + "type": "array", + "items": { + "type": "object", + "properties": { + "timestamp": { + "type": "integer", + "minimum": 0 + }, + "values": { + "type": "array", + "items": { + "type": "number", + "nullable": true + }, + "maxItems": 8 + } + }, + "required": [ + "timestamp", + "values" + ], + "additionalProperties": false + }, + "maxItems": 2000 + } + }, + "required": [ + "contract_version", + "type", + "series", + "points" + ], + "additionalProperties": false + }, + { + "type": "object", + "properties": { + "contract_version": { + "type": "number", + "enum": [ + 1 + ] + }, + "type": { + "type": "string", + "enum": [ + "categorical" + ] + }, + "series": { + "type": "array", + "items": { + "type": "object", + "properties": { + "key": { + "type": "string", + "minLength": 1, + "maxLength": 64, + "pattern": "^[a-z][a-z0-9]*(?:_[a-z0-9]+)*$" + }, + "label": { + "type": "string", + "minLength": 1, + "maxLength": 200 + }, + "unit": { + "type": "string", + "minLength": 1, + "maxLength": 64 + }, + "definition": { + "type": "string", + "minLength": 1, + "maxLength": 500 + } + }, + "required": [ + "key", + "label" + ], + "additionalProperties": false + }, + "minItems": 1, + "maxItems": 8 + }, + "categories": { + "type": "array", + "items": { + "type": "object", + "properties": { + "key": { + "type": "string", + "minLength": 1, + "maxLength": 64, + "pattern": "^[a-z][a-z0-9]*(?:_[a-z0-9]+)*$" + }, + "label": { + "type": "string", + "minLength": 1, + "maxLength": 200 + } + }, + "required": [ + "key", + "label" + ], + "additionalProperties": false + }, + "maxItems": 100 + }, + "values": { + "type": "array", + "items": { + "type": "array", + "items": { + "type": "number", + "nullable": true + }, + "maxItems": 8 + }, + "maxItems": 100 + } + }, + "required": [ + "contract_version", + "type", + "series", + "categories", + "values" + ], + "additionalProperties": false + }, + { + "type": "object", + "properties": { + "contract_version": { + "type": "number", + "enum": [ + 1 + ] + }, + "type": { + "type": "string", + "enum": [ + "status_list" + ] + }, + "items": { + "type": "array", + "items": { + "type": "object", + "properties": { + "key": { + "type": "string", + "minLength": 1, + "maxLength": 64, + "pattern": "^[a-z][a-z0-9]*(?:_[a-z0-9]+)*$" + }, + "label": { + "type": "string", + "minLength": 1, + "maxLength": 200 + }, + "severity": { + "type": "string", + "enum": [ + "info", + "success", + "warning", + "critical", + "unknown" + ] + }, + "detail": { + "type": "string", + "maxLength": 16384 + }, + "timestamp": { + "type": "integer", + "minimum": 0 + }, + "link": { + "type": "string", + "minLength": 1, + "maxLength": 2048 + } + }, + "required": [ + "key", + "label", + "severity" + ], + "additionalProperties": false + }, + "maxItems": 200 + } + }, + "required": [ + "contract_version", + "type", + "items" + ], + "additionalProperties": false + } + ] + }, + "comparison_result": { + "oneOf": [ + { + "type": "object", + "properties": { + "contract_version": { + "type": "number", + "enum": [ + 1 + ] + }, + "type": { + "type": "string", + "enum": [ + "scalar" + ] + }, + "value": { + "anyOf": [ + { + "type": "string", + "maxLength": 16384 + }, + { + "type": "number" + }, + { + "type": "boolean" + }, + { + "nullable": true + } + ] + }, + "unit": { + "type": "string", + "minLength": 1, + "maxLength": 64 + }, + "definition": { + "type": "string", + "minLength": 1, + "maxLength": 500 + }, + "timestamp": { + "type": "integer", + "minimum": 0 + }, + "history": { + "type": "array", + "items": { + "type": "object", + "properties": { + "timestamp": { + "type": "integer", + "minimum": 0 + }, + "value": { + "type": "number", + "nullable": true + } + }, + "required": [ + "timestamp", + "value" + ], + "additionalProperties": false + }, + "maxItems": 2000 + } + }, + "required": [ + "contract_version", + "type", + "value" + ], + "additionalProperties": false + }, + { + "type": "object", + "properties": { + "contract_version": { + "type": "number", + "enum": [ + 1 + ] + }, + "type": { + "type": "string", + "enum": [ + "timeseries" + ] + }, + "series": { + "type": "array", + "items": { + "type": "object", + "properties": { + "key": { + "type": "string", + "minLength": 1, + "maxLength": 64, + "pattern": "^[a-z][a-z0-9]*(?:_[a-z0-9]+)*$" + }, + "label": { + "type": "string", + "minLength": 1, + "maxLength": 200 + }, + "unit": { + "type": "string", + "minLength": 1, + "maxLength": 64 + }, + "definition": { + "type": "string", + "minLength": 1, + "maxLength": 500 + } + }, + "required": [ + "key", + "label" + ], + "additionalProperties": false + }, + "minItems": 1, + "maxItems": 8 + }, + "points": { + "type": "array", + "items": { + "type": "object", + "properties": { + "timestamp": { + "type": "integer", + "minimum": 0 + }, + "values": { + "type": "array", + "items": { + "type": "number", + "nullable": true + }, + "maxItems": 8 + } + }, + "required": [ + "timestamp", + "values" + ], + "additionalProperties": false + }, + "maxItems": 2000 + } + }, + "required": [ + "contract_version", + "type", + "series", + "points" + ], + "additionalProperties": false + }, + { + "type": "object", + "properties": { + "contract_version": { + "type": "number", + "enum": [ + 1 + ] + }, + "type": { + "type": "string", + "enum": [ + "categorical" + ] + }, + "series": { + "type": "array", + "items": { + "type": "object", + "properties": { + "key": { + "type": "string", + "minLength": 1, + "maxLength": 64, + "pattern": "^[a-z][a-z0-9]*(?:_[a-z0-9]+)*$" + }, + "label": { + "type": "string", + "minLength": 1, + "maxLength": 200 + }, + "unit": { + "type": "string", + "minLength": 1, + "maxLength": 64 + }, + "definition": { + "type": "string", + "minLength": 1, + "maxLength": 500 + } + }, + "required": [ + "key", + "label" + ], + "additionalProperties": false + }, + "minItems": 1, + "maxItems": 8 + }, + "categories": { + "type": "array", + "items": { + "type": "object", + "properties": { + "key": { + "type": "string", + "minLength": 1, + "maxLength": 64, + "pattern": "^[a-z][a-z0-9]*(?:_[a-z0-9]+)*$" + }, + "label": { + "type": "string", + "minLength": 1, + "maxLength": 200 + } + }, + "required": [ + "key", + "label" + ], + "additionalProperties": false + }, + "maxItems": 100 + }, + "values": { + "type": "array", + "items": { + "type": "array", + "items": { + "type": "number", + "nullable": true + }, + "maxItems": 8 + }, + "maxItems": 100 + } + }, + "required": [ + "contract_version", + "type", + "series", + "categories", + "values" + ], + "additionalProperties": false + }, + { + "type": "object", + "properties": { + "contract_version": { + "type": "number", + "enum": [ + 1 + ] + }, + "type": { + "type": "string", + "enum": [ + "status_list" + ] + }, + "items": { + "type": "array", + "items": { + "type": "object", + "properties": { + "key": { + "type": "string", + "minLength": 1, + "maxLength": 64, + "pattern": "^[a-z][a-z0-9]*(?:_[a-z0-9]+)*$" + }, + "label": { + "type": "string", + "minLength": 1, + "maxLength": 200 + }, + "severity": { + "type": "string", + "enum": [ + "info", + "success", + "warning", + "critical", + "unknown" + ] + }, + "detail": { + "type": "string", + "maxLength": 16384 + }, + "timestamp": { + "type": "integer", + "minimum": 0 + }, + "link": { + "type": "string", + "minLength": 1, + "maxLength": 2048 + } + }, + "required": [ + "key", + "label", + "severity" + ], + "additionalProperties": false + }, + "maxItems": 200 + } + }, + "required": [ + "contract_version", + "type", + "items" + ], + "additionalProperties": false + }, + { + "nullable": true + } + ] + }, + "completeness": { + "type": "string", + "enum": [ + "partial" + ] + }, + "unavailable_reason": { + "type": "string", + "enum": [ + "source_unavailable", + "query_limit_exceeded", + "dependency_missing", + "invalid_source_data", + "internal_error" + ] + } + }, + "required": [ + "metric_key", + "metric_version", + "time_semantics", + "observed_at", + "result", + "comparison_result", + "completeness", + "unavailable_reason" + ], + "additionalProperties": false + }, + { + "type": "object", + "properties": { + "metric_key": { + "type": "string", + "enum": [ + "needs_attention", + "install_health", + "active_products", + "capacity_pressure", + "operation_outcomes", + "new_installs", + "cluster_health", + "recent_issues", + "recent_activity" + ] + }, + "metric_version": { + "type": "integer", + "minimum": 0, + "exclusiveMinimum": true + }, + "time_semantics": { + "type": "string", + "enum": [ + "current", + "range", + "mixed" + ] + }, + "completeness": { + "type": "string", + "enum": [ + "no_data" + ] + }, + "observed_at": { + "type": "integer", + "minimum": 0 + }, + "result": { + "nullable": true + }, + "comparison_result": { + "nullable": true + }, + "unavailable_reason": { + "nullable": true + } + }, + "required": [ + "metric_key", + "metric_version", + "time_semantics", + "completeness", + "observed_at", + "result", + "comparison_result", + "unavailable_reason" + ], + "additionalProperties": false + }, + { + "type": "object", + "properties": { + "metric_key": { + "type": "string", + "enum": [ + "needs_attention", + "install_health", + "active_products", + "capacity_pressure", + "operation_outcomes", + "new_installs", + "cluster_health", + "recent_issues", + "recent_activity" + ] + }, + "metric_version": { + "type": "integer", + "minimum": 0, + "exclusiveMinimum": true + }, + "time_semantics": { + "type": "string", + "enum": [ + "current", + "range", + "mixed" + ] + }, + "completeness": { + "type": "string", + "enum": [ + "unavailable" + ] + }, + "observed_at": { + "nullable": true + }, + "result": { + "nullable": true + }, + "comparison_result": { + "nullable": true + }, + "unavailable_reason": { + "type": "string", + "enum": [ + "source_unavailable", + "not_applicable", + "query_limit_exceeded", + "dependency_missing", + "invalid_source_data", + "internal_error" + ] + } + }, + "required": [ + "metric_key", + "metric_version", + "time_semantics", + "completeness", + "observed_at", + "result", + "comparison_result", + "unavailable_reason" + ], + "additionalProperties": false + } + ] + }, + "minItems": 1, + "maxItems": 9 + } + }, + "required": [ + "contract_version", + "range", + "comparison_range", + "metrics" + ], + "additionalProperties": false } } } @@ -36988,48 +55991,30 @@ } } } - }, - "404": { - "description": "Not found", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/ApiErrorResponse" - } - } - } } } - }, + } + }, + "/v1/organizations": { "get": { "x-platform-visibility": "PUBLIC", "x-platform-live": { "visibility": "INTERNAL", "transport": "convex", - "convexQuery": "cluster.ui.listWorkerBootstrapsByClusterForApi" + "convexQuery": "organization.ui.listMyOrganizationsForApi" }, + "operationId": "organizations.list", "tags": [ - "Clusters" + "Organizations" ], - "operationId": "clusters.listWorkerBootstraps", - "summary": "List cluster worker bootstraps", - "description": "Lists worker-bootstrap tokens for the cluster. Cursor-paginated. Includes revoked / expired tokens by default — filter via the `status` query when implemented.", + "summary": "List organizations", + "description": "Lists all organizations the authenticated user belongs to.", "security": [ { "BearerAuth": [] } ], "parameters": [ - { - "schema": { - "type": "string", - "minLength": 1, - "maxLength": 54 - }, - "required": true, - "name": "id", - "in": "path" - }, { "schema": { "type": "string", @@ -37053,28 +56038,15 @@ "description": "Items per page (1-100, default 50)", "name": "limit", "in": "query" - }, - { - "schema": { - "type": "string", - "minLength": 1, - "maxLength": 53, - "description": "Optional workspace/scope context for the request. Carries a single workspace wire id (`ws_…`) today. Only needed for broad tokens — a workspace-owned token implies its workspace.", - "example": "ws_j572abc123def456" - }, - "required": false, - "description": "Optional workspace/scope context for the request. Carries a single workspace wire id (`ws_…`) today. Only needed for broad tokens — a workspace-owned token implies its workspace.", - "name": "akua-context", - "in": "header" } ], "responses": { "200": { - "description": "Worker bootstraps page", + "description": "List of organizations", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/WorkerBootstrapList" + "$ref": "#/components/schemas/OrganizationList" } } } @@ -37088,9 +56060,59 @@ } } } + } + } + }, + "post": { + "x-platform-visibility": "PUBLIC", + "operationId": "organizations.create", + "tags": [ + "Organizations" + ], + "summary": "Create organization", + "description": "Creates a new organization. The authenticated user becomes the initial owner.", + "security": [ + { + "BearerAuth": [] + } + ], + "parameters": [ + { + "schema": { + "type": "string", + "minLength": 1, + "maxLength": 64, + "description": "Optional caller-supplied idempotency key. Any non-empty key up to 64 characters is accepted. Endpoint-specific documentation describes how the key is used.", + "example": "create-prod-2026-05-07" + }, + "required": false, + "description": "Optional caller-supplied idempotency key. Any non-empty key up to 64 characters is accepted. Endpoint-specific documentation describes how the key is used.", + "name": "idempotency-key", + "in": "header" + } + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/OrganizationCreateRequest" + } + } + } + }, + "responses": { + "201": { + "description": "Organization created", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Organization" + } + } + } }, - "403": { - "description": "Forbidden", + "400": { + "description": "Bad request", "content": { "application/json": { "schema": { @@ -37099,8 +56121,8 @@ } } }, - "404": { - "description": "Not found", + "401": { + "description": "Unauthorized", "content": { "application/json": { "schema": { @@ -37112,15 +56134,15 @@ } } }, - "/v1/clusters/{id}/worker_bootstraps/{wbs_id}": { + "/v1/organizations/{id}": { "get": { "x-platform-visibility": "PUBLIC", + "operationId": "organizations.get", "tags": [ - "Clusters" + "Organizations" ], - "operationId": "clusters.getWorkerBootstrap", - "summary": "Get cluster worker bootstrap", - "description": "Returns a single worker-bootstrap token by ID, including its current status and expiry timestamp.", + "summary": "Get organization details", + "description": "Returns details for an organization the authenticated user belongs to.", "security": [ { "BearerAuth": [] @@ -37131,43 +56153,23 @@ "schema": { "type": "string", "minLength": 1, - "maxLength": 54 + "maxLength": 54, + "description": "Organization ID. Prefixed form `org_` is canonical.", + "example": "org_j572abc123def456" }, "required": true, + "description": "Organization ID. Prefixed form `org_` is canonical.", "name": "id", "in": "path" - }, - { - "schema": { - "type": "string", - "minLength": 1, - "maxLength": 54 - }, - "required": true, - "name": "wbs_id", - "in": "path" - }, - { - "schema": { - "type": "string", - "minLength": 1, - "maxLength": 53, - "description": "Optional workspace/scope context for the request. Carries a single workspace wire id (`ws_…`) today. Only needed for broad tokens — a workspace-owned token implies its workspace.", - "example": "ws_j572abc123def456" - }, - "required": false, - "description": "Optional workspace/scope context for the request. Carries a single workspace wire id (`ws_…`) today. Only needed for broad tokens — a workspace-owned token implies its workspace.", - "name": "akua-context", - "in": "header" } ], "responses": { "200": { - "description": "Worker bootstrap", + "description": "Organization details", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/WorkerBootstrap" + "$ref": "#/components/schemas/Organization" } } } @@ -37203,17 +56205,15 @@ } } } - } - }, - "/v1/clusters/{id}/worker_bootstraps/{wbs_id}:revoke": { - "post": { + }, + "patch": { "x-platform-visibility": "PUBLIC", + "operationId": "organizations.update", "tags": [ - "Clusters" + "Organizations" ], - "operationId": "clusters.revokeWorkerBootstrap", - "summary": "Revoke worker bootstrap", - "description": "Starts an asynchronous revoke of a worker bootstrap token. The bootstrap is soft-revoked immediately; k0s token invalidation completes when the managed control plane is reachable.", + "summary": "Update organization", + "description": "Updates profile fields on an organization. Requires owner or admin role in the organization.", "security": [ { "BearerAuth": [] @@ -37224,45 +56224,25 @@ "schema": { "type": "string", "minLength": 1, - "maxLength": 54 + "maxLength": 54, + "description": "Organization ID. Prefixed form `org_` is canonical.", + "example": "org_j572abc123def456" }, "required": true, + "description": "Organization ID. Prefixed form `org_` is canonical.", "name": "id", "in": "path" }, - { - "schema": { - "type": "string", - "minLength": 1, - "maxLength": 54 - }, - "required": true, - "name": "wbs_id", - "in": "path" - }, - { - "schema": { - "type": "string", - "minLength": 1, - "maxLength": 53, - "description": "Optional workspace/scope context for the request. Carries a single workspace wire id (`ws_…`) today. Only needed for broad tokens — a workspace-owned token implies its workspace.", - "example": "ws_j572abc123def456" - }, - "required": false, - "description": "Optional workspace/scope context for the request. Carries a single workspace wire id (`ws_…`) today. Only needed for broad tokens — a workspace-owned token implies its workspace.", - "name": "akua-context", - "in": "header" - }, { "schema": { "type": "string", "minLength": 1, "maxLength": 64, - "description": "Caller-supplied idempotency key. Repeated requests with the same key return the existing resource instead of creating a duplicate. Safe to retry after a timed-out or interrupted request.", + "description": "Optional caller-supplied idempotency key. Any non-empty key up to 64 characters is accepted. Endpoint-specific documentation describes how the key is used.", "example": "create-prod-2026-05-07" }, "required": false, - "description": "Caller-supplied idempotency key. Repeated requests with the same key return the existing resource instead of creating a duplicate. Safe to retry after a timed-out or interrupted request.", + "description": "Optional caller-supplied idempotency key. Any non-empty key up to 64 characters is accepted. Endpoint-specific documentation describes how the key is used.", "name": "idempotency-key", "in": "header" }, @@ -37280,13 +56260,32 @@ "in": "header" } ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/OrganizationUpdateRequest" + } + } + } + }, "responses": { - "202": { - "description": "Revoke initiated", + "200": { + "description": "Organization updated", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/Operation" + "$ref": "#/components/schemas/OrganizationOk" + } + } + } + }, + "400": { + "description": "Bad request", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" } } } @@ -37332,29 +56331,71 @@ } } } - } - }, - "/v1/user/admin_status": { - "get": { - "x-platform-visibility": "ADMIN", - "operationId": "auth.getAdminStatus", + }, + "delete": { + "x-platform-visibility": "PUBLIC", + "operationId": "organizations.delete", "tags": [ - "Auth" + "Organizations" ], - "summary": "Get current admin status", - "description": "Returns whether the authenticated user has platform administrator access in the dashboard.", + "summary": "Delete organization", + "description": "Deletes an organization after validating membership, workspace ownership, and owner protection.", "security": [ { "BearerAuth": [] } ], + "parameters": [ + { + "schema": { + "type": "string", + "minLength": 1, + "maxLength": 54, + "description": "Organization ID. Prefixed form `org_` is canonical.", + "example": "org_j572abc123def456" + }, + "required": true, + "description": "Organization ID. Prefixed form `org_` is canonical.", + "name": "id", + "in": "path" + }, + { + "schema": { + "type": "string", + "minLength": 1, + "maxLength": 64, + "description": "Optional caller-supplied idempotency key. Any non-empty key up to 64 characters is accepted. Endpoint-specific documentation describes how the key is used.", + "example": "create-prod-2026-05-07" + }, + "required": false, + "description": "Optional caller-supplied idempotency key. Any non-empty key up to 64 characters is accepted. Endpoint-specific documentation describes how the key is used.", + "name": "idempotency-key", + "in": "header" + }, + { + "schema": { + "type": "string", + "minLength": 1, + "maxLength": 256, + "description": "The `etag` of the resource version the client last read. Required on writes when the resource exposes an `etag` field. Mismatch returns 409 `ABORTED` with the current etag in the error metadata.", + "example": "42" + }, + "required": true, + "description": "The `etag` of the resource version the client last read. Required on writes when the resource exposes an `etag` field. Mismatch returns 409 `ABORTED` with the current etag in the error metadata.", + "name": "if-match", + "in": "header" + } + ], "responses": { - "200": { - "description": "Current admin status", + "204": { + "description": "Organization deleted" + }, + "400": { + "description": "Bad request", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/AdminStatus" + "$ref": "#/components/schemas/ApiErrorResponse" } } } @@ -37368,42 +56409,19 @@ } } } - } - } - } - }, - "/v1/dashboard/counts": { - "get": { - "x-platform-visibility": "INTERNAL", - "x-platform-live": { - "visibility": "INTERNAL", - "transport": "convex", - "convexQuery": "ui.getDashboardCountsForApi" - }, - "operationId": "dashboard.getCounts", - "tags": [ - "Dashboard Overview" - ], - "summary": "Get dashboard counts", - "description": "Returns aggregate dashboard counts for the selected workspace scope.", - "security": [ - { - "BearerAuth": [] - } - ], - "responses": { - "200": { - "description": "Dashboard counts", + }, + "403": { + "description": "Forbidden", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/DashboardCounts" + "$ref": "#/components/schemas/ApiErrorResponse" } } } }, - "401": { - "description": "Unauthorized", + "404": { + "description": "Not found", "content": { "application/json": { "schema": { @@ -37415,26 +56433,39 @@ } } }, - "/v1/organizations": { + "/v1/organizations/{id}/members": { "get": { "x-platform-visibility": "PUBLIC", "x-platform-live": { "visibility": "INTERNAL", "transport": "convex", - "convexQuery": "organization.ui.listMyOrganizationsForApi" + "convexQuery": "organization.ui.listMembersForApi" }, - "operationId": "organizations.list", + "operationId": "organizations.listMembers", "tags": [ "Organizations" ], - "summary": "List organizations", - "description": "Lists all organizations the authenticated user belongs to.", + "summary": "List organization members", + "description": "Lists a page of organization members. Requires membership in the organization.", "security": [ { "BearerAuth": [] } ], "parameters": [ + { + "schema": { + "type": "string", + "minLength": 1, + "maxLength": 54, + "description": "Organization ID. Prefixed form `org_` is canonical.", + "example": "org_j572abc123def456" + }, + "required": true, + "description": "Organization ID. Prefixed form `org_` is canonical.", + "name": "id", + "in": "path" + }, { "schema": { "type": "string", @@ -37462,11 +56493,11 @@ ], "responses": { "200": { - "description": "List of organizations", + "description": "List of members", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/OrganizationList" + "$ref": "#/components/schemas/OrganizationMemberList" } } } @@ -37480,53 +56511,89 @@ } } } + }, + "403": { + "description": "Forbidden", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } + } + } } } }, "post": { "x-platform-visibility": "PUBLIC", - "operationId": "organizations.create", + "operationId": "organizations.addMember", "tags": [ "Organizations" ], - "summary": "Create organization", - "description": "Creates a new organization. The authenticated user becomes the initial owner.", + "summary": "Add organization member", + "description": "Adds a user to the organization with the supplied role (defaults to `member`). Requires owner or admin role.", "security": [ { "BearerAuth": [] } ], "parameters": [ + { + "schema": { + "type": "string", + "minLength": 1, + "maxLength": 54, + "description": "Organization ID. Prefixed form `org_` is canonical.", + "example": "org_j572abc123def456" + }, + "required": true, + "description": "Organization ID. Prefixed form `org_` is canonical.", + "name": "id", + "in": "path" + }, { "schema": { "type": "string", "minLength": 1, "maxLength": 64, - "description": "Caller-supplied idempotency key. Repeated requests with the same key return the existing resource instead of creating a duplicate. Safe to retry after a timed-out or interrupted request.", + "description": "Optional caller-supplied idempotency key. Any non-empty key up to 64 characters is accepted. Endpoint-specific documentation describes how the key is used.", "example": "create-prod-2026-05-07" }, "required": false, - "description": "Caller-supplied idempotency key. Repeated requests with the same key return the existing resource instead of creating a duplicate. Safe to retry after a timed-out or interrupted request.", + "description": "Optional caller-supplied idempotency key. Any non-empty key up to 64 characters is accepted. Endpoint-specific documentation describes how the key is used.", "name": "idempotency-key", "in": "header" + }, + { + "schema": { + "type": "string", + "minLength": 1, + "maxLength": 256, + "description": "The `etag` of the resource version the client last read. Required on writes when the resource exposes an `etag` field. Mismatch returns 409 `ABORTED` with the current etag in the error metadata.", + "example": "42" + }, + "required": true, + "description": "The `etag` of the resource version the client last read. Required on writes when the resource exposes an `etag` field. Mismatch returns 409 `ABORTED` with the current etag in the error metadata.", + "name": "if-match", + "in": "header" } ], "requestBody": { "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/OrganizationCreateRequest" + "$ref": "#/components/schemas/OrganizationAddMemberRequest" } } } }, "responses": { "201": { - "description": "Organization created", + "description": "Member added", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/Organization" + "$ref": "#/components/schemas/OrganizationOk" } } } @@ -37550,19 +56617,43 @@ } } } + }, + "403": { + "description": "Forbidden", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } + } + } + }, + "409": { + "description": "Conflict", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } + } + } } } } }, - "/v1/organizations/{id}": { + "/v1/organizations/{id}/invitations": { "get": { "x-platform-visibility": "PUBLIC", - "operationId": "organizations.get", + "x-platform-live": { + "visibility": "INTERNAL", + "transport": "convex", + "convexQuery": "organization.ui.listInvitationsForApi" + }, + "operationId": "organizations.listInvitations", "tags": [ "Organizations" ], - "summary": "Get organization details", - "description": "Returns details for an organization the authenticated user belongs to.", + "summary": "List pending organization invitations", "security": [ { "BearerAuth": [] @@ -37573,23 +56664,44 @@ "schema": { "type": "string", "minLength": 1, - "maxLength": 54, - "description": "Organization ID. Prefixed form `org_` is canonical.", - "example": "org_j572abc123def456" + "maxLength": 54 }, "required": true, - "description": "Organization ID. Prefixed form `org_` is canonical.", "name": "id", "in": "path" + }, + { + "schema": { + "type": "string", + "description": "Pagination cursor from a previous response's `next_cursor`." + }, + "required": false, + "description": "Pagination cursor from a previous response's `next_cursor`.", + "name": "cursor", + "in": "query" + }, + { + "schema": { + "type": "integer", + "minimum": 1, + "maximum": 100, + "default": 50, + "description": "Items per page (1-100, default 50)", + "example": 50 + }, + "required": false, + "description": "Items per page (1-100, default 50)", + "name": "limit", + "in": "query" } ], "responses": { "200": { - "description": "Organization details", + "description": "Pending invitations", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/Organization" + "$ref": "#/components/schemas/OrganizationInvitationList" } } } @@ -37613,27 +56725,16 @@ } } } - }, - "404": { - "description": "Not found", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/ApiErrorResponse" - } - } - } } } }, - "patch": { + "post": { "x-platform-visibility": "PUBLIC", - "operationId": "organizations.update", + "operationId": "organizations.createInvitation", "tags": [ "Organizations" ], - "summary": "Update organization", - "description": "Updates profile fields on an organization. Requires owner or admin role in the organization.", + "summary": "Invite an organization member by email", "security": [ { "BearerAuth": [] @@ -37644,58 +56745,29 @@ "schema": { "type": "string", "minLength": 1, - "maxLength": 54, - "description": "Organization ID. Prefixed form `org_` is canonical.", - "example": "org_j572abc123def456" + "maxLength": 54 }, "required": true, - "description": "Organization ID. Prefixed form `org_` is canonical.", "name": "id", "in": "path" - }, - { - "schema": { - "type": "string", - "minLength": 1, - "maxLength": 64, - "description": "Caller-supplied idempotency key. Repeated requests with the same key return the existing resource instead of creating a duplicate. Safe to retry after a timed-out or interrupted request.", - "example": "create-prod-2026-05-07" - }, - "required": false, - "description": "Caller-supplied idempotency key. Repeated requests with the same key return the existing resource instead of creating a duplicate. Safe to retry after a timed-out or interrupted request.", - "name": "idempotency-key", - "in": "header" - }, - { - "schema": { - "type": "string", - "minLength": 1, - "maxLength": 256, - "description": "The `etag` of the resource version the client last read. Required on writes when the resource exposes an `etag` field. Mismatch returns 409 `ABORTED` with the current etag in the error metadata.", - "example": "42" - }, - "required": true, - "description": "The `etag` of the resource version the client last read. Required on writes when the resource exposes an `etag` field. Mismatch returns 409 `ABORTED` with the current etag in the error metadata.", - "name": "if-match", - "in": "header" } ], "requestBody": { "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/OrganizationUpdateRequest" + "$ref": "#/components/schemas/OrganizationInvitationCreateRequest" } } } }, "responses": { - "200": { - "description": "Organization updated", + "201": { + "description": "Invitation sent", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/OrganizationOk" + "$ref": "#/components/schemas/OrganizationInvitation" } } } @@ -37730,16 +56802,6 @@ } } }, - "404": { - "description": "Not found", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/ApiErrorResponse" - } - } - } - }, "409": { "description": "Conflict", "content": { @@ -37751,15 +56813,16 @@ } } } - }, - "delete": { + } + }, + "/v1/organizations/{id}/invitations/{invitationId}/resend": { + "post": { "x-platform-visibility": "PUBLIC", - "operationId": "organizations.delete", + "operationId": "organizations.resendInvitation", "tags": [ "Organizations" ], - "summary": "Delete organization", - "description": "Deletes an organization after validating membership, workspace ownership, and owner protection.", + "summary": "Resend an organization invitation", "security": [ { "BearerAuth": [] @@ -37770,52 +56833,29 @@ "schema": { "type": "string", "minLength": 1, - "maxLength": 54, - "description": "Organization ID. Prefixed form `org_` is canonical.", - "example": "org_j572abc123def456" + "maxLength": 54 }, "required": true, - "description": "Organization ID. Prefixed form `org_` is canonical.", "name": "id", "in": "path" }, { "schema": { "type": "string", - "minLength": 1, - "maxLength": 64, - "description": "Caller-supplied idempotency key. Repeated requests with the same key return the existing resource instead of creating a duplicate. Safe to retry after a timed-out or interrupted request.", - "example": "create-prod-2026-05-07" - }, - "required": false, - "description": "Caller-supplied idempotency key. Repeated requests with the same key return the existing resource instead of creating a duplicate. Safe to retry after a timed-out or interrupted request.", - "name": "idempotency-key", - "in": "header" - }, - { - "schema": { - "type": "string", - "minLength": 1, - "maxLength": 256, - "description": "The `etag` of the resource version the client last read. Required on writes when the resource exposes an `etag` field. Mismatch returns 409 `ABORTED` with the current etag in the error metadata.", - "example": "42" + "pattern": "^orgi_[a-z0-9]+$" }, "required": true, - "description": "The `etag` of the resource version the client last read. Required on writes when the resource exposes an `etag` field. Mismatch returns 409 `ABORTED` with the current etag in the error metadata.", - "name": "if-match", - "in": "header" + "name": "invitationId", + "in": "path" } ], "responses": { - "204": { - "description": "Organization deleted" - }, - "400": { - "description": "Bad request", + "200": { + "description": "Invitation resent", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/ApiErrorResponse" + "$ref": "#/components/schemas/OrganizationInvitation" } } } @@ -37849,24 +56889,28 @@ } } } + }, + "409": { + "description": "Conflict", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } + } + } } } } }, - "/v1/organizations/{id}/members": { - "get": { + "/v1/organizations/{id}/invitations/{invitationId}": { + "delete": { "x-platform-visibility": "PUBLIC", - "x-platform-live": { - "visibility": "INTERNAL", - "transport": "convex", - "convexQuery": "organization.ui.listMembersForApi" - }, - "operationId": "organizations.listMembers", + "operationId": "organizations.cancelInvitation", "tags": [ "Organizations" ], - "summary": "List organization members", - "description": "Lists every member of the organization. Requires membership in the organization.", + "summary": "Cancel an organization invitation", "security": [ { "BearerAuth": [] @@ -37877,29 +56921,38 @@ "schema": { "type": "string", "minLength": 1, - "maxLength": 54, - "description": "Organization ID. Prefixed form `org_` is canonical.", - "example": "org_j572abc123def456" + "maxLength": 54 }, "required": true, - "description": "Organization ID. Prefixed form `org_` is canonical.", "name": "id", "in": "path" + }, + { + "schema": { + "type": "string", + "pattern": "^orgi_[a-z0-9]+$" + }, + "required": true, + "name": "invitationId", + "in": "path" } ], "responses": { - "200": { - "description": "List of members", + "204": { + "description": "Invitation canceled" + }, + "401": { + "description": "Unauthorized", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/OrganizationMemberList" + "$ref": "#/components/schemas/ApiErrorResponse" } } } }, - "401": { - "description": "Unauthorized", + "403": { + "description": "Forbidden", "content": { "application/json": { "schema": { @@ -37908,8 +56961,8 @@ } } }, - "403": { - "description": "Forbidden", + "404": { + "description": "Not found", "content": { "application/json": { "schema": { @@ -37919,83 +56972,43 @@ } } } - }, + } + }, + "/v1/organization_invitations/accept": { "post": { "x-platform-visibility": "PUBLIC", - "operationId": "organizations.addMember", + "operationId": "organizations.acceptInvitation", "tags": [ "Organizations" ], - "summary": "Add organization member", - "description": "Adds a user to the organization with the supplied role (defaults to `member`). Requires owner or admin role.", + "summary": "Accept an organization invitation", "security": [ { "BearerAuth": [] } ], - "parameters": [ - { - "schema": { - "type": "string", - "minLength": 1, - "maxLength": 54, - "description": "Organization ID. Prefixed form `org_` is canonical.", - "example": "org_j572abc123def456" - }, - "required": true, - "description": "Organization ID. Prefixed form `org_` is canonical.", - "name": "id", - "in": "path" - }, - { - "schema": { - "type": "string", - "minLength": 1, - "maxLength": 64, - "description": "Caller-supplied idempotency key. Repeated requests with the same key return the existing resource instead of creating a duplicate. Safe to retry after a timed-out or interrupted request.", - "example": "create-prod-2026-05-07" - }, - "required": false, - "description": "Caller-supplied idempotency key. Repeated requests with the same key return the existing resource instead of creating a duplicate. Safe to retry after a timed-out or interrupted request.", - "name": "idempotency-key", - "in": "header" - }, - { - "schema": { - "type": "string", - "minLength": 1, - "maxLength": 256, - "description": "The `etag` of the resource version the client last read. Required on writes when the resource exposes an `etag` field. Mismatch returns 409 `ABORTED` with the current etag in the error metadata.", - "example": "42" - }, - "required": true, - "description": "The `etag` of the resource version the client last read. Required on writes when the resource exposes an `etag` field. Mismatch returns 409 `ABORTED` with the current etag in the error metadata.", - "name": "if-match", - "in": "header" - } - ], "requestBody": { "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/OrganizationAddMemberRequest" + "$ref": "#/components/schemas/OrganizationInvitationAcceptRequest" } } } }, "responses": { - "201": { - "description": "Member added", + "200": { + "description": "Invitation accepted", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/OrganizationOk" + "$ref": "#/components/schemas/OrganizationInvitation" } } } }, - "400": { - "description": "Bad request", + "401": { + "description": "Unauthorized", "content": { "application/json": { "schema": { @@ -38004,8 +57017,8 @@ } } }, - "401": { - "description": "Unauthorized", + "403": { + "description": "Forbidden", "content": { "application/json": { "schema": { @@ -38014,8 +57027,8 @@ } } }, - "403": { - "description": "Forbidden", + "404": { + "description": "Not found", "content": { "application/json": { "schema": { @@ -38082,11 +57095,11 @@ "type": "string", "minLength": 1, "maxLength": 64, - "description": "Caller-supplied idempotency key. Repeated requests with the same key return the existing resource instead of creating a duplicate. Safe to retry after a timed-out or interrupted request.", + "description": "Optional caller-supplied idempotency key. Any non-empty key up to 64 characters is accepted. Endpoint-specific documentation describes how the key is used.", "example": "create-prod-2026-05-07" }, "required": false, - "description": "Caller-supplied idempotency key. Repeated requests with the same key return the existing resource instead of creating a duplicate. Safe to retry after a timed-out or interrupted request.", + "description": "Optional caller-supplied idempotency key. Any non-empty key up to 64 characters is accepted. Endpoint-specific documentation describes how the key is used.", "name": "idempotency-key", "in": "header" }, @@ -38220,11 +57233,11 @@ "type": "string", "minLength": 1, "maxLength": 64, - "description": "Caller-supplied idempotency key. Repeated requests with the same key return the existing resource instead of creating a duplicate. Safe to retry after a timed-out or interrupted request.", + "description": "Optional caller-supplied idempotency key. Any non-empty key up to 64 characters is accepted. Endpoint-specific documentation describes how the key is used.", "example": "create-prod-2026-05-07" }, "required": false, - "description": "Caller-supplied idempotency key. Repeated requests with the same key return the existing resource instead of creating a duplicate. Safe to retry after a timed-out or interrupted request.", + "description": "Optional caller-supplied idempotency key. Any non-empty key up to 64 characters is accepted. Endpoint-specific documentation describes how the key is used.", "name": "idempotency-key", "in": "header" }, @@ -38331,6 +57344,30 @@ "description": "Organization ID. Prefixed form `org_` is canonical.", "name": "id", "in": "path" + }, + { + "schema": { + "type": "string", + "description": "Pagination cursor from a previous response's `next_cursor`." + }, + "required": false, + "description": "Pagination cursor from a previous response's `next_cursor`.", + "name": "cursor", + "in": "query" + }, + { + "schema": { + "type": "integer", + "minimum": 1, + "maximum": 100, + "default": 50, + "description": "Items per page (1-100, default 50)", + "example": 50 + }, + "required": false, + "description": "Items per page (1-100, default 50)", + "name": "limit", + "in": "query" } ], "responses": { @@ -38559,7 +57596,7 @@ "convexQuery": "quota.ui.listQuotaUsageForApi" }, "summary": "List quota usage for the authenticated user", - "description": "Returns current usage and limits for all quota metrics. Allocation and rate quotas are per-user across all workspaces. Concurrency quotas are per-cluster — pass `cluster_id` to include them.", + "description": "Returns current usage and limits for all quota metrics. With workspace context, allocation quotas are scoped to that workspace. Without context, allocation quotas retain the user-wide view. Rate quotas are user-scoped, and concurrency quotas are per-cluster when `cluster_id` is supplied.", "security": [ { "BearerAuth": [] @@ -38577,6 +57614,19 @@ "description": "Cluster ID to include concurrency quotas", "name": "cluster_id", "in": "query" + }, + { + "schema": { + "type": "string", + "minLength": 1, + "maxLength": 53, + "description": "Optional workspace/scope context for the request. Carries a single workspace wire id (`ws_…`) today. Only needed for broad tokens — a workspace-owned token implies its workspace.", + "example": "ws_j572abc123def456" + }, + "required": false, + "description": "Optional workspace/scope context for the request. Carries a single workspace wire id (`ws_…`) today. Only needed for broad tokens — a workspace-owned token implies its workspace.", + "name": "akua-context", + "in": "header" } ], "responses": { @@ -38599,6 +57649,16 @@ } } } + }, + "403": { + "description": "Forbidden", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } + } + } } } } @@ -39064,11 +58124,11 @@ "type": "string", "minLength": 1, "maxLength": 64, - "description": "Caller-supplied idempotency key. Repeated requests with the same key return the existing resource instead of creating a duplicate. Safe to retry after a timed-out or interrupted request.", + "description": "Optional caller-supplied idempotency key. Any non-empty key up to 64 characters is accepted. Endpoint-specific documentation describes how the key is used.", "example": "create-prod-2026-05-07" }, "required": false, - "description": "Caller-supplied idempotency key. Repeated requests with the same key return the existing resource instead of creating a duplicate. Safe to retry after a timed-out or interrupted request.", + "description": "Optional caller-supplied idempotency key. Any non-empty key up to 64 characters is accepted. Endpoint-specific documentation describes how the key is used.", "name": "idempotency-key", "in": "header" } @@ -39649,9 +58709,12 @@ "schema": { "type": "string", "minLength": 1, - "maxLength": 64 + "maxLength": 64, + "description": "Required caller-supplied idempotency key. Any non-empty key up to 64 characters is accepted. Endpoint-specific documentation describes how the key is used.", + "example": "create-prod-2026-05-07" }, "required": true, + "description": "Required caller-supplied idempotency key. Any non-empty key up to 64 characters is accepted. Endpoint-specific documentation describes how the key is used.", "name": "idempotency-key", "in": "header" } @@ -39930,9 +58993,12 @@ "schema": { "type": "string", "minLength": 1, - "maxLength": 64 + "maxLength": 64, + "description": "Required caller-supplied idempotency key. Any non-empty key up to 64 characters is accepted. Endpoint-specific documentation describes how the key is used.", + "example": "create-prod-2026-05-07" }, "required": true, + "description": "Required caller-supplied idempotency key. Any non-empty key up to 64 characters is accepted. Endpoint-specific documentation describes how the key is used.", "name": "idempotency-key", "in": "header" } @@ -40153,9 +59219,12 @@ "schema": { "type": "string", "minLength": 1, - "maxLength": 64 + "maxLength": 64, + "description": "Required caller-supplied idempotency key. Any non-empty key up to 64 characters is accepted. Endpoint-specific documentation describes how the key is used.", + "example": "create-prod-2026-05-07" }, "required": true, + "description": "Required caller-supplied idempotency key. Any non-empty key up to 64 characters is accepted. Endpoint-specific documentation describes how the key is used.", "name": "idempotency-key", "in": "header" } @@ -40269,9 +59338,12 @@ "schema": { "type": "string", "minLength": 1, - "maxLength": 64 + "maxLength": 64, + "description": "Required caller-supplied idempotency key. Any non-empty key up to 64 characters is accepted. Endpoint-specific documentation describes how the key is used.", + "example": "create-prod-2026-05-07" }, "required": true, + "description": "Required caller-supplied idempotency key. Any non-empty key up to 64 characters is accepted. Endpoint-specific documentation describes how the key is used.", "name": "idempotency-key", "in": "header" } @@ -40394,9 +59466,12 @@ "schema": { "type": "string", "minLength": 1, - "maxLength": 64 + "maxLength": 64, + "description": "Required caller-supplied idempotency key. Any non-empty key up to 64 characters is accepted. Endpoint-specific documentation describes how the key is used.", + "example": "create-prod-2026-05-07" }, "required": true, + "description": "Required caller-supplied idempotency key. Any non-empty key up to 64 characters is accepted. Endpoint-specific documentation describes how the key is used.", "name": "idempotency-key", "in": "header" } @@ -42262,11 +61337,11 @@ "type": "string", "minLength": 1, "maxLength": 64, - "description": "Caller-supplied idempotency key. Repeated requests with the same key return the existing resource instead of creating a duplicate. Safe to retry after a timed-out or interrupted request.", + "description": "Optional caller-supplied idempotency key. Any non-empty key up to 64 characters is accepted. Endpoint-specific documentation describes how the key is used.", "example": "create-prod-2026-05-07" }, "required": false, - "description": "Caller-supplied idempotency key. Repeated requests with the same key return the existing resource instead of creating a duplicate. Safe to retry after a timed-out or interrupted request.", + "description": "Optional caller-supplied idempotency key. Any non-empty key up to 64 characters is accepted. Endpoint-specific documentation describes how the key is used.", "name": "idempotency-key", "in": "header" } @@ -42565,11 +61640,11 @@ "type": "string", "minLength": 1, "maxLength": 64, - "description": "Caller-supplied idempotency key. Repeated requests with the same key return the existing resource instead of creating a duplicate. Safe to retry after a timed-out or interrupted request.", + "description": "Optional caller-supplied idempotency key. Any non-empty key up to 64 characters is accepted. Endpoint-specific documentation describes how the key is used.", "example": "create-prod-2026-05-07" }, "required": false, - "description": "Caller-supplied idempotency key. Repeated requests with the same key return the existing resource instead of creating a duplicate. Safe to retry after a timed-out or interrupted request.", + "description": "Optional caller-supplied idempotency key. Any non-empty key up to 64 characters is accepted. Endpoint-specific documentation describes how the key is used.", "name": "idempotency-key", "in": "header" } @@ -43922,9 +62997,12 @@ "schema": { "type": "string", "minLength": 1, - "maxLength": 64 + "maxLength": 64, + "description": "Required caller-supplied idempotency key. Any non-empty key up to 64 characters is accepted. Endpoint-specific documentation describes how the key is used.", + "example": "create-prod-2026-05-07" }, "required": true, + "description": "Required caller-supplied idempotency key. Any non-empty key up to 64 characters is accepted. Endpoint-specific documentation describes how the key is used.", "name": "idempotency-key", "in": "header" } @@ -44283,9 +63361,12 @@ "schema": { "type": "string", "minLength": 1, - "maxLength": 64 + "maxLength": 64, + "description": "Required caller-supplied idempotency key. Any non-empty key up to 64 characters is accepted. Endpoint-specific documentation describes how the key is used.", + "example": "create-prod-2026-05-07" }, "required": true, + "description": "Required caller-supplied idempotency key. Any non-empty key up to 64 characters is accepted. Endpoint-specific documentation describes how the key is used.", "name": "idempotency-key", "in": "header" } @@ -44378,9 +63459,12 @@ "schema": { "type": "string", "minLength": 1, - "maxLength": 64 + "maxLength": 64, + "description": "Required caller-supplied idempotency key. Any non-empty key up to 64 characters is accepted. Endpoint-specific documentation describes how the key is used.", + "example": "create-prod-2026-05-07" }, "required": true, + "description": "Required caller-supplied idempotency key. Any non-empty key up to 64 characters is accepted. Endpoint-specific documentation describes how the key is used.", "name": "idempotency-key", "in": "header" } @@ -44472,9 +63556,12 @@ "schema": { "type": "string", "minLength": 1, - "maxLength": 64 + "maxLength": 64, + "description": "Required caller-supplied idempotency key. Any non-empty key up to 64 characters is accepted. Endpoint-specific documentation describes how the key is used.", + "example": "create-prod-2026-05-07" }, "required": true, + "description": "Required caller-supplied idempotency key. Any non-empty key up to 64 characters is accepted. Endpoint-specific documentation describes how the key is used.", "name": "idempotency-key", "in": "header" } @@ -44664,9 +63751,12 @@ "schema": { "type": "string", "minLength": 1, - "maxLength": 64 + "maxLength": 64, + "description": "Required caller-supplied idempotency key. Any non-empty key up to 64 characters is accepted. Endpoint-specific documentation describes how the key is used.", + "example": "create-prod-2026-05-07" }, "required": true, + "description": "Required caller-supplied idempotency key. Any non-empty key up to 64 characters is accepted. Endpoint-specific documentation describes how the key is used.", "name": "idempotency-key", "in": "header" } @@ -44852,9 +63942,12 @@ "schema": { "type": "string", "minLength": 1, - "maxLength": 64 + "maxLength": 64, + "description": "Required caller-supplied idempotency key. Any non-empty key up to 64 characters is accepted. Endpoint-specific documentation describes how the key is used.", + "example": "create-prod-2026-05-07" }, "required": true, + "description": "Required caller-supplied idempotency key. Any non-empty key up to 64 characters is accepted. Endpoint-specific documentation describes how the key is used.", "name": "idempotency-key", "in": "header" } @@ -44966,9 +64059,12 @@ "schema": { "type": "string", "minLength": 1, - "maxLength": 64 + "maxLength": 64, + "description": "Required caller-supplied idempotency key. Any non-empty key up to 64 characters is accepted. Endpoint-specific documentation describes how the key is used.", + "example": "create-prod-2026-05-07" }, "required": true, + "description": "Required caller-supplied idempotency key. Any non-empty key up to 64 characters is accepted. Endpoint-specific documentation describes how the key is used.", "name": "idempotency-key", "in": "header" } @@ -45300,6 +64396,21 @@ "BearerAuth": [] } ], + "parameters": [ + { + "schema": { + "type": "string", + "minLength": 1, + "maxLength": 53, + "description": "Optional workspace/scope context for the request. Carries a single workspace wire id (`ws_…`) today. Only needed for broad tokens — a workspace-owned token implies its workspace.", + "example": "ws_j572abc123def456" + }, + "required": false, + "description": "Optional workspace/scope context for the request. Carries a single workspace wire id (`ws_…`) today. Only needed for broad tokens — a workspace-owned token implies its workspace.", + "name": "akua-context", + "in": "header" + } + ], "requestBody": { "content": { "application/json": { @@ -45363,6 +64474,98 @@ } } }, + "/v1/access_decisions:explainBatch": { + "post": { + "x-platform-visibility": "PUBLIC", + "operationId": "accessDecisions.explainBatch", + "tags": [ + "Access Decisions" + ], + "summary": "Explain multiple access decisions", + "description": "Explains an ordered batch of access actions for the authenticated requester.", + "security": [ + { + "BearerAuth": [] + } + ], + "parameters": [ + { + "schema": { + "type": "string", + "minLength": 1, + "maxLength": 53, + "description": "Optional workspace/scope context for the request. Carries a single workspace wire id (`ws_…`) today. Only needed for broad tokens — a workspace-owned token implies its workspace.", + "example": "ws_j572abc123def456" + }, + "required": false, + "description": "Optional workspace/scope context for the request. Carries a single workspace wire id (`ws_…`) today. Only needed for broad tokens — a workspace-owned token implies its workspace.", + "name": "akua-context", + "in": "header" + } + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ExplainAccessDecisionsBatchBody" + } + } + } + }, + "responses": { + "200": { + "description": "Ordered access decision explanations", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/AccessDecisionBatch" + } + } + } + }, + "401": { + "description": "Unauthorized", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } + } + } + }, + "403": { + "description": "Forbidden", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } + } + } + }, + "404": { + "description": "Not found", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } + } + } + }, + "422": { + "description": "Unprocessable entity", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } + } + } + } + } + } + }, "/v1/admin/capabilities": { "get": { "x-platform-visibility": "ADMIN", diff --git a/src/generated/commands.gen.ts b/src/generated/commands.gen.ts index f2a8849..84d02fd 100644 --- a/src/generated/commands.gen.ts +++ b/src/generated/commands.gen.ts @@ -13,7 +13,32 @@ export const commandRegistry = [ "summary": "Explain an access decision", "visibility": "PUBLIC", "requires_auth": true, - "parameters": [] + "parameters": [ + { + "name": "akua-context", + "in": "header", + "required": false + } + ] + }, + { + "operation_id": "accessDecisions.explainBatch", + "command": "access-decisions explain-batch", + "resource": "access-decisions", + "action": "explain-batch", + "method": "POST", + "path": "/v1/access_decisions:explainBatch", + "tag": "Access Decisions", + "summary": "Explain multiple access decisions", + "visibility": "PUBLIC", + "requires_auth": true, + "parameters": [ + { + "name": "akua-context", + "in": "header", + "required": false + } + ] }, { "operation_id": "agentEvents.list", @@ -1120,6 +1145,30 @@ export const commandRegistry = [ } ] }, + { + "operation_id": "clusters.getComputeSettings", + "command": "clusters get-compute-settings", + "resource": "clusters", + "action": "get-compute-settings", + "method": "GET", + "path": "/v1/clusters/{id}/compute_settings", + "tag": "Clusters", + "summary": "Get cluster compute settings", + "visibility": "PUBLIC", + "requires_auth": true, + "parameters": [ + { + "name": "id", + "in": "path", + "required": true + }, + { + "name": "akua-context", + "in": "header", + "required": false + } + ] + }, { "operation_id": "clusters.getKubeconfig", "command": "clusters get-kubeconfig", @@ -1460,59 +1509,14 @@ export const commandRegistry = [ ] }, { - "operation_id": "compute.checkMachineDrift", - "command": "compute check-machine-drift", - "resource": "compute", - "action": "check-machine-drift", - "method": "GET", - "path": "/v1/compute/machines/{providerId}/drift", - "tag": "Compute", - "summary": "Check if machine has drifted", - "visibility": "PUBLIC", - "requires_auth": true, - "parameters": [ - { - "name": "providerId", - "in": "path", - "required": true - } - ] - }, - { - "operation_id": "compute.createConfig", - "command": "compute create-config", - "resource": "compute", - "action": "create-config", - "method": "POST", - "path": "/v1/compute/configs", - "tag": "Compute", - "summary": "Create a compute config", - "visibility": "PUBLIC", - "requires_auth": true, - "parameters": [] - }, - { - "operation_id": "compute.createMachine", - "command": "compute create-machine", - "resource": "compute", - "action": "create-machine", - "method": "POST", - "path": "/v1/compute/machines", - "tag": "Compute", - "summary": "Create a machine", - "visibility": "PUBLIC", - "requires_auth": true, - "parameters": [] - }, - { - "operation_id": "compute.deleteConfig", - "command": "compute delete-config", - "resource": "compute", - "action": "delete-config", - "method": "DELETE", - "path": "/v1/compute/configs/{id}", - "tag": "Compute", - "summary": "Delete a compute config", + "operation_id": "clusters.updateComputeSettings", + "command": "clusters update-compute-settings", + "resource": "clusters", + "action": "update-compute-settings", + "method": "PATCH", + "path": "/v1/clusters/{id}/compute_settings", + "tag": "Clusters", + "summary": "Update cluster compute settings", "visibility": "PUBLIC", "requires_auth": true, "parameters": [ @@ -1522,235 +1526,13 @@ export const commandRegistry = [ "required": true }, { - "name": "if-match", + "name": "akua-context", "in": "header", - "required": true - } - ] - }, - { - "operation_id": "compute.deleteMachine", - "command": "compute delete-machine", - "resource": "compute", - "action": "delete-machine", - "method": "DELETE", - "path": "/v1/compute/machines/{providerId}", - "tag": "Compute", - "summary": "Delete a machine", - "visibility": "PUBLIC", - "requires_auth": true, - "parameters": [ - { - "name": "providerId", - "in": "path", - "required": true - } - ] - }, - { - "operation_id": "compute.deleteSuspension", - "command": "compute delete-suspension", - "resource": "compute", - "action": "delete-suspension", - "method": "DELETE", - "path": "/v1/compute/suspensions/{id}", - "tag": "Compute", - "summary": "Delete a suspension", - "visibility": "PUBLIC", - "requires_auth": true, - "parameters": [ - { - "name": "id", - "in": "path", - "required": true - } - ] - }, - { - "operation_id": "compute.getClusterStatus", - "command": "compute get-cluster-status", - "resource": "compute", - "action": "get-cluster-status", - "method": "GET", - "path": "/v1/clusters/{clusterId}/compute_status", - "tag": "Compute", - "summary": "Get cluster compute status", - "visibility": "PUBLIC", - "requires_auth": true, - "parameters": [ - { - "name": "clusterId", - "in": "path", - "required": true - } - ] - }, - { - "operation_id": "compute.getConfig", - "command": "compute get-config", - "resource": "compute", - "action": "get-config", - "method": "GET", - "path": "/v1/compute/configs/{id}", - "tag": "Compute", - "summary": "Get a compute config", - "visibility": "PUBLIC", - "requires_auth": true, - "parameters": [ - { - "name": "id", - "in": "path", - "required": true - } - ] - }, - { - "operation_id": "compute.getMachine", - "command": "compute get-machine", - "resource": "compute", - "action": "get-machine", - "method": "GET", - "path": "/v1/compute/machines/{providerId}", - "tag": "Compute", - "summary": "Get machine status", - "visibility": "PUBLIC", - "requires_auth": true, - "parameters": [ - { - "name": "providerId", - "in": "path", - "required": true - } - ] - }, - { - "operation_id": "compute.listConfigs", - "command": "compute list-configs", - "resource": "compute", - "action": "list-configs", - "method": "GET", - "path": "/v1/compute/configs", - "tag": "Compute", - "summary": "List compute configs", - "visibility": "PUBLIC", - "requires_auth": true, - "parameters": [ - { - "name": "cursor", - "in": "query", "required": false }, { - "name": "limit", - "in": "query", - "required": false - } - ] - }, - { - "operation_id": "compute.listInstanceTypes", - "command": "compute list-instance-types", - "resource": "compute", - "action": "list-instance-types", - "method": "GET", - "path": "/v1/compute/instance_types", - "tag": "Compute", - "summary": "List available instance types", - "visibility": "PUBLIC", - "requires_auth": true, - "parameters": [ - { - "name": "config", - "in": "query", - "required": false - } - ] - }, - { - "operation_id": "compute.listMachines", - "command": "compute list-machines", - "resource": "compute", - "action": "list-machines", - "method": "GET", - "path": "/v1/compute/machines", - "tag": "Compute", - "summary": "List machines in cluster", - "visibility": "PUBLIC", - "requires_auth": true, - "parameters": [ - { - "name": "cluster", - "in": "query", - "required": true - } - ] - }, - { - "operation_id": "compute.listSuspensions", - "command": "compute list-suspensions", - "resource": "compute", - "action": "list-suspensions", - "method": "GET", - "path": "/v1/compute/suspensions", - "tag": "Compute", - "summary": "List suspended machines", - "visibility": "PUBLIC", - "requires_auth": true, - "parameters": [] - }, - { - "operation_id": "compute.resumeSuspension", - "command": "compute resume-suspension", - "resource": "compute", - "action": "resume-suspension", - "method": "POST", - "path": "/v1/compute/suspensions/{id}/resume", - "tag": "Compute", - "summary": "Resume a suspended machine", - "visibility": "PUBLIC", - "requires_auth": true, - "parameters": [ - { - "name": "id", - "in": "path", - "required": true - } - ] - }, - { - "operation_id": "compute.suspendMachine", - "command": "compute suspend-machine", - "resource": "compute", - "action": "suspend-machine", - "method": "POST", - "path": "/v1/compute/machines/{providerId}/suspend", - "tag": "Compute", - "summary": "Suspend a machine", - "visibility": "PUBLIC", - "requires_auth": true, - "parameters": [ - { - "name": "providerId", - "in": "path", - "required": true - } - ] - }, - { - "operation_id": "compute.updateClusterSettings", - "command": "compute update-cluster-settings", - "resource": "compute", - "action": "update-cluster-settings", - "method": "PATCH", - "path": "/v1/clusters/{clusterId}/compute_settings", - "tag": "Compute", - "summary": "Update cluster compute settings", - "visibility": "PUBLIC", - "requires_auth": true, - "parameters": [ - { - "name": "clusterId", - "in": "path", + "name": "if-match", + "in": "header", "required": true } ] @@ -2071,7 +1853,42 @@ export const commandRegistry = [ "summary": "Create dashboard", "visibility": "PUBLIC", "requires_auth": true, - "parameters": [] + "parameters": [ + { + "name": "akua-context", + "in": "header", + "required": false + } + ] + }, + { + "operation_id": "dashboards.createRevision", + "command": "dashboards create-revision", + "resource": "dashboards", + "action": "create-revision", + "method": "POST", + "path": "/v1/dashboards/{id}/revisions", + "tag": "Dashboards", + "summary": "Create dashboard revision", + "visibility": "PUBLIC", + "requires_auth": true, + "parameters": [ + { + "name": "id", + "in": "path", + "required": true + }, + { + "name": "if-match", + "in": "header", + "required": true + }, + { + "name": "idempotency-key", + "in": "header", + "required": true + } + ] }, { "operation_id": "dashboards.createWidget", @@ -2179,6 +1996,30 @@ export const commandRegistry = [ } ] }, + { + "operation_id": "dashboards.getRevision", + "command": "dashboards get-revision", + "resource": "dashboards", + "action": "get-revision", + "method": "GET", + "path": "/v1/dashboards/{id}/revisions/{revision_id}", + "tag": "Dashboards", + "summary": "Get dashboard revision", + "visibility": "PUBLIC", + "requires_auth": true, + "parameters": [ + { + "name": "id", + "in": "path", + "required": true + }, + { + "name": "revision_id", + "in": "path", + "required": true + } + ] + }, { "operation_id": "dashboards.getWidget", "command": "dashboards get-widget", @@ -2203,6 +2044,25 @@ export const commandRegistry = [ } ] }, + { + "operation_id": "dashboards.getWorkspaceOverview", + "command": "dashboards get-workspace-overview", + "resource": "dashboards", + "action": "get-workspace-overview", + "method": "GET", + "path": "/v1/dashboards/workspace_overview", + "tag": "Dashboards", + "summary": "Get the workspace overview dashboard", + "visibility": "PUBLIC", + "requires_auth": true, + "parameters": [ + { + "name": "akua-context", + "in": "header", + "required": false + } + ] + }, { "operation_id": "dashboards.list", "command": "dashboards list", @@ -2232,6 +2092,35 @@ export const commandRegistry = [ } ] }, + { + "operation_id": "dashboards.listRevisions", + "command": "dashboards list-revisions", + "resource": "dashboards", + "action": "list-revisions", + "method": "GET", + "path": "/v1/dashboards/{id}/revisions", + "tag": "Dashboards", + "summary": "List dashboard revisions", + "visibility": "PUBLIC", + "requires_auth": true, + "parameters": [ + { + "name": "id", + "in": "path", + "required": true + }, + { + "name": "cursor", + "in": "query", + "required": false + }, + { + "name": "limit", + "in": "query", + "required": false + } + ] + }, { "operation_id": "dashboards.listWidgets", "command": "dashboards list-widgets", @@ -2261,6 +2150,69 @@ export const commandRegistry = [ } ] }, + { + "operation_id": "dashboards.resetToRecommended", + "command": "dashboards reset-to-recommended", + "resource": "dashboards", + "action": "reset-to-recommended", + "method": "POST", + "path": "/v1/dashboards/{id}:resetToRecommended", + "tag": "Dashboards", + "summary": "Reset the Workspace overview to the recommended configuration", + "visibility": "PUBLIC", + "requires_auth": true, + "parameters": [ + { + "name": "id", + "in": "path", + "required": true + }, + { + "name": "if-match", + "in": "header", + "required": true + }, + { + "name": "idempotency-key", + "in": "header", + "required": true + } + ] + }, + { + "operation_id": "dashboards.restoreRevision", + "command": "dashboards restore-revision", + "resource": "dashboards", + "action": "restore-revision", + "method": "POST", + "path": "/v1/dashboards/{id}/revisions/{revision_id}:restore", + "tag": "Dashboards", + "summary": "Restore dashboard revision", + "visibility": "PUBLIC", + "requires_auth": true, + "parameters": [ + { + "name": "id", + "in": "path", + "required": true + }, + { + "name": "revision_id", + "in": "path", + "required": true + }, + { + "name": "if-match", + "in": "header", + "required": true + }, + { + "name": "idempotency-key", + "in": "header", + "required": true + } + ] + }, { "operation_id": "dashboards.update", "command": "dashboards update", @@ -2628,21 +2580,123 @@ export const commandRegistry = [ "required": true }, { - "name": "akua-context", + "name": "akua-context", + "in": "header", + "required": false + } + ] + }, + { + "operation_id": "installs.listRenders", + "command": "installs list-renders", + "resource": "installs", + "action": "list-renders", + "method": "GET", + "path": "/v1/installs/{id}/renders", + "tag": "Installs", + "summary": "List install renders", + "visibility": "PUBLIC", + "requires_auth": true, + "parameters": [ + { + "name": "id", + "in": "path", + "required": true + }, + { + "name": "cursor", + "in": "query", + "required": false + }, + { + "name": "limit", + "in": "query", + "required": false + }, + { + "name": "akua-context", + "in": "header", + "required": false + } + ] + }, + { + "operation_id": "installs.restore", + "command": "installs restore", + "resource": "installs", + "action": "restore", + "method": "POST", + "path": "/v1/installs/{id}:restore", + "tag": "Installs", + "summary": "Restore install render", + "visibility": "PUBLIC", + "requires_auth": true, + "parameters": [ + { + "name": "id", + "in": "path", + "required": true + }, + { + "name": "akua-context", + "in": "header", + "required": false + }, + { + "name": "if-match", + "in": "header", + "required": true + }, + { + "name": "idempotency-key", + "in": "header", + "required": true + } + ] + }, + { + "operation_id": "installs.setAutomaticUpdates", + "command": "installs set-automatic-updates", + "resource": "installs", + "action": "set-automatic-updates", + "method": "PATCH", + "path": "/v1/installs/{id}/automatic_updates", + "tag": "Installs", + "summary": "Set automatic install updates", + "visibility": "PUBLIC", + "requires_auth": true, + "parameters": [ + { + "name": "id", + "in": "path", + "required": true + }, + { + "name": "akua-context", + "in": "header", + "required": false + }, + { + "name": "if-match", + "in": "header", + "required": true + }, + { + "name": "idempotency-key", "in": "header", - "required": false + "required": true } ] }, { - "operation_id": "installs.listRenders", - "command": "installs list-renders", + "operation_id": "installs.updateVersion", + "command": "installs update-version", "resource": "installs", - "action": "list-renders", - "method": "GET", - "path": "/v1/installs/{id}/renders", + "action": "update-version", + "method": "POST", + "path": "/v1/installs/{id}:update", "tag": "Installs", - "summary": "List install renders", + "summary": "Update install version", "visibility": "PUBLIC", "requires_auth": true, "parameters": [ @@ -2652,19 +2706,19 @@ export const commandRegistry = [ "required": true }, { - "name": "cursor", - "in": "query", + "name": "akua-context", + "in": "header", "required": false }, { - "name": "limit", - "in": "query", - "required": false + "name": "if-match", + "in": "header", + "required": true }, { - "name": "akua-context", + "name": "idempotency-key", "in": "header", - "required": false + "required": true } ] }, @@ -2746,7 +2800,7 @@ export const commandRegistry = [ { "name": "idempotency-key", "in": "header", - "required": false + "required": true }, { "name": "if-match", @@ -2984,7 +3038,7 @@ export const commandRegistry = [ { "name": "idempotency-key", "in": "header", - "required": false + "required": true }, { "name": "if-match", @@ -3018,7 +3072,7 @@ export const commandRegistry = [ { "name": "idempotency-key", "in": "header", - "required": false + "required": true }, { "name": "if-match", @@ -3175,6 +3229,11 @@ export const commandRegistry = [ "name": "akua-context", "in": "header", "required": false + }, + { + "name": "idempotency-key", + "in": "header", + "required": false } ] }, @@ -3674,6 +3733,19 @@ export const commandRegistry = [ } ] }, + { + "operation_id": "organizations.acceptInvitation", + "command": "organizations accept-invitation", + "resource": "organizations", + "action": "accept-invitation", + "method": "POST", + "path": "/v1/organization_invitations/accept", + "tag": "Organizations", + "summary": "Accept an organization invitation", + "visibility": "PUBLIC", + "requires_auth": true, + "parameters": [] + }, { "operation_id": "organizations.addMember", "command": "organizations add-member", @@ -3703,6 +3775,30 @@ export const commandRegistry = [ } ] }, + { + "operation_id": "organizations.cancelInvitation", + "command": "organizations cancel-invitation", + "resource": "organizations", + "action": "cancel-invitation", + "method": "DELETE", + "path": "/v1/organizations/{id}/invitations/{invitationId}", + "tag": "Organizations", + "summary": "Cancel an organization invitation", + "visibility": "PUBLIC", + "requires_auth": true, + "parameters": [ + { + "name": "id", + "in": "path", + "required": true + }, + { + "name": "invitationId", + "in": "path", + "required": true + } + ] + }, { "operation_id": "organizations.create", "command": "organizations create", @@ -3722,6 +3818,25 @@ export const commandRegistry = [ } ] }, + { + "operation_id": "organizations.createInvitation", + "command": "organizations create-invitation", + "resource": "organizations", + "action": "create-invitation", + "method": "POST", + "path": "/v1/organizations/{id}/invitations", + "tag": "Organizations", + "summary": "Invite an organization member by email", + "visibility": "PUBLIC", + "requires_auth": true, + "parameters": [ + { + "name": "id", + "in": "path", + "required": true + } + ] + }, { "operation_id": "organizations.delete", "command": "organizations delete", @@ -3794,6 +3909,35 @@ export const commandRegistry = [ } ] }, + { + "operation_id": "organizations.listInvitations", + "command": "organizations list-invitations", + "resource": "organizations", + "action": "list-invitations", + "method": "GET", + "path": "/v1/organizations/{id}/invitations", + "tag": "Organizations", + "summary": "List pending organization invitations", + "visibility": "PUBLIC", + "requires_auth": true, + "parameters": [ + { + "name": "id", + "in": "path", + "required": true + }, + { + "name": "cursor", + "in": "query", + "required": false + }, + { + "name": "limit", + "in": "query", + "required": false + } + ] + }, { "operation_id": "organizations.listManagedWorkspaces", "command": "organizations list-managed-workspaces", @@ -3810,6 +3954,16 @@ export const commandRegistry = [ "name": "id", "in": "path", "required": true + }, + { + "name": "cursor", + "in": "query", + "required": false + }, + { + "name": "limit", + "in": "query", + "required": false } ] }, @@ -3829,6 +3983,16 @@ export const commandRegistry = [ "name": "id", "in": "path", "required": true + }, + { + "name": "cursor", + "in": "query", + "required": false + }, + { + "name": "limit", + "in": "query", + "required": false } ] }, @@ -3866,6 +4030,30 @@ export const commandRegistry = [ } ] }, + { + "operation_id": "organizations.resendInvitation", + "command": "organizations resend-invitation", + "resource": "organizations", + "action": "resend-invitation", + "method": "POST", + "path": "/v1/organizations/{id}/invitations/{invitationId}/resend", + "tag": "Organizations", + "summary": "Resend an organization invitation", + "visibility": "PUBLIC", + "requires_auth": true, + "parameters": [ + { + "name": "id", + "in": "path", + "required": true + }, + { + "name": "invitationId", + "in": "path", + "required": true + } + ] + }, { "operation_id": "organizations.update", "command": "organizations update", @@ -4608,6 +4796,11 @@ export const commandRegistry = [ "name": "cluster_id", "in": "query", "required": false + }, + { + "name": "akua-context", + "in": "header", + "required": false } ] }, @@ -5457,6 +5650,84 @@ export const commandRegistry = [ "requires_auth": true, "parameters": [] }, + { + "operation_id": "snippetRuns.get", + "command": "snippet-runs get", + "resource": "snippet-runs", + "action": "get", + "method": "GET", + "path": "/v1/snippet_runs/{id}", + "tag": "Snippet Runs", + "summary": "Get workspace snippet run", + "visibility": "PUBLIC", + "requires_auth": true, + "parameters": [ + { + "name": "id", + "in": "path", + "required": true + }, + { + "name": "akua-context", + "in": "header", + "required": false + } + ] + }, + { + "operation_id": "snippetRuns.list", + "command": "snippet-runs list", + "resource": "snippet-runs", + "action": "list", + "method": "GET", + "path": "/v1/snippet_runs", + "tag": "Snippet Runs", + "summary": "List workspace snippet runs", + "visibility": "PUBLIC", + "requires_auth": true, + "parameters": [ + { + "name": "cursor", + "in": "query", + "required": false + }, + { + "name": "limit", + "in": "query", + "required": false + }, + { + "name": "state", + "in": "query", + "required": false + }, + { + "name": "source", + "in": "query", + "required": false + }, + { + "name": "snippet", + "in": "query", + "required": false + }, + { + "name": "dashboard", + "in": "query", + "required": false + }, + { + "name": "view", + "in": "query", + "required": false + }, + { + "name": "akua-context", + "in": "header", + "required": false + } + ] + }, { "operation_id": "snippets.create", "command": "snippets create", @@ -5507,7 +5778,7 @@ export const commandRegistry = [ "method": "DELETE", "path": "/v1/snippets/{id}", "tag": "Snippets", - "summary": "Delete snippet", + "summary": "Archive snippet", "visibility": "PUBLIC", "requires_auth": true, "parameters": [ @@ -5916,6 +6187,30 @@ export const commandRegistry = [ } ] }, + { + "operation_id": "workspaces.getManagement", + "command": "workspaces get-management", + "resource": "workspaces", + "action": "get-management", + "method": "GET", + "path": "/v1/workspaces/{id}/management", + "tag": "Workspaces", + "summary": "Get workspace management access", + "visibility": "PUBLIC", + "requires_auth": true, + "parameters": [ + { + "name": "id", + "in": "path", + "required": true + }, + { + "name": "akua-context", + "in": "header", + "required": false + } + ] + }, { "operation_id": "workspaces.getSubscription", "command": "workspaces get-subscription", @@ -6114,6 +6409,40 @@ export const commandRegistry = [ } ] }, + { + "operation_id": "workspaces.revokeManagement", + "command": "workspaces revoke-management", + "resource": "workspaces", + "action": "revoke-management", + "method": "POST", + "path": "/v1/workspaces/{id}:revokeManagement", + "tag": "Workspaces", + "summary": "Revoke workspace management access", + "visibility": "PUBLIC", + "requires_auth": true, + "parameters": [ + { + "name": "id", + "in": "path", + "required": true + }, + { + "name": "akua-context", + "in": "header", + "required": false + }, + { + "name": "idempotency-key", + "in": "header", + "required": false + }, + { + "name": "if-match", + "in": "header", + "required": true + } + ] + }, { "operation_id": "workspaces.update", "command": "workspaces update",