From 4cd329beb4e35d72cbc245ddf3b1d25a120eb6cb Mon Sep 17 00:00:00 2001 From: robinbraemer <22003767+robinbraemer@users.noreply.github.com> Date: Mon, 27 Jul 2026 10:15:09 +0000 Subject: [PATCH] chore: update OpenAPI spec and command registry --- openapi/public.json | 55972 +++++++++++++++++++++----------- src/generated/commands.gen.ts | 920 +- 2 files changed, 38084 insertions(+), 18808 deletions(-) diff --git a/openapi/public.json b/openapi/public.json index b433ecd..b87de4f 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,189 +1212,14521 @@ ] }, "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", + "properties": { + "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" + ] + }, + "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": [ + "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" + }, + "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": [ + "result_contract_version", + "result_type", + "default_visualization", + "stats" + ], + "additionalProperties": false + } + ] + }, + "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()." + }, + "inputs": { + "type": "object", + "additionalProperties": { + "nullable": true + } + } + }, + "required": [ + "code" + ], + "additionalProperties": false + }, + "ExecuteStoredSnippetBody": { + "type": "object", + "properties": { + "inputs": { + "type": "object", + "additionalProperties": { + "nullable": true + } + } + }, + "additionalProperties": false + }, + "CreateSnippetBody": { + "oneOf": [ + { + "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", + "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." + }, + "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 + }, + { + "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", + "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." + }, + "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" + ] + }, + "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": [ + "name", + "code", + "display_type", + "result_contract_version", + "result_type", + "default_visualization" + ], + "additionalProperties": false + } + ], + "x-platform-exact-union": true + }, + "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 + }, + { + "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 + }, + "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" + ] + } + ] + }, + "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", + "minimum": 0 + }, + "region_count": { + "type": "integer", + "minimum": 0 + }, + "offer_count": { + "type": "integer", + "minimum": 0 + }, + "install_count": { + "type": "integer", + "minimum": 0 + } + }, + "required": [ + "id", + "html_url", + "name", + "workspace_id", + "package", + "marketplace", + "created_at", + "updated_at", + "etag", + "state", + "cluster_count", + "region_count", + "offer_count", + "install_count" + ] + }, + "MarketplaceProductList": { + "type": "array", + "items": { + "$ref": "#/components/schemas/MarketplaceProduct" + } + }, + "MarketplaceProduct": { + "type": "object", + "properties": { + "id": { + "type": "string", + "minLength": 1, + "maxLength": 50 + }, + "name": { + "type": "string" + }, + "regions": { + "type": "array", + "items": { + "$ref": "#/components/schemas/MarketplaceRegion" + } + }, + "hasStripe": { + "type": "boolean" + }, + "marketplace": { + "$ref": "#/components/schemas/MarketplaceProductState" + }, + "settings": { + "$ref": "#/components/schemas/MarketplaceProductSettings" + }, + "visibleOffer": { + "$ref": "#/components/schemas/MarketplaceVisibleOffer" + } + }, + "required": [ + "id", + "name", + "regions", + "hasStripe" + ] + }, + "MarketplaceRegion": { + "type": "object", + "properties": { + "_id": { + "type": "string", + "minLength": 1, + "maxLength": 50 + }, + "_creationTime": { + "type": "number" + }, + "workspaceId": { + "type": "string", + "minLength": 1, + "maxLength": 50 + }, + "name": { + "type": "string" + }, + "icon": { + "type": "string" + } + }, + "required": [ + "_id", + "_creationTime", + "workspaceId", + "name" + ] + }, + "MarketplaceProductState": { + "type": "object", + "properties": { + "published": { + "type": "boolean" + }, + "externalUrl": { + "type": "string" + } + }, + "required": [ + "published" + ] + }, + "MarketplaceProductSettings": { + "type": "object", + "properties": { + "customImage": { + "type": "string" + }, + "customDescription": { + "type": "string" + }, + "showSources": { + "type": "boolean" + } + } + }, + "MarketplaceVisibleOffer": { + "type": "object", + "properties": { + "shortHash": { + "type": "string" + } + }, + "required": [ + "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": { + "id": { + "type": "string", + "minLength": 1, + "maxLength": 50 + }, + "name": { + "type": "string" + }, + "valuesSchema": { + "type": "string" + }, + "regions": { + "type": "array", + "items": { + "$ref": "#/components/schemas/MarketplaceRegion" + } + }, + "pricing": { + "type": "array", + "items": { + "$ref": "#/components/schemas/MarketplaceProductPricing" + } + }, + "isOwner": { + "type": "boolean" + }, + "settings": { + "$ref": "#/components/schemas/MarketplaceProductSettings" + }, + "stripePriceIds": { + "type": "array", + "items": { + "type": "string" + } + }, + "marketplace": { + "$ref": "#/components/schemas/MarketplaceProductState" + }, + "visibleOffer": { + "$ref": "#/components/schemas/MarketplaceVisibleOffer" + } + }, + "required": [ + "id", + "name", + "regions", + "pricing", + "isOwner", + "settings", + "stripePriceIds" + ] + }, + "MarketplaceProductPricing": { + "type": "object", + "properties": { + "price": { + "type": "number" + }, + "recurring": { + "type": "string" + }, + "currency": { + "type": "string" + } + }, + "required": [ + "price", + "currency" + ] + }, + "CreateProductBody": { + "type": "object", + "properties": { + "name": { + "type": "string", + "minLength": 2, + "maxLength": 64, + "example": "PostgreSQL Managed" + }, + "package_id": { + "type": "string", + "minLength": 1, + "maxLength": 54 + }, + "package_version_pin": { + "$ref": "#/components/schemas/PackageVersionPin" + }, + "custom_image": { + "type": "string", + "format": "uri", + "description": "Custom display image URL — overrides the package logo" + }, + "custom_description": { + "type": "string", + "maxLength": 500, + "description": "Custom display description — overrides the package description" + }, + "marketplace": { + "$ref": "#/components/schemas/ProductMarketplace" + } + }, + "required": [ + "name", + "package_id", + "package_version_pin" + ], + "additionalProperties": false + }, + "ProductMarketplace": { + "type": "object", + "properties": { + "published": { + "type": "boolean", + "description": "Whether the product is publicly visible on the marketplace" + } + }, + "required": [ + "published" + ], + "additionalProperties": false, + "description": "Marketplace listing config. Omit to keep the product unlisted." + }, + "UpdateProductBody": { + "type": "object", + "properties": { + "name": { + "type": "string", + "minLength": 2, + "maxLength": 64, + "example": "PostgreSQL Managed" + }, + "package_version_pin": { + "$ref": "#/components/schemas/PackageVersionPin" + }, + "custom_image": { + "type": "string", + "nullable": true, + "format": "uri" + }, + "custom_description": { + "type": "string", + "nullable": true, + "maxLength": 500 + }, + "marketplace": { + "$ref": "#/components/schemas/ProductMarketplace" + } + }, + "additionalProperties": false + }, + "ArchiveProductBody": { + "type": "object", + "properties": { + "cascade_offers": { + "type": "boolean", + "default": false + }, + "archive_reason": { + "type": "string", + "maxLength": 500 + } + }, + "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": { + "id": { + "type": "string", + "minLength": 1, + "maxLength": 54 + }, + "workspace_id": { + "type": "string", + "minLength": 1, + "maxLength": 53 + }, + "authority_workspace_id": { + "type": "string", + "minLength": 1, + "maxLength": 53 + }, + "display_name": { + "type": "string", + "minLength": 1, + "maxLength": 120 + }, + "partner_organization_id": { + "type": "string", + "minLength": 1, + "maxLength": 54 + }, + "product_scope": { + "$ref": "#/components/schemas/OfferChannelProductScope" + }, + "state": { + "type": "string", + "enum": [ + "active", + "archived" + ] + }, + "commercial_authority": { + "type": "string", + "enum": [ + "platform", + "workspace" + ] + }, + "active_channel_policy_id": { + "type": "string", + "minLength": 1, + "maxLength": 56 + }, + "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", + "display_name", + "product_scope", + "state", + "commercial_authority", + "created_at", + "etag" + ], + "x-platform-visibility": "TRUSTED_PARTNER" + }, + "OfferChannelProductScope": { + "oneOf": [ + { + "type": "object", + "properties": { + "type": { + "type": "string", + "enum": [ + "all_products" + ] + } + }, + "required": [ + "type" + ] + }, + { + "type": "object", + "properties": { + "type": { + "type": "string", + "enum": [ + "selected_products" + ] + }, + "product_ids": { + "type": "array", + "items": { + "type": "string", + "minLength": 1, + "maxLength": 55 + }, + "maxItems": 100 + } + }, + "required": [ + "type", + "product_ids" + ] + } + ], + "x-platform-visibility": "TRUSTED_PARTNER" + }, + "CreateOfferChannelBody": { + "type": "object", + "properties": { + "workspace_id": { + "type": "string", + "minLength": 1, + "maxLength": 53 + }, + "display_name": { + "type": "string", + "minLength": 1, + "maxLength": 120 + }, + "partner_organization_id": { + "type": "string", + "minLength": 1, + "maxLength": 54 + }, + "product_scope": { + "$ref": "#/components/schemas/OfferChannelProductScope" + }, + "commercial_authority": { + "type": "string", + "enum": [ + "platform", + "workspace" + ], + "default": "platform" + } + }, + "required": [ + "display_name", + "product_scope" + ], + "additionalProperties": false, + "x-platform-visibility": "TRUSTED_PARTNER" + }, + "OfferChannelList": { + "type": "object", + "properties": { + "data": { + "type": "array", + "items": { + "$ref": "#/components/schemas/OfferChannelListItem" + } + }, + "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": "TRUSTED_PARTNER" + }, + "OfferChannelListItem": { + "allOf": [ + { + "$ref": "#/components/schemas/OfferChannel" + }, + { + "type": "object", + "properties": { + "active_policy": { + "$ref": "#/components/schemas/ChannelPolicy" + } + } + } + ], + "x-platform-visibility": "TRUSTED_PARTNER" + }, + "ChannelPolicy": { + "type": "object", + "properties": { + "id": { + "type": "string", + "minLength": 1, + "maxLength": 56 + }, + "offer_channel_id": { + "type": "string", + "minLength": 1, + "maxLength": 54 + }, + "version": { + "type": "integer", + "minimum": 0, + "exclusiveMinimum": true + }, + "state": { + "type": "string", + "enum": [ + "draft", + "approved", + "active", + "archived" + ] + }, + "policy": { + "$ref": "#/components/schemas/ChannelPolicyPayload" + }, + "created_at": { + "type": "integer", + "minimum": 0, + "description": "Unix timestamp (seconds)" + }, + "approved_at": { + "type": "integer", + "minimum": 0, + "description": "Unix timestamp (seconds)" + }, + "activated_at": { + "type": "integer", + "minimum": 0, + "description": "Unix timestamp (seconds)" + }, + "etag": { + "type": "string" + } + }, + "required": [ + "id", + "offer_channel_id", + "version", + "state", + "policy", + "created_at", + "etag" + ], + "x-platform-visibility": "TRUSTED_PARTNER" + }, + "ChannelPolicyPayload": { + "type": "object", + "properties": { + "pricing_policy": { + "type": "object", + "properties": { + "type": { + "type": "string", + "enum": [ + "fixed_or_range" + ] + }, + "currency": { + "type": "string", + "enum": [ + "eur", + "usd" + ] + }, + "default_unit_amount": { + "type": "integer", + "minimum": 0 + }, + "minimum_unit_amount": { + "type": "integer", + "minimum": 0 + }, + "maximum_unit_amount": { + "type": "integer", + "minimum": 0 + }, + "interval": { + "$ref": "#/components/schemas/PricingInterval" + } + }, + "required": [ + "type", + "currency", + "default_unit_amount", + "minimum_unit_amount", + "maximum_unit_amount", + "interval" + ], + "additionalProperties": false + }, + "settlement_policy": { + "type": "object", + "properties": { + "type": { + "type": "string", + "enum": [ + "platform_resolved" + ] + }, + "allowed_commercial_modes": { + "type": "array", + "items": { + "$ref": "#/components/schemas/CommercialMode" + }, + "minItems": 1 + } + }, + "required": [ + "type", + "allowed_commercial_modes" + ], + "additionalProperties": false + }, + "approval_policy": { + "type": "object", + "properties": { + "paid_offers": { + "type": "string", + "enum": [ + "requires_platform_approval", + "auto_approved" + ] + }, + "non_billable_test_offers": { + "type": "string", + "enum": [ + "requires_platform_approval", + "auto_approved" + ] + } + }, + "required": [ + "paid_offers", + "non_billable_test_offers" + ], + "additionalProperties": false + }, + "trusted_testing_policy": { + "type": "object", + "properties": { + "stripe_checkout_environment": { + "type": "string", + "enum": [ + "sandbox" + ] + } + }, + "required": [ + "stripe_checkout_environment" + ], + "additionalProperties": false + }, + "support_access_policy": { + "$ref": "#/components/schemas/OfferSupportScope" + } + }, + "required": [ + "pricing_policy", + "settlement_policy", + "approval_policy", + "support_access_policy" + ], + "additionalProperties": false, + "x-platform-visibility": "TRUSTED_PARTNER" + }, + "PricingInterval": { + "type": "string", + "enum": [ + "month", + "year" + ] + }, + "CommercialMode": { + "type": "string", + "enum": [ + "paid", + "non_billable_test" + ], + "description": "Customer commercial path requested for an offer. `paid` routes through checkout when policy requires it; `non_billable_test` creates a non-billable test offer when policy allows it." + }, + "OfferSupportScope": { + "type": "object", + "properties": { + "type": { + "type": "string", + "enum": [ + "scoped_support_relationship" + ] + }, + "visibility": { + "type": "array", + "items": { + "type": "string", + "enum": [ + "install_state", + "app_urls" + ] + }, + "maxItems": 20 + } + }, + "required": [ + "type", + "visibility" + ], + "additionalProperties": false + }, + "CreateChannelPolicyBody": { + "type": "object", + "properties": { + "offer_channel_id": { + "type": "string", + "minLength": 1, + "maxLength": 54 + }, + "policy": { + "$ref": "#/components/schemas/ChannelPolicyPayload" + } + }, + "required": [ + "offer_channel_id", + "policy" + ], + "additionalProperties": false, + "x-platform-visibility": "TRUSTED_PARTNER" + }, + "ChannelPolicyList": { + "type": "object", + "properties": { + "data": { + "type": "array", + "items": { + "$ref": "#/components/schemas/ChannelPolicy" + } + }, + "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": "TRUSTED_PARTNER" + }, + "OfferList": { + "type": "object", + "properties": { + "data": { + "type": "array", + "items": { + "$ref": "#/components/schemas/Offer" + } + }, + "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" + ] + }, + "Offer": { + "type": "object", + "properties": { + "id": { + "type": "string", + "minLength": 1, + "maxLength": 56, + "description": "Offer ID" + }, + "short_hash": { + "type": "string", + "description": "8-char base62 code that appears in the customer-clicked URL `/i/`", + "example": "aB3xK9pQ" + }, + "workspace_id": { + "type": "string", + "minLength": 1, + "maxLength": 53, + "description": "Workspace ID" + }, + "target_workspace_id": { + "type": "string", + "minLength": 1, + "maxLength": 53, + "description": "Optional workspace that receives the offer outcome when visible to the caller" + }, + "created_by": { + "type": "string", + "description": "User ID of the seller who issued the offer" + }, + "product_id": { + "type": "string", + "minLength": 1, + "maxLength": 55, + "description": "Product ID" + }, + "package_id": { + "type": "string", + "minLength": 1, + "maxLength": 54, + "description": "Package ID" + }, + "package_version_id": { + "type": "string", + "minLength": 1, + "maxLength": 55, + "description": "Package version ID — pinned at create time" + }, + "input_schema": { + "type": "object", + "additionalProperties": { + "nullable": true + }, + "description": "JSON Schema 2020-12 with x-ui extensions for the pinned package version. Present on customer resolve responses so the install wizard can render the configure step." + }, + "allowed_emails": { + "type": "array", + "items": { + "type": "string" + }, + "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", + "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" + }, + "redacted": { + "type": "boolean", + "enum": [ + true + ], + "description": "True when a configured sensitive value was removed from this response" + } + }, + "required": [ + "value", + "locked" + ] + }, + "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", + "description": "Suggested billing tier" + }, + "region_id": { + "type": "string", + "minLength": 1, + "maxLength": 54, + "description": "Region pin" + }, + "cluster_id": { + "type": "string", + "minLength": 1, + "maxLength": 54, + "description": "Cluster pin" + }, + "offer_channel_id": { + "type": "string", + "minLength": 1, + "maxLength": 54, + "description": "Offer Channel that resolved private-offer policy for this offer" + }, + "commercial_mode": { + "$ref": "#/components/schemas/CommercialMode" + }, + "approval_state": { + "$ref": "#/components/schemas/OfferApprovalState" + }, + "requested_policy_snapshot": { + "$ref": "#/components/schemas/OfferPolicySnapshot" + }, + "approved_policy_snapshot": { + "$ref": "#/components/schemas/OfferPolicySnapshot" + }, + "notes": { + "type": "string" + }, + "expires_at": { + "type": "integer", + "minimum": 0, + "description": "Unix timestamp (seconds)" + }, + "max_uses": { + "type": "integer", + "minimum": 0, + "exclusiveMinimum": true + }, + "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)." + }, + "used_count": { + "type": "integer", + "minimum": 0 + }, + "archived_at": { + "type": "integer", + "minimum": 0, + "description": "Unix timestamp (seconds)" + }, + "status": { + "$ref": "#/components/schemas/OfferStatus" + }, + "created_at": { + "type": "integer", + "minimum": 0, + "description": "Unix timestamp (seconds)" + }, + "updated_at": { + "type": "integer", + "minimum": 0, + "description": "Unix timestamp (seconds)" + }, + "etag": { + "type": "string" + }, + "product_name": { + "type": "string", + "description": "Display name of the offered product" + }, + "image_url": { + "type": "string", + "description": "Logo or icon URL for the customer landing page" + }, + "seller_name": { + "type": "string", + "description": "Display name of the seller who issued this offer" + } + }, + "required": [ + "id", + "short_hash", + "package_id", + "package_version_id", + "status", + "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": [ + "not_required", + "pending", + "approved", + "rejected" + ] + }, + "OfferPolicySnapshot": { + "type": "object", + "properties": { + "offer_channel_id": { + "type": "string", + "minLength": 1, + "maxLength": 54 + }, + "channel_policy_id": { + "type": "string", + "minLength": 1, + "maxLength": 56 + }, + "channel_policy_version": { + "type": "integer", + "minimum": 0, + "exclusiveMinimum": true + }, + "commercial_mode": { + "$ref": "#/components/schemas/CommercialMode" + }, + "approval_required": { + "type": "boolean" + }, + "checkout_required": { + "type": "boolean" + }, + "approval_mode": { + "type": "string", + "enum": [ + "requires_platform_approval", + "auto_approved_within_policy" + ], + "x-platform-visibility": "TRUSTED_PARTNER" + }, + "checkout_environment": { + "type": "string", + "enum": [ + "none", + "stripe_live", + "stripe_sandbox" + ], + "x-platform-visibility": "TRUSTED_PARTNER" + }, + "pricing_bounds": { + "$ref": "#/components/schemas/OfferPricingBounds" + }, + "pricing_summary": { + "$ref": "#/components/schemas/OfferPricingSummary" + }, + "support_scope": { + "$ref": "#/components/schemas/OfferSupportScope" + }, + "blocking_reasons": { + "type": "array", + "items": { + "type": "string" + }, + "default": [] + } + }, + "required": [ + "offer_channel_id", + "channel_policy_id", + "channel_policy_version", + "commercial_mode", + "approval_required", + "checkout_required", + "support_scope" + ] + }, + "OfferPricingBounds": { + "type": "object", + "properties": { + "currency": { + "type": "string", + "enum": [ + "eur", + "usd" + ] + }, + "default_unit_amount": { + "type": "integer", + "minimum": 0 + }, + "minimum_unit_amount": { + "type": "integer", + "minimum": 0 + }, + "maximum_unit_amount": { + "type": "integer", + "minimum": 0 + }, + "interval": { + "$ref": "#/components/schemas/PricingInterval" + } + }, + "required": [ + "currency", + "default_unit_amount", + "minimum_unit_amount", + "maximum_unit_amount", + "interval" + ], + "additionalProperties": false, + "x-platform-visibility": "TRUSTED_PARTNER" + }, + "OfferPricingSummary": { + "type": "object", + "properties": { + "currency": { + "type": "string", + "enum": [ + "eur", + "usd" + ] + }, + "unit_amount": { + "type": "integer", + "minimum": 0 + }, + "interval": { + "$ref": "#/components/schemas/PricingInterval" + }, + "source": { + "type": "string", + "enum": [ + "channel_policy", + "request" + ] + } + }, + "required": [ + "currency", + "unit_amount", + "interval", + "source" + ] + }, + "OfferStatus": { + "type": "string", + "enum": [ + "active", + "archived", + "expired", + "redeemed" + ], + "description": "Computed lifecycle status — never set directly; derived from row state." + }, + "PreviewOfferBody": { + "type": "object", + "properties": { + "package_version_id": { + "type": "string", + "minLength": 1, + "maxLength": 55, + "description": "Package version ID to preview against. Preview requires a concrete package version because no offer row is created to store a resolved product pin." + }, + "product_id": { + "type": "string", + "minLength": 1, + "maxLength": 55, + "description": "Product ID for channel policy attribution." + }, + "target_workspace_id": { + "type": "string", + "minLength": 1, + "maxLength": 53, + "description": "Existing customer workspace used for preview context." + }, + "allowed_emails": { + "type": "array", + "items": { + "type": "string", + "maxLength": 254, + "format": "email" + }, + "maxItems": 50, + "description": "Verified customer email allowlist used for preview context." + }, + "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 used for preview context." + }, + "region_id": { + "type": "string", + "minLength": 1, + "maxLength": 54, + "description": "Delivery region pin used for preview context." + }, + "cluster_id": { + "type": "string", + "minLength": 1, + "maxLength": 54, + "description": "Delivery cluster pin used for preview context." + }, + "offer_channel_id": { + "type": "string", + "minLength": 1, + "maxLength": 54, + "description": "Offer Channel whose active policy is previewed." + }, + "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" + } + }, + "required": [ + "package_version_id", + "product_id", + "offer_channel_id", + "commercial_mode" + ], + "additionalProperties": false, + "description": "Preview channel policy resolution for a concrete package version and product before creating an offer.", + "x-platform-visibility": "TRUSTED_PARTNER" + }, + "OfferPricingRequest": { + "type": "object", + "properties": { + "currency": { + "type": "string", + "enum": [ + "eur", + "usd" + ], + "example": "eur", + "description": "ISO currency code for the requested price." + }, + "unit_amount": { + "type": "integer", + "minimum": 0, + "maximum": 100000000, + "description": "Requested price in the smallest currency unit, for example cents for EUR or USD." + }, + "interval": { + "allOf": [ + { + "$ref": "#/components/schemas/PricingInterval" + }, + { + "description": "Billing interval for the requested price." + } + ] + } + }, + "required": [ + "currency", + "unit_amount", + "interval" + ], + "additionalProperties": false, + "description": "Requested customer-visible price for channel policy resolution. The active policy validates the request before the offer is created." + }, + "OfferCreated": { + "type": "object", + "properties": { + "id": { + "type": "string", + "minLength": 1, + "maxLength": 56, + "description": "Offer ID" + }, + "short_hash": { + "type": "string" + } + }, + "required": [ + "id", + "short_hash" + ] + }, + "CreateOfferBody": { + "anyOf": [ + { + "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, + "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." + }, + "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`." + }, + "offer_channel_id": { + "type": "string", + "minLength": 1, + "maxLength": 54, + "description": "Offer Channel whose active policy resolves approval, checkout, support, and pricing terms. Requires `product_id`." + }, + "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)." + } + }, + "required": [ + "product_id" + ], + "additionalProperties": false + }, + { + "type": "object", + "properties": { + "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." + }, + "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." + }, + "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." + }, + "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`." + }, + "offer_channel_id": { + "type": "string", + "minLength": 1, + "maxLength": 54, + "description": "Offer Channel whose active policy resolves approval, checkout, support, and pricing terms. Requires `product_id`." + }, + "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)." + } + }, + "required": [ + "package_version_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." + }, + "OrderDraft": { + "type": "object", + "properties": { + "id": { + "type": "string", + "minLength": 1, + "maxLength": 55, + "description": "Order draft ID" + }, + "offer_id": { + "type": "string", + "minLength": 1, + "maxLength": 56, + "description": "Offer this order draft is redeeming" + }, + "status": { + "$ref": "#/components/schemas/OrderDraftStatus" + }, + "termination_reason": { + "$ref": "#/components/schemas/OrderDraftTerminationReason" + }, + "user_id": { + "type": "string", + "minLength": 1, + "description": "Authenticated customer" + }, + "customer_email": { + "type": "string" + }, + "workspace_id": { + "type": "string", + "minLength": 1, + "maxLength": 53, + "description": "Workspace selected/created during the workspace phase" + }, + "cluster_id": { + "type": "string", + "minLength": 1, + "maxLength": 54, + "description": "Cluster allocated during the compute phase" + }, + "cluster_ready": { + "type": "boolean" + }, + "server_joined": { + "type": "boolean" + }, + "payment_completed": { + "type": "boolean" + }, + "current_checkout_session": { + "$ref": "#/components/schemas/CurrentOrderDraftCheckoutSession" + }, + "install_operation_id": { + "type": "string", + "minLength": 1, + "maxLength": 53, + "description": "Operation tracking the spawned install workflow" + }, + "order": { + "$ref": "#/components/schemas/OrderSummary" + }, + "delivery": { + "$ref": "#/components/schemas/OrderDeliverySummary" + }, + "field_values": { + "type": "object", + "additionalProperties": { + "nullable": true + }, + "description": "Customer-supplied configure values, including any pre-fills from the offer. Only returned to the order draft’s own customer; never to other authed callers." + }, + "created_at": { + "type": "integer", + "minimum": 0, + "description": "Unix timestamp (seconds)" + }, + "updated_at": { + "type": "integer", + "minimum": 0, + "description": "Unix timestamp (seconds)" + }, + "etag": { + "type": "string" + }, + "ttl_expires_at": { + "type": "integer", + "minimum": 0, + "description": "Unix timestamp (seconds)" + } + }, + "required": [ + "id", + "offer_id", + "status", + "cluster_ready", + "server_joined", + "payment_completed", + "created_at", + "updated_at", + "etag", + "ttl_expires_at" + ] + }, + "OrderDraftStatus": { + "type": "string", + "enum": [ + "auth", + "workspace", + "compute", + "compute_bootstrap", + "configure", + "payment", + "install", + "done", + "cleaning_up", + "terminated" + ], + "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." + }, + "OrderDraftTerminationReason": { + "type": "string", + "enum": [ + "timeout", + "revoked", + "offer_expired", + "install_failed", + "cluster_allocation_failed", + "quota_exceeded" + ], + "description": "Set when status=terminated; explains why the order draft ended." + }, + "CurrentOrderDraftCheckoutSession": { + "type": "object", + "properties": { + "stripe_environment": { + "$ref": "#/components/schemas/StripeEnvironment" + }, + "id": { + "type": "string", + "description": "Stripe Checkout Session ID", + "example": "cs_test_..." + }, + "draft_revision": { + "type": "integer", + "minimum": 0, + "description": "Order draft revision this Checkout Session belongs to" + }, + "url": { + "type": "string", + "format": "uri", + "description": "Stripe-hosted Checkout URL" + }, + "expires_at": { + "type": "integer", + "minimum": 0, + "description": "Unix timestamp (seconds)" + } + }, + "required": [ + "stripe_environment", + "id", + "draft_revision" + ] + }, + "StripeEnvironment": { + "type": "string", + "enum": [ + "live", + "sandbox" + ], + "description": "Stripe payment environment for this Checkout Session." + }, + "OrderSummary": { + "type": "object", + "properties": { + "id": { + "type": "string", + "minLength": 1, + "maxLength": 54, + "description": "Order ID" + }, + "status": { + "$ref": "#/components/schemas/OrderStatus" + }, + "stripe_environment": { + "allOf": [ + { + "$ref": "#/components/schemas/StripeEnvironment" + }, + { + "description": "Stripe payment environment for paid Stripe checkout orders." + } + ] + }, + "stripe_checkout_id": { + "type": "string" + }, + "draft_revision": { + "type": "integer", + "minimum": 0 + }, + "cleanup_policy": { + "$ref": "#/components/schemas/OrderCleanupPolicy" + }, + "committed_at": { + "type": "integer", + "minimum": 0, + "description": "Unix timestamp (seconds)" + } + }, + "required": [ + "id", + "status", + "stripe_checkout_id", + "draft_revision", + "cleanup_policy", + "committed_at" + ] + }, + "OrderStatus": { + "type": "string", + "enum": [ + "delivery_pending", + "delivery_running", + "delivered", + "delivery_failed" + ] + }, + "OrderCleanupPolicy": { + "oneOf": [ + { + "type": "object", + "properties": { + "kind": { + "type": "string", + "enum": [ + "none" + ] + } + }, + "required": [ + "kind" + ], + "additionalProperties": false + }, + { + "type": "object", + "properties": { + "kind": { + "type": "string", + "enum": [ + "temporal_actor_ttl" + ] + }, + "cleanup_at": { + "type": "integer", + "minimum": 0, + "description": "Unix timestamp (seconds)" + }, + "removable_by": { + "type": "string", + "enum": [ + "platform_policy", + "platform_admin" + ] + }, + "conversion_required": { + "type": "string", + "enum": [ + "paid_order", + "platform_approval" + ] + } + }, + "required": [ + "kind", + "cleanup_at", + "removable_by", + "conversion_required" + ], + "additionalProperties": false + } + ], + "description": "Cleanup policy attached to committed order resources. Demo/test policies are visible so customers and sellers can see when resources will be removed." + }, + "OrderDeliverySummary": { + "type": "object", + "properties": { + "id": { + "type": "string", + "minLength": 1, + "maxLength": 55, + "description": "Order delivery ID" + }, + "kind": { + "type": "string", + "enum": [ + "install" + ] + }, + "authorization_kind": { + "type": "string", + "enum": [ + "paid_order", + "non_billable_test_order" + ] + }, + "status": { + "$ref": "#/components/schemas/OrderDeliveryStatus" + }, + "cleanup_policy": { + "$ref": "#/components/schemas/OrderCleanupPolicy" + }, + "install_id": { + "type": "string", + "minLength": 1, + "maxLength": 55 + }, + "urls": { + "type": "array", + "items": { + "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" + ] + } + }, + "install_operation_id": { + "type": "string", + "minLength": 1, + "maxLength": 53, + "description": "Operation tracking the spawned install workflow" + }, + "started_at": { + "type": "integer", + "minimum": 0, + "description": "Unix timestamp (seconds)" + }, + "completed_at": { + "type": "integer", + "minimum": 0, + "description": "Unix timestamp (seconds)" + } + }, + "required": [ + "id", + "kind", + "authorization_kind", + "status", + "cleanup_policy", + "urls" + ] + }, + "OrderDeliveryStatus": { + "type": "string", + "enum": [ + "pending", + "running", + "succeeded", + "failed" + ] + }, + "OrderDraftList": { + "type": "object", + "properties": { + "data": { + "type": "array", + "items": { + "$ref": "#/components/schemas/OrderDraft" + } + }, + "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" + ] + }, + "ClaimOrderDraftBody": { + "type": "object", + "properties": { + "claim_token": { + "type": "string" + } + }, + "required": [ + "claim_token" + ], + "additionalProperties": false + }, + "SelectOrderDraftWorkspaceBody": { + "oneOf": [ + { + "type": "object", + "properties": { + "kind": { + "type": "string", + "enum": [ + "existing" + ] + }, + "workspace_id": { + "type": "string", + "minLength": 1, + "maxLength": 53 + } + }, + "required": [ + "kind", + "workspace_id" + ], + "additionalProperties": false + }, + { + "type": "object", + "properties": { + "kind": { + "type": "string", + "enum": [ + "new" + ] + }, + "name": { + "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": [ + "kind" + ], + "additionalProperties": false + } + ] + }, + "SubmitConfigureOrderDraftBody": { + "type": "object", + "properties": { + "field_values": { + "type": "object", + "additionalProperties": { + "nullable": true + }, + "description": "Customer-supplied configure form values, keyed by field name" + } + }, + "required": [ + "field_values" + ], + "additionalProperties": false + }, + "OrderDraftWorkerBootstrap": { + "type": "object", + "properties": { + "token": { + "type": "string", + "description": "Short-lived worker join token (one-time view)." + }, + "expires_at": { + "type": "integer", + "minimum": 0, + "description": "Token expiry time (unix seconds)." + }, + "command": { + "type": "string", + "description": "Bash bootstrap command with the token already substituted, ready to run on a worker node." + }, + "cloud_init": { + "type": "string", + "description": "Cloud-init YAML with the token already substituted, ready to use as worker-node user-data." + }, + "artifacts": { + "$ref": "#/components/schemas/WorkerBootstrapArtifacts" + } + }, + "required": [ + "token", + "expires_at", + "command", + "cloud_init" + ] + }, + "WorkerBootstrapArtifacts": { + "type": "object", + "properties": { + "linux": { + "type": "object", + "properties": { + "amd64": { + "$ref": "#/components/schemas/WorkerBootstrapArtifact" + }, + "arm64": { + "$ref": "#/components/schemas/WorkerBootstrapArtifact" + } + } + }, + "windows": { + "type": "object", + "properties": { + "amd64": { + "$ref": "#/components/schemas/WorkerBootstrapArtifact" + }, + "arm64": { + "$ref": "#/components/schemas/WorkerBootstrapArtifact" + } + } + } + }, + "description": "Platform-specific bootstrap artifacts with tokens already substituted. Populated only on create responses." + }, + "WorkerBootstrapArtifact": { + "oneOf": [ + { + "type": "object", + "properties": { + "supported": { + "type": "boolean", + "enum": [ + true + ], + "description": "Whether this platform/architecture artifact is currently supported." + }, + "command": { + "type": "string", + "description": "Bootstrap command with the token already substituted. Reveal-on-create only." + }, + "shell": { + "type": "string", + "enum": [ + "bash", + "powershell" + ], + "description": "Shell expected to execute the bootstrap command or downloaded script." + }, + "download_url": { + "type": "string", + "format": "uri", + "description": "Token-free script URL used by the bootstrap command." + }, + "cloud_init": { + "type": "string", + "description": "Cloud-init YAML with the token already substituted. Reveal-on-create only." + } + }, + "required": [ + "supported" + ] + }, + { + "type": "object", + "properties": { + "supported": { + "type": "boolean", + "enum": [ + false + ], + "description": "Whether this platform/architecture artifact is currently supported. Unsupported entries do not include token-bearing commands." + } + }, + "required": [ + "supported" + ], + "additionalProperties": false + } + ] + }, + "OrderDraftCheckoutSession": { + "type": "object", + "properties": { + "id": { + "type": "string", + "description": "Stripe Checkout Session ID", + "example": "cs_test_..." + }, + "url": { + "type": "string", + "format": "uri", + "description": "Stripe-hosted Checkout URL" + }, + "expires_at": { + "type": "integer", + "minimum": 0, + "description": "Unix timestamp (seconds)" + }, + "stripe_environment": { + "$ref": "#/components/schemas/StripeEnvironment" + } + }, + "required": [ + "id", + "url", + "expires_at", + "stripe_environment" ] }, - "DashboardList": { + "CheckoutSessionList": { "type": "object", "properties": { "data": { "type": "array", "items": { - "$ref": "#/components/schemas/Dashboard" + "$ref": "#/components/schemas/CheckoutSession" } }, "has_more": { @@ -910,137 +15745,45 @@ "next_cursor" ] }, - "Dashboard": { + "CheckoutSession": { "type": "object", "properties": { "id": { "type": "string", - "example": "j572abc123def456" + "description": "Checkout session ID", + "example": "chk_j572abc..." }, - "html_url": { - "type": "string", - "maxLength": 2048, - "format": "uri", - "description": "Absolute dashboard URL for this resource. OUTPUT_ONLY.", - "example": "https://akua.dev/dashboards/dash_j572abc123def456" + "stripe_environment": { + "$ref": "#/components/schemas/StripeEnvironment" }, - "name": { + "order_draft_id": { "type": "string", - "example": "Cluster Overview" + "minLength": 1, + "maxLength": 55, + "description": "Parent order draft ID", + "example": "odft_j572abc..." }, - "description": { + "order_draft_etag_at_mint": { "type": "string", - "nullable": true, - "description": "Optional dashboard description" - }, - "workspace_id": { - "type": "string" + "description": "Parent order draft etag when this checkout session was minted." }, - "widgets": { - "type": "array", - "items": { - "$ref": "#/components/schemas/Widget" - }, - "description": "Output-only denormalized widget list for dashboard read models." + "state": { + "$ref": "#/components/schemas/CheckoutSessionStatus" }, - "created_by": { + "url": { "type": "string", - "description": "User ID of the dashboard creator" - }, - "created_at": { - "type": "integer", - "minimum": 0, - "description": "Unix timestamp (seconds)" + "format": "uri", + "description": "Stripe-hosted Checkout URL" }, - "updated_at": { + "expires_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": [ - { - "type": "number", - "enum": [ - 1 - ] - }, - { - "type": "number", - "enum": [ - 2 - ] - }, - { - "type": "number", - "enum": [ - 3 - ] - }, - { - "type": "number", - "enum": [ - 4 - ] - } - ] - }, - "display_type": { + "stripe_checkout_session_id": { "type": "string", - "nullable": true, - "enum": [ - "table", - "stat", - "json", - "logs", - null - ], - "description": "Controls how the snippet result is rendered in dashboard widgets" + "description": "Stripe Checkout session identifier", + "example": "cs_test_..." }, "created_at": { "type": "integer", @@ -1051,69 +15794,81 @@ "type": "integer", "minimum": 0, "description": "Unix timestamp (seconds)" - }, - "etag": { - "type": "string" } }, "required": [ "id", - "dashboard_id", - "widget_type", - "snippet_id", - "position", - "col_span", - "display_type", + "stripe_environment", + "order_draft_id", + "order_draft_etag_at_mint", + "state", + "stripe_checkout_session_id", "created_at", - "updated_at", - "etag" + "updated_at" ] }, - "WidgetList": { + "CheckoutSessionStatus": { + "type": "string", + "enum": [ + "open", + "expired", + "payment_failed", + "superseded", + "paid" + ] + }, + "DemoCleanupRemoval": { "type": "object", "properties": { - "data": { - "type": "array", - "items": { - "$ref": "#/components/schemas/Widget" - } + "order_id": { + "type": "string", + "minLength": 1, + "maxLength": 54, + "description": "Order whose demo cleanup was removed." }, - "has_more": { - "type": "boolean", - "description": "True if more items exist after this page." + "delivery_id": { + "type": "string", + "minLength": 1, + "maxLength": 55, + "description": "Order delivery whose demo cleanup was removed." }, - "next_cursor": { + "cleanup_workflow_id": { "type": "string", - "nullable": true, - "description": "Opaque cursor for the next page, or null if no more pages." + "minLength": 1, + "description": "Previously scheduled Temporal cleanup workflow ID. The workflow will skip after re-reading the removed cleanup policy." } }, "required": [ - "data", - "has_more", - "next_cursor" - ] + "order_id", + "delivery_id", + "cleanup_workflow_id" + ], + "additionalProperties": false, + "x-platform-visibility": "ADMIN" }, - "OperationEnvelope": { + "RemoveDemoCleanupAfterPlatformApprovalBody": { "type": "object", "properties": { - "operation_id": { + "reason": { "type": "string", "minLength": 1, - "maxLength": 53 + "maxLength": 1000, + "description": "Platform approval reason for removing non-billable demo cleanup." } }, "required": [ - "operation_id" - ] + "reason" + ], + "additionalProperties": false, + "x-platform-visibility": "ADMIN" }, - "MachineList": { + "EntitlementList": { "type": "object", "properties": { "data": { "type": "array", "items": { - "$ref": "#/components/schemas/Machine" + "$ref": "#/components/schemas/Entitlement" } }, "has_more": { @@ -1124,275 +15879,118 @@ "type": "string", "nullable": true, "description": "Opaque cursor for the next page, or null if no more pages." + }, + "etag": { + "type": "string" } }, "required": [ "data", "has_more", - "next_cursor" + "next_cursor", + "etag" ] }, - "Machine": { + "Entitlement": { "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": { + "feature": { "type": "object", "properties": { - "identity_kind": { - "type": "string", - "enum": [ - "recyclable", - "persistent" - ] + "feature_set": { + "type": "string" }, - "public_ip": { - "type": "string", - "nullable": true + "key": { + "type": "string" }, - "floating_ip": { + "name": { + "type": "string" + } + }, + "required": [ + "feature_set", + "key", + "name" + ] + }, + "allocation": { + "oneOf": [ + { "type": "object", "properties": { - "id": { - "type": "string" + "type": { + "type": "string", + "enum": [ + "bool" + ] }, - "ipv4": { - "type": "string" + "value": { + "type": "boolean" } }, "required": [ - "id", - "ipv4" + "type", + "value" ] - } - }, - "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": { "type": "string", "enum": [ - "hcloud" + "max_count" ] }, - "snapshot_id": { - "type": "integer" - }, - "size_gb": { - "type": "number" + "value": { + "type": "integer", + "minimum": 0 } }, "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" + "type", + "value" ] - } - }, - "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": "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)" + "properties": { + "type": { + "type": "string", + "enum": [ + "unlimited" + ] + }, + "value": { + "nullable": true + } + }, + "required": [ + "type", + "value" + ] + } + ] } }, "required": [ - "id", - "machine_id", - "state", - "etag", - "created_at", - "started_at", - "expires_at" + "workspace_id", + "feature", + "allocation" ] }, - "DriftReportList": { + "OperationList": { "type": "object", "properties": { "data": { "type": "array", "items": { - "$ref": "#/components/schemas/DriftReport" + "$ref": "#/components/schemas/Operation" } }, "has_more": { @@ -1411,173 +16009,149 @@ "next_cursor" ] }, - "SuspensionEventList": { + "Operation": { "type": "object", "properties": { - "data": { - "type": "array", - "items": { - "$ref": "#/components/schemas/SuspensionEvent" - } - }, - "has_more": { - "type": "boolean", - "description": "True if more items exist after this page." + "id": { + "type": "string", + "minLength": 1, + "maxLength": 53 }, - "next_cursor": { + "workspace_id": { "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 + "maxLength": 53 }, - "machine_id": { + "organization_id": { "type": "string", + "nullable": true, "minLength": 1, "maxLength": 54 }, - "state": { + "owner_type": { "type": "string", "enum": [ - "in_progress", - "completed", - "resumed", - "expired" + "install", + "repository_change_request", + "repository", + "workspace", + "machine", + "cluster", + "package" ], - "description": "Suspension-event lifecycle state." + "description": "Domain entity collection the operation acts on." }, - "started_at": { - "type": "integer", - "minimum": 0, - "description": "Unix timestamp (seconds)" + "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_`)." }, - "resumed_at": { - "type": "integer", - "minimum": 0, - "description": "Unix timestamp (seconds)" + "parent_operation_id": { + "type": "string", + "nullable": true, + "minLength": 1, + "maxLength": 53, + "description": "ID of the chained parent operation, when present." }, - "expires_at": { - "type": "integer", - "minimum": 0, - "description": "Unix timestamp (seconds)" + "state": { + "type": "string", + "enum": [ + "RUNNING", + "SUCCEEDED", + "FAILED", + "CANCELLED" + ], + "description": "Lifecycle state. Past-participle terminal states per AIP-216." }, - "snapshot_ref": { - "type": "object", - "properties": { - "provider": { - "type": "string", - "enum": [ - "hcloud" - ] - }, - "snapshot_id": { - "type": "integer" - }, - "size_gb": { - "type": "number" - } - }, - "required": [ - "provider", - "snapshot_id", - "size_gb" - ] + "done": { + "type": "boolean", + "description": "True iff state is a terminal value." }, - "monthly_cost_cents": { - "type": "integer" + "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" }, - "total_cost_cents": { - "type": "integer" + "metadata": { + "$ref": "#/components/schemas/OperationMetadata" }, - "reason": { - "type": "string", - "enum": [ - "manual", - "downgrade" - ] + "response": { + "$ref": "#/components/schemas/OperationResponse" }, - "etag": { - "type": "string" - } - }, - "required": [ - "id", - "machine_id", - "state", - "started_at", - "expires_at", - "snapshot_ref", - "monthly_cost_cents", - "reason", - "etag" - ] - }, - "CredentialScope": { - "oneOf": [ - { + "error": { "type": "object", + "nullable": true, "properties": { - "kind": { - "type": "string", - "enum": [ - "system" - ], - "description": "Use system-managed provider credentials." + "message": { + "type": "string" } }, "required": [ - "kind" + "message" ], - "additionalProperties": false + "description": "Populated when `state` is `FAILED` or `CANCELLED`." }, - { + "last_error": { "type": "object", + "nullable": true, "properties": { - "kind": { - "type": "string", - "enum": [ - "byom" - ] - }, - "secret_id": { - "type": "string", - "minLength": 1, - "maxLength": 54 + "message": { + "type": "string" }, - "secret_version_id": { - "type": "string", - "minLength": 1, - "maxLength": 55 + "step_name": { + "type": "string" } }, "required": [ - "kind", - "secret_id" + "message" ], - "additionalProperties": false + "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" + } } + }, + "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" ] }, - "ProductList": { + "DashboardInstallList": { "type": "object", "properties": { "data": { "type": "array", "items": { - "$ref": "#/components/schemas/Product" + "$ref": "#/components/schemas/DashboardInstall" } }, "has_more": { @@ -1596,69 +16170,62 @@ "next_cursor" ] }, - "Product": { + "DashboardInstall": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, - "maxLength": 55, - "example": "prod_j572abc123def456" + "maxLength": 55 }, "html_url": { "type": "string", "maxLength": 2048, "format": "uri", "description": "Absolute dashboard URL for this resource. OUTPUT_ONLY.", - "example": "https://akua.dev/products/prod_j572abc123def456" + "example": "https://akua.dev/installs/inst_j572abc123def456" }, "name": { - "type": "string", - "example": "PostgreSQL Managed" + "type": "string" }, "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}`." + "cluster_id": { + "type": "string", + "minLength": 1, + "maxLength": 54 }, - "custom_image": { + "cluster_name": { + "type": "string" + }, + "region_name": { + "type": "string" + }, + "region_icon": { "type": "string", - "description": "Custom display image URL — overrides the package logo on customer-facing pages" + "nullable": true }, - "custom_description": { + "source": { + "$ref": "#/components/schemas/DashboardInstallSource" + }, + "state": { "type": "string", - "description": "Custom display description — overrides the package description" + "enum": [ + "pending", + "rendering", + "syncing", + "healthy", + "degraded", + "failed", + "deleted" + ], + "description": "Install lifecycle state from the control plane perspective." }, - "marketplace": { - "$ref": "#/components/schemas/ProductMarketplaceState" + "reconciling": { + "type": "boolean" }, "created_at": { "type": "integer", @@ -1672,23 +16239,6 @@ }, "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": [ @@ -1696,15 +16246,19 @@ "html_url", "name", "workspace_id", - "package", - "marketplace", + "cluster_id", + "cluster_name", + "region_name", + "region_icon", + "source", + "state", + "reconciling", "created_at", "updated_at", - "etag", - "state" + "etag" ] }, - "PackageVersionPin": { + "DashboardInstallSource": { "oneOf": [ { "type": "object", @@ -1712,12 +16266,26 @@ "kind": { "type": "string", "enum": [ - "latest" + "product" ] + }, + "id": { + "type": "string", + "minLength": 1, + "maxLength": 55 + }, + "name": { + "type": "string" + }, + "version": { + "$ref": "#/components/schemas/PackageVersionSummary" } }, "required": [ - "kind" + "kind", + "id", + "name", + "version" ], "additionalProperties": false }, @@ -1727,124 +16295,197 @@ "kind": { "type": "string", "enum": [ - "pinned" + "package" ] }, - "version": { + "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 + }, + "name": { + "type": "string" + }, + "version": { + "$ref": "#/components/schemas/PackageVersionSummary" } }, "required": [ "kind", + "id", + "name", "version" ], "additionalProperties": false + }, + { + "nullable": true } - ] - }, - "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." + "description": "Null only for legacy or incomplete persisted lineage; source identity and version are never fabricated." }, - "DashboardProductList": { + "PackageVersionSummary": { "type": "object", "properties": { - "data": { - "type": "array", - "items": { - "$ref": "#/components/schemas/DashboardProduct" - } - }, - "has_more": { - "type": "boolean", - "description": "True if more items exist after this page." + "id": { + "type": "string", + "minLength": 1, + "maxLength": 55 }, - "next_cursor": { + "semver": { "type": "string", - "nullable": true, - "description": "Opaque cursor for the next page, or null if no more pages." + "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": [ - "data", - "has_more", - "next_cursor" + "id", + "semver" ] }, - "DashboardProduct": { + "DashboardInstallDetail": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, - "maxLength": 55, - "example": "prod_j572abc123def456" + "maxLength": 55 }, "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" + "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 + }, + "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": { + "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": [ + "id", + "name", + "region" + ] + }, + "product": { + "type": "object", + "nullable": true, + "properties": { + "id": { + "type": "string", + "minLength": 1, + "maxLength": 55 + }, + "name": { + "type": "string" + }, + "is_owner": { + "type": "boolean" + } + }, + "required": [ + "id", + "name", + "is_owner" + ] + }, "package": { "type": "object", + "nullable": true, "properties": { "id": { "type": "string", "minLength": 1, - "maxLength": 54, - "example": "pkg_j572abc123def456" + "maxLength": 54 }, - "version_pin": { - "$ref": "#/components/schemas/PackageVersionPin" + "name": { + "type": "string" }, - "default_version_id": { + "source_kind": { "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." + "enum": [ + "hosted", + "oci" + ] + }, + "version": { + "$ref": "#/components/schemas/PackageVersionSummary" } }, "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}`." + "name", + "source_kind", + "version" + ] }, - "custom_image": { + "target_revision": { "type": "string", - "description": "Custom display image URL — overrides the package logo on dashboard catalog rows" + "nullable": true }, - "marketplace": { - "$ref": "#/components/schemas/ProductMarketplaceState" + "demo_cleanup": { + "$ref": "#/components/schemas/InstallDemoCleanup" }, "created_at": { "type": "integer", @@ -1858,500 +16499,307 @@ }, "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", - "minimum": 0 - }, - "region_count": { - "type": "integer", - "minimum": 0 - }, - "offer_count": { - "type": "integer", - "minimum": 0 - }, - "install_count": { - "type": "integer", - "minimum": 0 } }, "required": [ "id", "html_url", - "name", "workspace_id", + "cluster_id", + "deploy_repository_id", + "name", + "is_standalone", + "argo_app_namespace", + "public_urls", + "argo_status", + "cluster", + "product", "package", - "marketplace", + "target_revision", "created_at", "updated_at", - "etag", - "state", - "cluster_count", - "region_count", - "offer_count", - "install_count" + "etag" ] }, - "MarketplaceProductList": { - "type": "array", - "items": { - "$ref": "#/components/schemas/MarketplaceProduct" - } - }, - "MarketplaceProduct": { + "InstallUrl": { "type": "object", "properties": { - "id": { - "type": "string", - "minLength": 1, - "maxLength": 50 - }, - "name": { + "route_key": { "type": "string" }, - "regions": { - "type": "array", - "items": { - "$ref": "#/components/schemas/MarketplaceRegion" - } - }, - "hasStripe": { - "type": "boolean" - }, - "marketplace": { - "$ref": "#/components/schemas/MarketplaceProductState" - }, - "settings": { - "$ref": "#/components/schemas/MarketplaceProductSettings" + "hostname": { + "type": "string" }, - "visibleOffer": { - "$ref": "#/components/schemas/MarketplaceVisibleOffer" - } - }, - "required": [ - "id", - "name", - "regions", - "hasStripe" - ] - }, - "MarketplaceRegion": { - "type": "object", - "properties": { - "_id": { + "url": { "type": "string", - "minLength": 1, - "maxLength": 50 - }, - "_creationTime": { - "type": "number" + "format": "uri" }, - "workspaceId": { + "protocol": { "type": "string", - "minLength": 1, - "maxLength": 50 + "enum": [ + "http", + "websocket", + "grpc" + ], + "description": "Transport class for route forwarding." }, - "name": { - "type": "string" + "routing_mode": { + "type": "string", + "enum": [ + "through_dispatcher", + "bypass_dispatcher" + ], + "description": "Whether traffic uses the dispatcher Worker or bypasses it." }, - "icon": { - "type": "string" - } - }, - "required": [ - "_id", - "_creationTime", - "workspaceId", - "name" - ] - }, - "MarketplaceProductState": { - "type": "object", - "properties": { - "published": { - "type": "boolean" + "status": { + "type": "string", + "enum": [ + "pending", + "provisioning", + "active", + "not_ready", + "failed" + ], + "description": "Customer-facing install URL routing state." }, - "externalUrl": { - "type": "string" - } - }, - "required": [ - "published" - ] - }, - "MarketplaceProductSettings": { - "type": "object", - "properties": { - "customImage": { + "error": { "type": "string" }, - "customDescription": { - "type": "string" + "last_observed_at": { + "type": "integer", + "minimum": 0, + "description": "Unix timestamp (seconds)" }, - "showSources": { - "type": "boolean" - } - } - }, - "MarketplaceVisibleOffer": { - "type": "object", - "properties": { - "shortHash": { - "type": "string" + "updated_at": { + "type": "integer", + "minimum": 0, + "description": "Unix timestamp (seconds)" } }, "required": [ - "shortHash" + "route_key", + "hostname", + "url", + "protocol", + "routing_mode", + "status", + "updated_at" ] }, - "MarketplaceProductDetail": { + "DashboardInstallArgoStatus": { "type": "object", + "nullable": true, "properties": { - "id": { - "type": "string", - "minLength": 1, - "maxLength": 50 - }, - "name": { - "type": "string" - }, - "valuesSchema": { - "type": "string" - }, - "regions": { - "type": "array", - "items": { - "$ref": "#/components/schemas/MarketplaceRegion" - } - }, - "pricing": { - "type": "array", - "items": { - "$ref": "#/components/schemas/MarketplaceProductPricing" - } - }, - "isOwner": { - "type": "boolean" - }, - "settings": { - "$ref": "#/components/schemas/MarketplaceProductSettings" - }, - "stripePriceIds": { - "type": "array", - "items": { - "type": "string" + "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 } }, - "marketplace": { - "$ref": "#/components/schemas/MarketplaceProductState" - }, - "visibleOffer": { - "$ref": "#/components/schemas/MarketplaceVisibleOffer" + "updated_at": { + "type": "integer", + "minimum": 0, + "description": "Unix timestamp (seconds)" } }, "required": [ - "id", - "name", - "regions", - "pricing", - "isOwner", - "settings", - "stripePriceIds" + "status", + "updated_at" ] }, - "MarketplaceProductPricing": { + "ResourceStatus": { "type": "object", "properties": { - "price": { - "type": "number" - }, - "recurring": { + "group": { "type": "string" }, - "currency": { + "kind": { "type": "string" - } - }, - "required": [ - "price", - "currency" - ] - }, - "CreateProductBody": { - "type": "object", - "properties": { - "name": { - "type": "string", - "minLength": 2, - "maxLength": 64, - "example": "PostgreSQL Managed" - }, - "package_id": { - "type": "string", - "minLength": 1, - "maxLength": 54 - }, - "package_version_pin": { - "$ref": "#/components/schemas/PackageVersionPin" - }, - "custom_image": { - "type": "string", - "format": "uri", - "description": "Custom display image URL — overrides the package logo" - }, - "custom_description": { - "type": "string", - "maxLength": 500, - "description": "Custom display description — overrides the package description" }, - "marketplace": { - "$ref": "#/components/schemas/ProductMarketplace" - } - }, - "required": [ - "name", - "package_id", - "package_version_pin" - ], - "additionalProperties": false - }, - "ProductMarketplace": { - "type": "object", - "properties": { - "published": { - "type": "boolean", - "description": "Whether the product is publicly visible on the marketplace" - } - }, - "required": [ - "published" - ], - "additionalProperties": false, - "description": "Marketplace listing config. Omit to keep the product unlisted." - }, - "UpdateProductBody": { - "type": "object", - "properties": { "name": { - "type": "string", - "minLength": 2, - "maxLength": 64, - "example": "PostgreSQL Managed" - }, - "package_version_pin": { - "$ref": "#/components/schemas/PackageVersionPin" - }, - "custom_image": { - "type": "string", - "nullable": true, - "format": "uri" - }, - "custom_description": { - "type": "string", - "nullable": true, - "maxLength": 500 - }, - "marketplace": { - "$ref": "#/components/schemas/ProductMarketplace" - } - }, - "additionalProperties": false - }, - "ArchiveProductBody": { - "type": "object", - "properties": { - "cascade_offers": { - "type": "boolean", - "default": false - }, - "archive_reason": { - "type": "string", - "maxLength": 500 - } - }, - "additionalProperties": false - }, - "OfferChannel": { - "type": "object", - "properties": { - "id": { - "type": "string", - "minLength": 1, - "maxLength": 54 - }, - "workspace_id": { - "type": "string", - "minLength": 1, - "maxLength": 53 - }, - "authority_workspace_id": { - "type": "string", - "minLength": 1, - "maxLength": 53 - }, - "display_name": { - "type": "string", - "minLength": 1, - "maxLength": 120 - }, - "partner_organization_id": { - "type": "string", - "minLength": 1, - "maxLength": 54 - }, - "product_scope": { - "$ref": "#/components/schemas/OfferChannelProductScope" - }, - "state": { - "type": "string", - "enum": [ - "active", - "archived" - ] - }, - "commercial_authority": { - "type": "string", - "enum": [ - "platform", - "workspace" - ] + "type": "string" }, - "active_channel_policy_id": { - "type": "string", - "minLength": 1, - "maxLength": 56 + "message": { + "type": "string" }, - "created_at": { - "type": "integer", - "minimum": 0, - "description": "Unix timestamp (seconds)" + "namespace": { + "type": "string" }, - "updated_at": { - "type": "integer", - "minimum": 0, - "description": "Unix timestamp (seconds)" + "version": { + "type": "string" }, - "etag": { + "status": { "type": "string" + }, + "health": { + "type": "object", + "properties": { + "status": { + "type": "string" + }, + "message": { + "type": "string" + } + }, + "required": [ + "status" + ] } }, "required": [ - "id", - "workspace_id", - "display_name", - "product_scope", - "state", - "commercial_authority", - "created_at", - "etag" + "kind", + "name" ], - "x-platform-visibility": "TRUSTED_PARTNER" + "additionalProperties": { + "nullable": true + } }, - "OfferChannelProductScope": { + "InstallDemoCleanup": { "oneOf": [ { "type": "object", "properties": { - "type": { + "kind": { "type": "string", "enum": [ - "all_products" + "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": [ - "type" - ] + "kind", + "cleanup_at", + "removable_by", + "conversion_required", + "delivery_status" + ], + "additionalProperties": false }, { "type": "object", "properties": { - "type": { + "kind": { "type": "string", "enum": [ - "selected_products" + "removed" ] }, - "product_ids": { - "type": "array", - "items": { - "type": "string", - "minLength": 1, - "maxLength": 55 - }, - "maxItems": 100 + "delivery_status": { + "type": "string", + "enum": [ + "pending", + "running", + "succeeded", + "failed" + ], + "description": "Order delivery status for the demo install whose cleanup was removed." } }, "required": [ - "type", - "product_ids" - ] - } - ], - "x-platform-visibility": "TRUSTED_PARTNER" - }, - "CreateOfferChannelBody": { - "type": "object", - "properties": { - "workspace_id": { - "type": "string", - "minLength": 1, - "maxLength": 53 - }, - "display_name": { - "type": "string", - "minLength": 1, - "maxLength": 120 - }, - "partner_organization_id": { - "type": "string", - "minLength": 1, - "maxLength": 54 - }, - "product_scope": { - "$ref": "#/components/schemas/OfferChannelProductScope" - }, - "commercial_authority": { - "type": "string", - "enum": [ - "platform", - "workspace" + "kind", + "delivery_status" ], - "default": "platform" + "additionalProperties": false } - }, - "required": [ - "display_name", - "product_scope" ], - "additionalProperties": false, - "x-platform-visibility": "TRUSTED_PARTNER" + "description": "Visible cleanup state for non-billable demo installs. Temporal workflow IDs and internal cleanup evidence are intentionally omitted." }, - "OfferChannelList": { + "ManagedInstallList": { "type": "object", "properties": { "data": { "type": "array", "items": { - "$ref": "#/components/schemas/OfferChannelListItem" + "$ref": "#/components/schemas/ManagedInstall" } }, "has_more": { @@ -2368,273 +16816,492 @@ "data", "has_more", "next_cursor" - ], - "x-platform-visibility": "TRUSTED_PARTNER" - }, - "OfferChannelListItem": { - "allOf": [ - { - "$ref": "#/components/schemas/OfferChannel" - }, - { - "type": "object", - "properties": { - "active_policy": { - "$ref": "#/components/schemas/ChannelPolicy" - } - } - } - ], - "x-platform-visibility": "TRUSTED_PARTNER" + ] }, - "ChannelPolicy": { + "ManagedInstall": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, - "maxLength": 56 + "maxLength": 55 }, - "offer_channel_id": { + "name": { "type": "string", - "minLength": 1, - "maxLength": 54 + "nullable": true + }, + "customer": { + "type": "object", + "properties": { + "workspace_id": { + "type": "string", + "minLength": 1, + "maxLength": 53 + }, + "name": { + "type": "string" + }, + "icon": { + "type": "string", + "nullable": true + } + }, + "required": [ + "workspace_id", + "name", + "icon" + ] + }, + "can_manage": { + "type": "boolean" + }, + "product": { + "type": "object", + "nullable": true, + "properties": { + "id": { + "type": "string", + "minLength": 1, + "maxLength": 55 + }, + "name": { + "type": "string" + } + }, + "required": [ + "id", + "name" + ] }, "version": { + "anyOf": [ + { + "$ref": "#/components/schemas/PackageVersionSummary" + }, + { + "nullable": true + } + ] + }, + "current_version": { + "anyOf": [ + { + "$ref": "#/components/schemas/PackageVersionSummary" + }, + { + "nullable": true + } + ] + }, + "desired_version": { + "anyOf": [ + { + "$ref": "#/components/schemas/PackageVersionSummary" + }, + { + "nullable": true + } + ] + }, + "available_version": { + "anyOf": [ + { + "$ref": "#/components/schemas/PackageVersionSummary" + }, + { + "nullable": true + } + ] + }, + "automatic_updates_enabled": { + "type": "boolean" + }, + "lifecycle_revision": { "type": "integer", - "minimum": 0, - "exclusiveMinimum": true + "minimum": 0 }, - "state": { + "etag": { + "type": "string" + }, + "rollback_target": { + "anyOf": [ + { + "$ref": "#/components/schemas/ManagedInstallRollbackTarget" + }, + { + "nullable": true + } + ] + }, + "cluster": { + "type": "object", + "nullable": true, + "properties": { + "id": { + "type": "string", + "minLength": 1, + "maxLength": 54 + }, + "name": { + "type": "string" + } + }, + "required": [ + "id", + "name" + ] + }, + "region": { + "type": "object", + "nullable": true, + "properties": { + "id": { + "type": "string", + "minLength": 1, + "maxLength": 54 + }, + "name": { + "type": "string" + }, + "icon": { + "type": "string", + "nullable": true + } + }, + "required": [ + "id", + "name", + "icon" + ] + }, + "health": { "type": "string", + "nullable": true, "enum": [ - "draft", - "approved", - "active", - "archived" + "Unknown", + "Progressing", + "Healthy", + "Suspended", + "Degraded", + "Missing", + null ] }, - "policy": { - "$ref": "#/components/schemas/ChannelPolicyPayload" + "state": { + "type": "string", + "enum": [ + "pending", + "rendering", + "syncing", + "healthy", + "degraded", + "failed", + "deleted" + ], + "description": "Install lifecycle state from the control plane perspective." }, - "created_at": { - "type": "integer", - "minimum": 0, - "description": "Unix timestamp (seconds)" + "reconciling": { + "type": "boolean" }, - "approved_at": { + "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)" }, - "activated_at": { + "updated_at": { "type": "integer", "minimum": 0, "description": "Unix timestamp (seconds)" - }, - "etag": { - "type": "string" } }, "required": [ "id", - "offer_channel_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", - "policy", + "reconciling", + "urls", + "update_available", + "attention_reasons", "created_at", - "etag" + "updated_at" ], - "x-platform-visibility": "TRUSTED_PARTNER" + "description": "A bounded operations projection for an install in a workspace managed by the requesting organization." }, - "ChannelPolicyPayload": { + "ManagedInstallRollbackTarget": { "type": "object", "properties": { - "pricing_policy": { + "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": { + "product_id": { "type": "string", - "enum": [ - "fixed_or_range" - ] + "minLength": 1, + "maxLength": 55 }, - "currency": { + "status": { "type": "string", "enum": [ - "eur", - "usd" + "backfilling" ] - }, - "default_unit_amount": { - "type": "integer", - "minimum": 0 - }, - "minimum_unit_amount": { - "type": "integer", - "minimum": 0 - }, - "maximum_unit_amount": { - "type": "integer", - "minimum": 0 - }, - "interval": { - "$ref": "#/components/schemas/PricingInterval" } }, "required": [ - "type", - "currency", - "default_unit_amount", - "minimum_unit_amount", - "maximum_unit_amount", - "interval" + "product_id", + "status" ], "additionalProperties": false }, - "settlement_policy": { + { "type": "object", "properties": { - "type": { + "product_id": { + "type": "string", + "minLength": 1, + "maxLength": 55 + }, + "status": { "type": "string", "enum": [ - "platform_resolved" + "ready" ] }, - "allowed_commercial_modes": { + "data": { "type": "array", "items": { - "$ref": "#/components/schemas/CommercialMode" - }, - "minItems": 1 - } - }, - "required": [ - "type", - "allowed_commercial_modes" - ], - "additionalProperties": false - }, - "approval_policy": { - "type": "object", - "properties": { - "paid_offers": { - "type": "string", - "enum": [ - "requires_platform_approval", - "auto_approved" - ] + "$ref": "#/components/schemas/ProductAttentionInstall" + } }, - "non_billable_test_offers": { + "has_more": { + "type": "boolean" + }, + "next_cursor": { "type": "string", - "enum": [ - "requires_platform_approval", - "auto_approved" - ] + "nullable": true } }, "required": [ - "paid_offers", - "non_billable_test_offers" + "product_id", + "status", + "data", + "has_more", + "next_cursor" ], "additionalProperties": false + } + ], + "x-platform-visibility": "INTERNAL" + }, + "ProductAttentionInstall": { + "allOf": [ + { + "$ref": "#/components/schemas/Install" }, - "trusted_testing_policy": { + { "type": "object", "properties": { - "stripe_checkout_environment": { + "attention_status": { "type": "string", "enum": [ - "sandbox" + "degraded", + "failed" ] + }, + "status_updated_at": { + "type": "integer", + "minimum": 0, + "description": "Unix timestamp (seconds)" } }, "required": [ - "stripe_checkout_environment" - ], - "additionalProperties": false - }, - "support_access_policy": { - "$ref": "#/components/schemas/OfferSupportScope" - } - }, - "required": [ - "pricing_policy", - "settlement_policy", - "approval_policy", - "support_access_policy" - ], - "additionalProperties": false, - "x-platform-visibility": "TRUSTED_PARTNER" - }, - "PricingInterval": { - "type": "string", - "enum": [ - "month", - "year" - ] - }, - "CommercialMode": { - "type": "string", - "enum": [ - "paid", - "non_billable_test" + "attention_status", + "status_updated_at" + ] + } ], - "description": "Customer commercial path requested for an offer. `paid` routes through checkout when policy requires it; `non_billable_test` creates a non-billable test offer when policy allows it." + "x-platform-visibility": "INTERNAL" }, - "OfferSupportScope": { + "InstallCustomerWorkspace": { "type": "object", "properties": { - "type": { + "id": { "type": "string", - "enum": [ - "scoped_support_relationship" - ] + "minLength": 1, + "maxLength": 53 }, - "visibility": { - "type": "array", - "items": { - "type": "string", - "enum": [ - "install_state", - "app_urls" - ] - }, - "maxItems": 20 + "name": { + "type": "string", + "minLength": 1, + "maxLength": 100 } }, "required": [ - "type", - "visibility" - ], - "additionalProperties": false + "id", + "name" + ] }, - "CreateChannelPolicyBody": { + "Install": { "type": "object", "properties": { - "offer_channel_id": { + "id": { "type": "string", "minLength": 1, - "maxLength": 54 + "maxLength": 55 }, - "policy": { - "$ref": "#/components/schemas/ChannelPolicyPayload" + "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": [ - "offer_channel_id", - "policy" - ], - "additionalProperties": false, - "x-platform-visibility": "TRUSTED_PARTNER" + "id", + "html_url", + "workspace_id", + "customer_workspace", + "package_version_id", + "state", + "reconciling", + "urls", + "created_at", + "updated_at", + "etag" + ] }, - "ChannelPolicyList": { + "InstallList": { "type": "object", "properties": { "data": { "type": "array", "items": { - "$ref": "#/components/schemas/ChannelPolicy" + "$ref": "#/components/schemas/Install" } }, "has_more": { @@ -2651,183 +17318,71 @@ "data", "has_more", "next_cursor" - ], - "x-platform-visibility": "TRUSTED_PARTNER" + ] }, - "OfferList": { + "InstallDomainSettings": { "type": "object", "properties": { - "data": { + "workspace_subdomain": { + "$ref": "#/components/schemas/InstallDomainSettingsWorkspaceSubdomain" + }, + "preview_hostnames": { "type": "array", "items": { - "$ref": "#/components/schemas/Offer" + "$ref": "#/components/schemas/InstallDomainSettingsPreviewHostname" } }, - "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." + "custom_domains": { + "type": "array", + "items": { + "$ref": "#/components/schemas/InstallDomainSettingsCustomDomain" + } } }, "required": [ - "data", - "has_more", - "next_cursor" + "workspace_subdomain", + "preview_hostnames", + "custom_domains" ] }, - "Offer": { + "InstallDomainSettingsWorkspaceSubdomain": { "type": "object", + "nullable": true, "properties": { "id": { "type": "string", "minLength": 1, - "maxLength": 56, - "description": "Offer ID" - }, - "short_hash": { - "type": "string", - "description": "8-char base62 code that appears in the customer-clicked URL `/i/`", - "example": "aB3xK9pQ" + "maxLength": 54 }, "workspace_id": { "type": "string", "minLength": 1, - "maxLength": 53, - "description": "Workspace ID" - }, - "target_workspace_id": { - "type": "string", - "minLength": 1, - "maxLength": 53, - "description": "Optional workspace that receives the offer outcome when visible to the caller" - }, - "created_by": { - "type": "string", - "description": "User ID of the seller who issued the offer" - }, - "product_id": { - "type": "string", - "minLength": 1, - "maxLength": 55, - "description": "Product ID" - }, - "package_id": { - "type": "string", - "minLength": 1, - "maxLength": 54, - "description": "Package ID" - }, - "package_version_id": { - "type": "string", - "minLength": 1, - "maxLength": 55, - "description": "Package version ID — pinned at create time" - }, - "input_schema": { - "type": "object", - "additionalProperties": { - "nullable": true - }, - "description": "JSON Schema 2020-12 with x-ui extensions for the pinned package version. Present on customer resolve responses so the install wizard can render the configure step." - }, - "allowed_emails": { - "type": "array", - "items": { - "type": "string" - }, - "description": "Empty / omitted = anyone authed can claim. Non-empty = the customer's verified email must match. Only returned to authed callers." - }, - "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": "Seller pre-fills keyed by package input-schema property name. Only returned to authed callers whose email matches the allowlist." - }, - "tier": { - "type": "string", - "description": "Suggested billing tier" + "maxLength": 53 }, - "region_id": { + "name": { "type": "string", "minLength": 1, - "maxLength": 54, - "description": "Region pin" + "maxLength": 63 }, - "cluster_id": { + "fqdn": { "type": "string", "minLength": 1, - "maxLength": 54, - "description": "Cluster pin" + "maxLength": 253 }, - "offer_channel_id": { + "status": { "type": "string", - "minLength": 1, - "maxLength": 54, - "description": "Offer Channel that resolved private-offer policy for this offer" - }, - "commercial_mode": { - "$ref": "#/components/schemas/CommercialMode" - }, - "approval_state": { - "$ref": "#/components/schemas/OfferApprovalState" - }, - "requested_policy_snapshot": { - "$ref": "#/components/schemas/OfferPolicySnapshot" - }, - "approved_policy_snapshot": { - "$ref": "#/components/schemas/OfferPolicySnapshot" - }, - "notes": { - "type": "string" - }, - "expires_at": { - "type": "integer", - "minimum": 0, - "description": "Unix timestamp (seconds)" - }, - "max_uses": { - "type": "integer", - "minimum": 0, - "exclusiveMinimum": true - }, - "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)." - }, - "used_count": { - "type": "integer", - "minimum": 0 + "enum": [ + "active", + "propagating", + "reserved" + ] }, - "archived_at": { + "name_changed_at": { "type": "integer", + "nullable": true, "minimum": 0, "description": "Unix timestamp (seconds)" }, - "status": { - "$ref": "#/components/schemas/OfferStatus" - }, "created_at": { "type": "integer", "minimum": 0, @@ -2840,337 +17395,369 @@ }, "etag": { "type": "string" - }, - "product_name": { - "type": "string", - "description": "Display name of the offered product" - }, - "image_url": { - "type": "string", - "description": "Logo or icon URL for the customer landing page" - }, - "seller_name": { - "type": "string", - "description": "Display name of the seller who issued this offer" } }, "required": [ "id", - "short_hash", - "package_id", - "package_version_id", + "workspace_id", + "name", + "fqdn", "status", - "created_at" - ] - }, - "OfferApprovalState": { - "type": "string", - "enum": [ - "not_required", - "pending", - "approved", - "rejected" + "name_changed_at", + "created_at", + "updated_at", + "etag" ] }, - "OfferPolicySnapshot": { + "InstallDomainSettingsPreviewHostname": { "type": "object", "properties": { - "offer_channel_id": { + "id": { "type": "string", "minLength": 1, "maxLength": 54 }, - "channel_policy_id": { + "workspace_id": { "type": "string", "minLength": 1, - "maxLength": 56 - }, - "channel_policy_version": { - "type": "integer", - "minimum": 0, - "exclusiveMinimum": true - }, - "commercial_mode": { - "$ref": "#/components/schemas/CommercialMode" + "maxLength": 53 }, - "approval_required": { - "type": "boolean" + "install_id": { + "type": "string", + "minLength": 1, + "maxLength": 55 }, - "checkout_required": { - "type": "boolean" + "hostname": { + "type": "string", + "minLength": 1, + "maxLength": 253 }, - "approval_mode": { + "protocol": { "type": "string", "enum": [ - "requires_platform_approval", - "auto_approved_within_policy" + "http", + "websocket", + "grpc" ], - "x-platform-visibility": "TRUSTED_PARTNER" + "description": "Transport class for route forwarding." }, - "checkout_environment": { + "routing_mode": { "type": "string", "enum": [ - "none", - "stripe_live", - "stripe_sandbox" + "through_dispatcher", + "bypass_dispatcher" ], - "x-platform-visibility": "TRUSTED_PARTNER" + "description": "Whether traffic uses the dispatcher Worker or bypasses it." }, - "pricing_bounds": { - "$ref": "#/components/schemas/OfferPricingBounds" + "binding_kind": { + "type": "string", + "enum": [ + "pinned", + "floating" + ] }, - "pricing_summary": { - "$ref": "#/components/schemas/OfferPricingSummary" + "track": { + "type": "string", + "nullable": true, + "minLength": 1, + "maxLength": 100 }, - "support_scope": { - "$ref": "#/components/schemas/OfferSupportScope" + "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 + } + ] }, - "blocking_reasons": { - "type": "array", - "items": { - "type": "string" - }, - "default": [] - } - }, - "required": [ - "offer_channel_id", - "channel_policy_id", - "channel_policy_version", - "commercial_mode", - "approval_required", - "checkout_required", - "support_scope" - ] - }, - "OfferPricingBounds": { - "type": "object", - "properties": { - "currency": { + "status": { "type": "string", "enum": [ - "eur", - "usd" + "provisioning", + "active", + "evicted", + "releasing" ] }, - "default_unit_amount": { - "type": "integer", - "minimum": 0 - }, - "minimum_unit_amount": { + "last_seen_at": { "type": "integer", - "minimum": 0 + "nullable": true, + "minimum": 0, + "description": "Unix timestamp (seconds)" }, - "maximum_unit_amount": { - "type": "integer", - "minimum": 0 + "observed_url": { + "type": "string", + "nullable": true }, - "interval": { - "$ref": "#/components/schemas/PricingInterval" - } - }, - "required": [ - "currency", - "default_unit_amount", - "minimum_unit_amount", - "maximum_unit_amount", - "interval" - ], - "additionalProperties": false, - "x-platform-visibility": "TRUSTED_PARTNER" - }, - "OfferPricingSummary": { - "type": "object", - "properties": { - "currency": { + "error": { "type": "string", - "enum": [ - "eur", - "usd" - ] + "nullable": true }, - "unit_amount": { + "created_at": { "type": "integer", - "minimum": 0 + "minimum": 0, + "description": "Unix timestamp (seconds)" }, - "interval": { - "$ref": "#/components/schemas/PricingInterval" + "updated_at": { + "type": "integer", + "minimum": 0, + "description": "Unix timestamp (seconds)" }, - "source": { - "type": "string", - "enum": [ - "channel_policy", - "request" - ] + "etag": { + "type": "string" } }, "required": [ - "currency", - "unit_amount", - "interval", - "source" + "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" ] }, - "OfferStatus": { - "type": "string", - "enum": [ - "active", - "archived", - "expired", - "redeemed" - ], - "description": "Computed lifecycle status — never set directly; derived from row state." - }, - "PreviewOfferBody": { + "InstallDomainSettingsCustomDomain": { "type": "object", "properties": { - "package_version_id": { + "id": { "type": "string", "minLength": 1, - "maxLength": 55, - "description": "Package version ID to preview against. Preview requires a concrete package version because no offer row is created to store a resolved product pin." + "maxLength": 54 }, - "product_id": { + "workspace_id": { "type": "string", "minLength": 1, - "maxLength": 55, - "description": "Product ID for channel policy attribution." + "maxLength": 53 }, - "target_workspace_id": { + "hostname": { "type": "string", "minLength": 1, - "maxLength": 53, - "description": "Existing customer workspace used for preview context." - }, - "allowed_emails": { - "type": "array", - "items": { - "type": "string", - "maxLength": 254, - "format": "email" - }, - "maxItems": 50, - "description": "Verified customer email allowlist used for preview context." + "maxLength": 253 }, - "field_values": { - "type": "object", - "additionalProperties": { - "type": "object", - "properties": { - "value": { - "nullable": true, - "description": "Pre-fill value for this schema property" + "target": { + "oneOf": [ + { + "type": "object", + "properties": { + "kind": { + "type": "string", + "enum": [ + "install" + ] + }, + "install_id": { + "type": "string", + "minLength": 1, + "maxLength": 55 + } }, - "locked": { - "type": "boolean", - "description": "When true the customer cannot override; submit ignores client value" - } + "required": [ + "kind", + "install_id" + ], + "additionalProperties": false }, - "required": [ - "value", - "locked" - ] - }, - "description": "Package input pre-fills used for preview context." + { + "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 + } + ] }, - "region_id": { + "protocol": { "type": "string", - "minLength": 1, - "maxLength": 54, - "description": "Delivery region pin used for preview context." + "enum": [ + "http", + "websocket", + "grpc" + ], + "description": "Transport class for route forwarding." }, - "cluster_id": { + "routing_mode": { "type": "string", - "minLength": 1, - "maxLength": 54, - "description": "Delivery cluster pin used for preview context." + "enum": [ + "through_dispatcher", + "bypass_dispatcher" + ], + "description": "Whether traffic uses the dispatcher Worker or bypasses it." }, - "offer_channel_id": { + "target_kind": { "type": "string", - "minLength": 1, - "maxLength": 54, - "description": "Offer Channel whose active policy is previewed." + "enum": [ + "install", + "cluster", + "external" + ] }, - "commercial_mode": { - "allOf": [ - { - "$ref": "#/components/schemas/CommercialMode" + "cloudflare_custom_hostname_id": { + "type": "string", + "nullable": true + }, + "ssl": { + "type": "object", + "properties": { + "status": { + "type": "string", + "enum": [ + "pending_validation", + "active", + "failed" + ] }, - { - "description": "Requested customer path for channel policy resolution. This is not settlement authority; the active channel policy decides the final terms." + "validation_records": { + "type": "array", + "items": { + "type": "object", + "additionalProperties": { + "type": "string" + } + } } + }, + "required": [ + "status" ] }, - "pricing_request": { - "$ref": "#/components/schemas/OfferPricingRequest" - } - }, - "required": [ - "package_version_id", - "product_id", - "offer_channel_id", - "commercial_mode" - ], - "additionalProperties": false, - "description": "Preview channel policy resolution for a concrete package version and product before creating an offer.", - "x-platform-visibility": "TRUSTED_PARTNER" - }, - "OfferPricingRequest": { - "type": "object", - "properties": { - "currency": { + "status": { "type": "string", "enum": [ - "eur", - "usd" - ], - "example": "eur", - "description": "ISO currency code for the requested price." + "provisioning", + "active", + "failed", + "releasing" + ] }, - "unit_amount": { + "error": { + "type": "string", + "nullable": true + }, + "created_at": { "type": "integer", "minimum": 0, - "maximum": 100000000, - "description": "Requested price in the smallest currency unit, for example cents for EUR or USD." + "description": "Unix timestamp (seconds)" }, - "interval": { - "allOf": [ - { - "$ref": "#/components/schemas/PricingInterval" - }, - { - "description": "Billing interval for the requested price." - } - ] - } - }, - "required": [ - "currency", - "unit_amount", - "interval" - ], - "additionalProperties": false, - "description": "Requested customer-visible price for channel policy resolution. The active policy validates the request before the offer is created." - }, - "OfferCreated": { - "type": "object", - "properties": { - "id": { - "type": "string", - "minLength": 1, - "maxLength": 56, - "description": "Offer ID" + "updated_at": { + "type": "integer", + "minimum": 0, + "description": "Unix timestamp (seconds)" }, - "short_hash": { + "etag": { "type": "string" } }, "required": [ "id", - "short_hash" + "workspace_id", + "hostname", + "target", + "protocol", + "routing_mode", + "target_kind", + "cloudflare_custom_hostname_id", + "ssl", + "status", + "error", + "created_at", + "updated_at", + "etag" ] }, - "CreateOfferBody": { + "CreateInstallBody": { "anyOf": [ { "type": "object", @@ -3178,318 +17765,246 @@ "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, - "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" + "maxLength": 55 }, "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" + "maxLength": 54 }, "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." + "maxLength": 54 }, - "field_values": { + "initial_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." - }, - "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`." - }, - "offer_channel_id": { - "type": "string", - "minLength": 1, - "maxLength": 54, - "description": "Offer Channel whose active policy resolves approval, checkout, support, and pricing terms. Requires `product_id`." - }, - "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-private note for operators reviewing or supporting the offer. Not shown to the customer." - }, - "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", - "minimum": 0, - "exclusiveMinimum": true, - "maximum": 10000, - "description": "Maximum number of successful redemptions allowed for this offer. Omit for the default single-use behavior." - }, - "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)." + "nullable": true + } } }, "required": [ - "product_id" + "product_id", + "region_id" ], "additionalProperties": false }, { "type": "object", "properties": { - "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." - }, - "product_id": { + "package_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." + "maxLength": 54 }, - "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" + "package_version_pin": { + "$ref": "#/components/schemas/InstallPackageVersionPin" }, "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" + "maxLength": 54 }, "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." + "maxLength": 54 }, - "field_values": { + "initial_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." - }, - "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`." - }, - "offer_channel_id": { + "nullable": true + } + } + }, + "required": [ + "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": { + "kind": { "type": "string", - "minLength": 1, - "maxLength": 54, - "description": "Offer Channel whose active policy resolves approval, checkout, support, and pricing terms. Requires `product_id`." - }, - "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." - } + "enum": [ + "latest" + ] + } + }, + "required": [ + "kind" + ], + "additionalProperties": false + }, + { + "type": "object", + "properties": { + "kind": { + "type": "string", + "enum": [ + "pinned" ] }, - "pricing_request": { - "$ref": "#/components/schemas/OfferPricingRequest" - }, - "notes": { + "version": { "type": "string", - "maxLength": 500, - "description": "Seller-private note for operators reviewing or supporting the offer. Not shown to the customer." - }, - "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", - "minimum": 0, - "exclusiveMinimum": true, - "maximum": 10000, - "description": "Maximum number of successful redemptions allowed for this offer. Omit for the default single-use behavior." - }, - "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)." + "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": [ - "package_version_id" + "kind", + "version" ], "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." + ] }, - "OrderDraft": { + "InstallLifecycleMutation": { + "type": "object", + "properties": { + "install": { + "$ref": "#/components/schemas/InstallLifecycleState" + }, + "render": { + "anyOf": [ + { + "$ref": "#/components/schemas/InstallRender" + }, + { + "nullable": true + } + ] + } + }, + "required": [ + "install", + "render" + ] + }, + "InstallLifecycleState": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, - "maxLength": 55, - "description": "Order draft ID" + "maxLength": 55 }, - "offer_id": { - "type": "string", - "minLength": 1, - "maxLength": 56, - "description": "Offer this order draft is redeeming" + "current_version": { + "anyOf": [ + { + "$ref": "#/components/schemas/PackageVersionSummary" + }, + { + "nullable": true + } + ], + "description": "Last PackageVersion whose render completed successfully." }, - "status": { - "$ref": "#/components/schemas/OrderDraftStatus" + "desired_version": { + "anyOf": [ + { + "$ref": "#/components/schemas/PackageVersionSummary" + }, + { + "nullable": true + } + ], + "description": "Requested PackageVersion while an update or restore is pending or has failed. Null when desired and current match." }, - "termination_reason": { - "$ref": "#/components/schemas/OrderDraftTerminationReason" + "automatic_updates_enabled": { + "type": "boolean" }, - "user_id": { - "type": "string", - "minLength": 1, - "description": "Authenticated customer" + "updated_at": { + "type": "integer", + "minimum": 0, + "description": "Unix timestamp (seconds)" }, - "customer_email": { + "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, - "description": "Workspace selected/created during the workspace phase" + "maxLength": 53 }, - "cluster_id": { + "install_id": { "type": "string", "minLength": 1, - "maxLength": 54, - "description": "Cluster allocated during the compute phase" + "maxLength": 55 }, - "cluster_ready": { - "type": "boolean" + "operation_id": { + "type": "string", + "nullable": true, + "minLength": 1, + "maxLength": 53 }, - "server_joined": { - "type": "boolean" + "repository_change_request_id": { + "type": "string", + "nullable": true, + "minLength": 1, + "maxLength": 54 }, - "payment_completed": { - "type": "boolean" + "render_hash": { + "type": "string", + "nullable": true }, - "current_checkout_session": { - "$ref": "#/components/schemas/CurrentOrderDraftCheckoutSession" + "commit_sha": { + "type": "string", + "nullable": true }, - "install_operation_id": { + "package_version_id": { "type": "string", + "nullable": true, "minLength": 1, - "maxLength": 53, - "description": "Operation tracking the spawned install workflow" + "maxLength": 55 }, - "order": { - "$ref": "#/components/schemas/OrderSummary" + "restored_from_render_id": { + "type": "string", + "nullable": true, + "minLength": 1, + "maxLength": 54 }, - "delivery": { - "$ref": "#/components/schemas/OrderDeliverySummary" + "state": { + "type": "string", + "enum": [ + "running", + "deployed", + "skipped", + "failed" + ] }, - "field_values": { - "type": "object", - "additionalProperties": { - "nullable": true - }, - "description": "Customer-supplied configure values, including any pre-fills from the offer. Only returned to the order draft’s own customer; never to other authed callers." + "message": { + "type": "string", + "nullable": true }, "created_at": { "type": "integer", @@ -3500,354 +18015,209 @@ "type": "integer", "minimum": 0, "description": "Unix timestamp (seconds)" - }, - "etag": { - "type": "string" - }, - "ttl_expires_at": { - "type": "integer", - "minimum": 0, - "description": "Unix timestamp (seconds)" } }, "required": [ "id", - "offer_id", - "status", - "cluster_ready", - "server_joined", - "payment_completed", + "workspace_id", + "install_id", + "render_hash", + "state", "created_at", - "updated_at", - "etag", - "ttl_expires_at" + "updated_at" ] }, - "OrderDraftStatus": { - "type": "string", - "enum": [ - "auth", - "workspace", - "compute", - "compute_bootstrap", - "configure", - "payment", - "install", - "done", - "cleaning_up", - "terminated" - ], - "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." - }, - "OrderDraftTerminationReason": { - "type": "string", - "enum": [ - "timeout", - "revoked", - "offer_expired", - "install_failed", - "cluster_allocation_failed", - "quota_exceeded" + "UpdateInstallVersionBody": { + "type": "object", + "properties": { + "package_version_id": { + "type": "string", + "minLength": 1, + "maxLength": 55 + } + }, + "required": [ + "package_version_id" ], - "description": "Set when status=terminated; explains why the order draft ended." + "additionalProperties": false }, - "CurrentOrderDraftCheckoutSession": { + "RestoreInstallBody": { "type": "object", "properties": { - "stripe_environment": { - "$ref": "#/components/schemas/StripeEnvironment" - }, - "id": { - "type": "string", - "description": "Stripe Checkout Session ID", - "example": "cs_test_..." - }, - "draft_revision": { - "type": "integer", - "minimum": 0, - "description": "Order draft revision this Checkout Session belongs to" - }, - "url": { + "render_id": { "type": "string", - "format": "uri", - "description": "Stripe-hosted Checkout URL" - }, - "expires_at": { - "type": "integer", - "minimum": 0, - "description": "Unix timestamp (seconds)" + "minLength": 1, + "maxLength": 54 } }, "required": [ - "stripe_environment", - "id", - "draft_revision" - ] + "render_id" + ], + "additionalProperties": false }, - "StripeEnvironment": { - "type": "string", - "enum": [ - "live", - "sandbox" + "SetInstallAutomaticUpdatesBody": { + "type": "object", + "properties": { + "automatic_updates_enabled": { + "type": "boolean" + } + }, + "required": [ + "automatic_updates_enabled" ], - "description": "Stripe payment environment for this Checkout Session." + "additionalProperties": false }, - "OrderSummary": { + "CreateInstallRenderBody": { "type": "object", "properties": { - "id": { + "message": { "type": "string", - "minLength": 1, - "maxLength": 54, - "description": "Order ID" - }, - "status": { - "$ref": "#/components/schemas/OrderStatus" - }, - "stripe_environment": { - "allOf": [ - { - "$ref": "#/components/schemas/StripeEnvironment" - }, - { - "description": "Stripe payment environment for paid Stripe checkout orders." - } - ] + "maxLength": 255 }, - "stripe_checkout_id": { - "type": "string" + "skip_unchanged": { + "type": "boolean", + "nullable": true, + "default": true }, - "draft_revision": { - "type": "integer", - "minimum": 0 + "extra_annotations": { + "type": "object", + "additionalProperties": { + "type": "string" + } + } + }, + "additionalProperties": false + }, + "InstallRenderList": { + "type": "object", + "properties": { + "data": { + "type": "array", + "items": { + "$ref": "#/components/schemas/InstallRender" + } }, - "cleanup_policy": { - "$ref": "#/components/schemas/OrderCleanupPolicy" + "has_more": { + "type": "boolean", + "description": "True if more items exist after this page." }, - "committed_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": [ - "id", - "status", - "stripe_checkout_id", - "draft_revision", - "cleanup_policy", - "committed_at" - ] - }, - "OrderStatus": { - "type": "string", - "enum": [ - "delivery_pending", - "delivery_running", - "delivered", - "delivery_failed" + "data", + "has_more", + "next_cursor" ] }, - "OrderCleanupPolicy": { - "oneOf": [ - { - "type": "object", - "properties": { - "kind": { - "type": "string", - "enum": [ - "none" - ] - } - }, - "required": [ - "kind" - ], - "additionalProperties": false - }, - { - "type": "object", - "properties": { - "kind": { - "type": "string", - "enum": [ - "temporal_actor_ttl" - ] - }, - "cleanup_at": { - "type": "integer", - "minimum": 0, - "description": "Unix timestamp (seconds)" - }, - "removable_by": { - "type": "string", - "enum": [ - "platform_policy", - "platform_admin" - ] - }, - "conversion_required": { - "type": "string", - "enum": [ - "paid_order", - "platform_approval" - ] - } - }, - "required": [ - "kind", - "cleanup_at", - "removable_by", - "conversion_required" - ], - "additionalProperties": false - } - ], - "description": "Cleanup policy attached to committed order resources. Demo/test policies are visible so customers and sellers can see when resources will be removed." - }, - "OrderDeliverySummary": { + "InstallStatus": { "type": "object", "properties": { - "id": { + "install_id": { "type": "string", "minLength": 1, - "maxLength": 55, - "description": "Order delivery ID" + "maxLength": 55 }, - "kind": { + "health": { "type": "string", - "enum": [ - "install" - ] + "nullable": true }, - "authorization_kind": { + "sync": { "type": "string", - "enum": [ - "paid_order", - "non_billable_test_order" - ] - }, - "status": { - "$ref": "#/components/schemas/OrderDeliveryStatus" - }, - "cleanup_policy": { - "$ref": "#/components/schemas/OrderCleanupPolicy" + "nullable": true }, - "install_id": { + "revision": { "type": "string", - "minLength": 1, - "maxLength": 55 - }, - "urls": { - "type": "array", - "items": { - "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" - ] + "nullable": true + }, + "resources": { + "type": "array", + "nullable": true, + "items": { + "$ref": "#/components/schemas/ResourceStatus" } }, - "install_operation_id": { + "operation_phase": { "type": "string", - "minLength": 1, - "maxLength": 53, - "description": "Operation tracking the spawned install workflow" + "nullable": true }, - "started_at": { + "updated_at": { "type": "integer", + "nullable": true, "minimum": 0, "description": "Unix timestamp (seconds)" }, - "completed_at": { - "type": "integer", - "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": [ - "id", - "kind", - "authorization_kind", - "status", - "cleanup_policy", - "urls" + "install_id", + "health", + "sync", + "revision", + "resources", + "operation_phase", + "updated_at", + "state", + "reconciling" ] }, - "OrderDeliveryStatus": { - "type": "string", - "enum": [ - "pending", - "running", - "succeeded", - "failed" + "PodList": { + "type": "object", + "properties": { + "data": { + "type": "array", + "items": { + "$ref": "#/components/schemas/Pod" + } + } + }, + "required": [ + "data" ] }, - "OrderDraftList": { + "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/OrderDraft" + "$ref": "#/components/schemas/Package" } }, "has_more": { @@ -3866,19 +18236,73 @@ "next_cursor" ] }, - "ClaimOrderDraftBody": { + "Package": { "type": "object", "properties": { - "claim_token": { + "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" + }, + "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 + } + }, + "description": "Source provenance used to create this Package (helm URLs, OCI refs, git source details). Only visible in `view=full`." + }, + "created_at": { + "type": "integer", + "minimum": 0, + "description": "Unix timestamp (seconds)" + }, + "etag": { "type": "string" } }, "required": [ - "claim_token" - ], - "additionalProperties": false + "id", + "html_url", + "workspace_id", + "name", + "latest_version_id", + "description", + "source", + "created_at" + ] }, - "SelectOrderDraftWorkspaceBody": { + "PackageSource": { "oneOf": [ { "type": "object", @@ -3886,20 +18310,20 @@ "kind": { "type": "string", "enum": [ - "existing" + "hosted" ] }, - "workspace_id": { + "repository_id": { "type": "string", "minLength": 1, - "maxLength": 53 + "maxLength": 55, + "description": "platform-hosted repository that contains the package source" } }, "required": [ "kind", - "workspace_id" - ], - "additionalProperties": false + "repository_id" + ] }, { "type": "object", @@ -3907,189 +18331,372 @@ "kind": { "type": "string", "enum": [ - "new" + "oci" ] }, - "name": { + "oci_ref": { "type": "string", - "minLength": 1, - "maxLength": 100 + "description": "OCI reference to the package source (no digest)" } }, "required": [ - "kind" - ], - "additionalProperties": false + "kind", + "oci_ref" + ] } ] }, - "SubmitConfigureOrderDraftBody": { + "PackageWithVersionsList": { "type": "object", "properties": { - "field_values": { - "type": "object", - "additionalProperties": { - "nullable": true - }, - "description": "Customer-supplied configure form values, keyed by field name" + "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": [ - "field_values" - ], - "additionalProperties": false + "data", + "has_more", + "next_cursor" + ] }, - "OrderDraftWorkerBootstrap": { + "PackageWithVersions": { "type": "object", "properties": { - "token": { + "id": { "type": "string", - "description": "Short-lived worker join token (one-time view)." + "minLength": 1, + "maxLength": 54 }, - "expires_at": { - "type": "integer", - "minimum": 0, - "description": "Token expiry time (unix seconds)." + "name": { + "type": "string" }, - "command": { - "type": "string", - "description": "Bash bootstrap command with the token already substituted, ready to run on a worker node." + "versions": { + "type": "array", + "items": { + "$ref": "#/components/schemas/PackageVersionSummary" + } + } + }, + "required": [ + "id", + "name", + "versions" + ] + }, + "PackageInventoryList": { + "type": "object", + "properties": { + "data": { + "type": "array", + "items": { + "$ref": "#/components/schemas/PackageInventoryRow" + } }, - "cloud_init": { - "type": "string", - "description": "Cloud-init YAML with the token already substituted, ready to use as worker-node user-data." + "has_more": { + "type": "boolean", + "description": "True if more items exist after this page." }, - "artifacts": { - "$ref": "#/components/schemas/WorkerBootstrapArtifacts" + "next_cursor": { + "type": "string", + "nullable": true, + "description": "Opaque cursor for the next page, or null if no more pages." } }, "required": [ - "token", - "expires_at", - "command", - "cloud_init" + "data", + "has_more", + "next_cursor" ] }, - "WorkerBootstrapArtifacts": { + "PackageInventoryRow": { "type": "object", "properties": { - "linux": { - "type": "object", - "properties": { - "amd64": { - "$ref": "#/components/schemas/WorkerBootstrapArtifact" - }, - "arm64": { - "$ref": "#/components/schemas/WorkerBootstrapArtifact" + "id": { + "type": "string", + "minLength": 1, + "maxLength": 54 + }, + "workspace_id": { + "type": "string", + "minLength": 1, + "maxLength": 53 + }, + "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 } } }, - "windows": { + "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", + "source", + "versions", + "has_more_versions", + "created_at", + "etag" + ] + }, + "PackageDetailResponse": { + "type": "object", + "nullable": true, + "properties": { + "package": { "type": "object", "properties": { - "amd64": { - "$ref": "#/components/schemas/WorkerBootstrapArtifact" + "id": { + "type": "string", + "minLength": 1, + "maxLength": 54 }, - "arm64": { - "$ref": "#/components/schemas/WorkerBootstrapArtifact" + "workspace_id": { + "type": "string", + "minLength": 1, + "maxLength": 53 + }, + "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": { + "type": "string" } + }, + "required": [ + "id", + "workspace_id", + "name", + "description", + "source", + "created_at", + "etag" + ] + }, + "versions": { + "type": "array", + "items": { + "$ref": "#/components/schemas/PackageDetailVersion" } } }, - "description": "Platform-specific bootstrap artifacts with tokens already substituted. Populated only on create responses." + "required": [ + "package", + "versions" + ] }, - "WorkerBootstrapArtifact": { - "oneOf": [ - { + "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": { "type": "object", "properties": { - "supported": { - "type": "boolean", - "enum": [ - true - ], - "description": "Whether this platform/architecture artifact is currently supported." - }, - "command": { - "type": "string", - "description": "Bootstrap command with the token already substituted. Reveal-on-create only." + "clusterTypes": { + "type": "array", + "items": { + "type": "string" + } }, - "shell": { - "type": "string", - "enum": [ - "bash", - "powershell" - ], - "description": "Shell expected to execute the bootstrap command or downloaded script." + "kubernetes": { + "type": "object", + "properties": { + "minVersion": { + "type": "string" + }, + "maxVersion": { + "type": "string" + } + } }, - "download_url": { - "type": "string", - "format": "uri", - "description": "Token-free script URL used by the bootstrap command." + "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" + ] }, - "cloud_init": { - "type": "string", - "description": "Cloud-init YAML with the token already substituted. Reveal-on-create only." + "kaas": { + "type": "object", + "properties": { + "networkProfile": { + "type": "string", + "enum": [ + "linux_cilium", + "mixed_os_calico" + ] + } + }, + "required": [ + "networkProfile" + ] } }, "required": [ - "supported" + "clusterTypes", + "kubernetes", + "placement" ] }, - { - "type": "object", - "properties": { - "supported": { - "type": "boolean", - "enum": [ - false - ], - "description": "Whether this platform/architecture artifact is currently supported. Unsupported entries do not include token-bearing commands." - } - }, - "required": [ - "supported" - ], - "additionalProperties": false - } - ] - }, - "OrderDraftCheckoutSession": { - "type": "object", - "properties": { - "id": { - "type": "string", - "description": "Stripe Checkout Session ID", - "example": "cs_test_..." - }, - "url": { - "type": "string", - "format": "uri", - "description": "Stripe-hosted Checkout URL" + "published_at": { + "type": "integer", + "minimum": 0, + "description": "Unix timestamp (seconds)" }, - "expires_at": { + "created_at": { "type": "integer", "minimum": 0, "description": "Unix timestamp (seconds)" }, - "stripe_environment": { - "$ref": "#/components/schemas/StripeEnvironment" + "etag": { + "type": "string" } }, "required": [ "id", - "url", - "expires_at", - "stripe_environment" + "package_id", + "semver", + "ref", + "input_schema", + "published_at", + "created_at", + "etag" ] }, - "CheckoutSessionList": { + "PackageVersionInputs": { + "type": "object", + "additionalProperties": { + "nullable": true + } + }, + "PackageVersionList": { "type": "object", "properties": { "data": { "type": "array", "items": { - "$ref": "#/components/schemas/CheckoutSession" + "$ref": "#/components/schemas/PackageVersion" } }, "has_more": { @@ -4108,271 +18715,236 @@ "next_cursor" ] }, - "CheckoutSession": { + "PackageVersion": { "type": "object", "properties": { "id": { "type": "string", - "description": "Checkout session ID", - "example": "chk_j572abc..." - }, - "stripe_environment": { - "$ref": "#/components/schemas/StripeEnvironment" + "minLength": 1, + "maxLength": 55 }, - "order_draft_id": { + "package_id": { "type": "string", "minLength": 1, - "maxLength": 55, - "description": "Parent order draft ID", - "example": "odft_j572abc..." + "maxLength": 54 }, - "order_draft_etag_at_mint": { + "semver": { "type": "string", - "description": "Parent order draft etag when this checkout session was minted." + "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-]+)*))?$" }, - "state": { - "$ref": "#/components/schemas/CheckoutSessionStatus" + "ref": { + "type": "string" }, - "url": { - "type": "string", - "format": "uri", - "description": "Stripe-hosted Checkout URL" + "input_schema": { + "type": "object", + "additionalProperties": { + "nullable": true + } }, - "expires_at": { + "published_at": { "type": "integer", "minimum": 0, "description": "Unix timestamp (seconds)" }, - "stripe_checkout_session_id": { - "type": "string", - "description": "Stripe Checkout session identifier", - "example": "cs_test_..." - }, "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", - "stripe_environment", - "order_draft_id", - "order_draft_etag_at_mint", - "state", - "stripe_checkout_session_id", - "created_at", - "updated_at" - ] - }, - "CheckoutSessionStatus": { - "type": "string", - "enum": [ - "open", - "expired", - "payment_failed", - "superseded", - "paid" + "package_id", + "semver", + "ref", + "input_schema", + "published_at", + "created_at" ] }, - "DemoCleanupRemoval": { + "PackageArtifacthubValuesSchema": { "type": "object", "properties": { - "order_id": { - "type": "string", - "minLength": 1, - "maxLength": 54, - "description": "Order whose demo cleanup was removed." + "values": { + "type": "object", + "additionalProperties": { + "nullable": true + }, + "description": "Parsed chart values object" }, - "delivery_id": { - "type": "string", - "minLength": 1, - "maxLength": 55, - "description": "Order delivery whose demo cleanup was removed." + "schema": { + "type": "object", + "nullable": true, + "additionalProperties": { + "nullable": true + }, + "description": "JSON Schema for the values (null when the values cannot be parsed)" }, - "cleanup_workflow_id": { + "values_yaml": { "type": "string", - "minLength": 1, - "description": "Previously scheduled Temporal cleanup workflow ID. The workflow will skip after re-reading the removed cleanup policy." + "description": "Raw chart values YAML" } }, "required": [ - "order_id", - "delivery_id", - "cleanup_workflow_id" - ], - "additionalProperties": false, - "x-platform-visibility": "ADMIN" + "values", + "schema", + "values_yaml" + ] }, - "RemoveDemoCleanupAfterPlatformApprovalBody": { + "ImportPackageBody": { "type": "object", "properties": { - "reason": { + "name": { "type": "string", "minLength": 1, - "maxLength": 1000, - "description": "Platform approval reason for removing non-billable demo cleanup." - } - }, - "required": [ - "reason" - ], - "additionalProperties": false, - "x-platform-visibility": "ADMIN" - }, - "EntitlementList": { - "type": "object", - "properties": { - "data": { - "type": "array", - "items": { - "$ref": "#/components/schemas/Entitlement" - } - }, - "has_more": { - "type": "boolean", - "description": "True if more items exist after this page." + "maxLength": 120 }, - "next_cursor": { + "description": { "type": "string", "nullable": true, - "description": "Opaque cursor for the next page, or null if no more pages." + "maxLength": 1000 }, - "etag": { - "type": "string" + "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": [ - "data", - "has_more", - "next_cursor", - "etag" - ] + "name", + "oci_ref", + "version" + ], + "additionalProperties": false }, - "Entitlement": { + "CreatePackageVersionBody": { "type": "object", "properties": { - "workspace_id": { + "semver": { "type": "string", "minLength": 1, - "maxLength": 53 + "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" }, - "feature": { - "type": "object", - "properties": { - "feature_set": { - "type": "string" - }, - "key": { - "type": "string" + "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" }, - "name": { - "type": "string" + { + "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." } - }, - "required": [ - "feature_set", - "key", - "name" ] }, - "allocation": { - "oneOf": [ - { + "compatibility": { + "type": "object", + "properties": { + "clusterTypes": { + "type": "array", + "items": { + "type": "string" + } + }, + "kubernetes": { "type": "object", "properties": { - "type": { - "type": "string", - "enum": [ - "bool" - ] + "minVersion": { + "type": "string" }, - "value": { - "type": "boolean" + "maxVersion": { + "type": "string" } - }, - "required": [ - "type", - "value" - ] + } }, - { + "placement": { "type": "object", "properties": { - "type": { - "type": "string", - "enum": [ - "max_count" + "providers": { + "anyOf": [ + { + "type": "string", + "enum": [ + "any" + ] + }, + { + "type": "array", + "items": { + "type": "string" + } + } ] }, - "value": { - "type": "integer", - "minimum": 0 + "regions": { + "anyOf": [ + { + "type": "string", + "enum": [ + "any" + ] + }, + { + "type": "array", + "items": { + "type": "string" + } + } + ] } }, "required": [ - "type", - "value" + "providers", + "regions" ] }, - { + "kaas": { "type": "object", "properties": { - "type": { + "networkProfile": { "type": "string", "enum": [ - "unlimited" + "linux_cilium", + "mixed_os_calico" ] - }, - "value": { - "nullable": true } }, "required": [ - "type", - "value" + "networkProfile" ] } + }, + "required": [ + "clusterTypes", + "kubernetes", + "placement" ] } }, "required": [ - "workspace_id", - "feature", - "allocation" - ] - }, - "OperationList": { - "type": "object", - "properties": { - "data": { - "type": "array", - "items": { - "$ref": "#/components/schemas/Operation" - } - }, - "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" - ] + "semver", + "ref", + "input_schema" + ], + "additionalProperties": false }, - "Operation": { + "PackageOperationEnvelope": { "type": "object", "properties": { "id": { @@ -4434,14 +19006,14 @@ "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" + "description": "Deep link to the dashboard view of this operation.", + "example": "https://akua.dev/packages/pkg_j572abc123def456?tab=operations" }, "metadata": { - "$ref": "#/components/schemas/OperationMetadata" + "$ref": "#/components/schemas/PackageOperationMetadata" }, "response": { - "$ref": "#/components/schemas/OperationResponse" + "$ref": "#/components/schemas/PackageOperationResponse" }, "error": { "type": "object", @@ -4470,7 +19042,133 @@ "required": [ "message" ], - "description": "Latest error from any failed step. Populated even mid-flight; cleared when the step succeeds on retry." + "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" + } + } + }, + "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": { + "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" + ] + }, + "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": { + "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", @@ -4483,1859 +19181,1978 @@ "minimum": 0, "description": "Unix timestamp (seconds)" }, - "steps": { - "type": "array", - "items": { - "$ref": "#/components/schemas/OperationStep" - } + "error_message": { + "type": "string", + "nullable": true + }, + "retryable": { + "type": "boolean" + }, + "skippable": { + "type": "boolean" } }, "required": [ - "id", - "workspace_id", - "organization_id", - "owner_type", - "owner_id", - "parent_operation_id", - "state", - "done", - "html_url", - "metadata", - "response", - "error", - "last_error", + "name", + "status", + "execution_type", "started_at", - "completed_at" + "completed_at", + "error_message", + "retryable", + "skippable" ] }, - "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": [ - "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" - ] + "CreatePackageBody": { + "type": "object", + "properties": { + "name": { + "type": "string", + "minLength": 1, + "maxLength": 120 }, - { - "type": "object", - "properties": { - "type": { - "type": "string", - "enum": [ - "cluster.resume" - ] - }, - "cluster_id": { - "type": "string", - "minLength": 1, - "maxLength": 54 - } + "sources": { + "type": "array", + "items": { + "$ref": "#/components/schemas/CreatePackageHelmSource" }, - "required": [ - "type", - "cluster_id" + "minItems": 1, + "maxItems": 1 + } + }, + "required": [ + "name", + "sources" + ], + "additionalProperties": false + }, + "CreatePackageHelmSource": { + "type": "object", + "properties": { + "kind": { + "type": "string", + "enum": [ + "helm" ] }, - { - "type": "object", - "properties": { - "type": { - "type": "string", - "enum": [ - "cluster.capabilities.refresh" - ] - }, - "cluster_id": { - "type": "string", - "minLength": 1, - "maxLength": 54 - } - }, - "required": [ - "type", - "cluster_id" - ] + "repo_url": { + "type": "string", + "minLength": 1, + "maxLength": 2048, + "pattern": "^oci:\\/\\/" }, - { - "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" - ] + "chart": { + "type": "string", + "maxLength": 255 }, - { - "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" - ] + "target_revision": { + "type": "string", + "minLength": 1, + "maxLength": 256 }, - { - "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" - ] + "path": { + "type": "string", + "maxLength": 2048 }, - { + "values": { "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" - ] + "additionalProperties": { + "nullable": true + } + } + }, + "required": [ + "kind", + "repo_url", + "target_revision" + ], + "additionalProperties": false + }, + "WorkspaceList": { + "type": "object", + "properties": { + "data": { + "type": "array", + "items": { + "$ref": "#/components/schemas/Workspace" + } }, - { - "type": "object", - "properties": { - "type": { - "type": "string", - "enum": [ - "install.delete" - ] - }, - "install_id": { - "type": "string", - "minLength": 1, - "maxLength": 55 - } - }, - "required": [ - "type", - "install_id" - ] + "has_more": { + "type": "boolean", + "description": "True if more items exist after this page." }, - { - "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" - ] + "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": { + "type": "object", + "properties": { + "id": { + "type": "string", + "minLength": 1, + "maxLength": 53, + "description": "Workspace ID", + "example": "ws_j572abc123def456" }, - { - "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" - ] + "name": { + "type": "string", + "description": "Display name", + "example": "Acme Research" }, - { + "slug": { + "type": "string", + "description": "URL-safe workspace slug" + }, + "icon": { + "type": "string", + "maxLength": 256, + "format": "uri", + "x-platform-visibility": "INTERNAL" + }, + "plan": { "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": { + "tier": { "type": "string" }, - "idempotency_key": { - "type": "string" - } - }, - "required": [ - "type", - "install_id", - "preview_hostname_id", - "if_match", - "idempotency_key" - ] - }, - { - "type": "object", - "properties": { - "type": { + "billed_by": { "type": "string", "enum": [ - "workspace.delete" + "platform", + "seller" ] - }, - "workspace_id": { - "type": "string", - "minLength": 1, - "maxLength": 53 } }, "required": [ - "type", - "workspace_id" + "tier", + "billed_by" ] }, - { - "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" + "workspace_class": { + "type": "string", + "enum": [ + "standard", + "platform", + "sandbox" ] }, - { - "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" + "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", + "slug", + "plan", + "workspace_class", + "created_at", + "updated_at", + "etag" + ] + }, + "WorkspaceMemberList": { + "type": "object", + "properties": { + "data": { + "type": "array", + "items": { + "$ref": "#/components/schemas/WorkspaceMember" + } + }, + "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" + ] + }, + "WorkspaceMember": { + "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" ] }, - { - "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" + "joined_at": { + "type": "string", + "format": "date-time", + "description": "ISO 8601 join timestamp" + } + }, + "required": [ + "id", + "user_id", + "role", + "joined_at" + ] + }, + "WorkspaceSubscription": { + "type": "object", + "properties": { + "id": { + "type": "string" + }, + "workspace_id": { + "type": "string", + "minLength": 1, + "maxLength": 53 + }, + "tier": { + "type": "string" + }, + "status": { + "type": "string" + }, + "cancellation_scheduled": { + "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)" + } + }, + "required": [ + "id", + "workspace_id", + "tier", + "status", + "cancellation_scheduled", + "current_period_end", + "billed_by", + "created_at" + ] + }, + "WorkspaceAccessState": { + "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": { + "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)" + }, + "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", - "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" - ] + "nullable": true, + "properties": { + "organization": { + "type": "object", + "properties": { + "id": { + "type": "string", + "minLength": 1, + "maxLength": 54 }, - { - "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" - ] + "name": { + "type": "string" } + }, + "required": [ + "id", + "name" ] }, - "protocol": { - "type": "string", - "enum": [ - "http", - "websocket", - "grpc" - ] - }, - "routing_mode": { - "type": "string", - "enum": [ - "through_dispatcher", - "bypass_dispatcher" - ] - }, - "if_match": { - "type": "string" - }, - "idempotency_key": { - "type": "string" + "granted_at": { + "type": "integer", + "minimum": 0, + "description": "Unix timestamp (seconds)" } }, "required": [ - "type", - "workspace_id", - "custom_domain_id", - "if_match", - "idempotency_key" + "organization", + "granted_at" ] }, + "etag": { + "type": "string" + } + }, + "required": [ + "workspace_id", + "management", + "etag" + ] + }, + "OperationEnvelope": { + "type": "object", + "properties": { + "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 + }, + "workspace_id": { + "type": "string", + "minLength": 1, + "maxLength": 53 + }, + "requested_tier": { + "type": "string" + }, + "status": { + "type": "string" + }, + "effective_at": { + "type": "string", + "nullable": true + }, + "created_at": { + "type": "integer", + "minimum": 0, + "description": "Unix timestamp (seconds)" + } + }, + "required": [ + "id", + "workspace_id", + "requested_tier", + "status", + "effective_at", + "created_at" + ] + }, + "CreatedApiToken": { + "type": "object", + "properties": { + "id": { + "type": "string", + "minLength": 1, + "maxLength": 54 + }, + "workspace_id": { + "type": "string", + "minLength": 1, + "maxLength": 53 + }, + "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": 100, + "description": "Human-readable name for the token", + "example": "My CLI token" + }, + "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 + } + }, + "required": [ + "name" + ], + "additionalProperties": false + }, + "ApiTokenList": { + "type": "object", + "properties": { + "data": { + "type": "array", + "items": { + "$ref": "#/components/schemas/ApiToken" + } + }, + "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 + }, + "workspace_id": { + "type": "string", + "minLength": 1, + "maxLength": 53 + }, + "name": { + "type": "string", + "example": "My CLI token" + }, + "prefix": { + "type": "string", + "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)" + }, + "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": { - "type": { + "id": { "type": "string", - "enum": [ - "custom_domain.delete" - ] + "minLength": 1, + "maxLength": 55 + }, + "name": { + "type": "string" }, "workspace_id": { "type": "string", "minLength": 1, "maxLength": 53 }, - "custom_domain_id": { - "type": "string", - "minLength": 1, - "maxLength": 54 + "created_at": { + "type": "integer", + "minimum": 0, + "description": "Unix timestamp (seconds)" }, - "if_match": { - "type": "string" + "updated_at": { + "type": "integer", + "minimum": 0, + "description": "Unix timestamp (seconds)" }, - "idempotency_key": { + "etag": { "type": "string" - } - }, - "required": [ - "type", - "workspace_id", - "custom_domain_id", - "if_match", - "idempotency_key" - ] - }, - { - "type": "object", - "properties": { - "type": { + }, + "reconciling": { + "type": "boolean" + }, + "purpose": { "type": "string", "enum": [ - "cloudflare.private_origin_route.prepare" + "deploy" ] }, - "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": { + "last_deploy_sha": { "type": "string", - "minLength": 1, - "maxLength": 53 + "nullable": true }, - "route_intent_id": { + "last_render_hash": { "type": "string", - "minLength": 1, - "maxLength": 54 + "nullable": true } }, "required": [ - "type", + "id", + "name", "workspace_id", - "route_intent_id" + "created_at", + "updated_at", + "etag", + "reconciling", + "purpose", + "cluster_id" ] }, { "type": "object", "properties": { - "type": { - "type": "string", - "enum": [ - "package.create" - ] - }, - "idempotency_key": { - "type": "string" - }, - "workspace_id": { + "id": { "type": "string", "minLength": 1, - "maxLength": 53 + "maxLength": 55 }, "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" - ] + "created_at": { + "type": "integer", + "minimum": 0, + "description": "Unix timestamp (seconds)" }, - "repository_change_request_id": { - "type": "string", - "minLength": 1, - "maxLength": 54 + "updated_at": { + "type": "integer", + "minimum": 0, + "description": "Unix timestamp (seconds)" }, - "user_id": { + "etag": { "type": "string" }, - "reason": { - "type": "string" - } - }, - "required": [ - "type", - "repository_change_request_id", - "user_id", - "reason" - ] - }, - { - "type": "object", - "properties": { - "type": { + "reconciling": { + "type": "boolean" + }, + "purpose": { "type": "string", "enum": [ - "repository_change_request.withdraw" + "package" ] }, - "repository_change_request_id": { + "package_id": { "type": "string", "minLength": 1, "maxLength": 54 - }, - "user_id": { - "type": "string" } }, "required": [ - "type", - "repository_change_request_id", - "user_id" + "id", + "name", + "workspace_id", + "created_at", + "updated_at", + "etag", + "reconciling", + "purpose", + "package_id" ] }, { "type": "object", "properties": { - "type": { + "id": { "type": "string", - "enum": [ - "repository_change_request.expire" - ] + "minLength": 1, + "maxLength": 55 }, - "repository_change_request_id": { + "name": { + "type": "string" + }, + "workspace_id": { "type": "string", "minLength": 1, - "maxLength": 54 - } - }, - "required": [ - "type", - "repository_change_request_id" - ] - }, - { - "type": "object", - "properties": { - "type": { + "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.delete" + "repository_change_request" ] }, - "repository_id": { + "repository_change_request_id": { "type": "string", "minLength": 1, - "maxLength": 55 + "maxLength": 54 } }, "required": [ - "type", - "repository_id" + "id", + "name", + "workspace_id", + "created_at", + "updated_at", + "etag", + "reconciling", + "purpose", + "repository_change_request_id" ] } ] }, - "OperationResponse": { - "anyOf": [ - { + "GithubInstallationUrl": { + "type": "object", + "properties": { + "url": { + "type": "string", + "format": "uri" + } + }, + "required": [ + "url" + ] + }, + "GithubCreateInstallationUrlBody": { + "type": "object", + "properties": { + "redirect_url": { + "type": "string", + "format": "uri" + } + }, + "additionalProperties": false + }, + "GithubRepoList": { + "type": "object", + "properties": { + "data": { + "type": "array", + "items": { + "$ref": "#/components/schemas/GithubRepo" + } + } + }, + "required": [ + "data" + ] + }, + "GithubRepo": { + "type": "object", + "properties": { + "id": { + "type": "number" + }, + "name": { + "type": "string" + }, + "full_name": { + "type": "string" + }, + "archived": { + "type": "boolean" + }, + "disabled": { + "type": "boolean" + }, + "default_branch": { + "type": "string" + }, + "html_url": { + "type": "string" + }, + "owner": { "type": "object", "properties": { + "id": { + "type": "number" + }, + "login": { + "type": "string" + }, "type": { - "type": "string", - "enum": [ - "machine.create" - ] + "type": "string" }, - "machine_id": { - "type": "string", - "minLength": 1, - "maxLength": 54 + "avatar_url": { + "type": "string" }, - "provider_id": { + "html_url": { "type": "string" } }, "required": [ + "id", + "login", "type", - "machine_id", - "provider_id" + "avatar_url", + "html_url" ] + } + }, + "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" + ] + }, + "GithubAppInstallation": { + "type": "object", + "properties": { + "installation_id": { + "type": "integer", + "minimum": 0, + "exclusiveMinimum": true }, - { + "workspace_id": { + "type": "string", + "minLength": 1, + "maxLength": 53 + }, + "account": { "type": "object", "properties": { "type": { "type": "string", "enum": [ - "cluster.delete" + "User", + "Organization" ] }, - "cluster_id": { - "type": "string", - "minLength": 1, - "maxLength": 54 + "login": { + "type": "string" + }, + "id": { + "type": "number" } }, "required": [ "type", - "cluster_id" + "login", + "id" ] + } + }, + "required": [ + "installation_id", + "workspace_id", + "account" + ] + }, + "GithubWorkflowPrGet": { + "type": "object", + "properties": { + "data": { + "$ref": "#/components/schemas/GithubWorkflowPr" + } + }, + "required": [ + "data" + ] + }, + "GithubWorkflowPr": { + "type": "object", + "nullable": true, + "properties": { + "pr_id": { + "type": "integer", + "minimum": 0, + "exclusiveMinimum": true }, - { + "pr_url": { + "type": "string", + "format": "uri" + }, + "status": { + "type": "string", + "enum": [ + "open", + "merged", + "closed", + "draft" + ] + } + }, + "required": [ + "pr_id", + "pr_url", + "status" + ] + }, + "GithubWorkflowRunList": { + "type": "object", + "properties": { + "data": { + "type": "array", + "items": { + "$ref": "#/components/schemas/GithubWorkflowRun" + } + }, + "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" + ] + }, + "GithubWorkflowRun": { + "type": "object", + "properties": { + "id": { + "type": "string", + "minLength": 1, + "maxLength": 54 + }, + "custom": { "type": "object", "properties": { - "type": { - "type": "string", - "enum": [ - "cluster.create" - ] + "image": { + "type": "string" }, - "cluster_id": { - "type": "string", - "minLength": 1, - "maxLength": 54 + "sent_at": { + "type": "number" } }, "required": [ - "type", - "cluster_id" + "image", + "sent_at" ] }, - { + "installation": { "type": "object", "properties": { - "type": { - "type": "string", - "enum": [ - "cluster.suspend" - ] - }, - "cluster_id": { - "type": "string", - "minLength": 1, - "maxLength": 54 + "id": { + "type": "number" } }, "required": [ - "type", - "cluster_id" + "id" ] }, - { + "workflow_run": { "type": "object", "properties": { - "type": { + "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": [ - "cluster.resume" + "queued", + "in_progress", + "completed", + "action_required", + "cancelled", + "failure", + "neutral", + "skipped", + "stale", + "success", + "timed_out", + "requested", + "waiting", + "pending" ] }, - "cluster_id": { - "type": "string", - "minLength": 1, - "maxLength": 54 - } - }, - "required": [ - "type", - "cluster_id" - ] - }, - { - "type": "object", - "properties": { - "type": { + "conclusion": { "type": "string", + "nullable": true, "enum": [ - "cluster.capabilities.refresh" + "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" ] - }, - "cluster_id": { - "type": "string", - "minLength": 1, - "maxLength": 54 } }, "required": [ - "type", - "cluster_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": { - "type": { - "type": "string", - "enum": [ - "cluster.capability.ensure" + "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" ] }, - "cluster_id": { - "type": "string", - "minLength": 1, - "maxLength": 54 + "name": { + "type": "string" }, - "capability": { + "full_name": { + "type": "string" + }, + "html_url": { "type": "string", - "minLength": 1 + "format": "uri" } }, "required": [ - "type", - "cluster_id", - "capability" + "id", + "owner", + "name", + "full_name", + "html_url" ] + } + }, + "required": [ + "id", + "installation", + "workflow_run", + "repository" + ] + }, + "GithubPackagePermissions": { + "type": "object", + "properties": { + "has_warning": { + "type": "boolean" }, - { + "warning": { + "type": "string" + }, + "fix_url": { + "type": "string" + } + }, + "required": [ + "has_warning" + ] + }, + "GithubCheckPackagePermissionsBody": { + "type": "object", + "properties": { + "repository": { "type": "object", "properties": { - "type": { - "type": "string", - "enum": [ - "cluster.worker_bootstrap.revoke" - ] + "id": { + "type": "number" }, - "note": { + "owner": { + "type": "string" + }, + "name": { "type": "string" } }, "required": [ - "type" + "id", + "owner", + "name" ] }, - { + "installation_id": { + "type": "integer", + "minimum": 0, + "exclusiveMinimum": true + } + }, + "required": [ + "repository", + "installation_id" + ], + "additionalProperties": false + }, + "GithubWorkflowPrCreated": { + "type": "object", + "properties": { + "pr_id": { + "type": "integer", + "minimum": 0, + "exclusiveMinimum": true + }, + "pr_url": { + "type": "string", + "format": "uri" + }, + "status": { + "type": "string", + "enum": [ + "open" + ] + } + }, + "required": [ + "pr_id", + "pr_url", + "status" + ] + }, + "GithubCreateWorkflowPrBody": { + "type": "object", + "properties": { + "repository": { "type": "object", "properties": { - "type": { - "type": "string", - "enum": [ - "install.create" - ] - }, - "install_id": { - "type": "string", - "minLength": 1, - "maxLength": 55 + "id": { + "type": "number" }, - "argo_app_name": { + "owner": { "type": "string" }, - "argo_app_namespace": { + "name": { "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 - ] + "default_branch": { + "type": "string" } }, "required": [ - "type", - "install_id", - "sandbox_skipped" - ], - "additionalProperties": false + "id", + "owner", + "name", + "default_branch" + ] }, - { + "build_settings": { "type": "object", "properties": { - "type": { + "buildContext": { "type": "string", - "enum": [ - "install.render" - ] + "default": "./" }, - "install_render_id": { - "type": "string", - "minLength": 1, - "maxLength": 54 + "buildCommand": { + "type": "string" }, - "repository_id": { - "type": "string", - "minLength": 1, - "maxLength": 55 + "startCommand": { + "type": "string" }, - "commit_sha": { + "installCommand": { "type": "string" }, - "render_hash": { + "buildAptPackages": { "type": "string" }, - "skipped": { - "type": "boolean" + "runtimeAptPackages": { + "type": "string" } - }, - "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" - ] + "installation_id": { + "type": "integer", + "minimum": 0, + "exclusiveMinimum": true + } + }, + "required": [ + "repository", + "build_settings", + "installation_id" + ], + "additionalProperties": false + }, + "GithubVerifyInstallationResponse": { + "type": "object", + "properties": { + "redirect_url": { + "type": "string" + } + }, + "required": [ + "redirect_url" + ] + }, + "GithubVerifyInstallationBody": { + "type": "object", + "properties": { + "installation_id": { + "type": "integer", + "minimum": 0, + "exclusiveMinimum": true }, - { + "code": { + "type": "string", + "minLength": 1 + }, + "state": { + "type": "string", + "minLength": 1 + } + }, + "required": [ + "installation_id", + "code", + "state" + ], + "additionalProperties": false + }, + "Secret": { + "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/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", - "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" + "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", - "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" + "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)" + }, + "updated_at": { + "type": "integer", + "minimum": 0, + "description": "Unix timestamp (seconds)" + }, + "deleted_at": { + "type": "integer", + "minimum": 0, + "description": "Unix timestamp (seconds)" + }, + "purge_at": { + "type": "integer", + "minimum": 0, + "description": "Unix timestamp (seconds)" + }, + "expire_time": { + "type": "integer", + "minimum": 0, + "description": "Unix timestamp (seconds)" + }, + "etag": { + "type": "string" + } + }, + "required": [ + "id", + "html_url", + "workspace_id", + "name", + "kind", + "state", + "validation", + "version_count", + "enabled_version_count", + "created_at", + "updated_at", + "etag" + ] + }, + "SecretValidation": { + "type": "object", + "nullable": true, + "properties": { + "state": { + "type": "string", + "enum": [ + "unspecified", + "valid", + "invalid" ] }, + "validated_at": { + "type": "integer", + "minimum": 0, + "description": "Unix timestamp (seconds)" + }, + "error": { + "type": "string" + } + }, + "required": [ + "state", + "validated_at" + ], + "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": { - "type": { - "type": "string", - "enum": [ - "preview_hostname.delete" - ] - }, - "install_id": { + "name": { "type": "string", "minLength": 1, - "maxLength": 55 + "maxLength": 200 }, - "preview_hostname_id": { + "description": { "type": "string", - "minLength": 1, - "maxLength": 54 + "maxLength": 500 }, - "hostname": { - "type": "string", - "minLength": 1, - "maxLength": 253 - } - }, - "required": [ - "type", - "install_id", - "preview_hostname_id", - "hostname" - ] - }, - { - "type": "object", - "properties": { - "type": { + "labels": { + "type": "object", + "additionalProperties": { + "type": "string", + "maxLength": 200 + } + }, + "kind": { "type": "string", "enum": [ - "workspace.delete" + "cloud_provider/hcloud" ] }, - "workspace_id": { + "value": { "type": "string", - "minLength": 1, - "maxLength": 53 + "minLength": 1 } }, "required": [ - "type", - "workspace_id" - ] + "name", + "kind", + "value" + ], + "additionalProperties": false }, { "type": "object", "properties": { - "type": { + "name": { "type": "string", - "enum": [ - "workspace.subscription.cancel" - ] + "minLength": 1, + "maxLength": 200 }, - "subscription_id": { - "type": "string" + "description": { + "type": "string", + "maxLength": 500 }, - "cancel_at": { - "type": "integer", - "minimum": 0, - "description": "Unix timestamp (seconds)" - } - }, - "required": [ - "type", - "subscription_id", - "cancel_at" - ] - }, - { - "type": "object", - "properties": { - "type": { + "labels": { + "type": "object", + "additionalProperties": { + "type": "string", + "maxLength": 200 + } + }, + "kind": { "type": "string", "enum": [ - "workspace.subdomain.set_name" + "cloud_provider/aws" ] }, - "workspace_id": { - "type": "string", - "minLength": 1, - "maxLength": 53 - }, - "workspace_subdomain_id": { + "value": { "type": "string", - "minLength": 1, - "maxLength": 54 + "minLength": 1 }, - "fqdn": { - "type": "string", - "minLength": 1, - "maxLength": 253 + "aws_access_key_id": { + "type": "string" } }, "required": [ - "type", - "workspace_id", - "workspace_subdomain_id", - "fqdn" - ] + "name", + "kind", + "value" + ], + "additionalProperties": false }, { "type": "object", "properties": { - "type": { - "type": "string", - "enum": [ - "custom_domain.create" - ] - }, - "workspace_id": { + "name": { "type": "string", "minLength": 1, - "maxLength": 53 + "maxLength": 200 }, - "custom_domain_id": { + "description": { "type": "string", - "minLength": 1, - "maxLength": 54 + "maxLength": 500 }, - "hostname": { - "type": "string", - "minLength": 1, - "maxLength": 253 - } - }, - "required": [ - "type", - "workspace_id", - "custom_domain_id", - "hostname" - ] - }, - { - "type": "object", - "properties": { - "type": { + "labels": { + "type": "object", + "additionalProperties": { + "type": "string", + "maxLength": 200 + } + }, + "kind": { "type": "string", "enum": [ - "custom_domain.update" + "cloud_provider/gcp" ] }, - "workspace_id": { - "type": "string", - "minLength": 1, - "maxLength": 53 - }, - "custom_domain_id": { - "type": "string", - "minLength": 1, - "maxLength": 54 - }, - "hostname": { + "value": { "type": "string", - "minLength": 1, - "maxLength": 253 + "minLength": 1 } }, "required": [ - "type", - "workspace_id", - "custom_domain_id", - "hostname" - ] + "name", + "kind", + "value" + ], + "additionalProperties": false }, { "type": "object", "properties": { - "type": { - "type": "string", - "enum": [ - "custom_domain.delete" - ] - }, - "workspace_id": { + "name": { "type": "string", "minLength": 1, - "maxLength": 53 + "maxLength": 200 }, - "custom_domain_id": { + "description": { "type": "string", - "minLength": 1, - "maxLength": 54 + "maxLength": 500 }, - "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" - ] + "labels": { + "type": "object", + "additionalProperties": { + "type": "string", + "maxLength": 200 + } }, - "origin_route_id": { - "type": "string", - "minLength": 1, - "maxLength": 54 - } - }, - "required": [ - "type", - "origin_route_id" - ] - }, - { - "type": "object", - "properties": { - "type": { + "kind": { "type": "string", "enum": [ - "cloudflare.private_origin_route.release" + "cloud_provider/azure" ] }, - "route_intent_id": { + "value": { "type": "string", - "minLength": 1, - "maxLength": 54 + "minLength": 1 } }, "required": [ - "type", - "route_intent_id" - ] + "name", + "kind", + "value" + ], + "additionalProperties": false }, { "type": "object", "properties": { - "type": { - "type": "string", - "enum": [ - "package.create" - ] - }, - "package_id": { + "name": { "type": "string", "minLength": 1, - "maxLength": 54 + "maxLength": 200 }, - "package_version_id": { + "description": { "type": "string", - "minLength": 1, - "maxLength": 55 + "maxLength": 500 }, - "repository_id": { - "type": "string", - "minLength": 1, - "maxLength": 55 - } - }, - "required": [ - "type", - "package_id", - "package_version_id", - "repository_id" - ] - }, - { - "type": "object", - "properties": { - "type": { + "labels": { + "type": "object", + "additionalProperties": { + "type": "string", + "maxLength": 200 + } + }, + "kind": { "type": "string", "enum": [ - "repository_change_request.create" + "oci_registry" ] }, - "repository_change_request_id": { - "type": "string", - "minLength": 1, - "maxLength": 54 - }, - "fork_repository_id": { + "value": { "type": "string", - "minLength": 1, - "maxLength": 55 + "minLength": 1 }, - "expires_at": { - "type": "integer", - "minimum": 0, - "description": "Unix timestamp (seconds)" + "username": { + "type": "string" } }, "required": [ - "type", - "repository_change_request_id", - "fork_repository_id", - "expires_at" - ] + "name", + "kind", + "value" + ], + "additionalProperties": false }, { "type": "object", "properties": { - "type": { + "name": { "type": "string", - "enum": [ - "repository_change_request.accept" - ] + "minLength": 1, + "maxLength": 200 }, - "merged_at": { - "type": "integer", - "minimum": 0, - "description": "Unix timestamp (seconds)" + "description": { + "type": "string", + "maxLength": 500 }, - "triggered_install_render": { - "type": "boolean" - } - }, - "required": [ - "type", - "merged_at", - "triggered_install_render" - ] - }, - { - "type": "object", - "properties": { - "type": { + "labels": { + "type": "object", + "additionalProperties": { + "type": "string", + "maxLength": 200 + } + }, + "kind": { "type": "string", "enum": [ - "repository_change_request.reject" + "cloudflare_api" ] }, - "rejected_at": { - "type": "integer", - "minimum": 0, - "description": "Unix timestamp (seconds)" + "value": { + "type": "string", + "minLength": 1 } }, "required": [ - "type", - "rejected_at" - ] + "name", + "kind", + "value" + ], + "additionalProperties": false }, { "type": "object", "properties": { - "type": { + "name": { "type": "string", - "enum": [ - "repository_change_request.withdraw" - ] + "minLength": 1, + "maxLength": 200 }, - "withdrawn_at": { - "type": "integer", - "minimum": 0, - "description": "Unix timestamp (seconds)" - } - }, - "required": [ - "type", - "withdrawn_at" - ] - }, - { - "type": "object", - "properties": { - "type": { + "description": { "type": "string", - "enum": [ - "repository_change_request.expire" - ] + "maxLength": 500 }, - "expired": { - "type": "boolean" - } - }, - "required": [ - "type", - "expired" - ] - }, - { - "type": "object", - "properties": { - "type": { + "labels": { + "type": "object", + "additionalProperties": { + "type": "string", + "maxLength": 200 + } + }, + "kind": { "type": "string", "enum": [ - "repository.delete" + "webhook_signing" ] }, - "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" + "value": { + "type": "string", + "minLength": 16 + } + }, + "required": [ + "name", + "kind", + "value" + ], + "additionalProperties": false }, - "skippable": { - "type": "boolean" + { + "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 } - }, - "required": [ - "name", - "status", - "execution_type", - "started_at", - "completed_at", - "error_message", - "retryable", - "skippable" ] }, - "DashboardInstallList": { + "SecretList": { "type": "object", "properties": { "data": { "type": "array", "items": { - "$ref": "#/components/schemas/DashboardInstall" + "$ref": "#/components/schemas/Secret" } }, "has_more": { @@ -6354,473 +21171,154 @@ "next_cursor" ] }, - "DashboardInstall": { + "UpdateSecretBody": { "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" - }, - "workspace_id": { "type": "string", "minLength": 1, - "maxLength": 53 + "maxLength": 200 }, - "cluster_id": { + "description": { "type": "string", - "minLength": 1, - "maxLength": 54 - }, - "cluster_name": { - "type": "string" + "maxLength": 500 }, - "region_name": { - "type": "string" + "labels": { + "type": "object", + "additionalProperties": { + "type": "string", + "maxLength": 200 + } }, - "region_icon": { + "mime_type": { "type": "string", - "nullable": true - }, - "created_at": { - "type": "integer", - "minimum": 0, - "description": "Unix timestamp (seconds)" + "maxLength": 100 }, - "updated_at": { - "type": "integer", - "minimum": 0, - "description": "Unix timestamp (seconds)" + "version_aliases": { + "type": "object", + "additionalProperties": { + "type": "integer", + "minimum": 0, + "exclusiveMinimum": true + } + } + }, + "additionalProperties": false + }, + "ValidateProviderTokenResult": { + "type": "object", + "properties": { + "valid": { + "type": "boolean", + "description": "Whether the token authenticated successfully." }, - "etag": { - "type": "string" + "error": { + "type": "string", + "description": "Human-readable reason when `valid` is false." } }, "required": [ - "id", - "html_url", - "name", - "workspace_id", - "cluster_id", - "cluster_name", - "region_name", - "region_icon", - "created_at", - "updated_at", - "etag" + "valid" ] }, - "DashboardInstallDetail": { + "ValidateProviderTokenBody": { "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": { + "provider": { "type": "string", - "minLength": 1, - "maxLength": 53 + "enum": [ + "hcloud" + ], + "description": "Cloud provider to validate the token against." }, - "cluster_id": { + "value": { "type": "string", "minLength": 1, - "maxLength": 54 - }, - "name": { - "type": "string", - "nullable": true - }, - "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": { - "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": [ - "id", - "name", - "region" - ] - }, - "product": { - "type": "object", - "nullable": true, - "properties": { - "name": { - "type": "string" - }, - "is_owner": { - "type": "boolean" - } - }, - "required": [ - "name", - "is_owner" - ] - }, - "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" + "description": "The provider API token to probe. Consumed, never stored." } }, "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" + "provider", + "value" ] }, - "InstallUrl": { + "SecretVersion": { "type": "object", "properties": { - "route_key": { - "type": "string" - }, - "hostname": { - "type": "string" - }, - "url": { + "id": { "type": "string", - "format": "uri" + "minLength": 1, + "maxLength": 55 }, - "protocol": { + "secret_id": { "type": "string", - "enum": [ - "http", - "websocket", - "grpc" - ], - "description": "Transport class for route forwarding." + "minLength": 1, + "maxLength": 54 }, - "routing_mode": { - "type": "string", - "enum": [ - "through_dispatcher", - "bypass_dispatcher" - ], - "description": "Whether traffic uses the dispatcher Worker or bypasses it." + "version_number": { + "type": "integer", + "minimum": 0, + "exclusiveMinimum": true }, - "status": { + "state": { "type": "string", "enum": [ - "pending", - "provisioning", - "active", - "not_ready", - "failed" - ], - "description": "Customer-facing install URL routing state." - }, - "error": { - "type": "string" + "enabled", + "disabled", + "destroyed" + ] }, - "last_observed_at": { - "type": "integer", - "minimum": 0, - "description": "Unix timestamp (seconds)" + "comment": { + "type": "string", + "maxLength": 200 }, - "updated_at": { + "created_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": { - "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 - } }, - "updated_at": { + "destroyed_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" - }, - "namespace": { - "type": "string" }, - "version": { - "type": "string" - }, - "status": { + "etag": { "type": "string" - }, - "health": { - "type": "object", - "properties": { - "status": { - "type": "string" - } - }, - "required": [ - "status" - ] } }, "required": [ - "kind", - "name" - ], - "additionalProperties": { - "nullable": true - } + "id", + "secret_id", + "version_number", + "state", + "created_at", + "etag" + ] }, - "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 + "CreateSecretVersionBody": { + "type": "object", + "properties": { + "value": { + "type": "string", + "minLength": 1 }, - { - "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 + "comment": { + "type": "string", + "maxLength": 200 } + }, + "required": [ + "value" ], - "description": "Visible cleanup state for non-billable demo installs. Temporal workflow IDs and internal cleanup evidence are intentionally omitted." + "additionalProperties": false }, - "InstallList": { + "SecretVersionList": { "type": "object", "properties": { "data": { "type": "array", "items": { - "$ref": "#/components/schemas/Install" + "$ref": "#/components/schemas/SecretVersion" } }, "has_more": { @@ -6839,334 +21337,329 @@ "next_cursor" ] }, - "Install": { + "SecretPlaintext": { "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 + "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": { + "type": "object", + "properties": { + "stripe_account_id": { + "type": "string" }, - "product_id": { - "type": "string", - "minLength": 1, - "maxLength": 55 + "charges_enabled": { + "type": "boolean" }, - "package_version_id": { + "payouts_enabled": { + "type": "boolean" + } + }, + "required": [ + "stripe_account_id", + "charges_enabled", + "payouts_enabled" + ] + }, + "StripeAccountLinkCreated": { + "type": "object", + "properties": { + "url": { + "type": "string" + } + }, + "required": [ + "url" + ] + }, + "CreateStripeAccountLinkBody": { + "type": "object", + "properties": { + "return_url": { "type": "string", - "minLength": 1, - "maxLength": 55 + "format": "uri" }, - "state": { + "refresh_url": { "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": { + "format": "uri" + } + }, + "additionalProperties": false + }, + "StripeAccountSessionCreated": { + "type": "object", + "properties": { + "client_secret": { "type": "string" } }, "required": [ - "id", - "html_url", - "workspace_id", - "customer_workspace", - "cluster_id", - "product_id", - "package_version_id", - "state", - "reconciling", - "urls", - "created_at", - "updated_at", - "etag" + "client_secret" ] }, - "InstallCustomerWorkspace": { + "CreateStripeAccountSessionBody": { + "type": "object", + "properties": {}, + "additionalProperties": false + }, + "WorkspaceStripeProducts": { "type": "object", "properties": { - "id": { + "data": { + "type": "array", + "items": { + "$ref": "#/components/schemas/StripeProduct" + } + }, + "has_more": { + "type": "boolean", + "description": "True if more items exist after this page." + }, + "next_cursor": { "type": "string", - "minLength": 1, - "maxLength": 53 + "nullable": true, + "description": "Opaque cursor for the next page, or null if no more pages." }, - "name": { + "stripe_account_id": { "type": "string", - "minLength": 1, - "maxLength": 100 + "nullable": true } }, "required": [ - "id", - "name" + "data", + "has_more", + "next_cursor", + "stripe_account_id" ] }, - "InstallDomainSettings": { + "StripeProduct": { "type": "object", "properties": { - "workspace_subdomain": { - "$ref": "#/components/schemas/InstallDomainSettingsWorkspaceSubdomain" + "id": { + "type": "string" }, - "preview_hostnames": { + "name": { + "type": "string" + }, + "images": { "type": "array", "items": { - "$ref": "#/components/schemas/InstallDomainSettingsPreviewHostname" + "type": "string" } }, - "custom_domains": { + "prices": { "type": "array", "items": { - "$ref": "#/components/schemas/InstallDomainSettingsCustomDomain" + "$ref": "#/components/schemas/StripePrice" } } }, "required": [ - "workspace_subdomain", - "preview_hostnames", - "custom_domains" + "id", + "name", + "images", + "prices" ] }, - "InstallDomainSettingsWorkspaceSubdomain": { + "StripePrice": { "type": "object", - "nullable": true, "properties": { "id": { - "type": "string", - "minLength": 1, - "maxLength": 54 + "type": "string" }, - "workspace_id": { - "type": "string", - "minLength": 1, - "maxLength": 53 + "currency": { + "type": "string" }, - "name": { - "type": "string", - "minLength": 1, - "maxLength": 63 + "billing_scheme": { + "type": "string" }, - "fqdn": { + "nickname": { "type": "string", - "minLength": 1, - "maxLength": 253 + "nullable": true }, - "status": { + "unit_amount": { + "type": "number", + "nullable": true + }, + "unit_amount_decimal": { "type": "string", - "enum": [ - "active", - "propagating", - "reserved" - ] + "nullable": true }, - "name_changed_at": { - "type": "integer", + "recurring": { + "type": "object", "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" + "properties": { + "interval": { + "type": "string" + }, + "interval_count": { + "type": "number" + }, + "usage_type": { + "type": "string" + } + }, + "required": [ + "interval", + "interval_count", + "usage_type" + ] } }, "required": [ "id", - "workspace_id", - "name", - "fqdn", - "status", - "name_changed_at", - "created_at", - "updated_at", - "etag" + "currency", + "billing_scheme", + "nickname", + "unit_amount", + "unit_amount_decimal", + "recurring" ] }, - "InstallDomainSettingsPreviewHostname": { + "UpgradeCheckoutCreated": { "type": "object", "properties": { - "id": { + "url": { + "type": "string" + } + }, + "required": [ + "url" + ] + }, + "CreateUpgradeCheckoutBody": { + "type": "object", + "properties": { + "success_url": { "type": "string", - "minLength": 1, - "maxLength": 54 + "format": "uri" }, - "workspace_id": { + "cancel_url": { "type": "string", - "minLength": 1, - "maxLength": 53 - }, - "install_id": { + "format": "uri" + } + }, + "required": [ + "success_url", + "cancel_url" + ], + "additionalProperties": false + }, + "BillingPortalSessionCreated": { + "type": "object", + "properties": { + "url": { + "type": "string" + } + }, + "required": [ + "url" + ] + }, + "CreateBillingPortalSessionBody": { + "type": "object", + "properties": { + "return_url": { "type": "string", - "minLength": 1, - "maxLength": 55 + "format": "uri" + } + }, + "required": [ + "return_url" + ], + "additionalProperties": false + }, + "ClusterList": { + "type": "object", + "properties": { + "data": { + "type": "array", + "items": { + "$ref": "#/components/schemas/Cluster" + } }, - "hostname": { - "type": "string", - "minLength": 1, - "maxLength": 253 + "has_more": { + "type": "boolean", + "description": "True if more items exist after this page." }, - "protocol": { + "next_cursor": { "type": "string", - "enum": [ - "http", - "websocket", - "grpc" - ], - "description": "Transport class for route forwarding." - }, - "routing_mode": { + "nullable": true, + "description": "Opaque cursor for the next page, or null if no more pages." + } + }, + "required": [ + "data", + "has_more", + "next_cursor" + ] + }, + "Cluster": { + "type": "object", + "properties": { + "id": { "type": "string", - "enum": [ - "through_dispatcher", - "bypass_dispatcher" - ], - "description": "Whether traffic uses the dispatcher Worker or bypasses it." + "minLength": 1, + "maxLength": 54 }, - "binding_kind": { + "html_url": { "type": "string", - "enum": [ - "pinned", - "floating" - ] + "maxLength": 2048, + "format": "uri", + "description": "Absolute dashboard URL for this resource. OUTPUT_ONLY.", + "example": "https://akua.dev/clusters/clu_j572abc123def456" }, - "track": { + "name": { + "type": "string" + }, + "workspace_id": { "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 - } - ] + "maxLength": 53 }, - "status": { + "state": { "type": "string", "enum": [ + "pending", "provisioning", "active", - "evicted", - "releasing" - ] - }, - "last_seen_at": { - "type": "integer", - "nullable": true, - "minimum": 0, - "description": "Unix timestamp (seconds)" + "suspended", + "deleting" + ], + "description": "Cluster lifecycle state in canonical lowercase, past-participle naming." }, - "observed_url": { + "provider": { "type": "string", - "nullable": true + "enum": [ + "managed_kaas", + "imported_byoc" + ], + "description": "Cluster control-plane family: managed (`managed_kaas`) vs imported self-managed (`imported_byoc`)." }, - "error": { - "type": "string", - "nullable": true + "reconciling": { + "type": "boolean" }, "created_at": { "type": "integer", @@ -7184,24 +21677,39 @@ }, "required": [ "id", + "html_url", + "name", "workspace_id", - "install_id", - "hostname", - "protocol", - "routing_mode", - "binding_kind", - "track", - "binding", - "status", - "last_seen_at", - "observed_url", - "error", + "state", + "provider", + "reconciling", "created_at", "updated_at", "etag" ] }, - "InstallDomainSettingsCustomDomain": { + "DashboardClusterList": { + "type": "object", + "properties": { + "clusters": { + "type": "array", + "items": { + "$ref": "#/components/schemas/DashboardCluster" + } + }, + "regions": { + "type": "array", + "items": { + "$ref": "#/components/schemas/DashboardClusterRegion" + } + } + }, + "required": [ + "clusters", + "regions" + ] + }, + "DashboardCluster": { "type": "object", "properties": { "id": { @@ -7209,153 +21717,39 @@ "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 }, - "hostname": { + "region_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": { - "type": "string", - "enum": [ - "http", - "websocket", - "grpc" - ], - "description": "Transport class for route forwarding." + "region": { + "$ref": "#/components/schemas/DashboardClusterRegion" }, - "routing_mode": { + "provider": { "type": "string", "enum": [ - "through_dispatcher", - "bypass_dispatcher" + "managed_kaas", + "imported_byoc" ], - "description": "Whether traffic uses the dispatcher Worker or bypasses it." - }, - "target_kind": { - "type": "string", - "enum": [ - "install", - "cluster", - "external" - ] - }, - "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" - ] - }, - "status": { - "type": "string", - "enum": [ - "provisioning", - "active", - "failed", - "releasing" - ] + "description": "Cluster control-plane family: managed (`managed_kaas`) vs imported self-managed (`imported_byoc`)." }, - "error": { - "type": "string", - "nullable": true + "kaas": { + "$ref": "#/components/schemas/ClusterKaas" }, "created_at": { "type": "integer", @@ -7367,110 +21761,176 @@ "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", + "html_url", + "name", "workspace_id", - "hostname", - "target", - "protocol", - "routing_mode", - "target_kind", - "cloudflare_custom_hostname_id", - "ssl", - "status", - "error", + "region_id", + "region", + "provider", + "kaas", "created_at", "updated_at", + "product_count", + "installs_count", + "deployment_health", + "active_operation", "etag" ] }, - "CreateInstallBody": { + "DashboardClusterRegion": { "type": "object", "properties": { - "product_id": { + "id": { "type": "string", "minLength": 1, - "maxLength": 55 + "maxLength": 54 }, - "region_id": { + "name": { + "type": "string" + }, + "icon": { + "type": "string", + "nullable": true + }, + "workspace_id": { "type": "string", "minLength": 1, - "maxLength": 54 + "maxLength": 53 }, - "initial_values": { - "type": "object", - "additionalProperties": { - "nullable": true - } + "created_at": { + "type": "integer", + "minimum": 0, + "description": "Unix timestamp (seconds)" } }, "required": [ - "product_id", - "region_id" - ], - "additionalProperties": false + "id", + "name", + "icon", + "workspace_id", + "created_at" + ] }, - "InstallRender": { + "ClusterKaas": { "type": "object", + "nullable": true, "properties": { - "id": { - "type": "string", - "minLength": 1, - "maxLength": 54 + "namespace": { + "type": "string" }, - "workspace_id": { - "type": "string", - "minLength": 1, - "maxLength": 53 + "version": { + "type": "string" }, - "install_id": { + "network_profile": { "type": "string", - "minLength": 1, - "maxLength": 55 + "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`." }, - "operation_id": { + "status": { "type": "string", - "nullable": true, - "minLength": 1, - "maxLength": 53 + "enum": [ + "PROVISIONING", + "RUNNING", + "RECONCILING", + "SUSPENDING", + "SUSPENDED", + "RESUMING", + "DELETING", + "ERROR", + "DEGRADED" + ] }, - "repository_change_request_id": { + "status_message": { "type": "string", + "nullable": true + }, + "suspended_at": { + "type": "integer", "nullable": true, - "minLength": 1, - "maxLength": 54 + "minimum": 0, + "description": "Unix timestamp (seconds)" }, - "render_hash": { + "suspended_by": { "type": "string", "nullable": true + } + }, + "required": [ + "namespace", + "version", + "network_profile", + "status", + "status_message", + "suspended_at", + "suspended_by" + ] + }, + "DashboardClusterDeploymentHealth": { + "type": "object", + "properties": { + "healthy": { + "type": "integer", + "minimum": 0 }, - "commit_sha": { - "type": "string", - "nullable": true + "degraded": { + "type": "integer", + "minimum": 0 }, - "state": { - "type": "string", - "enum": [ - "running", - "deployed", - "skipped", - "failed" - ] + "reconciling": { + "type": "integer", + "minimum": 0 }, - "message": { + "failed": { + "type": "integer", + "minimum": 0 + } + }, + "required": [ + "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." + }, + "DashboardClusterActiveOperation": { + "type": "object", + "nullable": true, + "properties": { + "id": { "type": "string", - "nullable": true + "minLength": 1, + "maxLength": 53 }, - "created_at": { - "type": "integer", - "minimum": 0, - "description": "Unix timestamp (seconds)" + "type": { + "type": "string", + "minLength": 1 }, - "updated_at": { + "started_at": { "type": "integer", "minimum": 0, "description": "Unix timestamp (seconds)" @@ -7478,664 +21938,553 @@ }, "required": [ "id", - "workspace_id", - "install_id", - "render_hash", - "state", - "created_at", - "updated_at" - ] + "type", + "started_at" + ], + "description": "The authoritative running operation for this cluster, independent of recent-operation pagination." }, - "CreateInstallRenderBody": { + "ClusterCapabilities": { "type": "object", "properties": { - "message": { - "type": "string", - "maxLength": 255 + "api_groups": { + "type": "array", + "items": { + "type": "string" + } }, - "skip_unchanged": { - "type": "boolean", - "nullable": true, - "default": true + "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" + ] + } + }, + "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" + }, + "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" + ] + } }, - "extra_annotations": { + "default_gateway": { "type": "object", - "additionalProperties": { + "properties": { + "namespace": { + "type": "string" + }, + "name": { + "type": "string" + } + }, + "required": [ + "namespace", + "name" + ] + }, + "ingress_classes": { + "type": "array", + "items": { "type": "string" } - } - }, - "additionalProperties": false - }, - "InstallRenderList": { - "type": "object", - "properties": { - "data": { + }, + "nodes": { "type": "array", "items": { - "$ref": "#/components/schemas/InstallRender" + "$ref": "#/components/schemas/ClusterNode" } }, - "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." + "freshness": { + "$ref": "#/components/schemas/ClusterCapabilitiesFreshness" } }, "required": [ - "data", - "has_more", - "next_cursor" + "api_groups", + "storage_classes", + "gateway_classes", + "gateways", + "ingress_classes", + "nodes", + "freshness" ] }, - "InstallStatus": { + "ClusterNode": { "type": "object", "properties": { - "install_id": { - "type": "string", - "minLength": 1, - "maxLength": 55 + "name": { + "type": "string" }, - "health": { - "type": "string", - "nullable": true + "ready": { + "type": "boolean" }, - "sync": { - "type": "string", - "nullable": true + "worker_capacity": { + "type": "boolean" }, - "revision": { - "type": "string", - "nullable": true + "schedulable": { + "type": "boolean" }, - "resources": { + "addresses": { "type": "array", - "nullable": true, "items": { - "$ref": "#/components/schemas/ResourceStatus" + "type": "object", + "properties": { + "type": { + "type": "string" + }, + "value": { + "type": "string" + } + }, + "required": [ + "type", + "value" + ] } }, - "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": { + "status_message": { "type": "string" }, - "containers": { + "roles": { "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" - }, - "workspace_id": { - "type": "string", - "minLength": 1, - "maxLength": 53 }, - "name": { + "created_at": { "type": "string" }, - "latest_version_id": { - "type": "string", - "minLength": 1, - "maxLength": 55 + "version": { + "type": "string" }, - "description": { - "type": "string", - "nullable": true + "cpu_capacity": { + "type": "string" }, - "source": { - "$ref": "#/components/schemas/PackageSource" + "memory_capacity": { + "type": "string" }, - "composed_from_sources": { - "type": "array", - "nullable": true, - "items": { - "type": "object", - "additionalProperties": { - "nullable": true - } - }, - "description": "Source provenance used to create this Package (helm URLs, OCI refs, git source details). Only visible in `view=full`." + "os_image": { + "type": "string" }, - "created_at": { - "type": "integer", - "minimum": 0, - "description": "Unix timestamp (seconds)" + "operating_system": { + "type": "string" }, - "etag": { + "architecture": { "type": "string" } }, "required": [ - "id", - "html_url", - "workspace_id", "name", - "latest_version_id", - "description", - "source", - "created_at" + "roles", + "version", + "cpu_capacity", + "memory_capacity", + "os_image", + "architecture" ] }, - "PackageSource": { - "oneOf": [ + "ClusterCapabilitiesFreshness": { + "anyOf": [ { "type": "object", "properties": { - "kind": { + "state": { "type": "string", "enum": [ - "hosted" + "missing" ] }, - "repository_id": { + "max_age_seconds": { + "type": "integer", + "minimum": 0 + }, + "age_seconds": { + "nullable": true + }, + "last_successful_at": { + "nullable": true + }, + "last_refresh_status": { "type": "string", - "minLength": 1, - "maxLength": 55, - "description": "platform-hosted repository that contains the package source" + "nullable": true, + "enum": [ + "FAILED", + "RUNNING", + null + ] + }, + "last_refresh_error": { + "type": "string", + "nullable": true } }, "required": [ - "kind", - "repository_id" + "state", + "max_age_seconds", + "age_seconds", + "last_successful_at", + "last_refresh_status", + "last_refresh_error" ] }, { "type": "object", "properties": { - "kind": { + "state": { "type": "string", "enum": [ - "oci" + "fresh", + "stale" ] }, - "oci_ref": { + "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", - "description": "OCI reference to the package source (no digest)" + "enum": [ + "SUCCESS", + "FAILED", + "RUNNING" + ] + }, + "last_refresh_error": { + "type": "string", + "nullable": true } }, "required": [ - "kind", - "oci_ref" + "state", + "max_age_seconds", + "age_seconds", + "last_successful_at", + "last_refresh_status", + "last_refresh_error" ] } ] }, - "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" - ] - }, - "PackageWithVersions": { + "Kubeconfig": { "type": "object", "properties": { - "id": { - "type": "string", - "minLength": 1, - "maxLength": 54 - }, - "name": { + "kubeconfig": { "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-]+)*))?$" } }, "required": [ - "id", - "semver" + "kubeconfig" ] }, - "PackageInventoryList": { + "ExecResult": { "type": "object", "properties": { - "data": { - "type": "array", - "items": { - "$ref": "#/components/schemas/PackageInventoryRow" - } + "output": { + "type": "string" }, - "has_more": { - "type": "boolean", - "description": "True if more items exist after this page." + "exit_code": { + "type": "integer" }, - "next_cursor": { - "type": "string", - "nullable": true, - "description": "Opaque cursor for the next page, or null if no more pages." + "duration_ms": { + "type": "number", + "minimum": 0 } }, "required": [ - "data", - "has_more", - "next_cursor" + "output", + "exit_code", + "duration_ms" ] }, - "PackageInventoryRow": { + "ExecBody": { "type": "object", "properties": { - "id": { + "namespace": { "type": "string", "minLength": 1, - "maxLength": 54 + "maxLength": 253 }, - "workspace_id": { + "pod": { "type": "string", "minLength": 1, - "maxLength": 53 - }, - "name": { - "type": "string" + "maxLength": 253 }, - "description": { + "container": { "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" - } - }, - "required": [ - "id", - "workspace_id", - "name", - "description", - "source", - "versions", - "has_more_versions", - "created_at", - "etag" - ] - }, - "PackageDetailResponse": { - "type": "object", - "nullable": true, - "properties": { - "package": { - "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 - }, - "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": [ - "id", - "workspace_id", - "name", - "description", - "source", - "created_at", - "etag" - ] + "minLength": 1, + "maxLength": 253 }, - "versions": { + "command": { "type": "array", "items": { - "$ref": "#/components/schemas/PackageDetailVersion" + "type": "string" } } }, "required": [ - "package", - "versions" - ] + "namespace", + "pod", + "command" + ], + "additionalProperties": false }, - "PackageDetailVersion": { + "WorkerBootstrap": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, - "maxLength": 55 + "maxLength": 54 }, - "package_id": { + "cluster_id": { "type": "string", "minLength": 1, "maxLength": 54 }, - "semver": { + "status": { "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" + "enum": [ + "active", + "revoked", + "expired" + ], + "description": "Lifecycle state for a one-time worker bootstrap token." }, - "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" - ] + "created_at": { + "type": "integer", + "minimum": 0, + "description": "Unix timestamp (seconds)" }, - "published_at": { + "updated_at": { "type": "integer", "minimum": 0, "description": "Unix timestamp (seconds)" }, - "created_at": { + "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": [ "id", - "package_id", - "semver", - "ref", - "input_schema", - "published_at", + "cluster_id", + "status", "created_at", - "etag" + "updated_at", + "etag", + "reconciling", + "active_operation" ] }, - "PackageVersionInputs": { + "WorkerBootstrapList": { "type": "object", - "additionalProperties": { - "nullable": true - } + "properties": { + "data": { + "type": "array", + "items": { + "$ref": "#/components/schemas/WorkerBootstrap" + } + }, + "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" + ] }, - "PackageVersionList": { + "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": { "type": "object", "properties": { "data": { "type": "array", "items": { - "$ref": "#/components/schemas/PackageVersion" + "$ref": "#/components/schemas/OrganizationListItem" } }, "has_more": { @@ -8154,566 +22503,684 @@ "next_cursor" ] }, - "PackageVersion": { + "OrganizationListItem": { "type": "object", "properties": { "id": { - "type": "string", - "minLength": 1, - "maxLength": 55 - }, - "package_id": { "type": "string", "minLength": 1, "maxLength": 54 }, - "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-]+)*))?$" + "example": "Code Zero" }, - "ref": { - "type": "string" + "slug": { + "type": "string", + "nullable": true, + "example": "code-zero" }, - "input_schema": { - "type": "object", - "additionalProperties": { - "nullable": true - } + "icon": { + "type": "string", + "nullable": true, + "maxLength": 256, + "format": "uri", + "example": "https://github.com/code-zero.png" }, - "published_at": { + "created_at": { "type": "integer", "minimum": 0, "description": "Unix timestamp (seconds)" }, - "created_at": { + "updated_at": { "type": "integer", "minimum": 0, "description": "Unix timestamp (seconds)" }, "etag": { "type": "string" + }, + "role": { + "type": "string", + "enum": [ + "owner", + "admin", + "member" + ], + "description": "Membership role in the organization" } }, "required": [ "id", - "package_id", - "semver", - "ref", - "input_schema", - "published_at", - "created_at" + "name", + "slug", + "icon", + "created_at", + "updated_at", + "etag", + "role" ] }, - "PackageArtifacthubValuesSchema": { + "Organization": { "type": "object", "properties": { - "values": { - "type": "object", - "additionalProperties": { - "nullable": true - }, - "description": "Parsed chart values object" + "id": { + "type": "string", + "minLength": 1, + "maxLength": 54 }, - "schema": { - "type": "object", + "name": { + "type": "string", + "example": "Code Zero" + }, + "slug": { + "type": "string", "nullable": true, - "additionalProperties": { - "nullable": true - }, - "description": "JSON Schema for the values (null when the values cannot be parsed)" + "example": "code-zero" }, - "values_yaml": { + "icon": { "type": "string", - "description": "Raw chart values YAML" + "nullable": true, + "maxLength": 256, + "format": "uri", + "example": "https://github.com/code-zero.png" + }, + "created_at": { + "type": "integer", + "minimum": 0, + "description": "Unix timestamp (seconds)" + }, + "updated_at": { + "type": "integer", + "minimum": 0, + "description": "Unix timestamp (seconds)" + }, + "etag": { + "type": "string" } }, "required": [ - "values", - "schema", - "values_yaml" + "id", + "name", + "slug", + "icon", + "created_at", + "updated_at", + "etag" ] }, - "ImportPackageBody": { + "OrganizationCreateRequest": { "type": "object", "properties": { "name": { "type": "string", - "minLength": 1, - "maxLength": 120 - }, - "description": { - "type": "string", - "nullable": true, - "maxLength": 1000 + "minLength": 2, + "maxLength": 50, + "pattern": "^[\\p{L}\\p{N}](?:[\\p{L}\\p{N}\\s\\-'&.]*[\\p{L}\\p{N}])?$/u" }, - "oci_ref": { + "slug": { "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" + "minLength": 3, + "maxLength": 39, + "pattern": "^[a-z0-9](?:[a-z0-9-]*[a-z0-9])?$" } }, "required": [ - "name", - "oci_ref", - "version" + "name" ], "additionalProperties": false }, - "CreatePackageVersionBody": { + "OrganizationOk": { "type": "object", "properties": { - "semver": { + "ok": { + "type": "boolean", + "enum": [ + true + ] + } + }, + "required": [ + "ok" + ] + }, + "OrganizationUpdateRequest": { + "type": "object", + "properties": { + "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-]+)*))?$", - "example": "1.2.3" + "minLength": 2, + "maxLength": 50, + "pattern": "^[\\p{L}\\p{N}](?:[\\p{L}\\p{N}\\s\\-'&.]*[\\p{L}\\p{N}])?$/u" }, - "ref": { + "slug": { "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." + "minLength": 3, + "maxLength": 39, + "pattern": "^[a-z0-9](?:[a-z0-9-]*[a-z0-9])?$" }, - "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." - } - ] + "icon": { + "type": "string", + "nullable": true, + "maxLength": 256, + "format": "uri" + } + }, + "additionalProperties": false + }, + "OrganizationMemberList": { + "type": "object", + "properties": { + "data": { + "type": "array", + "items": { + "$ref": "#/components/schemas/OrganizationMember" + } }, - "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" - ] + "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": [ - "semver", - "ref", - "input_schema" - ], - "additionalProperties": false + "data", + "has_more", + "next_cursor" + ] }, - "PackageOperationEnvelope": { + "OrganizationMember": { "type": "object", "properties": { - "id": { + "user_id": { + "type": "string", + "example": "user_abc123", + "description": "BetterAuth user ID of the member" + }, + "name": { "type": "string", - "minLength": 1, - "maxLength": 53 + "nullable": true, + "example": "Robin Owner" }, - "workspace_id": { + "email": { "type": "string", "nullable": true, - "minLength": 1, - "maxLength": 53 + "format": "email", + "example": "robin@example.com" }, - "organization_id": { + "image": { "type": "string", "nullable": true, - "minLength": 1, - "maxLength": 54 + "format": "uri", + "example": "https://example.com/robin.png" }, - "owner_type": { + "role": { "type": "string", "enum": [ - "install", - "repository_change_request", - "repository", - "workspace", - "machine", - "cluster", - "package" + "owner", + "admin", + "member" ], - "description": "Domain entity collection the operation acts on." + "description": "Membership role in the organization", + "example": "admin" }, - "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_`)." + "joined_at": { + "type": "integer", + "minimum": 0, + "description": "Unix timestamp (seconds)" }, - "parent_operation_id": { + "updated_at": { + "type": "integer", + "minimum": 0, + "description": "Unix timestamp (seconds)" + }, + "etag": { + "type": "string" + } + }, + "required": [ + "user_id", + "name", + "email", + "image", + "role", + "joined_at", + "updated_at", + "etag" + ] + }, + "OrganizationAddMemberRequest": { + "type": "object", + "properties": { + "user_id": { "type": "string", - "nullable": true, - "minLength": 1, - "maxLength": 53, - "description": "ID of the chained parent operation, when present." + "example": "user_abc123", + "description": "BetterAuth user ID of the user to add" }, - "state": { + "role": { "type": "string", "enum": [ - "RUNNING", - "SUCCEEDED", - "FAILED", - "CANCELLED" + "owner", + "admin", + "member" ], - "description": "Lifecycle state. Past-participle terminal states per AIP-216." + "default": "member", + "description": "Membership role in the organization" + } + }, + "required": [ + "user_id" + ], + "additionalProperties": false + }, + "OrganizationInvitationList": { + "type": "object", + "properties": { + "data": { + "type": "array", + "items": { + "$ref": "#/components/schemas/OrganizationInvitation" + } }, - "done": { + "has_more": { "type": "boolean", - "description": "True iff state is a terminal value." + "description": "True if more items exist after this page." }, - "html_url": { + "next_cursor": { "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" + "nullable": true, + "description": "Opaque cursor for the next page, or null if no more pages." + } + }, + "required": [ + "data", + "has_more", + "next_cursor" + ] + }, + "OrganizationInvitation": { + "type": "object", + "properties": { + "id": { + "type": "string", + "pattern": "^orgi_[a-z0-9]+$" }, - "metadata": { - "$ref": "#/components/schemas/PackageOperationMetadata" + "organization_id": { + "type": "string", + "minLength": 1, + "maxLength": 54 }, - "response": { - "$ref": "#/components/schemas/PackageOperationResponse" + "email": { + "type": "string", + "format": "email" }, - "error": { - "type": "object", - "nullable": true, - "properties": { - "message": { - "type": "string" - } - }, - "required": [ - "message" + "role": { + "type": "string", + "enum": [ + "owner", + "admin", + "member" ], - "description": "Populated when `state` is `FAILED` or `CANCELLED`." + "description": "Membership role in the organization" }, - "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." + "status": { + "type": "string", + "enum": [ + "pending", + "accepted", + "canceled" + ] }, - "started_at": { + "invited_by": { + "type": "string" + }, + "expires_at": { "type": "integer", "minimum": 0, "description": "Unix timestamp (seconds)" }, - "completed_at": { + "created_at": { "type": "integer", - "nullable": true, "minimum": 0, "description": "Unix timestamp (seconds)" }, - "steps": { - "type": "array", - "items": { - "$ref": "#/components/schemas/PackageOperationStep" - } + "updated_at": { + "type": "integer", + "minimum": 0, + "description": "Unix timestamp (seconds)" + }, + "etag": { + "type": "string" } }, "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" + "email", + "role", + "status", + "invited_by", + "expires_at", + "created_at", + "updated_at", + "etag" ] }, - "PackageOperationMetadata": { + "OrganizationInvitationCreateRequest": { "type": "object", "properties": { - "type": { + "email": { + "type": "string" + }, + "role": { "type": "string", "enum": [ - "package.create" - ] + "owner", + "admin", + "member" + ], + "default": "member", + "description": "Membership role in the organization" + } + }, + "required": [ + "email" + ], + "additionalProperties": false + }, + "OrganizationInvitationAcceptRequest": { + "type": "object", + "properties": { + "token": { + "type": "string", + "minLength": 32, + "maxLength": 512 + } + }, + "required": [ + "token" + ], + "additionalProperties": false + }, + "OrganizationUpdateMemberRoleRequest": { + "type": "object", + "properties": { + "role": { + "type": "string", + "enum": [ + "owner", + "admin", + "member" + ], + "description": "Membership role in the organization" + } + }, + "required": [ + "role" + ], + "additionalProperties": false + }, + "ManagedWorkspaceList": { + "type": "object", + "properties": { + "data": { + "type": "array", + "items": { + "$ref": "#/components/schemas/ManagedWorkspace" + } }, - "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": { + "ManagedWorkspace": { "type": "object", - "nullable": true, "properties": { - "type": { + "id": { "type": "string", - "enum": [ - "package.create" - ] + "minLength": 1, + "maxLength": 53 }, - "package_id": { + "name": { "type": "string", - "minLength": 1, - "maxLength": 54 + "example": "My Workspace" }, - "package_version_id": { + "icon": { "type": "string", - "minLength": 1, - "maxLength": 55 + "nullable": true, + "example": null }, - "repository_id": { + "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/Notification" + } + }, + "has_more": { + "type": "boolean", + "description": "True if more items exist after this page." + }, + "next_cursor": { "type": "string", - "minLength": 1, - "maxLength": 55 + "nullable": true, + "description": "Opaque cursor for the next page, or null if no more pages." } }, "required": [ - "type", - "package_id", - "package_version_id", - "repository_id" - ], - "description": "Populated only when `done && state === \"SUCCEEDED\"`." + "data", + "has_more", + "next_cursor" + ] }, - "PackageOperationStep": { + "Notification": { "type": "object", "properties": { - "name": { + "id": { "type": "string", - "description": "User-visible milestone name." + "minLength": 1, + "maxLength": 54 }, - "status": { + "type": { "type": "string", - "enum": [ - "pending", - "running", - "completed", - "failed", - "skipped" - ], - "description": "Step lifecycle state." + "example": "machine_expiry" }, - "execution_type": { + "resource_type": { + "type": "string", + "example": "machine" + }, + "resource_id": { + "type": "string" + }, + "title": { + "type": "string", + "nullable": true + }, + "body": { "type": "string", + "nullable": true + }, + "severity": { + "type": "string", + "nullable": true, "enum": [ - "system", - "user", - "approval", - "skipped" + "info", + "warning", + "critical", + null ], - "description": "Step execution kind. `user`/`approval` mean the workflow is blocked on a human action. Internal bookkeeping steps are filtered from public responses." + "description": "Severity level surfaced to UI indicators." }, - "started_at": { + "context": { + "type": "object", + "nullable": true, + "additionalProperties": { + "type": "string" + } + }, + "read_at": { "type": "integer", + "nullable": true, "minimum": 0, - "description": "Unix timestamp (seconds)" + "description": "Unix timestamp (seconds) when read, null if unread" }, - "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" } }, "required": [ - "name", - "status", - "execution_type", - "started_at", - "completed_at", - "error_message", - "retryable", - "skippable" + "id", + "type", + "resource_type", + "resource_id", + "title", + "body", + "severity", + "context", + "read_at", + "created_at" ] }, - "CreatePackageBody": { + "UnreadCount": { "type": "object", "properties": { - "name": { - "type": "string", - "minLength": 1, - "maxLength": 120 - }, - "sources": { + "count": { + "type": "number" + } + }, + "required": [ + "count" + ] + }, + "QuotaInfoList": { + "type": "object", + "properties": { + "data": { "type": "array", "items": { - "$ref": "#/components/schemas/CreatePackageHelmSource" - }, - "minItems": 1, - "maxItems": 1 + "$ref": "#/components/schemas/QuotaInfo" + } + }, + "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": [ - "name", - "sources" - ], - "additionalProperties": false + "data", + "has_more", + "next_cursor" + ] }, - "CreatePackageHelmSource": { + "QuotaInfo": { "type": "object", "properties": { - "kind": { + "metric": { + "type": "string", + "example": "compute/machines", + "description": "Metric: service/resource" + }, + "type": { "type": "string", "enum": [ - "helm" - ] + "allocation", + "rate", + "concurrency" + ], + "description": "Allocation = max owned, rate = max per time window, concurrency = max in-flight.", + "example": "allocation" }, - "repo_url": { + "display_name": { "type": "string", - "minLength": 1, - "maxLength": 2048, - "pattern": "^oci:\\/\\/" + "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" }, - "chart": { - "type": "string", - "maxLength": 255 + "limit": { + "type": "number", + "example": 1 }, - "target_revision": { - "type": "string", - "minLength": 1, - "maxLength": 256 + "usage": { + "type": "number", + "example": 0 }, - "path": { - "type": "string", - "maxLength": 2048 + "remaining": { + "type": "number", + "example": 1 }, - "values": { - "type": "object", - "additionalProperties": { - "nullable": true - } + "resets_at": { + "type": "integer", + "minimum": 0, + "description": "For rate quotas: Unix timestamp (seconds) reset time" } }, "required": [ - "kind", - "repo_url", - "target_revision" - ], - "additionalProperties": false + "metric", + "type", + "display_name", + "unit", + "limit", + "usage", + "remaining" + ] }, - "WorkspaceList": { + "RegionList": { "type": "object", "properties": { "data": { "type": "array", "items": { - "$ref": "#/components/schemas/Workspace" + "$ref": "#/components/schemas/Region" } }, "has_more": { @@ -8732,84 +23199,49 @@ "next_cursor" ] }, - "Workspace": { + "Region": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, - "maxLength": 53, - "description": "Workspace ID", - "example": "ws_j572abc123def456" + "maxLength": 54 }, "name": { "type": "string", - "description": "Display name", - "example": "Acme Research" + "example": "us-east-1" }, - "slug": { + "icon": { "type": "string", - "description": "URL-safe workspace slug" - }, - "plan": { - "type": "object", - "properties": { - "tier": { - "type": "string" - }, - "billed_by": { - "type": "string", - "enum": [ - "platform", - "seller" - ] - } - }, - "required": [ - "tier", - "billed_by" - ] + "nullable": true, + "description": "Icon URL" }, - "workspace_class": { + "workspace_id": { "type": "string", - "enum": [ - "standard", - "platform", - "sandbox" - ] + "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" } }, "required": [ "id", "name", - "slug", - "plan", - "workspace_class", - "created_at", - "updated_at", - "etag" + "icon", + "workspace_id", + "created_at" ] }, - "WorkspaceMemberList": { + "DashboardRegionList": { "type": "object", "properties": { "data": { "type": "array", "items": { - "$ref": "#/components/schemas/WorkspaceMember" + "$ref": "#/components/schemas/DashboardRegion" } }, "has_more": { @@ -8828,181 +23260,84 @@ "next_cursor" ] }, - "WorkspaceMember": { - "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" + "DashboardRegion": { + "allOf": [ + { + "$ref": "#/components/schemas/Region" }, - "role": { - "type": "string", - "enum": [ - "owner", - "admin", - "member" + { + "type": "object", + "properties": { + "cluster_pool_health": { + "$ref": "#/components/schemas/ClusterPoolHealth" + } + }, + "required": [ + "cluster_pool_health" ] - }, - "joined_at": { - "type": "string", - "format": "date-time", - "description": "ISO 8601 join timestamp" } - }, - "required": [ - "id", - "user_id", - "role", - "joined_at" ] }, - "WorkspaceSubscription": { + "ClusterPoolHealth": { "type": "object", "properties": { - "id": { - "type": "string" - }, - "workspace_id": { + "region_id": { "type": "string", "minLength": 1, - "maxLength": 53 - }, - "tier": { - "type": "string" + "maxLength": 54 }, - "status": { - "type": "string" + "target_size": { + "type": "number" }, - "cancellation_scheduled": { + "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)" - } - }, - "required": [ - "id", - "workspace_id", - "tier", - "status", - "cancellation_scheduled", - "current_period_end", - "billed_by", - "created_at" - ] - }, - "WorkspaceAccessState": { - "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 + "available": { + "type": "number" }, - "accessible": { - "type": "boolean" + "provisioning": { + "type": "number" }, - "reason": { - "type": "string", - "nullable": true, - "enum": [ - "payment_grace", - "restricted", - "suspended", - "ended", - "reactivating", - null - ] + "allocation_requests": { + "type": "number" }, - "reconciliation_status": { - "type": "string", - "enum": [ - "pending", - "reconciled", - "failed" - ] + "allocated_last_24h": { + "type": "number" }, - "payment_grace_ends_at": { - "type": "integer", - "nullable": true, - "minimum": 0, - "description": "Unix timestamp (seconds)" + "deleted_last_24h": { + "type": "number" }, - "restricted_at": { - "type": "integer", - "nullable": true, - "minimum": 0, - "description": "Unix timestamp (seconds)" + "failed_last_24h": { + "type": "number" }, - "suspend_at": { + "last_refill_at": { "type": "integer", - "nullable": true, "minimum": 0, "description": "Unix timestamp (seconds)" }, - "ended_at": { - "type": "integer", - "nullable": true, - "minimum": 0, - "description": "Unix timestamp (seconds)" + "last_error": { + "type": "string" } }, "required": [ - "workspace_id", - "status", - "access_version", - "accessible", - "reason", - "reconciliation_status", - "payment_grace_ends_at", - "restricted_at", - "suspend_at", - "ended_at" + "region_id", + "target_size", + "enabled", + "available", + "provisioning", + "allocation_requests", + "allocated_last_24h", + "deleted_last_24h", + "failed_last_24h" ] }, - "SubscriptionChangeRequestList": { + "RegistryCredentialList": { "type": "object", "properties": { "data": { "type": "array", "items": { - "$ref": "#/components/schemas/SubscriptionChangeRequest" + "$ref": "#/components/schemas/RegistryCredential" } }, "has_more": { @@ -9021,7 +23356,7 @@ "next_cursor" ] }, - "SubscriptionChangeRequest": { + "RegistryCredential": { "type": "object", "properties": { "id": { @@ -9029,114 +23364,250 @@ "minLength": 1, "maxLength": 55 }, - "workspace_id": { + "name": { "type": "string", - "minLength": 1, - "maxLength": 53 - }, - "requested_tier": { - "type": "string" + "example": "GitHub Container Registry" }, - "status": { - "type": "string" + "registry_url": { + "type": "string", + "example": "ghcr.io" }, - "effective_at": { + "type": { "type": "string", - "nullable": true + "enum": [ + "basic", + "token", + "oauth" + ], + "description": "Authentication scheme used to talk to the upstream registry." + }, + "is_active": { + "type": "boolean", + "description": "Whether the credential is active" }, "created_at": { "type": "integer", "minimum": 0, "description": "Unix timestamp (seconds)" + }, + "last_used_at": { + "type": "integer", + "nullable": true, + "minimum": 0, + "description": "Unix timestamp (seconds), null if never used" } }, "required": [ "id", - "workspace_id", - "requested_tier", - "status", - "effective_at", - "created_at" + "name", + "registry_url", + "type", + "is_active", + "created_at", + "last_used_at" ] }, - "CreatedApiToken": { + "RegistryStats": { "type": "object", "properties": { - "id": { - "type": "string", - "minLength": 1, - "maxLength": 54 + "total_pulls": { + "type": "number" }, - "workspace_id": { - "type": "string", - "minLength": 1, - "maxLength": 53 + "successful_pulls": { + "type": "number" }, - "name": { - "type": "string" + "failed_pulls": { + "type": "number" }, - "token": { - "type": "string", - "description": "The full token. This is shown only once - store it securely.", - "example": "sk_akua_a3b2c4d5e6f7g8h9i0j1k2l3m4n5o6p7" + "success_rate": { + "type": "number" + }, + "auth_successes": { + "type": "number" + }, + "auth_failures": { + "type": "number" + }, + "by_registry": { + "type": "array", + "items": { + "type": "object", + "properties": { + "registry_url": { + "type": "string" + }, + "pulls": { + "type": "number" + }, + "failures": { + "type": "number" + } + }, + "required": [ + "registry_url", + "pulls", + "failures" + ] + } + }, + "latency": { + "type": "object", + "properties": { + "avg": { + "type": "number", + "nullable": true + }, + "p95": { + "type": "number", + "nullable": true + } + }, + "required": [ + "avg", + "p95" + ] } }, "required": [ - "id", - "workspace_id", - "name", - "token" + "total_pulls", + "successful_pulls", + "failed_pulls", + "success_rate", + "auth_successes", + "auth_failures", + "by_registry", + "latency" ] }, - "CreateApiTokenRequest": { + "RegistryActivityResponse": { "type": "object", "properties": { - "name": { + "data": { + "type": "array", + "items": { + "$ref": "#/components/schemas/RegistryActivityBucket" + } + } + }, + "required": [ + "data" + ] + }, + "RegistryActivityBucket": { + "type": "object", + "properties": { + "timestamp": { + "type": "number", + "description": "Unix timestamp in milliseconds." + }, + "success": { + "type": "number" + }, + "failed": { + "type": "number" + } + }, + "required": [ + "timestamp", + "success", + "failed" + ] + }, + "RegistryAuditLogList": { + "type": "object", + "properties": { + "data": { + "type": "array", + "items": { + "$ref": "#/components/schemas/RegistryAuditLog" + } + } + }, + "required": [ + "data" + ] + }, + "RegistryAuditLog": { + "type": "object", + "properties": { + "id": { "type": "string", "minLength": 1, - "maxLength": 100, - "description": "Human-readable name for the token", - "example": "My CLI token" + "maxLength": 54 }, - "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 + "timestamp": { + "type": "number", + "description": "Unix timestamp in milliseconds." + }, + "operation": { + "type": "string", + "enum": [ + "pull_manifest", + "pull_blob", + "pull_failed", + "auth_success", + "auth_failed" + ] + }, + "registry_url": { + "type": "string" + }, + "repository": { + "type": "string" + }, + "reference": { + "type": "string", + "nullable": true + }, + "success": { + "type": "boolean" + }, + "install_name": { + "type": "string", + "nullable": true } }, "required": [ - "name" - ], - "additionalProperties": false + "id", + "timestamp", + "operation", + "registry_url", + "repository", + "reference", + "success", + "install_name" + ] }, - "ApiTokenList": { + "RegistryErrorList": { "type": "object", "properties": { "data": { "type": "array", "items": { - "$ref": "#/components/schemas/ApiToken" + "$ref": "#/components/schemas/RegistryError" } + } + }, + "required": [ + "data" + ] + }, + "RegistryError": { + "type": "object", + "properties": { + "message": { + "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." + "count": { + "type": "number" } }, "required": [ - "data", - "has_more", - "next_cursor" + "message", + "count" ] }, - "ApiToken": { + "CreateRepositoryChangeRequestResponse": { "type": "object", "properties": { "id": { @@ -9144,456 +23615,351 @@ "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 }, - "name": { + "parent_repository_id": { "type": "string", - "example": "My CLI token" + "minLength": 1, + "maxLength": 55 }, - "prefix": { + "fork_repository_id": { "type": "string", - "example": "sk_akua_a3b2", - "description": "Short identifier prefix of the full token, for display only." + "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, + "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", "minimum": 0, "description": "Unix timestamp (seconds)" }, - "last_used_at": { + "updated_at": { "type": "integer", - "nullable": true, "minimum": 0, - "description": "Unix timestamp (seconds) of last use, or null if never used" + "description": "Unix timestamp (seconds)" }, "expires_at": { "type": "integer", - "nullable": true, "minimum": 0, - "description": "Unix timestamp (seconds) when the token expires, or null if never" + "description": "Unix timestamp (seconds)" + }, + "rejection_reason": { + "type": "string", + "nullable": true + }, + "etag": { + "type": "string" } }, "required": [ "id", + "html_url", "workspace_id", - "name", - "prefix", + "parent_repository_id", + "fork_repository_id", + "state", + "change_type", + "created_by_type", + "created_by_id", + "remediation_evidence", "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" + "updated_at", + "expires_at", + "rejection_reason", + "etag" ] }, - "Repository": { + "CreateRepositoryChangeRequestBody": { "oneOf": [ { "type": "object", "properties": { - "id": { - "type": "string", - "minLength": 1, - "maxLength": 55 - }, - "name": { - "type": "string" - }, - "workspace_id": { + "parent_repository_id": { "type": "string", "minLength": 1, - "maxLength": 53 - }, - "created_at": { - "type": "integer", - "minimum": 0, - "description": "Unix timestamp (seconds)" + "maxLength": 55, + "description": "Repository that will receive the accepted change request." }, - "updated_at": { + "expires_at_seconds": { "type": "integer", "minimum": 0, - "description": "Unix timestamp (seconds)" - }, - "etag": { - "type": "string" - }, - "reconciling": { - "type": "boolean" + "exclusiveMinimum": true, + "description": "Seconds until the repository change request expires." }, - "purpose": { + "kind": { "type": "string", "enum": [ - "deploy" + "user" ] - }, - "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" - ] + "parent_repository_id", + "kind" + ], + "additionalProperties": false }, { "type": "object", "properties": { - "id": { - "type": "string", - "minLength": 1, - "maxLength": 55 - }, - "name": { - "type": "string" - }, - "workspace_id": { + "parent_repository_id": { "type": "string", "minLength": 1, - "maxLength": 53 - }, - "created_at": { - "type": "integer", - "minimum": 0, - "description": "Unix timestamp (seconds)" + "maxLength": 55, + "description": "Repository that will receive the accepted change request." }, - "updated_at": { + "expires_at_seconds": { "type": "integer", "minimum": 0, - "description": "Unix timestamp (seconds)" - }, - "etag": { - "type": "string" - }, - "reconciling": { - "type": "boolean" + "exclusiveMinimum": true, + "description": "Seconds until the repository change request expires." }, - "purpose": { + "kind": { "type": "string", "enum": [ - "package" + "wizard" ] - }, - "package_id": { - "type": "string", - "minLength": 1, - "maxLength": 54 } }, "required": [ - "id", - "name", - "workspace_id", - "created_at", - "updated_at", - "etag", - "reconciling", - "purpose", - "package_id" - ] + "parent_repository_id", + "kind" + ], + "additionalProperties": false }, { "type": "object", "properties": { - "id": { - "type": "string", - "minLength": 1, - "maxLength": 55 - }, - "name": { - "type": "string" - }, - "workspace_id": { + "parent_repository_id": { "type": "string", "minLength": 1, - "maxLength": 53 - }, - "created_at": { - "type": "integer", - "minimum": 0, - "description": "Unix timestamp (seconds)" + "maxLength": 55, + "description": "Repository that will receive the accepted change request." }, - "updated_at": { + "expires_at_seconds": { "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 - }, - "GithubRepoList": { - "type": "object", - "properties": { - "data": { - "type": "array", - "items": { - "$ref": "#/components/schemas/GithubRepo" - } - } - }, - "required": [ - "data" - ] - }, - "GithubRepo": { - "type": "object", - "properties": { - "id": { - "type": "number" - }, - "name": { - "type": "string" - }, - "full_name": { - "type": "string" - }, - "archived": { - "type": "boolean" - }, - "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" + "exclusiveMinimum": true, + "description": "Seconds until the repository change request expires." }, - "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", - "items": { - "$ref": "#/components/schemas/GithubAppInstallation" - } - } - }, - "required": [ - "data" - ] - }, - "GithubAppInstallation": { - "type": "object", - "properties": { - "installation_id": { - "type": "integer", - "minimum": 0, - "exclusiveMinimum": true - }, - "workspace_id": { - "type": "string", - "minLength": 1, - "maxLength": 53 - }, - "account": { - "type": "object", - "properties": { - "type": { + "kind": { "type": "string", "enum": [ - "User", - "Organization" - ] - }, - "login": { - "type": "string" + "agent" + ], + "description": "Agent actor creating the change request." }, - "id": { - "type": "number" + "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": [ - "type", - "login", - "id" - ] + "parent_repository_id", + "kind", + "agent_id", + "remediation_evidence" + ], + "additionalProperties": false } - }, - "required": [ - "installation_id", - "workspace_id", - "account" ] }, - "GithubWorkflowPrGet": { + "CreateRepositoryChangeRequestTokenResponse": { "type": "object", "properties": { - "data": { - "$ref": "#/components/schemas/GithubWorkflowPr" + "repository_change_request_id": { + "type": "string", + "minLength": 1, + "maxLength": 54 + }, + "fork_remote_url": { + "type": "string", + "format": "uri" + }, + "fork_write_token": { + "type": "string" + }, + "expires_at": { + "type": "integer", + "minimum": 0, + "description": "Unix timestamp (seconds)" } }, "required": [ - "data" + "repository_change_request_id", + "fork_remote_url", + "fork_write_token", + "expires_at" ] }, - "GithubWorkflowPr": { + "CreateRepositoryChangeRequestTokenBody": { "type": "object", - "nullable": true, "properties": { - "pr_id": { - "type": "integer", - "minimum": 0, - "exclusiveMinimum": true - }, - "pr_url": { - "type": "string", - "format": "uri" - }, - "status": { + "scope": { "type": "string", "enum": [ - "open", - "merged", - "closed", - "draft" - ] + "read", + "write" + ], + "default": "write" + }, + "expires_in_seconds": { + "type": "integer", + "minimum": 0, + "exclusiveMinimum": true, + "maximum": 3600, + "description": "Seconds until the fork write token expires. Maximum is one hour." } }, - "required": [ - "pr_id", - "pr_url", - "status" - ] + "additionalProperties": false }, - "GithubWorkflowRunList": { + "RepositoryChangeRequestList": { "type": "object", "properties": { "data": { "type": "array", "items": { - "$ref": "#/components/schemas/GithubWorkflowRun" + "$ref": "#/components/schemas/RepositoryChangeRequest" } }, "has_more": { @@ -9612,7 +23978,7 @@ "next_cursor" ] }, - "GithubWorkflowRun": { + "RepositoryChangeRequest": { "type": "object", "properties": { "id": { @@ -9620,455 +23986,230 @@ "minLength": 1, "maxLength": 54 }, - "custom": { - "type": "object", - "properties": { - "image": { - "type": "string" - }, - "sent_at": { - "type": "number" - } - }, - "required": [ - "image", - "sent_at" + "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": { + "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" ] }, - "installation": { - "type": "object", - "properties": { - "id": { - "type": "number" - } - }, - "required": [ - "id" + "created_by_type": { + "type": "string", + "enum": [ + "user", + "wizard", + "agent" ] }, - "workflow_run": { + "created_by_id": { + "type": "string" + }, + "remediation_evidence": { "type": "object", + "nullable": true, "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": { + "summary": { "type": "string", - "enum": [ - "queued", - "in_progress", - "completed", - "action_required", - "cancelled", - "failure", - "neutral", - "skipped", - "stale", - "success", - "timed_out", - "requested", - "waiting", - "pending" - ] + "minLength": 1, + "maxLength": 2000 }, - "conclusion": { + "likely_fix": { "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" - } - }, - "required": [ - "login", - "id" - ] + "minLength": 1, + "maxLength": 2000 }, - "referenced_workflows": { + "resource_refs": { "type": "array", "items": { "type": "object", "properties": { - "path": { - "type": "string" - }, - "sha": { - "type": "string" + "resource": { + "type": "string", + "minLength": 1, + "maxLength": 120 }, - "ref": { - "type": "string" + "id": { + "type": "string", + "minLength": 1, + "maxLength": 200 } }, "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": [ - "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": { - "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" - } + "resource", + "id" + ], + "additionalProperties": false }, - "required": [ - "login", - "id", - "avatar_url", - "html_url" - ] - }, - "name": { - "type": "string" - }, - "full_name": { - "type": "string" - }, - "html_url": { - "type": "string", - "format": "uri" + "minItems": 1, + "maxItems": 20 } }, "required": [ - "id", - "owner", - "name", - "full_name", - "html_url" - ] - } - }, - "required": [ - "id", - "installation", - "workflow_run", - "repository" - ] - }, - "GithubPackagePermissions": { - "type": "object", - "properties": { - "has_warning": { - "type": "boolean" + "summary", + "likely_fix", + "resource_refs" + ], + "additionalProperties": false }, - "warning": { - "type": "string" + "created_at": { + "type": "integer", + "minimum": 0, + "description": "Unix timestamp (seconds)" }, - "fix_url": { - "type": "string" - } - }, - "required": [ - "has_warning" - ] - }, - "GithubCheckPackagePermissionsBody": { - "type": "object", - "properties": { - "repository": { - "type": "object", - "properties": { - "id": { - "type": "number" - }, - "owner": { - "type": "string" - }, - "name": { - "type": "string" - } - }, - "required": [ - "id", - "owner", - "name" - ] + "updated_at": { + "type": "integer", + "minimum": 0, + "description": "Unix timestamp (seconds)" }, - "installation_id": { + "expires_at": { "type": "integer", "minimum": 0, - "exclusiveMinimum": true + "description": "Unix timestamp (seconds)" + }, + "rejection_reason": { + "type": "string", + "nullable": true + }, + "etag": { + "type": "string" } }, "required": [ - "repository", - "installation_id" - ], - "additionalProperties": false + "id", + "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" + ] }, - "GithubWorkflowPrCreated": { + "AcceptRepositoryChangeRequestResponse": { "type": "object", "properties": { - "pr_id": { - "type": "integer", - "minimum": 0, - "exclusiveMinimum": true - }, - "pr_url": { + "repository_change_request_id": { "type": "string", - "format": "uri" + "minLength": 1, + "maxLength": 54 }, - "status": { + "operation_id": { "type": "string", - "enum": [ - "open" - ] + "minLength": 1, + "maxLength": 53 + }, + "accepted_at": { + "type": "integer", + "minimum": 0, + "description": "Unix timestamp (seconds)" } }, "required": [ - "pr_id", - "pr_url", - "status" + "repository_change_request_id", + "operation_id", + "accepted_at" ] }, - "GithubCreateWorkflowPrBody": { + "RejectRepositoryChangeRequestResponse": { "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" - } - } + "repository_change_request_id": { + "type": "string", + "minLength": 1, + "maxLength": 54 }, - "installation_id": { + "rejected_at": { "type": "integer", "minimum": 0, - "exclusiveMinimum": true + "description": "Unix timestamp (seconds)" } }, "required": [ - "repository", - "build_settings", - "installation_id" - ], - "additionalProperties": false + "repository_change_request_id", + "rejected_at" + ] }, - "GithubVerifyInstallationResponse": { + "RejectRepositoryChangeRequestBody": { "type": "object", "properties": { - "redirect_url": { - "type": "string" + "rejection_reason": { + "type": "string", + "minLength": 1, + "maxLength": 2000, + "description": "Reason shown in audit logs and review UI." } }, "required": [ - "redirect_url" - ] + "rejection_reason" + ], + "additionalProperties": false }, - "GithubVerifyInstallationBody": { + "WithdrawRepositoryChangeRequestResponse": { "type": "object", "properties": { - "installation_id": { - "type": "integer", - "minimum": 0, - "exclusiveMinimum": true - }, - "code": { + "repository_change_request_id": { "type": "string", - "minLength": 1 + "minLength": 1, + "maxLength": 54 }, - "state": { - "type": "string", - "minLength": 1 + "withdrawn_at": { + "type": "integer", + "minimum": 0, + "description": "Unix timestamp (seconds)" } }, "required": [ - "installation_id", - "code", - "state" - ], - "additionalProperties": false + "repository_change_request_id", + "withdrawn_at" + ] }, - "Secret": { + "Agent": { "type": "object", "properties": { "id": { @@ -10076,90 +24217,71 @@ "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": { + "organization_id": { "type": "string", + "nullable": true, "minLength": 1, - "maxLength": 200 + "maxLength": 54 }, - "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" + "name": { + "type": "string" }, "description": { "type": "string", - "maxLength": 500 + "nullable": true }, - "labels": { - "type": "object", - "additionalProperties": { - "type": "string", - "maxLength": 200 - } + "instructions": { + "type": "string" }, "state": { "type": "string", "enum": [ - "active", - "soft_deleted" + "ENABLED", + "ARCHIVED" ] }, - "validation": { - "$ref": "#/components/schemas/SecretValidation" - }, - "mime_type": { + "origin": { "type": "string", - "maxLength": 100 + "enum": [ + "PLATFORM", + "USER", + "SYSTEM" + ] }, - "version_aliases": { - "type": "object", - "additionalProperties": { - "type": "integer", - "minimum": 0, - "exclusiveMinimum": true + "capabilities": { + "type": "array", + "items": { + "type": "string", + "enum": [ + "CHAT", + "CODING", + "AMBIENT" + ] } }, - "version_count": { - "type": "integer", - "minimum": 0 - }, - "enabled_version_count": { - "type": "integer", - "minimum": 0 + "ambient": { + "$ref": "#/components/schemas/AgentAmbientConfig" }, - "created_at": { - "type": "integer", - "minimum": 0, - "description": "Unix timestamp (seconds)" + "model_policy": { + "$ref": "#/components/schemas/AgentModelPolicy" }, - "updated_at": { - "type": "integer", - "minimum": 0, - "description": "Unix timestamp (seconds)" + "created_by": { + "type": "string" }, - "deleted_at": { - "type": "integer", - "minimum": 0, - "description": "Unix timestamp (seconds)" + "usage_summary": { + "$ref": "#/components/schemas/AgentUsageSummary" }, - "purge_at": { + "created_at": { "type": "integer", "minimum": 0, "description": "Unix timestamp (seconds)" }, - "expire_time": { + "updated_at": { "type": "integer", "minimum": 0, "description": "Unix timestamp (seconds)" @@ -10170,359 +24292,374 @@ }, "required": [ "id", - "html_url", "workspace_id", + "organization_id", "name", - "kind", + "description", + "instructions", "state", - "validation", - "version_count", - "enabled_version_count", + "origin", + "capabilities", + "ambient", + "model_policy", + "created_by", + "usage_summary", "created_at", "updated_at", "etag" ] }, - "SecretValidation": { + "AgentAmbientConfig": { "type": "object", "nullable": true, "properties": { - "state": { + "enabled": { + "type": "boolean" + }, + "policy": { + "$ref": "#/components/schemas/AgentAmbientPolicy" + }, + "triggers": { + "type": "array", + "items": { + "$ref": "#/components/schemas/AgentAmbientTrigger" + }, + "maxItems": 50 + } + }, + "required": [ + "enabled", + "triggers" + ] + }, + "AgentAmbientPolicy": { + "type": "object", + "properties": { + "remediation_mode": { "type": "string", "enum": [ - "unspecified", - "valid", - "invalid" + "READ_ONLY", + "APPROVAL_GATED" ] }, - "validated_at": { + "allowed_resource_scopes": { + "type": "array", + "items": { + "$ref": "#/components/schemas/AgentAmbientResourceScope" + }, + "maxItems": 100 + }, + "max_spend_cents_per_trigger": { "type": "integer", - "minimum": 0, - "description": "Unix timestamp (seconds)" + "minimum": 0 + } + }, + "required": [ + "remediation_mode", + "allowed_resource_scopes" + ] + }, + "AgentAmbientResourceScope": { + "type": "object", + "properties": { + "type": { + "type": "string", + "minLength": 1, + "maxLength": 120 }, - "error": { - "type": "string" + "id": { + "type": "string", + "minLength": 1, + "maxLength": 200 } }, "required": [ - "state", - "validated_at" - ], - "description": "Server-managed validation telemetry. Populated for credential-typed secrets; null otherwise. OUTPUT_ONLY — clients cannot set this on create/update." + "type" + ] }, - "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 + "AgentAmbientTrigger": { + "type": "object", + "properties": { + "trigger_id": { + "type": "string", + "minLength": 1, + "maxLength": 120 }, - { - "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": { + "type": "string", + "enum": [ + "INSTALL_STATE", + "CLUSTER_DEGRADATION", + "SECURITY_FINDING", + "QUOTA_PRESSURE", + "COST_ANOMALY", + "MANUAL_TEST" + ] }, - { - "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 + "state": { + "type": "string", + "enum": [ + "ENABLED", + "DISABLED" + ] }, - { - "type": "object", - "properties": { - "name": { - "type": "string", - "minLength": 1, - "maxLength": 200 - }, - "description": { - "type": "string", - "maxLength": 500 - }, - "labels": { + "severity_min": { + "type": "string", + "enum": [ + "LOW", + "MEDIUM", + "HIGH", + "CRITICAL" + ] + }, + "runtime_hint": { + "type": "string", + "enum": [ + "AUTO", + "CODE_MODE", + "RETAINED_RUNTIME" + ] + }, + "cooldown_seconds": { + "type": "integer", + "minimum": 0, + "exclusiveMinimum": true + }, + "relationship_scope": { + "anyOf": [ + { "type": "object", - "additionalProperties": { - "type": "string", - "maxLength": 200 - } - }, - "kind": { - "type": "string", - "enum": [ - "cloud_provider/azure" + "properties": { + "type": { + "type": "string", + "enum": [ + "WORKSPACE" + ] + } + }, + "required": [ + "type" ] }, - "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" + "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" ] - }, - "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": { + "resource_filters": { + "type": "array", + "items": { + "type": "object", + "properties": { + "type": { "type": "string", + "minLength": 1, + "maxLength": 120 + }, + "id": { + "type": "string", + "minLength": 1, "maxLength": 200 } }, - "kind": { - "type": "string", - "enum": [ - "cloudflare_api" - ] - }, - "value": { - "type": "string", - "minLength": 1 - } + "required": [ + "type", + "id" + ] }, - "required": [ - "name", - "kind", - "value" - ], - "additionalProperties": false + "maxItems": 50 }, - { + "quiet_hours": { "type": "object", "properties": { - "name": { + "timezone": { "type": "string", "minLength": 1, - "maxLength": 200 - }, - "description": { - "type": "string", - "maxLength": 500 - }, - "labels": { - "type": "object", - "additionalProperties": { - "type": "string", - "maxLength": 200 - } + "maxLength": 120 }, - "kind": { + "start": { "type": "string", - "enum": [ - "webhook_signing" - ] + "pattern": "^\\d{2}:\\d{2}$" }, - "value": { + "end": { "type": "string", - "minLength": 16 + "pattern": "^\\d{2}:\\d{2}$" } }, "required": [ - "name", - "kind", - "value" - ], - "additionalProperties": false + "timezone", + "start", + "end" + ] + } + }, + "required": [ + "trigger_id", + "type", + "state", + "runtime_hint" + ] + }, + "AgentModelPolicy": { + "type": "object", + "properties": { + "default_model": { + "type": "string", + "minLength": 1, + "maxLength": 120 }, - { - "type": "object", - "properties": { - "name": { - "type": "string", - "minLength": 1, - "maxLength": 200 - }, - "description": { - "type": "string", - "maxLength": 500 - }, - "labels": { - "type": "object", - "additionalProperties": { + "billing_mode": { + "type": "string", + "enum": [ + "PLATFORM_SUBSCRIPTION", + "PLATFORM_API", + "WORKSPACE_BYOK" + ] + }, + "credential_secret_id": { + "type": "string", + "nullable": true, + "minLength": 1, + "maxLength": 54 + }, + "allowed_models": { + "type": "array", + "items": { + "type": "string", + "minLength": 1, + "maxLength": 120 + }, + "minItems": 1, + "maxItems": 50 + }, + "severity_model_overrides": { + "type": "array", + "items": { + "type": "object", + "properties": { + "severity": { "type": "string", - "maxLength": 200 + "enum": [ + "LOW", + "MEDIUM", + "HIGH", + "CRITICAL" + ] + }, + "model": { + "type": "string", + "minLength": 1, + "maxLength": 120 } }, - "kind": { - "type": "string", - "enum": [ - "generic" - ] - }, - "value": { - "type": "string", - "minLength": 1 - } + "required": [ + "severity", + "model" + ] }, - "required": [ - "name", - "kind", - "value" - ], - "additionalProperties": false + "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": [ + "default_model", + "billing_mode", + "credential_secret_id", + "allowed_models" ] }, - "SecretList": { + "AgentUsageSummary": { + "type": "object", + "properties": { + "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": [ + "provider_cost_cents", + "provider_token_count", + "runtime_compute_seconds", + "runtime_storage_gb_hours", + "mcp_call_count", + "api_call_count", + "ambient_trigger_count" + ] + }, + "AgentList": { "type": "object", "properties": { "data": { "type": "array", "items": { - "$ref": "#/components/schemas/Secret" + "$ref": "#/components/schemas/Agent" } }, "has_more": { @@ -10541,113 +24678,224 @@ "next_cursor" ] }, - "UpdateSecretBody": { + "AgentSkillList": { "type": "object", "properties": { - "name": { + "data": { + "type": "array", + "items": { + "$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", + "has_more", + "next_cursor" + ] + }, + "AgentSkill": { + "type": "object", + "properties": { + "id": { "type": "string", "minLength": 1, - "maxLength": 200 + "maxLength": 54 + }, + "workspace_id": { + "type": "string", + "minLength": 1, + "maxLength": 53 + }, + "name": { + "type": "string" + }, + "version": { + "type": "string" }, "description": { + "type": "string" + }, + "state": { "type": "string", - "maxLength": 500 + "enum": [ + "PUBLISHED", + "ARCHIVED" + ] }, - "labels": { - "type": "object", - "additionalProperties": { + "required_grants": { + "type": "array", + "items": { + "type": "object", + "properties": { + "resource": { + "type": "string" + }, + "actions": { + "type": "array", + "items": { + "type": "string" + } + } + }, + "required": [ + "resource", + "actions" + ] + } + }, + "supported_capabilities": { + "type": "array", + "items": { "type": "string", - "maxLength": 200 + "enum": [ + "CHAT", + "CODING", + "AMBIENT" + ] } }, - "mime_type": { - "type": "string", - "maxLength": 100 + "created_at": { + "type": "integer", + "minimum": 0, + "description": "Unix timestamp (seconds)" }, - "version_aliases": { - "type": "object", - "additionalProperties": { - "type": "integer", - "minimum": 0, - "exclusiveMinimum": true - } - } - }, - "additionalProperties": false - }, - "ValidateProviderTokenResult": { - "type": "object", - "properties": { - "valid": { - "type": "boolean", - "description": "Whether the token authenticated successfully." + "updated_at": { + "type": "integer", + "minimum": 0, + "description": "Unix timestamp (seconds)" }, - "error": { - "type": "string", - "description": "Human-readable reason when `valid` is false." + "etag": { + "type": "string" } }, "required": [ - "valid" + "id", + "workspace_id", + "name", + "version", + "description", + "state", + "required_grants", + "supported_capabilities", + "created_at", + "updated_at", + "etag" ] }, - "ValidateProviderTokenBody": { + "AgentTemplateList": { "type": "object", "properties": { - "provider": { - "type": "string", - "enum": [ - "hcloud" - ], - "description": "Cloud provider to validate the token against." + "data": { + "type": "array", + "items": { + "$ref": "#/components/schemas/AgentTemplate" + } }, - "value": { + "has_more": { + "type": "boolean", + "description": "True if more items exist after this page." + }, + "next_cursor": { "type": "string", - "minLength": 1, - "description": "The provider API token to probe. Consumed, never stored." + "nullable": true, + "description": "Opaque cursor for the next page, or null if no more pages." } }, "required": [ - "provider", - "value" + "data", + "has_more", + "next_cursor" ] }, - "SecretVersion": { + "AgentTemplate": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, - "maxLength": 55 + "maxLength": 56 }, - "secret_id": { - "type": "string", - "minLength": 1, - "maxLength": 54 + "name": { + "type": "string" + }, + "description": { + "type": "string" }, - "version_number": { - "type": "integer", - "minimum": 0, - "exclusiveMinimum": true + "instructions": { + "type": "string" }, "state": { "type": "string", "enum": [ - "enabled", - "disabled", - "destroyed" + "PUBLISHED" ] }, - "comment": { - "type": "string", - "maxLength": 200 + "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" + }, + "remediation_policy": { + "$ref": "#/components/schemas/AgentTemplateRemediationPolicy" + }, + "grants": { + "type": "array", + "items": { + "type": "object", + "properties": { + "resource": { + "type": "string" + }, + "actions": { + "type": "array", + "items": { + "type": "string" + } + } + }, + "required": [ + "resource", + "actions" + ] + } }, "created_at": { "type": "integer", "minimum": 0, "description": "Unix timestamp (seconds)" }, - "destroyed_at": { + "updated_at": { "type": "integer", "minimum": 0, "description": "Unix timestamp (seconds)" @@ -10658,379 +24906,378 @@ }, "required": [ "id", - "secret_id", - "version_number", + "name", + "description", + "instructions", "state", + "capabilities", + "ambient", + "trigger_filters", + "model_policy", + "runtime_policy", + "remediation_policy", + "grants", "created_at", + "updated_at", "etag" ] }, - "CreateSecretVersionBody": { + "AgentTemplateTriggerFilter": { "type": "object", "properties": { - "value": { + "type": { "type": "string", - "minLength": 1 + "enum": [ + "INSTALL_STATE", + "CLUSTER_DEGRADATION", + "SECURITY_FINDING", + "QUOTA_PRESSURE", + "COST_ANOMALY", + "MANUAL_TEST" + ] }, - "comment": { - "type": "string", - "maxLength": 200 - } - }, - "required": [ - "value" - ], - "additionalProperties": false - }, - "SecretVersionList": { - "type": "object", - "properties": { - "data": { + "resource_types": { "type": "array", "items": { - "$ref": "#/components/schemas/SecretVersion" + "type": "string" } }, - "has_more": { - "type": "boolean", - "description": "True if more items exist after this page." + "states": { + "type": "array", + "items": { + "type": "string" + } }, - "next_cursor": { + "min_severity": { "type": "string", - "nullable": true, - "description": "Opaque cursor for the next page, or null if no more pages." + "enum": [ + "LOW", + "MEDIUM", + "HIGH", + "CRITICAL" + ] } }, "required": [ - "data", - "has_more", - "next_cursor" + "type", + "resource_types", + "states" ] }, - "SecretPlaintext": { + "AgentRuntimePolicy": { "type": "object", "properties": { - "value": { + "execution_environment": { + "type": "string", + "enum": [ + "CODE_MODE_FIRST", + "RETAINED_RUNTIME_ALLOWED", + "NO_RETAINED_RUNTIME" + ] + }, + "filesystem": { + "type": "string" + }, + "shell": { + "type": "string" + }, + "browser": { "type": "string" } }, "required": [ - "value" + "execution_environment", + "filesystem", + "shell", + "browser" ] }, - "StripeAccountCreated": { + "AgentTemplateRemediationPolicy": { "type": "object", + "nullable": true, "properties": { - "stripe_account_id": { - "type": "string" + "repository_change_request": { + "$ref": "#/components/schemas/AgentTemplateRepositoryChangeRequestRemediationPolicy" } }, "required": [ - "stripe_account_id" + "repository_change_request" ] }, - "CreateStripeAccountBody": { - "type": "object", - "properties": {}, - "additionalProperties": false - }, - "StripeAccountStatus": { + "AgentTemplateRepositoryChangeRequestRemediationPolicy": { "type": "object", "properties": { - "stripe_account_id": { - "type": "string" + "mode": { + "type": "string", + "enum": [ + "LIKELY_SOURCE_OR_CONFIG_FIX_ONLY" + ] }, - "charges_enabled": { + "evidence_required": { "type": "boolean" }, - "payouts_enabled": { - "type": "boolean" - } - }, - "required": [ - "stripe_account_id", - "charges_enabled", - "payouts_enabled" - ] - }, - "StripeAccountLinkCreated": { - "type": "object", - "properties": { - "url": { - "type": "string" + "allowed_actions": { + "type": "array", + "items": { + "type": "string" + } + }, + "blocked_actions": { + "type": "array", + "items": { + "type": "string" + } } }, "required": [ - "url" + "mode", + "evidence_required", + "allowed_actions", + "blocked_actions" ] }, - "CreateStripeAccountLinkBody": { + "AgentPreference": { "type": "object", "properties": { - "return_url": { + "id": { "type": "string", - "format": "uri" + "minLength": 1, + "maxLength": 54 }, - "refresh_url": { + "workspace_id": { "type": "string", - "format": "uri" - } - }, - "additionalProperties": false - }, - "StripeAccountSessionCreated": { - "type": "object", - "properties": { - "client_secret": { + "minLength": 1, + "maxLength": 53 + }, + "user_id": { "type": "string" - } - }, - "required": [ - "client_secret" - ] - }, - "CreateStripeAccountSessionBody": { - "type": "object", - "properties": {}, - "additionalProperties": false - }, - "WorkspaceStripeProducts": { - "type": "object", - "properties": { - "data": { + }, + "communication_profile": { + "type": "string", + "enum": [ + "BEGINNER", + "INTERMEDIATE", + "ADVANCED", + "EXPERT", + "ADAPTIVE" + ] + }, + "learning_mode_enabled": { + "type": "boolean" + }, + "seen_concepts": { "type": "array", "items": { - "$ref": "#/components/schemas/StripeProduct" + "type": "string" } }, - "has_more": { - "type": "boolean", - "description": "True if more items exist after this page." + "created_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." + "updated_at": { + "type": "integer", + "minimum": 0, + "description": "Unix timestamp (seconds)" }, - "stripe_account_id": { - "type": "string", - "nullable": true + "etag": { + "type": "string" } }, "required": [ - "data", - "has_more", - "next_cursor", - "stripe_account_id" + "id", + "workspace_id", + "user_id", + "communication_profile", + "learning_mode_enabled", + "seen_concepts", + "created_at", + "updated_at", + "etag" ] }, - "StripeProduct": { + "SandboxOperationsSummary": { "type": "object", "properties": { - "id": { - "type": "string" + "active_sandbox_count": { + "type": "integer", + "minimum": 0 }, - "name": { - "type": "string" + "idle_retained_filesystem_count": { + "type": "integer", + "minimum": 0 }, - "images": { - "type": "array", - "items": { - "type": "string" - } + "retained_filesystem_age_ms": { + "type": "number", + "minimum": 0 }, - "prices": { + "estimated_retained_filesystem_gb_hours": { + "type": "number", + "minimum": 0 + }, + "stuck_sandbox_count_by_state": { "type": "array", "items": { - "$ref": "#/components/schemas/StripePrice" + "type": "object", + "properties": { + "state": { + "type": "string", + "enum": [ + "CREATING", + "STARTING", + "ACTIVE", + "STOPPING", + "STOPPED", + "DELETING", + "DELETED", + "FAILED" + ] + }, + "count": { + "type": "integer", + "minimum": 0 + } + }, + "required": [ + "state", + "count" + ] } + }, + "average_cold_start_latency_ms": { + "type": "number", + "nullable": true, + "minimum": 0 + }, + "average_resume_latency_ms": { + "type": "number", + "nullable": true, + "minimum": 0 } }, "required": [ - "id", - "name", - "images", - "prices" + "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" ] }, - "StripePrice": { + "AgentSession": { "type": "object", "properties": { "id": { - "type": "string" - }, - "currency": { - "type": "string" - }, - "billing_scheme": { - "type": "string" + "type": "string", + "minLength": 1, + "maxLength": 54 }, - "nickname": { + "workspace_id": { "type": "string", - "nullable": true + "minLength": 1, + "maxLength": 53 }, - "unit_amount": { - "type": "number", - "nullable": true + "organization_id": { + "type": "string", + "nullable": true, + "minLength": 1, + "maxLength": 54 }, - "unit_amount_decimal": { + "agent_id": { "type": "string", - "nullable": true + "minLength": 1, + "maxLength": 54 }, - "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", - "currency", - "billing_scheme", - "nickname", - "unit_amount", - "unit_amount_decimal", - "recurring" - ] - }, - "UpgradeCheckoutCreated": { - "type": "object", - "properties": { - "url": { - "type": "string" - } - }, - "required": [ - "url" - ] - }, - "CreateUpgradeCheckoutBody": { - "type": "object", - "properties": { - "success_url": { + "state": { "type": "string", - "format": "uri" + "enum": [ + "ACTIVE", + "WAITING_FOR_INPUT", + "WAITING_FOR_PERMISSION", + "COMPLETED", + "FAILED", + "CANCELLED", + "ARCHIVED" + ] }, - "cancel_url": { + "origin": { "type": "string", - "format": "uri" - } - }, - "required": [ - "success_url", - "cancel_url" - ], - "additionalProperties": false - }, - "BillingPortalSessionCreated": { - "type": "object", - "properties": { - "url": { - "type": "string" - } - }, - "required": [ - "url" - ] - }, - "CreateBillingPortalSessionBody": { - "type": "object", - "properties": { - "return_url": { + "enum": [ + "DASHBOARD", + "API", + "MCP", + "ACP", + "AMBIENT", + "SYSTEM" + ] + }, + "title": { "type": "string", - "format": "uri" - } - }, - "required": [ - "return_url" - ], - "additionalProperties": false - }, - "ClusterList": { - "type": "object", - "properties": { - "data": { - "type": "array", - "items": { - "$ref": "#/components/schemas/Cluster" - } + "nullable": true + }, + "communication_profile": { + "type": "string", + "enum": [ + "BEGINNER", + "INTERMEDIATE", + "ADVANCED", + "EXPERT", + "ADAPTIVE" + ] }, - "has_more": { - "type": "boolean", - "description": "True if more items exist after this page." + "created_by": { + "type": "string" }, - "next_cursor": { + "parent_session_id": { "type": "string", "nullable": true, - "description": "Opaque cursor for the next page, or null if no more pages." - } - }, - "required": [ - "data", - "has_more", - "next_cursor" - ] - }, - "Cluster": { - "type": "object", - "properties": { - "id": { + "minLength": 1, + "maxLength": 54 + }, + "forked_from_session_id": { "type": "string", + "nullable": true, "minLength": 1, "maxLength": 54 }, - "html_url": { + "spawned_by_turn_id": { "type": "string", - "maxLength": 2048, - "format": "uri", - "description": "Absolute dashboard URL for this resource. OUTPUT_ONLY.", - "example": "https://akua.dev/clusters/clu_j572abc123def456" + "nullable": true, + "minLength": 1, + "maxLength": 54 }, - "name": { - "type": "string" + "agent_role": { + "type": "string", + "nullable": true }, - "workspace_id": { + "current_sandbox_id": { "type": "string", + "nullable": true, "minLength": 1, - "maxLength": 53 + "maxLength": 54 }, - "state": { + "last_event_cursor": { "type": "string", - "enum": [ - "pending", - "provisioning", - "active", - "suspended", - "deleting" - ], - "description": "Cluster lifecycle state in canonical lowercase, past-participle naming." + "nullable": true }, - "provider": { - "type": "string", - "enum": [ - "managed_kaas", - "imported_byoc" - ], - "description": "Cluster control-plane family: managed (`managed_kaas`) vs imported self-managed (`imported_byoc`)." + "events_retained_until": { + "type": "integer", + "minimum": 0, + "description": "Unix timestamp (seconds)" }, - "reconciling": { + "filesystem_retained_until": { + "type": "integer", + "minimum": 0, + "description": "Unix timestamp (seconds)" + }, + "filesystem_pinned": { "type": "boolean" }, + "usage_summary": { + "$ref": "#/components/schemas/AgentUsageSummary" + }, "created_at": { "type": "integer", "minimum": 0, @@ -11047,128 +25294,112 @@ }, "required": [ "id", - "html_url", - "name", "workspace_id", + "organization_id", + "agent_id", "state", - "provider", - "reconciling", + "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" ] }, - "DashboardClusterList": { + "AgentSessionList": { "type": "object", "properties": { - "clusters": { + "data": { "type": "array", "items": { - "$ref": "#/components/schemas/DashboardCluster" + "$ref": "#/components/schemas/AgentSession" } }, - "regions": { + "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" + ] + }, + "AgentWorkConflictList": { + "type": "object", + "properties": { + "data": { "type": "array", "items": { - "$ref": "#/components/schemas/DashboardClusterRegion" + "$ref": "#/components/schemas/AgentWorkConflict" } } }, "required": [ - "clusters", - "regions" - ] + "data" + ], + "additionalProperties": false }, - "DashboardCluster": { + "AgentWorkConflict": { "type": "object", "properties": { - "id": { + "agent_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" - }, - "name": { - "type": "string" - }, - "workspace_id": { + "session_id": { "type": "string", "minLength": 1, - "maxLength": 53 + "maxLength": 54 }, - "region_id": { + "turn_id": { "type": "string", "minLength": 1, "maxLength": 54 }, - "region": { - "$ref": "#/components/schemas/DashboardClusterRegion" - }, - "kaas": { - "$ref": "#/components/schemas/ClusterKaas" - }, - "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 - }, - "etag": { - "type": "string" - } - }, - "required": [ - "id", - "html_url", - "name", - "workspace_id", - "region_id", - "region", - "kaas", - "created_at", - "updated_at", - "product_count", - "installs_count", - "etag" - ] - }, - "DashboardClusterRegion": { - "type": "object", - "properties": { - "id": { + "event_id": { "type": "string", "minLength": 1, "maxLength": 54 }, - "name": { - "type": "string" - }, - "icon": { + "event_type": { "type": "string", - "nullable": true + "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" + ] }, - "workspace_id": { + "reason": { "type": "string", "minLength": 1, - "maxLength": 53 + "maxLength": 500 }, "created_at": { "type": "integer", @@ -11177,417 +25408,252 @@ } }, "required": [ - "id", - "name", - "icon", - "workspace_id", + "agent_id", + "session_id", + "turn_id", + "event_id", + "event_type", + "reason", "created_at" - ] - }, - "ClusterKaas": { - "type": "object", - "nullable": true, - "properties": { - "namespace": { - "type": "string" - }, - "version": { - "type": "string" - }, - "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`." - }, - "status": { - "type": "string", - "enum": [ - "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": [ - "namespace", - "version", - "network_profile", - "status", - "status_message", - "suspended_at", - "suspended_by" - ] - }, - "ClusterCapabilities": { - "type": "object", - "properties": { - "api_groups": { - "type": "array", - "items": { - "type": "string" - } - }, - "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" - ] - } - }, - "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" - }, - "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" - ] - } - }, - "default_gateway": { - "type": "object", - "properties": { - "namespace": { - "type": "string" - }, - "name": { - "type": "string" - } - }, - "required": [ - "namespace", - "name" - ] - }, - "ingress_classes": { - "type": "array", - "items": { - "type": "string" - } - }, - "nodes": { - "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": { - "type": "string" - }, - "operating_system": { - "type": "string" - }, - "architecture": { - "type": "string" - } - }, - "required": [ - "name", - "roles", - "version", - "cpu_capacity", - "memory_capacity", - "os_image", - "architecture" - ] - } - } - }, - "required": [ - "api_groups", - "storage_classes", - "gateway_classes", - "gateways", - "ingress_classes", - "nodes" - ] - }, - "Kubeconfig": { - "type": "object", - "properties": { - "kubeconfig": { - "type": "string" - } - }, - "required": [ - "kubeconfig" - ] + ], + "additionalProperties": false }, - "ExecResult": { + "SetAgentSessionRetentionBody": { "type": "object", - "properties": { - "output": { - "type": "string" + "properties": { + "events_retained_until": { + "type": "integer", + "minimum": 0, + "description": "Unix timestamp (seconds)" }, - "exit_code": { - "type": "integer" + "filesystem_retained_until": { + "type": "integer", + "minimum": 0, + "description": "Unix timestamp (seconds)" }, - "duration_ms": { - "type": "number", - "minimum": 0 + "filesystem_pinned": { + "type": "boolean" + }, + "retention_reason": { + "type": "string", + "enum": [ + "SESSION_ACTIVE", + "PINNED", + "POLICY", + "TERMINAL_GRACE", + "MANUAL_DELETE" + ] } }, "required": [ - "output", - "exit_code", - "duration_ms" - ] + "events_retained_until", + "filesystem_retained_until", + "filesystem_pinned", + "retention_reason" + ], + "additionalProperties": false }, - "ExecBody": { + "AgentTurn": { "type": "object", "properties": { - "namespace": { + "id": { "type": "string", "minLength": 1, - "maxLength": 253 + "maxLength": 54 }, - "pod": { + "workspace_id": { "type": "string", "minLength": 1, - "maxLength": 253 + "maxLength": 53 }, - "container": { + "organization_id": { "type": "string", + "nullable": true, "minLength": 1, - "maxLength": 253 + "maxLength": 54 }, - "command": { - "type": "array", - "items": { - "type": "string" - } - } - }, - "required": [ - "namespace", - "pod", - "command" - ], - "additionalProperties": false - }, - "WorkerBootstrap": { - "type": "object", - "properties": { - "id": { + "agent_id": { "type": "string", "minLength": 1, "maxLength": 54 }, - "cluster_id": { + "session_id": { "type": "string", "minLength": 1, "maxLength": 54 }, - "status": { + "state": { "type": "string", "enum": [ - "active", - "revoked", - "expired" - ], - "description": "Lifecycle state for a one-time worker bootstrap token." + "QUEUED", + "RUNNING", + "WAITING_FOR_INPUT", + "WAITING_FOR_PERMISSION", + "COMPLETED", + "FAILED", + "CANCELLED" + ] }, - "created_at": { - "type": "integer", - "minimum": 0, - "description": "Unix timestamp (seconds)" + "origin": { + "type": "string", + "enum": [ + "DASHBOARD", + "API", + "MCP", + "ACP", + "AMBIENT", + "SYSTEM" + ] }, - "updated_at": { + "input": { + "type": "object", + "properties": { + "type": { + "type": "string", + "enum": [ + "message" + ] + }, + "content": { + "type": "string" + } + }, + "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)" }, - "expires_at": { + "completed_at": { "type": "integer", + "nullable": true, "minimum": 0, "description": "Unix timestamp (seconds)" }, - "etag": { - "type": "string" - }, - "token": { + "runtime_decision": { "type": "string", - "description": "One-time-view bearer token. Populated only on the create response; never returned on subsequent GET/LIST/:revoke reads." + "nullable": true, + "enum": [ + "ALLOWED", + "DENIED", + "APPROVAL_REQUIRED", + null + ] }, - "command": { + "decision_reason": { "type": "string", - "description": "Bash bootstrap command with the token already substituted, ready to run on a worker node. Reveal-on-create only." + "nullable": true }, - "cloud_init": { + "resolved_execution_mode": { "type": "string", - "description": "Cloud-init YAML with the token already substituted, ready to use as worker-node user-data. Reveal-on-create only." + "nullable": true, + "enum": [ + "CODE_MODE", + "RETAINED_RUNTIME", + null + ] }, - "artifacts": { - "$ref": "#/components/schemas/WorkerBootstrapArtifacts" + "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, + "description": "Unix timestamp (seconds)" + }, + "updated_at": { + "type": "integer", + "minimum": 0, + "description": "Unix timestamp (seconds)" + }, + "etag": { + "type": "string" } }, "required": [ "id", - "cluster_id", - "status", + "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" ] }, - "WorkerBootstrapList": { + "AgentTurnList": { "type": "object", "properties": { "data": { "type": "array", "items": { - "$ref": "#/components/schemas/WorkerBootstrap" + "$ref": "#/components/schemas/AgentTurn" } }, "has_more": { @@ -11606,49 +25672,84 @@ "next_cursor" ] }, - "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": { + "AgentEvent": { "type": "object", "properties": { - "install_count": { - "type": "integer", - "minimum": 0 + "id": { + "type": "string", + "minLength": 1, + "maxLength": 54 }, - "product_count": { - "type": "integer", - "minimum": 0 + "workspace_id": { + "type": "string", + "minLength": 1, + "maxLength": 53 }, - "cluster_count": { + "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 + "minimum": 0, + "description": "Unix timestamp (seconds)" + }, + "data": { + "nullable": true } }, "required": [ - "install_count", - "product_count", - "cluster_count" - ], - "x-platform-visibility": "INTERNAL" + "id", + "workspace_id", + "agent_id", + "session_id", + "turn_id", + "sequence", + "cursor", + "type", + "created_at" + ] }, - "OrganizationList": { + "AgentProviderExchangeList": { "type": "object", "properties": { "data": { "type": "array", "items": { - "$ref": "#/components/schemas/Organization" + "$ref": "#/components/schemas/AgentProviderExchange" } }, "has_more": { @@ -11667,7 +25768,7 @@ "next_cursor" ] }, - "Organization": { + "AgentProviderExchange": { "type": "object", "properties": { "id": { @@ -11675,238 +25776,166 @@ "minLength": 1, "maxLength": 54 }, - "name": { + "workspace_id": { "type": "string", - "example": "Code Zero" + "minLength": 1, + "maxLength": 53 }, - "slug": { + "organization_id": { "type": "string", "nullable": true, - "example": "code-zero" - }, - "created_at": { - "type": "integer", - "minimum": 0, - "description": "Unix timestamp (seconds)" + "minLength": 1, + "maxLength": 54 }, - "updated_at": { - "type": "integer", - "minimum": 0, - "description": "Unix timestamp (seconds)" + "agent_id": { + "type": "string", + "minLength": 1, + "maxLength": 54 }, - "etag": { - "type": "string" - } - }, - "required": [ - "id", - "name", - "slug", - "created_at", - "updated_at", - "etag" - ] - }, - "OrganizationCreateRequest": { - "type": "object", - "properties": { - "name": { + "session_id": { "type": "string", - "minLength": 2, - "maxLength": 50, - "pattern": "^[\\p{L}\\p{N}](?:[\\p{L}\\p{N}\\s\\-'&.]*[\\p{L}\\p{N}])?$/u" + "minLength": 1, + "maxLength": 54 }, - "slug": { + "turn_id": { "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": { + "minLength": 1, + "maxLength": 54 + }, + "provider": { + "type": "string" + }, + "model": { "type": "string", - "minLength": 2, - "maxLength": 50, - "pattern": "^[\\p{L}\\p{N}](?:[\\p{L}\\p{N}\\s\\-'&.]*[\\p{L}\\p{N}])?$/u" + "nullable": true }, - "slug": { + "fallback_from_model": { "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" - } - } - }, - "required": [ - "data" - ] - }, - "OrganizationMember": { - "type": "object", - "properties": { - "user_id": { + "nullable": true + }, + "fallback_reason": { "type": "string", - "example": "user_abc123", - "description": "BetterAuth user ID of the member" + "nullable": true }, - "role": { + "credential_mode": { "type": "string", "enum": [ - "owner", - "admin", - "member" - ], - "description": "Membership role in the organization", - "example": "admin" + "PLATFORM_SUBSCRIPTION", + "PLATFORM_API", + "WORKSPACE_BYOK" + ] }, - "joined_at": { + "credential_secret_id": { + "type": "string", + "nullable": true, + "minLength": 1, + "maxLength": 54 + }, + "requested_at": { "type": "integer", "minimum": 0, "description": "Unix timestamp (seconds)" }, - "updated_at": { + "responded_at": { "type": "integer", "minimum": 0, "description": "Unix timestamp (seconds)" }, - "etag": { - "type": "string" - } - }, - "required": [ - "user_id", - "role", - "joined_at", - "updated_at", - "etag" - ] - }, - "OrganizationAddMemberRequest": { - "type": "object", - "properties": { - "user_id": { - "type": "string", - "example": "user_abc123", - "description": "BetterAuth user ID of the user to add" + "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 + }, + "output": { + "type": "integer", + "minimum": 0 + }, + "total": { + "type": "integer", + "minimum": 0 + } + } }, - "role": { + "message_summary": { "type": "string", - "enum": [ - "owner", - "admin", - "member" - ], - "default": "member", - "description": "Membership role in the organization" - } - }, - "required": [ - "user_id" - ], - "additionalProperties": false - }, - "OrganizationUpdateMemberRoleRequest": { - "type": "object", - "properties": { - "role": { + "nullable": true + }, + "upstream_error_code": { "type": "string", - "enum": [ - "owner", - "admin", - "member" - ], - "description": "Membership role in the organization" + "nullable": true + }, + "created_at": { + "type": "integer", + "minimum": 0, + "description": "Unix timestamp (seconds)" } }, "required": [ - "role" - ], - "additionalProperties": false + "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" + ] }, - "ManagedWorkspaceList": { + "AgentEventList": { "type": "object", "properties": { "data": { "type": "array", "items": { - "$ref": "#/components/schemas/ManagedWorkspace" + "$ref": "#/components/schemas/AgentEvent" } - } - }, - "required": [ - "data" - ] - }, - "ManagedWorkspace": { - "type": "object", - "properties": { - "id": { - "type": "string", - "minLength": 1, - "maxLength": 53 }, - "name": { - "type": "string", - "example": "My Workspace" + "has_more": { + "type": "boolean", + "description": "True if more items exist after this page." }, - "icon": { + "next_cursor": { "type": "string", "nullable": true, - "example": null - }, - "created_at": { - "type": "integer", - "minimum": 0, - "description": "Unix timestamp (seconds)" + "description": "Opaque cursor for the next page, or null if no more pages." } }, "required": [ - "id", - "name", - "icon", - "created_at" + "data", + "has_more", + "next_cursor" ] }, - "NotificationList": { + "ApprovalRequestList": { "type": "object", "properties": { "data": { "type": "array", "items": { - "$ref": "#/components/schemas/Notification" + "$ref": "#/components/schemas/ApprovalRequest" } }, "has_more": { @@ -11925,7 +25954,7 @@ "next_cursor" ] }, - "Notification": { + "ApprovalRequest": { "type": "object", "properties": { "id": { @@ -11933,175 +25962,164 @@ "minLength": 1, "maxLength": 54 }, - "type": { + "workspace_id": { "type": "string", - "example": "machine_expiry" + "minLength": 1, + "maxLength": 53 }, - "resource_type": { + "agent_id": { "type": "string", - "example": "machine" - }, - "resource_id": { - "type": "string" + "minLength": 1, + "maxLength": 54 }, - "title": { + "session_id": { "type": "string", - "nullable": true + "minLength": 1, + "maxLength": 54 }, - "body": { + "turn_id": { "type": "string", - "nullable": true + "minLength": 1, + "maxLength": 54 }, - "severity": { + "state": { "type": "string", - "nullable": true, "enum": [ - "info", - "warning", - "critical", - null - ], - "description": "Severity level surfaced to UI indicators." + "PENDING", + "APPROVED", + "REJECTED" + ] }, - "context": { - "type": "object", - "nullable": true, - "additionalProperties": { - "type": "string" - } + "title": { + "type": "string" }, - "read_at": { + "summary": { + "type": "string" + }, + "actions": { + "type": "array", + "items": { + "nullable": true + }, + "default": [] + }, + "created_by": { + "type": "string" + }, + "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)" + }, + "etag": { + "type": "string" } }, "required": [ "id", - "type", - "resource_type", - "resource_id", + "workspace_id", + "agent_id", + "session_id", + "turn_id", + "state", "title", - "body", - "severity", - "context", - "read_at", - "created_at" - ] - }, - "UnreadCount": { - "type": "object", - "properties": { - "count": { - "type": "number" - } - }, - "required": [ - "count" + "summary", + "created_by", + "created_at", + "updated_at", + "etag" ] }, - "QuotaInfoList": { + "WorkspaceSubdomain": { "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": { + "id": { "type": "string", - "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": { + "minLength": 1, + "maxLength": 54 + }, + "workspace_id": { "type": "string", - "example": "compute/machines", - "description": "Metric: service/resource" + "minLength": 1, + "maxLength": 53 }, - "type": { + "name": { "type": "string", - "enum": [ - "allocation", - "rate", - "concurrency" - ], - "description": "Allocation = max owned, rate = max per time window, concurrency = max in-flight.", - "example": "allocation" + "minLength": 1, + "maxLength": 63 }, - "display_name": { + "fqdn": { "type": "string", - "example": "Compute machines" + "minLength": 1, + "maxLength": 253 }, - "unit": { + "status": { "type": "string", "enum": [ - "count", - "cores", - "bytes", - "seconds", - "count/day", - "count/minute", - "cents/day" + "active", + "propagating", + "reserved" ], - "description": "Unit the limit/usage numbers are measured in.", - "example": "count" - }, - "limit": { - "type": "number", - "example": 1 + "description": "Current workspace subdomain lifecycle state." }, - "usage": { - "type": "number", - "example": 0 + "name_changed_at": { + "type": "integer", + "nullable": true, + "minimum": 0, + "description": "Unix timestamp (seconds)" }, - "remaining": { - "type": "number", - "example": 1 + "created_at": { + "type": "integer", + "minimum": 0, + "description": "Unix timestamp (seconds)" }, - "resets_at": { + "updated_at": { "type": "integer", "minimum": 0, - "description": "For rate quotas: Unix timestamp (seconds) reset time" + "description": "Unix timestamp (seconds)" + }, + "etag": { + "type": "string" } }, "required": [ - "metric", - "type", - "display_name", - "unit", - "limit", - "usage", - "remaining" + "id", + "workspace_id", + "name", + "fqdn", + "status", + "name_changed_at", + "created_at", + "updated_at", + "etag" ] }, - "RegionList": { + "SetWorkspaceSubdomainNameBody": { + "type": "object", + "properties": { + "name": { + "type": "string", + "minLength": 1, + "maxLength": 63 + } + }, + "required": [ + "name" + ], + "additionalProperties": false + }, + "PreviewHostnameList": { "type": "object", "properties": { "data": { "type": "array", "items": { - "$ref": "#/components/schemas/Region" + "$ref": "#/components/schemas/PreviewHostname" } }, "has_more": { @@ -12120,7 +26138,7 @@ "next_cursor" ] }, - "Region": { + "PreviewHostname": { "type": "object", "properties": { "id": { @@ -12128,137 +26146,214 @@ "minLength": 1, "maxLength": 54 }, - "name": { + "workspace_id": { "type": "string", - "example": "us-east-1" + "minLength": 1, + "maxLength": 53 }, - "icon": { + "install_id": { "type": "string", - "nullable": true, - "description": "Icon URL" + "minLength": 1, + "maxLength": 55 }, - "workspace_id": { + "hostname": { "type": "string", "minLength": 1, - "maxLength": 53 + "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": { + "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 + } + ] + }, + "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", - "name", - "icon", "workspace_id", - "created_at" + "install_id", + "hostname", + "protocol", + "routing_mode", + "binding", + "status", + "last_seen_at", + "created_at", + "updated_at", + "etag" ] }, - "DashboardRegionList": { + "BindPinnedPreviewHostnameBody": { "type": "object", "properties": { - "data": { - "type": "array", - "items": { - "$ref": "#/components/schemas/DashboardRegion" - } - }, - "has_more": { - "type": "boolean", - "description": "True if more items exist after this page." + "render_id": { + "type": "string", + "minLength": 1, + "maxLength": 54 }, - "next_cursor": { + "protocol": { "type": "string", - "nullable": true, - "description": "Opaque cursor for the next page, or null if no more pages." - } - }, - "required": [ - "data", - "has_more", - "next_cursor" - ] - }, - "DashboardRegion": { - "allOf": [ - { - "$ref": "#/components/schemas/Region" + "enum": [ + "http", + "websocket", + "grpc" + ], + "default": "http", + "description": "Transport class for route forwarding." }, - { - "type": "object", - "properties": { - "cluster_pool_health": { - "$ref": "#/components/schemas/ClusterPoolHealth" - } - }, - "required": [ - "cluster_pool_health" - ] + "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 }, - "ClusterPoolHealth": { + "BindFloatingPreviewHostnameBody": { "type": "object", "properties": { - "region_id": { + "track": { "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" + "maxLength": 100 }, - "failed_last_24h": { - "type": "number" + "render_id": { + "type": "string", + "minLength": 1, + "maxLength": 54 }, - "last_refill_at": { - "type": "integer", - "minimum": 0, - "description": "Unix timestamp (seconds)" + "protocol": { + "type": "string", + "enum": [ + "http", + "websocket", + "grpc" + ], + "default": "http", + "description": "Transport class for route forwarding." }, - "last_error": { - "type": "string" + "routing_mode": { + "type": "string", + "enum": [ + "through_dispatcher", + "bypass_dispatcher" + ], + "default": "through_dispatcher", + "description": "Whether traffic uses the dispatcher Worker or bypasses it." } }, "required": [ - "region_id", - "target_size", - "enabled", - "available", - "provisioning", - "allocation_requests", - "allocated_last_24h", - "deleted_last_24h", - "failed_last_24h" - ] + "track", + "render_id" + ], + "additionalProperties": false }, - "RegistryCredentialList": { + "CustomDomainList": { "type": "object", "properties": { "data": { "type": "array", "items": { - "$ref": "#/components/schemas/RegistryCredential" + "$ref": "#/components/schemas/CustomDomain" } }, "has_more": { @@ -12277,2586 +26372,2503 @@ "next_cursor" ] }, - "RegistryCredential": { + "CustomDomain": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, - "maxLength": 55 + "maxLength": 54 }, - "name": { + "workspace_id": { "type": "string", - "example": "GitHub Container Registry" + "minLength": 1, + "maxLength": 53 }, - "registry_url": { + "hostname": { "type": "string", - "example": "ghcr.io" + "minLength": 1, + "maxLength": 253 }, - "type": { + "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": [ - "basic", - "token", - "oauth" + "http", + "websocket", + "grpc" ], - "description": "Authentication scheme used to talk to the upstream registry." + "description": "Transport class for route forwarding." }, - "is_active": { - "type": "boolean", - "description": "Whether the credential is active" + "routing_mode": { + "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" + ] + }, + "status": { + "type": "string", + "enum": [ + "provisioning", + "active", + "failed", + "releasing" + ] }, "created_at": { "type": "integer", "minimum": 0, "description": "Unix timestamp (seconds)" }, - "last_used_at": { + "updated_at": { "type": "integer", - "nullable": true, "minimum": 0, - "description": "Unix timestamp (seconds), null if never used" + "description": "Unix timestamp (seconds)" + }, + "etag": { + "type": "string" } }, "required": [ "id", - "name", - "registry_url", - "type", - "is_active", + "workspace_id", + "hostname", + "target", + "protocol", + "routing_mode", + "ssl", + "status", "created_at", - "last_used_at" + "updated_at", + "etag" ] }, - "RegistryStats": { + "CreateCustomDomainBody": { "type": "object", "properties": { - "total_pulls": { - "type": "number" - }, - "successful_pulls": { - "type": "number" - }, - "failed_pulls": { - "type": "number" - }, - "success_rate": { - "type": "number" - }, - "auth_successes": { - "type": "number" - }, - "auth_failures": { - "type": "number" + "hostname": { + "type": "string", + "minLength": 1, + "maxLength": 253 }, - "by_registry": { - "type": "array", - "items": { - "type": "object", - "properties": { - "registry_url": { - "type": "string" - }, - "pulls": { - "type": "number" + "target": { + "oneOf": [ + { + "type": "object", + "properties": { + "kind": { + "type": "string", + "enum": [ + "install" + ] + }, + "install_id": { + "type": "string", + "minLength": 1, + "maxLength": 55 + } }, - "failures": { - "type": "number" - } + "required": [ + "kind", + "install_id" + ], + "additionalProperties": false }, - "required": [ - "registry_url", - "pulls", - "failures" - ] - } - }, - "latency": { - "type": "object", - "properties": { - "avg": { - "type": "number", - "nullable": true + { + "type": "object", + "properties": { + "kind": { + "type": "string", + "enum": [ + "cluster" + ] + }, + "cluster_id": { + "type": "string", + "minLength": 1, + "maxLength": 54 + } + }, + "required": [ + "kind", + "cluster_id" + ], + "additionalProperties": false }, - "p95": { - "type": "number", - "nullable": true + { + "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": [ - "avg", - "p95" ] + }, + "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": [ - "total_pulls", - "successful_pulls", - "failed_pulls", - "success_rate", - "auth_successes", - "auth_failures", - "by_registry", - "latency" - ] - }, - "RegistryActivityResponse": { - "type": "object", - "properties": { - "data": { - "type": "array", - "items": { - "$ref": "#/components/schemas/RegistryActivityBucket" - } - } - }, - "required": [ - "data" - ] + "hostname", + "target" + ], + "additionalProperties": false }, - "RegistryActivityBucket": { + "UpdateCustomDomainBody": { "type": "object", "properties": { - "timestamp": { - "type": "number", - "description": "Unix timestamp in milliseconds." + "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 + } + ] }, - "success": { - "type": "number" + "protocol": { + "type": "string", + "enum": [ + "http", + "websocket", + "grpc" + ], + "description": "Transport class for route forwarding." }, - "failed": { - "type": "number" + "routing_mode": { + "type": "string", + "enum": [ + "through_dispatcher", + "bypass_dispatcher" + ], + "description": "Whether traffic uses the dispatcher Worker or bypasses it." } }, - "required": [ - "timestamp", - "success", - "failed" - ] + "additionalProperties": false }, - "RegistryAuditLogList": { + "CloudflareCredentialList": { "type": "object", "properties": { "data": { "type": "array", "items": { - "$ref": "#/components/schemas/RegistryAuditLog" + "$ref": "#/components/schemas/CloudflareCredential" } + }, + "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": { + "CloudflareCredential": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, - "maxLength": 54 - }, - "timestamp": { - "type": "number", - "description": "Unix timestamp in milliseconds." + "maxLength": 56 }, - "operation": { + "name": { "type": "string", - "enum": [ - "pull_manifest", - "pull_blob", - "pull_failed", - "auth_success", - "auth_failed" - ] + "example": "Production Cloudflare" }, - "registry_url": { - "type": "string" + "account_id": { + "type": "string", + "description": "Cloudflare account ID." }, - "repository": { - "type": "string" + "origin_zone_id": { + "type": "string", + "nullable": true, + "description": "Cloudflare zone ID used for Access-protected origin hostnames." }, - "reference": { + "origin_hostname_suffix": { "type": "string", - "nullable": true + "nullable": true, + "description": "Hostname suffix used for Access-protected origin hostnames." }, - "success": { - "type": "boolean" + "is_active": { + "type": "boolean", + "description": "Whether the credential is active" }, - "install_name": { - "type": "string", - "nullable": true + "created_at": { + "type": "integer", + "minimum": 0, + "description": "Unix timestamp (seconds)" + }, + "last_used_at": { + "type": "integer", + "nullable": true, + "minimum": 0, + "description": "Unix timestamp (seconds), null if never used" } }, "required": [ "id", - "timestamp", - "operation", - "registry_url", - "repository", - "reference", - "success", - "install_name" + "name", + "account_id", + "origin_zone_id", + "origin_hostname_suffix", + "is_active", + "created_at", + "last_used_at" ] }, - "RegistryErrorList": { + "CreateCloudflareCredentialBody": { "type": "object", "properties": { - "data": { - "type": "array", - "items": { - "$ref": "#/components/schemas/RegistryError" - } + "name": { + "type": "string", + "minLength": 1, + "maxLength": 100, + "example": "Production Cloudflare" + }, + "account_id": { + "type": "string", + "minLength": 1, + "maxLength": 200, + "pattern": "^[A-Za-z0-9_-]+$", + "description": "Cloudflare account ID." + }, + "origin_zone_id": { + "type": "string", + "minLength": 1, + "maxLength": 200, + "pattern": "^[A-Za-z0-9_-]+$", + "description": "Cloudflare zone ID used for Access-protected origin hostnames." + }, + "origin_hostname_suffix": { + "type": "string", + "minLength": 1, + "maxLength": 253, + "description": "Hostname suffix used for Access-protected origin hostnames." + }, + "api_token": { + "type": "string", + "minLength": 1, + "maxLength": 2000, + "description": "Cloudflare API token. Stored as a platform Secret; never returned." } }, "required": [ - "data" - ] + "name", + "account_id", + "origin_zone_id", + "origin_hostname_suffix", + "api_token" + ], + "additionalProperties": false }, - "RegistryError": { + "AccessDecision": { "type": "object", "properties": { - "message": { - "type": "string" + "decision": { + "$ref": "#/components/schemas/AccessDecisionResult" }, - "count": { - "type": "number" + "action": { + "type": "object", + "properties": { + "id": { + "type": "string", + "minLength": 1 + }, + "name": { + "type": "string", + "minLength": 1 + } + }, + "required": [ + "id", + "name" + ], + "additionalProperties": false + }, + "reasons": { + "type": "array", + "items": { + "$ref": "#/components/schemas/AccessReason" + } } }, "required": [ - "message", - "count" + "decision", + "action", + "reasons" + ], + "additionalProperties": false + }, + "AccessDecisionResult": { + "oneOf": [ + { + "type": "object", + "properties": { + "result": { + "type": "string", + "enum": [ + "allowed" + ] + } + }, + "required": [ + "result" + ], + "additionalProperties": false + }, + { + "type": "object", + "properties": { + "result": { + "type": "string", + "enum": [ + "denied" + ] + }, + "message": { + "type": "string", + "minLength": 1 + } + }, + "required": [ + "result", + "message" + ], + "additionalProperties": false + }, + { + "type": "object", + "properties": { + "result": { + "type": "string", + "enum": [ + "unknown" + ] + }, + "message": { + "type": "string", + "minLength": 1 + } + }, + "required": [ + "result", + "message" + ], + "additionalProperties": false + } ] }, - "CreateRepositoryChangeRequestResponse": { + "AccessReason": { "type": "object", "properties": { - "id": { + "kind": { "type": "string", - "minLength": 1, - "maxLength": 54 + "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" + ] }, - "html_url": { + "result": { "type": "string", - "maxLength": 2048, - "format": "uri", - "description": "Absolute dashboard URL for this resource. OUTPUT_ONLY.", - "example": "https://akua.dev/repository-change-requests/rcr_j572abc123def456" + "enum": [ + "allowed", + "denied", + "not_evaluated" + ] }, - "workspace_id": { - "type": "string", - "minLength": 1, - "maxLength": 53 + "key": { + "type": "string" }, - "parent_repository_id": { - "type": "string", - "minLength": 1, - "maxLength": 55 + "source": { + "type": "string" }, - "fork_repository_id": { - "type": "string", - "minLength": 1, - "maxLength": 55 + "message": { + "type": "string" }, - "state": { - "type": "string", - "enum": [ - "AWAITING_CHANGES", - "VALIDATING", - "READY", - "ACCEPTING", - "ACCEPTED", - "REJECTED", - "WITHDRAWN", - "EXPIRED", - "FAILED" - ], - "description": "Repository change request lifecycle state" + "metric": { + "type": "string" }, - "change_type": { + "scope": { "type": "string", "enum": [ - "manifest_patch", - "inputs_change", - "package_change", - "unknown" + "global", + "organization", + "workspace", + "user" ] }, - "created_by_type": { - "type": "string", - "enum": [ - "user", - "wizard", - "agent" - ] + "limit": { + "type": "number" }, - "created_by_id": { + "usage": { + "type": "number" + }, + "remaining": { + "type": "number" + }, + "resourceId": { + "type": "string" + }, + "resourceType": { + "type": "string" + }, + "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 + }, + { + "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 }, - "remediation_evidence": { + { "type": "object", - "nullable": true, "properties": { - "summary": { - "type": "string", - "minLength": 1, - "maxLength": 2000 + "subject": { + "$ref": "#/components/schemas/AccessSubject" }, - "likely_fix": { + "permission": { "type": "string", - "minLength": 1, - "maxLength": 2000 + "enum": [ + "offers.reject_channel_offer" + ] }, - "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 + "resource": { + "$ref": "#/components/schemas/OfferChannelModerationResource" + }, + "context": { + "$ref": "#/components/schemas/OfferChannelDecisionContext" } }, "required": [ - "summary", - "likely_fix", - "resource_refs" + "permission", + "resource" ], "additionalProperties": false }, - "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)" - }, - "rejection_reason": { - "type": "string", - "nullable": true - }, - "etag": { - "type": "string" - } - }, - "required": [ - "id", - "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" - ] - }, - "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." + "subject": { + "$ref": "#/components/schemas/AccessSubject" }, - "kind": { + "permission": { "type": "string", "enum": [ - "user" + "workspaces.inspect_class" ] + }, + "resource": { + "$ref": "#/components/schemas/WorkspaceClassResource" } }, "required": [ - "parent_repository_id", - "kind" + "permission", + "resource" ], "additionalProperties": false }, { "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." + "subject": { + "$ref": "#/components/schemas/AccessSubject" }, - "kind": { + "permission": { "type": "string", "enum": [ - "wizard" + "workspaces.inspect_membership" ] + }, + "resource": { + "$ref": "#/components/schemas/WorkspaceMembershipResource" } }, "required": [ - "parent_repository_id", - "kind" + "permission", + "resource" ], "additionalProperties": false }, { "type": "object", "properties": { - "parent_repository_id": { + "subject": { + "$ref": "#/components/schemas/AccessSubject" + }, + "permission": { "type": "string", - "minLength": 1, - "maxLength": 55, - "description": "Repository that will receive the accepted change request." + "enum": [ + "products.create" + ] }, - "expires_at_seconds": { - "type": "integer", - "minimum": 0, - "exclusiveMinimum": true, - "description": "Seconds until the repository change request expires." + "resource": { + "$ref": "#/components/schemas/ProductCockpitResource" + } + }, + "required": [ + "permission" + ], + "additionalProperties": false + }, + { + "type": "object", + "properties": { + "subject": { + "$ref": "#/components/schemas/AccessSubject" }, - "kind": { + "permission": { "type": "string", "enum": [ - "agent" + "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" ], - "description": "Agent actor creating the change request." + "additionalProperties": false + } + }, + "required": [ + "permission", + "resource" + ], + "additionalProperties": false + }, + { + "type": "object", + "properties": { + "subject": { + "$ref": "#/components/schemas/AccessSubject" }, - "agent_id": { + "permission": { "type": "string", - "minLength": 1, - "maxLength": 54, - "description": "Agent that found the likely source or configuration fix." + "enum": [ + "products.update" + ] }, - "remediation_evidence": { + "resource": { "type": "object", "properties": { - "summary": { + "product_id": { "type": "string", "minLength": 1, - "maxLength": 2000 + "maxLength": 55 }, - "likely_fix": { + "workspace_id": { "type": "string", "minLength": 1, - "maxLength": 2000 + "maxLength": 53 }, - "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 + "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": [ - "summary", - "likely_fix", - "resource_refs" + "product_id", + "workspace_id" ], - "additionalProperties": false, - "description": "Evidence that the agent found a likely source or configuration fix before opening the change request." + "additionalProperties": false } }, "required": [ - "parent_repository_id", - "kind", - "agent_id", - "remediation_evidence" + "permission", + "resource" ], "additionalProperties": false - } - ] - }, - "CreateRepositoryChangeRequestTokenResponse": { - "type": "object", - "properties": { - "repository_change_request_id": { - "type": "string", - "minLength": 1, - "maxLength": 54 - }, - "fork_remote_url": { - "type": "string", - "format": "uri" - }, - "fork_write_token": { - "type": "string" }, - "expires_at": { - "type": "integer", - "minimum": 0, - "description": "Unix timestamp (seconds)" - } - }, - "required": [ - "repository_change_request_id", - "fork_remote_url", - "fork_write_token", - "expires_at" - ] - }, - "CreateRepositoryChangeRequestTokenBody": { - "type": "object", - "properties": { - "scope": { - "type": "string", - "enum": [ - "read", - "write" + { + "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" ], - "default": "write" - }, - "expires_in_seconds": { - "type": "integer", - "minimum": 0, - "exclusiveMinimum": true, - "maximum": 3600, - "description": "Seconds until the fork write token expires. Maximum is one hour." - } - }, - "additionalProperties": false - }, - "RepositoryChangeRequestList": { - "type": "object", - "properties": { - "data": { - "type": "array", - "items": { - "$ref": "#/components/schemas/RepositoryChangeRequest" - } - }, - "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" - ] - }, - "RepositoryChangeRequest": { - "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" - }, - "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 + "additionalProperties": false }, - "state": { - "type": "string", - "enum": [ - "AWAITING_CHANGES", - "VALIDATING", - "READY", - "ACCEPTING", - "ACCEPTED", - "REJECTED", - "WITHDRAWN", - "EXPIRED", - "FAILED" + { + "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" ], - "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" + "additionalProperties": false }, - "remediation_evidence": { + { "type": "object", - "nullable": true, "properties": { - "summary": { - "type": "string", - "minLength": 1, - "maxLength": 2000 + "subject": { + "$ref": "#/components/schemas/AccessSubject" }, - "likely_fix": { + "permission": { "type": "string", - "minLength": 1, - "maxLength": 2000 + "enum": [ + "products.inspect_readiness" + ] }, - "resource_refs": { - "type": "array", - "items": { - "type": "object", - "properties": { - "resource": { - "type": "string", - "minLength": 1, - "maxLength": 120 - }, - "id": { - "type": "string", - "minLength": 1, - "maxLength": 200 - } + "resource": { + "type": "object", + "properties": { + "product_id": { + "type": "string", + "minLength": 1, + "maxLength": 55 }, - "required": [ - "resource", - "id" - ], - "additionalProperties": false + "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" + ] + } }, - "minItems": 1, - "maxItems": 20 + "required": [ + "product_id", + "workspace_id" + ], + "additionalProperties": false } }, "required": [ - "summary", - "likely_fix", - "resource_refs" + "permission", + "resource" ], "additionalProperties": false }, - "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)" - }, - "rejection_reason": { - "type": "string", - "nullable": true - }, - "etag": { - "type": "string" - } - }, - "required": [ - "id", - "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" - ] - }, - "AcceptRepositoryChangeRequestResponse": { - "type": "object", - "properties": { - "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": [ - "repository_change_request_id", - "operation_id", - "accepted_at" - ] - }, - "RejectRepositoryChangeRequestResponse": { - "type": "object", - "properties": { - "repository_change_request_id": { - "type": "string", - "minLength": 1, - "maxLength": 54 - }, - "rejected_at": { - "type": "integer", - "minimum": 0, - "description": "Unix timestamp (seconds)" - } - }, - "required": [ - "repository_change_request_id", - "rejected_at" - ] - }, - "RejectRepositoryChangeRequestBody": { - "type": "object", - "properties": { - "rejection_reason": { - "type": "string", - "minLength": 1, - "maxLength": 2000, - "description": "Reason shown in audit logs and review UI." - } - }, - "required": [ - "rejection_reason" - ], - "additionalProperties": false - }, - "WithdrawRepositoryChangeRequestResponse": { - "type": "object", - "properties": { - "repository_change_request_id": { - "type": "string", - "minLength": 1, - "maxLength": 54 - }, - "withdrawn_at": { - "type": "integer", - "minimum": 0, - "description": "Unix timestamp (seconds)" - } - }, - "required": [ - "repository_change_request_id", - "withdrawn_at" - ] - }, - "Agent": { - "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 - }, - "name": { - "type": "string" - }, - "description": { - "type": "string", - "nullable": true - }, - "instructions": { - "type": "string" - }, - "state": { - "type": "string", - "enum": [ - "ENABLED", - "ARCHIVED" - ] - }, - "origin": { - "type": "string", - "enum": [ - "PLATFORM", - "USER", - "SYSTEM" - ] - }, - "capabilities": { - "type": "array", - "items": { - "type": "string", - "enum": [ - "CHAT", - "CODING", - "AMBIENT" - ] - } - }, - "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", - "workspace_id", - "organization_id", - "name", - "description", - "instructions", - "state", - "origin", - "capabilities", - "ambient", - "model_policy", - "created_by", - "usage_summary", - "created_at", - "updated_at", - "etag" - ] - }, - "AgentAmbientConfig": { - "type": "object", - "nullable": true, - "properties": { - "enabled": { - "type": "boolean" - }, - "policy": { - "$ref": "#/components/schemas/AgentAmbientPolicy" - }, - "triggers": { - "type": "array", - "items": { - "$ref": "#/components/schemas/AgentAmbientTrigger" - }, - "maxItems": 50 - } - }, - "required": [ - "enabled", - "triggers" - ] - }, - "AgentAmbientPolicy": { - "type": "object", - "properties": { - "remediation_mode": { - "type": "string", - "enum": [ - "READ_ONLY", - "APPROVAL_GATED" - ] - }, - "allowed_resource_scopes": { - "type": "array", - "items": { - "$ref": "#/components/schemas/AgentAmbientResourceScope" + { + "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 + } }, - "maxItems": 100 - }, - "max_spend_cents_per_trigger": { - "type": "integer", - "minimum": 0 - } - }, - "required": [ - "remediation_mode", - "allowed_resource_scopes" - ] - }, - "AgentAmbientResourceScope": { - "type": "object", - "properties": { - "type": { - "type": "string", - "minLength": 1, - "maxLength": 120 - }, - "id": { - "type": "string", - "minLength": 1, - "maxLength": 200 - } - }, - "required": [ - "type" - ] - }, - "AgentAmbientTrigger": { - "type": "object", - "properties": { - "trigger_id": { - "type": "string", - "minLength": 1, - "maxLength": 120 - }, - "type": { - "type": "string", - "enum": [ - "INSTALL_STATE", - "CLUSTER_DEGRADATION", - "SECURITY_FINDING", - "QUOTA_PRESSURE", - "COST_ANOMALY", - "MANUAL_TEST" - ] - }, - "state": { - "type": "string", - "enum": [ - "ENABLED", - "DISABLED" - ] - }, - "severity_min": { - "type": "string", - "enum": [ - "LOW", - "MEDIUM", - "HIGH", - "CRITICAL" - ] - }, - "runtime_hint": { - "type": "string", - "enum": [ - "AUTO", - "CODE_MODE", - "RETAINED_RUNTIME" - ] - }, - "cooldown_seconds": { - "type": "integer", - "minimum": 0, - "exclusiveMinimum": true + "required": [ + "permission", + "resource" + ], + "additionalProperties": false }, - "relationship_scope": { - "anyOf": [ - { + { + "type": "object", + "properties": { + "subject": { + "$ref": "#/components/schemas/AccessSubject" + }, + "permission": { + "type": "string", + "enum": [ + "products.inspect_channels" + ] + }, + "resource": { "type": "object", "properties": { - "type": { + "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": [ - "WORKSPACE" + "draft", + "active", + "archived" ] } }, "required": [ - "type" + "product_id", + "workspace_id" + ], + "additionalProperties": false + } + }, + "required": [ + "permission", + "resource" + ], + "additionalProperties": false + }, + { + "type": "object", + "properties": { + "subject": { + "$ref": "#/components/schemas/AccessSubject" + }, + "permission": { + "type": "string", + "enum": [ + "products.inspect_installs" ] }, - { + "resource": { "type": "object", "properties": { - "type": { + "product_id": { "type": "string", - "enum": [ - "SELLER_CUSTOMER" - ] + "minLength": 1, + "maxLength": 55 }, - "seller_workspace_id": { + "workspace_id": { "type": "string", "minLength": 1, "maxLength": 53 }, - "customer_workspace_id": { + "package_id": { "type": "string", "minLength": 1, - "maxLength": 53 + "maxLength": 54 }, - "support_relationship_id": { + "package_version_id": { "type": "string", "minLength": 1, - "maxLength": 200 + "maxLength": 55 + }, + "resource_state": { + "type": "string", + "enum": [ + "draft", + "active", + "archived" + ] } }, "required": [ - "type", - "seller_workspace_id", - "customer_workspace_id" - ] + "product_id", + "workspace_id" + ], + "additionalProperties": false } - ] - }, - "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 + "required": [ + "permission", + "resource" + ], + "additionalProperties": false }, - "quiet_hours": { + { "type": "object", "properties": { - "timezone": { - "type": "string", - "minLength": 1, - "maxLength": 120 + "subject": { + "$ref": "#/components/schemas/AccessSubject" }, - "start": { + "permission": { "type": "string", - "pattern": "^\\d{2}:\\d{2}$" + "enum": [ + "packages.create" + ] }, - "end": { - "type": "string", - "pattern": "^\\d{2}:\\d{2}$" + "resource": { + "$ref": "#/components/schemas/PackageCockpitResource" } }, "required": [ - "timezone", - "start", - "end" - ] - } - }, - "required": [ - "trigger_id", - "type", - "state", - "runtime_hint" - ] - }, - "AgentModelPolicy": { - "type": "object", - "properties": { - "default_model": { - "type": "string", - "minLength": 1, - "maxLength": 120 - }, - "billing_mode": { - "type": "string", - "enum": [ - "PLATFORM_SUBSCRIPTION", - "PLATFORM_API", - "WORKSPACE_BYOK" - ] - }, - "credential_secret_id": { - "type": "string", - "nullable": true, - "minLength": 1, - "maxLength": 54 - }, - "allowed_models": { - "type": "array", - "items": { - "type": "string", - "minLength": 1, - "maxLength": 120 - }, - "minItems": 1, - "maxItems": 50 + "permission" + ], + "additionalProperties": false }, - "severity_model_overrides": { - "type": "array", - "items": { - "type": "object", - "properties": { - "severity": { - "type": "string", - "enum": [ - "LOW", - "MEDIUM", - "HIGH", - "CRITICAL" - ] - }, - "model": { - "type": "string", - "minLength": 1, - "maxLength": 120 - } + { + "type": "object", + "properties": { + "subject": { + "$ref": "#/components/schemas/AccessSubject" }, - "required": [ - "severity", - "model" - ] + "permission": { + "type": "string", + "enum": [ + "packages.import_published_package" + ] + }, + "resource": { + "$ref": "#/components/schemas/PackageCockpitResource" + } }, - "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": [ - "default_model", - "billing_mode", - "credential_secret_id", - "allowed_models" - ] - }, - "AgentUsageSummary": { - "type": "object", - "properties": { - "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": [ - "provider_cost_cents", - "provider_token_count", - "runtime_compute_seconds", - "runtime_storage_gb_hours", - "mcp_call_count", - "api_call_count", - "ambient_trigger_count" - ] - }, - "AgentList": { - "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": { - "type": "string", - "nullable": true, - "description": "Opaque cursor for the next page, or null if no more pages." - } - }, - "required": [ - "data", - "has_more", - "next_cursor" - ] - }, - "AgentSkillList": { - "type": "object", - "properties": { - "data": { - "type": "array", - "items": { - "$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", - "has_more", - "next_cursor" - ] - }, - "AgentSkill": { - "type": "object", - "properties": { - "id": { - "type": "string", - "minLength": 1, - "maxLength": 54 - }, - "workspace_id": { - "type": "string", - "minLength": 1, - "maxLength": 53 - }, - "name": { - "type": "string" - }, - "version": { - "type": "string" - }, - "description": { - "type": "string" - }, - "state": { - "type": "string", - "enum": [ - "PUBLISHED", - "ARCHIVED" - ] + "required": [ + "permission" + ], + "additionalProperties": false }, - "required_grants": { - "type": "array", - "items": { - "type": "object", - "properties": { - "resource": { - "type": "string" - }, - "actions": { - "type": "array", - "items": { - "type": "string" - } - } + { + "type": "object", + "properties": { + "subject": { + "$ref": "#/components/schemas/AccessSubject" }, - "required": [ - "resource", - "actions" - ] - } - }, - "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", - "workspace_id", - "name", - "version", - "description", - "state", - "required_grants", - "supported_capabilities", - "created_at", - "updated_at", - "etag" - ] - }, - "AgentTemplateList": { - "type": "object", - "properties": { - "data": { - "type": "array", - "items": { - "$ref": "#/components/schemas/AgentTemplate" - } - }, - "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" - ] - }, - "AgentTemplate": { - "type": "object", - "properties": { - "id": { - "type": "string", - "minLength": 1, - "maxLength": 56 - }, - "name": { - "type": "string" - }, - "description": { - "type": "string" - }, - "instructions": { - "type": "string" + "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 }, - "state": { - "type": "string", - "enum": [ - "PUBLISHED" - ] + { + "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 }, - "capabilities": { - "type": "array", - "items": { - "type": "string", - "enum": [ - "CHAT", - "CODING", - "AMBIENT" - ] - } + { + "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 }, - "ambient": { - "$ref": "#/components/schemas/AgentAmbientConfig" + { + "type": "object", + "properties": { + "subject": { + "$ref": "#/components/schemas/AccessSubject" + }, + "permission": { + "type": "string", + "enum": [ + "clusters.update" + ] + }, + "resource": { + "$ref": "#/components/schemas/ClusterCockpitResource" + } + }, + "required": [ + "permission", + "resource" + ], + "additionalProperties": false }, - "trigger_filters": { - "type": "array", - "items": { - "$ref": "#/components/schemas/AgentTemplateTriggerFilter" - } + { + "type": "object", + "properties": { + "subject": { + "$ref": "#/components/schemas/AccessSubject" + }, + "permission": { + "type": "string", + "enum": [ + "clusters.delete" + ] + }, + "resource": { + "$ref": "#/components/schemas/ClusterCockpitResource" + } + }, + "required": [ + "permission", + "resource" + ], + "additionalProperties": false }, - "model_policy": { - "$ref": "#/components/schemas/AgentModelPolicy" + { + "type": "object", + "properties": { + "subject": { + "$ref": "#/components/schemas/AccessSubject" + }, + "permission": { + "type": "string", + "enum": [ + "clusters.suspend" + ] + }, + "resource": { + "$ref": "#/components/schemas/ClusterCockpitResource" + } + }, + "required": [ + "permission", + "resource" + ], + "additionalProperties": false }, - "runtime_policy": { - "$ref": "#/components/schemas/AgentRuntimePolicy" + { + "type": "object", + "properties": { + "subject": { + "$ref": "#/components/schemas/AccessSubject" + }, + "permission": { + "type": "string", + "enum": [ + "clusters.resume" + ] + }, + "resource": { + "$ref": "#/components/schemas/ClusterCockpitResource" + } + }, + "required": [ + "permission", + "resource" + ], + "additionalProperties": false }, - "remediation_policy": { - "$ref": "#/components/schemas/AgentTemplateRemediationPolicy" + { + "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 }, - "grants": { - "type": "array", - "items": { - "type": "object", - "properties": { - "resource": { - "type": "string" - }, - "actions": { - "type": "array", - "items": { - "type": "string" - } - } + { + "type": "object", + "properties": { + "subject": { + "$ref": "#/components/schemas/AccessSubject" }, - "required": [ - "resource", - "actions" - ] - } + "permission": { + "type": "string", + "enum": [ + "clusters.get_kubeconfig" + ] + }, + "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": [ + "clusters.create_worker_bootstrap" + ] + }, + "resource": { + "$ref": "#/components/schemas/ClusterCockpitResource" + } + }, + "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": [ + "clusters.revoke_worker_bootstrap" + ] + }, + "resource": { + "$ref": "#/components/schemas/ClusterCockpitResource" + } + }, + "required": [ + "permission", + "resource" + ], + "additionalProperties": false }, - "etag": { - "type": "string" - } - }, - "required": [ - "id", - "name", - "description", - "instructions", - "state", - "capabilities", - "ambient", - "trigger_filters", - "model_policy", - "runtime_policy", - "remediation_policy", - "grants", - "created_at", - "updated_at", - "etag" - ] - }, - "AgentTemplateTriggerFilter": { - "type": "object", - "properties": { - "type": { - "type": "string", - "enum": [ - "INSTALL_STATE", - "CLUSTER_DEGRADATION", - "SECURITY_FINDING", - "QUOTA_PRESSURE", - "COST_ANOMALY", - "MANUAL_TEST" - ] + { + "type": "object", + "properties": { + "subject": { + "$ref": "#/components/schemas/AccessSubject" + }, + "permission": { + "type": "string", + "enum": [ + "machines.create" + ] + }, + "resource": { + "$ref": "#/components/schemas/ClusterCockpitResource" + } + }, + "required": [ + "permission", + "resource" + ], + "additionalProperties": false }, - "resource_types": { - "type": "array", - "items": { - "type": "string" - } + { + "type": "object", + "properties": { + "subject": { + "$ref": "#/components/schemas/AccessSubject" + }, + "permission": { + "type": "string", + "enum": [ + "machines.update" + ] + }, + "resource": { + "$ref": "#/components/schemas/MachineCockpitResource" + } + }, + "required": [ + "permission", + "resource" + ], + "additionalProperties": false }, - "states": { - "type": "array", - "items": { - "type": "string" - } + { + "type": "object", + "properties": { + "subject": { + "$ref": "#/components/schemas/AccessSubject" + }, + "permission": { + "type": "string", + "enum": [ + "machines.delete" + ] + }, + "resource": { + "$ref": "#/components/schemas/MachineCockpitResource" + } + }, + "required": [ + "permission", + "resource" + ], + "additionalProperties": false }, - "min_severity": { - "type": "string", - "enum": [ - "LOW", - "MEDIUM", - "HIGH", - "CRITICAL" - ] - } - }, - "required": [ - "type", - "resource_types", - "states" - ] - }, - "AgentRuntimePolicy": { - "type": "object", - "properties": { - "execution_environment": { - "type": "string", - "enum": [ - "CODE_MODE_FIRST", - "RETAINED_RUNTIME_ALLOWED", - "NO_RETAINED_RUNTIME" - ] + { + "type": "object", + "properties": { + "subject": { + "$ref": "#/components/schemas/AccessSubject" + }, + "permission": { + "type": "string", + "enum": [ + "machines.suspend" + ] + }, + "resource": { + "$ref": "#/components/schemas/MachineCockpitResource" + } + }, + "required": [ + "permission", + "resource" + ], + "additionalProperties": false }, - "filesystem": { - "type": "string" + { + "type": "object", + "properties": { + "subject": { + "$ref": "#/components/schemas/AccessSubject" + }, + "permission": { + "type": "string", + "enum": [ + "machines.resume" + ] + }, + "resource": { + "$ref": "#/components/schemas/MachineCockpitResource" + } + }, + "required": [ + "permission", + "resource" + ], + "additionalProperties": false }, - "shell": { - "type": "string" + { + "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 }, - "browser": { - "type": "string" - } - }, - "required": [ - "execution_environment", - "filesystem", - "shell", - "browser" - ] - }, - "AgentTemplateRemediationPolicy": { - "type": "object", - "nullable": true, - "properties": { - "repository_change_request": { - "$ref": "#/components/schemas/AgentTemplateRepositoryChangeRequestRemediationPolicy" + { + "type": "object", + "properties": { + "subject": { + "$ref": "#/components/schemas/AccessSubject" + }, + "permission": { + "type": "string", + "enum": [ + "installs.create" + ] + }, + "resource": { + "$ref": "#/components/schemas/ClusterCockpitResource" + } + }, + "required": [ + "permission", + "resource" + ], + "additionalProperties": false + }, + { + "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": [ - "repository_change_request" ] }, - "AgentTemplateRepositoryChangeRequestRemediationPolicy": { + "AccessSubject": { "type": "object", "properties": { - "mode": { + "user_id": { "type": "string", - "enum": [ - "LIKELY_SOURCE_OR_CONFIG_FIX_ONLY" - ] - }, - "evidence_required": { - "type": "boolean" + "minLength": 1 }, - "allowed_actions": { - "type": "array", - "items": { - "type": "string" - } + "organization_id": { + "type": "string", + "minLength": 1, + "maxLength": 54 }, - "blocked_actions": { - "type": "array", - "items": { - "type": "string" - } + "workspace_id": { + "type": "string", + "minLength": 1, + "maxLength": 53 } }, - "required": [ - "mode", - "evidence_required", - "allowed_actions", - "blocked_actions" - ] + "additionalProperties": false }, - "AgentPreference": { + "OfferChannelCreateResource": { "type": "object", "properties": { - "id": { + "offer_channel_id": { "type": "string", "minLength": 1, "maxLength": 54 }, - "workspace_id": { + "target_workspace_id": { "type": "string", "minLength": 1, "maxLength": 53 }, - "user_id": { - "type": "string" + "product_id": { + "type": "string", + "minLength": 1, + "maxLength": 55 }, - "communication_profile": { + "commercial_mode": { "type": "string", "enum": [ - "BEGINNER", - "INTERMEDIATE", - "ADVANCED", - "EXPERT", - "ADAPTIVE" + "paid", + "non_billable_test" ] - }, - "learning_mode_enabled": { - "type": "boolean" - }, - "seen_concepts": { - "type": "array", - "items": { - "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", - "user_id", - "communication_profile", - "learning_mode_enabled", - "seen_concepts", - "created_at", - "updated_at", - "etag" - ] + "offer_channel_id", + "product_id", + "commercial_mode" + ], + "additionalProperties": false }, - "SandboxOperationsSummary": { + "OfferChannelDecisionContext": { "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 - }, - "estimated_retained_filesystem_gb_hours": { - "type": "number", - "minimum": 0 - }, - "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" - ] - } - }, - "average_cold_start_latency_ms": { - "type": "number", - "nullable": true, - "minimum": 0 + "selected_organization_id": { + "type": "string", + "minLength": 1, + "maxLength": 54 }, - "average_resume_latency_ms": { - "type": "number", - "nullable": true, - "minimum": 0 + "stripe_mode": { + "type": "string", + "enum": [ + "live", + "test", + "sandbox" + ] } }, - "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" - ] + "additionalProperties": false }, - "AgentSession": { + "NonChannelPaidProductOfferResource": { "type": "object", "properties": { - "id": { - "type": "string", - "minLength": 1, - "maxLength": 54 - }, "workspace_id": { "type": "string", "minLength": 1, "maxLength": 53 }, - "organization_id": { + "product_id": { "type": "string", - "nullable": true, "minLength": 1, - "maxLength": 54 + "maxLength": 55 }, - "agent_id": { + "package_version_id": { "type": "string", "minLength": 1, - "maxLength": 54 - }, - "state": { - "type": "string", - "enum": [ - "ACTIVE", - "WAITING_FOR_INPUT", - "WAITING_FOR_PERMISSION", - "COMPLETED", - "FAILED", - "CANCELLED", - "ARCHIVED" - ] - }, - "origin": { - "type": "string", - "enum": [ - "DASHBOARD", - "API", - "MCP", - "ACP", - "AMBIENT", - "SYSTEM" - ] + "maxLength": 55 }, - "title": { + "target_workspace_id": { "type": "string", - "nullable": true + "minLength": 1, + "maxLength": 53 }, - "communication_profile": { + "commercial_mode": { "type": "string", "enum": [ - "BEGINNER", - "INTERMEDIATE", - "ADVANCED", - "EXPERT", - "ADAPTIVE" + "paid" ] - }, - "created_by": { - "type": "string" - }, - "parent_session_id": { + } + }, + "required": [ + "workspace_id", + "product_id", + "package_version_id", + "commercial_mode" + ], + "additionalProperties": false + }, + "NonBillableTestOfferResource": { + "type": "object", + "properties": { + "workspace_id": { "type": "string", - "nullable": true, "minLength": 1, - "maxLength": 54 + "maxLength": 53 }, - "forked_from_session_id": { + "product_id": { "type": "string", - "nullable": true, "minLength": 1, - "maxLength": 54 + "maxLength": 55 }, - "spawned_by_turn_id": { + "package_version_id": { "type": "string", - "nullable": true, "minLength": 1, - "maxLength": 54 - }, - "agent_role": { - "type": "string", - "nullable": true + "maxLength": 55 }, - "current_sandbox_id": { + "target_workspace_id": { "type": "string", - "nullable": true, "minLength": 1, - "maxLength": 54 + "maxLength": 53 }, - "last_event_cursor": { + "target_workspace_class": { "type": "string", - "nullable": true - }, - "events_retained_until": { - "type": "integer", - "minimum": 0, - "description": "Unix timestamp (seconds)" - }, - "filesystem_retained_until": { - "type": "integer", - "minimum": 0, - "description": "Unix timestamp (seconds)" - }, - "filesystem_pinned": { - "type": "boolean" - }, - "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)" + "enum": [ + "standard", + "platform", + "sandbox" + ] }, - "etag": { - "type": "string" + "commercial_mode": { + "type": "string", + "enum": [ + "non_billable_test" + ] } }, "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" - ] + "product_id", + "package_version_id", + "commercial_mode" + ], + "additionalProperties": false }, - "AgentSessionList": { + "OfferChannelCreateDecisionResource": { "type": "object", "properties": { - "data": { - "type": "array", - "items": { - "$ref": "#/components/schemas/AgentSession" - } + "workspace_id": { + "type": "string", + "minLength": 1, + "maxLength": 53 }, - "has_more": { - "type": "boolean", - "description": "True if more items exist after this page." + "product_id": { + "type": "string", + "minLength": 1, + "maxLength": 55 }, - "next_cursor": { + "partner_organization_id": { "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" - } + "minLength": 1, + "maxLength": 54 } }, "required": [ - "data" + "workspace_id" ], "additionalProperties": false }, - "AgentWorkConflict": { + "OfferChannelInspectResource": { "type": "object", "properties": { - "agent_id": { - "type": "string", - "minLength": 1, - "maxLength": 54 - }, - "session_id": { - "type": "string", - "minLength": 1, - "maxLength": 54 - }, - "turn_id": { + "workspace_id": { "type": "string", "minLength": 1, - "maxLength": 54 + "maxLength": 53 }, - "event_id": { + "offer_channel_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": { + "product_id": { "type": "string", "minLength": 1, - "maxLength": 500 - }, - "created_at": { - "type": "integer", - "minimum": 0, - "description": "Unix timestamp (seconds)" + "maxLength": 55 } }, "required": [ - "agent_id", - "session_id", - "turn_id", - "event_id", - "event_type", - "reason", - "created_at" + "workspace_id" ], "additionalProperties": false }, - "SetAgentSessionRetentionBody": { + "ChannelPolicyApproveResource": { "type": "object", "properties": { - "events_retained_until": { - "type": "integer", - "minimum": 0, - "description": "Unix timestamp (seconds)" + "workspace_id": { + "type": "string", + "minLength": 1, + "maxLength": 53 }, - "filesystem_retained_until": { - "type": "integer", - "minimum": 0, - "description": "Unix timestamp (seconds)" + "offer_channel_id": { + "type": "string", + "minLength": 1, + "maxLength": 54 }, - "filesystem_pinned": { - "type": "boolean" + "channel_policy_id": { + "type": "string", + "minLength": 1, + "maxLength": 56 }, - "retention_reason": { + "resource_state": { "type": "string", "enum": [ - "SESSION_ACTIVE", - "PINNED", - "POLICY", - "TERMINAL_GRACE", - "MANUAL_DELETE" + "draft" ] } }, "required": [ - "events_retained_until", - "filesystem_retained_until", - "filesystem_pinned", - "retention_reason" + "workspace_id", + "offer_channel_id", + "channel_policy_id", + "resource_state" ], "additionalProperties": false }, - "AgentTurn": { + "ChannelPolicyActivateResource": { "type": "object", - "properties": { - "id": { - "type": "string", - "minLength": 1, - "maxLength": 54 - }, + "properties": { "workspace_id": { "type": "string", "minLength": 1, "maxLength": 53 }, - "organization_id": { - "type": "string", - "nullable": true, - "minLength": 1, - "maxLength": 54 - }, - "agent_id": { + "offer_channel_id": { "type": "string", "minLength": 1, "maxLength": 54 }, - "session_id": { + "channel_policy_id": { "type": "string", "minLength": 1, - "maxLength": 54 + "maxLength": 56 }, - "state": { + "resource_state": { "type": "string", "enum": [ - "QUEUED", - "RUNNING", - "WAITING_FOR_INPUT", - "WAITING_FOR_PERMISSION", - "COMPLETED", - "FAILED", - "CANCELLED" + "approved" ] + } + }, + "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 }, - "origin": { + "offer_channel_id": { "type": "string", - "enum": [ - "DASHBOARD", - "API", - "MCP", - "ACP", - "AMBIENT", - "SYSTEM" - ] + "minLength": 1, + "maxLength": 54 }, - "input": { - "type": "object", - "properties": { - "type": { - "type": "string", - "enum": [ - "message" - ] - }, - "content": { - "type": "string" - } - }, - "required": [ - "type", - "content" - ] + "owner_workspace_id": { + "type": "string", + "minLength": 1, + "maxLength": 53 }, - "runtime_hint": { + "resource_state": { "type": "string", "enum": [ - "AUTO", - "CODE_MODE", - "RETAINED_RUNTIME" + "pending_approval", + "approved", + "rejected" ] }, - "model": { + "platform_policy_snapshot_id": { "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)" + "minLength": 1, + "x-platform-visibility": "ADMIN" }, - "runtime_decision": { + "partner_price_band_key": { "type": "string", - "nullable": true, - "enum": [ - "ALLOWED", - "DENIED", - "APPROVAL_REQUIRED", - null - ] - }, - "decision_reason": { + "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", - "nullable": true + "minLength": 1, + "maxLength": 53 }, - "resolved_execution_mode": { + "required_class": { "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" + "standard", + "platform", + "sandbox" ] - }, - "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" - ] + "workspace_id" + ], + "additionalProperties": false }, - "AgentTurnList": { + "WorkspaceMembershipResource": { "type": "object", "properties": { - "data": { + "workspace_id": { + "type": "string", + "minLength": 1, + "maxLength": 53 + }, + "required_roles": { "type": "array", "items": { - "$ref": "#/components/schemas/AgentTurn" + "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 }, - "AgentEvent": { + "ProductCockpitResource": { "type": "object", "properties": { - "id": { + "product_id": { "type": "string", "minLength": 1, - "maxLength": 54 + "maxLength": 55 }, "workspace_id": { "type": "string", "minLength": 1, "maxLength": 53 }, - "agent_id": { - "type": "string", - "minLength": 1, - "maxLength": 54 - }, - "session_id": { + "package_id": { "type": "string", "minLength": 1, "maxLength": 54 }, - "turn_id": { + "package_version_id": { "type": "string", "minLength": 1, - "maxLength": 54 - }, - "sequence": { - "type": "integer" - }, - "cursor": { - "type": "string" + "maxLength": 55 }, - "type": { + "resource_state": { "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" + "draft", + "active", + "archived" ] - }, - "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" - ] + "workspace_id" + ], + "additionalProperties": false }, - "AgentProviderExchangeList": { + "PackageCockpitResource": { "type": "object", "properties": { - "data": { - "type": "array", - "items": { - "$ref": "#/components/schemas/AgentProviderExchange" - } + "package_id": { + "type": "string", + "minLength": 1, + "maxLength": 54 }, - "has_more": { - "type": "boolean", - "description": "True if more items exist after this page." + "package_version_id": { + "type": "string", + "minLength": 1, + "maxLength": 55 }, - "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" - ] + "workspace_id" + ], + "additionalProperties": false }, - "AgentProviderExchange": { + "ClusterCockpitResource": { "type": "object", "properties": { - "id": { + "workspace_id": { "type": "string", "minLength": 1, - "maxLength": 54 + "maxLength": 53 }, + "cluster_id": { + "type": "string", + "minLength": 1, + "maxLength": 54 + } + }, + "required": [ + "workspace_id", + "cluster_id" + ], + "additionalProperties": false + }, + "MachineCockpitResource": { + "type": "object", + "properties": { "workspace_id": { "type": "string", "minLength": 1, "maxLength": 53 }, - "organization_id": { + "cluster_id": { "type": "string", - "nullable": true, "minLength": 1, "maxLength": 54 }, - "agent_id": { + "machine_id": { "type": "string", "minLength": 1, "maxLength": 54 + } + }, + "required": [ + "workspace_id", + "cluster_id", + "machine_id" + ], + "additionalProperties": false + }, + "CatalogActionExplainResource": { + "type": "object", + "properties": { + "action_id": { + "type": "string", + "minLength": 1 }, - "session_id": { + "workspace_id": { "type": "string", "minLength": 1, - "maxLength": 54 + "maxLength": 53 }, - "turn_id": { + "organization_id": { "type": "string", "minLength": 1, "maxLength": 54 }, - "provider": { - "type": "string" - }, - "model": { + "user_id": { "type": "string", - "nullable": true + "minLength": 1 }, - "fallback_from_model": { + "product_id": { "type": "string", - "nullable": true + "minLength": 1, + "maxLength": 55 }, - "fallback_reason": { + "package_id": { "type": "string", - "nullable": true + "minLength": 1, + "maxLength": 54 }, - "credential_mode": { + "package_version_id": { "type": "string", - "enum": [ - "PLATFORM_SUBSCRIPTION", - "PLATFORM_API", - "WORKSPACE_BYOK" - ] + "minLength": 1, + "maxLength": 55 }, - "credential_secret_id": { + "offer_id": { "type": "string", - "nullable": true, "minLength": 1, - "maxLength": 54 - }, - "requested_at": { - "type": "integer", - "minimum": 0, - "description": "Unix timestamp (seconds)" - }, - "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 - }, - "output": { - "type": "integer", - "minimum": 0 - }, - "total": { - "type": "integer", - "minimum": 0 - } - } + "maxLength": 56 }, - "message_summary": { + "offer_channel_id": { "type": "string", - "nullable": true + "minLength": 1, + "maxLength": 54 }, - "upstream_error_code": { + "channel_policy_id": { "type": "string", - "nullable": true - }, - "created_at": { - "type": "integer", - "minimum": 0, - "description": "Unix timestamp (seconds)" + "minLength": 1, + "maxLength": 56 } }, "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" - ] + "action_id" + ], + "additionalProperties": false, + "x-platform-visibility": "ADMIN" }, - "AgentEventList": { + "AccessDecisionBatch": { "type": "object", "properties": { - "data": { + "decisions": { "type": "array", "items": { - "$ref": "#/components/schemas/AgentEvent" - } - }, - "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." + "$ref": "#/components/schemas/AccessDecision" + }, + "minItems": 1, + "maxItems": 25 + } + }, + "required": [ + "decisions" + ], + "additionalProperties": false + }, + "ExplainAccessDecisionsBatchBody": { + "type": "object", + "properties": { + "requests": { + "type": "array", + "items": { + "$ref": "#/components/schemas/ExplainAccessDecisionBody" + }, + "minItems": 1, + "maxItems": 25 } }, "required": [ - "data", - "has_more", - "next_cursor" - ] + "requests" + ], + "additionalProperties": false }, - "ApprovalRequestList": { + "AdminCapabilityList": { "type": "object", "properties": { "data": { "type": "array", "items": { - "$ref": "#/components/schemas/ApprovalRequest" + "$ref": "#/components/schemas/AdminCapability" } }, "has_more": { @@ -14873,90 +28885,225 @@ "data", "has_more", "next_cursor" - ] + ], + "x-platform-visibility": "ADMIN" }, - "ApprovalRequest": { + "AdminCapability": { "type": "object", "properties": { "id": { "type": "string", - "minLength": 1, - "maxLength": 54 + "example": "networking" }, - "workspace_id": { - "type": "string", - "minLength": 1, - "maxLength": 53 + "name": { + "type": "string" }, - "agent_id": { - "type": "string", - "minLength": 1, - "maxLength": 54 + "owner": { + "type": "string" }, - "session_id": { - "type": "string", - "minLength": 1, - "maxLength": 54 + "surfaces": { + "type": "array", + "items": { + "type": "string", + "enum": [ + "web", + "api", + "worker", + "docs" + ] + } }, - "turn_id": { - "type": "string", - "minLength": 1, - "maxLength": 54 + "actions": { + "type": "array", + "items": { + "$ref": "#/components/schemas/AdminCapabilityAction" + } }, - "state": { + "flags": { + "type": "array", + "items": { + "type": "string" + } + }, + "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", - "enum": [ - "PENDING", - "APPROVED", - "REJECTED" - ] + "example": "custom_domains.use_dispatcher_bypass" }, - "title": { + "name": { "type": "string" }, - "summary": { - "type": "string" + "access": { + "$ref": "#/components/schemas/AdminCapabilityActionAccess" }, - "actions": { + "quota_metrics": { "type": "array", "items": { - "nullable": true + "type": "string" + } + }, + "operations": { + "type": "array", + "items": { + "type": "string" + } + } + }, + "required": [ + "id", + "name", + "access" + ], + "x-platform-visibility": "ADMIN" + }, + "AdminCapabilityActionAccess": { + "oneOf": [ + { + "type": "object", + "properties": { + "kind": { + "type": "string", + "enum": [ + "baseline" + ] + }, + "reason": { + "type": "string" + } }, - "default": [] + "required": [ + "kind", + "reason" + ] }, - "created_by": { - "type": "string" + { + "type": "object", + "properties": { + "kind": { + "type": "string", + "enum": [ + "feature_flagged" + ] + }, + "flags": { + "type": "array", + "items": { + "type": "string" + } + } + }, + "required": [ + "kind", + "flags" + ] }, - "created_at": { - "type": "integer", - "minimum": 0, - "description": "Unix timestamp (seconds)" + { + "type": "object", + "properties": { + "kind": { + "type": "string", + "enum": [ + "entitled" + ] + }, + "entitlements": { + "type": "array", + "items": { + "type": "string" + } + } + }, + "required": [ + "kind", + "entitlements" + ] }, - "updated_at": { - "type": "integer", - "minimum": 0, - "description": "Unix timestamp (seconds)" + { + "type": "object", + "properties": { + "kind": { + "type": "string", + "enum": [ + "admin" + ] + }, + "reason": { + "type": "string" + } + }, + "required": [ + "kind", + "reason" + ] }, - "etag": { - "type": "string" + { + "type": "object", + "properties": { + "kind": { + "type": "string", + "enum": [ + "internal" + ] + }, + "reason": { + "type": "string" + } + }, + "required": [ + "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": [ - "id", - "workspace_id", - "agent_id", - "session_id", - "turn_id", - "state", - "title", - "summary", - "created_by", - "created_at", - "updated_at", - "etag" - ] + "data", + "has_more", + "next_cursor" + ], + "x-platform-visibility": "ADMIN" }, - "WorkspaceSubdomain": { + "AdminDirectoryOrganization": { "type": "object", "properties": { "id": { @@ -14964,83 +29111,42 @@ "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 + "type": "string" }, - "status": { + "slug": { "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)" + "nullable": true }, "created_at": { - "type": "integer", - "minimum": 0, - "description": "Unix timestamp (seconds)" + "type": "number" }, - "updated_at": { + "member_count": { "type": "integer", - "minimum": 0, - "description": "Unix timestamp (seconds)" + "minimum": 0 }, - "etag": { - "type": "string" + "workspace_count": { + "type": "integer", + "minimum": 0 } }, "required": [ "id", - "workspace_id", "name", - "fqdn", - "status", - "name_changed_at", + "slug", "created_at", - "updated_at", - "etag" - ] - }, - "SetWorkspaceSubdomainNameBody": { - "type": "object", - "properties": { - "name": { - "type": "string", - "minLength": 1, - "maxLength": 63 - } - }, - "required": [ - "name" + "member_count", + "workspace_count" ], - "additionalProperties": false + "x-platform-visibility": "ADMIN" }, - "PreviewHostnameList": { + "AdminDirectoryUserList": { "type": "object", "properties": { "data": { "type": "array", "items": { - "$ref": "#/components/schemas/PreviewHostname" + "$ref": "#/components/schemas/AdminDirectoryUser" } }, "has_more": { @@ -15057,224 +29163,163 @@ "data", "has_more", "next_cursor" - ] + ], + "x-platform-visibility": "ADMIN" }, - "PreviewHostname": { + "AdminDirectoryUser": { "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." + "minLength": 1 }, - "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 - } - ] + "name": { + "type": "string" }, - "status": { + "email": { "type": "string", - "enum": [ - "provisioning", - "active", - "evicted", - "releasing" - ], - "description": "Current preview hostname lifecycle state." + "format": "email" }, - "last_seen_at": { - "type": "integer", - "nullable": true, - "minimum": 0, - "description": "Unix timestamp (seconds)" + "email_verified": { + "type": "boolean" }, - "created_at": { + "workspace_count": { "type": "integer", - "minimum": 0, - "description": "Unix timestamp (seconds)" + "minimum": 0 }, - "updated_at": { + "organization_count": { "type": "integer", - "minimum": 0, - "description": "Unix timestamp (seconds)" + "minimum": 0 }, - "etag": { - "type": "string" + "created_at": { + "type": "number" } }, "required": [ "id", - "workspace_id", - "install_id", - "hostname", - "protocol", - "routing_mode", - "binding", - "status", - "last_seen_at", - "created_at", - "updated_at", - "etag" - ] + "name", + "email", + "email_verified", + "workspace_count", + "organization_count", + "created_at" + ], + "x-platform-visibility": "ADMIN" }, - "BindPinnedPreviewHostnameBody": { + "AdminDirectoryWorkspaceList": { "type": "object", "properties": { - "render_id": { - "type": "string", - "minLength": 1, - "maxLength": 54 + "data": { + "type": "array", + "items": { + "$ref": "#/components/schemas/AdminDirectoryWorkspace" + } }, - "protocol": { - "type": "string", - "enum": [ - "http", - "websocket", - "grpc" - ], - "default": "http", - "description": "Transport class for route forwarding." + "has_more": { + "type": "boolean", + "description": "True if more items exist after this page." }, - "routing_mode": { + "next_cursor": { "type": "string", - "enum": [ - "through_dispatcher", - "bypass_dispatcher" - ], - "default": "through_dispatcher", - "description": "Whether traffic uses the dispatcher Worker or bypasses it." + "nullable": true, + "description": "Opaque cursor for the next page, or null if no more pages." } }, "required": [ - "render_id" + "data", + "has_more", + "next_cursor" ], - "additionalProperties": false + "x-platform-visibility": "ADMIN" }, - "BindFloatingPreviewHostnameBody": { + "AdminDirectoryWorkspace": { "type": "object", "properties": { - "track": { + "id": { "type": "string", "minLength": 1, - "maxLength": 100 + "maxLength": 53 }, - "render_id": { + "name": { + "type": "string" + }, + "slug": { + "type": "string" + }, + "organization_id": { "type": "string", "minLength": 1, "maxLength": 54 }, - "protocol": { + "organization_name": { + "type": "string" + }, + "workspace_class": { "type": "string", "enum": [ - "http", - "websocket", - "grpc" - ], - "default": "http", - "description": "Transport class for route forwarding." + "standard", + "platform", + "sandbox" + ] }, - "routing_mode": { + "plan_tier": { + "type": "string" + }, + "access_status": { "type": "string", "enum": [ - "through_dispatcher", - "bypass_dispatcher" - ], - "default": "through_dispatcher", - "description": "Whether traffic uses the dispatcher Worker or bypasses it." + "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": [ - "track", - "render_id" + "id", + "name", + "slug", + "workspace_class", + "plan_tier", + "member_count", + "cluster_count", + "product_count", + "operation_count", + "created_at" ], - "additionalProperties": false + "x-platform-visibility": "ADMIN" }, - "CustomDomainList": { + "AdminAccessOverrideList": { "type": "object", "properties": { "data": { "type": "array", "items": { - "$ref": "#/components/schemas/CustomDomain" + "$ref": "#/components/schemas/AdminAccessOverride" } }, "has_more": { @@ -15291,12 +29336,34 @@ "data", "has_more", "next_cursor" - ] + ], + "x-platform-visibility": "ADMIN" }, - "CustomDomain": { + "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 @@ -15306,367 +29373,234 @@ "minLength": 1, "maxLength": 53 }, - "hostname": { + "effect": { "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 - } + "enum": [ + "allow", + "deny" ] }, - "protocol": { + "previous_effect": { "type": "string", + "nullable": true, "enum": [ - "http", - "websocket", - "grpc" - ], - "description": "Transport class for route forwarding." + "allow", + "deny", + null + ] }, - "routing_mode": { + "new_effect": { "type": "string", + "nullable": true, "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" + "allow", + "deny", + null ] }, - "status": { + "reason": { + "type": "string" + }, + "created_by": { "type": "string", - "enum": [ - "provisioning", - "active", - "failed", - "releasing" - ] + "minLength": 1 }, "created_at": { - "type": "integer", - "minimum": 0, - "description": "Unix timestamp (seconds)" + "type": "number" + }, + "updated_by": { + "type": "string", + "minLength": 1 }, "updated_at": { - "type": "integer", - "minimum": 0, - "description": "Unix timestamp (seconds)" + "type": "number" }, - "etag": { - "type": "string" + "expires_at": { + "type": "number" + }, + "revoked_at": { + "type": "number" } }, "required": [ "id", - "workspace_id", - "hostname", - "target", - "protocol", - "routing_mode", - "ssl", - "status", + "target_type", + "key", + "scope", + "effect", + "previous_effect", + "new_effect", + "reason", + "created_by", "created_at", - "updated_at", - "etag" - ] + "updated_by", + "updated_at" + ], + "x-platform-visibility": "ADMIN" }, - "CreateCustomDomainBody": { - "type": "object", - "properties": { - "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 + "CreateAdminAccessOverrideBody": { + "oneOf": [ + { + "type": "object", + "properties": { + "target_type": { + "type": "string", + "enum": [ + "feature_flag", + "entitlement" + ] }, - { - "type": "object", - "properties": { - "kind": { - "type": "string", - "enum": [ - "cluster" - ] - }, - "cluster_id": { - "type": "string", - "minLength": 1, - "maxLength": 54 - } - }, - "required": [ - "kind", - "cluster_id" - ], - "additionalProperties": false + "key": { + "type": "string", + "minLength": 1, + "maxLength": 256 }, - { - "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 + "effect": { + "type": "string", + "enum": [ + "allow", + "deny" + ] + }, + "reason": { + "type": "string", + "minLength": 1, + "maxLength": 500 + }, + "expires_at": { + "type": "number" + }, + "scope": { + "type": "string", + "enum": [ + "global" + ] } - ] - }, - "protocol": { - "type": "string", - "enum": [ - "http", - "websocket", - "grpc" + }, + "required": [ + "target_type", + "key", + "effect", + "reason", + "scope" ], - "default": "http", - "description": "Transport class for route forwarding." + "additionalProperties": false }, - "routing_mode": { - "type": "string", - "enum": [ - "through_dispatcher", - "bypass_dispatcher" - ], - "default": "through_dispatcher", - "description": "Whether traffic uses the dispatcher Worker or bypasses it." - } - }, - "required": [ - "hostname", - "target" - ], - "additionalProperties": false - }, - "UpdateCustomDomainBody": { - "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": { + "target_type": { + "type": "string", + "enum": [ + "feature_flag", + "entitlement" + ] }, - { - "type": "object", - "properties": { - "kind": { - "type": "string", - "enum": [ - "cluster" - ] - }, - "cluster_id": { - "type": "string", - "minLength": 1, - "maxLength": 54 - } - }, - "required": [ - "kind", - "cluster_id" - ], - "additionalProperties": false + "key": { + "type": "string", + "minLength": 1, + "maxLength": 256 }, - { - "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 + "effect": { + "type": "string", + "enum": [ + "allow", + "deny" + ] + }, + "reason": { + "type": "string", + "minLength": 1, + "maxLength": 500 + }, + "expires_at": { + "type": "number" + }, + "scope": { + "type": "string", + "enum": [ + "organization" + ] + }, + "organization_id": { + "type": "string", + "minLength": 1, + "maxLength": 54 } - ] - }, - "protocol": { - "type": "string", - "enum": [ - "http", - "websocket", - "grpc" + }, + "required": [ + "target_type", + "key", + "effect", + "reason", + "scope", + "organization_id" ], - "description": "Transport class for route forwarding." + "additionalProperties": false }, - "routing_mode": { - "type": "string", - "enum": [ - "through_dispatcher", - "bypass_dispatcher" + { + "type": "object", + "properties": { + "target_type": { + "type": "string", + "enum": [ + "feature_flag", + "entitlement" + ] + }, + "key": { + "type": "string", + "minLength": 1, + "maxLength": 256 + }, + "effect": { + "type": "string", + "enum": [ + "allow", + "deny" + ] + }, + "reason": { + "type": "string", + "minLength": 1, + "maxLength": 500 + }, + "expires_at": { + "type": "number" + }, + "scope": { + "type": "string", + "enum": [ + "workspace" + ] + }, + "workspace_id": { + "type": "string", + "minLength": 1, + "maxLength": 53 + } + }, + "required": [ + "target_type", + "key", + "effect", + "reason", + "scope", + "workspace_id" ], - "description": "Whether traffic uses the dispatcher Worker or bypasses it." + "additionalProperties": false } - }, - "additionalProperties": false + ], + "x-platform-visibility": "ADMIN", + "x-platform-exact-union": true }, - "CloudflareCredentialList": { + "AdminQuotaOverrideList": { "type": "object", "properties": { "data": { "type": "array", "items": { - "$ref": "#/components/schemas/CloudflareCredential" + "$ref": "#/components/schemas/AdminQuotaOverride" } }, "has_more": { @@ -15683,2521 +29617,4634 @@ "data", "has_more", "next_cursor" - ] + ], + "x-platform-visibility": "ADMIN" }, - "CloudflareCredential": { + "AdminQuotaOverride": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, - "maxLength": 56 + "maxLength": 54 }, - "name": { + "scope": { "type": "string", - "example": "Production Cloudflare" + "enum": [ + "user", + "workspace" + ] }, - "account_id": { + "user_id": { "type": "string", - "description": "Cloudflare account ID." + "minLength": 1 }, - "origin_zone_id": { + "workspace_id": { "type": "string", - "nullable": true, - "description": "Cloudflare zone ID used for Access-protected origin hostnames." + "minLength": 1, + "maxLength": 53 }, - "origin_hostname_suffix": { - "type": "string", - "nullable": true, - "description": "Hostname suffix used for Access-protected origin hostnames." + "metric": { + "type": "string" }, - "is_active": { - "type": "boolean", - "description": "Whether the credential is active" + "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": "integer", - "minimum": 0, - "description": "Unix timestamp (seconds)" + "type": "number" }, - "last_used_at": { - "type": "integer", - "nullable": true, - "minimum": 0, - "description": "Unix timestamp (seconds), null if never used" + "updated_by": { + "type": "string", + "minLength": 1 + }, + "updated_at": { + "type": "number" + }, + "revoked_at": { + "type": "number" } }, "required": [ "id", - "name", - "account_id", - "origin_zone_id", - "origin_hostname_suffix", - "is_active", - "created_at", - "last_used_at" - ] + "scope", + "metric", + "limit", + "previous_limit", + "new_limit" + ], + "x-platform-visibility": "ADMIN" }, - "CreateCloudflareCredentialBody": { + "SetAdminQuotaOverrideBody": { "type": "object", "properties": { - "name": { + "scope": { "type": "string", - "minLength": 1, - "maxLength": 100, - "example": "Production Cloudflare" + "enum": [ + "user", + "workspace" + ] }, - "account_id": { + "user_id": { "type": "string", - "minLength": 1, - "maxLength": 200, - "pattern": "^[A-Za-z0-9_-]+$", - "description": "Cloudflare account ID." + "minLength": 1 }, - "origin_zone_id": { + "workspace_id": { "type": "string", "minLength": 1, - "maxLength": 200, - "pattern": "^[A-Za-z0-9_-]+$", - "description": "Cloudflare zone ID used for Access-protected origin hostnames." + "maxLength": 53 }, - "origin_hostname_suffix": { + "metric": { "type": "string", "minLength": 1, - "maxLength": 253, - "description": "Hostname suffix used for Access-protected origin hostnames." + "maxLength": 256 }, - "api_token": { + "limit": { + "type": "integer", + "minimum": 0 + }, + "reason": { "type": "string", "minLength": 1, - "maxLength": 2000, - "description": "Cloudflare API token. Stored as a platform Secret; never returned." + "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" }, - "required": [ - "name", - "account_id", - "origin_zone_id", - "origin_hostname_suffix", - "api_token" + "operationId": "snippets.get", + "tags": [ + "Snippets" ], - "additionalProperties": false - }, - "AccessDecision": { - "type": "object", - "properties": { - "decision": { - "$ref": "#/components/schemas/AccessDecisionResult" + "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" + } + } + } }, - "action": { - "type": "object", - "properties": { - "id": { - "type": "string", - "minLength": 1 - }, - "name": { - "type": "string", - "minLength": 1 + "401": { + "description": "Unauthorized", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } } - }, - "required": [ - "id", - "name" - ], - "additionalProperties": false + } }, - "reasons": { - "type": "array", - "items": { - "$ref": "#/components/schemas/AccessReason" + "403": { + "description": "Forbidden", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } + } + } + }, + "404": { + "description": "Not found", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } + } } } - }, - "required": [ - "decision", - "action", - "reasons" - ], - "additionalProperties": false + } }, - "AccessDecisionResult": { - "oneOf": [ + "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": [ { - "type": "object", - "properties": { - "result": { - "type": "string", - "enum": [ - "allowed" - ] - } - }, - "required": [ - "result" - ], - "additionalProperties": false - }, + "BearerAuth": [] + } + ], + "parameters": [ { - "type": "object", - "properties": { - "result": { - "type": "string", - "enum": [ - "denied" - ] - }, - "message": { - "type": "string", - "minLength": 1 - } + "schema": { + "type": "string", + "minLength": 1, + "maxLength": 54, + "description": "Snippet ID" }, - "required": [ - "result", - "message" - ], - "additionalProperties": false + "required": true, + "description": "Snippet ID", + "name": "id", + "in": "path" }, { - "type": "object", - "properties": { - "result": { - "type": "string", - "enum": [ - "unknown" - ] - }, - "message": { - "type": "string", - "minLength": 1 - } + "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": [ - "result", - "message" - ], - "additionalProperties": false + "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" } - ] - }, - "AccessReason": { - "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": { - "type": "string", - "enum": [ - "allowed", - "denied", - "not_evaluated" - ] - }, - "key": { - "type": "string" - }, - "source": { - "type": "string" - }, - "message": { - "type": "string" - }, - "metric": { - "type": "string" - }, - "scope": { - "type": "string", - "enum": [ - "global", - "organization", - "workspace", - "user" - ] - }, - "limit": { - "type": "number" - }, - "usage": { - "type": "number" - }, - "remaining": { - "type": "number" + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/UpdateSnippetBody" + } + } + } + }, + "responses": { + "200": { + "description": "Snippet updated", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "snippet_id": { + "type": "string" + } + }, + "required": [ + "snippet_id" + ] + } + } + } }, - "resourceId": { - "type": "string" + "401": { + "description": "Unauthorized", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } + } + } }, - "resourceType": { - "type": "string" + "404": { + "description": "Not found", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } + } + } }, - "relationship": { - "type": "string" + "409": { + "description": "Conflict", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } + } + } } - }, - "required": [ - "kind", - "result" - ], - "additionalProperties": false + } }, - "ExplainAccessDecisionBody": { - "oneOf": [ + "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": [ { - "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" - } + "BearerAuth": [] + } + ], + "parameters": [ + { + "schema": { + "type": "string", + "minLength": 1, + "maxLength": 54, + "description": "Snippet ID" }, - "required": [ - "permission", - "resource" - ], - "additionalProperties": false + "required": true, + "description": "Snippet ID", + "name": "id", + "in": "path" }, { - "type": "object", - "properties": { - "subject": { - "$ref": "#/components/schemas/AccessSubject" - }, - "permission": { - "type": "string", - "enum": [ - "offers.create_non_channel_paid_product_offer" - ] - }, - "resource": { - "$ref": "#/components/schemas/NonChannelPaidProductOfferResource" - } + "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": [ - "permission", - "resource" - ], - "additionalProperties": false + "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": "Snippet archived, or already archived" }, - { - "type": "object", - "properties": { - "subject": { - "$ref": "#/components/schemas/AccessSubject" - }, - "permission": { - "type": "string", - "enum": [ - "offers.create_non_billable_test_offer" - ] - }, - "resource": { - "$ref": "#/components/schemas/NonBillableTestOfferResource" + "401": { + "description": "Unauthorized", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } } - }, - "required": [ - "permission", - "resource" - ], - "additionalProperties": false + } + }, + "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": [ { - "type": "object", - "properties": { - "subject": { - "$ref": "#/components/schemas/AccessSubject" - }, - "permission": { - "type": "string", - "enum": [ - "offer_channels.create" - ] - }, - "resource": { - "$ref": "#/components/schemas/OfferChannelCreateDecisionResource" + "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/ExecuteSnippetBody" + } + } + } + }, + "responses": { + "200": { + "description": "Snippet execution result", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ExecuteSnippetResponse" + } } - }, - "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" + "401": { + "description": "Unauthorized", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } } - }, - "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" + "403": { + "description": "Forbidden", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } } - }, - "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" + "422": { + "description": "Unprocessable entity", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } } + } + } + } + } + }, + "/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": [ - "permission", - "resource" - ], - "additionalProperties": false + "required": true, + "name": "id", + "in": "path" + } + ], + "requestBody": { + "required": false, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ExecuteStoredSnippetBody" + } + } + } + }, + "responses": { + "200": { + "description": "Snippet execution result", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ExecuteSnippetResponse" + } + } + } }, - { - "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" + "401": { + "description": "Unauthorized", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } } - }, - "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" + "404": { + "description": "Not found", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } } - }, - "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" + "409": { + "description": "Conflict", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } } - }, - "required": [ - "permission", - "resource" - ], - "additionalProperties": false + } }, - { - "type": "object", - "properties": { - "subject": { - "$ref": "#/components/schemas/AccessSubject" - }, - "permission": { - "type": "string", - "enum": [ - "workspaces.inspect_membership" - ] - }, - "resource": { - "$ref": "#/components/schemas/WorkspaceMembershipResource" + "422": { + "description": "Unprocessable entity", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } } + } + } + } + } + }, + "/v1/snippets/{id}/runs": { + "post": { + "x-platform-visibility": "PUBLIC", + "operationId": "snippets.createRun", + "tags": [ + "Snippets" + ], + "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": [] + } + ], + "parameters": [ + { + "schema": { + "type": "string", + "minLength": 1, + "maxLength": 54 }, - "required": [ - "permission", - "resource" - ], - "additionalProperties": false + "required": true, + "name": "id", + "in": "path" }, { - "type": "object", - "properties": { - "subject": { - "$ref": "#/components/schemas/AccessSubject" - }, - "permission": { - "type": "string", - "enum": [ - "products.create" - ] - }, - "resource": { - "$ref": "#/components/schemas/ProductCockpitResource" - } + "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": [ - "permission" - ], - "additionalProperties": 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" }, { - "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 - } + "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": [ - "permission", - "resource" - ], - "additionalProperties": false + "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" + } + } + } }, - { - "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 + "401": { + "description": "Unauthorized", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } } - }, - "required": [ - "permission", - "resource" - ], - "additionalProperties": false + } }, - { - "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 + "403": { + "description": "Forbidden", + "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" + } } + } + } + } + }, + "get": { + "x-platform-visibility": "PUBLIC", + "x-platform-live": { + "visibility": "INTERNAL", + "transport": "convex", + "convexQuery": "snippet.ui.listSnippetRunsForApi" + }, + "operationId": "snippets.listRuns", + "tags": [ + "Snippets" + ], + "summary": "List snippet runs", + "description": "Returns runs for a snippet. Use `view=basic` for a compact listing.", + "security": [ + { + "BearerAuth": [] + } + ], + "parameters": [ + { + "schema": { + "type": "string", + "minLength": 1, + "maxLength": 54 }, - "required": [ - "permission", - "resource" - ], - "additionalProperties": false + "required": true, + "name": "id", + "in": "path" }, { - "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 - } + "schema": { + "type": "string", + "description": "Pagination cursor from a previous response's `next_cursor`." }, - "required": [ - "permission", - "resource" - ], - "additionalProperties": false + "required": false, + "description": "Pagination cursor from a previous response's `next_cursor`.", + "name": "cursor", + "in": "query" }, { - "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 - } + "schema": { + "type": "integer", + "minimum": 1, + "maximum": 100, + "default": 50, + "description": "Items per page (1-100, default 50)", + "example": 50 }, - "required": [ - "permission", - "resource" - ], - "additionalProperties": false + "required": false, + "description": "Items per page (1-100, default 50)", + "name": "limit", + "in": "query" }, { - "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 - } + "schema": { + "type": "string", + "enum": [ + "succeeded", + "failed", + "timed_out" + ] }, - "required": [ - "permission", - "resource" - ], - "additionalProperties": false + "required": false, + "name": "state", + "in": "query" }, { - "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 + "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" + } + } + } + }, + "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}/runs/{run_id}": { + "get": { + "x-platform-visibility": "PUBLIC", + "x-platform-live": { + "visibility": "INTERNAL", + "transport": "convex", + "convexQuery": "snippet.ui.getSnippetRun" + }, + "operationId": "snippets.getRun", + "tags": [ + "Snippets" + ], + "summary": "Get snippet run", + "description": "Returns a single snippet run by ID.", + "security": [ + { + "BearerAuth": [] + } + ], + "parameters": [ + { + "schema": { + "type": "string", + "minLength": 1, + "maxLength": 54 }, - "required": [ - "permission", - "resource" - ], - "additionalProperties": false + "required": true, + "name": "id", + "in": "path" }, { - "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 + "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" + } + } + } + }, + "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/snippet_runs": { + "get": { + "x-platform-visibility": "PUBLIC", + "x-platform-live": { + "visibility": "INTERNAL", + "transport": "convex", + "convexQuery": "snippet.ui.listWorkspaceSnippetRunsForApi" + }, + "operationId": "snippetRuns.list", + "tags": [ + "Snippet Runs" + ], + "summary": "List workspace snippet runs", + "description": "Returns durable snippet execution activity for the selected workspace, newest first.", + "security": [ + { + "BearerAuth": [] + } + ], + "parameters": [ + { + "schema": { + "type": "string", + "description": "Pagination cursor from a previous response's `next_cursor`." }, - "required": [ - "permission", - "resource" - ], - "additionalProperties": false + "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" }, { - "type": "object", - "properties": { - "subject": { - "$ref": "#/components/schemas/AccessSubject" - }, - "permission": { - "type": "string", - "enum": [ - "packages.create" - ] - }, - "resource": { - "$ref": "#/components/schemas/PackageCockpitResource" - } + "schema": { + "type": "string", + "enum": [ + "succeeded", + "failed", + "timed_out" + ] }, - "required": [ - "permission" - ], - "additionalProperties": false + "required": false, + "name": "state", + "in": "query" }, { - "type": "object", - "properties": { - "subject": { - "$ref": "#/components/schemas/AccessSubject" - }, - "permission": { - "type": "string", - "enum": [ - "packages.import_published_package" - ] - }, - "resource": { - "$ref": "#/components/schemas/PackageCockpitResource" - } + "schema": { + "type": "string", + "enum": [ + "manual", + "dashboard_open", + "dashboard_refresh", + "agent" + ] }, - "required": [ - "permission" - ], - "additionalProperties": false + "required": false, + "name": "source", + "in": "query" }, { - "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 - } + "schema": { + "type": "string", + "minLength": 1, + "maxLength": 54 }, - "required": [ - "permission", - "resource" - ], - "additionalProperties": false + "required": false, + "name": "snippet", + "in": "query" }, { - "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 - } + "schema": { + "type": "string", + "minLength": 1, + "maxLength": 55 }, - "required": [ - "permission", - "resource" - ], - "additionalProperties": false + "required": false, + "name": "dashboard", + "in": "query" }, { - "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 - } + "schema": { + "type": "string", + "enum": [ + "basic", + "full" + ], + "default": "basic", + "description": "Control whether output and error details are included." }, - "required": [ - "permission", - "resource" - ], - "additionalProperties": false + "required": false, + "description": "Control whether output and error details are included.", + "name": "view", + "in": "query" }, { - "type": "object", - "properties": { - "subject": { - "$ref": "#/components/schemas/AccessSubject" - }, - "permission": { - "type": "string", - "enum": [ - "catalog_actions.explain" - ] - }, - "resource": { - "$ref": "#/components/schemas/CatalogActionExplainResource" - } + "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": [ - "permission", - "resource" - ], - "additionalProperties": false, - "x-platform-visibility": "ADMIN" + "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" } - ] - }, - "AccessSubject": { - "type": "object", - "properties": { - "user_id": { - "type": "string", - "minLength": 1 + ], + "responses": { + "200": { + "description": "Workspace snippet-run history", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/SnippetRunList" + } + } + } }, - "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" + } + } + } } + } + } + }, + "/v1/snippet_runs/{id}": { + "get": { + "x-platform-visibility": "PUBLIC", + "x-platform-live": { + "visibility": "INTERNAL", + "transport": "convex", + "convexQuery": "snippet.ui.getWorkspaceSnippetRunForApi" }, - "additionalProperties": false - }, - "OfferChannelCreateResource": { - "type": "object", - "properties": { - "offer_channel_id": { - "type": "string", - "minLength": 1, - "maxLength": 54 - }, - "target_workspace_id": { - "type": "string", - "minLength": 1, - "maxLength": 53 - }, - "product_id": { - "type": "string", - "minLength": 1, - "maxLength": 55 - }, - "commercial_mode": { - "type": "string", - "enum": [ - "paid", - "non_billable_test" - ] + "operationId": "snippetRuns.get", + "tags": [ + "Snippet Runs" + ], + "summary": "Get workspace snippet run", + "description": "Returns one durable snippet execution, including its terminal payload.", + "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 + }, + "required": true, + "name": "id", + "in": "path" }, - "stripe_mode": { - "type": "string", - "enum": [ - "live", - "test", - "sandbox" - ] + { + "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" } - }, - "additionalProperties": false - }, - "NonChannelPaidProductOfferResource": { - "type": "object", - "properties": { - "workspace_id": { - "type": "string", - "minLength": 1, - "maxLength": 53 - }, - "product_id": { - "type": "string", - "minLength": 1, - "maxLength": 55 + ], + "responses": { + "200": { + "description": "Snippet run details", + "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" + } + } + } }, - "target_workspace_id": { - "type": "string", - "minLength": 1, - "maxLength": 53 + "403": { + "description": "Forbidden", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } + } + } }, - "commercial_mode": { - "type": "string", - "enum": [ - "paid" - ] + "404": { + "description": "Not found", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } + } + } } - }, - "required": [ - "workspace_id", - "product_id", - "package_version_id", - "commercial_mode" + } + } + }, + "/v1/dashboard_widget_results:resolve": { + "post": { + "x-platform-visibility": "INTERNAL", + "operationId": "dashboardWidgetResults.resolve", + "tags": [ + "Dashboard Overview" ], - "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 - }, - "target_workspace_id": { - "type": "string", - "minLength": 1, - "maxLength": 53 - }, - "target_workspace_class": { - "type": "string", - "enum": [ - "standard", - "platform", - "sandbox" - ] - }, - "commercial_mode": { - "type": "string", - "enum": [ - "non_billable_test" - ] + "summary": "Resolve dashboard widget result", + "description": "Returns the authenticated viewer's last successful matching snippet-widget result and freshness metadata.", + "security": [ + { + "BearerAuth": [] } - }, - "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 + "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": [ - "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 - }, - "product_id": { - "type": "string", - "minLength": 1, - "maxLength": 55 + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ResolveDashboardWidgetResultBody" + } + } } }, - "required": [ - "workspace_id" - ], - "additionalProperties": false - }, - "ChannelPolicyApproveResource": { - "type": "object", - "properties": { - "workspace_id": { - "type": "string", - "minLength": 1, - "maxLength": 53 + "responses": { + "200": { + "description": "Matching widget result resolution", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/DashboardWidgetResultResolution" + } + } + } }, - "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 + "403": { + "description": "Forbidden", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } + } + } }, - "resource_state": { - "type": "string", - "enum": [ - "draft" - ] + "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/dashboards": { + "get": { + "x-platform-visibility": "PUBLIC", + "x-platform-live": { + "visibility": "INTERNAL", + "transport": "convex", + "convexQuery": "snippet.ui.listDashboardsForApi" }, - "required": [ - "workspace_id", - "offer_channel_id", - "channel_policy_id", - "resource_state" + "operationId": "dashboards.list", + "tags": [ + "Dashboards" ], - "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": "List dashboards in workspace", + "description": "Returns all dashboards belonging to the workspace specified in the workspace context.", + "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 + "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" }, - "owner_workspace_id": { - "type": "string", - "minLength": 1, - "maxLength": 53 + { + "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" }, - "resource_state": { - "type": "string", - "enum": [ - "pending_approval", - "approved", - "rejected" - ] + { + "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" + } + } + } }, - "platform_policy_snapshot_id": { - "type": "string", - "minLength": 1, - "x-platform-visibility": "ADMIN" + "401": { + "description": "Unauthorized", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } + } + } }, - "partner_price_band_key": { - "type": "string", - "minLength": 1, - "x-platform-visibility": "TRUSTED_PARTNER" + "403": { + "description": "Forbidden", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } + } + } } - }, - "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 - }, - "required_class": { - "type": "string", - "enum": [ - "standard", - "platform", - "sandbox" - ] + "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": [] } - }, - "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": 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 + } } } }, - "required": [ - "workspace_id" - ], - "additionalProperties": false - }, - "ProductCockpitResource": { - "type": "object", - "properties": { - "product_id": { - "type": "string", - "minLength": 1, - "maxLength": 55 + "responses": { + "201": { + "description": "Dashboard created", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "dashboard_id": { + "type": "string" + } + }, + "required": [ + "dashboard_id" + ] + } + } + } }, - "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 + "403": { + "description": "Forbidden", + "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" + } + } + } } + } + } + }, + "/v1/dashboards/workspace_overview": { + "get": { + "x-platform-visibility": "PUBLIC", + "x-platform-live": { + "visibility": "INTERNAL", + "transport": "convex", + "convexQuery": "snippet.ui.getWorkspaceOverviewForApi" }, - "required": [ - "workspace_id" + "operationId": "dashboards.getWorkspaceOverview", + "tags": [ + "Dashboards" ], - "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": "Get the workspace overview dashboard", + "description": "Returns the unique shared Workspace overview and its ordered widget configuration.", + "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 - }, - "product_id": { - "type": "string", - "minLength": 1, - "maxLength": 55 - }, - "package_id": { - "type": "string", - "minLength": 1, - "maxLength": 54 + "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" + } + } + } }, - "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 + "404": { + "description": "Not found", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } + } + } }, - "channel_policy_id": { - "type": "string", - "minLength": 1, - "maxLength": 56 + "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": [ - "action_id" + "operationId": "dashboards.get", + "tags": [ + "Dashboards" ], - "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": "Get dashboard details", + "description": "Returns a dashboard including its widget layout and snippet references.", + "security": [ + { + "BearerAuth": [] } - }, - "required": [ - "data", - "has_more", - "next_cursor" ], - "x-platform-visibility": "ADMIN" - }, - "AdminCapability": { - "type": "object", - "properties": { - "id": { - "type": "string", - "example": "networking" - }, - "name": { - "type": "string" - }, - "owner": { - "type": "string" - }, - "surfaces": { - "type": "array", - "items": { + "parameters": [ + { + "schema": { "type": "string", - "enum": [ - "web", - "api", - "worker", - "docs" - ] + "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" + } + } } }, - "actions": { - "type": "array", - "items": { - "$ref": "#/components/schemas/AdminCapabilityAction" + "401": { + "description": "Unauthorized", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } + } } }, - "flags": { - "type": "array", - "items": { - "type": "string" + "403": { + "description": "Forbidden", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } + } } }, - "entitlements": { - "type": "array", - "items": { - "type": "string" + "404": { + "description": "Not found", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } + } } } - }, - "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" + "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" }, - "name": { - "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" + ] + } + } + } }, - "access": { - "$ref": "#/components/schemas/AdminCapabilityActionAccess" + "401": { + "description": "Unauthorized", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } + } + } }, - "quota_metrics": { - "type": "array", - "items": { - "type": "string" + "404": { + "description": "Not found", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } + } } }, - "operations": { - "type": "array", - "items": { - "type": "string" + "409": { + "description": "Conflict", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } + } } } - }, - "required": [ - "id", - "name", - "access" - ], - "x-platform-visibility": "ADMIN" + } }, - "AdminCapabilityActionAccess": { - "oneOf": [ + "delete": { + "x-platform-visibility": "PUBLIC", + "operationId": "dashboards.delete", + "tags": [ + "Dashboards" + ], + "summary": "Delete dashboard", + "description": "Permanently deletes a dashboard. Referenced snippets are not affected.", + "security": [ { - "type": "object", - "properties": { - "kind": { - "type": "string", - "enum": [ - "baseline" - ] - }, - "reason": { - "type": "string" - } + "BearerAuth": [] + } + ], + "parameters": [ + { + "schema": { + "type": "string", + "minLength": 1, + "maxLength": 55, + "description": "Dashboard ID" }, - "required": [ - "kind", - "reason" - ] + "required": true, + "description": "Dashboard ID", + "name": "id", + "in": "path" }, { - "type": "object", - "properties": { - "kind": { - "type": "string", - "enum": [ - "feature_flagged" - ] - }, - "flags": { - "type": "array", - "items": { - "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" + }, + "401": { + "description": "Unauthorized", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } + } + } + }, + "404": { + "description": "Not found", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" } } - }, - "required": [ - "kind", - "flags" - ] + } }, - { - "type": "object", - "properties": { - "kind": { - "type": "string", - "enum": [ - "entitled" - ] - }, - "entitlements": { - "type": "array", - "items": { - "type": "string" + "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": [ - "kind", - "entitlements" - ] + "required": true, + "name": "id", + "in": "path" }, { - "type": "object", - "properties": { - "kind": { - "type": "string", - "enum": [ - "admin" - ] - }, - "reason": { - "type": "string" - } + "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": [ - "internal" - ] - }, - "reason": { - "type": "string" - } + "schema": { + "type": "integer", + "minimum": 1, + "maximum": 10, + "default": 10, + "description": "Dashboard revisions per page (1-10, default 10)", + "example": 10 }, - "required": [ - "kind", - "reason" - ] + "required": false, + "description": "Dashboard revisions per page (1-10, default 10)", + "name": "limit", + "in": "query" } ], - "x-platform-visibility": "ADMIN" - }, - "AdminDirectoryOrganizationList": { - "type": "object", - "properties": { - "data": { - "type": "array", - "items": { - "$ref": "#/components/schemas/AdminDirectoryOrganization" + "responses": { + "200": { + "description": "Dashboard revision history", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/DashboardRevisionList" + } + } } }, - "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 + "401": { + "description": "Unauthorized", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } + } + } }, - "name": { - "type": "string" + "403": { + "description": "Forbidden", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } + } + } }, - "slug": { - "type": "string", - "nullable": true + "404": { + "description": "Not found", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } + } + } }, - "created_at": { - "type": "number" + "422": { + "description": "Input validation error", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } + } + } + } + } + }, + "post": { + "x-platform-visibility": "PUBLIC", + "operationId": "dashboards.createRevision", + "tags": [ + "Dashboards" + ], + "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" }, - "member_count": { - "type": "integer", - "minimum": 0 + { + "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" }, - "workspace_count": { - "type": "integer", - "minimum": 0 + { + "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" } - }, - "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" + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "name": { + "type": "string", + "minLength": 1, + "maxLength": 100 + }, + "description": { + "type": "string", + "nullable": true, + "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": [ + "name", + "description", + "filter_definitions", + "default_filter_values", + "widgets" + ], + "additionalProperties": false + } } - }, - "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" + "responses": { + "201": { + "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/DashboardRevisionMutationResponse" + } + } + } }, - "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" - } - }, - "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" + "404": { + "description": "Not found", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } + } } }, - "has_more": { - "type": "boolean", - "description": "True if more items exist after this page." + "409": { + "description": "Conflict", + "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." + "422": { + "description": "Unprocessable entity", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } + } + } } - }, - "required": [ - "data", - "has_more", - "next_cursor" + } + } + }, + "/v1/dashboards/{id}/revisions/{revision_id}": { + "get": { + "x-platform-visibility": "PUBLIC", + "operationId": "dashboards.getRevision", + "tags": [ + "Dashboards" ], - "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" - ] + "summary": "Get dashboard revision", + "description": "Returns one immutable dashboard revision and its snippet version drift.", + "security": [ + { + "BearerAuth": [] + } + ], + "parameters": [ + { + "schema": { + "type": "string", + "minLength": 1, + "maxLength": 55 + }, + "required": true, + "name": "id", + "in": "path" }, - "plan_tier": { - "type": "string" + { + "schema": { + "type": "string", + "minLength": 1, + "maxLength": 55 + }, + "required": true, + "name": "revision_id", + "in": "path" + } + ], + "responses": { + "200": { + "description": "Dashboard revision details", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/DashboardRevision" + } + } + } }, - "access_status": { - "type": "string", - "enum": [ - "active", - "payment_grace", - "restricted", - "suspended", - "ended", - "reactivating" - ] + "401": { + "description": "Unauthorized", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } + } + } }, - "accessible": { - "type": "boolean" + "403": { + "description": "Forbidden", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } + } + } }, - "member_count": { - "type": "integer", - "minimum": 0 + "404": { + "description": "Not found", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } + } + } }, - "cluster_count": { - "type": "integer", - "minimum": 0 + "422": { + "description": "Input validation error", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } + } + } + } + } + } + }, + "/v1/dashboards/{id}/revisions/{revision_id}:restore": { + "post": { + "x-platform-visibility": "PUBLIC", + "operationId": "dashboards.restoreRevision", + "tags": [ + "Dashboards" + ], + "summary": "Restore dashboard revision", + "description": "Restores an immutable snapshot by creating and activating a new dashboard revision.", + "security": [ + { + "BearerAuth": [] + } + ], + "parameters": [ + { + "schema": { + "type": "string", + "minLength": 1, + "maxLength": 55 + }, + "required": true, + "name": "id", + "in": "path" }, - "product_count": { - "type": "integer", - "minimum": 0 + { + "schema": { + "type": "string", + "minLength": 1, + "maxLength": 55 + }, + "required": true, + "name": "revision_id", + "in": "path" }, - "operation_count": { - "type": "integer", - "minimum": 0 + { + "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" }, - "created_at": { - "type": "number" + { + "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" } - }, - "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": { + "required": true, + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "summary": { + "type": "string", + "nullable": true, + "maxLength": 500 + } + }, + "required": [ + "summary" + ], + "additionalProperties": false + } } - }, - "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 + "responses": { + "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/DashboardRevisionMutationResponse" + } + } + } }, - "created_at": { - "type": "number" + "401": { + "description": "Unauthorized", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } + } + } }, - "updated_by": { - "type": "string", - "minLength": 1 + "403": { + "description": "Forbidden", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } + } + } }, - "updated_at": { - "type": "number" + "404": { + "description": "Not found", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } + } + } }, - "expires_at": { - "type": "number" + "409": { + "description": "Conflict", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } + } + } }, - "revoked_at": { - "type": "number" + "422": { + "description": "Unprocessable entity", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } + } + } } - }, - "required": [ - "id", - "target_type", - "key", - "scope", - "effect", - "previous_effect", - "new_effect", - "reason", - "created_by", - "created_at", - "updated_by", - "updated_at" + } + } + }, + "/v1/dashboards/{id}:resetToRecommended": { + "post": { + "x-platform-visibility": "PUBLIC", + "operationId": "dashboards.resetToRecommended", + "tags": [ + "Dashboards" ], - "x-platform-visibility": "ADMIN" - }, - "CreateAdminAccessOverrideBody": { - "type": "object", - "properties": { - "target_type": { - "type": "string", - "enum": [ - "feature_flag", - "entitlement" - ] + "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": [] + } + ], + "parameters": [ + { + "schema": { + "type": "string", + "minLength": 1, + "maxLength": 55 + }, + "required": true, + "name": "id", + "in": "path" }, - "key": { - "type": "string", - "minLength": 1, - "maxLength": 256 + { + "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" }, - "scope": { - "type": "string", - "enum": [ - "global", - "organization", - "workspace" - ] + { + "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": { + "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/DashboardRevisionMutationResponse" + } + } + } }, - "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" + } + } + } }, - "effect": { - "type": "string", - "enum": [ - "allow", - "deny" - ] + "404": { + "description": "Not found", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } + } + } }, - "reason": { - "type": "string", - "minLength": 1, - "maxLength": 500 + "409": { + "description": "Conflict", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } + } + } }, - "expires_at": { - "type": "number" + "422": { + "description": "Unprocessable entity", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } + } + } } - }, - "required": [ - "target_type", - "key", - "scope", - "effect", - "reason" + } + } + }, + "/v1/dashboards/{id}/widgets": { + "post": { + "x-platform-visibility": "PUBLIC", + "operationId": "dashboards.createWidget", + "tags": [ + "Dashboards" ], - "additionalProperties": false, - "x-platform-visibility": "ADMIN" - }, - "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." + "summary": "Create dashboard widget", + "description": "Creates a widget as a child resource under a dashboard.", + "security": [ + { + "BearerAuth": [] } - }, - "required": [ - "data", - "has_more", - "next_cursor" ], - "x-platform-visibility": "ADMIN" - }, - "AdminQuotaOverride": { - "type": "object", - "properties": { - "id": { - "type": "string", - "minLength": 1, - "maxLength": 54 - }, - "scope": { - "type": "string", - "enum": [ - "user", - "workspace" - ] + "parameters": [ + { + "schema": { + "type": "string", + "minLength": 1, + "maxLength": 55 + }, + "required": true, + "name": "id", + "in": "path" }, - "user_id": { - "type": "string", - "minLength": 1 + { + "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" }, - "workspace_id": { - "type": "string", - "minLength": 1, - "maxLength": 53 + { + "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": { + "201": { + "description": "Dashboard widget created", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Widget" + } + } + } }, - "metric": { - "type": "string" + "401": { + "description": "Unauthorized", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } + } + } }, - "limit": { - "type": "number" + "403": { + "description": "Forbidden", + "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" + } + } + } }, - "reason": { - "type": "string" + "422": { + "description": "Unprocessable entity", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } + } + } + } + } + }, + "get": { + "x-platform-visibility": "PUBLIC", + "operationId": "dashboards.listWidgets", + "tags": [ + "Dashboards" + ], + "summary": "List dashboard widgets", + "description": "Lists widgets for a dashboard.", + "security": [ + { + "BearerAuth": [] + } + ], + "parameters": [ + { + "schema": { + "type": "string", + "minLength": 1, + "maxLength": 55 + }, + "required": true, + "name": "id", + "in": "path" }, - "created_by": { - "type": "string", - "minLength": 1 + { + "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" }, - "created_at": { - "type": "number" + { + "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": "List of dashboard widgets", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/WidgetList" + } + } + } }, - "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" + } + } + } }, - "revoked_at": { - "type": "number" + "404": { + "description": "Not found", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } + } + } } - }, - "required": [ - "id", - "scope", - "metric", - "limit", - "previous_limit", - "new_limit" + } + } + }, + "/v1/dashboards/{id}/widgets/{wgt_id}": { + "get": { + "x-platform-visibility": "PUBLIC", + "operationId": "dashboards.getWidget", + "tags": [ + "Dashboards" ], - "x-platform-visibility": "ADMIN" - }, - "SetAdminQuotaOverrideBody": { - "type": "object", - "properties": { - "scope": { - "type": "string", - "enum": [ - "user", - "workspace" - ] - }, - "user_id": { - "type": "string", - "minLength": 1 + "summary": "Get dashboard widget", + "description": "Returns a single dashboard widget.", + "security": [ + { + "BearerAuth": [] + } + ], + "parameters": [ + { + "schema": { + "type": "string", + "minLength": 1, + "maxLength": 55 + }, + "required": true, + "name": "id", + "in": "path" }, - "workspace_id": { - "type": "string", - "minLength": 1, - "maxLength": 53 + { + "schema": { + "type": "string", + "minLength": 1, + "maxLength": 54 + }, + "required": true, + "name": "wgt_id", + "in": "path" + } + ], + "responses": { + "200": { + "description": "Dashboard widget details", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Widget" + } + } + } }, - "metric": { - "type": "string", - "minLength": 1, - "maxLength": 256 + "401": { + "description": "Unauthorized", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } + } + } }, - "limit": { - "type": "integer", - "minimum": 0 + "403": { + "description": "Forbidden", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } + } + } }, - "reason": { - "type": "string", - "minLength": 1, - "maxLength": 500 + "404": { + "description": "Not found", + "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": { + } + }, + "patch": { "x-platform-visibility": "PUBLIC", - "operationId": "compute.createMachine", + "operationId": "dashboards.updateWidget", "tags": [ - "Compute" + "Dashboards" ], - "summary": "Create a machine", - "description": "Provisions a new machine in the specified cluster with the given compute configuration.", + "summary": "Update dashboard widget", + "description": "Updates widget placement and display settings.", "security": [ { - "BearerAuth": [] + "BearerAuth": [] + } + ], + "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" + }, + { + "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": { - "type": "object", - "properties": { - "config_ref": { - "type": "string", - "description": "ComputeConfig ID" - }, - "cluster_id": { - "type": "string", - "description": "Cluster ID" - }, - "node_claim": { - "nullable": true, - "description": "Machine requirements (instance type, resources, taints)" - } - }, - "required": [ - "config_ref", - "cluster_id" - ] + "$ref": "#/components/schemas/UpdateDashboardWidgetBody" } } } }, "responses": { - "201": { - "description": "Machine created", + "200": { + "description": "Dashboard widget updated", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/ComputeMachine" + "$ref": "#/components/schemas/Widget" } } } @@ -18212,69 +34259,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": { @@ -18284,17 +34300,15 @@ } } } - } - }, - "/v1/compute/machines/{providerId}": { + }, "delete": { "x-platform-visibility": "PUBLIC", - "operationId": "compute.deleteMachine", + "operationId": "dashboards.deleteWidget", "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": "Delete dashboard widget", + "description": "Deletes a dashboard widget. Snippet references are preserved.", "security": [ { "BearerAuth": [] @@ -18304,17 +34318,53 @@ { "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": 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": 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": "Machine deleted" + "description": "Dashboard widget deleted" }, "401": { "description": "Unauthorized", @@ -18326,50 +34376,274 @@ } } }, + "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/ApiErrorResponse" + } + } + } + }, + "409": { + "description": "Conflict", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/ComputeError" + "$ref": "#/components/schemas/ApiErrorResponse" } } } } } - }, - "get": { - "x-platform-visibility": "PUBLIC", - "operationId": "compute.getMachine", + } + }, + "/v1/cluster_runtime/machines": { + "post": { + "x-platform-visibility": "INTERNAL", + "operationId": "clusterRuntime.createMachine", "tags": [ - "Compute" + "Cluster Runtime" ], - "summary": "Get machine status", - "description": "Returns current state of a machine including conditions and provider metadata.", + "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": "Provider-assigned machine ID" - }, - "required": true, - "description": "Provider-assigned machine ID", - "name": "providerId", - "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": "Machine details", + "201": { + "description": "Machine creation accepted", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/ComputeMachine" + "$ref": "#/components/schemas/ClusterRuntimeMachine" } } } @@ -18384,54 +34658,80 @@ } } }, + "403": { + "description": "Cluster service-account authentication required", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClusterRuntimeError" + } + } + } + }, "404": { - "description": "Machine not found (NodeClaimNotFound)", + "description": "Compute configuration not found", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClusterRuntimeError" + } + } + } + }, + "422": { + "description": "Invalid runtime machine request", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClusterRuntimeError" + } + } + } + }, + "429": { + "description": "Machine quota exhausted", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClusterRuntimeError" + } + } + } + }, + "503": { + "description": "No matching capacity available", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/ComputeError" + "$ref": "#/components/schemas/ClusterRuntimeError" } } } } } - } - }, - "/v1/compute/instance_types": { + }, "get": { - "x-platform-visibility": "PUBLIC", - "operationId": "compute.listInstanceTypes", + "x-platform-visibility": "INTERNAL", + "operationId": "clusterRuntime.listMachines", "tags": [ - "Compute" + "Cluster Runtime" ], - "summary": "List available instance types", - "description": "Returns instance types with pricing for a compute config. Returns available instance types for provisioning. Results are cached.", + "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": "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", + "description": "Cluster machines", "content": { "application/json": { "schema": { "type": "array", "items": { - "$ref": "#/components/schemas/InstanceType" + "$ref": "#/components/schemas/ClusterRuntimeMachine" } } } @@ -18447,12 +34747,12 @@ } } }, - "404": { - "description": "Config not found (NodeClassNotReady)", + "403": { + "description": "Cluster service-account authentication required", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/ComputeError" + "$ref": "#/components/schemas/ClusterRuntimeError" } } } @@ -18460,15 +34760,15 @@ } } }, - "/v1/compute/machines/{providerId}/drift": { + "/v1/cluster_runtime/machines/{provider_id}": { "get": { - "x-platform-visibility": "PUBLIC", - "operationId": "compute.checkMachineDrift", + "x-platform-visibility": "INTERNAL", + "operationId": "clusterRuntime.getMachine", "tags": [ - "Compute" + "Cluster Runtime" ], - "summary": "Check if machine has drifted", - "description": "Checks if a machine has drifted from its desired compute configuration.", + "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": [] @@ -18478,21 +34778,22 @@ { "schema": { "type": "string", + "minLength": 1, "description": "Provider-assigned machine ID" }, "required": true, "description": "Provider-assigned machine ID", - "name": "providerId", + "name": "provider_id", "in": "path" } ], "responses": { "200": { - "description": "Drift result", + "description": "Machine status", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/DriftResult" + "$ref": "#/components/schemas/ClusterRuntimeMachine" } } } @@ -18506,72 +34807,37 @@ } } } - } - } - } - }, - "/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": "Cluster service-account authentication required", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/ApiErrorResponse" + "$ref": "#/components/schemas/ClusterRuntimeError" } } } }, "404": { - "description": "Machine not found (NodeClaimNotFound)", + "description": "Machine not found", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/ComputeError" + "$ref": "#/components/schemas/ClusterRuntimeError" } } } } } - } - }, - "/v1/compute/suspensions/{id}/resume": { - "post": { - "x-platform-visibility": "PUBLIC", - "operationId": "compute.resumeSuspension", + }, + "delete": { + "x-platform-visibility": "INTERNAL", + "operationId": "clusterRuntime.deleteMachine", "tags": [ - "Compute" + "Cluster Runtime" ], - "summary": "Resume a suspended machine", - "description": "Restores the machine from its snapshot, creates a new cloud server.", + "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": [] @@ -18581,17 +34847,18 @@ { "schema": { "type": "string", - "description": "Suspension ID" + "minLength": 1, + "description": "Provider-assigned machine ID" }, "required": true, - "description": "Suspension ID", - "name": "id", + "description": "Provider-assigned machine ID", + "name": "provider_id", "in": "path" } ], "responses": { "204": { - "description": "Resume workflow started" + "description": "Machine deletion acknowledged" }, "401": { "description": "Unauthorized", @@ -18603,63 +34870,32 @@ } } }, - "404": { - "description": "Suspension not found", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/ComputeError" - } - } - } - } - } - } - }, - "/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", + "403": { + "description": "Cluster service-account authentication required", "content": { "application/json": { "schema": { - "type": "array", - "items": { - "$ref": "#/components/schemas/Suspension" - } + "$ref": "#/components/schemas/ClusterRuntimeError" } } } }, - "401": { - "description": "Unauthorized", + "404": { + "description": "Machine not found", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/ApiErrorResponse" + "$ref": "#/components/schemas/ClusterRuntimeError" } } } }, - "403": { - "description": "Akua-Context required", + "503": { + "description": "Machine lifecycle is unavailable", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/ApiErrorResponse" + "$ref": "#/components/schemas/ClusterRuntimeError" } } } @@ -18667,15 +34903,15 @@ } } }, - "/v1/compute/suspensions/{id}": { - "delete": { - "x-platform-visibility": "PUBLIC", - "operationId": "compute.deleteSuspension", + "/v1/cluster_runtime/machines/{provider_id}/drift": { + "get": { + "x-platform-visibility": "INTERNAL", + "operationId": "clusterRuntime.checkMachineDrift", "tags": [ - "Compute" + "Cluster Runtime" ], - "summary": "Delete a suspension", - "description": "Deletes the snapshot and suspension record permanently.", + "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": [] @@ -18685,17 +34921,25 @@ { "schema": { "type": "string", - "description": "Suspension ID" + "minLength": 1, + "description": "Provider-assigned machine ID" }, "required": true, - "description": "Suspension ID", - "name": "id", + "description": "Provider-assigned machine ID", + "name": "provider_id", "in": "path" } ], "responses": { - "204": { - "description": "Suspension deleted" + "200": { + "description": "Drift result", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClusterRuntimeDrift" + } + } + } }, "401": { "description": "Unauthorized", @@ -18707,12 +34951,32 @@ } } }, + "403": { + "description": "Cluster service-account authentication required", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClusterRuntimeError" + } + } + } + }, "404": { - "description": "Suspension not found", + "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/ComputeError" + "$ref": "#/components/schemas/ClusterRuntimeError" } } } @@ -18720,15 +34984,15 @@ } } }, - "/v1/compute/configs": { + "/v1/cluster_runtime/instance_types": { "get": { - "x-platform-visibility": "PUBLIC", - "operationId": "compute.listConfigs", + "x-platform-visibility": "INTERNAL", + "operationId": "clusterRuntime.listInstanceTypes", "tags": [ - "Compute" + "Cluster Runtime" ], - "summary": "List compute configs", - "description": "Lists compute configs for the workspace.", + "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": [] @@ -18738,35 +35002,25 @@ { "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 + "maxLength": 100, + "description": "Compute configuration name; derived from cluster context when omitted" }, "required": false, - "description": "Items per page (1-100, default 50)", - "name": "limit", + "description": "Compute configuration name; derived from cluster context when omitted", + "name": "config", "in": "query" } ], "responses": { "200": { - "description": "List of compute configs", + "description": "Available instance types", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/ComputeConfigList" + "type": "array", + "items": { + "$ref": "#/components/schemas/ClusterRuntimeInstanceType" + } } } } @@ -18782,80 +35036,59 @@ } }, "403": { - "description": "Akua-Context required", + "description": "Cluster service-account authentication required", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/ApiErrorResponse" + "$ref": "#/components/schemas/ClusterRuntimeError" } } } - } - } - }, - "post": { - "x-platform-visibility": "PUBLIC", - "operationId": "compute.createConfig", - "tags": [ - "Compute" - ], - "summary": "Create a compute config", - "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" - ] + }, + "404": { + "description": "Compute configuration not found", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClusterRuntimeError" + } + } + } + }, + "422": { + "description": "Invalid instance-type query", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClusterRuntimeError" + } } } } - }, + } + } + }, + "/v1/cluster_runtime/compute_status": { + "get": { + "x-platform-visibility": "INTERNAL", + "operationId": "clusterRuntime.getComputeStatus", + "tags": [ + "Cluster Runtime" + ], + "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": [] + } + ], "responses": { - "201": { - "description": "Config created", + "200": { + "description": "Cluster compute status", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/CreatedComputeConfig" + "$ref": "#/components/schemas/ClusterRuntimeComputeStatus" } } } @@ -18871,11 +35104,21 @@ } }, "403": { - "description": "Akua-Context required", + "description": "Cluster service-account authentication required", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/ApiErrorResponse" + "$ref": "#/components/schemas/ClusterRuntimeError" + } + } + } + }, + "404": { + "description": "Cluster not found", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClusterRuntimeError" } } } @@ -18883,14 +35126,20 @@ } } }, - "/v1/compute/configs/{id}": { + "/v1/clusters/{id}/compute_settings": { "get": { "x-platform-visibility": "PUBLIC", - "operationId": "compute.getConfig", + "x-platform-live": { + "visibility": "PUBLIC", + "transport": "convex", + "convexQuery": "compute.ui.getClusterComputeSettingsForApi" + }, + "operationId": "clusters.getComputeSettings", "tags": [ - "Compute" + "Clusters" ], - "summary": "Get a compute config", + "summary": "Get cluster compute settings", + "description": "Returns autoscaling state, current machine usage, the configured limit, and the etag required for updates.", "security": [ { "BearerAuth": [] @@ -18900,21 +35149,36 @@ { "schema": { "type": "string", - "description": "ComputeConfig ID" + "minLength": 1, + "maxLength": 54, + "description": "Cluster ID." }, "required": true, - "description": "ComputeConfig ID", + "description": "Cluster 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": "Compute config", + "description": "Cluster compute settings", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/ComputeConfig" + "$ref": "#/components/schemas/ClusterComputeSettings" } } } @@ -18930,7 +35194,7 @@ } }, "403": { - "description": "Akua-Context required", + "description": "Forbidden", "content": { "application/json": { "schema": { @@ -18940,24 +35204,25 @@ } }, "404": { - "description": "Config not found", + "description": "Not found", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/ComputeError" + "$ref": "#/components/schemas/ApiErrorResponse" } } } } } }, - "delete": { + "patch": { "x-platform-visibility": "PUBLIC", - "operationId": "compute.deleteConfig", + "operationId": "clusters.updateComputeSettings", "tags": [ - "Compute" + "Clusters" ], - "summary": "Delete a compute config", + "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": [] @@ -18967,13 +35232,28 @@ { "schema": { "type": "string", - "description": "ComputeConfig ID" + "minLength": 1, + "maxLength": 54, + "description": "Cluster ID." }, "required": true, - "description": "ComputeConfig ID", + "description": "Cluster 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", @@ -18988,22 +35268,29 @@ "in": "header" } ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/UpdateClusterComputeSettingsBody" + } + } + } + }, "responses": { - "204": { - "description": "Config deleted" - }, - "401": { - "description": "Unauthorized", + "200": { + "description": "Cluster compute settings updated", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/ApiErrorResponse" + "$ref": "#/components/schemas/ClusterComputeSettings" } } } }, - "403": { - "description": "Akua-Context required", + "400": { + "description": "Bad request", "content": { "application/json": { "schema": { @@ -19012,88 +35299,38 @@ } } }, - "404": { - "description": "Config not found", + "401": { + "description": "Unauthorized", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/ComputeError" + "$ref": "#/components/schemas/ApiErrorResponse" } } } }, - "409": { - "description": "Config has active machines", + "403": { + "description": "Forbidden", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/ComputeError" + "$ref": "#/components/schemas/ApiErrorResponse" } } } - } - } - } - }, - "/v1/clusters/{clusterId}/compute_status": { - "get": { - "x-platform-visibility": "PUBLIC", - "operationId": "compute.getClusterStatus", - "tags": [ - "Compute" - ], - "summary": "Get cluster compute status", - "description": "Returns auto-scaling state, machine count, and limits for a cluster.", - "security": [ - { - "BearerAuth": [] - } - ], - "parameters": [ - { - "schema": { - "type": "string", - "description": "Cluster ID" - }, - "required": true, - "description": "Cluster ID", - "name": "clusterId", - "in": "path" - } - ], - "responses": { - "200": { - "description": "Compute status", + }, + "404": { + "description": "Not found", "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/ApiErrorResponse" } } } }, - "401": { - "description": "Unauthorized", + "409": { + "description": "Conflict", "content": { "application/json": { "schema": { @@ -19102,8 +35339,8 @@ } } }, - "403": { - "description": "Akua-Context required", + "422": { + "description": "Unprocessable entity", "content": { "application/json": { "schema": { @@ -19111,61 +35348,9 @@ } } } - } - } - } - }, - "/v1/clusters/{clusterId}/compute_settings": { - "patch": { - "x-platform-visibility": "PUBLIC", - "operationId": "compute.updateClusterSettings", - "tags": [ - "Compute" - ], - "summary": "Update cluster compute settings", - "description": "Controls auto-scaling behavior and machine limits for a cluster.", - "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": { - "204": { - "description": "Settings updated" }, - "401": { - "description": "Unauthorized", + "429": { + "description": "Too many requests", "content": { "application/json": { "schema": { @@ -19174,8 +35359,8 @@ } } }, - "403": { - "description": "Akua-Context required", + "503": { + "description": "Service unavailable", "content": { "application/json": { "schema": { @@ -19187,50 +35372,21 @@ } } }, - "/v1/snippets": { - "get": { + "/v1/machines": { + "post": { "x-platform-visibility": "PUBLIC", - "x-platform-live": { - "visibility": "INTERNAL", - "transport": "convex", - "convexQuery": "snippet.ui.listSnippetsForApi" - }, - "operationId": "snippets.list", "tags": [ - "Snippets" + "Machines" ], - "summary": "List snippets in workspace", - "description": "Returns all snippets belonging to the workspace specified in the workspace context.", + "operationId": "machines.create", + "summary": "Create machine", + "description": "Creates a machine and returns a long-running operation envelope.", "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", @@ -19243,52 +35399,19 @@ "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": [] + "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": { @@ -19297,74 +35420,35 @@ "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": { + "cluster_id": { "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." + "maxLength": 54 }, - "origin": { + "instance_type": { "type": "string", - "enum": [ - "user", - "agent", - "system" - ], - "description": "Who authored the snippet descriptor." + "minLength": 1 }, - "agent_session_id": { + "compute_config_id": { "type": "string", "minLength": 1, "maxLength": 54 }, - "agent_turn_id": { + "name": { "type": "string", - "minLength": 1, - "maxLength": 54 + "maxLength": 120 }, - "purpose": { - "type": "string", - "enum": [ - "general", - "prepared_action", - "reactive_read", - "widget" - ] + "node_claim": { + "type": "object", + "additionalProperties": { + "nullable": true + } } }, "required": [ - "name", - "code", - "display_type" + "cluster_id", + "instance_type", + "compute_config_id" ], "additionalProperties": false } @@ -19372,20 +35456,12 @@ } }, "responses": { - "201": { - "description": "Snippet created", + "202": { + "description": "Machine creation accepted", "content": { "application/json": { "schema": { - "type": "object", - "properties": { - "snippet_id": { - "type": "string" - } - }, - "required": [ - "snippet_id" - ] + "$ref": "#/components/schemas/MachineOperation" } } } @@ -19410,8 +35486,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": { @@ -19421,28 +35517,91 @@ } } } - } - }, - "/v1/snippets:usage": { + }, "get": { "x-platform-visibility": "PUBLIC", "x-platform-live": { - "visibility": "INTERNAL", + "visibility": "PUBLIC", "transport": "convex", - "convexQuery": "snippet.ui.listSnippetUsageForApi" + "convexQuery": "compute.ui.listMachinesForApi" }, - "operationId": "snippets.listUsage", "tags": [ - "Snippets" + "Machines" ], - "summary": "List snippet dashboard usage in workspace", - "description": "Returns dashboard references for snippets in the workspace specified in the workspace context.", + "operationId": "machines.list", + "summary": "List machines", + "description": "Lists all machines in the workspace.", "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 + }, + "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", + "enum": [ + "basic", + "full" + ], + "default": "basic" + }, + "required": false, + "name": "view", + "in": "query" + }, { "schema": { "type": "string", @@ -19459,11 +35618,11 @@ ], "responses": { "200": { - "description": "Snippet dashboard usage", + "description": "Machine list", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/SnippetUsageList" + "$ref": "#/components/schemas/MachineList" } } } @@ -19477,34 +35636,24 @@ } } } - }, - "403": { - "description": "Forbidden", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/ApiErrorResponse" - } - } - } } } } }, - "/v1/snippets/{id}:usage": { + "/v1/clusters/{id}/workers:dashboardList": { "get": { - "x-platform-visibility": "PUBLIC", + "x-platform-visibility": "INTERNAL", "x-platform-live": { "visibility": "INTERNAL", "transport": "convex", - "convexQuery": "snippet.ui.getSnippetUsageForApi" + "convexQuery": "compute.ui.listDashboardClusterWorkersForApi" }, - "operationId": "snippets.getUsage", "tags": [ - "Snippets" + "Clusters" ], - "summary": "Get snippet dashboard usage", - "description": "Returns dashboard references for one snippet.", + "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": [] @@ -19515,22 +35664,57 @@ "schema": { "type": "string", "minLength": 1, - "maxLength": 54, - "description": "Snippet ID" + "maxLength": 54 }, "required": true, - "description": "Snippet 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 + }, + "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": "Snippet dashboard usage", + "description": "Dashboard cluster worker page", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/SnippetUsage" + "$ref": "#/components/schemas/DashboardClusterWorkerList" } } } @@ -19568,20 +35752,15 @@ } } }, - "/v1/snippets/{id}": { + "/v1/machines/{id}": { "get": { "x-platform-visibility": "PUBLIC", - "x-platform-live": { - "visibility": "INTERNAL", - "transport": "convex", - "convexQuery": "snippet.ui.getSnippetForApi" - }, - "operationId": "snippets.get", "tags": [ - "Snippets" + "Machines" ], - "summary": "Get snippet details", - "description": "Returns a snippet including its code and display type.", + "operationId": "machines.get", + "summary": "Get machine", + "description": "Returns a machine by ID.", "security": [ { "BearerAuth": [] @@ -19592,22 +35771,33 @@ "schema": { "type": "string", "minLength": 1, - "maxLength": 54, - "description": "Snippet ID" + "maxLength": 54 }, "required": true, - "description": "Snippet 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": "Snippet details", + "description": "Machine details", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/Snippet" + "$ref": "#/components/schemas/Machine" } } } @@ -19646,12 +35836,12 @@ }, "patch": { "x-platform-visibility": "PUBLIC", - "operationId": "snippets.update", "tags": [ - "Snippets" + "Machines" ], - "summary": "Update snippet", - "description": "Updates snippet properties. Only provided fields are changed. Dashboards using this snippet will pick up code changes on next run.", + "operationId": "machines.update", + "summary": "Update machine", + "description": "Updates machine metadata.", "security": [ { "BearerAuth": [] @@ -19662,14 +35852,38 @@ "schema": { "type": "string", "minLength": 1, - "maxLength": 54, - "description": "Snippet ID" + "maxLength": 54 }, "required": true, - "description": "Snippet 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", @@ -19691,44 +35905,14 @@ "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" + "anyOf": [ + { + "type": "string", + "maxLength": 120 + }, + { + "nullable": true + } ] } }, @@ -19739,19 +35923,11 @@ }, "responses": { "200": { - "description": "Snippet updated", + "description": "Machine updated", "content": { "application/json": { "schema": { - "type": "object", - "properties": { - "snippet_id": { - "type": "string" - } - }, - "required": [ - "snippet_id" - ] + "$ref": "#/components/schemas/Machine" } } } @@ -19766,6 +35942,16 @@ } } }, + "403": { + "description": "Forbidden", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } + } + } + }, "404": { "description": "Not found", "content": { @@ -19790,12 +35976,12 @@ }, "delete": { "x-platform-visibility": "PUBLIC", - "operationId": "snippets.delete", "tags": [ - "Snippets" + "Machines" ], - "summary": "Delete snippet", - "description": "Permanently deletes a snippet. Fails with 409 if the snippet is referenced by any dashboard widgets.", + "operationId": "machines.delete", + "summary": "Delete machine", + "description": "Deletes a machine and returns a long-running operation envelope.", "security": [ { "BearerAuth": [] @@ -19806,14 +35992,38 @@ "schema": { "type": "string", "minLength": 1, - "maxLength": 54, - "description": "Snippet ID" + "maxLength": 54 }, "required": true, - "description": "Snippet 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", @@ -19829,8 +36039,15 @@ } ], "responses": { - "204": { - "description": "Snippet deleted" + "202": { + "description": "Machine deletion accepted", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/MachineOperation" + } + } + } }, "401": { "description": "Unauthorized", @@ -19842,6 +36059,16 @@ } } }, + "403": { + "description": "Forbidden", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } + } + } + }, "404": { "description": "Not found", "content": { @@ -19861,25 +36088,45 @@ } } } + }, + "503": { + "description": "Service unavailable", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } + } + } } } } }, - "/v1/snippets:execute": { + "/v1/machines/{id}:suspend": { "post": { "x-platform-visibility": "PUBLIC", - "operationId": "snippets.execute", "tags": [ - "Snippets" + "Machines" ], - "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.", + "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": [] } ], "parameters": [ + { + "schema": { + "type": "string", + "minLength": 1, + "maxLength": 54 + }, + "required": true, + "name": "id", + "in": "path" + }, { "schema": { "type": "string", @@ -19892,24 +36139,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": "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" } ], "requestBody": { "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/ExecuteSnippetBody" + "$ref": "#/components/schemas/SuspendMachineBody" } } } }, "responses": { - "200": { - "description": "Snippet execution result", + "202": { + "description": "Machine suspend accepted", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/ExecuteSnippetResponse" + "$ref": "#/components/schemas/MachineOperation" } } } @@ -19934,58 +36207,8 @@ } } }, - "422": { - "description": "Unprocessable entity", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/ApiErrorResponse" - } - } - } - } - } - } - }, - "/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", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/ExecuteSnippetResponse" - } - } - } - }, - "401": { - "description": "Unauthorized", + "404": { + "description": "Not found", "content": { "application/json": { "schema": { @@ -19994,8 +36217,8 @@ } } }, - "404": { - "description": "Not found", + "409": { + "description": "Conflict", "content": { "application/json": { "schema": { @@ -20004,8 +36227,8 @@ } } }, - "422": { - "description": "Unprocessable entity", + "503": { + "description": "Service unavailable", "content": { "application/json": { "schema": { @@ -20017,15 +36240,15 @@ } } }, - "/v1/snippets/{id}/runs": { + "/v1/machines/{id}:resume": { "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.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": [] @@ -20060,31 +36283,44 @@ "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" + "description": "Required caller key for idempotent machine lifecycle operations.", + "example": "suspend-worker-2026-07-18" }, - "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 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" } ], "requestBody": { "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/CreateSnippetRunBody" + "$ref": "#/components/schemas/ResumeMachineBody" } } } }, "responses": { - "201": { - "description": "Snippet run created", + "202": { + "description": "Machine resume accepted", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/SnippetRun" + "$ref": "#/components/schemas/MachineOperation" } } } @@ -20109,8 +36345,8 @@ } } }, - "422": { - "description": "Unprocessable entity", + "404": { + "description": "Not found", "content": { "application/json": { "schema": { @@ -20118,104 +36354,9 @@ } } } - } - } - }, - "get": { - "x-platform-visibility": "PUBLIC", - "x-platform-live": { - "visibility": "INTERNAL", - "transport": "convex", - "convexQuery": "snippet.ui.listSnippetRunsForApi" - }, - "operationId": "snippets.listRuns", - "tags": [ - "Snippets" - ], - "summary": "List snippet runs", - "description": "Returns runs for a snippet. Use `view=basic` for a compact listing.", - "security": [ - { - "BearerAuth": [] - } - ], - "parameters": [ - { - "schema": { - "type": "string", - "minLength": 1, - "maxLength": 54 - }, - "required": true, - "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", - "enum": [ - "succeeded", - "failed", - "timed_out" - ] - }, - "required": false, - "name": "state", - "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" - } - ], - "responses": { - "200": { - "description": "List of snippet runs", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/SnippetRunList" - } - } - } }, - "401": { - "description": "Unauthorized", + "409": { + "description": "Conflict", "content": { "application/json": { "schema": { @@ -20224,8 +36365,8 @@ } } }, - "403": { - "description": "Forbidden", + "503": { + "description": "Service unavailable", "content": { "application/json": { "schema": { @@ -20237,20 +36378,16 @@ } } }, - "/v1/snippets/{id}/runs/{run_id}": { - "get": { + "/v1/machines/{id}/drift_reports": { + "post": { "x-platform-visibility": "PUBLIC", - "x-platform-live": { - "visibility": "INTERNAL", - "transport": "convex", - "convexQuery": "snippet.ui.getSnippetRun" - }, - "operationId": "snippets.getRun", "tags": [ - "Snippets" + "Machines" ], - "summary": "Get snippet run", - "description": "Returns a single snippet run by ID.", + "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": [] @@ -20271,20 +36408,59 @@ "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" + }, + { + "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": { + "type": "object", + "properties": { + "trigger": { + "type": "string" + } + }, + "additionalProperties": false + } + } + } + }, "responses": { - "200": { - "description": "Snippet run details", + "201": { + "description": "Machine drift report created", + "headers": { + "Location": { + "schema": { + "type": "string" + }, + "description": "Location of the drift report." + } + }, "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/SnippetRun" + "$ref": "#/components/schemas/DriftReport" } } } @@ -20320,28 +36496,32 @@ } } } - } - }, - "/v1/dashboards": { + }, "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.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": [] } ], "parameters": [ + { + "schema": { + "type": "string", + "minLength": 1, + "maxLength": 54 + }, + "required": true, + "name": "id", + "in": "path" + }, { "schema": { "type": "string", @@ -20366,6 +36546,20 @@ "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", @@ -20382,90 +36576,11 @@ ], "responses": { "200": { - "description": "List of dashboards", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/DashboardList" - } - } - } - }, - "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": "dashboards.create", - "tags": [ - "Dashboards" - ], - "summary": "Create dashboard", - "description": "Creates a dashboard in the workspace. Widgets are added through the dashboard widgets sub-collection.", - "security": [ - { - "BearerAuth": [] - } - ], - "requestBody": { - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "name": { - "type": "string", - "minLength": 1, - "maxLength": 100, - "example": "Cluster Overview" - }, - "description": { - "type": "string", - "maxLength": 500 - } - }, - "required": [ - "name" - ], - "additionalProperties": false - } - } - } - }, - "responses": { - "201": { - "description": "Dashboard created", + "description": "Drift report list", "content": { "application/json": { "schema": { - "type": "object", - "properties": { - "dashboard_id": { - "type": "string" - } - }, - "required": [ - "dashboard_id" - ] + "$ref": "#/components/schemas/DriftReportList" } } } @@ -20490,8 +36605,8 @@ } } }, - "422": { - "description": "Unprocessable entity", + "404": { + "description": "Not found", "content": { "application/json": { "schema": { @@ -20503,20 +36618,16 @@ } } }, - "/v1/dashboards/{id}": { + "/v1/machines/{id}/drift_reports/{report_id}": { "get": { "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.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": [] @@ -20527,22 +36638,43 @@ "schema": { "type": "string", "minLength": 1, - "maxLength": 55, - "description": "Dashboard ID" + "maxLength": 54 }, "required": true, - "description": "Dashboard 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", + "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 details", + "description": "Machine drift report", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/Dashboard" + "$ref": "#/components/schemas/DriftReport" } } } @@ -20557,6 +36689,16 @@ } } }, + "403": { + "description": "Forbidden", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } + } + } + }, "404": { "description": "Not found", "content": { @@ -20568,15 +36710,18 @@ } } } - }, - "patch": { + } + }, + "/v1/machines/{id}/suspension_events": { + "get": { "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.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": [] @@ -20587,64 +36732,69 @@ "schema": { "type": "string", "minLength": 1, - "maxLength": 55, - "description": "Dashboard ID" + "maxLength": 54 }, "required": true, - "description": "Dashboard 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 + }, + "required": false, + "description": "Items per page (1-100, default 50)", + "name": "limit", + "in": "query" + }, + { + "schema": { + "type": "string", + "enum": [ + "manual", + "downgrade" + ] + }, + "required": false, + "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": { - "name": { - "type": "string", - "minLength": 1, - "maxLength": 100 - }, - "description": { - "type": "string", - "maxLength": 500 - } - }, - "additionalProperties": false - } - } - } - }, "responses": { "200": { - "description": "Dashboard updated", + "description": "Suspension event list", "content": { "application/json": { "schema": { - "type": "object", - "properties": { - "dashboard_id": { - "type": "string" - } - }, - "required": [ - "dashboard_id" - ] + "$ref": "#/components/schemas/SuspensionEventList" } } } @@ -20659,8 +36809,8 @@ } } }, - "404": { - "description": "Not found", + "403": { + "description": "Forbidden", "content": { "application/json": { "schema": { @@ -20669,8 +36819,8 @@ } } }, - "409": { - "description": "Conflict", + "404": { + "description": "Not found", "content": { "application/json": { "schema": { @@ -20680,15 +36830,18 @@ } } } - }, - "delete": { + } + }, + "/v1/machines/{id}/suspension_events/{event_id}": { + "get": { "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.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": [] @@ -20699,11 +36852,9 @@ "schema": { "type": "string", "minLength": 1, - "maxLength": 55, - "description": "Dashboard ID" + "maxLength": 54 }, "required": true, - "description": "Dashboard ID", "name": "id", "in": "path" }, @@ -20711,19 +36862,36 @@ "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": 54 }, "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", + "name": "event_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": { - "204": { - "description": "Dashboard deleted" + "200": { + "description": "Suspension event", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/SuspensionEvent" + } + } + } }, "401": { "description": "Unauthorized", @@ -20735,8 +36903,8 @@ } } }, - "404": { - "description": "Not found", + "403": { + "description": "Forbidden", "content": { "application/json": { "schema": { @@ -20745,8 +36913,8 @@ } } }, - "409": { - "description": "Conflict", + "404": { + "description": "Not found", "content": { "application/json": { "schema": { @@ -20758,31 +36926,21 @@ } } }, - "/v1/dashboards/{id}/widgets": { + "/v1/compute_configs": { "post": { "x-platform-visibility": "PUBLIC", - "operationId": "dashboards.createWidget", "tags": [ - "Dashboards" + "ComputeConfigs" ], - "summary": "Create dashboard widget", - "description": "Creates a widget as a child resource under a dashboard.", + "operationId": "computeConfigs.create", + "summary": "Create compute config", + "description": "Creates a compute config row.", "security": [ { "BearerAuth": [] } ], "parameters": [ - { - "schema": { - "type": "string", - "minLength": 1, - "maxLength": 55 - }, - "required": true, - "name": "id", - "in": "path" - }, { "schema": { "type": "string", @@ -20801,11 +36959,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,58 +36974,46 @@ "schema": { "type": "object", "properties": { - "snippet_id": { + "name": { "type": "string", "minLength": 1, - "maxLength": 54 + "maxLength": 100 }, - "col_span": { - "anyOf": [ - { - "type": "number", - "enum": [ - 1 - ] - }, - { - "type": "number", - "enum": [ - 2 - ] + "provider": { + "type": "string", + "enum": [ + "hcloud" + ] + }, + "provider_config": { + "type": "object", + "properties": { + "region": { + "type": "string", + "minLength": 1 }, - { - "type": "number", - "enum": [ - 3 - ] + "image": { + "type": "string", + "minLength": 1 }, - { - "type": "number", - "enum": [ - 4 - ] + "machine_type_filter": { + "type": "string" } + }, + "required": [ + "region", + "image" ] }, - "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" + "credential_scope": { + "$ref": "#/components/schemas/CredentialScope" } }, "required": [ - "snippet_id", - "col_span" + "name", + "provider", + "provider_config", + "credential_scope" ], "additionalProperties": false } @@ -20876,11 +37022,11 @@ }, "responses": { "201": { - "description": "Dashboard widget created", + "description": "Compute config created", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/Widget" + "$ref": "#/components/schemas/ComputeConfig" } } } @@ -20904,43 +37050,28 @@ } } } - }, - "404": { - "description": "Not found", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/ApiErrorResponse" - } - } - } } } }, "get": { "x-platform-visibility": "PUBLIC", - "operationId": "dashboards.listWidgets", + "x-platform-live": { + "visibility": "PUBLIC", + "transport": "convex", + "convexQuery": "compute.ui.listComputeConfigsForApi" + }, "tags": [ - "Dashboards" + "ComputeConfigs" ], - "summary": "List dashboard widgets", - "description": "Lists widgets for a dashboard.", + "operationId": "computeConfigs.list", + "summary": "List compute configs", + "description": "Lists compute configs in the workspace.", "security": [ { "BearerAuth": [] } ], "parameters": [ - { - "schema": { - "type": "string", - "minLength": 1, - "maxLength": 55 - }, - "required": true, - "name": "id", - "in": "path" - }, { "schema": { "type": "string", @@ -20964,15 +37095,41 @@ "description": "Items per page (1-100, default 50)", "name": "limit", "in": "query" + }, + { + "schema": { + "type": "string", + "enum": [ + "basic", + "full" + ], + "default": "basic" + }, + "required": false, + "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 dashboard widgets", + "description": "Compute config list", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/WidgetList" + "$ref": "#/components/schemas/ComputeConfigList" } } } @@ -20986,29 +37143,19 @@ } } } - }, - "403": { - "description": "Forbidden", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/ApiErrorResponse" - } - } - } } } } }, - "/v1/dashboards/{id}/widgets/{wgt_id}": { + "/v1/compute_configs/{id}": { "get": { "x-platform-visibility": "PUBLIC", - "operationId": "dashboards.getWidget", "tags": [ - "Dashboards" + "ComputeConfigs" ], - "summary": "Get dashboard widget", - "description": "Returns a single dashboard widget.", + "operationId": "computeConfigs.get", + "summary": "Get compute config", + "description": "Returns a compute config by ID.", "security": [ { "BearerAuth": [] @@ -21019,7 +37166,7 @@ "schema": { "type": "string", "minLength": 1, - "maxLength": 55 + "maxLength": 54 }, "required": true, "name": "id", @@ -21029,20 +37176,23 @@ "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": "wgt_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": "Dashboard widget details", + "description": "Compute config details", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/Widget" + "$ref": "#/components/schemas/ComputeConfig" } } } @@ -21057,6 +37207,16 @@ } } }, + "403": { + "description": "Forbidden", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } + } + } + }, "404": { "description": "Not found", "content": { @@ -21071,28 +37231,18 @@ }, "patch": { "x-platform-visibility": "PUBLIC", - "operationId": "dashboards.updateWidget", "tags": [ - "Dashboards" + "ComputeConfigs" ], - "summary": "Update dashboard widget", - "description": "Updates widget placement and display settings.", + "operationId": "computeConfigs.update", + "summary": "Update compute config", + "description": "Updates mutable fields of a compute config.", "security": [ { "BearerAuth": [] } ], "parameters": [ - { - "schema": { - "type": "string", - "minLength": 1, - "maxLength": 55 - }, - "required": true, - "name": "id", - "in": "path" - }, { "schema": { "type": "string", @@ -21100,7 +37250,7 @@ "maxLength": 54 }, "required": true, - "name": "wgt_id", + "name": "id", "in": "path" }, { @@ -21121,11 +37271,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" }, @@ -21149,48 +37299,29 @@ "schema": { "type": "object", "properties": { - "col_span": { - "anyOf": [ - { - "type": "number", - "enum": [ - 1 - ] - }, - { - "type": "number", - "enum": [ - 2 - ] + "name": { + "type": "string", + "minLength": 1, + "maxLength": 100 + }, + "provider_config": { + "type": "object", + "properties": { + "region": { + "type": "string", + "minLength": 1 }, - { - "type": "number", - "enum": [ - 3 - ] + "image": { + "type": "string", + "minLength": 1 }, - { - "type": "number", - "enum": [ - 4 - ] + "machine_type_filter": { + "type": "string" } - ] - }, - "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" + "credential_scope": { + "$ref": "#/components/schemas/CredentialScope" } }, "additionalProperties": false @@ -21200,11 +37331,11 @@ }, "responses": { "200": { - "description": "Dashboard widget updated", + "description": "Compute config updated", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/Widget" + "$ref": "#/components/schemas/ComputeConfig" } } } @@ -21248,27 +37379,17 @@ } } } - }, - "422": { - "description": "Unprocessable entity", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/ApiErrorResponse" - } - } - } } } }, "delete": { "x-platform-visibility": "PUBLIC", - "operationId": "dashboards.deleteWidget", "tags": [ - "Dashboards" + "ComputeConfigs" ], - "summary": "Delete dashboard widget", - "description": "Deletes a dashboard widget. Snippet references are preserved.", + "operationId": "computeConfigs.delete", + "summary": "Delete compute config", + "description": "Deletes a compute config.", "security": [ { "BearerAuth": [] @@ -21279,7 +37400,7 @@ "schema": { "type": "string", "minLength": 1, - "maxLength": 55 + "maxLength": 54 }, "required": true, "name": "id", @@ -21289,23 +37410,26 @@ "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": "wgt_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" }, { "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" }, { @@ -21323,8 +37447,15 @@ } ], "responses": { - "204": { - "description": "Dashboard widget deleted" + "200": { + "description": "Compute config deleted", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ComputeConfig" + } + } + } }, "401": { "description": "Unauthorized", @@ -21369,15 +37500,100 @@ } } }, - "/v1/machines": { + "/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": [ - "Machines" + "Products" ], - "operationId": "machines.create", - "summary": "Create machine", - "description": "Creates a machine and returns a long-running operation envelope.", + "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": [] @@ -21402,11 +37618,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" } @@ -21415,66 +37631,24 @@ "content": { "application/json": { "schema": { - "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 + "$ref": "#/components/schemas/CreateProductBody" } } } }, "responses": { - "202": { - "description": "Machine creation accepted", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/OperationEnvelope" - } - } - } - }, - "401": { - "description": "Unauthorized", + "201": { + "description": "Product created", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/ApiErrorResponse" + "$ref": "#/components/schemas/Product" } } } }, - "403": { - "description": "Forbidden", + "400": { + "description": "Bad request", "content": { "application/json": { "schema": { @@ -21483,8 +37657,8 @@ } } }, - "404": { - "description": "Not found", + "401": { + "description": "Unauthorized", "content": { "application/json": { "schema": { @@ -21493,8 +37667,8 @@ } } }, - "409": { - "description": "Conflict", + "403": { + "description": "Forbidden", "content": { "application/json": { "schema": { @@ -21503,8 +37677,8 @@ } } }, - "503": { - "description": "Service unavailable", + "422": { + "description": "Unprocessable entity", "content": { "application/json": { "schema": { @@ -21514,20 +37688,22 @@ } } } - }, + } + }, + "/v1/products:dashboardList": { "get": { - "x-platform-visibility": "PUBLIC", + "x-platform-visibility": "INTERNAL", "x-platform-live": { - "visibility": "PUBLIC", + "visibility": "INTERNAL", "transport": "convex", - "convexQuery": "compute.ui.listMachinesForApi" + "convexQuery": "product.ui.listDashboardProductsForApi" }, + "operationId": "products.listDashboard", "tags": [ - "Machines" + "Products" ], - "operationId": "machines.list", - "summary": "List machines", - "description": "Lists all machines in the workspace.", + "summary": "List dashboard products in workspace", + "description": "Returns product rows shaped for the dashboard product catalog, including target counts.", "security": [ { "BearerAuth": [] @@ -21558,47 +37734,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", - "enum": [ - "basic", - "full" - ], - "default": "basic" - }, - "required": false, - "name": "view", - "in": "query" - }, { "schema": { "type": "string", @@ -21615,11 +37750,11 @@ ], "responses": { "200": { - "description": "Machine list", + "description": "Dashboard product list", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/MachineList" + "$ref": "#/components/schemas/DashboardProductList" } } } @@ -21633,56 +37768,46 @@ } } } + }, + "403": { + "description": "Forbidden", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } + } + } } } } }, - "/v1/machines/{id}": { + "/v1/products:marketplaceList": { "get": { - "x-platform-visibility": "PUBLIC", + "x-platform-visibility": "INTERNAL", + "x-platform-live": { + "visibility": "INTERNAL", + "transport": "convex", + "convexQuery": "product.ui.getMarketplaceProductsForUi" + }, + "operationId": "products.listMarketplace", "tags": [ - "Machines" + "Products" ], - "operationId": "machines.get", - "summary": "Get machine", - "description": "Returns a machine by ID.", + "summary": "List marketplace products", + "description": "Returns product rows shaped for the marketplace catalog.", "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" - } - ], "responses": { "200": { - "description": "Machine details", + "description": "Marketplace product list", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/Machine" + "$ref": "#/components/schemas/MarketplaceProductList" } } } @@ -21696,37 +37821,24 @@ } } } - }, - "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", + } + }, + "/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.update", - "summary": "Update machine", - "description": "Updates machine metadata.", + "summary": "Get product dashboard summary", + "description": "Returns the product-level customer, install, offer, and redemption summary used by the product dashboard.", "security": [ { "BearerAuth": [] @@ -21737,9 +37849,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" }, @@ -21754,65 +37869,16 @@ "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": { - "type": "object", - "properties": { - "name": { - "anyOf": [ - { - "type": "string", - "maxLength": 120 - }, - { - "nullable": true - } - ] - } - }, - "additionalProperties": false - } - } + "in": "header" } - }, + ], "responses": { "200": { - "description": "Machine updated", + "description": "Product dashboard summary", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/Machine" + "$ref": "#/components/schemas/ProductDashboard" } } } @@ -21846,27 +37912,24 @@ } } } - }, - "409": { - "description": "Conflict", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/ApiErrorResponse" - } - } - } } } - }, - "delete": { - "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.delete", - "summary": "Delete machine", - "description": "Deletes a machine and returns a long-running operation envelope.", + "summary": "Get marketplace product", + "description": "Returns product detail shaped for the marketplace product page.", "security": [ { "BearerAuth": [] @@ -21877,59 +37940,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" } ], "responses": { - "202": { - "description": "Machine deletion accepted", + "200": { + "description": "Marketplace product detail", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/OperationEnvelope" + "$ref": "#/components/schemas/MarketplaceProductDetail" } } } @@ -21944,16 +37971,6 @@ } } }, - "403": { - "description": "Forbidden", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/ApiErrorResponse" - } - } - } - }, "404": { "description": "Not found", "content": { @@ -21963,29 +37980,24 @@ } } } - }, - "409": { - "description": "Conflict", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/ApiErrorResponse" - } - } - } } } } }, - "/v1/machines/{id}:suspend": { - "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.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 details", + "description": "Returns product metadata including the backing Package and marketplace settings.", "security": [ { "BearerAuth": [] @@ -21996,9 +38008,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 +38029,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 details", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/OperationEnvelope" + "$ref": "#/components/schemas/Product" } } } @@ -22091,29 +38071,17 @@ } } } - }, - "409": { - "description": "Conflict", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/ApiErrorResponse" - } - } - } } } - } - }, - "/v1/machines/{id}:resume": { - "post": { + }, + "patch": { "x-platform-visibility": "PUBLIC", + "operationId": "products.update", "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": "Update product", + "description": "Updates Product metadata, marketplace listing state, and the package version pin for future offers and installs.", "security": [ { "BearerAuth": [] @@ -22124,9 +38092,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" }, @@ -22148,11 +38119,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" }, @@ -22174,18 +38145,18 @@ "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/ResumeMachineBody" + "$ref": "#/components/schemas/UpdateProductBody" } } } }, "responses": { - "202": { - "description": "Machine resume accepted", + "200": { + "description": "Product updated", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/OperationEnvelope" + "$ref": "#/components/schemas/Product" } } } @@ -22229,19 +38200,29 @@ } } } + }, + "422": { + "description": "Unprocessable entity", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } + } + } } } } }, - "/v1/machines/{id}/drift_reports": { + "/v1/products/{id}:archive": { "post": { "x-platform-visibility": "PUBLIC", + "operationId": "products.archive", "tags": [ - "Machines" + "Products" ], - "operationId": "machines.createDriftReport", - "summary": "Create machine drift report", - "description": "Runs drift detection and stores a dedicated report row.", + "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": [] @@ -22252,9 +38233,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" }, @@ -22276,45 +38260,44 @@ "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": { - "trigger": { - "type": "string" - } - }, - "additionalProperties": false + "$ref": "#/components/schemas/ArchiveProductBody" } } } }, "responses": { - "201": { - "description": "Machine drift report created", - "headers": { - "Location": { - "schema": { - "type": "string" - }, - "description": "Location of the drift report." - } - }, + "200": { + "description": "Product archived", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/DriftReport" + "$ref": "#/components/schemas/Product" } } } @@ -22348,108 +38331,9 @@ } } } - } - } - }, - "get": { - "x-platform-visibility": "PUBLIC", - "tags": [ - "Machines" - ], - "operationId": "machines.listDriftReports", - "summary": "List machine drift reports", - "description": "Lists historical drift reports for a machine.", - "security": [ - { - "BearerAuth": [] - } - ], - "parameters": [ - { - "schema": { - "type": "string", - "minLength": 1, - "maxLength": 54 - }, - "required": true, - "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", - "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": "Drift report list", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/DriftReportList" - } - } - } - }, - "401": { - "description": "Unauthorized", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/ApiErrorResponse" - } - } - } }, - "403": { - "description": "Forbidden", + "409": { + "description": "Conflict", "content": { "application/json": { "schema": { @@ -22458,8 +38342,8 @@ } } }, - "404": { - "description": "Not found", + "422": { + "description": "Unprocessable entity", "content": { "application/json": { "schema": { @@ -22471,15 +38355,15 @@ } } }, - "/v1/machines/{id}/drift_reports/{report_id}": { - "get": { + "/v1/products/{id}:unarchive": { + "post": { "x-platform-visibility": "PUBLIC", + "operationId": "products.unarchive", "tags": [ - "Machines" + "Products" ], - "operationId": "machines.getDriftReport", - "summary": "Get machine drift report", - "description": "Returns a single drift report by ID.", + "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": [] @@ -22490,22 +38374,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,134 +38395,52 @@ "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": "Machine drift report", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/DriftReport" - } - } - } - }, - "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/machines/{id}/suspension_events": { - "get": { - "x-platform-visibility": "PUBLIC", - "tags": [ - "Machines" - ], - "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.", - "security": [ - { - "BearerAuth": [] - } - ], - "parameters": [ { "schema": { "type": "string", "minLength": 1, - "maxLength": 54 - }, - "required": true, - "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", - "enum": [ - "manual", - "downgrade" - ] + "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 +38474,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 +38515,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 +38562,11 @@ ], "responses": { "200": { - "description": "Suspension event", + "description": "Product rollouts", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/SuspensionEvent" + "$ref": "#/components/schemas/ProductRolloutList" } } } @@ -22762,29 +38590,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 +38625,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 +38638,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 +38683,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 +38724,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 +38747,11 @@ ], "responses": { "200": { - "description": "Compute config list", + "description": "Product rollout", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/ComputeConfigList" + "$ref": "#/components/schemas/ProductRollout" } } } @@ -22993,34 +38765,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 +38861,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 +38901,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 +38921,7 @@ "schema": { "type": "string", "minLength": 1, - "maxLength": 54 + "maxLength": 55 }, "required": true, "name": "id", @@ -23120,72 +38944,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 +39017,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 +39049,7 @@ "schema": { "type": "string", "minLength": 1, - "maxLength": 54 + "maxLength": 55 }, "required": true, "name": "id", @@ -23273,36 +39072,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 +39145,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 +39157,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 +39191,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 +39204,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", + }, + "responses": { + "201": { + "description": "Offer channel created", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/ApiErrorResponse" + "$ref": "#/components/schemas/OfferChannel" } } } @@ -23526,34 +39239,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 +39263,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 +39286,11 @@ ], "responses": { "200": { - "description": "Dashboard product list", + "description": "Offer channels", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/DashboardProductList" + "$ref": "#/components/schemas/OfferChannelList" } } } @@ -23632,32 +39318,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 +39363,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 +39405,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 +39423,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 +39468,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 +39504,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 +39517,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 +39552,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 +39608,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 +39626,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 +39667,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 +39685,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 +39709,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 +39748,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 +39824,8 @@ } } }, - "422": { - "description": "Unprocessable entity", + "403": { + "description": "Forbidden", "content": { "application/json": { "schema": { @@ -24114,15 +39837,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 +39855,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 +39879,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 +39918,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 +40011,8 @@ } } }, - "422": { - "description": "Unprocessable entity", + "403": { + "description": "Forbidden", "content": { "application/json": { "schema": { @@ -24255,16 +40022,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. 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": [] @@ -24283,34 +40049,34 @@ "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" } ], "requestBody": { "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 +40100,29 @@ } } } + }, + "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 +40133,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 +40173,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 +40206,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 +40266,8 @@ } } }, - "404": { - "description": "Not found", + "422": { + "description": "Unprocessable entity", "content": { "application/json": { "schema": { @@ -24482,14 +40279,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 +40298,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 +40319,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 +40361,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 +40404,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 +40467,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 +40549,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 +40568,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 +40638,16 @@ } } }, + "403": { + "description": "Forbidden", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } + } + } + }, "404": { "description": "Not found", "content": { @@ -24752,18 +40657,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 +40700,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 +40726,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 +40779,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 +40832,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 +40885,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 +40927,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 +41018,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 +41062,6 @@ "name": "limit", "in": "query" }, - { - "schema": { - "type": "string", - "minLength": 1, - "maxLength": 55 - }, - "required": false, - "name": "product_id", - "in": "query" - }, { "schema": { "type": "string", @@ -25072,11 +41078,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 +41108,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 +41134,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 +41175,8 @@ } } }, - "422": { - "description": "Unprocessable entity", + "404": { + "description": "Not found", "content": { "application/json": { "schema": { @@ -25194,15 +41188,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 +41207,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 +41270,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 +41313,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 +41367,8 @@ } } }, - "401": { - "description": "Unauthorized", + "403": { + "description": "Forbidden", "content": { "application/json": { "schema": { @@ -25336,8 +41377,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 +41410,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 +41429,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 +41442,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 +41512,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 +41545,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 +41558,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 +41628,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 +41729,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 +41762,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 +41786,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 +41845,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 +41876,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 +41950,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 +42025,8 @@ } } }, - "422": { - "description": "Unprocessable entity", + "404": { + "description": "Not found", "content": { "application/json": { "schema": { @@ -25893,15 +42038,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 +42057,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 +42129,16 @@ } } }, + "409": { + "description": "Conflict", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } + } + } + }, "422": { "description": "Unprocessable entity", "content": { @@ -25989,15 +42152,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 +42200,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 +42268,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 +42324,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 +42370,8 @@ } } }, - "409": { - "description": "Conflict", + "401": { + "description": "Unauthorized", "content": { "application/json": { "schema": { @@ -26361,8 +42380,8 @@ } } }, - "422": { - "description": "Unprocessable entity", + "403": { + "description": "Forbidden", "content": { "application/json": { "schema": { @@ -26374,15 +42393,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 +42417,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 +42430,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 +42480,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 +42503,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 +42565,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 +42588,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 +42601,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 +42678,6 @@ } } }, - "409": { - "description": "Conflict", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/ApiErrorResponse" - } - } - } - }, "422": { "description": "Unprocessable entity", "content": { @@ -26719,60 +42691,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 install rows shaped for the dashboard deployments table. 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 +42789,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 +42817,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 +42827,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 +42877,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 +42904,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 +43013,8 @@ } } }, - "403": { - "description": "Forbidden", + "401": { + "description": "Unauthorized", "content": { "application/json": { "schema": { @@ -27031,15 +43036,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 +43060,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 +43104,6 @@ } } }, - "403": { - "description": "Forbidden", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/ApiErrorResponse" - } - } - } - }, "404": { "description": "Not found", "content": { @@ -27115,63 +43117,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 +43226,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 +43239,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 +43287,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 +43339,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 +43487,8 @@ } } }, - "401": { - "description": "Unauthorized", + "403": { + "description": "Forbidden", "content": { "application/json": { "schema": { @@ -27457,8 +43497,8 @@ } } }, - "403": { - "description": "Forbidden", + "404": { + "description": "Not found", "content": { "application/json": { "schema": { @@ -27468,22 +43508,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 +43527,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 +43548,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 +43607,8 @@ } } }, - "404": { - "description": "Not found", + "409": { + "description": "Conflict", "content": { "application/json": { "schema": { @@ -27561,15 +43620,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 +43644,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 +43697,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 +43716,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 +43739,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 +43753,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 +43813,8 @@ } } }, - "422": { - "description": "Unprocessable entity", + "409": { + "description": "Conflict", "content": { "application/json": { "schema": { @@ -27768,20 +43826,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 +43844,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 +43863,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 +43941,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 +43973,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 +44060,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 +44130,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 +44143,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 +44178,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 +44228,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 +44268,11 @@ ], "responses": { "200": { - "description": "Install details", + "description": "Install renders", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/Install" + "$ref": "#/components/schemas/InstallRenderList" } } } @@ -28217,15 +44308,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 +44329,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 +44403,8 @@ } } }, - "403": { - "description": "Forbidden", + "404": { + "description": "Not found", "content": { "application/json": { "schema": { @@ -28329,20 +44426,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 +44445,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 +44519,8 @@ } } }, - "403": { - "description": "Forbidden", + "404": { + "description": "Not found", "content": { "application/json": { "schema": { @@ -28393,8 +44529,8 @@ } } }, - "404": { - "description": "Not found", + "409": { + "description": "Conflict", "content": { "application/json": { "schema": { @@ -28406,15 +44542,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 +44561,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 +44595,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 +44635,6 @@ } } }, - "403": { - "description": "Forbidden", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/ApiErrorResponse" - } - } - } - }, "404": { "description": "Not found", "content": { @@ -28522,15 +44656,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 +44677,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 +44737,8 @@ } } }, - "403": { - "description": "Forbidden", + "404": { + "description": "Not found", "content": { "application/json": { "schema": { @@ -28619,8 +44747,8 @@ } } }, - "404": { - "description": "Not found", + "409": { + "description": "Conflict", "content": { "application/json": { "schema": { @@ -29186,11 +45314,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 +45699,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 +46365,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 +46450,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 +46866,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 +47080,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 +47219,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 +47360,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 +47606,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 +47850,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 +49558,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 +50124,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 +50317,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 +50681,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 +51307,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 +51849,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 +51882,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 +51897,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 +51959,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 +52012,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 +52062,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 +52090,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 +52145,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 +52187,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 +52224,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 +52326,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 +52356,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 +52375,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 +52433,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 +52490,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 +52508,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 +52564,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 +52612,11 @@ ], "responses": { "200": { - "description": "Cluster details", + "description": "Cluster capabilities", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/Cluster" + "$ref": "#/components/schemas/ClusterCapabilities" } } } @@ -35772,15 +52652,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 +52697,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 +52758,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 +52803,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 +52827,7 @@ ], "responses": { "202": { - "description": "Delete initiated", + "description": "Suspend initiated", "content": { "application/json": { "schema": { @@ -36042,21 +52879,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 +52922,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 +52974,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 +53017,9 @@ "schema": { "type": "string", "minLength": 1, - "maxLength": 54, - "description": "Cluster ID." + "maxLength": 54 }, "required": true, - "description": "Cluster ID.", "name": "id", "in": "path" }, @@ -36197,11 +53039,11 @@ ], "responses": { "200": { - "description": "Cluster capabilities", + "description": "Cluster kubeconfig", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/ClusterCapabilities" + "$ref": "#/components/schemas/Kubeconfig" } } } @@ -36235,19 +53077,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 +53119,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 +53173,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 +53220,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 +53241,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 +53305,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 +53348,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 +53423,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 +53455,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 +53495,11 @@ ], "responses": { "200": { - "description": "Cluster kubeconfig", + "description": "Worker bootstraps page", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/Kubeconfig" + "$ref": "#/components/schemas/WorkerBootstrapList" } } } @@ -36666,15 +53537,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 +53565,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 +53588,14 @@ ], "responses": { "200": { - "description": "Kube API response passthrough" + "description": "Worker bootstrap", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/WorkerBootstrap" + } + } + } }, "401": { "description": "Unauthorized", @@ -36752,15 +53630,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 +53655,16 @@ "name": "id", "in": "path" }, + { + "schema": { + "type": "string", + "minLength": 1, + "maxLength": 54 + }, + "required": true, + "name": "wbs_id", + "in": "path" + }, { "schema": { "type": "string", @@ -36795,11 +53683,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 +53705,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 +53759,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 +55740,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 +55787,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 +55809,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 +55870,8 @@ } } }, - "404": { - "description": "Not found", + "401": { + "description": "Unauthorized", "content": { "application/json": { "schema": { @@ -37112,15 +55883,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 +55902,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 +55954,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 +55973,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 +56009,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 +56080,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 +56158,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 +56182,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 +56242,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 +56260,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 +56366,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 +56413,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 +56474,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 +56494,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 +56551,6 @@ } } }, - "404": { - "description": "Not found", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/ApiErrorResponse" - } - } - } - }, "409": { "description": "Conflict", "content": { @@ -37751,15 +56562,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 +56582,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 +56638,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 +56670,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 +56710,8 @@ } } }, - "403": { - "description": "Forbidden", + "404": { + "description": "Not found", "content": { "application/json": { "schema": { @@ -37919,83 +56721,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 +56766,8 @@ } } }, - "401": { - "description": "Unauthorized", + "403": { + "description": "Forbidden", "content": { "application/json": { "schema": { @@ -38014,8 +56776,8 @@ } } }, - "403": { - "description": "Forbidden", + "404": { + "description": "Not found", "content": { "application/json": { "schema": { @@ -38082,11 +56844,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 +56982,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 +57093,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 +57345,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 +57363,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 +57398,16 @@ } } } + }, + "403": { + "description": "Forbidden", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiErrorResponse" + } + } + } } } } @@ -39064,11 +57873,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 +58458,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 +58742,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 +58968,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 +59087,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 +59215,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 +61086,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 +61389,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 +62746,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 +63110,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 +63208,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 +63305,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 +63500,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 +63691,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 +63808,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 +64145,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 +64223,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..733aafb 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", @@ -2618,7 +2570,99 @@ export const commandRegistry = [ "method": "GET", "path": "/v1/installs/{id}/pods", "tag": "Installs", - "summary": "List install pods", + "summary": "List install pods", + "visibility": "PUBLIC", + "requires_auth": true, + "parameters": [ + { + "name": "id", + "in": "path", + "required": true + }, + { + "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": [ @@ -2631,18 +2675,28 @@ export const commandRegistry = [ "name": "akua-context", "in": "header", "required": false + }, + { + "name": "if-match", + "in": "header", + "required": true + }, + { + "name": "idempotency-key", + "in": "header", + "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", @@ -3674,6 +3728,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 +3770,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 +3813,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 +3904,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 +3949,16 @@ export const commandRegistry = [ "name": "id", "in": "path", "required": true + }, + { + "name": "cursor", + "in": "query", + "required": false + }, + { + "name": "limit", + "in": "query", + "required": false } ] }, @@ -3829,6 +3978,16 @@ export const commandRegistry = [ "name": "id", "in": "path", "required": true + }, + { + "name": "cursor", + "in": "query", + "required": false + }, + { + "name": "limit", + "in": "query", + "required": false } ] }, @@ -3866,6 +4025,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 +4791,11 @@ export const commandRegistry = [ "name": "cluster_id", "in": "query", "required": false + }, + { + "name": "akua-context", + "in": "header", + "required": false } ] }, @@ -5457,6 +5645,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 +5773,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 +6182,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 +6404,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",